Merge branch 'main' into feat/460-published-notices

Author: ScriptedAlchemy

.changeset/511-terminal-capability.md

@@ -0,0 +1,6 @@
+---
+'agent-bundle': patch
+'@agent-bundle/runtime': patch
+---
+
+Expose the process's terminal capability to routes and scripts as `(await agent()).terminal`, so a plugin that paints its own stderr or sizes its own output no longer probes `process.stdout.isTTY`, `columns`, or `FORCE_COLOR` itself. The new `Observed<AgentTerminal>` axis reports `hostSurface` (`cli`, `mcp`, `hook`, `script`, `workbench`), a `stdout` and `stderr` stream each with `kind` (`tty`, `pipe`, `none`), `color` (`none`, `basic`, `256`, `truecolor`), and `columns`/`rows` when known, plus `sharesTarget` (fd 1 and fd 2 name one file). Routed CLI executables (plain, rendered, and projected MCP commands) and rendered scripts probe their process once — honouring `FORCE_COLOR`, `CLICOLOR_FORCE`, `NO_COLOR`, `CLICOLOR=0`, `TERM=dumb`, `COLORTERM`/`TERM` depth, and `COLUMNS`/`LINES` overrides — and select their `tty` or piped output mode from that same value; generated MCP servers, event routes, and Workbench replays report `none` on both streams and never guess. The executable envelope passes the same value to plain `main` scripts and bins as `main(argv, { terminal })` (`ExecutableMainContext` from `agent-bundle`); a one-parameter `main` keeps working. `runGeneratedCliEntry` and `runGeneratedRenderedScript` (`agent-bundle/cli-entry`) accept `terminal` and hand it to `execute`, `render`, and `createSession`; `runRscCli` accepts `terminal` in its options and `createRscMcpServer` mounts the MCP value. In `agent-bundle/test`, the `tty` knob of `invokeCli` and `runScript` shapes a deterministic synthetic terminal, `renderRoute` and the in-memory MCP level mount what the artifact would, and `context.terminal` injects any other value. Fixes #511 (#534)

.changeset/514-serve-app.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Add `agent-bundle serve-app <server>/<app>` and `serveApp` in `agent-bundle/api`: serve one built MCP App standalone in a browser, bound to the plugin's own packed MCP server. The server launches exactly as `mcp run` does (same artifact resolution, `.env` layering, and plugin-data root), the App is hosted through the Workbench's MCP App host stack (sandbox proxy, consent authority, bridge) on `127.0.0.1` behind a per-launch token (`AB8003` / `AB8004` on refusal), and the App's tool is called once so it opens populated. `--tool`, `--input`, `--port`, `--profile`, `--allow <capability>`, `--open`, and the `mcp run` environment flags select the binding; `serveApp` returns `{ url, close, closed }` so a plugin's own CLI route can offer an "open the dashboard" command. Fixes #514. (#537)

docs/effect-conventions.md

@@ -563,6 +563,16 @@ Wiring rules:
   `install/surface.ts`), and child/worker stderr forwarding keep their direct
   `process.stdout`/`process.stderr` adapters: emitted artifacts must not carry
   a platform runtime, and byte-exact protocol frames are not terminal text.
