feat(cli): load a native application and run it from the CLI by chenxin-yan · Pull Request #213 · chenxin-yan/mitome

chenxin-yan · 2026-10-02T09:52:40Z

Closes #184. Stacked on #211 (→ #207 → #205).

Adds loadable native applications and the CLI that runs them.

What changed

@mitome/core: defineMitome(options). This typed producer composes:
- an ordinary program,
- native infrastructure Layers,
- Providers, with a Default Model and ordered fallbacks,
- an explicit CLI parseInput/renderResult mapping,
- optional process-local serving Hosts.
Requirements that are left open are compile errors (see test/application.types.ts). The original program, Layer and Provider types are preserved.
acquire() works in this order:
1. Validates the selection before acquiring anything.
2. Builds infrastructure once.
3. Provisions the Model lazily. An explicit --model never falls back. Configured fallbacks are tried in order, and each failed attempt is released before the next.
4. Unwinds a partial startup.
5. Becomes ready only once every Host has started.
Application:
- Serves fresh application-owned Sessions. Each Turn binds its own Turn Scope, never the acquisition Scope.
- Retains idle Sessions until close or shutdown.
- Reports a serving Host failure without restarting it or touching healthy Hosts.
- Shutdown closes admission, cancels and drains all owned work, and only then releases the Model and infrastructure. It is idempotent, and the library never exits the process.
CLI commands: mitome run --app <file> [--provider] [--model] [--grace] [input], mitome providers and mitome auth status|login|logout. All load the same --app default export; there is no implicit discovery.
CLI output and exit behaviour:
- stdout carries only the rendered result. Logs and defects go to stderr.
- --grace (default 5s) bounds cleanup after a signal, after normal completion, and after a failed startup. Expiry exits 1.
Docs: new applications.mdx and cli.mdx. CONTEXT.md no longer lists the deleted vocabulary. Codex credential errors now name the real auth login command.

Review

The work went through one design review, an initial implementation, and three rounds of independent verification plus spec, standards and simplicity review. That found and fixed:

Session close could free shared dependencies early. Session.close detached its Scope before draining, which could release them under a running cleanup.
stdout was not clean. Logs and runtime defects were printed to stdout.
--grace didn't always apply. It covered only signals; normal completion and failed-start cleanup are now bounded too.
A failing shutdown notification skipped resource release.

Each fix has a regression test that fails without it.

Known limitation (documented in cli.mdx): when a native Layer fails while it is being built, Effect rolls back that Layer's own resources before the application can start shutting down. If that rollback hangs, --grace only bounds it after SIGINT/SIGTERM.

Verification

bun run build|check|test -- --force all exit 0 (core 104, cli 19, providers 381, create-mitome 11 tests).
Independent offline runs of the compiled binary against a scripted-LanguageModel fixture, with no credentials and no network:
- one-shot runs from an argument and from stdin;
- unknown, unqualified or mismatched selection errors, with nothing acquired;
- offline providers and auth status;
- failed-start unwinding, including a held release that is bounded by grace;
- a failing program;
- SIGINT drain, exiting 130.

Not exercised: the interactive OAuth auth login flow, and real Providers over the network.

pullfrog · 2026-10-02T09:52:45Z

Run failed. View the logs →

^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using gpt-6-astra ｜ 𝕏}

github-actions · 2026-10-02T09:53:00Z

🦋 Changeset detected

Latest commit: 4e752b1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@mitome/core	Minor
@mitome/cli	Minor
@mitome/providers	Minor
create-mitome	Minor
@mitome/cli-darwin-arm64	Minor
@mitome/cli-darwin-x64	Minor
@mitome/cli-linux-arm64	Minor
@mitome/cli-linux-arm64-musl	Minor
@mitome/cli-linux-x64	Minor
@mitome/cli-linux-x64-musl	Minor
@mitome/cli-win32-arm64	Minor
@mitome/cli-win32-x64	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cubic-dev-ai

All reported issues were addressed across 32 files

_{Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic}

pullfrog · 2026-10-02T10:51:31Z

Run failed. View the logs →

^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using gpt-6-astra ｜ 𝕏}

pullfrog · 2026-10-06T23:18:08Z

Run failed. View the logs →

^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using gpt-6-astra ｜ 𝕏}

Address a #214 review finding: the Approval channel test bounds its poll and asserts one request appeared, so a Turn that never asks fails at the assertion instead of the 15s runner timeout. (The review's other point, building before the binary tests, is fixed in #213's test script.)

pullfrog

✅ No new issues found.

Reviewed changes
Reviewed the supplied incremental delta from 6bcb8d2 to 0a13bbb, limited to the CLI test script.

Added a pre-test binary build. Changed the CLI test command to compile dist/local/mitome before Vitest, preventing package-local tests from exercising an absent or stale executable.
Verified both execution paths. All 19 CLI tests passed through Turbo and through direct bun run test after workspace prerequisites were built.

^{｜ View workflow run ｜ Using gpt-6-astra ｜ 𝕏}

Address a #214 review finding: the Approval channel test bounds its poll and asserts one request appeared, so a Turn that never asks fails at the assertion instead of the 15s runner timeout. (The review's other point, building before the binary tests, is fixed in #213's test script.)

Add defineMitome to @mitome/core: a typed producer composing an ordinary program with shared infrastructure, Providers, Default and fallback Models, an explicit CLI mapping and serving Hosts. Unclosed requirements are compile errors. acquire builds infrastructure once, provisions the selected Model lazily with ordered configured fallback, serves explicit fresh application-owned Sessions, binds each Turn's own Scope, unwinds partial startup, isolates serving-Host failures and shuts down by closing admission and draining owned work before releasing infrastructure. The mitome CLI gains run, providers and auth status|login|logout, each loading the default export of an explicit --app file. run is one-shot with explicit input/output mapping and a --grace bound on signal shutdown. Codex credential remedies name the shipped auth command; docs, READMEs and the glossary describe the native application and CLI. Refs #184

…o results An explicit Session close detached its Scope from the application before its Turn cleanup finished, so a concurrent shutdown could release shared infrastructure underneath that cleanup. The application now holds a finalizer awaiting one shared close until it completes. The CLI grace timer now also starts when the command's own work ends, so cleanup after ordinary completion or failure is bounded, not only after a signal. Application Effect logs and unreported failures go to stderr, keeping stdout to the rendered result. Refs #184

acquire unwinds a failed startup before it returns, so the CLI's grace, started only once the command's work ended, never covered that unwind and a held infrastructure release hung the process. AcquireOptions gains onShutdown, run once when shutdown begins and before anything is cancelled or released; the CLI starts its deadline there as well. The library still waits for all cleanup; only the CLI exits. Refs #184

…n fails Effect.ensuring keeps closing the application's resources when onShutdown defects or is interrupted, and the docs state that a native Layer's own failed-build rollback runs before shutdown begins.

Exit-aware infrastructure releases now see the startup failure instead of success. Also address review notes on the docs example, the Application glossary entry and test environment restoration.

binary.test.ts spawns dist/local/mitome, which only the build script produces. Turbo builds first, but a direct `bun run test` in packages/cli on a fresh checkout failed with ENOENT, and after source edits it tested a stale binary. The compile takes under a second.

Address a #214 review finding: the Approval channel test bounds its poll and asserts one request appeared, so a Turn that never asks fails at the assertion instead of the 15s runner timeout. (The review's other point, building before the binary tests, is fixed in #213's test script.)

chenxin-yan added this pull request to stack #212 October 2, 2026 09:52

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

chenxin-yan mentioned this pull request Oct 2, 2026

feat(cli): run and approve Turns in a standalone TUI #214

Open

chenxin-yan force-pushed the feat/effect-native-cli-184 branch from dfa8379 to 6bcb8d2 Compare October 6, 2026 23:17

chenxin-yan force-pushed the feat/effect-native-cli-184 branch from 6bcb8d2 to 0a13bbb Compare November 1, 2026 00:59

pullfrog Bot reviewed Nov 1, 2026

View reviewed changes

chenxin-yan force-pushed the feat/effect-native-cli-184 branch from 0a13bbb to 7f20647 Compare November 1, 2026 01:12

chenxin-yan added 6 commits October 31, 2026 18:16

fix(core): release owned resources even when the shutdown notificatio…

fa58f98

…n fails Effect.ensuring keeps closing the application's resources when onShutdown defects or is interrupted, and the docs state that a native Layer's own failed-build rollback runs before shutdown begins.

fix(core): close infrastructure with the failure of a failed startup

9a16605

Exit-aware infrastructure releases now see the startup failure instead of success. Also address review notes on the docs example, the Application glossary entry and test environment restoration.

chenxin-yan force-pushed the feat/effect-native-cli-184 branch from 7f20647 to 4e752b1 Compare November 1, 2026 01:19

Navigation Menu

Repository navigation

feat(cli): load a native application and run it from the CLI - #213

feat(cli): load a native application and run it from the CLI#213
chenxin-yan wants to merge 6 commits into
feat/effect-native-corefrom
feat/effect-native-cli-184

chenxin-yan commented Oct 2, 2026 •

edited

Loading

Uh oh!

pullfrog Bot commented Oct 2, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 2, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pullfrog Bot commented Oct 2, 2026

Uh oh!

pullfrog Bot commented Oct 6, 2026

Uh oh!

pullfrog Bot left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

chenxin-yan commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Review

Verification

Uh oh!

pullfrog Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pullfrog Bot commented Oct 2, 2026

Uh oh!

pullfrog Bot commented Oct 6, 2026

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

chenxin-yan commented Oct 2, 2026 •

edited

Loading

pullfrog Bot commented Oct 2, 2026 •

edited

Loading

github-actions Bot commented Oct 2, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading