feat(runtime): expose the terminal capability to routes and scripts as request.terminal (#511)

[ScriptedAlchemy]

Fixes #511.

What

Routes and scripts get a read-only terminal capability from the framework instead of each plugin probing process.stdout.isTTY / columns / FORCE_COLOR itself.

(await agent()).terminal is a new Observed<AgentTerminal> axis beside lineage and workspace:

interface AgentTerminal {
  hostSurface: 'cli' | 'mcp' | 'hook' | 'script' | 'workbench';
  stdout: AgentTerminalStream;
  stderr: AgentTerminalStream;
  sharesTarget: boolean;          // fd 1 and fd 2 name one open file (2>&1, one shared terminal)
}
interface AgentTerminalStream {
  kind: 'tty' | 'pipe' | 'none';  // interactive terminal | any other open descriptor | no stream for the route
  color: 'none' | 'basic' | '256' | 'truecolor';
  columns?: number;               // terminal size, or COLUMNS override
  rows?: number;                  // terminal size, or LINES override
}

Per stream rather than flat because the filing consumer (cargo-hauler src/client/exec.ts) decides stdout and stderr color independently and asks whether the two share a target (2>&1) before merging a child's channels.

Per-surface values (honest, never guessed)

Surface	hostSurface	stdout / stderr	source
Routed CLI executable (npm bin and <target>/bin/<name>.mjs) — plain, rendered, or projected MCP command	cli	probed from the executable's own process; the rendered worker thread receives the executable's probe, never its own pipes	native
Rendered script (src/scripts/<name>.tsx)	script	probed	native
Plain main script / bin	cli (bin) / script (artifact)	probed; delivered as main(argv, { terminal }) (ExecutableMainContext)	—
Generated MCP server	mcp	none / none, color: 'none', sharesTarget: false	derived
Event route (shared runtime or standalone hook)	hook	none / none	derived
Workbench lifecycle replay	workbench	none / none	derived
Custom runAgentRequest host that mounts none	—	unavailable (not-provided)	—

Color precedence (matches the informal standards and the consumer's own colorEnabled): FORCE_COLOR decides outright (0/false off; ''/1/true basic; 2 256; 3 truecolor), CLICOLOR_FORCE forces on for a pipe at the COLORTERM/TERM depth, NO_COLOR (non-empty) and CLICOLOR=0 force off, TERM=dumb none, else tty-at-advertised-depth / pipe-none. COLUMNS/LINES override size. The routed CLI selects its tty-vs-Markdown mode from the same value, so plugin output and framework output can never disagree.

How

• packages/rsc-runtime/src/agent-request.ts: AgentTerminal* types, terminal on the handle/init, AGENT_REQUEST_STORE_VERSION 3 → 4.
• packages/agent-bundle/src/terminal-capability.ts (new, plain Node, no deps; rslib entry + agent-bundle/terminal-capability alias): detectProcessTerminal, terminalColor, sharesOutputTarget, noTerminal. No Effect runtime in artifacts; the first-party CLI is untouched (no eager Terminal loads — compatible with perf(cli): load the Effect terminal runtime lazily to restore cold-start time #530).
• cli-entry.ts: resolveTerminal probes once per invocation (explicit terminal option wins; legacy isTty still honoured as a stdout override), drives the output mode, and hands terminal to execute/render/createSession.
• entry-shell.ts: CLI bin mounts available(context.terminal, 'native'); rendered-route worker mounts message.terminal (forwarded, never probed); MCP Flight worker forwards message.terminal ?? unavailable; main envelope calls main(argv, { terminal: detectProcessTerminal(<cli|script>) }).
• mcp-server-runtime.ts host scopes mount noTerminal('mcp') / noTerminal('hook') and forward context.terminal to the worker; standalone hook shell mounts the hook literal; Workbench replay mounts workbench.
• Harness: invokeCli/runScript tty knob → deterministic synthetic terminal (80×24 basic tty, or two color-free pipes); renderRoute mounts the route kind's artifact value; in-memory MCP forwards the server's none; context.terminal injectable; plain-script child envelope mirrors the generated one.
• Public types: AgentTerminal* and ExecutableMainContext from agent-bundle / agent-bundle/routes.

Tests

• unit: terminal-capability.test.ts (color precedence, tty/pipe/closed-fd kinds, COLUMNS/LINES, sharesTarget), entry-shell.test.ts (envelope, bin/worker/Flight-worker templates, digest pin), cli-routes.test.ts (mode ↔ terminal agreement, --json, legacy isTty), rsc-runtime/tests/agent-request.test.ts.
• route-unit: renderRoute MCP → none, event route → hook/none/none, injection.
• projection: invokeCli plain (default pipe / tty), projected MCP command harness context --yes --json (→ cli, --json does not change the capability), injection; runScript rendered (script/pipe/pipe, script/tty/tty) and plain checksum --terminal (real child process probe); in-memory MCP → none.
• packed (packed-stdio-projection.test.ts, through openPackedMcpServer + spawned bin/route-harness.mjs and scripts/checksum.mjs): pipe detection, FORCE_COLOR=3 + COLUMNS=120, CLICOLOR_FORCE vs NO_COLOR, LINES; packed MCP context → none; shared-runtime event route → hook/none/none.

Ran locally: pnpm typecheck, pnpm lint, pnpm test:unit (3255 passed), pnpm test:route-unit, pnpm test:projection, node scripts/run-packed-tests.mjs packages/agent-bundle/tests/packed-stdio-projection.test.ts, pnpm docs:site:build.

Docs

docs/entry-conventions.md (new "Terminal capability (request.terminal)" section + envelope), docs/effect-conventions.md (Terminal/Stdio cross-reference: the route-facing capability is plain Node, not Terminal), website en+zh: guide/authoring/mcp.mdx (request-context section + per-surface table), package-entries.mdx (envelope), scripts-assets.mdx. One patch changeset for agent-bundle and @agent-bundle/runtime.

Coordination

• feat(runtime): expose the resolved plugin root as request.plugin and hand it to providers (#468) #532 (fix/468-plugin-root-context) adds request.plugin and also bumps AGENT_REQUEST_STORE_VERSION to 4; whichever lands second rebases and bumps to 5. Overlapping files: agent-request.ts, entry-shell.ts, mcp-server-runtime.ts, test/{cli,mcp,render}.ts, the route-harness context fixture tests, mcp.mdx en/zh.
• feat(routes): let a route declare its render budget with config.render.maxElapsedMs (#454) #526 (fix/runtime-install-gaps) touches entry-shell.ts, mcp-server-runtime.ts, the harness, and the same docs pages; textual overlap only.
• perf(cli): load the Effect terminal runtime lazily to restore cold-start time #530 (perf/cli-cold-start): no shared files; this PR adds nothing to cli.ts and no Effect Terminal loads.

Review status

Codex reviewed b19e2d8 (two P1 threads); both are addressed in 4df2dd8:

• Changeset as a release summary — rewritten: user-facing, imperative, names the export/option surface, no AGENT_REQUEST_STORE_VERSION or harness wiring, ends with Fixes #511 (#534).

• runRscCli / createRscMcpServer never mounted terminal — createRscMcpServer now mounts the mcp/none value (derived); runRscCli gains RscCliOptions.terminal and mounts it native when the caller passes one, otherwise the axis stays honestly unavailable (not-provided) — the adapter owns no probe (the probe is agent-bundle's dependency-free module, which @agent-bundle/runtime cannot import; duplicating it into the runtime for a compatibility adapter was judged not worth a second implementation). Both adapters are pinned in rsc-runtime/tests/agent-request.test.ts and documented in the per-surface tables (docs/entry-conventions.md, mcp.mdx en/zh).

• Reviewed head: b19e2d8 (pre-rebase; the same change is e89f9e9 after rebasing over fix(skills): serve agent-bundle/meta to rendered skills and compile their JSX without the consumer react runtime #527/fix(host-contracts): guard Claude's .claude.json by its user-scope mcpServers only in the native smoke #529/perf(cli): load the Effect terminal runtime lazily to restore cold-start time #530/docs(effect): record rc.112 finalizer, abortSignal, and language-service caveats #531/docs(evaluations): show a typed outcome grader (EvalGraderFunction / EvalGraderContext / EvalScriptOutcome) #535 — clean rebases, no conflicts).

• Unreviewed heads (current SHAs): 370944c (test-only: unpin the inherited color level in the plain-script probe test — CI runners force color), 084596a (the two fixes above), 3c4ea4f (zh docs row mirroring the en one). CI was fully green on the pre-rebase head 4df2dd8; the first post-rebase run hit a packages/workbench/tests/mcp-app-real.e2e.test.ts Playwright waitForRequest timeout (unrelated to this change; main's own runs are red on the Node 26 leg for other reasons) and was superseded by the rebase onto docs(evaluations): show a typed outcome grader (EvalGraderFunction / EvalGraderContext / EvalScriptOutcome) #535. Auto-merge (squash) is armed for green.

• perf(cli): load the Effect terminal runtime lazily to restore cold-start time #530 (perf/cli-cold-start) merged underneath: no shared files, no Effect Terminal loads added here.

[changeset-bot]

🦋 Changeset detected

Latest commit: c869e09

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

This PR includes changesets to release 2 packages

Name	Type
agent-bundle	Patch
@agent-bundle/runtime	Patch

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-04T06:29:16.042369Z	b19e2d8	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@534

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@534

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@534

commit: c869e09

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b19e2d82b6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Rewrite the changeset as a release summary

This entry is emitted into the release notes, but it includes internal implementation details such as AGENT_REQUEST_STORE_VERSION and harness/runtime wiring, and ends with Fixes #511 rather than the required (#511). Rewrite it as a concise, user-facing imperative summary naming the new public capability and ending with the parenthesized PR reference.

AGENTS.md reference: AGENTS.md:L102-L105

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Mount terminal data in the runtime compatibility adapters

When an operation calls agent() through the public runRscCli or createRscMcpServer adapters, neither adapter supplies terminal to its runAgentRequest initializer (checked src/cli.ts:37-52 and src/mcp-server.ts:42-56), so this fallback returns unavailable. This contradicts the new documentation promising a native CLI capability and a derived terminal-free MCP capability, leaving the feature absent from two documented production paths; both adapters should mount the appropriate value.

AGENTS.md reference: AGENTS.md:L78-L81

Useful? React with 👍 / 👎.