@dreb/coding-agent 2.48.0 → 2.49.0

package/README.md

@@ -81,7 +81,7 @@ Or use a custom provider (corporate proxy, Bedrock, etc.) — see [Custom provid
 
 Then just talk to dreb. All 12 built-in tools are enabled by default: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, `wait`, and `ask_user`. Use `--tools` to restrict to a subset (e.g., `--tools read,grep,find,ls` for read-only). Three additional tools — `search`, `skill`, and `tasks_update` — are always active regardless of `--tools`. `suggest_next` is active by default but excluded when `--tools` is specified. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [packages](#packages).
 
-**Also available:** [`@dreb/telegram`](https://www.npmjs.com/package/@dreb/telegram) — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (`npm install -g @dreb/telegram`). [`@dreb/dashboard`](https://www.npmjs.com/package/@dreb/dashboard) — run `dreb dashboard` for a browser UI with fleet overview, full chat steering, inline provider/API failures with partial output preserved, sanitized raster tool images plus sent user uploads retained as bounded transcript previews by default, subagent observability, host file browser, curated appearance themes (per-browser light/dark), and Tailscale/rotating-code pairing (`npm install -g @dreb/dashboard`; see [docs/dashboard.md](docs/dashboard.md)). Tool images cross browser-facing transport as content-addressed references; browser-local Settings offers placeholders, bounded previews, or informed-opt-in originals, with size disclosure and confirmation above 1 MiB. Full-resolution HTML export remains self-contained. Compact SSE snapshots update live fleet cards without repeatedly fetching the cross-project inventory, and session drill-in hydrates state, messages, and background agents through one ordered snapshot request. Terminal provider failures show their reason on fleet cards, while transient failures clear terminal state when automatic retry begins and remain recorded inline on the failed attempt. Its top bar and persistent session header indicators report connecting, connected, retrying, resyncing, disconnected, or auth failed; bounded SSE replay plus an explicit snapshot barrier restores session state, tasks, and image references after a reload, restart, gap, backpressure disconnect, or stalled stream, while authenticated image routes recover bytes separately from authoritative transcripts.
+**Also available:** [`@dreb/telegram`](https://www.npmjs.com/package/@dreb/telegram) — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (`npm install -g @dreb/telegram`). [`@dreb/dashboard`](https://www.npmjs.com/package/@dreb/dashboard) — run `dreb dashboard` for a browser UI with fleet overview, full chat steering, inline provider/API failures with partial output preserved, sanitized raster tool images plus sent user uploads retained as bounded transcript previews by default, a bounded all-agent subagent panel with drill-in, host file browser, curated appearance themes (per-browser light/dark), and Tailscale/rotating-code pairing (`npm install -g @dreb/dashboard`; see [docs/dashboard.md](docs/dashboard.md)). Tool images cross browser-facing transport as content-addressed references; browser-local Settings offers placeholders, bounded previews, or informed-opt-in originals, with size disclosure and confirmation above 1 MiB. Full-resolution HTML export remains self-contained. Compact SSE snapshots update live fleet cards without repeatedly fetching the cross-project inventory, and session drill-in hydrates state, messages, and background agents through one ordered snapshot request. Terminal provider failures show their reason on fleet cards, while transient failures clear terminal state when automatic retry begins and remain recorded inline on the failed attempt. Its top bar and persistent session header indicators report connecting, connected, retrying, resyncing, disconnected, or auth failed; bounded SSE replay plus an explicit snapshot barrier restores session state, tasks, and image references after a reload, restart, gap, backpressure disconnect, or stalled stream, while authenticated image routes recover bytes separately from authoritative transcripts.
 
 **Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 

package/dist/core/tools/ask-user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../../../src/core/tools/ask-user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAA2C,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAKtG,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD,QAAA,MAAM,aAAa;;;;;;;;EAwCjB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AA0FxD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,cAAc,CAAC,OAAO,aAAa,EAAE,cAAc,GAAG,SAAS,CAAC,CA+F9G","sourcesContent":["/**\n * ask_user tool.\n *\n * Lets the agent pause and ask the user a structured clarifying question —\n * with optional multiple-choice options, single- or multi-select, and a\n * \"type your own answer\" free-text field — rendered natively in the TUI, the\n * Dashboard, and over RPC. Answering, stopping the turn, aborting, or timing\n * out always settles cleanly so the agent never deadlocks on an absent user.\n *\n * Concurrent calls are serialized through a per-session FIFO queue: only one\n * question is ever shown at a time, and a queued call whose signal aborts\n * settles without opening any UI.\n */\n\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport type { AskRequest, AskResult, ExtensionContext, ToolDefinition } from \"../extensions/types.js\";\n\n// ============================================================================\n// Types\n\nexport interface AskUserDetails {\n\tquestion: string;\n\ttitle?: string;\n\tselected: string[];\n\tcustomText?: string;\n\t/** True when the question closed without an answer. */\n\tskipped: boolean;\n\t/** True when no interactive UI was available (headless/print mode). */\n\tunavailable: boolean;\n\t/** True when the UI host or response protocol failed. */\n\tfailed?: boolean;\n}\n\n// ============================================================================\n// Schema\n\nconst askUserSchema = Type.Object({\n\tquestion: Type.String({\n\t\tdescription: \"The Markdown-formatted question to ask the user. Be specific about what you need to decide.\",\n\t}),\n\ttitle: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Short bold header shown above the question.\",\n\t\t}),\n\t),\n\toptions: Type.Optional(\n\t\tType.Array(Type.String({ minLength: 1, pattern: \"\\\\S\" }), {\n\t\t\tminItems: 2,\n\t\t\tmaxItems: 4,\n\t\t\tdescription: \"2-4 nonblank suggested answers the user can pick from.\",\n\t\t}),\n\t),\n\tallowFreeText: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Offer a 'type your own answer' field. Defaults to true.\",\n\t\t}),\n\t),\n\tmultiSelect: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Allow selecting multiple options (checkboxes). Only meaningful with options.\",\n\t\t}),\n\t),\n\tmultiline: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Use a large multi-line text area for open-ended answers.\",\n\t\t}),\n\t),\n\ttimeoutSeconds: Type.Optional(\n\t\tType.Number({\n\t\t\tminimum: 5,\n\t\t\tmaximum: 3600,\n\t\t\tdescription:\n\t\t\t\t\"Optional: stop the current agent turn after this many seconds if the user does not respond. \" +\n\t\t\t\t\"Shows a live countdown. Omit to wait indefinitely.\",\n\t\t}),\n\t),\n});\n\nexport type AskUserInput = Static<typeof askUserSchema>;\n\n// ============================================================================\n// Result helpers\n\nfunction textResult(text: string, details: AskUserDetails) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text }],\n\t\tdetails,\n\t};\n}\n\nfunction baseDetails(input: AskUserInput): Omit<AskUserDetails, \"selected\" | \"skipped\" | \"unavailable\"> {\n\treturn { question: input.question, title: input.title };\n}\n\nfunction unavailableResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The ask_user tool requires an interactive UI, which is not available in this mode. \" +\n\t\t\t\"Proceed using your best judgment without waiting for an answer.\",\n\t\t{ ...baseDetails(input), selected: [], skipped: true, unavailable: true },\n\t);\n}\n\nfunction unansweredResult(input: AskUserInput) {\n\treturn textResult(\"The question closed without an answer.\", {\n\t\t...baseDetails(input),\n\t\tselected: [],\n\t\tskipped: true,\n\t\tunavailable: false,\n\t});\n}\n\nfunction failedResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The question could not be delivered because the interactive UI or response protocol failed. \" +\n\t\t\t\"Continue without this input.\",\n\t\t{\n\t\t\t...baseDetails(input),\n\t\t\tselected: [],\n\t\t\tskipped: false,\n\t\t\tunavailable: false,\n\t\t\tfailed: true,\n\t\t},\n\t);\n}\n\nfunction answeredResult(input: AskUserInput, answer: AskResult) {\n\tconst customText = answer.customText?.trim() || undefined;\n\tconst selected = answer.selected;\n\tconst parts: string[] = [];\n\tif (selected.length > 0) {\n\t\tparts.push(\n\t\t\tselected.length === 1 ? `The user selected: ${selected[0]}` : `The user selected: ${selected.join(\", \")}`,\n\t\t);\n\t}\n\tif (customText) {\n\t\tparts.push(selected.length > 0 ? `They also wrote: \"${customText}\"` : `The user answered: \"${customText}\"`);\n\t}\n\treturn textResult(parts.join(\" \"), {\n\t\t...baseDetails(input),\n\t\tselected,\n\t\tcustomText,\n\t\tskipped: false,\n\t\tunavailable: false,\n\t});\n}\n\n// ============================================================================\n// Render helpers\n\nfunction formatCall(args: { question?: string; title?: string } | undefined, theme: any): string {\n\tconst label = (args?.title || args?.question || \"\").replace(/\\s+/g, \" \").trim();\n\tconst shown = label.length > 80 ? `${label.slice(0, 79)}…` : label;\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"ask_user\"))} ${theme.fg(\"accent\", shown)}`;\n}\n\nfunction formatResult(details: AskUserDetails, theme: any): string {\n\tif (details.unavailable) return theme.fg(\"toolOutput\", \"no interactive UI — continued without asking\");\n\tif (details.failed) return theme.fg(\"toolOutput\", \"interactive UI failed — continued without an answer\");\n\tif (details.skipped) return theme.fg(\"toolOutput\", \"question closed without an answer\");\n\tconst parts: string[] = [];\n\tif (details.selected.length > 0) parts.push(details.selected.join(\", \"));\n\tif (details.customText) parts.push(`\"${details.customText}\"`);\n\treturn theme.fg(\"toolOutput\", `→ ${parts.join(\" + \")}`);\n}\n\n// ============================================================================\n// Tool definition factory\n\n/**\n * Create an `ask_user` tool definition. Each call creates an isolated FIFO\n * queue, so concurrent `ask_user` calls in a single session are shown strictly\n * one at a time.\n */\nexport function createAskUserToolDefinition(): ToolDefinition<typeof askUserSchema, AskUserDetails | undefined> {\n\t// Per-session serialization: only one question is ever open at a time.\n\tlet tail: Promise<void> = Promise.resolve();\n\tconst serialize = <T>(run: () => Promise<T>): Promise<T> => {\n\t\tconst result = tail.then(run, run);\n\t\t// Always advance the queue, whether the call resolved, cancelled, timed\n\t\t// out, or threw — so a failure can never wedge later questions.\n\t\ttail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t};\n\n\treturn {\n\t\tname: \"ask_user\",\n\t\tlabel: \"ask_user\",\n\t\tdescription:\n\t\t\t\"Pause and ask the user a structured clarifying question with optional multiple-choice options and a \" +\n\t\t\t\"free-text answer. Use only when genuinely blocked by ambiguity with multiple viable paths — not for routine confirmation.\",\n\n\t\tparameters: askUserSchema,\n\n\t\tpromptSnippet: \"Ask the user a clarifying question with optional multiple-choice options and free text\",\n\n\t\tpromptGuidelines: [\n\t\t\t\"Call ask_user ONLY when you are genuinely blocked by ambiguity and there are multiple viable paths forward\",\n\t\t\t\"Do NOT use it for routine confirmation, permission, or things you can reasonably decide yourself\",\n\t\t\t\"Provide 2-4 concrete `options` when there are clear candidate answers; the user can always type their own\",\n\t\t\t\"Set `multiSelect: true` when several options can be combined; `multiline: true` for open-ended answers\",\n\t\t\t\"The user may stop the current turn instead of answering; never treat that as an answer\",\n\t\t\t\"Prefer one focused question over many; the question blocks the turn until the user responds or stops it\",\n\t\t],\n\n\t\tasync execute(_toolCallId, input: AskUserInput, signal, _onUpdate, ctx?: ExtensionContext) {\n\t\t\tconst hasOptions = (input.options?.length ?? 0) > 0;\n\t\t\tconst request: AskRequest = {\n\t\t\t\tquestion: input.question,\n\t\t\t\ttitle: input.title,\n\t\t\t\toptions: input.options,\n\t\t\t\t// Guarantee at least one answer control: with no options, free text\n\t\t\t\t// must be offered regardless of the requested flag, otherwise both\n\t\t\t\t// surfaces would render only a Skip button and no way to answer.\n\t\t\t\tallowFreeText: hasOptions ? input.allowFreeText : true,\n\t\t\t\t// multiSelect is only meaningful with options; multiline only with\n\t\t\t\t// free text — normalize away impossible combinations.\n\t\t\t\tmultiSelect: hasOptions ? input.multiSelect : undefined,\n\t\t\t\tmultiline: hasOptions ? (input.allowFreeText === false ? undefined : input.multiline) : input.multiline,\n\t\t\t};\n\n\t\t\t// Optional auto-stop timeout, forwarded to every UI surface (TUI\n\t\t\t// countdown, RPC/Dashboard). Model-facing units are seconds.\n\t\t\tconst timeout = input.timeoutSeconds && input.timeoutSeconds > 0 ? input.timeoutSeconds * 1000 : undefined;\n\n\t\t\t// Headless / print / no-host modes: never block on an unreachable UI.\n\t\t\tif (!ctx?.hasUI) {\n\t\t\t\treturn unavailableResult(input);\n\t\t\t}\n\n\t\t\treturn serialize(async () => {\n\t\t\t\t// A queued call whose signal already aborted settles without ever\n\t\t\t\t// opening the UI; the parent turn is already stopping.\n\t\t\t\tif (signal?.aborted) return unansweredResult(input);\n\t\t\t\ttry {\n\t\t\t\t\tconst answer = await ctx.ui.ask(request, { signal, timeout });\n\t\t\t\t\tif (!answer || (answer.selected.length === 0 && !answer.customText?.trim())) {\n\t\t\t\t\t\treturn unansweredResult(input);\n\t\t\t\t\t}\n\t\t\t\t\treturn answeredResult(input, answer);\n\t\t\t\t} catch {\n\t\t\t\t\t// Host/protocol failure must still release the queue and never\n\t\t\t\t\t// deadlock, but it must not masquerade as an intentional user skip.\n\t\t\t\t\treturn failedResult(input);\n\t\t\t\t}\n\t\t\t});\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\ttext.setText(formatCall(args, theme));\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, _options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\tconst details = (result as any).details as AskUserDetails | undefined;\n\t\t\tif (details) {\n\t\t\t\ttext.setText(formatResult(details, theme));\n\t\t\t} else {\n\t\t\t\tconst content = result.content?.[0];\n\t\t\t\ttext.setText(theme.fg(\"toolOutput\", content?.type === \"text\" ? content.text : \"\"));\n\t\t\t}\n\t\t\treturn text;\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../../../src/core/tools/ask-user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAA2C,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAKtG,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD,QAAA,MAAM,aAAa;;;;;;;;EAwCjB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AA0FxD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,cAAc,CAAC,OAAO,aAAa,EAAE,cAAc,GAAG,SAAS,CAAC,CA+F9G","sourcesContent":["/**\n * ask_user tool.\n *\n * Lets the agent pause and ask the user a structured clarifying question —\n * with optional multiple-choice options, single- or multi-select, and a\n * \"type your own answer\" free-text field — rendered natively in the TUI, the\n * Dashboard, and over RPC. Answering, stopping the turn, aborting, or timing\n * out always settles cleanly so the agent never deadlocks on an absent user.\n *\n * Concurrent calls are serialized through a per-session FIFO queue: only one\n * question is ever shown at a time, and a queued call whose signal aborts\n * settles without opening any UI.\n */\n\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport type { AskRequest, AskResult, ExtensionContext, ToolDefinition } from \"../extensions/types.js\";\n\n// ============================================================================\n// Types\n\nexport interface AskUserDetails {\n\tquestion: string;\n\ttitle?: string;\n\tselected: string[];\n\tcustomText?: string;\n\t/** True when the question closed without an answer. */\n\tskipped: boolean;\n\t/** True when no interactive UI was available (headless/print mode). */\n\tunavailable: boolean;\n\t/** True when the UI host or response protocol failed. */\n\tfailed?: boolean;\n}\n\n// ============================================================================\n// Schema\n\nconst askUserSchema = Type.Object({\n\tquestion: Type.String({\n\t\tdescription: \"The Markdown-formatted question to ask the user. Be specific about what you need to decide.\",\n\t}),\n\ttitle: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Short bold header shown above the question.\",\n\t\t}),\n\t),\n\toptions: Type.Optional(\n\t\tType.Array(Type.String({ minLength: 1, pattern: \"^.*[^ \\\\t\\\\r\\\\n].*$\" }), {\n\t\t\tminItems: 2,\n\t\t\tmaxItems: 4,\n\t\t\tdescription: \"2-4 nonblank suggested answers the user can pick from.\",\n\t\t}),\n\t),\n\tallowFreeText: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Offer a 'type your own answer' field. Defaults to true.\",\n\t\t}),\n\t),\n\tmultiSelect: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Allow selecting multiple options (checkboxes). Only meaningful with options.\",\n\t\t}),\n\t),\n\tmultiline: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Use a large multi-line text area for open-ended answers.\",\n\t\t}),\n\t),\n\ttimeoutSeconds: Type.Optional(\n\t\tType.Number({\n\t\t\tminimum: 5,\n\t\t\tmaximum: 3600,\n\t\t\tdescription:\n\t\t\t\t\"Optional: stop the current agent turn after this many seconds if the user does not respond. \" +\n\t\t\t\t\"Shows a live countdown. Omit to wait indefinitely.\",\n\t\t}),\n\t),\n});\n\nexport type AskUserInput = Static<typeof askUserSchema>;\n\n// ============================================================================\n// Result helpers\n\nfunction textResult(text: string, details: AskUserDetails) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text }],\n\t\tdetails,\n\t};\n}\n\nfunction baseDetails(input: AskUserInput): Omit<AskUserDetails, \"selected\" | \"skipped\" | \"unavailable\"> {\n\treturn { question: input.question, title: input.title };\n}\n\nfunction unavailableResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The ask_user tool requires an interactive UI, which is not available in this mode. \" +\n\t\t\t\"Proceed using your best judgment without waiting for an answer.\",\n\t\t{ ...baseDetails(input), selected: [], skipped: true, unavailable: true },\n\t);\n}\n\nfunction unansweredResult(input: AskUserInput) {\n\treturn textResult(\"The question closed without an answer.\", {\n\t\t...baseDetails(input),\n\t\tselected: [],\n\t\tskipped: true,\n\t\tunavailable: false,\n\t});\n}\n\nfunction failedResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The question could not be delivered because the interactive UI or response protocol failed. \" +\n\t\t\t\"Continue without this input.\",\n\t\t{\n\t\t\t...baseDetails(input),\n\t\t\tselected: [],\n\t\t\tskipped: false,\n\t\t\tunavailable: false,\n\t\t\tfailed: true,\n\t\t},\n\t);\n}\n\nfunction answeredResult(input: AskUserInput, answer: AskResult) {\n\tconst customText = answer.customText?.trim() || undefined;\n\tconst selected = answer.selected;\n\tconst parts: string[] = [];\n\tif (selected.length > 0) {\n\t\tparts.push(\n\t\t\tselected.length === 1 ? `The user selected: ${selected[0]}` : `The user selected: ${selected.join(\", \")}`,\n\t\t);\n\t}\n\tif (customText) {\n\t\tparts.push(selected.length > 0 ? `They also wrote: \"${customText}\"` : `The user answered: \"${customText}\"`);\n\t}\n\treturn textResult(parts.join(\" \"), {\n\t\t...baseDetails(input),\n\t\tselected,\n\t\tcustomText,\n\t\tskipped: false,\n\t\tunavailable: false,\n\t});\n}\n\n// ============================================================================\n// Render helpers\n\nfunction formatCall(args: { question?: string; title?: string } | undefined, theme: any): string {\n\tconst label = (args?.title || args?.question || \"\").replace(/\\s+/g, \" \").trim();\n\tconst shown = label.length > 80 ? `${label.slice(0, 79)}…` : label;\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"ask_user\"))} ${theme.fg(\"accent\", shown)}`;\n}\n\nfunction formatResult(details: AskUserDetails, theme: any): string {\n\tif (details.unavailable) return theme.fg(\"toolOutput\", \"no interactive UI — continued without asking\");\n\tif (details.failed) return theme.fg(\"toolOutput\", \"interactive UI failed — continued without an answer\");\n\tif (details.skipped) return theme.fg(\"toolOutput\", \"question closed without an answer\");\n\tconst parts: string[] = [];\n\tif (details.selected.length > 0) parts.push(details.selected.join(\", \"));\n\tif (details.customText) parts.push(`\"${details.customText}\"`);\n\treturn theme.fg(\"toolOutput\", `→ ${parts.join(\" + \")}`);\n}\n\n// ============================================================================\n// Tool definition factory\n\n/**\n * Create an `ask_user` tool definition. Each call creates an isolated FIFO\n * queue, so concurrent `ask_user` calls in a single session are shown strictly\n * one at a time.\n */\nexport function createAskUserToolDefinition(): ToolDefinition<typeof askUserSchema, AskUserDetails | undefined> {\n\t// Per-session serialization: only one question is ever open at a time.\n\tlet tail: Promise<void> = Promise.resolve();\n\tconst serialize = <T>(run: () => Promise<T>): Promise<T> => {\n\t\tconst result = tail.then(run, run);\n\t\t// Always advance the queue, whether the call resolved, cancelled, timed\n\t\t// out, or threw — so a failure can never wedge later questions.\n\t\ttail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t};\n\n\treturn {\n\t\tname: \"ask_user\",\n\t\tlabel: \"ask_user\",\n\t\tdescription:\n\t\t\t\"Pause and ask the user a structured clarifying question with optional multiple-choice options and a \" +\n\t\t\t\"free-text answer. Use only when genuinely blocked by ambiguity with multiple viable paths — not for routine confirmation.\",\n\n\t\tparameters: askUserSchema,\n\n\t\tpromptSnippet: \"Ask the user a clarifying question with optional multiple-choice options and free text\",\n\n\t\tpromptGuidelines: [\n\t\t\t\"Call ask_user ONLY when you are genuinely blocked by ambiguity and there are multiple viable paths forward\",\n\t\t\t\"Do NOT use it for routine confirmation, permission, or things you can reasonably decide yourself\",\n\t\t\t\"Provide 2-4 concrete `options` when there are clear candidate answers; the user can always type their own\",\n\t\t\t\"Set `multiSelect: true` when several options can be combined; `multiline: true` for open-ended answers\",\n\t\t\t\"The user may stop the current turn instead of answering; never treat that as an answer\",\n\t\t\t\"Prefer one focused question over many; the question blocks the turn until the user responds or stops it\",\n\t\t],\n\n\t\tasync execute(_toolCallId, input: AskUserInput, signal, _onUpdate, ctx?: ExtensionContext) {\n\t\t\tconst hasOptions = (input.options?.length ?? 0) > 0;\n\t\t\tconst request: AskRequest = {\n\t\t\t\tquestion: input.question,\n\t\t\t\ttitle: input.title,\n\t\t\t\toptions: input.options,\n\t\t\t\t// Guarantee at least one answer control: with no options, free text\n\t\t\t\t// must be offered regardless of the requested flag, otherwise both\n\t\t\t\t// surfaces would render only a Skip button and no way to answer.\n\t\t\t\tallowFreeText: hasOptions ? input.allowFreeText : true,\n\t\t\t\t// multiSelect is only meaningful with options; multiline only with\n\t\t\t\t// free text — normalize away impossible combinations.\n\t\t\t\tmultiSelect: hasOptions ? input.multiSelect : undefined,\n\t\t\t\tmultiline: hasOptions ? (input.allowFreeText === false ? undefined : input.multiline) : input.multiline,\n\t\t\t};\n\n\t\t\t// Optional auto-stop timeout, forwarded to every UI surface (TUI\n\t\t\t// countdown, RPC/Dashboard). Model-facing units are seconds.\n\t\t\tconst timeout = input.timeoutSeconds && input.timeoutSeconds > 0 ? input.timeoutSeconds * 1000 : undefined;\n\n\t\t\t// Headless / print / no-host modes: never block on an unreachable UI.\n\t\t\tif (!ctx?.hasUI) {\n\t\t\t\treturn unavailableResult(input);\n\t\t\t}\n\n\t\t\treturn serialize(async () => {\n\t\t\t\t// A queued call whose signal already aborted settles without ever\n\t\t\t\t// opening the UI; the parent turn is already stopping.\n\t\t\t\tif (signal?.aborted) return unansweredResult(input);\n\t\t\t\ttry {\n\t\t\t\t\tconst answer = await ctx.ui.ask(request, { signal, timeout });\n\t\t\t\t\tif (!answer || (answer.selected.length === 0 && !answer.customText?.trim())) {\n\t\t\t\t\t\treturn unansweredResult(input);\n\t\t\t\t\t}\n\t\t\t\t\treturn answeredResult(input, answer);\n\t\t\t\t} catch {\n\t\t\t\t\t// Host/protocol failure must still release the queue and never\n\t\t\t\t\t// deadlock, but it must not masquerade as an intentional user skip.\n\t\t\t\t\treturn failedResult(input);\n\t\t\t\t}\n\t\t\t});\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\ttext.setText(formatCall(args, theme));\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, _options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\tconst details = (result as any).details as AskUserDetails | undefined;\n\t\t\tif (details) {\n\t\t\t\ttext.setText(formatResult(details, theme));\n\t\t\t} else {\n\t\t\t\tconst content = result.content?.[0];\n\t\t\t\ttext.setText(theme.fg(\"toolOutput\", content?.type === \"text\" ? content.text : \"\"));\n\t\t\t}\n\t\t\treturn text;\n\t\t},\n\t};\n}\n"]}

package/dist/core/tools/ask-user.js

@@ -22,7 +22,7 @@ const askUserSchema = Type.Object({
     title: Type.Optional(Type.String({
         description: "Short bold header shown above the question.",
     })),
-    options: Type.Optional(Type.Array(Type.String({ minLength: 1, pattern: "\\S" }), {
+    options: Type.Optional(Type.Array(Type.String({ minLength: 1, pattern: "^.*[^ \\t\\r\\n].*$" }), {
         minItems: 2,
         maxItems: 4,
         description: "2-4 nonblank suggested answers the user can pick from.",

package/dist/core/tools/ask-user.js.map

@@ -1 +1 @@
-{"version":3,"file":"ask-user.js","sourceRoot":"","sources":["../../../src/core/tools/ask-user.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ask_user tool.\n *\n * Lets the agent pause and ask the user a structured clarifying question —\n * with optional multiple-choice options, single- or multi-select, and a\n * \"type your own answer\" free-text field — rendered natively in the TUI, the\n * Dashboard, and over RPC. Answering, stopping the turn, aborting, or timing\n * out always settles cleanly so the agent never deadlocks on an absent user.\n *\n * Concurrent calls are serialized through a per-session FIFO queue: only one\n * question is ever shown at a time, and a queued call whose signal aborts\n * settles without opening any UI.\n */\n\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport type { AskRequest, AskResult, ExtensionContext, ToolDefinition } from \"../extensions/types.js\";\n\n// ============================================================================\n// Types\n\nexport interface AskUserDetails {\n\tquestion: string;\n\ttitle?: string;\n\tselected: string[];\n\tcustomText?: string;\n\t/** True when the question closed without an answer. */\n\tskipped: boolean;\n\t/** True when no interactive UI was available (headless/print mode). */\n\tunavailable: boolean;\n\t/** True when the UI host or response protocol failed. */\n\tfailed?: boolean;\n}\n\n// ============================================================================\n// Schema\n\nconst askUserSchema = Type.Object({\n\tquestion: Type.String({\n\t\tdescription: \"The Markdown-formatted question to ask the user. Be specific about what you need to decide.\",\n\t}),\n\ttitle: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Short bold header shown above the question.\",\n\t\t}),\n\t),\n\toptions: Type.Optional(\n\t\tType.Array(Type.String({ minLength: 1, pattern: \"\\\\S\" }), {\n\t\t\tminItems: 2,\n\t\t\tmaxItems: 4,\n\t\t\tdescription: \"2-4 nonblank suggested answers the user can pick from.\",\n\t\t}),\n\t),\n\tallowFreeText: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Offer a 'type your own answer' field. Defaults to true.\",\n\t\t}),\n\t),\n\tmultiSelect: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Allow selecting multiple options (checkboxes). Only meaningful with options.\",\n\t\t}),\n\t),\n\tmultiline: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Use a large multi-line text area for open-ended answers.\",\n\t\t}),\n\t),\n\ttimeoutSeconds: Type.Optional(\n\t\tType.Number({\n\t\t\tminimum: 5,\n\t\t\tmaximum: 3600,\n\t\t\tdescription:\n\t\t\t\t\"Optional: stop the current agent turn after this many seconds if the user does not respond. \" +\n\t\t\t\t\"Shows a live countdown. Omit to wait indefinitely.\",\n\t\t}),\n\t),\n});\n\nexport type AskUserInput = Static<typeof askUserSchema>;\n\n// ============================================================================\n// Result helpers\n\nfunction textResult(text: string, details: AskUserDetails) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text }],\n\t\tdetails,\n\t};\n}\n\nfunction baseDetails(input: AskUserInput): Omit<AskUserDetails, \"selected\" | \"skipped\" | \"unavailable\"> {\n\treturn { question: input.question, title: input.title };\n}\n\nfunction unavailableResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The ask_user tool requires an interactive UI, which is not available in this mode. \" +\n\t\t\t\"Proceed using your best judgment without waiting for an answer.\",\n\t\t{ ...baseDetails(input), selected: [], skipped: true, unavailable: true },\n\t);\n}\n\nfunction unansweredResult(input: AskUserInput) {\n\treturn textResult(\"The question closed without an answer.\", {\n\t\t...baseDetails(input),\n\t\tselected: [],\n\t\tskipped: true,\n\t\tunavailable: false,\n\t});\n}\n\nfunction failedResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The question could not be delivered because the interactive UI or response protocol failed. \" +\n\t\t\t\"Continue without this input.\",\n\t\t{\n\t\t\t...baseDetails(input),\n\t\t\tselected: [],\n\t\t\tskipped: false,\n\t\t\tunavailable: false,\n\t\t\tfailed: true,\n\t\t},\n\t);\n}\n\nfunction answeredResult(input: AskUserInput, answer: AskResult) {\n\tconst customText = answer.customText?.trim() || undefined;\n\tconst selected = answer.selected;\n\tconst parts: string[] = [];\n\tif (selected.length > 0) {\n\t\tparts.push(\n\t\t\tselected.length === 1 ? `The user selected: ${selected[0]}` : `The user selected: ${selected.join(\", \")}`,\n\t\t);\n\t}\n\tif (customText) {\n\t\tparts.push(selected.length > 0 ? `They also wrote: \"${customText}\"` : `The user answered: \"${customText}\"`);\n\t}\n\treturn textResult(parts.join(\" \"), {\n\t\t...baseDetails(input),\n\t\tselected,\n\t\tcustomText,\n\t\tskipped: false,\n\t\tunavailable: false,\n\t});\n}\n\n// ============================================================================\n// Render helpers\n\nfunction formatCall(args: { question?: string; title?: string } | undefined, theme: any): string {\n\tconst label = (args?.title || args?.question || \"\").replace(/\\s+/g, \" \").trim();\n\tconst shown = label.length > 80 ? `${label.slice(0, 79)}…` : label;\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"ask_user\"))} ${theme.fg(\"accent\", shown)}`;\n}\n\nfunction formatResult(details: AskUserDetails, theme: any): string {\n\tif (details.unavailable) return theme.fg(\"toolOutput\", \"no interactive UI — continued without asking\");\n\tif (details.failed) return theme.fg(\"toolOutput\", \"interactive UI failed — continued without an answer\");\n\tif (details.skipped) return theme.fg(\"toolOutput\", \"question closed without an answer\");\n\tconst parts: string[] = [];\n\tif (details.selected.length > 0) parts.push(details.selected.join(\", \"));\n\tif (details.customText) parts.push(`\"${details.customText}\"`);\n\treturn theme.fg(\"toolOutput\", `→ ${parts.join(\" + \")}`);\n}\n\n// ============================================================================\n// Tool definition factory\n\n/**\n * Create an `ask_user` tool definition. Each call creates an isolated FIFO\n * queue, so concurrent `ask_user` calls in a single session are shown strictly\n * one at a time.\n */\nexport function createAskUserToolDefinition(): ToolDefinition<typeof askUserSchema, AskUserDetails | undefined> {\n\t// Per-session serialization: only one question is ever open at a time.\n\tlet tail: Promise<void> = Promise.resolve();\n\tconst serialize = <T>(run: () => Promise<T>): Promise<T> => {\n\t\tconst result = tail.then(run, run);\n\t\t// Always advance the queue, whether the call resolved, cancelled, timed\n\t\t// out, or threw — so a failure can never wedge later questions.\n\t\ttail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t};\n\n\treturn {\n\t\tname: \"ask_user\",\n\t\tlabel: \"ask_user\",\n\t\tdescription:\n\t\t\t\"Pause and ask the user a structured clarifying question with optional multiple-choice options and a \" +\n\t\t\t\"free-text answer. Use only when genuinely blocked by ambiguity with multiple viable paths — not for routine confirmation.\",\n\n\t\tparameters: askUserSchema,\n\n\t\tpromptSnippet: \"Ask the user a clarifying question with optional multiple-choice options and free text\",\n\n\t\tpromptGuidelines: [\n\t\t\t\"Call ask_user ONLY when you are genuinely blocked by ambiguity and there are multiple viable paths forward\",\n\t\t\t\"Do NOT use it for routine confirmation, permission, or things you can reasonably decide yourself\",\n\t\t\t\"Provide 2-4 concrete `options` when there are clear candidate answers; the user can always type their own\",\n\t\t\t\"Set `multiSelect: true` when several options can be combined; `multiline: true` for open-ended answers\",\n\t\t\t\"The user may stop the current turn instead of answering; never treat that as an answer\",\n\t\t\t\"Prefer one focused question over many; the question blocks the turn until the user responds or stops it\",\n\t\t],\n\n\t\tasync execute(_toolCallId, input: AskUserInput, signal, _onUpdate, ctx?: ExtensionContext) {\n\t\t\tconst hasOptions = (input.options?.length ?? 0) > 0;\n\t\t\tconst request: AskRequest = {\n\t\t\t\tquestion: input.question,\n\t\t\t\ttitle: input.title,\n\t\t\t\toptions: input.options,\n\t\t\t\t// Guarantee at least one answer control: with no options, free text\n\t\t\t\t// must be offered regardless of the requested flag, otherwise both\n\t\t\t\t// surfaces would render only a Skip button and no way to answer.\n\t\t\t\tallowFreeText: hasOptions ? input.allowFreeText : true,\n\t\t\t\t// multiSelect is only meaningful with options; multiline only with\n\t\t\t\t// free text — normalize away impossible combinations.\n\t\t\t\tmultiSelect: hasOptions ? input.multiSelect : undefined,\n\t\t\t\tmultiline: hasOptions ? (input.allowFreeText === false ? undefined : input.multiline) : input.multiline,\n\t\t\t};\n\n\t\t\t// Optional auto-stop timeout, forwarded to every UI surface (TUI\n\t\t\t// countdown, RPC/Dashboard). Model-facing units are seconds.\n\t\t\tconst timeout = input.timeoutSeconds && input.timeoutSeconds > 0 ? input.timeoutSeconds * 1000 : undefined;\n\n\t\t\t// Headless / print / no-host modes: never block on an unreachable UI.\n\t\t\tif (!ctx?.hasUI) {\n\t\t\t\treturn unavailableResult(input);\n\t\t\t}\n\n\t\t\treturn serialize(async () => {\n\t\t\t\t// A queued call whose signal already aborted settles without ever\n\t\t\t\t// opening the UI; the parent turn is already stopping.\n\t\t\t\tif (signal?.aborted) return unansweredResult(input);\n\t\t\t\ttry {\n\t\t\t\t\tconst answer = await ctx.ui.ask(request, { signal, timeout });\n\t\t\t\t\tif (!answer || (answer.selected.length === 0 && !answer.customText?.trim())) {\n\t\t\t\t\t\treturn unansweredResult(input);\n\t\t\t\t\t}\n\t\t\t\t\treturn answeredResult(input, answer);\n\t\t\t\t} catch {\n\t\t\t\t\t// Host/protocol failure must still release the queue and never\n\t\t\t\t\t// deadlock, but it must not masquerade as an intentional user skip.\n\t\t\t\t\treturn failedResult(input);\n\t\t\t\t}\n\t\t\t});\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\ttext.setText(formatCall(args, theme));\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, _options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\tconst details = (result as any).details as AskUserDetails | undefined;\n\t\t\tif (details) {\n\t\t\t\ttext.setText(formatResult(details, theme));\n\t\t\t} else {\n\t\t\t\tconst content = result.content?.[0];\n\t\t\t\ttext.setText(theme.fg(\"toolOutput\", content?.type === \"text\" ? content.text : \"\"));\n\t\t\t}\n\t\t\treturn text;\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"ask-user.js","sourceRoot":"","sources":["../../../src/core/tools/ask-user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAe,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAmBtD,+EAA+E;AAC/E,SAAS;AAET,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC;QACrB,WAAW,EAAE,6FAA6F;KAC1G,CAAC;IACF,KAAK,EAAE,IAAI,CAAC,QAAQ,CACnB,IAAI,CAAC,MAAM,CAAC;QACX,WAAW,EAAE,6CAA6C;KAC1D,CAAC,CACF;IACD,OAAO,EAAE,IAAI,CAAC,QAAQ,CACrB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,EAAE;QACzE,QAAQ,EAAE,CAAC;QACX,QAAQ,EAAE,CAAC;QACX,WAAW,EAAE,wDAAwD;KACrE,CAAC,CACF;IACD,aAAa,EAAE,IAAI,CAAC,QAAQ,CAC3B,IAAI,CAAC,OAAO,CAAC;QACZ,WAAW,EAAE,yDAAyD;KACtE,CAAC,CACF;IACD,WAAW,EAAE,IAAI,CAAC,QAAQ,CACzB,IAAI,CAAC,OAAO,CAAC;QACZ,WAAW,EAAE,8EAA8E;KAC3F,CAAC,CACF;IACD,SAAS,EAAE,IAAI,CAAC,QAAQ,CACvB,IAAI,CAAC,OAAO,CAAC;QACZ,WAAW,EAAE,0DAA0D;KACvE,CAAC,CACF;IACD,cAAc,EAAE,IAAI,CAAC,QAAQ,CAC5B,IAAI,CAAC,MAAM,CAAC;QACX,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,IAAI;QACb,WAAW,EACV,8FAA8F;YAC9F,oDAAoD;KACrD,CAAC,CACF;CACD,CAAC,CAAC;AAIH,+EAA+E;AAC/E,iBAAiB;AAEjB,SAAS,UAAU,CAAC,IAAY,EAAE,OAAuB,EAAE;IAC1D,OAAO;QACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;QAC1C,OAAO;KACP,CAAC;AAAA,CACF;AAED,SAAS,WAAW,CAAC,KAAmB,EAAgE;IACvG,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;AAAA,CACxD;AAED,SAAS,iBAAiB,CAAC,KAAmB,EAAE;IAC/C,OAAO,UAAU,CAChB,qFAAqF;QACpF,iEAAiE,EAClE,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CACzE,CAAC;AAAA,CACF;AAED,SAAS,gBAAgB,CAAC,KAAmB,EAAE;IAC9C,OAAO,UAAU,CAAC,wCAAwC,EAAE;QAC3D,GAAG,WAAW,CAAC,KAAK,CAAC;QACrB,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,KAAK;KAClB,CAAC,CAAC;AAAA,CACH;AAED,SAAS,YAAY,CAAC,KAAmB,EAAE;IAC1C,OAAO,UAAU,CAChB,8FAA8F;QAC7F,8BAA8B,EAC/B;QACC,GAAG,WAAW,CAAC,KAAK,CAAC;QACrB,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,KAAK;QAClB,MAAM,EAAE,IAAI;KACZ,CACD,CAAC;AAAA,CACF;AAED,SAAS,cAAc,CAAC,KAAmB,EAAE,MAAiB,EAAE;IAC/D,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CACT,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,sBAAsB,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,sBAAsB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzG,CAAC;IACH,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,qBAAqB,UAAU,GAAG,CAAC,CAAC,CAAC,uBAAuB,UAAU,GAAG,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QAClC,GAAG,WAAW,CAAC,KAAK,CAAC;QACrB,QAAQ;QACR,UAAU;QACV,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,KAAK;KAClB,CAAC,CAAC;AAAA,CACH;AAED,+EAA+E;AAC/E,iBAAiB;AAEjB,SAAS,UAAU,CAAC,IAAuD,EAAE,KAAU,EAAU;IAChG,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAG,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;AAAA,CACvF;AAED,SAAS,YAAY,CAAC,OAAuB,EAAE,KAAU,EAAU;IAClE,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,gDAA8C,CAAC,CAAC;IACvG,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,uDAAqD,CAAC,CAAC;IACzG,IAAI,OAAO,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,mCAAmC,CAAC,CAAC;IACxF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,OAAK,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAAA,CACxD;AAED,+EAA+E;AAC/E,0BAA0B;AAE1B;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,GAAqE;IAC/G,uEAAuE;IACvE,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,CAAI,GAAqB,EAAc,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACnC,wEAAwE;QACxE,kEAAgE;QAChE,IAAI,GAAG,MAAM,CAAC,IAAI,CACjB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CACf,CAAC;QACF,OAAO,MAAM,CAAC;IAAA,CACd,CAAC;IAEF,OAAO;QACN,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,UAAU;QACjB,WAAW,EACV,sGAAsG;YACtG,6HAA2H;QAE5H,UAAU,EAAE,aAAa;QAEzB,aAAa,EAAE,wFAAwF;QAEvG,gBAAgB,EAAE;YACjB,4GAA4G;YAC5G,kGAAkG;YAClG,2GAA2G;YAC3G,wGAAwG;YACxG,wFAAwF;YACxF,yGAAyG;SACzG;QAED,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,KAAmB,EAAE,MAAM,EAAE,SAAS,EAAE,GAAsB,EAAE;YAC1F,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACpD,MAAM,OAAO,GAAe;gBAC3B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,oEAAoE;gBACpE,mEAAmE;gBACnE,iEAAiE;gBACjE,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI;gBACtD,mEAAmE;gBACnE,wDAAsD;gBACtD,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;gBACvD,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS;aACvG,CAAC;YAEF,iEAAiE;YACjE,6DAA6D;YAC7D,MAAM,OAAO,GAAG,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YAE3G,sEAAsE;YACtE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;gBACjB,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;YAED,OAAO,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC5B,kEAAkE;gBAClE,uDAAuD;gBACvD,IAAI,MAAM,EAAE,OAAO;oBAAE,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBACpD,IAAI,CAAC;oBACJ,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;oBAC9D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;wBAC7E,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;oBAChC,CAAC;oBACD,OAAO,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBACtC,CAAC;gBAAC,MAAM,CAAC;oBACR,+DAA+D;oBAC/D,oEAAoE;oBACpE,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;gBAC5B,CAAC;YAAA,CACD,CAAC,CAAC;QAAA,CACH;QAED,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE;YAChC,MAAM,IAAI,GAAI,OAAO,CAAC,aAAkC,IAAI,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;YAChG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YACtC,OAAO,IAAI,CAAC;QAAA,CACZ;QAED,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE;YAC9C,MAAM,IAAI,GAAI,OAAO,CAAC,aAAkC,IAAI,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;YAChG,MAAM,OAAO,GAAI,MAAc,CAAC,OAAqC,CAAC;YACtE,IAAI,OAAO,EAAE,CAAC;gBACb,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACP,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;gBACpC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACpF,CAAC;YACD,OAAO,IAAI,CAAC;QAAA,CACZ;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * ask_user tool.\n *\n * Lets the agent pause and ask the user a structured clarifying question —\n * with optional multiple-choice options, single- or multi-select, and a\n * \"type your own answer\" free-text field — rendered natively in the TUI, the\n * Dashboard, and over RPC. Answering, stopping the turn, aborting, or timing\n * out always settles cleanly so the agent never deadlocks on an absent user.\n *\n * Concurrent calls are serialized through a per-session FIFO queue: only one\n * question is ever shown at a time, and a queued call whose signal aborts\n * settles without opening any UI.\n */\n\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport type { AskRequest, AskResult, ExtensionContext, ToolDefinition } from \"../extensions/types.js\";\n\n// ============================================================================\n// Types\n\nexport interface AskUserDetails {\n\tquestion: string;\n\ttitle?: string;\n\tselected: string[];\n\tcustomText?: string;\n\t/** True when the question closed without an answer. */\n\tskipped: boolean;\n\t/** True when no interactive UI was available (headless/print mode). */\n\tunavailable: boolean;\n\t/** True when the UI host or response protocol failed. */\n\tfailed?: boolean;\n}\n\n// ============================================================================\n// Schema\n\nconst askUserSchema = Type.Object({\n\tquestion: Type.String({\n\t\tdescription: \"The Markdown-formatted question to ask the user. Be specific about what you need to decide.\",\n\t}),\n\ttitle: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Short bold header shown above the question.\",\n\t\t}),\n\t),\n\toptions: Type.Optional(\n\t\tType.Array(Type.String({ minLength: 1, pattern: \"^.*[^ \\\\t\\\\r\\\\n].*$\" }), {\n\t\t\tminItems: 2,\n\t\t\tmaxItems: 4,\n\t\t\tdescription: \"2-4 nonblank suggested answers the user can pick from.\",\n\t\t}),\n\t),\n\tallowFreeText: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Offer a 'type your own answer' field. Defaults to true.\",\n\t\t}),\n\t),\n\tmultiSelect: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Allow selecting multiple options (checkboxes). Only meaningful with options.\",\n\t\t}),\n\t),\n\tmultiline: Type.Optional(\n\t\tType.Boolean({\n\t\t\tdescription: \"Use a large multi-line text area for open-ended answers.\",\n\t\t}),\n\t),\n\ttimeoutSeconds: Type.Optional(\n\t\tType.Number({\n\t\t\tminimum: 5,\n\t\t\tmaximum: 3600,\n\t\t\tdescription:\n\t\t\t\t\"Optional: stop the current agent turn after this many seconds if the user does not respond. \" +\n\t\t\t\t\"Shows a live countdown. Omit to wait indefinitely.\",\n\t\t}),\n\t),\n});\n\nexport type AskUserInput = Static<typeof askUserSchema>;\n\n// ============================================================================\n// Result helpers\n\nfunction textResult(text: string, details: AskUserDetails) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text }],\n\t\tdetails,\n\t};\n}\n\nfunction baseDetails(input: AskUserInput): Omit<AskUserDetails, \"selected\" | \"skipped\" | \"unavailable\"> {\n\treturn { question: input.question, title: input.title };\n}\n\nfunction unavailableResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The ask_user tool requires an interactive UI, which is not available in this mode. \" +\n\t\t\t\"Proceed using your best judgment without waiting for an answer.\",\n\t\t{ ...baseDetails(input), selected: [], skipped: true, unavailable: true },\n\t);\n}\n\nfunction unansweredResult(input: AskUserInput) {\n\treturn textResult(\"The question closed without an answer.\", {\n\t\t...baseDetails(input),\n\t\tselected: [],\n\t\tskipped: true,\n\t\tunavailable: false,\n\t});\n}\n\nfunction failedResult(input: AskUserInput) {\n\treturn textResult(\n\t\t\"The question could not be delivered because the interactive UI or response protocol failed. \" +\n\t\t\t\"Continue without this input.\",\n\t\t{\n\t\t\t...baseDetails(input),\n\t\t\tselected: [],\n\t\t\tskipped: false,\n\t\t\tunavailable: false,\n\t\t\tfailed: true,\n\t\t},\n\t);\n}\n\nfunction answeredResult(input: AskUserInput, answer: AskResult) {\n\tconst customText = answer.customText?.trim() || undefined;\n\tconst selected = answer.selected;\n\tconst parts: string[] = [];\n\tif (selected.length > 0) {\n\t\tparts.push(\n\t\t\tselected.length === 1 ? `The user selected: ${selected[0]}` : `The user selected: ${selected.join(\", \")}`,\n\t\t);\n\t}\n\tif (customText) {\n\t\tparts.push(selected.length > 0 ? `They also wrote: \"${customText}\"` : `The user answered: \"${customText}\"`);\n\t}\n\treturn textResult(parts.join(\" \"), {\n\t\t...baseDetails(input),\n\t\tselected,\n\t\tcustomText,\n\t\tskipped: false,\n\t\tunavailable: false,\n\t});\n}\n\n// ============================================================================\n// Render helpers\n\nfunction formatCall(args: { question?: string; title?: string } | undefined, theme: any): string {\n\tconst label = (args?.title || args?.question || \"\").replace(/\\s+/g, \" \").trim();\n\tconst shown = label.length > 80 ? `${label.slice(0, 79)}…` : label;\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"ask_user\"))} ${theme.fg(\"accent\", shown)}`;\n}\n\nfunction formatResult(details: AskUserDetails, theme: any): string {\n\tif (details.unavailable) return theme.fg(\"toolOutput\", \"no interactive UI — continued without asking\");\n\tif (details.failed) return theme.fg(\"toolOutput\", \"interactive UI failed — continued without an answer\");\n\tif (details.skipped) return theme.fg(\"toolOutput\", \"question closed without an answer\");\n\tconst parts: string[] = [];\n\tif (details.selected.length > 0) parts.push(details.selected.join(\", \"));\n\tif (details.customText) parts.push(`\"${details.customText}\"`);\n\treturn theme.fg(\"toolOutput\", `→ ${parts.join(\" + \")}`);\n}\n\n// ============================================================================\n// Tool definition factory\n\n/**\n * Create an `ask_user` tool definition. Each call creates an isolated FIFO\n * queue, so concurrent `ask_user` calls in a single session are shown strictly\n * one at a time.\n */\nexport function createAskUserToolDefinition(): ToolDefinition<typeof askUserSchema, AskUserDetails | undefined> {\n\t// Per-session serialization: only one question is ever open at a time.\n\tlet tail: Promise<void> = Promise.resolve();\n\tconst serialize = <T>(run: () => Promise<T>): Promise<T> => {\n\t\tconst result = tail.then(run, run);\n\t\t// Always advance the queue, whether the call resolved, cancelled, timed\n\t\t// out, or threw — so a failure can never wedge later questions.\n\t\ttail = result.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn result;\n\t};\n\n\treturn {\n\t\tname: \"ask_user\",\n\t\tlabel: \"ask_user\",\n\t\tdescription:\n\t\t\t\"Pause and ask the user a structured clarifying question with optional multiple-choice options and a \" +\n\t\t\t\"free-text answer. Use only when genuinely blocked by ambiguity with multiple viable paths — not for routine confirmation.\",\n\n\t\tparameters: askUserSchema,\n\n\t\tpromptSnippet: \"Ask the user a clarifying question with optional multiple-choice options and free text\",\n\n\t\tpromptGuidelines: [\n\t\t\t\"Call ask_user ONLY when you are genuinely blocked by ambiguity and there are multiple viable paths forward\",\n\t\t\t\"Do NOT use it for routine confirmation, permission, or things you can reasonably decide yourself\",\n\t\t\t\"Provide 2-4 concrete `options` when there are clear candidate answers; the user can always type their own\",\n\t\t\t\"Set `multiSelect: true` when several options can be combined; `multiline: true` for open-ended answers\",\n\t\t\t\"The user may stop the current turn instead of answering; never treat that as an answer\",\n\t\t\t\"Prefer one focused question over many; the question blocks the turn until the user responds or stops it\",\n\t\t],\n\n\t\tasync execute(_toolCallId, input: AskUserInput, signal, _onUpdate, ctx?: ExtensionContext) {\n\t\t\tconst hasOptions = (input.options?.length ?? 0) > 0;\n\t\t\tconst request: AskRequest = {\n\t\t\t\tquestion: input.question,\n\t\t\t\ttitle: input.title,\n\t\t\t\toptions: input.options,\n\t\t\t\t// Guarantee at least one answer control: with no options, free text\n\t\t\t\t// must be offered regardless of the requested flag, otherwise both\n\t\t\t\t// surfaces would render only a Skip button and no way to answer.\n\t\t\t\tallowFreeText: hasOptions ? input.allowFreeText : true,\n\t\t\t\t// multiSelect is only meaningful with options; multiline only with\n\t\t\t\t// free text — normalize away impossible combinations.\n\t\t\t\tmultiSelect: hasOptions ? input.multiSelect : undefined,\n\t\t\t\tmultiline: hasOptions ? (input.allowFreeText === false ? undefined : input.multiline) : input.multiline,\n\t\t\t};\n\n\t\t\t// Optional auto-stop timeout, forwarded to every UI surface (TUI\n\t\t\t// countdown, RPC/Dashboard). Model-facing units are seconds.\n\t\t\tconst timeout = input.timeoutSeconds && input.timeoutSeconds > 0 ? input.timeoutSeconds * 1000 : undefined;\n\n\t\t\t// Headless / print / no-host modes: never block on an unreachable UI.\n\t\t\tif (!ctx?.hasUI) {\n\t\t\t\treturn unavailableResult(input);\n\t\t\t}\n\n\t\t\treturn serialize(async () => {\n\t\t\t\t// A queued call whose signal already aborted settles without ever\n\t\t\t\t// opening the UI; the parent turn is already stopping.\n\t\t\t\tif (signal?.aborted) return unansweredResult(input);\n\t\t\t\ttry {\n\t\t\t\t\tconst answer = await ctx.ui.ask(request, { signal, timeout });\n\t\t\t\t\tif (!answer || (answer.selected.length === 0 && !answer.customText?.trim())) {\n\t\t\t\t\t\treturn unansweredResult(input);\n\t\t\t\t\t}\n\t\t\t\t\treturn answeredResult(input, answer);\n\t\t\t\t} catch {\n\t\t\t\t\t// Host/protocol failure must still release the queue and never\n\t\t\t\t\t// deadlock, but it must not masquerade as an intentional user skip.\n\t\t\t\t\treturn failedResult(input);\n\t\t\t\t}\n\t\t\t});\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\ttext.setText(formatCall(args, theme));\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, _options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0, undefined, true);\n\t\t\tconst details = (result as any).details as AskUserDetails | undefined;\n\t\t\tif (details) {\n\t\t\t\ttext.setText(formatResult(details, theme));\n\t\t\t} else {\n\t\t\t\tconst content = result.content?.[0];\n\t\t\t\ttext.setText(theme.fg(\"toolOutput\", content?.type === \"text\" ? content.text : \"\"));\n\t\t\t}\n\t\t\treturn text;\n\t\t},\n\t};\n}\n"]}

package/docs/dashboard.md

@@ -120,7 +120,7 @@ networking window above.
 | Screen | What it does |
 |---|---|
 | **Fleet** | Home. Live-first: one grid of every live session at the top — status chip (● running / ◆ needs-attention / ○ idle / ✕ error), project path, activity line, live subagent lines, tasks progress, ctx%, model, terminal provider-error reason, last activity. Live cards keep a deterministic order by project path, then session start time; needs-attention cards badge the browser tab without jumping around. Below the grid: past sessions grouped by project, three compact rows per group with an "all N on disk" expander, resume and delete. |
-| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, inline provider/API failures with partial output preserved, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs, markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, and inline tool-result images, compaction/branch summaries, custom messages), per-message copy, tasks panel, subagent strip, status line with elapsed time plus ■ stop and compaction/retry aborts, a persistent session-header live indicator, and an info bar with cwd, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, median tok/s, and a stats popover. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste with sent images retained as user-message previews, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests for select/confirm/input/editor render as modals; rich `ask`/`ask_user` questions render inline with Markdown-formatted question text, choices, optional free text, an in-card Stop agent action, Escape-to-stop, and the authoritative auto-stop countdown. Pending questions set needs-attention state and use the existing hidden-page notification path. Extension notifications render as toasts. |
+| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, inline provider/API failures with partial output preserved, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs, markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, and inline tool-result images, compaction/branch summaries, custom messages), per-message copy, tasks panel, a bounded scrollable subagent panel that lists every retained agent newest-first with full running/done counts, status line with elapsed time plus ■ stop and compaction/retry aborts, a persistent session-header live indicator, and an info bar with cwd, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, median tok/s, and a stats popover. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste with sent images retained as user-message previews, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests for select/confirm/input/editor render as modals; rich `ask`/`ask_user` questions render inline with Markdown-formatted question text, choices, optional free text, an in-card Stop agent action, Escape-to-stop, and the authoritative auto-stop countdown. Pending questions set needs-attention state and use the existing hidden-page notification path. Extension notifications render as toasts. |
 | **Subagent view** | Read-only transcript of a background agent: live events via the RPC relay, hydrated from the agent's on-disk session log (`/subagents/:agentId/messages`) so the transcript survives browser reloads. Shows the task, streaming output, tool activity, and any safe Dispatch Arbiter changed/unchanged/failure records with the final agent/model/thinking. No raw arbiter output is displayed or transported. No composer — subagents can't be steered yet; the parent session controls them. |
 | **Files** | Host-wide browser with places shortcuts (home, /tmp, project roots), breadcrumbs to `/`, new-folder, download, drop-zone/picker upload with explicit collision prompts, and "new session here" on any directory. It also shows the **effective global nested-context trust** for the displayed canonical directory: untrusted, trusted by that root, inherited from a granting root, or global expert trust-all. You can trust the displayed folder and descendants, or untrust the actual granting root; untrusting an inherited folder removes that root's trust for all descendants. |
 | **Settings** | Persistent defaults (default model, thinking level, steering/follow-up queue modes, auto-compaction, auto-retry) via `get_settings`/`set_settings` — validation errors are shown verbatim. The global-only Dispatch Arbiter card exposes enable/disable, exact authenticated model selection, thinking, guide path, and readiness guidance; model-less enablement is blocked and RPC/runtime validation remains fail-closed. Entering Settings flushes pending writes and reloads durable global + project settings, so external edits appear; read, parse, or write failures fail loudly instead of showing stale settings. The global-only nested-context policy lists every explicit trusted root for audit and revoke, offers a simple add-by-path control, and includes a prominently warned expert trust-all toggle; the Files view remains the primary place to grant trust while browsing. Most defaults seed new sessions; context-trust changes are observed by active main/subagent processes for future lazy loads, but cannot remove already injected content. Dashboard-local preferences (always expand thinking, transcript image display mode, needs-attention notification permission) live in the browser, alongside an appearance section: a theme gallery of eight curated themes (entropist.ca, Dim, Solarized, Gruvbox, Caves of Qud, Van Gogh, and the colorblind-safe Okabe-Ito and Paul Tol) with live preview cards and a system/light/dark mode selector, saved per browser. Shows the current rotating pairing code on the host/local dashboard, plus the paired-devices list with unpair. |
@@ -128,7 +128,7 @@ networking window above.
 
 ### Dispatch Arbiter observability
 
-When the global Dispatch Arbiter is enabled, the dashboard consumes the typed `subagent_arbitration` RPC event. The matching background-agent card is updated to the final selected agent before child events arrive; the parent chip shows final model/thinking or a failure marker, and the subagent drill-in lists ordered records (including chain steps). Runtime snapshots carry the same safe records so refresh/resync during a live process does not revert to the requested identity.
+When the global Dispatch Arbiter is enabled, the dashboard consumes the typed `subagent_arbitration` RPC event. The matching background-agent card is updated to the final selected agent before child events arrive; the parent panel row shows final model/thinking or a failure marker, and the subagent drill-in lists ordered records (including chain steps). Runtime snapshots carry the same safe records so refresh/resync during a live process does not revert to the requested identity.
 
 Only host-validated proposed/final tuples, changed fields, status, step, and bounded host errors cross RPC/SSE. Arbiter prompts, raw output, reasoning, tasks, guides, and parent excerpts never reach dashboard protocol state. The safe record is separately persisted in the parent session as a non-context custom entry; child transcript hydration remains sourced from the child log.
 
@@ -374,8 +374,10 @@ Then open `https://hostname.tailXXXX.ts.net:<port>` on the phone.
 Background subagents are first-class:
 
 - Fleet cards show running/done counts and live agent lines.
-- The session view shows a chip strip — one chip per background agent; click
-  to drill into its live transcript.
+- The session view shows every retained background agent in a bounded,
+  scrollable panel, ordered newest-first with the full running/done count in its
+  summary. It uses the same native collapse pattern as the task tracker, starts
+  collapsed on mobile, and keeps every row available for transcript drill-in.
 - The drill-in view streams the child's events in real time via the
   `background_agent_event` relay (see [RPC events](rpc.md#event-types)) and
   hydrates from the agent's on-disk session log on mount, so transcripts
@@ -387,7 +389,8 @@ Single breakpoint at 700px. At <=700px, fleet cards stack; long session names,
 status chips, project paths, activity and subagent text, and past-session
 labels wrap within their cards or rows rather than spilling off-screen. The
 session view prioritizes read-and-steer (model/thinking switchers collapse into
-⋯, tasks default collapsed), and the file table shows name + download only.
+⋯, and task/subagent panels default collapsed), and the file table shows name +
+download only.
 Composer modes, abort, and needs-attention affordances are never reduced away
 — steering a running agent from a phone is the primary remote use case.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.48.0",
+	"version": "2.49.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {