@pi-archimedes/ask 2.10.3 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/ask",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -15,16 +15,16 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.10.3"
+    "@pi-archimedes/core": "2.11.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0",
     "typebox": ">=1.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "typebox": "^1.1.38",
     "typescript": "^6.0.0"
   },

package/src/default-export.test.ts

@@ -7,12 +7,17 @@ describe("ask default export (standalone factory)", () => {
 
 		const on = vi.fn();
 		const registerTool = vi.fn();
-		const pi = { on, registerTool } as any;
+		// `events` is the host handle the relay subscribes its ASK_REQUEST
+		// listener on — required on every pi this package declares support for.
+		const subscribe = vi.fn(() => () => {});
+		const pi = { on, registerTool, events: { emit: vi.fn(), on: subscribe } } as any;
 
 		defaultExport(pi);
 
 		// ask tool registered
 		expect(registerTool).toHaveBeenCalled();
+		// the subagent ask relay subscribed on the host handle
+		expect(subscribe).toHaveBeenCalledWith("archimedes:ask_request", expect.any(Function));
 
 		// registerAsk wires its own session lifecycle internally
 		const events = on.mock.calls.map((c: Array<unknown>) => c[0]);

package/src/ipc-relay.ts

@@ -1,5 +1,5 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import type { EventBus, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Events, emitOn } from "@pi-archimedes/core/events";
 import { getBridge } from "@pi-archimedes/core/bridge";
 import { type AskQuestion, type AskSelection } from "./selection.js";
 import { askSingleQuestionWithInlineNote } from "./picker.js";
@@ -11,7 +11,7 @@ export function registerIpcRelay(
 	getCtx: () => ExtensionContext | undefined,
 	unsubscribes: Array<() => void>,
 ): void {
-	const unsubAskRequest = getBus().on(Events.ASK_REQUEST, async (payload: unknown) => {
+	const unsubAskRequest = pi.events.on(Events.ASK_REQUEST, async (payload: unknown) => {
 		const data = payload as {
 			source: string;
 			requestId: string;
@@ -32,7 +32,7 @@ export function registerIpcRelay(
 
 		// Defer to next tick so TUI can process current state
 		await new Promise((resolve) => setImmediate(resolve));
-		await handleAskRequest(data, getCtx, (active, label) => emitBlocked(pi, active, label));
+		await handleAskRequest(data, getCtx, (active, label) => emitBlocked(pi, active, label), pi.events);
 	});
 	unsubscribes.push(unsubAskRequest);
 }
@@ -44,6 +44,7 @@ async function handleAskRequest(
 	},
 	getCtx: () => ExtensionContext | undefined,
 	reportBlocked: (active: boolean, label?: string) => void,
+	events: EventBus,
 ): Promise<void> {
 	const ctx = getCtx();
 	if (!ctx?.ui) return;
@@ -96,8 +97,8 @@ async function handleAskRequest(
 		customInput: selections[i]?.customInput,
 	}));
 
-	// Emit on bus — parent's streamEvents writes to child socket
-	getBus().emit(Events.ASK_RESPONSE, {
+	// Emit on the handle — the parent's streamEvents writes it to the child socket
+	emitOn(events, Events.ASK_RESPONSE, {
 		requestId: data.requestId,
 		cancelled,
 		results,

package/src/note.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Task 11 item 4 — the inline note's caret is pi-tui's fake cursor, not a
+ * hand-rolled reverse video.
+ *
+ * What pi-tui does with each shape (read from `dist/tui.js`):
+ *
+ *   renderFakeCursor(text) = FAKE_CURSOR_START + text + FAKE_CURSOR_END
+ *                          = "\x1b_pi:fc\x07" … "\x1b_pi:/fc\x07"
+ *
+ * Both are zero-width APC sequences. `TUI.resolveFakeCursors()` turns them into
+ * `\x1b[7m`/`\x1b[27m` when it draws the frame — and, when
+ * `showHardwareCursor` is on, it first drops a fake cursor that sits directly
+ * after `CURSOR_MARKER` (`FOCUSED_FAKE_CURSOR = /(\x1b_pi:c\x07)\x1b_pi:fc\x07(.*?)(?:\x1b_pi:\/fc\x07|$)/s`,
+ * replaced with `$1$2`), because the terminal is already drawing a cursor there.
+ *
+ * That is why the raw escapes were wrong: `\x1b[7m` is not inside fake-cursor
+ * markers, so `resolveFakeCursors` cannot see it and the frame carried the
+ * inverted block *and* the hardware cursor — two cursors. `CURSOR_MARKER` on its
+ * own was still emitted, so `extractCursorPosition()` still positioned the real
+ * cursor; only the block was redundant.
+ *
+ * The `CURSOR_MARKER` half is unchanged and still conditional
+ * (`includeHardwareCursorMarker`), and it must stay immediately before the fake
+ * cursor for that drop to fire. Issue #100 (`CURSOR_MARKER` lost when a prompt
+ * row is truncated) is a separate, still-open defect about the truncation paths;
+ * nothing here fixes or worsens it — the width assertions below pin that.
+ */
+
+import { describe, it, expect } from "vitest";
+import { CURSOR_MARKER, renderFakeCursor, visibleWidth } from "@earendil-works/pi-tui";
+import {
+  INLINE_NOTE_WRAP_PADDING,
+  buildOptionLabelWithInlineNote,
+  buildWrappedOptionLabelWithInlineNote,
+} from "./note.js";
+
+/**
+ * pi-tui exports the writer (`renderFakeCursor`) but not the class that resolves
+ * the markers, so the frame pass is only reachable through its dist file. A
+ * test-only import — nothing in this package's runtime touches it. Running pi-tui
+ * rather than re-typing its pattern is the point: the claim under test is what
+ * the frame does with the cell this package emits, and a copied regex would only
+ * prove the test agrees with itself.
+ */
+const { TuiBase } = (await import("@earendil-works/pi-tui/dist/tui.js")) as unknown as {
+  TuiBase: { prototype: { resolveFakeCursors(this: { showHardwareCursor: boolean }, lines: string[]): string[] } };
+};
+
+/** What pi-tui's own frame pass makes of a line, for each `showHardwareCursor` setting. */
+function resolve(line: string, showHardwareCursor: boolean): string {
+  return TuiBase.prototype.resolveFakeCursors.call({ showHardwareCursor }, [line])[0]!;
+}
+
+const occurrences = (haystack: string, needle: string) => haystack.split(needle).length - 1;
+
+/** pi-tui's own markers, derived from the exported helper rather than re-typed. */
+const fakeCursorCell = renderFakeCursor("x");
+const FAKE_CURSOR_START = fakeCursorCell.slice(0, fakeCursorCell.indexOf("x"));
+const FAKE_CURSOR_END = fakeCursorCell.slice(fakeCursorCell.indexOf("x") + 1);
+
+const SEP = " — note: ";
+
+describe("editing inline note caret", () => {
+  it("wraps the caret character in pi-tui's fake cursor, not raw reverse video", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "ab", true, undefined, 1, true);
+    expect(label).toBe(`Option${SEP}a${CURSOR_MARKER}${renderFakeCursor("b")}`);
+    expect(label).not.toContain("\x1b[7m");
+    expect(label).not.toContain("\x1b[27m");
+  });
+
+  it("puts the hardware-cursor marker directly before the fake cursor, which is the adjacency resolveFakeCursors matches", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "abc", true, undefined, 1, true);
+    expect(label).toContain(`${CURSOR_MARKER}${FAKE_CURSOR_START}b${FAKE_CURSOR_END}`);
+  });
+
+  it("drops the hardware-cursor marker when the caller does not want it, and keeps the fake cursor", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "ab", true, undefined, 1, false);
+    expect(label).not.toContain(CURSOR_MARKER);
+    expect(label).toContain(`${FAKE_CURSOR_START}b${FAKE_CURSOR_END}`);
+  });
+
+  it("clamps the caret to the end of the note (unchanged behaviour)", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "ab", true, undefined, 9, true);
+    expect(label).toBe(`Option${SEP}ab${CURSOR_MARKER}${renderFakeCursor(" ")}`);
+  });
+
+  it("draws a space for a caret past an empty note (unchanged behaviour)", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "", true, undefined, 0, true);
+    expect(label).toBe(`Option${SEP}${CURSOR_MARKER}${renderFakeCursor(" ")}`);
+  });
+
+  it("splits before/after the caret across control characters rather than hiding them (unchanged behaviour)", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "a\tb", true, undefined, 1, true);
+    expect(label).toBe(`Option${SEP}a${CURSOR_MARKER}${renderFakeCursor(" ")}b`);
+  });
+});
+
+describe("non-editing inline note", () => {
+  it("stays plain text — no cursor of either kind", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "  typed  ", false);
+    expect(label).toBe(`Option${SEP}typed`);
+    expect(label).not.toContain(CURSOR_MARKER);
+    expect(label).not.toContain(FAKE_CURSOR_START);
+  });
+
+  it("adds nothing at all for an empty note on an option that is not being edited", () => {
+    expect(buildOptionLabelWithInlineNote("Option", "   ", false)).toBe("Option");
+  });
+});
+
+describe("truncation and wrapping with the fake cursor", () => {
+  it("keeps the caret cell whole when the label fits, and counts the markers as zero width", () => {
+    const label = buildOptionLabelWithInlineNote("Option", "abc", true, 200, 1, true);
+    expect(label).toContain(`${CURSOR_MARKER}${FAKE_CURSOR_START}b${FAKE_CURSOR_END}`);
+    // "Option — note: abc" — 18 visible columns, marker bytes invisible.
+    expect(visibleWidth(label)).toBe(visibleWidth(`Option${SEP}abc`));
+  });
+
+  it("truncates from the head while editing, so the caret stays on screen", () => {
+    const long = "x".repeat(60);
+    const label = buildOptionLabelWithInlineNote("Option", long, true, 30, 59, true);
+    expect(label.startsWith("…")).toBe(true);
+    // The caret is at the very end of the note, so it survives the head cut.
+    expect(label).toContain(`${FAKE_CURSOR_START}x${FAKE_CURSOR_END}`);
+  });
+
+  it("wraps to the requested width and keeps exactly one caret cell across the lines", () => {
+    const long = "note text that is long enough to need wrapping here";
+    const lines = buildWrappedOptionLabelWithInlineNote(
+      "Option",
+      long,
+      true,
+      40,
+      INLINE_NOTE_WRAP_PADDING,
+      20,
+      true,
+    );
+    expect(lines.length).toBeGreaterThan(1);
+    for (const line of lines) expect(visibleWidth(line)).toBeLessThanOrEqual(40);
+    const joined = lines.join("\n");
+    expect(joined.split(`${FAKE_CURSOR_START}`).length - 1).toBe(1);
+    expect(joined).toContain(CURSOR_MARKER);
+  });
+});
+
+// The measurement the change rests on, executed rather than read: what pi-tui's
+// frame pass leaves behind for the cell this package emits.
+describe("caret through pi-tui's resolveFakeCursors", () => {
+  const INVERT_ON = "\x1b[7m";
+  const INVERT_OFF = "\x1b[27m";
+  const caret = buildOptionLabelWithInlineNote("Option", "ab", true, undefined, 1, true);
+
+  it("with no hardware cursor, the cell becomes reverse video", () => {
+    const resolved = resolve(caret, false);
+    expect(resolved).toContain(`${INVERT_ON}b${INVERT_OFF}`);
+    // The zero-width markers are gone, so they cannot leak into the frame.
+    expect(resolved).not.toContain(FAKE_CURSOR_START);
+    expect(resolved).not.toContain(FAKE_CURSOR_END);
+  });
+
+  it("with the hardware cursor on, the focused cell drops its block — exactly one cursor", () => {
+    const resolved = resolve(caret, true);
+    expect(occurrences(resolved, INVERT_ON)).toBe(0);
+    // The hardware marker itself survives: it is what positions the real cursor.
+    expect(resolved).toContain(CURSOR_MARKER);
+  });
+
+  it("the shape this package used to emit keeps two cursors when the hardware one is on", () => {
+    // The old caret, built the way `note.ts` built it before the fix: a raw
+    // reverse-video cell after CURSOR_MARKER. pi-tui cannot see it, so the drop
+    // above does not happen and the frame carries both.
+    const oldCaret = `Option${SEP}a${CURSOR_MARKER}${INVERT_ON}b${INVERT_OFF}`;
+    const resolved = resolve(oldCaret, true);
+    expect(resolved).toBe(oldCaret);
+    expect(occurrences(resolved, INVERT_ON)).toBe(1);
+  });
+
+  it("a caret with no hardware marker keeps its block in both settings (an unfocused fake cursor)", () => {
+    const noMarker = buildOptionLabelWithInlineNote("Option", "ab", true, undefined, 1, false);
+    for (const showHardwareCursor of [false, true]) {
+      const resolved = resolve(noMarker, showHardwareCursor);
+      expect(resolved).toContain(`${INVERT_ON}b${INVERT_OFF}`);
+    }
+  });
+
+  it("a plain option label is untouched by the pass", () => {
+    const plain = buildOptionLabelWithInlineNote("Option", "typed", false);
+    expect(resolve(plain, false)).toBe(plain);
+    expect(resolve(plain, true)).toBe(plain);
+  });
+});

