@f5-sales-demo/xcsh 21.34.0 → 21.35.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.34.0",
+	"version": "21.35.1",
 	"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.34.0",
-		"@f5-sales-demo/pi-ai": "21.34.0",
-		"@f5-sales-demo/pi-natives": "21.34.0",
-		"@f5-sales-demo/pi-resource-management": "21.34.0",
-		"@f5-sales-demo/pi-tui": "21.34.0",
-		"@f5-sales-demo/pi-utils": "21.34.0",
-		"@f5-sales-demo/xcsh-stats": "21.34.0",
+		"@f5-sales-demo/pi-agent-core": "21.35.1",
+		"@f5-sales-demo/pi-ai": "21.35.1",
+		"@f5-sales-demo/pi-natives": "21.35.1",
+		"@f5-sales-demo/pi-resource-management": "21.35.1",
+		"@f5-sales-demo/pi-tui": "21.35.1",
+		"@f5-sales-demo/pi-utils": "21.35.1",
+		"@f5-sales-demo/xcsh-stats": "21.35.1",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "0.34.52",
 		"@xterm/headless": "^6.0",

package/src/browser/capabilities.generated.ts

@@ -837,6 +837,18 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 					"annotation": "Annotate the page for documentation and teaching."
 				}
 			}
+		},
+		"interactions": {
+			"contract": "xcsh.interaction.v1",
+			"waiting": "request_user_input",
+			"asynchronous": "request_user_input_async",
+			"planActions": [
+				"implement",
+				"fresh",
+				"stay"
+			],
+			"snapshot": true,
+			"responseReceipts": true
 		}
 	}
 };

package/src/browser/capabilities.json

