Read docs/architecture.md and the current command registration before proposing
a change. The standalone entry point lives in packages/tui.
Entry points
| Path | Responsibility |
|---|---|
packages/tui/src/index.ts |
Process bootstrap and runtime environment |
packages/tui/src/cli/main.ts |
Command execution and process lifecycle |
packages/tui/src/cli/program.ts |
Commander command registration |
packages/tui/src/cli/contract.ts |
Interactive and exec option contracts |
packages/tui/src/tui/ |
Interactive terminal UI |
packages/tui/src/headless/ |
Exec invocation, output, cancellation and settlement |
packages/tui/src/acp/ |
ACP protocol adapter |
packages/tui/src/runtime/adapter.ts |
Adapter to the in-process CliService |
packages/local-runtime-v2/src/local/ |
Local product service entry points |
packages/protocol/src/local.ts |
Shared CLI data structures |
The execution path is:
TUI / exec / ACP
-> CliService
-> local applications
-> session / turn / agent services
-> model providers and tools
Preserve that in-process boundary. Shared behavior belongs in the relevant application or service; presentation and transport behavior belong in their adapters. Trace callers before assuming a fix to one adapter covers the others.
Implementing changes
- For commands and flags, inspect
cli/program.ts,cli/contract.ts, and the affected command handler together. Check parsing, help, dispatch and errors. - For interactive behavior, follow the controller and rendering path under
tui/. Check session selection, queued input and interruption where affected. - For exec, follow invocation through output and settlement. Verify stdout, stderr, exit code and cancellation; help output alone is insufficient.
- For ACP, check protocol updates and the underlying runtime operation together.
- For shared runtime changes, identify all affected TUI, exec and ACP consumers.
Verification
Use testing-workflow to select declared tests. Build the standalone artifact before inspecting its actual help:
pnpm build
node dist/cli.js --help
node dist/cli.js exec --help
node dist/cli.js acp --help
Read current help before documenting flags. Use temporary data directories and synthetic inputs for behavior checks, following the existing smoke/BYOK tests. Report offline protocol tests separately from live-provider acceptance.