@f5-sales-demo/xcsh 21.35.2 → 21.35.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.35.2",
+	"version": "21.35.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -63,13 +63,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.4.0",
-		"@f5-sales-demo/pi-agent-core": "21.35.2",
-		"@f5-sales-demo/pi-ai": "21.35.2",
-		"@f5-sales-demo/pi-natives": "21.35.2",
-		"@f5-sales-demo/pi-resource-management": "21.35.2",
-		"@f5-sales-demo/pi-tui": "21.35.2",
-		"@f5-sales-demo/pi-utils": "21.35.2",
-		"@f5-sales-demo/xcsh-stats": "21.35.2",
+		"@f5-sales-demo/pi-agent-core": "21.35.4",
+		"@f5-sales-demo/pi-ai": "21.35.4",
+		"@f5-sales-demo/pi-natives": "21.35.4",
+		"@f5-sales-demo/pi-resource-management": "21.35.4",
+		"@f5-sales-demo/pi-tui": "21.35.4",
+		"@f5-sales-demo/pi-utils": "21.35.4",
+		"@f5-sales-demo/xcsh-stats": "21.35.4",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "0.34.52",
 		"@xterm/headless": "^6.0",

package/src/config/auto-config.ts

@@ -20,7 +20,7 @@ import { hardenAgentConfigFileSync, writeAgentConfigFileSync } from "./agent-con
 import { DEFAULT_MODEL_ROLE } from "./settings-schema";
 
 /** Current config schema version. Bump when the generated format changes. */
-export const CURRENT_CONFIG_VERSION = 7;
+export const CURRENT_CONFIG_VERSION = 8;
 const LITELLM_CONFIG_DIR_MODE = 0o700;
 const LITELLM_MODELS_FILE_MODE = 0o600;
 const GENERATED_LITELLM_MARKER = "# Auto-generated by xcsh for LiteLLM proxy";
