experimental-ash 0.55.0 → 0.55.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # experimental-ash
 
+## 0.55.1
+
+### Patch Changes
+
+- 93c1d3c: feat(ash): add new TUI for `ash dev`, replacing the previous REPL by default
+- 6a8ec9f: Code-mode nested tool calls now return raw tool outputs inside the VM and expose those raw outputs to Ash lifecycle handlers.
+
 ## 0.55.0
 
 ### Minor Changes

package/dist/docs/public/advanced/cli-build-and-debugging.md

@@ -13,7 +13,7 @@ From your app root:
 - `ash info` - inspect the discovered authored surface and runtime details
 - `ash build` - compile `.ash/` artifacts and build the host output
 - `ash start` - serve the built `.output/` app
-- `ash dev` - start the local runtime and open the REPL
+- `ash dev` - start the local runtime and open the interactive [terminal UI](./dev-tui.md)
 - `ash eval` - run eval suites against the current app or a remote target
 
 ## Recommended Loop

package/dist/docs/public/advanced/dev-tui.md

@@ -0,0 +1,202 @@
+---
+title: "Dev TUI (`ash dev`)"
+description: "Run and chat with your agent locally in an interactive terminal UI."
+url: /dev-tui
+---
+
+`ash dev` starts the local runtime and opens an interactive terminal UI (the TUI) where you can
+chat with your agent, watch it stream, approve tool calls, and answer its questions — all without
+leaving the terminal. It is the fastest way to exercise an agent while you iterate.
+
+## Quick Start
+
+From your app root:
+
+```bash
+ash dev
+```
+
+This boots the local runtime, starts a dev server, and drops you into the TUI connected to it. Type
+a prompt, press `Enter`, and the agent's response streams in. Press `Ctrl+C` to
+quit; this also shuts the dev server down.
+
+## The Layout
+
+The TUI looks something like this (with the different sections being color-coded in reality):
+
+```
+┌ Ash ────────────────────────────────────────────────────────────────── 7,421 tokens ┐
+│ ╭ User ───────────────────────────────────────────────────────────────────────────╮ │
+│ │ what's the weather in San Francisco?                                            │ │
+│ ╰─────────────────────────────────────────────────────────────────────────────────╯ │
+│ ╭ Log · stdout ···································································╮ │
+│ │ weather-agent session started { sessionId: 'wrun_a1b2c3d4e5f6g7h8i9',           │ │
+│ │ channel: 'http' }                                                               │ │
+│ ╰·················································································╯ │
+│ ╭ Reasoning ······································································╮ │
+│ │ The user is asking about weather, so I need to load the get-weather skill       │ │
+│ │ first.                                                                          │ │
+│ ╰·················································································╯ │
+│ ╭ Tool · load_skill ──────────────────────────────────────────────────────── done ╮ │
+│ ╰─────────────────────────────────────────────────────────────────────────────────╯ │
+│ ╭ Log · stdout ···································································╮ │
+│ │ weather lookup { city: 'San Francisco', temperatureF: 72, condition: 'Sunny' }  │ │
+│ ╰·················································································╯ │
+│ ╭ Tool · get_weather ─────────────────────────────────────────────────────── done ╮ │
+│ ╰─────────────────────────────────────────────────────────────────────────────────╯ │
+│ ╭ Assistant ──────────────────────────────────────────────────────────────────────╮ │
+│ │ Using the local weather tool: San Francisco is currently 72°F and sunny, with a │ │
+│ │ light breeze.                                                                   │ │
+│ ╰─────────────────────────────────────────────────────────────────────────────────╯ │
+│ ╭ Log · stdout ···································································╮ │
+│ │ weather-agent turn completed {                                                  │ │
+│ │   sessionId: 'wrun_a1b2c3d4e5f6g7h8i9',                                         │ │
+│ │   turnId: 'turn_0',                                                             │ │
+│ │   sequence: 0                                                                   │ │
+│ │ }                                                                               │ │
+│ ╰·················································································╯ │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+┌ Input ──────────────────────────────────────────────────────────────────────────────┐
+│ > █                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+The TUI is made up of three regions:
+
+- **Header** — the app name and, while a turn is running, live response stats (e.g. tokens per second,
+  or total tokens).
+- **Transcript** — the scrollable conversation: your prompts, the agent's streamed messages,
+  reasoning, tool calls, subagent activity, connection-authorization prompts, and server/agent logs.
+- **Input / status bar** — where you type, plus a contextual hint line showing the current state
+  (`Streaming…`, `Executing tools…`, `Done`, an approval prompt, and so on) and the keys available.
+
+## Keyboard Shortcuts
+
+| Key       | Action                                                     |
+| --------- | ---------------------------------------------------------- |
+| `Enter`   | Send the prompt / confirm the current answer               |
+| `↑` / `↓` | Scroll the transcript                                      |
+| `Esc`     | Back out of (or clear) the current input without answering |
+| `Ctrl+R`  | Repaint the screen                                         |
+| `q`       | Quit when the agent is idle (a turn has finished)          |
+| `Ctrl+C`  | Quit at any time, interrupting a running turn              |
+
+## Slash Commands
+
+Type these as a prompt:
+
+- `/new` — start a fresh session. Clears the transcript and the durable session cursor so the next
+  turn begins a new server-side conversation.
+- `/exit` (or `/quit`) — leave the TUI and shut the dev server down, the same as `Ctrl+C`.
+
+## Human In The Loop
+
+When the agent needs you, the TUI prompts inline and the status bar tells you which keys apply:
+
+- **Tool approvals** — answer `y` / `n` to approve or deny.
+- **Questions** — for option questions, use `↑` / `↓` to select and `Enter`
+  to confirm; for freeform answers, type and press `Enter`. `Esc` backs out.
+
+If you press `Esc` on a pending request and then send a normal message, the request is
+ignored. See [Human In The Loop](../human-in-the-loop.mdx) for how these requests are authored.
+
+## Connection Authorization
+
+When a tool needs an authorized [connection](../connections.mdx) — for example an MCP server behind
+OAuth — the TUI renders the authorization challenge inline: the URL to visit and any user/device
+code to enter. The status bar shows a `Waiting for connection authorization` hint until you complete
+the flow in your browser, then the turn resumes automatically.
+
+## Subagents
+
+When the agent dispatches a [subagent](../subagents.mdx), its activity renders as its own section in
+the transcript, with a live status in the section header. By default subagent sections are shown in
+full; use `--subagents` to collapse or hide them (see below).
+
+## Logs
+
+`stdout` and `stderr` from the dev server and the agent are captured and shown inline in the
+transcript, so you can correlate log output with the turn that produced it. Control how much is shown
+with `--logs`.
+
+## Display Options
+
+The TUI's density is configurable. Each of these flags accepts one of `full`, `collapsed`,
+`auto-collapsed`, or `hidden` unless noted otherwise. `auto-collapsed` shows a section in full while
+it is active and collapses it once finished.
+
+| Flag                                | Controls                                                    | Default           |
+| ----------------------------------- | ----------------------------------------------------------- | ----------------- |
+| `--tools <mode>`                    | How tool calls render                                       | `auto-collapsed`  |
+| `--reasoning <mode>`                | How reasoning renders                                       | `full`            |
+| `--subagents <mode>`                | How subagent sections render                                | `full`            |
+| `--connection-auth <mode>`          | How connection-authorization prompts render                 | `full`            |
+| `--assistant-response-stats <mode>` | Header statistic: `tokens` or `tokensPerSecond`             | `tokensPerSecond` |
+| `--context-size <tokens>`           | Model context window size, shown as a usage percentage      | _unset_           |
+| `--logs <mode>`                     | Which server/agent logs to show: `all`, `stderr`, or `none` | `all`             |
+
+For example, to keep tool calls fully expanded and show absolute token counts:
+
+```bash
+ash dev --tools full --assistant-response-stats tokens
+```
+
+Set `--context-size` to your model's context window to see how full it is getting:
+
+```bash
+ash dev --context-size 200000
+```
+
+## Server Options
+
+By default `ash dev` binds the dev server to a local interface and uses `$PORT`, falling back to
+`3000`. Override either:
+
+```bash
+ash dev --host 0.0.0.0 --port 4000
+```
+
+## Connecting To A Remote Server
+
+Instead of starting a local server, point the TUI at an already-running one — for example a Vercel
+preview or production deployment:
+
+```bash
+ash dev https://<your-app>
+```
+
+The bare URL is shorthand for `--url https://<your-app>`. When connecting to a remote server, the
+`--host`, `--port`, and `--no-ui` options do not apply.
+
+If the deployment uses Vercel preview protection, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally
+before launching so the TUI can authenticate against it. See
+[Vercel Deployment](./vercel-deployment.md) for details.
+
+## Headless Mode
+
+Pass `--no-ui` to start the dev server and keep it running without an interactive UI — useful when
+another process drives the HTTP routes:
+
+```bash
+ash dev --no-ui
+```
+
+`ash dev` also falls back to headless automatically when the terminal is not a TTY (for example in
+CI or when output is piped), printing a note so the missing UI is not mistaken for a hang.
+
+## The Classic REPL
+
+Before the TUI, `ash dev` opened a simpler line-based REPL. It is still available behind a flag
+during the transition and will be removed in a future release:
+
+```bash
+ash dev --repl
+```
+
+Prefer the default TUI for day-to-day work.
+
+## What To Read Next
+
+- [CLI, Build, And Debugging](./cli-build-and-debugging.md)
+- [Human In The Loop](../human-in-the-loop.mdx)
+- [Vercel Deployment](./vercel-deployment.md)