package/src/note.ts

@@ -1,8 +1,6 @@
-import { CURSOR_MARKER, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, renderFakeCursor, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
 const INLINE_NOTE_SEPARATOR = " — note: ";
-const INLINE_EDIT_CURSOR_INVERT_ON = "\x1b[7m";
-const INLINE_EDIT_CURSOR_INVERT_OFF = "\x1b[27m";
 
 export const INLINE_NOTE_WRAP_PADDING = 2;
 
@@ -29,7 +27,15 @@ function buildEditingInlineNote(
 	const afterCursorStartIndex = rawCharAtCursor.length > 0 ? cursorIndex + 1 : cursorIndex;
 	const afterCursor = sanitizeNoteForInlineDisplay(rawNote.slice(afterCursorStartIndex));
 	const cursorMarker = includeHardwareCursorMarker ? CURSOR_MARKER : "";
-	const cursorCell = `${cursorMarker}${INLINE_EDIT_CURSOR_INVERT_ON}${charAtCursor}${INLINE_EDIT_CURSOR_INVERT_OFF}`;
+	// `renderFakeCursor()`, not a hand-rolled `\x1b[7m`: it wraps the cell in
+	// pi-tui's zero-width APC fake-cursor markers, which `TUI.resolveFakeCursors()`
+	// turns into reverse video when it draws the frame — and drops when
+	// `showHardwareCursor` is on and the cell sits directly after `CURSOR_MARKER`,
+	// because the terminal is drawing a cursor there already. Raw escapes are
+	// invisible to that pass, so the frame used to carry the inverted block *and*
+	// the hardware cursor. Keep the marker immediately before the cell: that
+	// adjacency is what the drop matches (`note.test.ts`).
+	const cursorCell = `${cursorMarker}${renderFakeCursor(charAtCursor)}`;
 	return `${beforeCursor}${cursorCell}${afterCursor}`;
 }
 

package/src/tool-declarations.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Task 11 item 3 — `ask` is for the model, not for scripts.
+ *
+ * `exposure: "model-only"` means: declared to the model while active, never
+ * callable through `ctx.executeTool()` (`pi: dist/core/extensions/types.d.ts`,
+ * `ToolExposure`; `dist/core/agent-session.js`, `_getCallableTools()` — only
+ * `direct` + active, `codemode` and `deferred` are callable). Codemode builds
+ * its callable set from exactly that list
+ * (`dist/extensions/codemode/execute.js`), so this costs something real, and it
+ * was measured on a real headless pi before shipping:
+ *
+ *   before (`direct`) — a codemode script's `tools.ask({...})` resolved; it
+ *   printed `ASK_TYPE: object {"cancelled":true,...}`.
+ *   after (`model-only`) — the same script fails with
+ *   `tools.ask does not exist. Available: ...` and `ask` is gone from its
+ *   `ALL_TOOLS`.
+ *
+ * A probe tool carrying only `exposure: "model-only"` showed the same split on
+ * the same pi: the model called it and got its result, while a script's
+ * `tools.probe_model_only({})` reported it as non-existent. `ask` takes the
+ * exposure because a script that asks a question the user never sees (the TUI
+ * and bridge paths need a session's UI) orchestrates nothing it can answer for;
+ * the interactive tool belongs to the model's turn.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskTool } from "./tool.js";
+
+type RegisteredTool = { name: string; exposure?: string; annotations?: Record<string, boolean> };
+
+function captureTool(): RegisteredTool {
+  const registered: RegisteredTool[] = [];
+  registerAskTool({
+    registerTool: (t: unknown) => registered.push(t as RegisteredTool),
+    events: { emit: vi.fn(), on: () => () => {} },
+  } as unknown as ExtensionAPI);
+  return registered[0]!;
+}
+
+describe("ask exposure", () => {
+  it("is model-only: declared to the model, never callable from a script", () => {
+    expect(captureTool().exposure).toBe("model-only");
+  });
+
+  it("carries no annotations — nothing here is a hint a permission gate needs", () => {
+    expect(captureTool().annotations).toBeUndefined();
+  });
+});

package/src/tool.output-schema.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Task 11 item 2 — `ask` as a programmatic tool.
+ *
+ * `ask` has four success paths (bridge, headless socket, single-question TUI,
+ * tabs dialog) and they all build the same `QuestionResult[]`; only the text
+ * differs. The structured content is that answer set plus the one thing a
+ * script cannot otherwise tell from the text reliably: whether the user
+ * answered at all.
+ *
+ * As elsewhere in this task, the payload is produced by running the real
+ * handler and validated against the schema the registered tool declares. The
+ * TUI components are mocked (as `tool.test.ts` does) so the assertions are about
+ * the result contract, not about drawing a dialog. A crashed picker still
+ * throws — that is an unexpected failure, not a reported one (`tool.test.ts`
+ * pins it) — so nothing here converts it.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Value } from "typebox/value";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskTool } from "./tool.js";
+
+const { bridgeState, eventsState } = vi.hoisted(() => {
+  const ask = vi.fn();
+  return {
+    bridgeState: { active: false, ask, confirm: vi.fn(), password: vi.fn(), state: vi.fn(() => "idle") },
+    eventsState: { emit: vi.fn(), on: () => () => {} },
+  };
+});
+
+vi.mock("@pi-archimedes/core/bridge", () => ({ getBridge: () => bridgeState }));
+vi.mock("./picker.js", () => ({ askSingleQuestionWithInlineNote: vi.fn() }));
+vi.mock("./dialog.js", () => ({ askQuestionsWithTabs: vi.fn() }));
+
+const { askSingleQuestionWithInlineNote } = await import("./picker.js");
+const { askQuestionsWithTabs } = await import("./dialog.js");
+
+type RegisteredTool = {
+  name: string;
+  outputSchema?: unknown;
+  execute: (
+    id: string,
+    params: unknown,
+    signal: unknown,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{
+    content: Array<{ type: string; text: string }>;
+    details: unknown;
+    structuredContent?: unknown;
+    isError?: boolean;
+  }>;
+};
+
+function captureTool(): RegisteredTool {
+  const registered: RegisteredTool[] = [];
+  registerAskTool({ registerTool: (t: unknown) => registered.push(t as RegisteredTool), events: eventsState } as unknown as ExtensionAPI);
+  return registered[0]!;
+}
+
+function check(tool: RegisteredTool, value: unknown): boolean {
+  expect(tool.outputSchema, "ask declares no outputSchema").toBeDefined();
+  return Value.Check(tool.outputSchema as never, value);
+}
+
+const oneQuestion = {
+  questions: [
+    { id: "q1", question: "Which option?", description: "Some context", options: [{ label: "A" }, { label: "B" }] },
+  ],
+};
+
+const twoQuestions = {
+  questions: [
+    { id: "q1", question: "First?", options: [{ label: "A" }, { label: "B" }] },
+    { id: "q2", question: "Second?", multi: true, options: [{ label: "A" }, { label: "B" }] },
+  ],
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  bridgeState.active = false;
+});
+
+describe("ask outputSchema", () => {
+  it("declares one", () => {
+    expect(captureTool().outputSchema).toBeDefined();
+  });
+
+  it("the answer set is what the schema describes: results + cancelled", () => {
+    const tool = captureTool();
+    const props = (tool.outputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+    expect(Object.keys(props).sort()).toEqual(["cancelled", "results"]);
+  });
+});
+
+describe("ask structuredContent — success paths", () => {
+  it("bridge answer → { cancelled: false, results: [one answered result] }", async () => {
+    bridgeState.active = true;
+    bridgeState.ask.mockResolvedValue({
+      cancelled: false,
+      results: [{ id: "q1", selectedOptions: ["B"], customInput: "extra" }],
+    });
+
+    const tool = captureTool();
+    const result = await tool.execute("t1", oneQuestion, undefined, undefined, { hasUI: true, ui: {} });
+
+    expect(result.structuredContent).toEqual({
+      cancelled: false,
+      results: [
+        {
+          id: "q1",
+          question: "Which option?",
+          description: "Some context",
+          options: ["A", "B"],
+          multi: false,
+          selectedOptions: ["B"],
+          customInput: "extra",
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+    // Content text unchanged — the summary line models read.
+    expect(result.content[0]!.text).toContain('q1: B + Other: "extra"');
+  });
+
+  it("bridge cancel → { cancelled: true, results: [one unanswered result] }, content text unchanged", async () => {
+    bridgeState.active = true;
+    bridgeState.ask.mockRejectedValue(new Error("bridge is not active"));
+
+    const tool = captureTool();
+    const result = await tool.execute("t1", oneQuestion, undefined, undefined, { hasUI: true, ui: {} });
+
+    expect(result.content[0]!.text).toBe("User cancelled the question.");
+    expect(result.structuredContent).toEqual({
+      cancelled: true,
+      results: [
+        {
+          id: "q1",
+          question: "Which option?",
+          description: "Some context",
+          options: ["A", "B"],
+          multi: false,
+          selectedOptions: [],
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("single-question TUI → one result, cancelled false, custom input only when given", async () => {
+    vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: ["A"] });
+
+    const tool = captureTool();
+    const result = await tool.execute("t2", oneQuestion, undefined, undefined, { hasUI: true, ui: {} });
+
+    expect(result.structuredContent).toEqual({
+      cancelled: false,
+      results: [
+        {
+          id: "q1",
+          question: "Which option?",
+          description: "Some context",
+          options: ["A", "B"],
+          multi: false,
+          selectedOptions: ["A"],
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("single-question TUI with no selection → cancelled true (the text says (cancelled))", async () => {
+    vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: [] });
+
+    const tool = captureTool();
+    const result = await tool.execute("t3", oneQuestion, undefined, undefined, { hasUI: true, ui: {} });
+
+    expect(result.content[0]!.text).toContain("(cancelled)");
+    expect((result.structuredContent as { cancelled: boolean }).cancelled).toBe(true);
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("a typed answer with nothing selected → cancelled false, customInput present", async () => {
+    // `cancelled` is the tool's own test — nothing selected AND nothing typed —
+    // so a typed answer is not a cancellation even with an empty selection, and
+    // `customInput` is the only field that says so.
+    bridgeState.active = true;
+    bridgeState.ask.mockResolvedValue({ cancelled: false, results: [{ id: "q1", selectedOptions: [], customInput: "typed instead" }] });
+
+    const tool = captureTool();
+    const result = await tool.execute("t5", oneQuestion, undefined, undefined, { hasUI: true, ui: {} });
+
+    const structured = result.structuredContent as { cancelled: boolean; results: Array<Record<string, unknown>> };
+    expect(structured.cancelled).toBe(false);
+    expect(structured.results[0]!.selectedOptions).toEqual([]);
+    expect(structured.results[0]!.customInput).toBe("typed instead");
+    expect(result.content[0]!.text).toContain("typed instead");
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("tabs dialog with two questions → two results, in question order", async () => {
+    vi.mocked(askQuestionsWithTabs).mockResolvedValue({
+      cancelled: false,
+      selections: [{ selectedOptions: ["A"] }, { selectedOptions: ["B"], customInput: "note" }],
+    });
+
+    const tool = captureTool();
+    const result = await tool.execute("t4", twoQuestions, undefined, undefined, { hasUI: true, ui: {} });
+
+    expect(result.structuredContent).toEqual({
+      cancelled: false,
+      results: [
+        {
+          id: "q1",
+          question: "First?",
+          options: ["A", "B"],
+          multi: false,
+          selectedOptions: ["A"],
+        },
+        {
+          id: "q2",
+          question: "Second?",
+          options: ["A", "B"],
+          multi: true,
+          selectedOptions: ["B"],
+          customInput: "note",
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+});

package/src/tool.test.ts

@@ -5,20 +5,22 @@ import * as path from "node:path";
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Events } from "@pi-archimedes/core/bus";
+import { Events } from "@pi-archimedes/core/events";
 import { registerAskTool } from "./tool.js";
 import { registerIpcRelay } from "./ipc-relay.js";
 import { renderAskCall, renderAskResult } from "./renderer.js";
 
 // ── Mocks ────────────────────────────────────────────────────────────────────
 //
-// Bus: an in-memory pub/sub whose `emit` is a spy (records + dispatches), so
-// tests can assert on emitted payloads while still letting the relay's
-// `on(ASK_REQUEST)` subscription receive them.
+// events: the host event bus (`pi.events`), an in-memory pub/sub whose `emit` is
+// a spy (records + dispatches), so tests can assert on emitted payloads while
+// still letting the relay's `on(ASK_REQUEST)` subscription receive them. One
+// handle per test — the tool and the relay are handed the same object, exactly
+// as two extensions in one pi process share one bus.
 // Bridge: a mutable state object — `active` flips per test, `ask` is a vi.fn.
 // Picker/dialog: mocked so the TUI branch never touches the real TUI.
 
-const { busState, bridgeState, eventsState } = vi.hoisted(() => {
+const { bridgeState, eventsState } = vi.hoisted(() => {
 	const listeners: Record<string, Array<(p: unknown) => void>> = {};
 	const emit = vi.fn((event: string, payload: unknown) => {
 		for (const fn of listeners[event] ?? []) {
@@ -37,7 +39,6 @@ const { busState, bridgeState, eventsState } = vi.hoisted(() => {
 	};
 	const ask = vi.fn();
 	return {
-		busState: { listeners, emit, on },
 		bridgeState: {
 			active: false,
 			ask,
@@ -45,15 +46,10 @@ const { busState, bridgeState, eventsState } = vi.hoisted(() => {
 			password: vi.fn(),
 			state: vi.fn(() => "idle"),
 		},
-		eventsState: { emit: vi.fn() }, // pi.events — the shared extension event bus
+		eventsState: { emit, on }, // pi.events — the host's shared extension event bus
 	};
 });
 
-vi.mock("@pi-archimedes/core/bus", async (importOriginal) => {
-	const actual = await importOriginal() as typeof import("@pi-archimedes/core/bus");
-	return { ...actual, getBus: () => ({ emit: busState.emit, on: busState.on }) };
-});
-
 vi.mock("@pi-archimedes/core/bridge", () => ({
 	getBridge: () => bridgeState,
 }));
@@ -103,9 +99,9 @@ function makeParams(): { questions: unknown[] } {
 	};
 }
 
-/** The payloads of the recorded `emit` calls for the given event. */
+/** The payloads of the recorded `emit` calls for the given channel. */
 function emitted(event: string): Record<string, unknown>[] {
-	return busState.emit.mock.calls
+	return eventsState.emit.mock.calls
 		.filter((c) => c[0] === event)
 		.map((c) => c[1]!) as Record<string, unknown>[];
 }
@@ -127,7 +123,6 @@ afterEach(() => {
 });
 
 beforeEach(() => {
-	busState.emit.mockClear();
 	eventsState.emit.mockClear();
 	bridgeState.active = false;
 	bridgeState.ask.mockReset();
@@ -299,8 +294,8 @@ describe("child branch (bridge inactive, no UI)", () => {
 		const result = await tool.execute("tool-2", makeParams(), undefined, undefined, { hasUI: false });
 
 		expect(result.content[0]!.text).toBe("User cancelled the question.");
-		// The child branch does not emit on the bus
-		expect(busState.emit).not.toHaveBeenCalled();
+		// The child branch does not emit on the handle
+		expect(eventsState.emit).not.toHaveBeenCalled();
 	});
 });
 
@@ -365,7 +360,7 @@ describe("TUI branch (bridge inactive, has UI)", () => {
 		const result = await tool.execute("tool-5", { questions: [] }, undefined, undefined, { hasUI: true, ui: {} });
 
 		expect(result.content[0]!.text).toBe("Error: questions must not be empty");
-		expect(busState.emit).not.toHaveBeenCalled();
+		expect(eventsState.emit).not.toHaveBeenCalled();
 		// No dialog shown → no herdr pairing either
 		expect(herdrEmits()).toEqual([]);
 	});
@@ -476,7 +471,7 @@ describe("ipc-relay", () => {
 		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
 		relayUnsubs.push(...unsubscribes);
 
-		busState.emit(Events.ASK_REQUEST, {
+		eventsState.emit(Events.ASK_REQUEST, {
 			source: "subagent:x",
 			requestId: "relay-1",
 			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
@@ -498,7 +493,7 @@ describe("ipc-relay", () => {
 		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
 		relayUnsubs.push(...unsubscribes);
 
-		busState.emit(Events.ASK_REQUEST, {
+		eventsState.emit(Events.ASK_REQUEST, {
 			source: "subagent:x",
 			requestId: "relay-2",
 			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
@@ -520,7 +515,7 @@ describe("ipc-relay", () => {
 		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
 		relayUnsubs.push(...unsubscribes);
 
-		busState.emit(Events.ASK_REQUEST, {
+		eventsState.emit(Events.ASK_REQUEST, {
 			source: "subagent:x",
 			requestId: "relay-3",
 			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
@@ -545,7 +540,7 @@ describe("ipc-relay", () => {
 		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
 		relayUnsubs.push(...unsubscribes);
 
-		busState.emit(Events.ASK_REQUEST, {
+		eventsState.emit(Events.ASK_REQUEST, {
 			source: "subagent:x",
 			requestId: "relay-4",
 			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],

package/src/tool.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import { Events, emitOn } from "@pi-archimedes/core/events";
 import { getBridge } from "@pi-archimedes/core/bridge";
 import { connect } from "node:net";
 import { randomUUID } from "node:crypto";
@@ -41,6 +41,70 @@ const AskParamsSchema = Type.Object({
 
 type AskParams = Static<typeof AskParamsSchema>;
 
+/**
+ * The machine-readable answer set.
+ *
+ * Same referee as elsewhere in this task: pi hands this to a codemode script in
+ * place of the text and validates nothing, so `tool.output-schema.test.ts` runs
+ * the handler and checks the payload against the declaration.
+ *
+ * `results` is the same `QuestionResult[]` the renderer's `details.results`
+ * carries, and `cancelled` is the one fact the text states only in prose
+ * (`Selected: (cancelled)` / `User cancelled the question.`): the user answered
+ * nothing. `ask` has no failure result — a crashed picker still throws, because
+ * that is an unexpected error rather than a reported one.
+ */
+const AskAnswerItemSchema = Type.Object({
+	id: Type.String(),
+	question: Type.String(),
+	description: Type.Optional(Type.String()),
+	options: Type.Array(Type.String()),
+	multi: Type.Boolean(),
+	selectedOptions: Type.Array(Type.String()),
+	customInput: Type.Optional(Type.String()),
+});
+
+const AskOutputSchema = Type.Object({
+	cancelled: Type.Boolean({ description: "True when nothing was selected and nothing was typed for any question" }),
+	results: Type.Array(AskAnswerItemSchema),
+});
+
+/** The JSON-shaped copy of one answer (undefined fields are omitted, not null). */
+function toAnswerOutput(result: QuestionResult): {
+	id: string;
+	question: string;
+	description?: string;
+	options: string[];
+	multi: boolean;
+	selectedOptions: string[];
+	customInput?: string;
+} {
+	return {
+		id: result.id,
+		question: result.question,
+		...(result.description !== undefined && { description: result.description }),
+		options: [...result.options],
+		multi: result.multi,
+		selectedOptions: [...result.selectedOptions],
+		...(result.customInput !== undefined && { customInput: result.customInput }),
+	};
+}
+
+/**
+ * The `structuredContent` for a completed round. `cancelled` uses the tool's own
+ * cancel test — nothing selected and nothing typed, for every question — which is
+ * what makes the bridge and headless branches emit the cancel text.
+ */
+function buildAskStructuredContent(results: QuestionResult[]): {
+	cancelled: boolean;
+	results: ReturnType<typeof toAnswerOutput>[];
+} {
+	return {
+		cancelled: results.every((result) => result.selectedOptions.length === 0 && !result.customInput),
+		results: results.map(toAnswerOutput),
+	};
+}
+
 // ── Types ────────────────────────────────────────────────────────────────────
 
 export interface QuestionResult {
@@ -230,6 +294,20 @@ export function registerAskTool(pi: ExtensionAPI): void {
 		label: "Ask",
 		description: ASK_TOOL_DESCRIPTION,
 		parameters: AskParamsSchema,
+		outputSchema: AskOutputSchema,
+		/**
+		 * Declared to the model, never callable from a codemode script — the use pi
+		 * documents the exposure for ("orchestrating or interactive tools").
+		 * `pi: dist/core/agent-session.js`, `_getCallableTools()`: only `direct` +
+		 * active, `codemode` and `deferred` tools are callable, and codemode builds
+		 * its `tools` from that set.
+		 *
+		 * This costs a capability, measured before it was taken: with the old
+		 * default `direct` exposure a codemode script's `tools.ask({...})` resolved
+		 * (to `{"cancelled":true,...}` in a headless session, where there is no UI
+		 * to answer). Scripts lose that; the model's own calls are unaffected.
+		 */
+		exposure: "model-only",
 		renderCall: renderAskCall,
 		renderResult: renderAskResult,
 
@@ -241,7 +319,7 @@ export function registerAskTool(pi: ExtensionAPI): void {
 			// refcount never leaks and the state machine is not stuck at blocked.
 			if (getBridge().active) {
 				const requestId = randomUUID();
-				getBus().emit(Events.ASK_REQUEST, {
+				emitOn(pi.events, Events.ASK_REQUEST, {
 					source: "main",
 					requestId,
 					questions: params.questions,
@@ -258,18 +336,20 @@ export function registerAskTool(pi: ExtensionAPI): void {
 				} catch {
 					response = { cancelled: true, results: params.questions.map((q) => ({ id: q.id, selectedOptions: [] })) };
 				}
-				getBus().emit(Events.ASK_RESPONSE, { requestId, cancelled: response.cancelled, results: response.results });
+				emitOn(pi.events, Events.ASK_RESPONSE, { requestId, cancelled: response.cancelled, results: response.results });
 
 				const results = responseToResults(response, params.questions);
 				if (response.cancelled && results.every((r) => r.selectedOptions.length === 0)) {
 					return {
 						content: [{ type: "text", text: "User cancelled the question." }],
 						details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+						structuredContent: buildAskStructuredContent(results),
 					};
 				}
 				return {
 					content: [{ type: "text", text: buildAskSessionContent(results) }],
 					details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+					structuredContent: buildAskStructuredContent(results),
 				};
 			}
 
@@ -346,12 +426,14 @@ export function registerAskTool(pi: ExtensionAPI): void {
 					return {
 						content: [{ type: "text", text: "User cancelled the question." }],
 						details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+						structuredContent: buildAskStructuredContent(results),
 					};
 				}
 
 				return {
 					content: [{ type: "text", text: buildAskSessionContent(results) }],
 					details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+					structuredContent: buildAskStructuredContent(results),
 				};
 			}
 
@@ -362,8 +444,8 @@ export function registerAskTool(pi: ExtensionAPI): void {
 				};
 			}
 
-			// Emit bus event so notify (if installed) can schedule a desktop notification
-			getBus().emit(Events.ASK_REQUEST, { source: "main", requestId: randomUUID(), questions: params.questions, toolCallId: _toolCallId });
+			// Announce the ask on the handle so notify (if installed) can schedule a desktop notification
+			emitOn(pi.events, Events.ASK_REQUEST, { source: "main", requestId: randomUUID(), questions: params.questions, toolCallId: _toolCallId });
 
 			// Report to herdr's managed extension (inert unless herdr spawned pi — the
 			// event is a no-op otherwise). One pair per dialog; the finally pairs it on
@@ -421,6 +503,7 @@ async function executeTuiAsk(
 		return {
 			content: [{ type: "text", text: buildAskSessionContent([result]) }],
 			details,
+			structuredContent: buildAskStructuredContent([result]),
 		};
 	}
 
@@ -444,5 +527,6 @@ async function executeTuiAsk(
 	return {
 		content: [{ type: "text", text: buildAskSessionContent(results) }],
 		details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+		structuredContent: buildAskStructuredContent(results),
 	};
 }