@dex-ai/ask-extension 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@dex-ai/ask-extension",
+  "version": "0.1.0",
+  "description": "Structured ask tool — multi-choice questions with tabbed wizard flows for the agent.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2",
+    "zod": "^3.23.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/ask.test.ts

@@ -0,0 +1,420 @@
+import { describe, expect, test } from "bun:test";
+import { Agent } from "@dex-ai/sdk";
+import type { Message, ToolOutput } from "@dex-ai/sdk";
+import { askExtension, ASK_REQUEST_KEY, ASK_RESULT_KEY } from "./index";
+import type { AskRequest, AskResult } from "./types";
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+const FAKE_PROVIDER = "scripted";
+const FAKE_MODEL = "scripted-1";
+
+const userMsg = (t: string): Message => ({
+	role: "user",
+	content: [{ type: "text", text: t }],
+});
+
+type FakeStep =
+	| { kind: "tool-call"; toolName: string; input: unknown; toolCallId?: string }
+	| { kind: "text"; text: string };
+
+function scriptedProvider(steps: FakeStep[]) {
+	const queue = steps.slice();
+	let callCount = 0;
+	return {
+		name: FAKE_PROVIDER,
+		models: [
+			{
+				id: FAKE_MODEL,
+				async *stream() {
+					callCount++;
+					const step = queue.shift() ?? { kind: "text" as const, text: "done" };
+					const meta = {
+						providerName: FAKE_PROVIDER,
+						modelId: FAKE_MODEL,
+						startedAt: Date.now(),
+					};
+					yield { type: "response-start", meta };
+					yield { type: "message-start", role: "assistant" };
+
+					if (step.kind === "text") {
+						yield { type: "text-delta", delta: step.text };
+						yield {
+							type: "message-stop",
+							message: {
+								role: "assistant",
+								content: [{ type: "text", text: step.text }],
+							},
+						};
+						yield { type: "finish", reason: "stop", usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } };
+					} else {
+						const toolCallId = step.toolCallId ?? `call-${callCount}`;
+						yield {
+							type: "tool-call",
+							toolCallId,
+							toolName: step.toolName,
+							input: step.input,
+						};
+						yield {
+							type: "message-stop",
+							message: {
+								role: "assistant",
+								content: [
+									{
+										type: "tool-call",
+										toolCallId,
+										toolName: step.toolName,
+										input: step.input,
+									},
+								],
+							},
+						};
+						yield { type: "finish", reason: "tool-calls", usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } };
+					}
+					yield { type: "response-stop", meta, usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, finishReason: step.kind === "text" ? "stop" : "tool-calls" };
+				},
+			},
+		],
+	};
+}
+
+/** Simulate the TUI side: watch for ask:request, then respond after a delay. */
+function autoResponder(
+	agent: { context: { state: Map<string, unknown> } },
+	makeResult: (req: AskRequest) => AskResult,
+	delayMs = 10,
+) {
+	const timer = setInterval(() => {
+		const req = agent.context.state.get(ASK_REQUEST_KEY) as AskRequest | undefined;
+		if (req) {
+			clearInterval(timer);
+			setTimeout(() => {
+				agent.context.state.set(ASK_RESULT_KEY, makeResult(req));
+			}, delayMs);
+		}
+	}, 5);
+	return () => clearInterval(timer);
+}
+
+function lastToolOutput(messages: ReadonlyArray<Message>, toolName: string): string | null {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i]!;
+		if (msg.role !== "tool") continue;
+		for (const c of msg.content) {
+			if (c.type === "tool-result" && (c as any).toolName === toolName) {
+				const out = (c as any).output as ToolOutput;
+				if (out.type === "text") return out.value;
+				if (out.type === "error-text") return out.value;
+				if (out.type === "json") return typeof out.value === "string" ? out.value : JSON.stringify(out.value);
+			}
+		}
+	}
+	return null;
+}
+
+/* ------------------------------------------------------------------ */
+/* Tests                                                              */
+/* ------------------------------------------------------------------ */
+
+const VALID_INPUT = {
+	tabs: [
+		{
+			label: "Scope",
+			question: "What scope?",
+			options: [
+				{ value: "a", label: "Option A" },
+				{ value: "b", label: "Option B" },
+			],
+		},
+	],
+};
+
+describe("structured_ask tool", () => {
+	test("sets ask:request in state and resolves on submit", async () => {
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{ kind: "tool-call", toolName: "structured_ask", input: VALID_INPUT },
+					{ kind: "text", text: "got it" },
+				]),
+				askExtension(),
+			],
+		});
+
+		// Simulate TUI: respond with submit
+		const cleanup = autoResponder(agent, (req) => ({
+			id: req.id,
+			type: "submit",
+			tabs: [{ label: "Scope", selected: ["a"], freeText: null }],
+		}));
+
+		const stream = agent.generate({ input: [userMsg("ask me")] });
+		await stream.result;
+		for await (const _ of stream) { /* drain */ }
+		cleanup();
+
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		expect(output).toBeTruthy();
+		const parsed = JSON.parse(output!);
+		expect(parsed.tabs).toEqual([{ label: "Scope", selected: ["a"], freeText: null }]);
+
+		// State cleaned up
+		expect(agent.context.state.get(ASK_REQUEST_KEY)).toBeUndefined();
+		expect(agent.context.state.get(ASK_RESULT_KEY)).toBeUndefined();
+
+		await agent.dispose();
+	});
+
+	test("eject returns partial results", async () => {
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{
+						kind: "tool-call",
+						toolName: "structured_ask",
+						input: {
+							tabs: [
+								{ label: "Tab1", question: "Q1?", options: [{ value: "x", label: "X" }] },
+								{ label: "Tab2", question: "Q2?", options: [{ value: "y", label: "Y" }] },
+							],
+						},
+					},
+					{ kind: "text", text: "ok lets chat" },
+				]),
+				askExtension(),
+			],
+		});
+
+		const cleanup = autoResponder(agent, (req) => ({
+			id: req.id,
+			type: "eject",
+			completedTabs: [{ label: "Tab1", selected: ["x"], freeText: null }],
+			currentTab: "Tab2",
+			partialSelected: [],
+		}));
+
+		const stream = agent.generate({ input: [userMsg("do it")] });
+		await stream.result;
+		for await (const _ of stream) { /* drain */ }
+		cleanup();
+
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		const parsed = JSON.parse(output!);
+		expect(parsed.ejected).toBe(true);
+		expect(parsed.completedTabs).toHaveLength(1);
+		expect(parsed.currentTab).toBe("Tab2");
+
+		await agent.dispose();
+	});
+
+	test("cancel returns cancelled", async () => {
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{ kind: "tool-call", toolName: "structured_ask", input: VALID_INPUT },
+					{ kind: "text", text: "ok" },
+				]),
+				askExtension(),
+			],
+		});
+
+		const cleanup = autoResponder(agent, (req) => ({
+			id: req.id,
+			type: "cancel",
+		}));
+
+		const stream = agent.generate({ input: [userMsg("ask")] });
+		await stream.result;
+		for await (const _ of stream) { /* drain */ }
+		cleanup();
+
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		const parsed = JSON.parse(output!);
+		expect(parsed.cancelled).toBe(true);
+
+		await agent.dispose();
+	});
+
+	test("concurrent call rejected", async () => {
+		// We can't easily test true concurrency with the generate loop,
+		// but we can verify that if ask:request is already set, a second
+		// call returns an error.
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{ kind: "tool-call", toolName: "structured_ask", input: VALID_INPUT },
+					{ kind: "text", text: "done" },
+				]),
+				askExtension(),
+			],
+		});
+
+		// Pre-set ask:request to simulate an existing pending ask
+		agent.context.state.set(ASK_REQUEST_KEY, { id: "existing", tabs: [] });
+
+		// Also set up a delayed response so it doesn't hang
+		const cleanup = autoResponder(agent, (req) => ({
+			id: req.id,
+			type: "cancel",
+		}), 5);
+
+		const stream = agent.generate({ input: [userMsg("ask")] });
+		await stream.result;
+		for await (const _ of stream) { /* drain */ }
+		cleanup();
+
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		expect(output).toContain("Error");
+		expect(output).toContain("already pending");
+
+		// Clean up the pre-set state
+		agent.context.state.delete(ASK_REQUEST_KEY);
+		await agent.dispose();
+	});
+
+	test("abort signal cancels pending ask", async () => {
+		const controller = new AbortController();
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{ kind: "tool-call", toolName: "structured_ask", input: VALID_INPUT },
+					{ kind: "text", text: "done" },
+				]),
+				askExtension(),
+			],
+			signal: controller.signal,
+		});
+
+		// After request is set, abort
+		const checkTimer = setInterval(() => {
+			if (agent.context.state.get(ASK_REQUEST_KEY)) {
+				clearInterval(checkTimer);
+				setTimeout(() => controller.abort(), 10);
+			}
+		}, 5);
+
+		const stream = agent.generate({ input: [userMsg("go")] });
+		try {
+			await stream.result;
+		} catch {
+			// Abort may throw
+		}
+		for await (const _ of stream) { /* drain */ }
+		clearInterval(checkTimer);
+
+		// On abort the tool should cancel and state should be cleaned up
+		// The tool might produce a cancel output, or the generate loop might
+		// produce an error — either way, state must be clean.
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		if (output) {
+			try {
+				const parsed = JSON.parse(output);
+				expect(parsed.cancelled).toBe(true);
+			} catch {
+				// If not valid JSON, it's an error message from the loop — acceptable
+				expect(output).toContain("abort");
+			}
+		}
+		// Key invariant: state cleaned up after abort
+		expect(agent.context.state.has(ASK_REQUEST_KEY)).toBe(false);
+
+		await agent.dispose();
+	});
+
+	test("multi-tab submit returns all tab results", async () => {
+		const multiInput = {
+			tabs: [
+				{ label: "Scope", question: "What?", options: [{ value: "a", label: "A" }, { value: "b", label: "B" }], multiSelect: true },
+				{ label: "Strategy", question: "How?", options: [{ value: "x", label: "X" }, { value: "y", label: "Y" }] },
+			],
+		};
+
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{ kind: "tool-call", toolName: "structured_ask", input: multiInput },
+					{ kind: "text", text: "done" },
+				]),
+				askExtension(),
+			],
+		});
+
+		const cleanup = autoResponder(agent, (req) => ({
+			id: req.id,
+			type: "submit",
+			tabs: [
+				{ label: "Scope", selected: ["a", "b"], freeText: null },
+				{ label: "Strategy", selected: ["x"], freeText: null },
+			],
+		}));
+
+		const stream = agent.generate({ input: [userMsg("go")] });
+		await stream.result;
+		for await (const _ of stream) { /* drain */ }
+		cleanup();
+
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		const parsed = JSON.parse(output!);
+		expect(parsed.tabs).toHaveLength(2);
+		expect(parsed.tabs[0].selected).toEqual(["a", "b"]);
+		expect(parsed.tabs[1].selected).toEqual(["x"]);
+
+		await agent.dispose();
+	});
+
+	test("free text result included", async () => {
+		const freeTextInput = {
+			tabs: [
+				{
+					label: "Name",
+					question: "Convention?",
+					options: [{ value: "camel", label: "camelCase" }],
+					allowFreeText: true,
+				},
+			],
+		};
+
+		const agent = await Agent.create({
+			provider: FAKE_PROVIDER,
+			model: FAKE_MODEL,
+			extensions: [
+				scriptedProvider([
+					{ kind: "tool-call", toolName: "structured_ask", input: freeTextInput },
+					{ kind: "text", text: "done" },
+				]),
+				askExtension(),
+			],
+		});
+
+		const cleanup = autoResponder(agent, (req) => ({
+			id: req.id,
+			type: "submit",
+			tabs: [{ label: "Name", selected: [], freeText: "PascalCase for types" }],
+		}));
+
+		const stream = agent.generate({ input: [userMsg("go")] });
+		await stream.result;
+		for await (const _ of stream) { /* drain */ }
+		cleanup();
+
+		const output = lastToolOutput(agent.context.messages, "structured_ask");
+		const parsed = JSON.parse(output!);
+		expect(parsed.tabs[0].freeText).toBe("PascalCase for types");
+
+		await agent.dispose();
+	});
+});