@@ -61,6 +61,10 @@ export interface GenerateModelsYmlOptions {
 /** Generate models.yml content for LiteLLM proxy. */
 export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOptions): string {
 	const apiBase = options?.apiBasePath ?? "/v1";
+	// LiteLLM's OpenAI-compatible chat route can live behind a custom API prefix
+	// (for example /api/v1). Astra with tools and reasoning requires the
+	// Responses API, which LiteLLM exposes on its dedicated OpenAI route.
+	const astraResponsesBaseUrl = `${baseUrl.replace(/\/+$/, "")}/openai/v1`;
 	// When a literal API key is provided, double-quote it to handle YAML-significant
 	// characters (: ! # { } [ ] ' " etc.). Escape backslashes and double quotes first.
 	const apiKeyValue = options?.apiKeyLiteral
@@ -99,6 +103,8 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 		"    models:",
 		"      - id: gpt-6-astra",
 		"        name: GPT-6 Astra",
+		"        api: openai-responses",
+		`        baseUrl: "${astraResponsesBaseUrl}"`,
 		"    picker:",
 		"      groupId: litellm",
 		"      groupLabel: LiteLLM",

package/src/herdr/interactions.ts

@@ -2,6 +2,7 @@ import { isDeepStrictEqual } from "node:util";
 import type { ConversationPlan, PlanAction } from "../../../chat-ui/src/interactions/conversation-plan";
 import type {
 	InteractionIdentity,
+	InteractionResolution,
 	UserInteraction,
 	UserInteractionEvent,
 	UserInteractions,
@@ -17,10 +18,10 @@ interface Binding {
 	pane_id: string;
 	producer: string;
 	generation: number;
-}
-interface Owner extends Binding {
+	/** Stable Herdr producer session; unlike the conversation thread, this cannot change in-process. */
 	session_id: string;
 }
+type Owner = Binding;
 interface Target {
 	owner: Owner;
 	request_id: string;
@@ -30,6 +31,9 @@ interface Entry {
 	identity: InteractionIdentity;
 	report: Record<string, unknown>;
 	decide?: (action: PlanAction) => Promise<{ accepted: boolean }>;
+	questionRequests?: Map<string, string>;
+	pendingRequestIds?: Set<string>;
+	resolutions?: InteractionResolution[];
 }
 const record = (value: unknown): value is Record<string, unknown> =>
 	value !== null && typeof value === "object" && !Array.isArray(value);
@@ -37,6 +41,7 @@ const record = (value: unknown): value is Record<string, unknown> =>
 /** Additional observation never owns completion or disables the local interaction path. */
 export class HerdrInteractionBridge {
 	#entries = new Map<string, Entry>();
+	#entryByInteraction = new Map<string, string>();
 	#reports: Record<string, unknown>[] = [];
 	#acks: Record<string, unknown>[] = [];
 	#decisions = new Map<string, { action: unknown; accepted: boolean }>();
@@ -65,46 +70,102 @@ export class HerdrInteractionBridge {
 	#observe(event: UserInteractionEvent): void {
 		if (event.type === "opened") this.#open(event.interaction, event.revision);
 		else {
-			const entry = this.#entries.get(event.interaction.id);
+			const key = this.#entryByInteraction.get(event.interaction.id) ?? event.interaction.id;
+			const entry = this.#entries.get(key);
 			if (!entry) return;
-			entry.report = { ...entry.report, event_revision: event.revision, state: event.reason ?? "owner_lost" };
-			this.#reports.push(structuredClone(entry.report));
+			if (entry.pendingRequestIds) {
+				entry.pendingRequestIds.delete(event.interaction.id);
+				entry.resolutions?.push(event.reason ?? "owner_lost");
+				if (entry.pendingRequestIds.size) return;
+			}
+			const resolutions = entry.resolutions ?? [event.reason ?? "owner_lost"];
+			const state = resolutions.every(reason => reason === "answered")
+				? "answered"
+				: (resolutions.find(reason => reason !== "answered") ?? "owner_lost");
+			entry.report = { ...entry.report, event_revision: event.revision, state };
+			this.#queueReport(entry.report);
 		}
 	}
 	#open(request: UserInteraction, revision: number): void {
 		const identity = request.identity;
 		if (!identity || (request.kind !== "request_user_input" && request.delivery !== "async")) return;
-		const target = { owner: { ...this.binding, session_id: identity.sessionId }, request_id: request.id };
+		const batch = request.delivery === "async" ? request.asyncBatch : undefined;
+		const requestId = batch?.requestId ?? request.id;
+		const existing = this.#entries.get(requestId);
+		if (existing?.questionRequests && request.questionId) {
+			existing.questionRequests.set(request.questionId, request.id);
+			existing.pendingRequestIds?.add(request.id);
+			this.#entryByInteraction.set(request.id, requestId);
+			return;
+		}
+		if (this.#entries.size >= 64) {
+			this.onError(new Error("Herdr interaction bridge capacity exceeded"));
+			return;
+		}
+		const target = { owner: { ...this.binding }, request_id: requestId };
+		const asyncQuestions = batch?.questions ?? [
+			{ title: request.title, ...(request.options ? { options: [...request.options] } : {}) },
+		];
+		const asyncQuestionIds = batch?.questionIds ?? [request.questionId ?? identity.itemId];
+		const asyncItem = batch?.item ?? {
+			id: identity.itemId,
+			type: "agentMessage" as const,
+			text: asyncQuestions
+				.map(question => [question.title, ...(question.options?.map(option => `- ${option}`) ?? [])].join("\n"))
+				.join("\n\n"),
+			phase: "final_answer" as const,
+			delivery: "async" as const,
+			questions: asyncQuestions,
+		};
 		const report = {
 			target,
 			thread_id: identity.threadId,
 			turn_id: identity.turnId,
 			item_id: identity.itemId,
-			question_ids: request.inputQuestions?.map(question => question.id) ?? [request.questionId ?? identity.itemId],
+			question_ids: request.inputQuestions?.map(question => question.id) ?? asyncQuestionIds,
 			event_revision: revision,
 			kind: request.delivery === "async" ? "async" : "waiting",
 			state: "pending",
 			payload:
 				request.delivery === "async"
-					? {
-							id: identity.itemId,
-							type: "agentMessage",
-							text: request.title,
-							phase: "final_answer",
-							delivery: "async",
-							questions: [{ title: request.title, ...(request.options ? { options: request.options } : {}) }],
-						}
+					? asyncItem
 					: { questions: request.inputQuestions, isBlocking: true, autoResolutionMs: null },
 		};
-		this.#entries.set(request.id, { target, identity: structuredClone(identity), report });
+		const entry: Entry = { target, identity: structuredClone(identity), report };
+		if (request.delivery === "async") {
+			entry.questionRequests = new Map([[request.questionId ?? identity.itemId, request.id]]);
+			entry.pendingRequestIds = new Set([request.id]);
+			entry.resolutions = [];
+		}
+		this.#entries.set(requestId, entry);
+		this.#entryByInteraction.set(request.id, requestId);
+		this.#queueReport(report);
+	}
+	#queueReport(report: Record<string, unknown>): void {
+		const target = JSON.stringify(report.target);
+		const state = report.state;
+		const index = this.#reports.findIndex(
+			queued =>
+				JSON.stringify(queued.target) === target &&
+				(state === "pending" ? queued.state === "pending" : queued.state !== "pending"),
+		);
+		if (index >= 0) {
+			this.#reports[index] = structuredClone(report);
+			return;
+		}
 		this.#reports.push(structuredClone(report));
+		if (this.#reports.length > 128) this.onError(new Error("Herdr interaction report queue capacity exceeded"));
 	}
 	plan(
 		plan: ConversationPlan,
 		identity: InteractionIdentity,
 		decide: (action: PlanAction) => Promise<{ accepted: boolean }>,
 	): void {
-		const target = { owner: { ...this.binding, session_id: identity.sessionId }, request_id: plan.id };
+		if (!this.#entries.has(plan.id) && this.#entries.size >= 64) {
+			this.onError(new Error("Herdr interaction bridge capacity exceeded"));
+			return;
+		}
+		const target = { owner: { ...this.binding }, request_id: plan.id };
 		const report = {
 			target,
 			thread_id: identity.threadId,
@@ -117,13 +178,13 @@ export class HerdrInteractionBridge {
 			state: "pending",
 		};
 		this.#entries.set(plan.id, { target, identity, report, decide });
-		this.#reports.push(structuredClone(report));
+		this.#queueReport(report);
 	}
 	resolvePlan(planId: string): void {
 		const entry = this.#entries.get(planId);
 		if (!entry) return;
 		entry.report = { ...entry.report, event_revision: Number(entry.report.event_revision) + 1, state: "answered" };
-		this.#reports.push(structuredClone(entry.report));
+		this.#queueReport(entry.report);
 	}
 	flush(): Promise<void> {
 		if (this.#closed) return Promise.resolve();
@@ -152,6 +213,10 @@ export class HerdrInteractionBridge {
 			});
 			if (response.type !== "agent_interaction") throw new Error("Herdr did not acknowledge the interaction report");
 			this.#reports.shift();
+			if (report.state !== "pending" && record(report.target)) {
+				const requestId = report.target.request_id;
+				if (typeof requestId === "string") this.#dropEntry(requestId);
+			}
 		}
 		const owners = new Map(
 			[...this.#entries.values()]
@@ -184,8 +249,23 @@ export class HerdrInteractionBridge {
 							typeof delivery.answer === "string" &&
 							["implement", "fresh", "stay"].includes(delivery.answer) &&
 							(await entry.decide(delivery.answer as PlanAction)).accepted;
-						this.#decisions.set(receipt.response_id as string, { action: delivery.answer, accepted });
+						this.#rememberDecision(receipt.response_id as string, delivery.answer, accepted);
 					}
+				} else if (entry.questionRequests) {
+					const answer = record(delivery.answer) ? delivery.answer : undefined;
+					const questionId = answer?.questionId;
+					const value = answer?.answer;
+					const interactionId =
+						typeof questionId === "string" ? entry.questionRequests.get(questionId) : undefined;
+					accepted =
+						typeof interactionId === "string" &&
+						typeof value === "string" &&
+						this.interactions.respondExternal(
+							interactionId,
+							receipt.response_id as string,
+							value,
+							entry.identity,
+						);
 				} else
 					accepted = this.interactions.respondExternal(
 						target.request_id,
@@ -204,6 +284,20 @@ export class HerdrInteractionBridge {
 		}
 		this.#failureReported = false;
 	}
+	#dropEntry(requestId: string): void {
+		const entry = this.#entries.get(requestId);
+		if (!entry) return;
+		for (const interactionId of entry.questionRequests?.values() ?? [])
+			this.#entryByInteraction.delete(interactionId);
+		this.#entries.delete(requestId);
+	}
+	#rememberDecision(responseId: string, action: unknown, accepted: boolean): void {
+		this.#decisions.set(responseId, { action, accepted });
+		for (const [oldestResponseId] of this.#decisions) {
+			if (this.#decisions.size <= 256) break;
+			this.#decisions.delete(oldestResponseId);
+		}
+	}
 	async #flushAcknowledgements(): Promise<void> {
 		while (this.#acks.length) {
 			const ack = await this.client.request("agent.interaction.delivery.ack", this.#acks[0]);

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "21.35.2",
-	"commit": "b977ec8d50109693c984cfbaae33bde9f085bef2",
-	"shortCommit": "b977ec8",
+	"version": "21.35.4",
+	"commit": "f093838a50d8443de241a571ffd2971cf2c9ede4",
+	"shortCommit": "f093838",
 	"branch": "main",
-	"tag": "v21.35.2",
-	"commitDate": "2026-09-20T22:17:50+00:00",
-	"buildDate": "2026-09-20T23:11:57.486Z",
+	"tag": "v21.35.4",
+	"commitDate": "2026-09-21T02:18:46+00:00",
+	"buildDate": "2026-09-21T03:22:24.221Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/b977ec8d50109693c984cfbaae33bde9f085bef2",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.35.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/f093838a50d8443de241a571ffd2971cf2c9ede4",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.35.4"
 };

package/src/internal-urls/docs-index.generated.ts

@@ -28,7 +28,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"en/automate-extend/skills.mdx": "---\ntitle: \"Create and load skills\"\ndescription: \"Package task-specific instructions in `SKILL.md` files at user or project scope.\"\nsidebar:\n  order: 5\n  label: \"Create and load skills\"\n---\n\nA skill is a directory centered on `SKILL.md`. It tells an agent when and how to perform a bounded kind of work; it is not executable proof by itself.\n\n## Where do skills live?\n\nUse project scope under `.xcsh/skills/` for repository-specific instructions and user scope under the xcsh data directory for personal skills. Project instructions should be reviewable with the repository.\n\n## How do I test one?\n\nStart xcsh with `--skills <GLOB>` to narrow discovery, invoke a prompt that matches the trigger, and inspect the tools and output. Use `--no-skills` to confirm behavior without it.\n\nGive `SKILL.md` a narrow trigger, explicit prerequisites, ordered actions, and a verifiable stopping\ncondition. Keep executable helpers inside the skill directory and invoke them through their\ndocumented interface rather than embedding machine-specific paths. Test positive and negative\nprompts with only that skill selected, inspect which instructions were loaded, then remove the\ntemporary skill and confirm the trigger no longer matches.\n",
 	"en/configure-secure/environment-reference.mdx": "---\ntitle: \"Environment variable reference\"\ndescription: \"Look up the environment variables that select models, credentials, tenants, execution behavior, storage roots, and diagnostics.\"\nsidebar:\n  order: 2\n  label: \"Environment variables\"\n---\n\nEnvironment variables carry credentials and process-scoped overrides. Settings files and command flags keep their documented precedence; a similarly named variable is not automatically supported. Provider adapters read their own vendor key names, which the adapter defines rather than this list.\n\n## Which variables configure models, providers, and search?\n\n| Variable | Controls |\n| --- | --- |\n| `PI_SMOL_MODEL` | Default model for the lightweight role, equivalent to `--smol` |\n| `PI_SLOW_MODEL` | Default model for the reasoning role, equivalent to `--slow` |\n| `PI_PLAN_MODEL` | Default model for the planning role, equivalent to `--plan` |\n| `XCSH_LOCALE` | Interface locale, ahead of `PI_LOCALE` and `LANG` |\n\nA flag beats the variable: `--smol` overrides `PI_SMOL_MODEL` for that invocation. Model selection stays a model-registry decision, so a name these variables set must still resolve through `xcsh --list-models <PROVIDER>`.\n\n## Which variables address an F5 Distributed Cloud tenant?\n\n| Variable | Controls |\n| --- | --- |\n| `XCSH_API_URL` | Tenant application programming interface (API) endpoint when no named context is active |\n| `XCSH_API_TOKEN` | Tenant API credential for that endpoint |\n| `XCSH_TENANT` | Tenant identifier reported in context status |\n| `XCSH_CONTEXT_NAME` | Name of the context the session binds to |\n| `XCSH_NAMESPACE` | Namespace applied when a command does not pass `-n` |\n| `F5XC_NAMESPACE` | Namespace source recorded in resource operation records |\n\nTreat every value in this group as a secret. Supply them through the runtime environment or a named context, never through a committed file or a command argument that reaches shell history.\n\n## Which variables configure Python, shell, and tool execution?\n\n| Variable | Controls |\n| --- | --- |\n| `PI_PYTHON_GATEWAY_URL` | Endpoint the Python tool sends code to |\n| `PI_PYTHON_GATEWAY_TOKEN` | Credential for that gateway |\n| `PI_PYTHON_SKIP_CHECK` | Skips the gateway warm-up probe |\n| `PI_SHELL_PREFIX` | Command prefix wrapped around shell tool invocations |\n| `PI_BASH_NO_LOGIN` | Runs the shell without `-l` |\n| `PI_NO_PTY` | Disables pseudo-terminal (PTY) execution, equivalent to `--no-pty` |\n| `PI_EDIT_VARIANT` | Selects the edit tool implementation and rejects an unknown value |\n\nShell execution inherits the launched process environment, subject to the sandbox and command policy. Restrict dependencies, working directory, and credentials at the process boundary rather than in the prompt.\n\n## Which variables configure storage, runtime, and diagnostics?\n\n| Variable | Controls |\n| --- | --- |\n| `PI_CODING_AGENT_DIR` | Primary agent data root, including session storage |\n| `PI_CONFIG_DIR` | Configuration root directory name, `.xcsh` by default |\n| `PI_PACKAGE_DIR` | Packaged asset directory the runtime resolves against |\n| `PI_SESSION_FILE` | Session file a child process attaches to |\n| `PI_NATIVE_VARIANT` | Hardware variant the native addon loader prefers |\n| `PI_CACHE_RETENTION` | Cache retention policy, `short` by default |\n| `PI_NO_TITLE` | Disables title auto-generation, equivalent to `--no-title` |\n| `PI_NOTIFICATIONS` | Desktop notification behavior |\n| `PI_DEBUG_STARTUP` | Startup phase diagnostics |\n| `PI_TIMING` | Phase timing output |\n| `PI_TUI_DEBUG` | Terminal user interface (TUI) rendering diagnostics |\n\nProject configuration stays under `.xcsh/` even when `PI_CODING_AGENT_DIR` moves the user root. Never print a credential-bearing variable into a diagnostic receipt; name the variable and state whether it was set.\n\nSet a variable only in the process that needs it, then use the relevant read-only command or a\nno-tool prompt to confirm selection. Environment values can override files and may be inherited by\nsubprocesses; never print tokens while diagnosing precedence. To undo a test, unset the variable in\nthe same shell and start a new xcsh process because an existing process has already captured its\nenvironment.\n",
 	"en/configure-secure/index.mdx": "---\ntitle: \"Configure and secure\"\ndescription: \"Control settings, providers, credentials, networking, secrets, sandboxing, and runtime boundaries.\"\nsidebar:\n  order: 0\n  label: \"Overview\"\n---\n\nConfiguration controls provider routing, settings precedence, filesystem access, and credential handling.\n\n## What should I configure first?\n\n1. Inspect [settings precedence and file locations](/xcsh/en/configure-secure/settings-files/).\n2. Look up any [environment variable](/xcsh/en/configure-secure/environment-reference/) the deployment sets.\n3. Choose a [provider and model route](/xcsh/en/configure-secure/providers-routing/).\n4. Apply [secret handling and the filesystem boundary](/xcsh/en/configure-secure/secrets-obfuscation/).\n5. Set the [sandbox boundaries](/xcsh/en/configure-secure/sandbox-boundaries/) that enforce those decisions.\n\nStart with defaults; add project configuration only when collaborators need the same behavior.\n",
-	"en/configure-secure/providers-routing.mdx": "---\ntitle: \"Configure providers and model routing\"\ndescription: \"Select models directly or map default, smol, slow, and plan roles.\"\nsidebar:\n  order: 3\n  label: \"Providers and models\"\nhead:\n  - tag: style\n    content: |\n      .sl-markdown-content .expressive-code { max-width: 100%; overflow-x: auto; }\n      .sl-markdown-content table { display: block; max-width: 100%; overflow-x: auto; }\n---\n\nxcsh resolves a requested model against available providers and credentials. A provider-qualified model name is the most explicit route.\n\n## How do I confirm a route?\n\nRun `xcsh --list-models <PROVIDER>`, then pass one returned name to `--model`. Environment keys and supported subscription sessions authenticate providers; never store tokens in committed settings.\n\n## How do I select a model in a conversation?\n\nOpen `/model`. Tab and Shift+Tab browse providers; typing searches across them. The active conversation model and saved role badges are shown separately. Configured providers remain visible when discovery is empty, unavailable, or requires authentication. Use Ctrl+R to refresh the current provider or Ctrl+L to open login.\n\nChoose a model with Enter, then choose its scope:\n\n- **Use in this conversation** is preselected. It changes this session, including resume, without changing saved role assignments.\n- **Save as default** changes the current conversation and the default for future sessions.\n- **Assign to role** saves Default, Fast/SMOL, Thorough/SLOW, Plan, or another existing role. Roles other than Default leave the current conversation unchanged.\n\nChoose a reasoning level supported by that exact model and press Enter to confirm. Inherit displays the provider default; an existing supported reasoning selection is preselected. Escape backs out without applying an unfinished choice. Failed writes are reported before badges show success.\n\nClaude Fable 5 and 5.1 use adaptive thinking on every request. Their default is `high`; supported\nchoices are `low`, `medium`, `high`, `xhigh`, and `max`, with xcsh's `minimal` choice mapped to\nAnthropic `low`. `off` is rejected because the Fable API does not support disabling thinking.\nFable also does not accept temperature or forced tool selection, so xcsh omits temperature and\nnormalizes `any` or a named forced tool to `auto` while retaining strict tool schemas.\n\nWhen the authenticated ChatGPT subscription catalog includes GPT-6 Astra, `/model` presents it as an additional premium option under **ChatGPT Subscription**. Astra does not replace the existing Luna, Terra, Sol, or role assignments unless you explicitly assign it.\n\nA manual conversation choice remains in effect under automatic routing. Entering planning mode uses the Plan assignment; exiting restores the prior conversation model and reasoning. Explicit `--models` scopes still limit the picker.\n\nOpen `/login` to see providers that are configured, credential-backed, allowlisted, active, or freshly detected. Optional local runtimes do not appear merely because xcsh attempted an automatic probe. Choose `Add provider…` to search the complete built-in catalog.\n\nProvider rows use human status labels. Press Right on a row to inspect its credential source, last verification, sanitized failure reason, model visibility, and any grouped routes. `/logout` lists only providers with stored credentials that xcsh can remove; environment and configuration credentials are not presented as removable.\n\nProvider grouping in `models.yml` is also used by the management view:\n\n```yaml\nproviders:\n  litellm:\n    picker:\n      groupId: litellm\n      groupLabel: LiteLLM\n      sectionLabel: OpenAI\n    modelAllowlist:\n      - gpt-6-astra\n      - gpt-5.6-sol\n      - gpt-5.6-terra\n      - gpt-5.6-luna\n  anthropic:\n    picker:\n      groupId: litellm\n      groupLabel: LiteLLM\n      sectionLabel: Anthropic\n    modelAllowlist:\n      - claude-fable-5-1\n      - claude-fable-5\n      - claude-opus-5\n      - claude-sonnet-5\n      - claude-haiku-4-5\n```\n\n`modelProviderAllowlist` is a settings key that limits normal `/model` visibility. An empty list means no picker restriction; it does not make every built-in provider relevant in `/login`. Explicit provider-qualified command-line selection and direct `/login <provider>` remain available.\n\n```bash\nxcsh config set modelProviderAllowlist '[\"litellm\", \"anthropic\"]'\nxcsh config set modelProviderOrder '[\"litellm\", \"anthropic\", \"google-vertex\"]'\n```\n\nFor command-line selection, qualify the provider whenever several usable providers expose the same model ID. A bare `--model` value succeeds only when one usable provider matches; otherwise xcsh prints the qualified choices and exits nonzero in noninteractive mode.\n\nThe two explicit Fable aliases are an exception to general fuzzy selection:\n\n```bash\nxcsh --model fable\nxcsh --model anthropic/fable\n```\n\nBoth select `anthropic/claude-fable-5-1` deterministically.\n\n## Where does LiteLLM fit?\n\nLiteLLM is an optional provider proxy installed or checked with `xcsh setup litellm`. Its base uniform resource locator (URL) and credential belong in the runtime environment. Successful text Responses support does not imply Realtime or audio support; test the exact endpoint your workflow uses.\n\nGPT-6 Astra has route-specific limits. xcsh-generated LiteLLM configuration exposes the model's full\n1,050,000-token context window (922,000 input plus up to 128,000 output). The ChatGPT Codex subscription\ntransport remains at 272,000 context with the same 128,000 maximum output because upstream deliberately\nkeeps that route in its short-context pricing tier. Both routes support image input and `low`, `medium`,\n`high`, `xhigh`, and `max` reasoning. Astra is selectable explicitly but is not assigned to an automatic\nrole by default.\n\n## How do I test licensed Vertex locally?\n\n`bun run dev` and local coding-agent binary builds load the licensed Vertex OAuth client pair automatically. Explicit `XCSH_VERTEX_OAUTH_CLIENT_ID` and `XCSH_VERTEX_OAUTH_CLIENT_SECRET` build inputs take precedence; supply both together.\n\nFor local UAT, the first launch can recover the embedded client pair from an installed official xcsh binary\nand retain it in `$XDG_CONFIG_HOME/xcsh/vertex-build.json` (default `~/.config/xcsh/vertex-build.json`). The\nfile is outside the checkout, shared by local sessions and worktrees for the same operating-system user, and\ncreated with owner-only permissions. Each worktree needs this development/build launcher to load it\nautomatically. Later launches reuse it even if the installed binary changes.\n`XCSH_VERTEX_OAUTH_CREDENTIALS_FILE` selects another private local file containing `clientId` and\n`clientSecret` fields.\n\nThe source-runtime preload keeps the pair in process memory; local compiled candidates embed it. Do not copy\nthis file or its values into source control, logs, or UAT reports. CI does not read or recover workstation\ncredentials: official release builds continue to receive the pair through GitHub secrets. Unit tests use\nfixture credentials; the live provider smoke script uses the same local preload as development UAT.\n\nRoute selection is complete only when the provider, account, and model all match the intended\nboundary. Use `/model` in the TUI or the explicit model flag shown by `xcsh --help`, send a no-tool\nidentity prompt, and inspect the session metadata. Switching a model affects subsequent turns; it\ndoes not rewrite earlier entries. Remove temporary route overrides and start a new session to verify\nthe default path independently.\n",
+	"en/configure-secure/providers-routing.mdx": "---\ntitle: \"Configure providers and model routing\"\ndescription: \"Select models directly or map default, smol, slow, and plan roles.\"\nsidebar:\n  order: 3\n  label: \"Providers and models\"\nhead:\n  - tag: style\n    content: |\n      .sl-markdown-content .expressive-code { max-width: 100%; overflow-x: auto; }\n      .sl-markdown-content table { display: block; max-width: 100%; overflow-x: auto; }\n---\n\nxcsh resolves a requested model against available providers and credentials. A provider-qualified model name is the most explicit route.\n\n## How do I confirm a route?\n\nRun `xcsh --list-models <PROVIDER>`, then pass one returned name to `--model`. Environment keys and supported subscription sessions authenticate providers; never store tokens in committed settings.\n\n## How do I select a model in a conversation?\n\nOpen `/model`. Tab and Shift+Tab browse providers; typing searches across them. The active conversation model and saved role badges are shown separately. Configured providers remain visible when discovery is empty, unavailable, or requires authentication. Use Ctrl+R to refresh the current provider or Ctrl+L to open login.\n\nChoose a model with Enter, then choose its scope:\n\n- **Use in this conversation** is preselected. It changes this session, including resume, without changing saved role assignments.\n- **Save as default** changes the current conversation and the default for future sessions.\n- **Assign to role** saves Default, Fast/SMOL, Thorough/SLOW, Plan, or another existing role. Roles other than Default leave the current conversation unchanged.\n\nChoose a reasoning level supported by that exact model and press Enter to confirm. Inherit displays the provider default; an existing supported reasoning selection is preselected. Escape backs out without applying an unfinished choice. Failed writes are reported before badges show success.\n\nClaude Fable 5 and 5.1 use adaptive thinking on every request. Their default is `high`; supported\nchoices are `low`, `medium`, `high`, `xhigh`, and `max`, with xcsh's `minimal` choice mapped to\nAnthropic `low`. `off` is rejected because the Fable API does not support disabling thinking.\nFable also does not accept temperature or forced tool selection, so xcsh omits temperature and\nnormalizes `any` or a named forced tool to `auto` while retaining strict tool schemas.\n\nWhen the authenticated ChatGPT subscription catalog includes GPT-6 Astra, `/model` presents it as an additional premium option under **ChatGPT Subscription**. Astra does not replace the existing Luna, Terra, Sol, or role assignments unless you explicitly assign it.\n\nA manual conversation choice remains in effect under automatic routing. Entering planning mode uses the Plan assignment; exiting restores the prior conversation model and reasoning. Explicit `--models` scopes still limit the picker.\n\nOpen `/login` to see providers that are configured, credential-backed, allowlisted, active, or freshly detected. Optional local runtimes do not appear merely because xcsh attempted an automatic probe. Choose `Add provider…` to search the complete built-in catalog.\n\nProvider rows use human status labels. Press Right on a row to inspect its credential source, last verification, sanitized failure reason, model visibility, and any grouped routes. `/logout` lists only providers with stored credentials that xcsh can remove; environment and configuration credentials are not presented as removable.\n\nProvider grouping in `models.yml` is also used by the management view:\n\n```yaml\nproviders:\n  litellm:\n    picker:\n      groupId: litellm\n      groupLabel: LiteLLM\n      sectionLabel: OpenAI\n    modelAllowlist:\n      - gpt-6-astra\n      - gpt-5.6-sol\n      - gpt-5.6-terra\n      - gpt-5.6-luna\n  anthropic:\n    picker:\n      groupId: litellm\n      groupLabel: LiteLLM\n      sectionLabel: Anthropic\n    modelAllowlist:\n      - claude-fable-5-1\n      - claude-fable-5\n      - claude-opus-5\n      - claude-sonnet-5\n      - claude-haiku-4-5\n```\n\n`modelProviderAllowlist` is a settings key that limits normal `/model` visibility. An empty list means no picker restriction; it does not make every built-in provider relevant in `/login`. Explicit provider-qualified command-line selection and direct `/login <provider>` remain available.\n\n```bash\nxcsh config set modelProviderAllowlist '[\"litellm\", \"anthropic\"]'\nxcsh config set modelProviderOrder '[\"litellm\", \"anthropic\", \"google-vertex\"]'\n```\n\nFor command-line selection, qualify the provider whenever several usable providers expose the same model ID. A bare `--model` value succeeds only when one usable provider matches; otherwise xcsh prints the qualified choices and exits nonzero in noninteractive mode.\n\nThe two explicit Fable aliases are an exception to general fuzzy selection:\n\n```bash\nxcsh --model fable\nxcsh --model anthropic/fable\n```\n\nBoth select `anthropic/claude-fable-5-1` deterministically.\n\n## Where does LiteLLM fit?\n\nLiteLLM is an optional provider proxy installed or checked with `xcsh setup litellm`. Its base uniform resource locator (URL) and credential belong in the runtime environment. Successful text Responses support does not imply Realtime or audio support; test the exact endpoint your workflow uses.\n\nGPT-6 Astra has route-specific limits. xcsh-generated LiteLLM configuration exposes the model's full\n1,050,000-token context window (922,000 input plus up to 128,000 output). xcsh uses the ChatGPT Codex\nsubscription catalog's 272,000-token effective context window and 128,000-token maximum output. That\ncatalog also advertises an 872,000-token maximum context window, which can be available when the Codex\ntransport expands its effective window. Both routes support image input and `low`, `medium`, `high`,\n`xhigh`, and `max` reasoning. Astra is selectable explicitly but is not assigned to an automatic role by\ndefault.\n\nGenerated LiteLLM configuration routes only Astra through LiteLLM's OpenAI Responses endpoint\n(`/openai/v1/responses`). This is required when Astra uses tools with reasoning: its Chat Completions route\nrejects that combination. Luna, Terra, and Sol keep the configured OpenAI-compatible Chat Completions base\npath. Astra also omits temperature because the Responses route rejects sampling temperature for that model.\n\n## How do I test licensed Vertex locally?\n\n`bun run dev` and local coding-agent binary builds load the licensed Vertex OAuth client pair automatically. Explicit `XCSH_VERTEX_OAUTH_CLIENT_ID` and `XCSH_VERTEX_OAUTH_CLIENT_SECRET` build inputs take precedence; supply both together.\n\nFor local UAT, the first launch can recover the embedded client pair from an installed official xcsh binary\nand retain it in `$XDG_CONFIG_HOME/xcsh/vertex-build.json` (default `~/.config/xcsh/vertex-build.json`). The\nfile is outside the checkout, shared by local sessions and worktrees for the same operating-system user, and\ncreated with owner-only permissions. Each worktree needs this development/build launcher to load it\nautomatically. Later launches reuse it even if the installed binary changes.\n`XCSH_VERTEX_OAUTH_CREDENTIALS_FILE` selects another private local file containing `clientId` and\n`clientSecret` fields.\n\nThe source-runtime preload keeps the pair in process memory; local compiled candidates embed it. Do not copy\nthis file or its values into source control, logs, or UAT reports. CI does not read or recover workstation\ncredentials: official release builds continue to receive the pair through GitHub secrets. Unit tests use\nfixture credentials; the live provider smoke script uses the same local preload as development UAT.\n\nRoute selection is complete only when the provider, account, and model all match the intended\nboundary. Use `/model` in the TUI or the explicit model flag shown by `xcsh --help`, send a no-tool\nidentity prompt, and inspect the session metadata. Switching a model affects subsequent turns; it\ndoes not rewrite earlier entries. Remove temporary route overrides and start a new session to verify\nthe default path independently.\n",
 	"en/configure-secure/sandbox-boundaries.mdx": "---\ntitle: \"Set sandbox boundaries\"\ndescription: \"Constrain filesystem, shell, native, browser, and extension effects at the layer that enforces them.\"\nsidebar:\n  order: 5\n  label: \"Sandbox boundaries\"\n---\n\nA model instruction is not a sandbox. Enforcement belongs to the tool, host process, container, operating system, or remote service that performs the action.\n\n## How do I restrict the exposed tool set?\n\nStart with `--no-tools` or an explicit `--tools` allow-list when a run needs only conversation. Disable Model Context Protocol (MCP) and extensions separately because they can register additional capabilities. Review custom tool and hook code with the same care as any locally executed module.\n\n## How do I constrain files and processes?\n\nFilesystem-aware tools resolve paths against their configured workspace boundary. The Bash runtime applies its sandbox and output limits before returning a result; large output may spill to an artifact instead of remaining inline. Containers add process and filesystem isolation, but mounted credentials and sockets still cross that boundary.\n\n## Where does remote authority differ from local authority?\n\nBrowser, editor, Office, and remote-service integrations enforce different permission models. Confirm the active host, account, context, namespace, and target immediately before a mutation. A successful read proves connectivity, not authorization for a write.\n\nSandboxing constrains the local tool implementation; it does not grant remote authority and it\ncannot retract a side effect already accepted by an external service. Begin with no tools, add the\nminimum file or process capability, and test an allowed path plus a denied path. Verify denial at\nthe tool boundary and inspect the filesystem or process table for absence of change. Restore the\nnarrower configuration after the test.\n",
 	"en/configure-secure/secrets-obfuscation.mdx": "---\ntitle: \"Resolve secrets safely\"\ndescription: \"Reference sensitive values without placing plaintext credentials in prompts, manifests, logs, or commits.\"\nsidebar:\n  order: 4\n  label: \"Resolve secrets safely\"\n---\n\nKeep provider keys and F5 Distributed Cloud contexts outside prompts, session exports, logs, and committed files. Pass secrets through supported environment or protected runtime files.\n\n## How does obfuscation work?\n\nWhen secret obfuscation is enabled, values declared in the protected `secrets.yml` source are resolved at runtime and replaced in observable text before it is retained or rendered. Environment values take their documented precedence over file-backed values.\n\nObfuscation reduces accidental disclosure in supported paths; it is not encryption for a compromised process or an excuse to place secrets in prompts.\n\n## How does the filesystem boundary work?\n\nxcsh discovers a task root and guards access outside it. Add an explicit path with `--allow-path`; use `--allow-home` only when the home directory is intentionally the task root. `--no-sandbox` removes that guard and should be reserved for a controlled diagnostic.\n\n## How do I inspect the boundary?\n\nRun `xcsh sandbox check`, then start a read-only session with the smallest required `--allow-path` set. A sandbox boundary limits file discovery; it does not replace operating-system permissions or tool review.\n\nRedaction reduces accidental disclosure in model and display paths; it is not encryption and does\nnot make a committed secret safe. Test with a synthetic value in an isolated process, inspect the\nprompt, tool result, logs, and exported session, then unset the value and remove the temporary rule.\nIf any surface retains the literal, stop before using a real credential and correct the boundary\nthat emitted it.\n",
 	"en/configure-secure/settings-files.mdx": "---\ntitle: \"Understand settings precedence\"\ndescription: \"Predict which user, project, environment, and command-line value xcsh resolves.\"\nsidebar:\n  order: 1\n  label: \"Settings precedence\"\n---\n\nProject settings apply to one repository; user settings apply across projects; command flags override both for one invocation. Use `xcsh config list --json` to inspect effective values.\n\n## How is configuration resolved?\n\nDiscovery collects fixed user, project, environment, and command-line sources, normalizes each through the schema-backed configuration wrapper, then resolves values by explicit priority. Capability-specific discovery uses the same roots but owns its own merge and deduplication rules. Native `.xcsh` providers participate through the documented provider interface, not an implicit recursive scan.\n\n## Where are settings stored?\n\nRun `xcsh config path` instead of assuming a platform path. Project data uses `.xcsh/`, including `settings.json`, `mcp.json`, contexts, skills, agents, extensions, tools, hooks, commands, and `XCSH.md`. Primary user data lives under the xcsh agent directory; `PI_CODING_AGENT_DIR` can override that location.\n\n## How do I change one value?\n\n```bash\nxcsh config get <KEY>\nxcsh config set <KEY> <VALUE>\nxcsh config reset <KEY>\n```\n\nUse environment variables for credentials and ephemeral process configuration. Do not copy an entire old settings file when only one key is needed.\n\nChange one key in the narrowest applicable scope and restart xcsh before judging precedence. Use `/settings` or a schema-backed read path to inspect the effective value; do not infer it from the file you edited. Project settings can affect collaborators, while user settings affect other worktrees on the same account. Revert the test key and confirm a new process resolves the prior value.\n",

package/src/modes/components/request-user-input.ts

@@ -3,6 +3,16 @@ import { INPUT_COPY, type InputQuestion, type InputResponse } from "../../../../
 import { QuestionForm } from "../../../../chat-ui/src/interactions/question-form";
 import { getEditorTheme } from "../theme/theme";
 
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function maskedEditorLines(text: string, width: number): string[] {
+	const masked = text
+		.split("\n")
+		.map(line => [...graphemes.segment(line)].map(() => "*").join(""))
+		.join("\n");
+	return masked.split("\n").flatMap(line => wrapTextWithAnsi(line, Math.max(1, width)));
+}
+
 /** Uses the ordinary multiline composer; form state stays local until explicit submission. */
 export class RequestUserInputComponent implements Component {
 	readonly form: QuestionForm;
@@ -63,7 +73,11 @@ export class RequestUserInputComponent implements Component {
 			add("");
 			add(this.form.options.length ? INPUT_COPY.notes : INPUT_COPY.answer);
 			this.#editor.setMaxHeight(Math.max(3, (this.tui.terminal.rows || 24) - lines.length - 3));
-			lines.push(...this.#editor.render(Math.max(1, width)));
+			lines.push(
+				...(this.form.question.isSecret
+					? maskedEditorLines(this.#editor.getText(), Math.max(1, width))
+					: this.#editor.render(Math.max(1, width))),
+			);
 		}
 		add("");
 		add(
@@ -101,6 +115,10 @@ export class RequestUserInputComponent implements Component {
 		} else if (matchesKey(data, "tab")) {
 			this.form.toggleNotes();
 			this.#restore();
+		} else if (!this.form.notesVisible && data === " ") this.form.commitSelection();
+		else if (!this.form.notesVisible && (matchesKey(data, "backspace") || matchesKey(data, "delete"))) {
+			this.form.clearSelection();
+			this.#restore();
 		} else if (enter) this.#submit();
 		else if (
 			matchesKey(data, "ctrl+p") ||
@@ -120,7 +138,7 @@ export class RequestUserInputComponent implements Component {
 		else if (keys.matches(data, "tui.select.up")) this.form.moveOption(-1);
 		else if (keys.matches(data, "tui.select.down")) this.form.moveOption(1);
 		else if (/^[1-9]$/.test(data) && Number(data) <= this.form.options.length) {
-			this.form.moveOption(Number(data) - 1 - this.form.draft.highlighted);
+			this.form.selectOption(Number(data) - 1);
 			this.#submit();
 		}
 		this.tui.requestRender();

package/src/remote-control/session.ts

@@ -161,6 +161,7 @@ export class RemoteSession {
 	#unsubscribeTransitions?: () => void;
 	#unsubscribeDispose?: () => void;
 	#unsubscribeTitle?: () => void;
+	#unsubscribeInteractionStatus?: () => void;
 	#interactions?: RemoteInteractions;
 	#effects = new Set<Promise<unknown>>();
 	#voiceHistoryOwner!: SessionVoiceHistory;
@@ -189,7 +190,7 @@ export class RemoteSession {
 	#startedAtMs = 0;
 	#lastProviderUsage?: Usage;
 	#usageEmitted = new Set<string>();
-	#threadStatus: "active" | "idle" = "idle";
+	#threadStatus = JSON.stringify({ type: "idle" });
 	get #durable(): boolean {
 		return typeof this.target.sessionManager.getBranch === "function";
 	}
@@ -278,6 +279,9 @@ export class RemoteSession {
 					void this.target.abort();
 				},
 			);
+		if (target.userInteractions)
+			this.#unsubscribeInteractionStatus = target.userInteractions.subscribe(() => this.#emitThreadStatus());
+		this.#threadStatus = JSON.stringify(this.#threadStatusValue());
 		this.#unsubscribeDispose = target.addBeforeDisposeHook?.(() => this.close());
 		this.#unsubscribeTitle = subscribeSessionTitle(target.sessionManager, title =>
 			this.#emit("thread/name/updated", { threadName: title }),
@@ -334,7 +338,7 @@ export class RemoteSession {
 				this.#hydrateActiveStream();
 			}
 		}
-		this.#threadStatus = this.#active || this.target.isStreaming ? "active" : "idle";
+		this.#threadStatus = JSON.stringify(this.#threadStatusValue());
 	}
 	#historyToolContext(message: AgentMessage): HistoryToolContext | undefined {
 		if (message.role === "bashExecution" || message.role === "pythonExecution")
@@ -402,6 +406,7 @@ export class RemoteSession {
 		this.#unsubscribeTransitions?.();
 		this.#unsubscribeDispose?.();
 		this.#unsubscribeTitle?.();
+		this.#unsubscribeInteractionStatus?.();
 		for (const cancel of this.#cancelDelegations) cancel();
 		this.#unsubscribe();
 		this.#interactions?.close();
@@ -439,12 +444,22 @@ export class RemoteSession {
 		this.#updatedAt = Math.floor(Date.now() / 1000);
 		for (const listener of this.#listeners) listener({ method, params: { ...params, threadId: this.#threadId } });
 	}
-	#emitThreadStatus(status: "active" | "idle"): void {
-		if (this.#threadStatus === status) return;
-		this.#threadStatus = status;
-		this.#emit("thread/status/changed", {
-			status: status === "active" ? { type: "active", activeFlags: [] } : { type: "idle" },
-		});
+	#threadStatusValue(
+		runtimeActive = Boolean(this.#active) || this.target.isStreaming,
+	): { type: "active"; activeFlags: string[] } | { type: "idle" } {
+		const waiting =
+			this.target.userInteractions?.waitingOnUserInput === true ||
+			this.target.conversationPlans?.current?.status === "pending";
+		return runtimeActive || waiting
+			? { type: "active", activeFlags: waiting ? ["waitingOnUserInput"] : [] }
+			: { type: "idle" };
+	}
+	#emitThreadStatus(runtimeStatus?: "active" | "idle"): void {
+		const status = this.#threadStatusValue(runtimeStatus === undefined ? undefined : runtimeStatus === "active");
+		const serialized = JSON.stringify(status);
+		if (this.#threadStatus === serialized) return;
+		this.#threadStatus = serialized;
+		this.#emit("thread/status/changed", { status });
 	}
 	#usageBreakdown(usage: Usage) {
 		return {
@@ -653,7 +668,7 @@ export class RemoteSession {
 			createdAt: this.#createdAt,
 			updatedAt: this.#updatedAt,
 			recencyAt: this.#updatedAt,
-			status: this.target.isStreaming || this.#active ? { type: "active", activeFlags: [] } : { type: "idle" },
+			status: this.#threadStatusValue(),
 			path: this.target.sessionFile ?? null,
 			cwd: this.target.sessionManager.getCwd(),
 			cliVersion: this.version,
@@ -1581,6 +1596,7 @@ export class RemoteSession {
 		}
 		if (event.type === "plan_available" || event.type === "plan_resolved") {
 			this.#emit("xcsh/interaction/plan", { contract: "xcsh.interaction.v1", event });
+			this.#emitThreadStatus();
 			return;
 		}
 		if (event.type === "async_user_input") {

package/src/session/agent-session.ts

@@ -65,6 +65,7 @@ import {
 	Snowflake,
 	setNativeKillTree,
 } from "@f5-sales-demo/pi-utils";
+import { createAsyncQuestionItem } from "../../../chat-ui/src/interactions/contract";
 import {
 	type ConversationPlan,
 	ConversationPlans,
@@ -807,6 +808,7 @@ export class AgentSession {
 					pane_id: process.env.HERDR_PANE_ID,
 					producer: "xcsh",
 					generation: Number(herdrGeneration),
+					session_id: this.sessionId,
 				},
 				() => {
 					void this.#emitSessionEvent({
@@ -815,7 +817,7 @@ export class AgentSession {
 						message: "Herdr interaction delivery is unavailable; local questions remain available.",
 					});
 				},
-				process.env.HERDR_NATIVE_CAPABILITY,
+				process.env.HERDR_NATIVE_CAPABILITY ?? process.env.HERDR_INTERACTION_CAPABILITY,
 			);
 			this.addBeforeDisposeHook(() => this.#herdrInteractions!.close());
 			this.addDisposeHook(
@@ -929,16 +931,7 @@ export class AgentSession {
 		questions: import("../../../chat-ui/src/interactions/contract").AsyncInputQuestion[],
 		questionIds: string[],
 	): void {
-		const item = {
-			id: itemId,
-			type: "agentMessage" as const,
-			text: questions
-				.map(question => [question.title, ...(question.options?.map(option => `- ${option}`) ?? [])].join("\n"))
-				.join("\n\n"),
-			phase: "final_answer" as const,
-			delivery: "async" as const,
-			questions: structuredClone(questions),
-		};
+		const item = createAsyncQuestionItem(itemId, questions);
 		this.sessionManager.appendCustomMessageEntry("async-user-input", item.text, true, { item, questionIds }, "agent");
 		void this.#emitSessionEvent({ type: "async_user_input", item, questionIds });
 	}

package/src/session/user-interactions.ts

@@ -1,7 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { type InputQuestion, type InputResponse, validInputResponse } from "../../../chat-ui/src/interactions/contract";
+import {
+	type AsyncInputQuestion,
+	type AsyncQuestionItem,
+	type InputQuestion,
+	type InputResponse,
+	validInputResponse,
+} from "../../../chat-ui/src/interactions/contract";
 import { isInteractionFrame, isInteractionIdentity } from "../../../chat-ui/src/interactions/transport";
 
 const toolCalls = new AsyncLocalStorage<string>();
@@ -20,6 +26,12 @@ export interface UserInteractionSpec {
 	options?: readonly string[];
 	toolCallId?: string;
 	isSecret?: boolean;
+	asyncBatch?: {
+		requestId: string;
+		questionIds: readonly string[];
+		questions: readonly AsyncInputQuestion[];
+		item: AsyncQuestionItem;
+	};
 }
 export interface UserInteraction extends UserInteractionSpec {
 	id: string;
@@ -210,13 +222,14 @@ export class UserInteractions {
 	}
 	requestAsyncBatch(
 		specs: readonly (UserInteractionSpec & { kind: "input"; delivery: "async" })[],
+		batch?: NonNullable<UserInteractionSpec["asyncBatch"]>,
 	): Promise<string | undefined>[] {
 		if (this.#closed || this.#cancelling) throw new Error("Session interaction owner unavailable");
 		if (!specs.length || this.#pending.size + specs.length > 32)
 			throw new Error("Too many pending user interactions");
 		this.#batchDepth++;
 		try {
-			return specs.map(spec => this.request(spec));
+			return specs.map(spec => this.request({ ...spec, ...(batch ? { asyncBatch: batch } : {}) }));
 		} finally {
 			this.#batchDepth--;
 			this.#flushNotifications();

package/src/tools/request-user-input.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolResult } from "@f5-sales-demo/pi-agent-core";
 import { type Static, Type } from "@sinclair/typebox";
-import type { AsyncInputQuestion } from "../../../chat-ui/src/interactions/contract";
+import { type AsyncInputQuestion, createAsyncQuestionItem } from "../../../chat-ui/src/interactions/contract";
 import asyncDescription from "../prompts/tools/request-user-input-async.md" with { type: "text" };
 import type { ToolSession } from ".";
 import { ToolAbortError, ToolError } from "./tool-errors";
@@ -114,6 +114,7 @@ export class RequestUserInputAsyncTool implements AgentTool<typeof requestUserIn
 		if (!owner) throw new ToolError("Session interaction owner unavailable");
 		const identity = this.session.getInteractionIdentity?.(callId);
 		const questionIds = args.questions.map((_, index) => `${callId}:${index}`);
+		const item = createAsyncQuestionItem(callId, args.questions as AsyncInputQuestion[]);
 		const pending = owner.requestAsyncBatch(
 			args.questions.map((question, index) => ({
 				kind: "input",
@@ -124,6 +125,7 @@ export class RequestUserInputAsyncTool implements AgentTool<typeof requestUserIn
 				toolCallId: callId,
 				identity,
 			})),
+			{ requestId: callId, questionIds, questions: item.questions, item },
 		);
 		for (const [index, result] of pending.entries()) {
 			void result