package/dist/docs/public/advanced/meta.json

@@ -11,6 +11,7 @@
     "workspace",
     "evals",
     "instrumentation",
+    "dev-tui",
     "cli-build-and-debugging",
     "typescript-api",
     "...",

package/dist/docs/public/advanced/vercel-deployment.md

@@ -33,7 +33,7 @@ Typical Vercel env vars for an Ash app include:
 - optional `ASH_SANDBOX_BACKEND`
 
 If your deployment uses Vercel preview protection and you want to connect to it with `ash dev`, set
-`VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching the REPL against the deployed URL.
+`VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching the dev TUI against the deployed URL.
 
 ## Sandbox Backend
 
@@ -88,9 +88,9 @@ Then attach to the returned stream URL pattern:
 curl https://<your-app>/ash/v1/session/<sessionId>/stream
 ```
 
-## Remote REPL
+## Remote Dev
 
-You can point the Ash REPL at a deployed app:
+You can point the Ash dev [TUI](./dev-tui.md) at a deployed app:
 
 ```bash
 ash dev https://<your-app>

package/dist/docs/public/getting-started.mdx

@@ -98,7 +98,7 @@ Useful commands:
 - `ash info`: show the active routes and compiled artifacts
 - `ash build`: compile the agent into `.ash/` and build the host output
 - `ash start`: serve the built `.output/` app
-- `ash dev`: start the local runtime and open the REPL
+- `ash dev`: start the local runtime and open the interactive [terminal UI](./advanced/dev-tui.md)
 
 ## Send A Message
 

package/dist/docs/public/human-in-the-loop.mdx

@@ -244,11 +244,11 @@ webhook URL — no separate interactivity endpoint needed.
 
 ## CLI Behavior
 
-`ash dev` surfaces pending HITL requests directly in the REPL:
+`ash dev` surfaces pending HITL requests directly in the [terminal UI](./advanced/dev-tui.md):
 
-- tool approvals prompt for yes/no
-- questions prompt for an option number or freeform answer
-- `Escape` returns to the normal `you>` prompt without answering
+- tool approvals prompt for `y` / `n`
+- option questions are answered with `↑` / `↓` to select and `Enter` to confirm; freeform questions accept typed input
+- `Escape` backs out without answering
 
 If you press `Escape` and then send a normal message, the pending requests are ignored.
 

package/dist/docs/public/onboarding.md

@@ -24,7 +24,7 @@ Collect these up front. A capable agent should use a structured question UI (suc
 
 1. **Name** — the project / directory name (kebab-case). Also used as the Slack connector slug.
 2. **Model** — for example `anthropic/claude-sonnet-4.6` or `openai/gpt-5-mini`. Baked into `agent/agent.ts`.
-3. **Channels** — `web` can be scaffolded headlessly. `slack` is an interactive follow-up because Vercel Connect opens a browser OAuth flow. The local REPL is always available via `ash dev`, regardless of channel choice.
+3. **Channels** — `web` can be scaffolded headlessly. `slack` is an interactive follow-up because Vercel Connect opens a browser OAuth flow. The local terminal UI is always available via `ash dev`, regardless of channel choice.
 4. **Model provider** — how the agent reaches a model:
    - Vercel project (default) — create a project, or pass `--project <slug>` to link an existing one, and use AI Gateway via OIDC.
    - API key override — pass `--gateway-api-key <key>` to write `AI_GATEWAY_API_KEY` to `.env.local`.
@@ -103,7 +103,7 @@ Treat setup as successful only when `ash info --json` reports `status: "ready"`
 ## Step 4 — Run and test locally
 
 - Web chat: `pnpm dev`, open `http://localhost:3000`, send a message.
-- REPL: `ash dev`, chat in the terminal.
+- Terminal UI: `ash dev`, chat in the terminal.
 
 The agent replies only if it can reach a model: either `AI_GATEWAY_API_KEY` is set in `.env.local`, or the Vercel project is linked and you have run `vercel env pull --yes`.
 

package/dist/src/cli/dev/{repl.d.ts → repl/repl.d.ts}

@@ -1,7 +1,7 @@
 import { type HandleMessageStreamEvent } from "#protocol/message.js";
 import type { InputRequest } from "#runtime/input/types.js";
 import { type CliTheme } from "#cli/ui/output.js";
-import { createDevelopmentTerminal } from "#cli/dev/terminal.js";
+import { createDevelopmentTerminal } from "#cli/dev/repl/terminal.js";
 export type ReplDisplayBlockKind = "content" | "meta";
 export type LiveContentKind = "message" | "reasoning";
 export interface FormattedContentEvent {

package/dist/src/cli/dev/{repl.js → repl/repl.js}

@@ -1,2 +1,2 @@
-import{ASH_CONTINUE_SESSION_ROUTE_PATTERN,ASH_CREATE_SESSION_ROUTE_PATH,ASH_MESSAGE_STREAM_ROUTE_PATTERN,createAshMessageStreamRoutePath}from"#protocol/routes.js";import{createInterface,emitKeypressEvents}from"node:readline";import{createCliTheme,renderCliBanner,renderCliSection,renderCliSpeakerLine,renderCliTaggedLine}from"#cli/ui/output.js";import{openStreamIterable}from"#client/open-stream.js";import{isCurrentTurnBoundaryEvent}from"#protocol/message.js";import{toErrorMessage}from"#shared/errors.js";import{createDevelopmentRequestHeadersAsync}from"#services/dev-client/request-headers.js";import{extractCurrentTurnBoundaryEvent}from"#services/dev-client/stream.js";import{resolveDevelopmentServerResourceUrl}from"#services/dev-client/url.js";import{formatVercelAuthChallengeMessage,isVercelAuthChallenge}from"#services/dev-client/vercel-auth-error.js";import{createDevClient}from"#services/dev-client.js";import{parseDevReplInput}from"#cli/dev/input.js";import{ESCAPED_RUNTIME_INPUT_PROMPT,extractPendingRuntimeInputRequests,promptForRuntimeInputRequests}from"#cli/dev/input-requests.js";import{createDevelopmentTerminal}from"#cli/dev/terminal.js";function renderConnectionRows(r){let i=[{label:`Server`,tone:`info`,value:r.serverUrl},{label:`Create`,tone:`info`,value:`POST ${ASH_CREATE_SESSION_ROUTE_PATH}`},{label:`Continue`,tone:`info`,value:`POST ${ASH_CONTINUE_SESSION_ROUTE_PATTERN}`},{label:`Stream`,tone:`info`,value:`GET ${ASH_MESSAGE_STREAM_ROUTE_PATTERN}`}];return i.push({label:`Session`,value:`Follow-up messages reuse the active continuation token.`}),i}function renderCommandRows(){return[{label:`/help`,value:`Print the connection contract and available commands.`},{label:`/new`,value:`Clear the current durable session cursor.`},{label:`/exit`,value:`Exit the REPL.`}]}function renderIntro(e,t){return[renderCliBanner(e,{subtitle:`Interactive development REPL for the active Ash server.`,title:`Ash Dev`}),``,renderCliSection(e,{rows:renderConnectionRows(t),title:`Connection`}),``,renderCliSection(e,{rows:renderCommandRows(),title:`Commands`})].join(`
+import{ASH_CONTINUE_SESSION_ROUTE_PATTERN,ASH_CREATE_SESSION_ROUTE_PATH,ASH_MESSAGE_STREAM_ROUTE_PATTERN,createAshMessageStreamRoutePath}from"#protocol/routes.js";import{createInterface,emitKeypressEvents}from"node:readline";import{createCliTheme,renderCliBanner,renderCliSection,renderCliSpeakerLine,renderCliTaggedLine}from"#cli/ui/output.js";import{openStreamIterable}from"#client/open-stream.js";import{isCurrentTurnBoundaryEvent}from"#protocol/message.js";import{toErrorMessage}from"#shared/errors.js";import{createDevelopmentRequestHeadersAsync}from"#services/dev-client/request-headers.js";import{extractCurrentTurnBoundaryEvent}from"#services/dev-client/stream.js";import{resolveDevelopmentServerResourceUrl}from"#services/dev-client/url.js";import{formatVercelAuthChallengeMessage,isVercelAuthChallenge}from"#services/dev-client/vercel-auth-error.js";import{createDevClient}from"#services/dev-client.js";import{parseDevReplInput}from"#cli/dev/repl/input.js";import{ESCAPED_RUNTIME_INPUT_PROMPT,extractPendingRuntimeInputRequests,promptForRuntimeInputRequests}from"#cli/dev/repl/input-requests.js";import{createDevelopmentTerminal}from"#cli/dev/repl/terminal.js";function renderConnectionRows(r){let i=[{label:`Server`,tone:`info`,value:r.serverUrl},{label:`Create`,tone:`info`,value:`POST ${ASH_CREATE_SESSION_ROUTE_PATH}`},{label:`Continue`,tone:`info`,value:`POST ${ASH_CONTINUE_SESSION_ROUTE_PATTERN}`},{label:`Stream`,tone:`info`,value:`GET ${ASH_MESSAGE_STREAM_ROUTE_PATTERN}`}];return i.push({label:`Session`,value:`Follow-up messages reuse the active continuation token.`}),i}function renderCommandRows(){return[{label:`/help`,value:`Print the connection contract and available commands.`},{label:`/new`,value:`Clear the current durable session cursor.`},{label:`/exit`,value:`Exit the REPL.`}]}function renderIntro(e,t){return[renderCliBanner(e,{subtitle:`Interactive development REPL for the active Ash server.`,title:`Ash Dev`}),``,renderCliSection(e,{rows:renderConnectionRows(t),title:`Connection`}),``,renderCliSection(e,{rows:renderCommandRows(),title:`Commands`})].join(`
 `)}function normalizeStepMessage(e){let t=e.trim();return t.length>0?t:null}function getRenderTag(e){return e.options?.isSubagent===!0?`subagent`:e.fallback}function getRenderTone(e){return e.options?.isSubagent===!0?`subagent`:e.fallback}function prefixSourceLabel(e){return e.options?.sourceLabel===void 0?e.message:`${e.options.sourceLabel}${e.separator??` `}${e.message}`}function formatContentEvent(e,t,n){switch(t.type){case`message.appended`:return{finalized:!1,kind:`message`,line:renderCliSpeakerLine(e,{message:t.data.messageSoFar,speaker:n?.sourceLabel??`agent`,tone:getRenderTone({fallback:`accent`,options:n})})};case`message.completed`:if(t.data.message===null)return;if(t.data.finishReason===`tool-calls`){let r=normalizeStepMessage(t.data.message);return r===null?void 0:{finalized:!0,kind:`message`,line:renderCliTaggedLine(e,{message:prefixSourceLabel({message:r,options:n,separator:`: `}),tag:getRenderTag({fallback:`step`,options:n}),tone:getRenderTone({fallback:`accent`,options:n})})}}return{finalized:!0,kind:`message`,line:renderCliSpeakerLine(e,{message:t.data.message,speaker:n?.sourceLabel??`agent`,tone:getRenderTone({fallback:`accent`,options:n})})};case`reasoning.appended`:return{finalized:!1,kind:`reasoning`,line:renderCliTaggedLine(e,{message:prefixSourceLabel({message:t.data.reasoningSoFar,options:n,separator:`: `}),tag:getRenderTag({fallback:`reasoning`,options:n}),tone:getRenderTone({fallback:`info`,options:n})})};case`reasoning.completed`:return{finalized:!0,kind:`reasoning`,line:renderCliTaggedLine(e,{message:prefixSourceLabel({message:t.data.reasoning,options:n,separator:`: `}),tag:getRenderTag({fallback:`reasoning`,options:n}),tone:getRenderTone({fallback:`info`,options:n})})};default:return}}function formatEvent(e,t,n){let r=formatContentEvent(e,t,n);if(r!==void 0)return r.line;switch(t.type){case`message.received`:return;case`actions.requested`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.actions.length} action${t.data.actions.length===1?``:`s`})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`muted`,options:n})});case`input.requested`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.requests.length} request${t.data.requests.length===1?``:`s`})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`info`,options:n})});case`action.result`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${formatActionResultLabel(t.data.result)})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`muted`,options:n})});case`session.waiting`:case`session.completed`:return;case`authorization.required`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.name}: ${t.data.description}${formatAuthorizationChallengeSuffix(t.data.authorization)})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`warning`,options:n})});case`compaction.requested`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`compacting conversation history`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`muted`,options:n})});case`compaction.completed`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`conversation history compacted`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`muted`,options:n})});case`step.failed`:case`turn.failed`:case`session.failed`:return;case`subagent.called`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.name} -> ${t.data.childSessionId})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`info`,options:n})});case`subagent.started`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.subagentName})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`info`,options:n})});case`subagent.event`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.subagentName}: ${formatNestedSubagentEventLabel(t.data.event)})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`muted`,options:n})});case`subagent.completed`:return renderCliTaggedLine(e,{message:prefixSourceLabel({message:`${t.type} (${t.data.subagentName})`,options:n}),tag:getRenderTag({fallback:`event`,options:n}),tone:getRenderTone({fallback:`info`,options:n})});default:return}}function getEventDisplayBlockKind(e){switch(e.type){case`message.appended`:case`message.completed`:case`reasoning.appended`:case`reasoning.completed`:return`content`;default:return`meta`}}function createTurnDisplayState(){return{activeLiveContentKind:null,lastPrintedBlockKind:null}}function printDisplayLine(e){let t=e.state;return t.activeLiveContentKind!==null&&(e.terminal.commitLive(),t={activeLiveContentKind:null,lastPrintedBlockKind:`content`}),t.lastPrintedBlockKind!==null&&t.lastPrintedBlockKind!==e.kind&&e.terminal.print(``),e.terminal.print(e.line),{activeLiveContentKind:null,lastPrintedBlockKind:e.kind}}function renderTurnEvent(e){let t=formatContentEvent(e.theme,e.event,e.options);if(t!==void 0){let n=e.state;return n.activeLiveContentKind!==null&&n.activeLiveContentKind!==t.kind&&(e.terminal.commitLive(),n={activeLiveContentKind:null,lastPrintedBlockKind:`content`}),n.lastPrintedBlockKind!==null&&n.lastPrintedBlockKind!==`content`&&e.terminal.print(``),e.terminal.updateLive(t.line),t.finalized?(e.terminal.commitLive(),{activeLiveContentKind:null,lastPrintedBlockKind:`content`}):{activeLiveContentKind:t.kind,lastPrintedBlockKind:`content`}}let n=formatEvent(e.theme,e.event,e.options);return n===void 0?e.state:printDisplayLine({kind:getEventDisplayBlockKind(e.event),line:n,state:e.state,terminal:e.terminal})}function isAbortLikeError(e){return(e instanceof DOMException||e instanceof Error)&&e.name===`AbortError`}function shouldDrainSubagentStreamsOnBoundary(e){return e.length===0}var ReplSubagentStreamManager=class{#e=new Map;#t;#n;#r;#i;constructor(e){this.#t=e.displayStateRef,this.#n=e.serverUrl,this.#r=e.terminal,this.#i=e.theme}subscribe(e){if(this.#e.has(e.sessionId))return;let t=new AbortController,n=this.#a({controller:t,sessionId:e.sessionId,subagentName:e.subagentName}).finally(()=>{this.#e.delete(e.sessionId)});this.#e.set(e.sessionId,{controller:t,done:n,label:e.subagentName})}async waitForIdle(){for(;this.#e.size>0;)await Promise.all([...this.#e.values()].map(e=>e.done))}async close(){let e=[...this.#e.values()];for(let t of e)t.controller.abort();await Promise.allSettled(e.map(e=>e.done))}async#a(e){let t=resolveDevelopmentServerResourceUrl({resource:createAshMessageStreamRoutePath(e.sessionId),serverUrl:this.#n});try{for await(let n of openStreamIterable({host:this.#n,maxReconnectAttempts:3,resolveHeaders:async()=>await createDevelopmentRequestHeadersAsync({resourceUrl:t}),sessionId:e.sessionId,signal:e.controller.signal,startIndex:0}))if(this.#t.current=renderTurnEvent({event:n,options:{isSubagent:!0,sourceLabel:e.subagentName},state:this.#t.current,terminal:this.#r,theme:this.#i}),n.type===`subagent.called`&&this.subscribe({sessionId:n.data.childSessionId,subagentName:n.data.name}),isCurrentTurnBoundaryEvent(n))return}catch(t){if(isAbortLikeError(t))return;let n=toErrorMessage(t);this.#t.current=printDisplayLine({kind:`meta`,line:renderCliTaggedLine(this.#i,{message:`${e.subagentName} stream failed: ${n}`,tag:`subagent`,tone:`danger`}),state:this.#t.current,terminal:this.#r})}finally{e.controller.abort()}}};function formatActionResultLabel(e){switch(e.kind){case`load-skill-result`:return e.kind;case`subagent-result`:return`${e.kind}:${e.subagentName}`;case`tool-result`:return`${e.kind}:${e.toolName}`}}function formatAuthorizationChallengeSuffix(e){if(e===void 0)return``;let t=[];return e.url!==void 0&&t.push(e.url),e.userCode!==void 0&&t.push(`code ${e.userCode}`),e.instructions!==void 0&&t.push(e.instructions),t.length===0?``:` — ${t.join(`, `)}`}function formatNestedSubagentEventLabel(e){switch(e.type){case`actions.requested`:{let t=e.data.actions,n=t.map(e=>e.kind===`tool-call`?e.toolName:e.kind).join(`,`);return`${e.type} (${t.length} action${t.length===1?``:`s`}${n.length>0?`: ${n}`:``})`}case`action.result`:return`${e.type} (${formatActionResultLabel(e.data.result)})`;case`input.requested`:return`${e.type} (${e.data.requests.length} request${e.data.requests.length===1?``:`s`})`;default:return e.type}}function formatDispatch(e,t){return t.continuationToken?renderCliTaggedLine(e,{message:`resuming session ${t.continuationToken}`,tag:`session`,tone:`info`}):renderCliTaggedLine(e,{message:`starting a new session`,tag:`session`,tone:`info`})}function formatTurnDispatch(e,t){return t.turn.inputResponses!==void 0&&t.turn.message===void 0?renderCliTaggedLine(e,{message:`responding to pending input request${t.turn.inputResponses.length===1?``:`s`}`,tag:`session`,tone:`info`}):formatDispatch(e,t.session)}function formatSessionBoundary(e,t){let n=extractCurrentTurnBoundaryEvent(t),r=extractPendingRuntimeInputRequests(t);switch(n?.type){case`session.waiting`:return[renderCliTaggedLine(e,{message:r.length>0?`waiting for input approval/answer or the next message`:`waiting for the next message`,tag:`session`,tone:`success`})];case`session.completed`:return[renderCliTaggedLine(e,{message:`session completed; the next input starts a new session`,tag:`session`,tone:`success`})];case`session.failed`:{let t=n.data.details&&typeof n.data.details.name==`string`?n.data.details.name:void 0;return[renderCliTaggedLine(e,{message:t?`session failed (${t}): ${n.data.message}`:`session failed: ${n.data.message}`,tag:`session`,tone:`danger`}),renderCliTaggedLine(e,{message:`cleared; the next input starts a new session`,tag:`session`,tone:`warning`})]}default:return[]}}async function waitForInputLine(e,t,n={}){return await new Promise(r=>{let i=e.input,cleanup=()=>{e.off(`close`,handleClose),e.off(`line`,handleLine),i.off(`keypress`,handleKeypress)},handleClose=()=>{cleanup(),r(void 0)},handleLine=e=>{cleanup(),r(e)},handleKeypress=(t,i)=>{n.allowEscape!==!0||i.name!==`escape`||(cleanup(),e.write(null,{ctrl:!0,name:`u`}),r(ESCAPED_RUNTIME_INPUT_PROMPT))};e.setPrompt(t),e.once(`close`,handleClose),e.once(`line`,handleLine),n.allowEscape&&(emitKeypressEvents(i,e),i.on(`keypress`,handleKeypress)),e.prompt()})}async function runTurn(e){let t=e.turn,n={current:createTurnDisplayState()},i=new ReplSubagentStreamManager({displayStateRef:n,serverUrl:e.serverUrl,terminal:e.terminal,theme:e.theme}),ask=async t=>{e.terminal.startPrompt(e.rl,t);let n=await waitForInputLine(e.rl,t,{allowEscape:!0});return e.terminal.stopPrompt(),n};try{for(;;){let a=e.client.getSession();n.current=printDisplayLine({kind:`meta`,line:formatTurnDispatch(e.theme,{session:a,turn:t}),state:n.current,terminal:e.terminal});let o=await e.client.send({inputResponses:t.inputResponses,message:t.message,onEvent(t){n.current=renderTurnEvent({event:t,state:n.current,terminal:e.terminal,theme:e.theme}),t.type===`subagent.called`&&i.subscribe({sessionId:t.data.childSessionId,subagentName:t.data.name})},onResponseStart(t){t.sessionId&&a.sessionId!==t.sessionId&&(n.current=printDisplayLine({kind:`meta`,line:renderCliTaggedLine(e.theme,{message:t.sessionId,tag:`session`,tone:`accent`}),state:n.current,terminal:e.terminal}),n.current=printDisplayLine({kind:`meta`,line:renderCliTaggedLine(e.theme,{message:resolveDevelopmentServerResourceUrl({resource:createAshMessageStreamRoutePath(t.sessionId),serverUrl:e.serverUrl}).toString(),tag:`stream`,tone:`info`}),state:n.current,terminal:e.terminal}))}}),s=extractPendingRuntimeInputRequests(o.events);if(shouldDrainSubagentStreamsOnBoundary(s)){await i.waitForIdle();for(let t of formatSessionBoundary(e.theme,o.events))n.current=printDisplayLine({kind:`meta`,line:t,state:n.current,terminal:e.terminal});return`continue`}let c=await promptForRuntimeInputRequests({ask,print(t){n.current=printDisplayLine({kind:`meta`,line:t,state:n.current,terminal:e.terminal})},requests:s,theme:e.theme});if(c.kind===`aborted`)return`exit`;if(c.kind===`deferred`)return n.current=printDisplayLine({kind:`meta`,line:renderCliTaggedLine(e.theme,{message:`left pending input requests unresolved; send a new message to ignore them`,tag:`session`,tone:`warning`}),state:n.current,terminal:e.terminal}),`continue`;t={inputResponses:c.inputResponses}}}finally{await i.close()}}async function runDevelopmentRepl(e){let t=createDevelopmentTerminal(),n=createCliTheme({color:!0}),r=createInterface({input:process.stdin,output:t.output,terminal:!0});r.on(`SIGINT`,()=>{r.close()});let a=createDevClient({serverUrl:e.serverUrl});try{for(t.print(renderIntro(n,e)),t.print(``);;){t.print(``),t.startPrompt(r,`you> `);let i=await waitForInputLine(r,`you> `);if(t.stopPrompt(),i===void 0)return;let o=parseDevReplInput(i);switch(o.kind!==`empty`&&o.kind!==`exit`&&t.print(``),o.kind){case`empty`:continue;case`help`:t.print(renderIntro(n,e)),t.print(``);continue;case`exit`:return;case`new`:await a.clear(),t.print(renderCliTaggedLine(n,{message:`cleared; the next input starts a new session`,tag:`session`,tone:`warning`})),t.print(``);continue;case`message`:try{if(await runTurn({client:a,rl:r,serverUrl:e.serverUrl,terminal:t,theme:n,turn:{message:o.message}})===`exit`)return}catch(r){isVercelAuthChallenge(r)?t.printError(renderCliTaggedLine(n,{message:formatVercelAuthChallengeMessage({serverUrl:e.serverUrl}),tag:`auth`,tone:`warning`})):t.printError(renderCliTaggedLine(n,{message:toErrorMessage(r),tag:`error`,tone:`danger`}))}t.print(``)}}}finally{await a.close(),r.close(),t.dispose()}}export{createTurnDisplayState,formatContentEvent,formatEvent,renderTurnEvent,runDevelopmentRepl,shouldDrainSubagentStreamsOnBoundary};

package/dist/src/cli/dev/tui/layout.d.ts

@@ -0,0 +1,24 @@
+export { sliceVisible, stripAnsi, visibleLength } from "./terminal-text.js";
+export type TUIScreenState = {
+    width: number;
+    height: number;
+    title: string;
+    rightTitle?: string;
+    body: string;
+    input: string;
+    inputActive: boolean;
+    inputCursorVisible?: boolean;
+    scrollOffset: number;
+    status?: string;
+};
+export type TUIScreenLinesState = Omit<TUIScreenState, "body"> & {
+    bodyLines: string[];
+};
+export type TUIScreenViewportState = Omit<TUIScreenLinesState, "bodyLines" | "scrollOffset"> & {
+    visibleBodyLines: string[];
+};
+export declare function renderScreen(state: TUIScreenState): string;
+export declare function renderScreenLines(state: TUIScreenLinesState): string;
+export declare function renderScreenViewport(state: TUIScreenViewportState): string;
+export declare function wrapText(input: string, width: number): string[];
+export declare function clampScrollOffset(scrollOffset: number, body: string, bodyHeight: number, width: number): number;

package/dist/src/cli/dev/tui/layout.js

@@ -0,0 +1,3 @@
+import{ansiPrefixPattern,codePointWidth,sliceVisible,stripAnsi,visibleLength}from"./terminal-text.js";import{renderMarkdown}from"./markdown.js";function renderScreen(e){let t=Math.max(20,e.width)-4,n=wrapText(renderMarkdown(e.body),t);return renderScreenLines({...e,bodyLines:n})}function renderScreenLines(e){let t=Math.max(8,e.height)-3-2,n=Math.max(0,e.bodyLines.length-t),r=Math.min(Math.max(0,e.scrollOffset),n),i=Math.max(0,e.bodyLines.length-t-r),a=e.bodyLines.slice(i,i+t);return renderScreenViewport({...e,visibleBodyLines:a})}function renderScreenViewport(e){let t=Math.max(20,e.width),n=Math.max(8,e.height)-3-2,r=e.visibleBodyLines.slice(0,n);for(;r.length<n;)r.push(``);return[topBorder(t,e.title,e.rightTitle),...r.map(e=>boxLine(e,t)),bottomBorder(t),topBorder(t,e.inputActive?`Input`:`Status`),boxLine(e.inputActive?`> ${e.input}${e.inputCursorVisible===!1?` `:`█`}`:e.status??`Streaming... ↑/↓ scroll · Ctrl+C quit`,t),bottomBorder(t)].join(`
+`)}function wrapText(e,t){if(t<=0)return[``];let n=[];for(let r of e.split(`
+`)){if(r.length===0){n.push(``);continue}let e=r;for(;visibleLength(e)>t;){let r=findBreakPoint(e,t);n.push(e.slice(0,r).trimEnd()),e=e.slice(r).trimStart()}n.push(e)}return n}function clampScrollOffset(e,t,n,r){let i=Math.max(1,n-2),o=wrapText(renderMarkdown(t),Math.max(1,r-4)),s=Math.max(0,o.length-i);return Math.min(Math.max(0,e),s)}function findBreakPoint(n,r){let i=0,a=0,o=-1;for(;i<n.length&&a<r;){let s=n.slice(i).match(ansiPrefixPattern);if(s){i+=s[0].length;continue}let c=n.codePointAt(i);if(c==null)break;let l=String.fromCodePoint(c),u=codePointWidth(c);if(u>0&&a+u>r)break;l===` `&&(o=i),i+=l.length,a+=u}let s=indexAfterAnsiSequences(n,i);return a===r&&n.codePointAt(s)===32?s:o>0?o:indexAtVisibleWidth(n,r)}function topBorder(e,t,r){let a=Math.max(0,e-2),o=sliceVisible(` ${t} `,a),s=r?sliceVisible(` ${r} `,Math.max(0,a-visibleLength(o))):``,c=Math.max(0,a-visibleLength(o)-visibleLength(s));return`┌${o}${`─`.repeat(c)}${s}┐`}function bottomBorder(e){return`└${`─`.repeat(e-2)}┘`}function boxLine(e,t){let r=t-4,a=sliceVisible(e,r);return`│ ${a}${` `.repeat(Math.max(0,r-visibleLength(a)))} │`}function indexAtVisibleWidth(n,r){let i=0,a=0;for(;i<n.length&&a<r;){let o=n.slice(i).match(ansiPrefixPattern);if(o){i+=o[0].length;continue}let s=n.codePointAt(i);if(s==null)break;let c=String.fromCodePoint(s),l=codePointWidth(s);if(l>0&&a+l>r)break;i+=c.length,a+=l}return i}function indexAfterAnsiSequences(t,n){let r=n;for(;r<t.length;){let n=t.slice(r).match(ansiPrefixPattern);if(!n)break;r+=n[0].length}return r}export{clampScrollOffset,renderScreen,renderScreenLines,renderScreenViewport,sliceVisible,stripAnsi,visibleLength,wrapText};

package/dist/src/cli/dev/tui/markdown.d.ts

@@ -0,0 +1,14 @@
+export type MarkdownToken = {
+    type: "text";
+    text: string;
+} | {
+    type: "bold";
+    text: string;
+} | {
+    type: "italic";
+    text: string;
+} | {
+    type: "code";
+    text: string;
+};
+export declare function renderMarkdown(input: string): string;

package/dist/src/cli/dev/tui/markdown.js

@@ -0,0 +1,3 @@
+import{visibleLength}from"./terminal-text.js";const ansi={bold:`\x1B[1m`,boldOff:`\x1B[22m`,italic:`\x1B[3m`,italicOff:`\x1B[23m`};function renderMarkdown(e){let t=e.split(`
+`),n=[];for(let e=0;e<t.length;e+=1){let r=parseTable(t,e);if(r!=null){n.push(...renderTable(r)),e=r.endIndex-1;continue}n.push(renderMarkdownLine(t[e]??``))}return n.join(`
+`)}function renderMarkdownLine(e){if(e.startsWith(`### `))return renderInlineMarkdown(`▶ ${e.slice(4)}`);if(e.startsWith(`## `))return renderInlineMarkdown(`■ ${e.slice(3)}`);if(e.startsWith(`# `))return renderInlineMarkdown(`█ ${e.slice(2)}`);let t=e.match(/^(\s*)[-+*]\s+(.*)$/);if(t){let[,e,n=``]=t;return renderInlineMarkdown(`${e}•${n.length>0?` ${n}`:``}`)}return/^\d+\. /.test(e)?renderInlineMarkdown(e.replace(/^(\d+)\. /,`$1. `)):e.startsWith(`> `)?renderInlineMarkdown(`│ ${e.slice(2)}`):renderInlineMarkdown(e)}function renderInlineMarkdown(e){return e.replaceAll(/`([^`]+)`/g,`$1`).replaceAll(/\*\*([^*\n]+)\*\*/g,`${ansi.bold}$1${ansi.boldOff}`).replaceAll(/__([^_\n]+)__/g,`${ansi.bold}$1${ansi.boldOff}`).replaceAll(/\*([^*\n]+)\*/g,`${ansi.italic}$1${ansi.italicOff}`).replaceAll(/_([^_\n]+)_/g,`${ansi.italic}$1${ansi.italicOff}`)}function parseTable(e,t){let n=parseTableCells(e[t]??``);if(n==null||n.length<2)return;let r=parseTableCells(e[t+1]??``);if(r==null||r.length!==n.length)return;let i=parseTableAlignments(r);if(i==null)return;let a=[],o=t+2;for(;o<e.length;){let t=parseTableCells(e[o]??``);if(t==null)break;a.push(normalizeTableRow(t,n.length)),o+=1}return{alignments:i,endIndex:o,header:n,rows:a}}function parseTableCells(e){if(!e.includes(`|`))return;let t=e.trim();t.startsWith(`|`)&&(t=t.slice(1)),t.endsWith(`|`)&&!t.endsWith(`\\|`)&&(t=t.slice(0,-1));let n=[],r=``;for(let e=0;e<t.length;e+=1){let i=t[e],a=t[e+1];if(i===`\\`&&a===`|`){r+=`|`,e+=1;continue}if(i===`|`){n.push(r.trim()),r=``;continue}r+=i}return n.push(r.trim()),n}function parseTableAlignments(e){let t=[];for(let n of e){let e=n.match(/^(:)?-{3,}(:)?$/);if(e==null)return;let[,r,i]=e;t.push(r!=null&&i!=null?`center`:i==null?`left`:`right`)}return t}function normalizeTableRow(e,t){return Array.from({length:t},(t,n)=>e[n]??``)}function renderTable(n){let r=n.header.map(e=>`${ansi.bold}${renderInlineMarkdown(e)}${ansi.boldOff}`),i=n.rows.map(e=>e.map(renderInlineMarkdown)),a=[r,...i],o=n.alignments.map((t,n)=>Math.max(3,...a.map(t=>visibleLength(t[n]??``))));return[formatTableRow(r,o,n.alignments),o.map(e=>`─`.repeat(e)).join(`  `),...i.map(e=>formatTableRow(e,o,n.alignments))]}function formatTableRow(e,t,n){return e.map((e,r)=>alignTableCell(e,t[r]??0,n[r]??`left`)).join(`  `)}function alignTableCell(t,n,r){let i=Math.max(0,n-visibleLength(t));if(r===`right`)return`${` `.repeat(i)}${t}`;if(r===`center`){let e=Math.floor(i/2),n=i-e;return`${` `.repeat(e)}${t}${` `.repeat(n)}`}return`${t}${` `.repeat(i)}`}export{renderMarkdown};

package/dist/src/cli/dev/tui/runner.d.ts

@@ -0,0 +1,205 @@
+import { type ConnectionAuthorizationOutcome, Client, ClientSession } from "#client/index.js";
+import { type UIMessage, type UIMessageChunk } from "ai";
+import type { AssistantResponseStatsMode, TerminalPartDisplayMode, TuiDisplayOptions } from "./types.js";
+import { type TerminalInput, type TerminalOutput } from "./terminal-renderer.js";
+export type AgentTUIStreamResult = {
+    uiMessageStream: AsyncIterable<UIMessageChunk> | ReadableStream<UIMessageChunk>;
+    message?: UIMessage;
+    abort?: () => void;
+};
+export type AgentTUIStreamOptions = {
+    messages: UIMessage[];
+};
+export type AgentTUISessionOptions = {
+    title?: string;
+    initialPrompt?: string;
+    submittedPrompt?: string;
+    waitForExit?: boolean;
+    continueSession?: boolean;
+    tools?: TerminalPartDisplayMode;
+    reasoning?: TerminalPartDisplayMode;
+    subagents?: TerminalPartDisplayMode;
+    connectionAuth?: TerminalPartDisplayMode;
+    assistantResponseStats?: AssistantResponseStatsMode;
+    contextSize?: number;
+};
+export type AgentTUIToolApprovalRequest = {
+    approvalId: string;
+    toolCallId: string;
+    toolName: string;
+    title?: string;
+    input: unknown;
+    providerExecuted?: boolean;
+    messageId: string;
+    partIndex: number;
+};
+export type AgentTUIToolApprovalResponse = {
+    approved: boolean;
+    reason?: string;
+};
+export type AgentTUIInputOption = {
+    id: string;
+    label: string;
+    description?: string;
+    style?: "primary" | "danger" | "default";
+};
+export type AgentTUIInputQuestion = {
+    requestId: string;
+    prompt: string;
+    display: "select" | "text";
+    options?: ReadonlyArray<AgentTUIInputOption>;
+    allowFreeform?: boolean;
+};
+export type AgentTUIInputQuestionResponse = {
+    optionId?: string;
+    text?: string;
+};
+export type AgentTUIRenderer = {
+    readPrompt?(options?: AgentTUISessionOptions): Promise<string | undefined>;
+    readToolApproval?(request: AgentTUIToolApprovalRequest, options?: AgentTUISessionOptions): Promise<AgentTUIToolApprovalResponse>;
+    readInputQuestion?(question: AgentTUIInputQuestion, options?: AgentTUISessionOptions): Promise<AgentTUIInputQuestionResponse | undefined>;
+    renderStream(result: AgentTUIStreamResult, options?: AgentTUISessionOptions): Promise<UIMessage | undefined>;
+    /**
+     * Out-of-band update for one child step (reasoning + message text) of a
+     * subagent dispatch. Called by the runner as child-session stream events
+     * arrive. The renderer renders this as a body section colored by the
+     * subagent palette.
+     */
+    upsertSubagentStep?(update: SubagentStepUpdate): void;
+    /**
+     * Out-of-band update for one child tool call of a subagent dispatch.
+     */
+    upsertSubagentTool?(update: SubagentToolUpdate): void;
+    /**
+     * Registers a tool call id as originating from a subagent's child
+     * session. The renderer must skip rendering parent UIMessage tool parts
+     * for these ids — they are surfaced via {@link upsertSubagentTool}
+     * instead.
+     */
+    markChildToolCallId?(callId: string): void;
+    /**
+     * Out-of-band update for one MCP connection authorization lifecycle.
+     * Called by the runner as `authorization.*` events arrive.
+     * The renderer renders this as a persistent body section per
+     * connection that transitions through `required` → `pending` →
+     * one of the terminal `ConnectionAuthorizationOutcome` states.
+     */
+    upsertConnectionAuth?(update: ConnectionAuthUpdate): void;
+    /**
+     * Sets the number of connections currently awaiting an OAuth
+     * callback. The renderer overrides its bottom status bar with a
+     * "waiting for connection authorization" hint while this is > 0,
+     * so the user understands the agent is parked, not hung.
+     */
+    setConnectionAuthPendingCount?(count: number): void;
+    /**
+     * Clears the rendered transcript and resets per-conversation display
+     * state, leaving the UI interactive on a fresh screen. Used by the
+     * `/new` command to start a new session with a clean slate.
+     */
+    reset?(): void;
+    /**
+     * Tears down interactive mode and restores the terminal, as if the user
+     * pressed Ctrl+C. Used by the `/exit` command.
+     */
+    shutdown?(): void;
+};
+export type AshTUIRunnerOptions = TuiDisplayOptions & {
+    session: ClientSession;
+    /**
+     * Optional client used to attach to child sessions for live subagent
+     * stream observation. When omitted, the TUI still shows the subagent
+     * section but cannot surface the subagent's reasoning / response /
+     * intermediate events — only the parent-stream `called` and
+     * `completed` transitions.
+     */
+    client?: Client;
+    renderer?: AgentTUIRenderer;
+    screen?: TerminalOutput;
+    userInput?: TerminalInput;
+    /**
+     * Formats an error thrown while dispatching a turn (the initial
+     * `session.send()` POST — e.g. a transport failure or a Vercel
+     * Deployment Protection challenge) into the text rendered in the
+     * inline error region. Defaults to the error's message. Callers that
+     * know about transport-specific challenges (the `ash dev` glue) inject
+     * a richer formatter here.
+     */
+    formatTransportError?: (error: unknown) => string;
+};
+export declare class AshTUIRunner {
+    #private;
+    constructor(options: AshTUIRunnerOptions);
+    run(): Promise<void>;
+}
+type ResponseMetadata = {
+    usage?: {
+        totalTokens?: number;
+        outputTokens?: number;
+    };
+};
+type SubagentChildStep = {
+    reasoning: string;
+    message: string;
+    finalized: boolean;
+};
+type SubagentToolState = {
+    toolName: string;
+    input: unknown;
+    status: "approval-requested" | "executing" | "done" | "failed";
+    output?: unknown;
+    errorText?: string;
+};
+export type SubagentRun = {
+    name: string;
+    /**
+     * One entry per logical "child message" — independent of the child's
+     * `stepIndex` field, which the harness can reuse across multiple
+     * assistant messages within a turn (e.g. a message before a tool call
+     * and another message after the tool result both arrive under
+     * `stepIndex: 0`). The key is a monotonic counter so each
+     * `message.completed` opens a new box on the next inbound delta.
+     */
+    steps: Map<number, SubagentChildStep>;
+    /**
+     * Section currently accepting reasoning/message deltas. `null` means
+     * the next delta opens a new section.
+     */
+    currentSectionKey: number | null;
+    /** Monotonic counter for new section keys. */
+    nextSectionKey: number;
+    tools: Map<string, SubagentToolState>;
+};
+export type SubagentStepUpdate = {
+    callId: string;
+    subagentName: string;
+    sectionKey: number;
+    reasoning: string;
+    message: string;
+    finalized: boolean;
+};
+export type SubagentToolUpdate = {
+    callId: string;
+    subagentName: string;
+    childCallId: string;
+    toolName: string;
+    input: unknown;
+    status: "approval-requested" | "executing" | "done" | "failed";
+    output?: unknown;
+    errorText?: string;
+};
+export type ConnectionAuthChallenge = {
+    url?: string;
+    userCode?: string;
+    expiresAt?: string;
+    instructions?: string;
+};
+export type ConnectionAuthState = "required" | "pending" | ConnectionAuthorizationOutcome;
+export type ConnectionAuthUpdate = {
+    name: string;
+    description: string;
+    state: ConnectionAuthState;
+    challenge?: ConnectionAuthChallenge;
+    reason?: string;
+};
+export type { ResponseMetadata as _ResponseMetadata };