@@ -421,7 +421,7 @@
     },
     {
       "name": "query_dom",
-      "summary": "Direct DOM.querySelector at wire speed — bypasses Runtime.evaluate for simple CSS selectors.",
+      "summary": "Direct DOM.querySelector at wire speed \u2014 bypasses Runtime.evaluate for simple CSS selectors.",
       "category": "read",
       "params": {
         "type": "object",
@@ -584,7 +584,7 @@
     },
     {
       "name": "diag_ttft",
-      "summary": "Diagnostic: init→first-token timeline (per-stage ms, total, dominant, cold/warm).",
+      "summary": "Diagnostic: init\u2192first-token timeline (per-stage ms, total, dominant, cold/warm).",
       "category": "read",
       "params": {
         "type": "object",
@@ -675,7 +675,7 @@
     },
     {
       "name": "set_explain_mode",
-      "summary": "Enter/leave explain mode — the gate for all on-page annotation overlays.",
+      "summary": "Enter/leave explain mode \u2014 the gate for all on-page annotation overlays.",
       "category": "annotation",
       "params": {
         "type": "object",
@@ -740,7 +740,7 @@
     },
     "capture": {
       "tool": "screenshot",
-      "description": "Capture a screenshot (base64 PNG) — for headless annotated-capture flows."
+      "description": "Capture a screenshot (base64 PNG) \u2014 for headless annotated-capture flows."
     },
     "viewport": {
       "tool": "resize_window",
@@ -777,12 +777,12 @@
         "media_asset_chunk",
         "media_asset_error"
       ],
-      "description": "User ↔ xcsh chat over the bridge. The extension side panel sends chat_request (with mode and page-context snapshot); xcsh streams ordered assistant items using chat_message_start, correlated chat_delta tokens, and chat_message_end. Each item declares commentary or final_answer phase. Exactly one terminal chat_done (with reference links) or chat_error closes the whole turn. Chat ids are prefixed \"c-\". Tool calls during a turn use the normal tool_request flow. chat_stop halts a streaming response. chat_tool_notice is emitted by the EXTENSION (the service worker) to the panel as a best-effort UI signal when a tool runs during a turn — it is NOT sent by xcsh; xcsh must not produce it to avoid double-rendering in the panel. Rich media uses chat_media descriptors and bounded media_asset_read/media_asset_chunk exchanges; media_asset_error reports unavailable assets.",
+      "description": "User \u2194 xcsh chat over the bridge. The extension side panel sends chat_request (with mode and page-context snapshot); xcsh streams ordered assistant items using chat_message_start, correlated chat_delta tokens, and chat_message_end. Each item declares commentary or final_answer phase. Exactly one terminal chat_done (with reference links) or chat_error closes the whole turn. Chat ids are prefixed \"c-\". Tool calls during a turn use the normal tool_request flow. chat_stop halts a streaming response. chat_tool_notice is emitted by the EXTENSION (the service worker) to the panel as a best-effort UI signal when a tool runs during a turn \u2014 it is NOT sent by xcsh; xcsh must not produce it to avoid double-rendering in the panel. Rich media uses chat_media descriptors and bounded media_asset_read/media_asset_chunk exchanges; media_asset_error reports unavailable assets.",
       "promptHints": {
         "role": "You are xcsh, the AI assistant embedded in the F5 Distributed Cloud (XC) console side panel. The user is viewing a live console page; help them drive automation and understand settings and their purpose.",
-        "grounding": "Every user message carries a page-context snapshot: url/path, title, a trimmed accessibility tree, and — when available — the live XC API resource JSON the page loaded (context.api.body). Treat context.api.body as the authoritative current state of the resource and ground answers in it instead of guessing; respect the truncated flags.",
+        "grounding": "Every user message carries a page-context snapshot: url/path, title, a trimmed accessibility tree, and \u2014 when available \u2014 the live XC API resource JSON the page loaded (context.api.body). Treat context.api.body as the authoritative current state of the resource and ground answers in it instead of guessing; respect the truncated flags.",
         "referenceLinks": "Emit every citation as a markdown link [title](url): F5 XC docs (docs.cloud.f5.com) as doc references and the tenant console host as console deep-links. These populate the panel References drawer, so always format references this way rather than as bare URLs.",
-        "toolUse": "Drive the console with the extension tools via the normal tool_request flow (navigate, click, annotate, screenshot, get_page_context, and so on). The extension surfaces tool activity to the panel itself (chat_tool_notice) — never emit chat_tool_notice yourself. Each turn ends with exactly one terminal frame, which the transport handles.",
+        "toolUse": "Drive the console with the extension tools via the normal tool_request flow (navigate, click, annotate, screenshot, get_page_context, and so on). The extension surfaces tool activity to the panel itself (chat_tool_notice) \u2014 never emit chat_tool_notice yourself. Each turn ends with exactly one terminal frame, which the transport handles.",
         "modes": {
           "educational": "Explain concepts and answer questions about settings and their purpose.",
           "presentation": "Guided, human-paced walkthrough/demo of the console.",
@@ -791,6 +791,18 @@
           "annotation": "Annotate the page for documentation and teaching."
         }
       }
+    },
+    "interactions": {
+      "contract": "xcsh.interaction.v1",
+      "waiting": "request_user_input",
+      "asynchronous": "request_user_input_async",
+      "planActions": [
+        "implement",
+        "fresh",
+        "stay"
+      ],
+      "snapshot": true,
+      "responseReceipts": true
     }
   }
 }

package/src/browser/chat-handler.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AssistantMessage, AssistantMessagePhase, ImageContent } from "@f5-sales-demo/pi-ai";
+import { isInteractionCommand } from "../../../chat-ui/src/interactions/transport";
 import { parseModelString } from "../config/model-resolver";
 import { settings } from "../config/settings";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