package/src/index.ts

@@ -0,0 +1,205 @@
+/**
+ * @dex-ai/ask-extension — Structured ask tool.
+ *
+ * Architecture: zero hard coupling to any TUI/CLI.
+ * - The tool sets `ask:request` in agent.state and polls `ask:result`.
+ * - Any host (CLI TUI, web UI, IDE plugin) watches `ask:request`,
+ *   presents UI, and sets `ask:result` when the user responds.
+ * - The tool picks up the result via polling and returns it to the agent.
+ */
+
+import { Tool } from "@dex-ai/sdk";
+import { z } from "zod";
+import type { GenerateContext } from "@dex-ai/sdk";
+import {
+	ASK_REQUEST_KEY,
+	ASK_RESULT_KEY,
+	type AskRequest,
+	type AskResult,
+	type AskTab,
+} from "./types";
+
+/* ------------------------------------------------------------------ */
+/* Schemas                                                            */
+/* ------------------------------------------------------------------ */
+
+const askOptionSchema = z.object({
+	value: z.string().describe("Unique identifier for this option"),
+	label: z.string().describe("Display label"),
+	description: z.string().optional().describe("Context shown below the label"),
+	selected: z.boolean().optional().describe("Pre-selected by default"),
+});
+
+const askTabSchema = z.object({
+	label: z.string().describe("Tab header label"),
+	question: z.string().describe("The question for this tab"),
+	options: z.array(askOptionSchema).min(1).describe("Choices for this step"),
+	multiSelect: z
+		.boolean()
+		.optional()
+		.default(false)
+		.describe("true = checkboxes (multi), false = radio (single)"),
+	allowFreeText: z
+		.boolean()
+		.optional()
+		.default(false)
+		.describe("Add free-text input option at end"),
+});
+
+const askParams = z.object({
+	tabs: z
+		.array(askTabSchema)
+		.min(1)
+		.max(6)
+		.describe(
+			"Each tab is a step/question. Single tab = simple ask; multiple = wizard. Max 5 question tabs + auto-appended Submit.",
+		),
+});
+
+type AskInput = z.infer<typeof askParams>;
+
+/* ------------------------------------------------------------------ */
+/* Poll interval for result checking                                  */
+/* ------------------------------------------------------------------ */
+
+const POLL_INTERVAL_MS = 50;
+
+/* ------------------------------------------------------------------ */
+/* Tool definition                                                    */
+/* ------------------------------------------------------------------ */
+
+const structuredAskTool = Tool.define({
+	name: "structured_ask",
+	displayName: "Ask User",
+	description:
+		"Ask the user a structured question with multiple-choice options. " +
+		"Supports single/multi-select, free text, and multi-tab wizard flows. " +
+		"The UI replaces the input area until the user responds.",
+	access: "read",
+	visible: false,
+	parameters: askParams,
+
+	async execute(input: AskInput, gctx: GenerateContext) {
+		const requestId = `${gctx.generateId}:${gctx.stepCount}`;
+
+		// Normalize tabs
+		const tabs: AskTab[] = input.tabs.map((t) => ({
+			label: t.label,
+			question: t.question,
+			options: t.options.map((o) => ({
+				value: o.value,
+				label: o.label,
+				...(o.description != null && { description: o.description }),
+				selected: o.selected ?? false,
+			})),
+			multiSelect: t.multiSelect ?? false,
+			allowFreeText: t.allowFreeText ?? false,
+		}));
+
+		// Reject if another ask is already pending
+		const existing = gctx.agent.state.get(ASK_REQUEST_KEY);
+		if (existing) {
+			return {
+				type: "error-text" as const,
+				value: "Error: Another structured_ask is already pending. Wait for it to complete.",
+			};
+		}
+
+		// Publish request into agent state (host UI watches this)
+		const request: AskRequest = { id: requestId, tabs };
+		gctx.agent.state.set(ASK_REQUEST_KEY, request);
+
+		// Wait for result via polling agent.state
+		const result = await new Promise<AskResult>((resolve) => {
+			const timer = setInterval(() => {
+				const res = gctx.agent.state.get(ASK_RESULT_KEY) as
+					| AskResult
+					| null
+					| undefined;
+				if (res && res.id === requestId) {
+					clearInterval(timer);
+					resolve(res);
+				}
+			}, POLL_INTERVAL_MS);
+
+			// Abort signal cleanup
+			const onAbort = () => {
+				clearInterval(timer);
+				gctx.agent.state.delete(ASK_REQUEST_KEY);
+				resolve({ id: requestId, type: "cancel" });
+			};
+			gctx.signal?.addEventListener("abort", onAbort, { once: true });
+
+			// Also listen on agent-level signal
+			gctx.agent.signal?.addEventListener("abort", onAbort, { once: true });
+		});
+
+		// Cleanup state
+		gctx.agent.state.delete(ASK_REQUEST_KEY);
+		gctx.agent.state.delete(ASK_RESULT_KEY);
+
+		// Format output for the agent
+		switch (result.type) {
+			case "submit":
+				return {
+					type: "text" as const,
+					value: JSON.stringify({ tabs: result.tabs }, null, 2),
+				};
+
+			case "eject":
+				return {
+					type: "text" as const,
+					value: JSON.stringify(
+						{
+							ejected: true,
+							message:
+								"User chose to discuss this in chat. Use the completed tabs as context.",
+							completedTabs: result.completedTabs,
+							currentTab: result.currentTab,
+							partialSelected: result.partialSelected,
+						},
+						null,
+						2,
+					),
+				};
+
+			case "cancel":
+				return {
+					type: "text" as const,
+					value: JSON.stringify({ cancelled: true }),
+				};
+		}
+	},
+});
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                  */
+/* ------------------------------------------------------------------ */
+
+export interface AskExtensionOptions {
+	/** Override the tool name. Default: "structured_ask". */
+	name?: string;
+}
+
+export function askExtension(_opts?: AskExtensionOptions) {
+	return {
+		name: "ask",
+		tools: [structuredAskTool],
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Re-exports                                                         */
+/* ------------------------------------------------------------------ */
+
+export type {
+	AskOption,
+	AskTab,
+	AskRequest,
+	AskTabResult,
+	AskResult,
+	AskResultSubmit,
+	AskResultEject,
+	AskResultCancel,
+} from "./types";
+export { ASK_REQUEST_KEY, ASK_RESULT_KEY } from "./types";

package/src/types.ts

@@ -0,0 +1,84 @@
+/* ------------------------------------------------------------------ */
+/* State keys                                                         */
+/* ------------------------------------------------------------------ */
+
+/** Key for the pending ask request (tool → TUI). */
+export const ASK_REQUEST_KEY = "ask:request";
+
+/** Key for the user's response (TUI → tool). */
+export const ASK_RESULT_KEY = "ask:result";
+
+/* ------------------------------------------------------------------ */
+/* Request types (tool → TUI)                                         */
+/* ------------------------------------------------------------------ */
+
+export interface AskOption {
+	/** Unique identifier returned in results. */
+	value: string;
+	/** Display label shown to the user. */
+	label: string;
+	/** Optional description shown below the label (dim text). */
+	description?: string;
+	/** Pre-selected by default. */
+	selected?: boolean;
+}
+
+export interface AskTab {
+	/** Tab header label (e.g. "Scope", "Strategy"). */
+	label: string;
+	/** The question shown when this tab is active. */
+	question: string;
+	/** Choices for this step. */
+	options: AskOption[];
+	/** true = checkboxes (multi-select), false = radio (single-select). */
+	multiSelect: boolean;
+	/** Add a free-text input option at the end. */
+	allowFreeText: boolean;
+}
+
+export interface AskRequest {
+	/** Unique per-call — derived from generateId + stepCount. */
+	id: string;
+	/** One or more tabs (single tab = simple mode, multi = wizard). */
+	tabs: AskTab[];
+}
+
+/* ------------------------------------------------------------------ */
+/* Result types (TUI → tool)                                          */
+/* ------------------------------------------------------------------ */
+
+export interface AskTabResult {
+	/** Matches the tab's label. */
+	label: string;
+	/** Values of the selected options. */
+	selected: string[];
+	/** Free text entered by the user, or null. */
+	freeText: string | null;
+}
+
+/** User submitted all tabs. */
+export interface AskResultSubmit {
+	id: string;
+	type: "submit";
+	tabs: AskTabResult[];
+}
+
+/** User chose "Chat about this" — ejected mid-flow. */
+export interface AskResultEject {
+	id: string;
+	type: "eject";
+	/** Tabs that were fully completed before eject. */
+	completedTabs: AskTabResult[];
+	/** Label of the tab the user was on when they ejected. */
+	currentTab: string;
+	/** Any partially selected values on the current tab. */
+	partialSelected: string[];
+}
+
+/** User pressed Esc to cancel. */
+export interface AskResultCancel {
+	id: string;
+	type: "cancel";
+}
+
+export type AskResult = AskResultSubmit | AskResultEject | AskResultCancel;