+- **The route-facing terminal capability is plain Node, not `Terminal`.**
+  `request.terminal` (#511) — TTY-ness, color depth, and `columns`/`rows` per
+  output stream, reported to routes, rendered scripts, and `main`-envelope
+  executables — is probed by the dependency-free `src/terminal-capability.ts`
+  (aliased into emitted executables as `agent-bundle/terminal-capability`)
+  because those artifacts must not carry the Effect runtime; the first-party
+  CLI mounts no route request scope, so it has nothing to read from the
+  `Terminal` service for it. `Terminal.columns`/`rows` remain the first-party
+  CLI's own way to size its human output. Rules and the per-surface table:
+  [Terminal capability](entry-conventions.md#terminal-capability-requestterminal).
 
 ## Effect Schema wire contracts (Schema projections)
 

docs/entry-conventions.md

@@ -594,6 +594,72 @@ the in-memory MCP proof level accepts a registry
 (`openInMemoryMcpServer({ lineage, lineageHost })`) so hook→MCP correlation
 is testable without a spawned process.
 
+#### Terminal capability (`request.terminal`)
+
+`(await agent()).terminal` is an `Observed<AgentTerminal>` (#511): what the
+process's output streams are, computed **once per invocation by the framework
+shell** with the same rules that pick the CLI output mode, so a route that
+colors its own stderr or sizes its own table agrees with the framework's
+rendering instead of re-probing `process.stdout` per plugin. It is information
+only — never a writer — and it never changes what `Agent.*` components render.
+
+```ts
+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;                // present for a terminal, or when COLUMNS overrides
+  rows?: number;                   // present for a terminal, or when LINES overrides
+}
+```
+
+The probe (`src/terminal-capability.ts`, plain Node, dependency-free, aliased
+into emitted executables as `agent-bundle/terminal-capability`) reads
+`isTTY`, `columns`, and `rows` off `process.stdout`/`process.stderr`, `fstat`s
+the descriptors (`tty`; any other open descriptor is `pipe`; a closed one is
+`none`; `sharesTarget` compares device and inode), and resolves color in the
+informal standards' precedence: `FORCE_COLOR` decides outright when set
+(`0`/`false` off; empty, `1`, or `true` basic; `2` 256; `3` truecolor — Node's
+reading), then `CLICOLOR_FORCE` forces color on even for a pipe at the depth
+`COLORTERM`/`TERM` advertise, `NO_COLOR` (any non-empty value) and `CLICOLOR=0`
+force it off, `TERM=dumb` renders none, and otherwise a terminal renders at its
+advertised depth while a pipe renders none. `COLUMNS`/`LINES` override the
+reported size whatever the stream is. The routed CLI derives its `tty` versus
+piped-Markdown mode from this same value (`stdout.kind === 'tty'`), so the two
+can never disagree.
+
+Per surface, the value the generated request scope mounts:
+
+| Surface | `hostSurface` | `stdout` / `stderr` | Source |
+| --- | --- | --- | --- |
+| Routed CLI executable (`dist/bin/<name>.js`, `<target>/bin/<name>.mjs`), plain or rendered command, projected MCP command | `cli` | Probed from the executable's own process; a rendered command's worker thread receives the executable's probe, never its own pipes. Machine output owns fd 1, so `stdout` describes where the rendered document lands and `stderr` the channel a route may write to itself. | `native` |
+| Rendered script (`scripts/<name>.mjs` from `src/scripts/<name>.tsx`) | `script` | Probed, as above. | `native` |
+| Generated MCP server (any transport) | `mcp` | `none` on both, `color: 'none'`, `sharesTarget: false` — stdout is the protocol wire and stderr the host's log. Never probed, whatever the descriptors are. | `derived` |
+| Event route (shared runtime or standalone hook process) | `hook` | `none` on both — stdout is the host's hook envelope. Never probed. | `derived` |
+| Workbench lifecycle replay | `workbench` | `none` on both — the document renders into a panel. | `derived` |
+| `createRscMcpServer` (the `defineRscApplication` MCP adapter) | `mcp` | `none` on both, as above. | `derived` |
+| `runRscCli` (the `defineRscApplication` CLI adapter) | `cli` when the caller passes `terminal` in its options | The adapter owns no probe — the generated routed-CLI shell does — so the caller's value is mounted `native`; omitted, the axis is `unavailable` (`not-provided`). | `native` / — |
+| Custom host calling `runAgentRequest` without `terminal` | — | `unavailable` (`not-provided`) | — |
+
+Plain `main`-exporting scripts and bins have no request scope, so the
+executable envelope hands them the same probe directly as the second argument
+of `main` (see [The executable envelope](#the-executable-envelope-bin--scripts)).
+
+The `agent-bundle/test` harness never probes the test runner's own streams:
+`invokeCli` and `runScript` mount a deterministic synthetic value shaped by
+their `tty` knob (an 80×24 `basic`-color terminal on both streams with
+`sharesTarget: true`, or two `color: 'none'` pipes), `renderRoute` mounts what
+the artifact's scope for that route kind would (`none` for MCP and event
+routes, the piped shape for `cli` and `script` kinds), the in-memory MCP level
+forwards the real server's `none`, and a plain script's `main` receives the
+real child process's probe (two pipes). A test that wants other values injects
+`context.terminal` through the same seam as every identity axis.
+
 ### Migration nudges
 
 Source validation reports **informational** nudges (never errors — migrations
@@ -625,17 +691,27 @@ default function for bin entries) receives the generated process envelope:
 
 ```ts
 // src/cli.ts — the whole CLI entry a consumer writes
-export const main = async (argv: readonly string[]): Promise<number> => {
-  // ...
+import type { ExecutableMainContext } from 'agent-bundle';
+
+export const main = async (argv: readonly string[], { terminal }: ExecutableMainContext): Promise<number> => {
+  if (terminal.stderr.color !== 'none') { /* paint progress on stderr */ }
   return 0;
 };
 ```
 
-The envelope awaits `main(process.argv.slice(2))`, adopts a numeric return as
-the process exit code, and lets an escaped rejection surface through Node's
-top-level failure path (stack to stderr, exit code 1). Self-executing modules
-(no `main` export) bundle directly, byte for byte — existing Scripts keep
-their behavior.
+The envelope awaits `main(process.argv.slice(2), { terminal })`, adopts a
+numeric return as the process exit code, and lets an escaped rejection surface
+through Node's top-level failure path (stack to stderr, exit code 1).
+`terminal` is the process's [terminal capability](#terminal-capability-requestterminal)
+(#511), probed once before `main` runs by the dependency-free
+`agent-bundle/terminal-capability` module the envelope aliases in — plain
+scripts and bins load no Effect runtime and no `@agent-bundle/runtime` for it.
+Its `hostSurface` is `cli` for a package bin (`dist/bin/<name>.js`) and
+`script` for an artifact script (`scripts/<name>.mjs`); a module shipped on
+both surfaces sees the surface it was launched from. A `main` declared with
+one parameter keeps working — the second argument is simply unread.
+Self-executing modules (no `main` export) bundle directly, byte for byte —
+existing Scripts keep their behavior and receive no probe.
 
 ### The routed CLI shell (#102 stages 2-3)
 
@@ -1182,3 +1258,38 @@ content-hashed bundle inside the target root). `--plugin-root <path>`
 overrides the env-anchor root, e.g. point it at `artifact/<target>` for a
 byte-faithful rehearsal of a copied-artifact launch; under a host install the
 anchor still means the durable install root, exactly as before.
+
+## `agent-bundle serve-app`
+
+```sh
+agent-bundle serve-app <server>/<app> [--artifact <path>] [--target <target>]
+  [--tool <name>] [--input <json> | --input-file <path>] [--port <port>]
+  [--profile <profile>] [--allow <capability>]... [--open]
+  [--env-file <path>]... [--no-env] [--plugin-root <path>]
+```
+
+Serves one built MCP App standalone in a browser, outside any MCP host and
+without the Workbench. The command launches the App's packed MCP server
+through exactly the `mcp run` launcher above (same manifest resolution, same
+three-layer environment, same durable-state anchors), binds the App to that
+one session through the Workbench's own MCP App host stack
+(`McpAppBindingService` → `McpAppPreviewService` → `McpAppRoutes`, the
+loopback sandbox proxy, the consent authority, `McpAppBridge`), calls the
+App's tool once so it opens populated, and prints the loopback URL. It runs
+in the foreground until SIGINT/SIGTERM, or until the server exits on its own,
+which is reported as one `AB5000` diagnostic with exit code 1. Without
+`--artifact`, a throwaway artifact is built into a staging directory beside
+the project root and removed when the host closes.
+
+The host document is served on `127.0.0.1` only, at `/`, with the
+authenticated `/api/mcp/...` routes behind a per-launch token plus
+same-origin and loopback `Host` checks (`AB8003` / `AB8004` on refusal); the
+App document runs on a second loopback origin inside the framework sandbox,
+and the bridge exposes only the selected server. This is a local preview
+host, not a deployment target.
+
+`serveApp` in `agent-bundle/api` is the programmatic form (`{ url, close,
+closed }`) for a plugin's own routed CLI (`hauler dashboard`). It belongs to
+the plugin's dev-time / CLI process — import it lazily from the route that
+needs it — never to the MCP server shell, so emitted artifacts stay free of
+the host runtime.

docs/framework-mode.md

@@ -93,6 +93,15 @@ as well, and is the form to use when the component also needs the URI at run
 time. The full grammar and the `config.template` resolution rule are in
 [Diagnostics](diagnostics.md).
 
+A built App is previewed in the Workbench MCP page, or served standalone in a
+plain browser tab with `agent-bundle serve-app <server>/<app>` — the same
+host stack (sandbox proxy, consent authority, bridge) bound to the plugin's
+own packed server, launched as `mcp run` launches it. `serveApp` in
+`agent-bundle/api` is the programmatic form for a plugin's own "open the
+dashboard" CLI route; it runs in the plugin's dev-time / CLI process, never
+in the MCP shell, and is a local preview host, not a deployment target. See
+[Entry conventions](entry-conventions.md#agent-bundle-serve-app).
+
 The compiler statically reads `config`, imports schemas and implementations
 only into generated entries, installs `runAgentRequest`, and derives the real
 MCP server from the route graph. Each call renders through a warm internal

packages/agent-bundle/fixtures/route-harness/src/events/tool/after.tsx

@@ -11,10 +11,15 @@ export default async function AfterTool({ canonical }: AgentEventRouteProps) {
   const actorContext = context.actor.state === 'available'
     ? `actor available:${context.actor.source}:${context.actor.value.id}`
     : `actor unavailable:${context.actor.reason}`;
+  // A hook has no terminal (#511); the route reports what it observed.
+  const terminalContext = context.terminal.state === 'available'
+    ? `terminal available:${context.terminal.source} ${context.terminal.value.hostSurface}/${context.terminal.value.stdout.kind}/${context.terminal.value.stderr.kind}`
+    : `terminal unavailable:${context.terminal.reason}`;
   return (
     <Agent.Result>
       <Agent.Markdown>{`Observed ${canonical.event} from ${canonical.provenance.host}.`}</Agent.Markdown>
       <Agent.Context>{actorContext}</Agent.Context>
+      <Agent.Context>{terminalContext}</Agent.Context>
       {notices.map((notice) => (
         <Agent.Context key={notice.id}>{`notice ${notice.id}: ${notice.message}`}</Agent.Context>
       ))}

packages/agent-bundle/fixtures/route-harness/src/mcp/harness/tools/context.tsx

@@ -16,6 +16,7 @@ export const resultSchema = z.object({
   host: z.unknown(),
   lineage: z.unknown(),
   session: z.unknown(),
+  terminal: z.unknown(),
   workspace: z.unknown(),
 }).strict();
 
@@ -36,11 +37,15 @@ export default async function Context() {
   const lineage: JsonValue = context.lineage.state === 'available'
     ? { source: context.lineage.source, state: context.lineage.state, value: JSON.parse(JSON.stringify(context.lineage.value)) as JsonValue }
     : { reason: context.lineage.reason, state: context.lineage.state };
+  const terminal: JsonValue = context.terminal.state === 'available'
+    ? { source: context.terminal.source, state: context.terminal.state, value: JSON.parse(JSON.stringify(context.terminal.value)) as JsonValue }
+    : { reason: context.terminal.reason, state: context.terminal.state };
   const result = {
     actor,
     host,
     lineage,
     session,
+    terminal,
     workspace,
   };
   return (

packages/agent-bundle/fixtures/route-harness/src/scripts/checksum.ts

@@ -1,17 +1,25 @@
+import type { ExecutableMainContext } from 'agent-bundle';
+
 /**
  * A plain script with the `main` process-envelope contract: the generated
- * `scripts/checksum.mjs` awaits `main(process.argv.slice(2))` and adopts a
- * numeric return as the exit code. No renderer, no request context.
+ * `scripts/checksum.mjs` awaits `main(process.argv.slice(2), { terminal })`
+ * and adopts a numeric return as the exit code. No renderer, no request
+ * context; the terminal capability (#511) arrives through the envelope.
  */
 
 /** Module state: a fresh process starts at zero, a cached module would not. */
 let calls = 0;
 
-export const main = async (argv: readonly string[]): Promise<number | undefined> => {
+export const main = async (argv: readonly string[], context: ExecutableMainContext): Promise<number | undefined> => {
   calls += 1;
   if (argv.includes('--explode')) {
     throw new Error('checksum exploded');
   }
+  if (argv.includes('--terminal')) {
+    // What the envelope probed for this process, as one canonical JSON line.
+    process.stdout.write(`${JSON.stringify(context.terminal)}\n`);
+    return 0;
+  }
   if (argv.includes('--calls')) {
     process.stdout.write(`checksum call ${String(calls)} in ${process.argv[1]!}\n`);
     return 0;

packages/agent-bundle/fixtures/route-harness/src/scripts/summary.tsx

@@ -57,6 +57,10 @@ export default async function Summary({ argv, signal }: ScriptRouteProps) {
     invocation: context.invocation.kind,
     stateMounted: context.state !== undefined,
     surface: context.invocation.surface ?? null,
+    // The executable's probed terminal (#511), as `<surface>/<stdout kind>/<stderr kind>`.
+    terminal: context.terminal.state === 'available'
+      ? `${context.terminal.value.hostSurface}/${context.terminal.value.stdout.kind}/${context.terminal.value.stderr.kind}`
+      : `unavailable:${context.terminal.reason}`,
   };
   if (argv.includes('--fail')) {
     return (

packages/agent-bundle/rslib.config.ts

@@ -112,6 +112,7 @@ export default defineConfig({
       // into its generated bundle.
       routes: './src/routes/public.ts',
       rstest: './src/rstest/index.ts',
+      'terminal-capability': './src/terminal-capability.ts',
       test: './src/test/index.ts',
       'test/browser': './src/test/browser.ts',
     },