@@ -112,6 +113,7 @@ export class ChatHandler {
 	// and awaits the correlated `host_tool_result`. Reused verbatim from the stdio RPC
 	// driver — the only WS-specific wiring is the `send()` output sink below.
 	#hostToolBridge: RpcHostToolBridge;
+	#unsubscribeInteractions?: () => void;
 
 	constructor(server: BridgeServer, session: AgentSession) {
 		this.#server = server;
@@ -126,7 +128,50 @@ export class ChatHandler {
 	}
 
 	attach(): void {
+		this.#unsubscribeInteractions = this.#session.subscribe(event => {
+			if (event.type === "interaction")
+				this.#server.send({ type: "interaction_event", revision: event.event.revision, event: event.event });
+			if (event.type === "interaction_snapshot") this.#server.send(event);
+			if (event.type === "plan_available" || event.type === "plan_resolved") this.#server.send(event);
+		});
 		this.#server.onMessage(msg => {
+			if (msg.type === "interaction_snapshot") {
+				this.#server.send({
+					type: "interaction_snapshot",
+					sessionId: this.#session.sessionId,
+					...this.#session.userInteractions.snapshot(),
+					plan: this.#session.conversationPlans.current,
+				});
+				return;
+			}
+			if (isInteractionCommand(msg) && (msg.type === "interaction_respond" || msg.type === "interaction_cancel")) {
+				if (msg.type === "interaction_respond") {
+					const accepted = this.#session.userInteractions.respondExternal(
+						msg.requestId,
+						msg.responseId,
+						msg.value,
+						msg.identity,
+					);
+					this.#server.send({ type: "interaction_receipt", responseId: msg.responseId, accepted });
+				} else {
+					const request = this.#session.userInteractions.pending().find(request => request.id === msg.requestId);
+					const matches =
+						request?.identity &&
+						Object.entries(request.identity).every(
+							([key, value]) => msg.identity[key as keyof typeof msg.identity] === value,
+						);
+					if (matches && this.#session.userInteractions.resolve(msg.requestId, "interrupted"))
+						void this.#session.abort();
+				}
+				return;
+			}
+			if (isInteractionCommand(msg) && msg.type === "plan_decide") {
+				void this.#session.decidePlan(msg.planId, msg.action).then(
+					receipt => this.#server.send({ type: "interaction_receipt", responseId: msg.responseId, ...receipt }),
+					() => this.#server.send({ type: "interaction_receipt", responseId: msg.responseId, accepted: false }),
+				);
+				return;
+			}
 			if (this.#server.serveKind === "browser" && isBrowserChatRequest(msg)) this.#handleChatRequest(msg);
 			else if (this.#server.serveKind === "office" && isTransportChatRequest(msg)) this.#handleChatRequest(msg);
 			else if (isChatStop(msg)) this.#handleChatStop(msg as unknown as { id: string });
@@ -655,6 +700,7 @@ export class ChatHandler {
 	}
 
 	dispose(): void {
+		this.#unsubscribeInteractions?.();
 		this.#disposed = true;
 		this.#pendingRequest = null; // abandon any queued prompt — don't replay into a dead session
 		// Fail any in-flight host-tool call — the session is going away.

package/src/browser/extension-bridge-tools.ts

@@ -112,8 +112,8 @@ export const BROWSER_TOOL_NAMES: readonly string[] = [
  * DELIBERATELY EXCLUDED:
  *  - Every {@link BROWSER_TOOL_NAMES} entry — there is no browser to drive in a
  *    document pane, so navigate/click/screenshot would only be hallucinated.
- *  - `ask` (needs interactive stdin → would hang headless), `python` (spawns a
- *    kernel → startup cost), `ssh`/`debug`/`notebook`/`browser`/`get_page_context`.
+ *  - `python` (spawns a kernel → startup cost),
+ *    `ssh`/`debug`/`notebook`/`browser`/`get_page_context`.
  *
  * SAFETY: the headless session pairs this with the bundled `sandbox-guard`
  * extension (see headless-bridge.ts `bundledExtensions`), which confines the file
@@ -145,4 +145,6 @@ export const OFFICE_TOOL_NAMES: readonly string[] = [
 	"task",
 	"calc",
 	"inspect_image",
+	"request_user_input",
+	"request_user_input_async",
 ];

package/src/cli/args.ts

@@ -470,7 +470,8 @@ ${chalk.bold("Available Tools (default-enabled unless noted):")}
   task          - Launch sub-agents for parallel tasks
   todo_write    - Manage todo/task lists
   web_search    - Search the web
-  ask           - Ask user questions (interactive mode only)
+  request_user_input       - Ask structured questions and wait (Plan mode by default)
+  request_user_input_async - Ask questions without blocking ongoing work
 
 ${chalk.bold("Sandbox Options:")}
   --no-sandbox               ${LAUNCH_FLAGS["no-sandbox"].description}

package/src/config/settings-schema.ts

@@ -951,24 +951,16 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "interaction", label: "Completion Notification", description: "Notify when the agent completes" },
 	},
 
-	"ask.timeout": {
-		type: "number",
-		default: 30,
+	"interactions.waitingInDefault": {
+		type: "boolean",
+		default: false,
 		ui: {
 			tab: "interaction",
-			label: "Ask Timeout",
-			description: "Auto-select recommended option after timeout (0 to disable)",
-			submenu: true,
+			label: "Waiting questions in Default mode",
+			description: "Allow request_user_input outside Plan mode",
 		},
 	},
 
-	"ask.notify": {
-		type: "enum",
-		values: ["on", "off"] as const,
-		default: "on",
-		ui: { tab: "interaction", label: "Ask Notification", description: "Notify when ask tool is waiting for input" },
-	},
-
 	// Speech-to-text
 	"stt.enabled": {
 		type: "boolean",

package/src/config/settings.ts

@@ -572,14 +572,6 @@ export class Settings {
 			delete raw.queueMode;
 		}
 
-		// ask.timeout: ms -> seconds (if value > 1000, it's old ms format)
-		if (raw.ask && typeof (raw.ask as Record<string, unknown>).timeout === "number") {
-			const oldValue = (raw.ask as Record<string, unknown>).timeout as number;
-			if (oldValue > 1000) {
-				(raw.ask as Record<string, unknown>).timeout = Math.round(oldValue / 1000);
-			}
-		}
-
 		// Migrate old flat "theme" string to nested theme.dark/theme.light
 		if (typeof raw.theme === "string") {
 			const oldTheme = raw.theme;

package/src/extensibility/extensions/bundled/herdr-reporter.ts

@@ -173,7 +173,7 @@ function nativeCapability(): string | undefined {
 
 /** Protocol 23 adds a workspace receipt without changing native action semantics. */
 function supportsNativeLifecycle(protocol: number | undefined): boolean {
-	return protocol === 22 || protocol === 23;
+	return protocol !== undefined && protocol >= 22 && protocol <= 25;
 }
 
 function persistedTurns(ctx: ExtensionContext): PersistedTurn[] {
@@ -962,7 +962,7 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 		if (!normalizedPhasesObserved) scheduleSettledTurnReconcile(ctx);
 	});
 
-	// An interactive prompt (permission gate, ask tool, confirm/input) is
+	// An interactive prompt (permission gate, waiting user-input tool, confirm/input) is
 	// awaiting the user: that is herdr's "needs attention" (blocked) state.
 	pi.on("user_prompt_start", async event => {
 		promptBlockedReason = getPromptBlockedReason(event.kind);

package/src/extensibility/extensions/types.ts

@@ -39,7 +39,6 @@ import type { PythonResult } from "../../ipy/executor";
 import type { Theme } from "../../modes/theme/theme";
 import type { CompactionPreparation, CompactionResult } from "../../session/compaction";
 import type { CustomMessage } from "../../session/messages";
-import type { InteractionQuestion, QuestionAnswers } from "../../session/question-types";
 import type {
 	BranchSummaryEntry,
 	CompactionEntry,
@@ -112,12 +111,6 @@ export type ExtensionWidgetContent = string[] | ExtensionUiComponentFactory | un
  * Each mode (interactive, RPC, print) provides its own implementation.
  */
 export interface ExtensionUIContext {
-	/** Present a whole question set through one shared completion owner when supported. */
-	questions?(
-		questions: readonly InteractionQuestion[],
-		dialogOptions?: ExtensionUIDialogOptions,
-	): Promise<QuestionAnswers | undefined>;
-
 	/** Show a selector and return the user's choice. */
 	select(title: string, options: string[], dialogOptions?: ExtensionUIDialogOptions): Promise<string | undefined>;
 
@@ -555,7 +548,7 @@ export interface MessageEndEvent {
 export type UserPromptKind = "select" | "confirm" | "input";
 
 /**
- * Fired when an interactive prompt (permission gate, `ask` tool, confirm/input
+ * Fired when an interactive prompt (permission gate, waiting user-input tool, confirm/input
  * dialog) is shown and is awaiting the user. Signals a "blocked / needs
  * attention" state that is otherwise not observable from the agent event stream,
  * since the session stays `isStreaming` while a prompt is open.

package/src/herdr/client.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { connect } from "node:net";
 
 export const HERDR_PROTOCOL_MIN_VERSION = 19;
-export const HERDR_PROTOCOL_MAX_VERSION = 23;
+export const HERDR_PROTOCOL_MAX_VERSION = 25;
 const DEFAULT_TIMEOUT_MS = 5_000;
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 
@@ -61,6 +61,11 @@ export class HerdrClient {
 		return this.negotiatedProtocol;
 	}
 
+	capabilityVersion(name: string): number | undefined {
+		const version = this.capabilities[name];
+		return typeof version === "number" && Number.isSafeInteger(version) ? version : undefined;
+	}
+
 	hasCapability(name: string): boolean {
 		return this.capabilities[name] === true;
 	}

package/src/herdr/interactions.ts

@@ -0,0 +1,221 @@
+import { isDeepStrictEqual } from "node:util";
+import type { ConversationPlan, PlanAction } from "../../../chat-ui/src/interactions/conversation-plan";
+import type {
+	InteractionIdentity,
+	UserInteraction,
+	UserInteractionEvent,
+	UserInteractions,
+} from "../session/user-interactions";
+
+interface Client {
+	ensureProtocol(): Promise<void>;
+	capabilityVersion(name: string): number | undefined;
+	request(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+interface Binding {
+	execution_id: string;
+	pane_id: string;
+	producer: string;
+	generation: number;
+}
+interface Owner extends Binding {
+	session_id: string;
+}
+interface Target {
+	owner: Owner;
+	request_id: string;
+}
+interface Entry {
+	target: Target;
+	identity: InteractionIdentity;
+	report: Record<string, unknown>;
+	decide?: (action: PlanAction) => Promise<{ accepted: boolean }>;
+}
+const record = (value: unknown): value is Record<string, unknown> =>
+	value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Additional observation never owns completion or disables the local interaction path. */
+export class HerdrInteractionBridge {
+	#entries = new Map<string, Entry>();
+	#reports: Record<string, unknown>[] = [];
+	#acks: Record<string, unknown>[] = [];
+	#decisions = new Map<string, { action: unknown; accepted: boolean }>();
+	#unsubscribe: () => void;
+	#timer?: ReturnType<typeof setInterval>;
+	#flight?: Promise<void>;
+	#closed = false;
+	#failureReported = false;
+	constructor(
+		private readonly client: Client,
+		private readonly interactions: UserInteractions,
+		private readonly binding: Binding,
+		private readonly onError: (error: unknown) => void,
+		private readonly capability?: string,
+		poll = true,
+	) {
+		this.#unsubscribe = interactions.subscribe(event => this.#observe(event));
+		for (const request of interactions.pending()) this.#open(request, 1);
+		if (poll) {
+			this.#timer = setInterval(() => {
+				void this.flush();
+			}, 1000);
+			this.#timer.unref?.();
+		}
+	}
+	#observe(event: UserInteractionEvent): void {
+		if (event.type === "opened") this.#open(event.interaction, event.revision);
+		else {
+			const entry = this.#entries.get(event.interaction.id);
+			if (!entry) return;
+			entry.report = { ...entry.report, event_revision: event.revision, state: event.reason ?? "owner_lost" };
+			this.#reports.push(structuredClone(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 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],
+			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 } : {}) }],
+						}
+					: { questions: request.inputQuestions, isBlocking: true, autoResolutionMs: null },
+		};
+		this.#entries.set(request.id, { target, identity: structuredClone(identity), report });
+		this.#reports.push(structuredClone(report));
+	}
+	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 };
+		const report = {
+			target,
+			thread_id: identity.threadId,
+			turn_id: identity.turnId,
+			item_id: plan.itemId,
+			question_ids: [],
+			event_revision: plan.revision,
+			kind: "plan_decision",
+			payload: plan,
+			state: "pending",
+		};
+		this.#entries.set(plan.id, { target, identity, report, decide });
+		this.#reports.push(structuredClone(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));
+	}
+	flush(): Promise<void> {
+		if (this.#closed) return Promise.resolve();
+		if (this.#flight) return this.#flight;
+		this.#flight = this.#flush()
+			.catch(error => {
+				if (!this.#failureReported) this.onError(error);
+				this.#failureReported = true;
+			})
+			.finally(() => {
+				this.#flight = undefined;
+			});
+		return this.#flight;
+	}
+	async #flush(): Promise<void> {
+		if (!this.#entries.size) return;
+		await this.client.ensureProtocol();
+		if (this.client.capabilityVersion("agent_interactions") !== 1)
+			throw new Error("Herdr interaction capability is unavailable");
+		await this.#flushAcknowledgements();
+		while (this.#reports.length) {
+			const report = this.#reports[0];
+			const response = await this.client.request("agent.interaction.report", {
+				...report,
+				...(this.capability ? { native_capability: this.capability } : {}),
+			});
+			if (response.type !== "agent_interaction") throw new Error("Herdr did not acknowledge the interaction report");
+			this.#reports.shift();
+		}
+		const owners = new Map(
+			[...this.#entries.values()]
+				.filter(entry => entry.report.state === "pending")
+				.map(entry => [JSON.stringify(entry.target.owner), entry.target.owner]),
+		);
+		for (const owner of owners.values()) {
+			const producer = { owner, ...(this.capability ? { native_capability: this.capability } : {}) };
+			const response = await this.client.request("agent.interaction.delivery.get", producer);
+			if (response.type !== "agent_interaction_deliveries" || !Array.isArray(response.deliveries))
+				throw new Error("Invalid Herdr delivery response");
+			for (const delivery of response.deliveries) {
+				if (
+					!record(delivery) ||
+					!record(delivery.receipt) ||
+					!record(delivery.receipt.target) ||
+					typeof delivery.receipt.response_id !== "string"
+				)
+					throw new Error("Invalid Herdr delivery identity");
+				const receipt = delivery.receipt;
+				const target = receipt.target as unknown as Target;
+				const entry = this.#entries.get(target.request_id);
+				if (!entry || !isDeepStrictEqual(target, entry.target)) throw new Error("Herdr delivery owner mismatch");
+				let accepted: boolean;
+				if (entry.decide) {
+					const prior = this.#decisions.get(receipt.response_id as string);
+					if (prior) accepted = prior.action === delivery.answer && prior.accepted;
+					else {
+						accepted =
+							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 });
+					}
+				} else
+					accepted = this.interactions.respondExternal(
+						target.request_id,
+						receipt.response_id as string,
+						delivery.answer,
+						entry.identity,
+					);
+				this.#acks.push({
+					producer,
+					request_id: target.request_id,
+					response_id: receipt.response_id,
+					accepted,
+				});
+				await this.#flushAcknowledgements();
+			}
+		}
+		this.#failureReported = false;
+	}
+	async #flushAcknowledgements(): Promise<void> {
+		while (this.#acks.length) {
+			const ack = await this.client.request("agent.interaction.delivery.ack", this.#acks[0]);
+			if (ack.type !== "agent_interaction_receipt")
+				throw new Error("Herdr did not acknowledge producer answer delivery");
+			this.#acks.shift();
+		}
+	}
+	async close(): Promise<void> {
+		if (this.#timer) clearInterval(this.#timer);
+		this.#unsubscribe();
+		await this.flush();
+		this.#closed = true;
+	}
+}

package/src/internal-urls/api-catalog-discovery.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import type { ApiCatalogCategory, ApiCatalogIndex } from "./api-catalog-types";
+
+export interface ApiCatalogDiscoveryDocument {
+	readonly id: string;
+	readonly categoryName: string;
+	readonly markdown: string;
+}
+
+export interface ApiCatalogDiscoveryCorpus {
+	readonly catalogVersion: string;
+	readonly documents: readonly ApiCatalogDiscoveryDocument[];
+}
+
+export interface ApiCatalogDiscoveryCandidate {
+	readonly categoryName: string;
+	readonly destination: string;
+}
+
+export function normalizeApiCatalogDiscoveryTerm(value: string): string {
+	return value.toLowerCase().replace(/[_\s]+/g, "-");
+}
+
+/** The legacy text predicate extracted without changing its semantics. */
+export function matchesBaselineCatalogDiscoveryTerm(term: string, values: readonly string[]): boolean {
+	const normalized = normalizeApiCatalogDiscoveryTerm(term);
+	return values.some(value => normalizeApiCatalogDiscoveryTerm(value).includes(normalized));
+}
+
+function categoryDocument(category: ApiCatalogCategory): ApiCatalogDiscoveryDocument {
+	const destination = `xcsh://api-catalog/${category.name}`;
+	const operations = category.operations.flatMap(operation => [
+		`- Operation: ${operation.name}`,
+		`  - Alias: ${(operation.operationAliases ?? []).join(", ")}`,
+		`  - Description: ${operation.description}`,
+		`  - Method: ${operation.method.toUpperCase()}`,
+		`  - Path: ${operation.path}`,
+		`  - Operation ID: ${operation.operationId}`,
+	]);
+
+	return {
+		id: `category:${category.name}`,
+		categoryName: category.name,
+		markdown: [
+			`# ${category.displayName}`,
+			"",
+			`- Category: ${category.name}`,
+			`- Destination: ${destination}`,
+			"",
+			"## Operations",
+			...(operations.length > 0 ? operations : ["- None"]),
+			"",
+		].join("\n"),
+	};
+}
+
+/**
+ * Produces a stable, authoritative-only corpus. It intentionally contains no
+ * tenant data, credentials, generated examples, or speculative API fields.
+ */
+export function buildApiCatalogDiscoveryCorpus(
+	index: ApiCatalogIndex,
+	data: Readonly<Record<string, ApiCatalogCategory>>,
+): ApiCatalogDiscoveryCorpus {
+	return {
+		catalogVersion: index.version,
+		documents: Object.values(data)
+			.slice()
+			.sort((left, right) => left.name.localeCompare(right.name))
+			.map(categoryDocument),
+	};
+}
+
+export function fingerprintApiCatalogDiscoveryCorpus(
+	corpus: ApiCatalogDiscoveryCorpus,
+	sourceSha: string,
+	engineVersion: string,
+): string {
+	const bytes = JSON.stringify({
+		sourceSha,
+		catalogVersion: corpus.catalogVersion,
+		engineVersion,
+		documents: corpus.documents,
+	});
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Byte-equivalent baseline candidate selection for the existing renderer.
+ * Ranking is intentionally unchanged: canonical CRUD promotion stays in the
+ * renderer where it has access to API-spec evidence.
+ */
+export function rankBaselineCatalogDiscovery(
+	term: string,
+	corpus: ApiCatalogDiscoveryCorpus,
+): readonly ApiCatalogDiscoveryCandidate[] {
+	return corpus.documents
+		.filter(document => matchesBaselineCatalogDiscoveryTerm(term, [document.markdown]))
+		.map(document => ({
+			categoryName: document.categoryName,
+			destination: `xcsh://api-catalog/${document.categoryName}`,
+		}));
+}