@akanjs/devkit 3.0.0-beta.17 → 3.0.0-beta.19

package/codeAgent/tools/McpServerConfig.ts

@@ -3,6 +3,15 @@ import path from "node:path";
 import type { CodeAgentMcpServerRef } from "akanjs/common";
 import { akanCodePaths } from "../agent/akanCodePaths";
 
+/** Which of the two files a server is declared in — see {@link McpServerConfig}. */
+export type McpServerScope = "global" | "workspace";
+
+export interface McpDeclaredServer {
+  ref: CodeAgentMcpServerRef;
+  disabled: boolean;
+  scope: McpServerScope;
+}
+
 interface ServerFileEntry {
   command?: string;
   args?: string[];
@@ -10,6 +19,8 @@ interface ServerFileEntry {
   url?: string;
   type?: string;
   disabled?: boolean;
+  headers?: Record<string, string>;
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
 }
 
 interface ServerFile {
@@ -18,55 +29,76 @@ interface ServerFile {
 }
 
 /**
- * The workspace's declared MCP servers, in the shape the editors already write.
+ * The declared MCP servers, in the shape the editors already write, from two files.
  *
- * `.akan/code/mcp.json` holds an `mcpServers` map — the block a developer already has in their Claude, Cursor
- * or VS Code config — so the file can be pasted rather than translated. `servers` is read as well because VS
- * Code spells it that way, and whichever key the file already uses is the one a write goes back into:
- * rewriting it to our preferred spelling would silently break the editor sharing the file.
+ * `~/.akan/code/mcp.json` is the person's, and `<repo>/.akan/code/mcp.json` is the checkout's. **The global
+ * file is where a server normally goes**: a server is an integration with an account, the token for it
+ * already lives in the home directory, and declaring it per repo means declaring and signing in again in
+ * every checkout. The workspace file is for a server that is genuinely this repo's — one it starts itself, or
+ * one only its team reaches — and a name declared in both resolves to the workspace's, because the more
+ * specific declaration is the one that knew about the other.
+ *
+ * Both hold an `mcpServers` map — the block a developer already has in their Claude, Cursor or VS Code config
+ * — so the file can be pasted rather than translated. `servers` is read as well because VS Code spells it
+ * that way, and whichever key a file already uses is the one a write goes back into: rewriting it to our
+ * preferred spelling would silently break the editor sharing the file.
  */
 export class McpServerConfig {
-  static file(workspaceRoot: string) {
-    return akanCodePaths.mcpFile(workspaceRoot);
+  static file(workspaceRoot: string, scope: McpServerScope = "workspace") {
+    return scope === "global" ? akanCodePaths.globalMcpFile() : akanCodePaths.mcpFile(workspaceRoot);
+  }
+
+  /** Both files, in the order they are merged — global first, so the workspace's entry lands on top of it. */
+  static files(workspaceRoot: string): { scope: McpServerScope; file: string }[] {
+    return [
+      { scope: "global", file: McpServerConfig.file(workspaceRoot, "global") },
+      { scope: "workspace", file: McpServerConfig.file(workspaceRoot, "workspace") },
+    ];
   }
 
   static read(workspaceRoot: string): CodeAgentMcpServerRef[] {
-    const entries = Object.entries(McpServerConfig.#parse(workspaceRoot).map);
-    return entries.filter(([, entry]) => !entry.disabled).map(([name, entry]) => McpServerConfig.#refOf(name, entry));
+    return McpServerConfig.declared(workspaceRoot)
+      .filter((entry) => !entry.disabled)
+      .map((entry) => entry.ref);
   }
 
   /** Every declared server including the disabled ones, which is what a listing has to show. */
-  static declared(workspaceRoot: string) {
-    return Object.entries(McpServerConfig.#parse(workspaceRoot).map).map(([name, entry]) => ({
-      ref: McpServerConfig.#refOf(name, entry),
-      disabled: !!entry.disabled,
-    }));
+  static declared(workspaceRoot: string): McpDeclaredServer[] {
+    const byName = new Map<string, McpDeclaredServer>();
+    for (const { scope } of McpServerConfig.files(workspaceRoot))
+      for (const [name, entry] of Object.entries(McpServerConfig.#parse(workspaceRoot, scope).map))
+        byName.set(name, { ref: McpServerConfig.#refOf(name, entry), disabled: !!entry.disabled, scope });
+    return [...byName.values()];
   }
 
   /**
-   * Declares one server, replacing an entry of the same name.
+   * Declares one server, replacing an entry of the same name in the file it is written to.
    *
    * A url is an http server and anything else is a command with its argv, which is the whole of the guess: a
    * transport asked for as a third argument is a thing to get wrong, and the two shapes are already distinct.
    */
-  static add(workspaceRoot: string, name: string, target: string[]) {
+  static add(workspaceRoot: string, name: string, target: string[], scope: McpServerScope = "global") {
     const [head, ...rest] = target;
     if (!head) throw new Error("Give the server a command to run, or a url to reach.");
     const entry: ServerFileEntry = /^https?:\/\//.test(head) ? { url: head } : { command: head, args: rest };
-    const { file, key, map } = McpServerConfig.#parse(workspaceRoot);
+    const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
     const next = { ...map, [name]: entry };
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
     return McpServerConfig.#refOf(name, entry);
   }
 
-  static remove(workspaceRoot: string, name: string) {
-    const { file, key, map } = McpServerConfig.#parse(workspaceRoot);
-    if (!(name in map)) return false;
-    const next = { ...map };
-    delete next[name];
-    writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
-    return true;
+  /** Removes it from whichever file declares it, and says which — a name can only be in one at a time. */
+  static remove(workspaceRoot: string, name: string): McpServerScope | false {
+    for (const { scope } of [...McpServerConfig.files(workspaceRoot)].reverse()) {
+      const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
+      if (!(name in map)) continue;
+      const next = { ...map };
+      delete next[name];
+      writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
+      return scope;
+    }
+    return false;
   }
 
   static #refOf(name: string, entry: ServerFileEntry): CodeAgentMcpServerRef {
@@ -77,6 +109,8 @@ export class McpServerConfig {
       ...(entry.args ? { args: entry.args } : {}),
       ...(entry.url ? { url: entry.url } : {}),
       ...(entry.env ? { env: entry.env } : {}),
+      ...(entry.headers ? { headers: entry.headers } : {}),
+      ...(entry.oauth ? { oauth: entry.oauth } : {}),
     };
   }
 
@@ -85,20 +119,21 @@ export class McpServerConfig {
     return ref.url ?? [ref.command, ...(ref.args ?? [])].filter(Boolean).join(" ");
   }
 
-  /** Why the file yielded nothing, when it exists and yielded nothing — a listing has to say which. */
+  /** Why a file yielded nothing, when it exists and yielded nothing — a listing has to say which. */
   static problem(workspaceRoot: string) {
-    const file = McpServerConfig.file(workspaceRoot);
-    if (!existsSync(file)) return undefined;
-    try {
-      JSON.parse(readFileSync(file, "utf8"));
-      return undefined;
-    } catch (error) {
-      return `${file} is not valid JSON — ${String(error)}`;
+    for (const { file } of McpServerConfig.files(workspaceRoot)) {
+      if (!existsSync(file)) continue;
+      try {
+        JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        return `${file} is not valid JSON — ${String(error)}`;
+      }
     }
+    return undefined;
   }
 
-  static #parse(workspaceRoot: string) {
-    const file = McpServerConfig.file(workspaceRoot);
+  static #parse(workspaceRoot: string, scope: McpServerScope) {
+    const file = McpServerConfig.file(workspaceRoot, scope);
     const empty = { file, key: "mcpServers" as const, map: {} as Record<string, ServerFileEntry> };
     if (!existsSync(file)) return empty;
     try {

package/codeAgent/tools/McpSignIn.ts

@@ -0,0 +1,161 @@
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { McpOAuth, type McpOAuthServer } from "./McpOAuth";
+import { McpOAuthLoopback } from "./McpOAuthLoopback";
+import { type McpStoredAuth, McpTokenStore } from "./McpTokenStore";
+
+export interface McpSignInOptions {
+  /** How the host reaches a browser. A host with none must not call {@link McpSignIn.run}. */
+  open: (url: string) => void;
+  onNotice?: (message: string) => void;
+}
+
+/**
+ * Signing one MCP server in, and keeping it signed in.
+ *
+ * The two halves are deliberately apart. {@link token} runs at connect and is allowed to do anything that
+ * needs no person — read a stored token, refresh an expired one — while {@link run} opens a browser and is
+ * only ever called by a host that has somebody in front of it.
+ *
+ * Connecting must never block on a sign-in. `McpToolPack.connect` happens inside `CodeAgent.create`, before
+ * the first frame is drawn, so a browser round trip there would hold the whole session on a screen that does
+ * not exist yet. A server that needs a credential and has none is reported, not waited for.
+ */
+export class McpSignIn {
+  /**
+   * The bearer token to connect with, or undefined when there is none to be had without asking.
+   *
+   * A refresh that fails is not an error here: the stored grant was revoked or expired past refreshing, and
+   * the answer is the same as having no token at all — the server will say so, and the host will offer a
+   * sign-in. Throwing would cost the session every other server's tools.
+   */
+  static async token(ref: CodeAgentMcpServerRef, onNotice?: (message: string) => void) {
+    const stored = McpTokenStore.read(ref.name);
+    if (!stored) return undefined;
+    if (!McpTokenStore.isExpired(stored)) return stored.accessToken;
+    if (!stored.refreshToken) return undefined;
+    try {
+      const server: McpOAuthServer = {
+        issuer: stored.issuer,
+        authorizationEndpoint: "",
+        tokenEndpoint: stored.tokenEndpoint,
+        resource: stored.resource,
+      };
+      const tokens = await McpOAuth.refresh(server, stored);
+      McpTokenStore.write(ref.name, {
+        ...stored,
+        accessToken: tokens.accessToken,
+        // A server that rotates refresh tokens invalidates the old one, so keeping it would sign us out.
+        ...(tokens.refreshToken ? { refreshToken: tokens.refreshToken } : {}),
+        ...(tokens.expiresAt ? { expiresAt: tokens.expiresAt } : {}),
+        ...(tokens.scope ? { scope: tokens.scope } : {}),
+      });
+      return tokens.accessToken;
+    } catch (error) {
+      onNotice?.(`MCP server "${ref.name}" needs signing in again — ${String(error)}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * The whole interactive flow: discover, register if needed, open a browser, store the token.
+   *
+   * The client registration is reused across sign-ins when the server it was made against has not moved, so a
+   * second sign-in to the same provider creates no second client entry in whatever account page lists them.
+   */
+  static async run(ref: CodeAgentMcpServerRef, options: McpSignInOptions): Promise<McpStoredAuth> {
+    if (!ref.url) throw new Error(`"${ref.name}" is a stdio server: give it its credential through "env".`);
+    const challenge = await McpSignIn.challenge(ref);
+    const server = await McpOAuth.discover(ref.url, challenge);
+    const stored = McpTokenStore.read(ref.name);
+    const reusable = stored && stored.issuer === server.issuer && !ref.oauth?.clientId ? stored : undefined;
+    const loopback = McpOAuthLoopback.bind(McpSignIn.#portOf(reusable?.redirectUri));
+    try {
+      const redirectUri = loopback.redirectUri;
+      const client = await McpSignIn.#client(ref, server, redirectUri, reusable);
+      options.onNotice?.(`Opening a browser to sign in to "${ref.name}"…`);
+      const scope = McpOAuth.scopeOf(ref, server);
+      const tokens = await McpOAuth.authorize({
+        server,
+        clientId: client.clientId,
+        ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+        redirectUri,
+        ...(scope ? { scope } : {}),
+        open: options.open,
+        wait: () => loopback.wait(),
+      });
+      const auth: McpStoredAuth = {
+        issuer: server.issuer,
+        tokenEndpoint: server.tokenEndpoint,
+        resource: server.resource,
+        clientId: client.clientId,
+        ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+        redirectUri,
+        accessToken: tokens.accessToken,
+        ...(tokens.refreshToken ? { refreshToken: tokens.refreshToken } : {}),
+        ...(tokens.expiresAt ? { expiresAt: tokens.expiresAt } : {}),
+        ...(tokens.scope ? { scope: tokens.scope } : {}),
+      };
+      McpTokenStore.write(ref.name, auth);
+      return auth;
+    } finally {
+      loopback.close();
+    }
+  }
+
+  /**
+   * What the server answers an unauthenticated `initialize` with, or null when it wants no credential.
+   *
+   * Asked before discovery because the challenge names the resource metadata, and a server serving it under a
+   * path publishes a url no client can derive. A server that answers anything but `401` is one that does not
+   * need signing in, which is worth saying rather than running a flow against.
+   */
+  static async challenge(ref: CodeAgentMcpServerRef) {
+    if (!ref.url) return null;
+    try {
+      const response = await fetch(ref.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+          ...ref.headers,
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 0,
+          method: "initialize",
+          params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "akan-code", version: "1" } },
+        }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      return response.status === 401 ? (response.headers.get("www-authenticate") ?? "") : null;
+    } catch {
+      // Unreachable is not unauthenticated. Discovery will try the well-known urls and report its own failure.
+      return null;
+    }
+  }
+
+  static async #client(
+    ref: CodeAgentMcpServerRef,
+    server: McpOAuthServer,
+    redirectUri: string,
+    reusable: McpStoredAuth | undefined,
+  ) {
+    if (ref.oauth?.clientId)
+      return {
+        clientId: ref.oauth.clientId,
+        ...(ref.oauth.clientSecret ? { clientSecret: ref.oauth.clientSecret } : {}),
+      };
+    if (reusable && reusable.redirectUri === redirectUri)
+      return {
+        clientId: reusable.clientId,
+        ...(reusable.clientSecret ? { clientSecret: reusable.clientSecret } : {}),
+      };
+    return await McpOAuth.register(server, redirectUri, ref.name);
+  }
+
+  static #portOf(redirectUri: string | undefined) {
+    if (!redirectUri) return undefined;
+    const port = Number(new URL(redirectUri).port);
+    return Number.isFinite(port) && port > 0 ? port : undefined;
+  }
+}

package/codeAgent/tools/McpTokenStore.ts

@@ -0,0 +1,92 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { akanCodePaths } from "../agent/akanCodePaths";
+
+/** One server's credential, and the client registration it was issued against. */
+export interface McpStoredAuth {
+  /** The authorization server that minted it, so a server that moves issuer invalidates rather than misuses it. */
+  issuer: string;
+  /** Kept with the token so a refresh at connect costs no discovery round trip before the first tool call. */
+  tokenEndpoint: string;
+  /** RFC 8707: what the token was minted for, which a refresh has to restate. */
+  resource: string;
+  clientId: string;
+  clientSecret?: string;
+  /** Registered with the client, so a later sign-in binds the same loopback port or registers again. */
+  redirectUri: string;
+  accessToken: string;
+  refreshToken?: string;
+  /** Epoch ms. Absent when the server issued no lifetime, which the spec allows and means "until refused". */
+  expiresAt?: number;
+  scope?: string;
+}
+
+/**
+ * The MCP bearer tokens, in the home directory and readable only by their owner.
+ *
+ * Never in the workspace: `.akan/code/mcp.json` is shared with the editors and routinely committed, and a
+ * refresh token there is a credential in the repo. The file is written whole through a rename so a crash
+ * mid-write cannot leave a truncated one, and a read that cannot parse it costs the sign-ins rather than the
+ * session — a corrupt file re-authenticates, which is recoverable, where a thrown error is not.
+ */
+export class McpTokenStore {
+  static file() {
+    return akanCodePaths.mcpAuthFile();
+  }
+
+  static read(name: string): McpStoredAuth | undefined {
+    return McpTokenStore.#all()[name];
+  }
+
+  static names() {
+    return Object.keys(McpTokenStore.#all());
+  }
+
+  /**
+   * Writes one entry, re-reading immediately before the write.
+   *
+   * Two sessions signing in to different servers at the same moment would otherwise each write the map they
+   * read at the start of their own flow — minutes earlier, across a browser round trip — and the second would
+   * drop the first's token.
+   */
+  static write(name: string, auth: McpStoredAuth) {
+    McpTokenStore.#save({ ...McpTokenStore.#all(), [name]: auth });
+  }
+
+  static clear(name: string) {
+    const all = McpTokenStore.#all();
+    if (!(name in all)) return false;
+    delete all[name];
+    McpTokenStore.#save(all);
+    return true;
+  }
+
+  /** Expired, or close enough that a call started now would land after it — see {@link skewMs}. */
+  static isExpired(auth: McpStoredAuth) {
+    return auth.expiresAt !== undefined && auth.expiresAt <= Date.now() + McpTokenStore.skewMs;
+  }
+
+  /** A token is treated as spent this long before it actually is, so a call never races its own expiry. */
+  static readonly skewMs = 60_000;
+
+  static #all(): Record<string, McpStoredAuth> {
+    const file = McpTokenStore.file();
+    if (!existsSync(file)) return {};
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as { servers?: Record<string, McpStoredAuth> };
+      return parsed.servers ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  static #save(servers: Record<string, McpStoredAuth>) {
+    const file = McpTokenStore.file();
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ servers }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    // `rename` keeps the temp file's mode, but an existing target written by an older build may be looser.
+    chmodSync(file, 0o600);
+  }
+}

package/codeAgent/tools/McpToolPack.ts

@@ -7,8 +7,9 @@ import {
   codeAgentOutputChars,
 } from "akanjs/common";
 import { Type } from "typebox";
-import { McpClient, type McpToolInfo } from "./McpClient";
+import { McpClient, type McpToolInfo, McpUnauthorized } from "./McpClient";
 import { McpServerConfig } from "./McpServerConfig";
+import { McpSignIn } from "./McpSignIn";
 
 export interface McpToolPackOptions {
   workspaceRoot: string;
@@ -45,12 +46,24 @@ export class McpToolPack {
     const pack = new McpToolPack();
     for (const ref of refs) {
       const base = { name: ref.name, transport: ref.transport, target: McpServerConfig.targetOf(ref) };
+      // Stored or refreshed, never asked for: connecting runs inside `CodeAgent.create`, and a browser round
+      // trip there would hold the session on a screen that has not been drawn yet — see {@link McpSignIn}.
+      const token = ref.transport === "http" ? await McpSignIn.token(ref, options.onNotice) : undefined;
       try {
-        const client = await new McpClient(ref).connect();
+        const client = await new McpClient(ref, token).connect();
         const tools = await client.listTools();
         pack.#clients.push({ client, tools });
-        pack.#status.push({ ...base, tools: tools.map((tool) => McpToolPack.#nameOf(ref.name, tool.name)) });
+        pack.#status.push({
+          ...base,
+          tools: tools.map((tool) => McpToolPack.#nameOf(ref.name, tool.name)),
+          auth: token ? "authorized" : "none",
+        });
       } catch (error) {
+        if (error instanceof McpUnauthorized) {
+          options.onNotice?.(`MCP server "${ref.name}" needs signing in — /mcp login ${ref.name}`);
+          pack.#status.push({ ...base, tools: [], auth: "required" });
+          continue;
+        }
         // One unreachable integration must not cost the agent its turn, so it costs only its own tools.
         options.onNotice?.(`MCP server "${ref.name}" is unavailable: ${String(error)}`);
         pack.#status.push({ ...base, tools: [], error: String(error) });

package/codeAgent/tools/askToolPack.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import { type CodeAgentProfile, type CodeAgentQuestion, codeAgentPresets } from "akanjs/common";
+import { AskToolPack } from "./AskToolPack";
+
+interface RegisteredTool {
+  name: string;
+  description: string;
+  execute: (
+    id: string,
+    params: { questions?: unknown[] },
+  ) => Promise<{ content: { text?: string }[]; isError?: boolean }>;
+}
+
+/** Runs the pack's extension and hands back the one tool it registered, plus the questions it went on to ask. */
+const mount = (
+  profile: CodeAgentProfile,
+  answer: (question: Omit<CodeAgentQuestion, "questionId">) => string | undefined,
+) => {
+  const asked: Omit<CodeAgentQuestion, "questionId">[] = [];
+  const pack = new AskToolPack({
+    profile,
+    ask: async (question) => {
+      asked.push(question);
+      return answer(question);
+    },
+  });
+  const tools: RegisteredTool[] = [];
+  const extension = pack.extension();
+  if (extension && "factory" in extension)
+    extension.factory({ registerTool: (spec: RegisteredTool) => tools.push(spec) } as never);
+  return { pack, tool: tools[0], asked };
+};
+
+const local = codeAgentPresets.local("/repo");
+const pod = codeAgentPresets.pod("/repo");
+
+const one = (patch: Record<string, unknown> = {}) => ({
+  question: "Which database?",
+  options: [{ label: "Postgres" }, { label: "SQLite", recommended: true }],
+  ...patch,
+});
+
+describe("ask_user", () => {
+  test("it is published only where somebody can answer", () => {
+    expect(mount(local, () => "x").pack.names()).toEqual(["ask_user"]);
+    // A pod and a sub-agent both set `canPrompt` false; the tool is never constructed there.
+    expect(mount(pod, () => "x").pack.names()).toEqual([]);
+    expect(mount(pod, () => "x").tool).toBeUndefined();
+  });
+
+  test("a question reaches the wire with its options, and the answer comes back as the label", async () => {
+    const { tool, asked } = mount(local, () => "SQLite");
+    const result = await tool?.execute("t", { questions: [one()] });
+    expect(asked[0]).toMatchObject({
+      prompt: "Which database?",
+      kind: "select",
+      options: [
+        { key: "0", label: "Postgres" },
+        { key: "1", label: "SQLite", recommended: true },
+      ],
+    });
+    expect(result?.content[0]?.text).toContain("→ SQLite");
+  });
+
+  test("a header is folded into the prompt, because the wire carries one line", async () => {
+    const { tool, asked } = mount(local, () => "a");
+    await tool?.execute("t", { questions: [one({ header: "Storage" })] });
+    expect(asked[0]?.prompt).toBe("Storage — Which database?");
+  });
+
+  test("several questions are asked in order, one at a time", async () => {
+    const { tool, asked } = mount(local, (question) => (question.prompt.includes("database") ? "SQLite" : "Yes"));
+    const result = await tool?.execute("t", {
+      questions: [one(), { question: "Run migrations now?", options: [{ label: "Yes" }, { label: "No" }] }],
+    });
+    expect(asked.map((entry) => entry.prompt)).toEqual(["Which database?", "Run migrations now?"]);
+    expect(result?.content[0]?.text).toContain("Which database?\n→ SQLite");
+    expect(result?.content[0]?.text).toContain("Run migrations now?\n→ Yes");
+  });
+
+  test("more questions than fit on a screen are cut rather than drawn over the transcript", async () => {
+    const { tool, asked } = mount(local, () => "a");
+    await tool?.execute("t", { questions: Array.from({ length: 7 }, (_, at) => one({ question: `Q${at}?` })) });
+    expect(asked).toHaveLength(AskToolPack.maxQuestions);
+  });
+
+  /** A blank answer reads to a model as "the user wanted nothing", which is the one thing a skip never means. */
+  test("a skipped question says so, and says what to do about it", async () => {
+    const { tool } = mount(local, () => undefined);
+    const result = await tool?.execute("t", { questions: [one()] });
+    expect(result?.content[0]?.text).toContain("skipped");
+    expect(result?.content[0]?.text).toContain("decide this yourself");
+  });
+
+  test("free text is offered unless the model turns it off", async () => {
+    const { tool, asked } = mount(local, () => "a");
+    await tool?.execute("t", { questions: [one(), one({ freeText: false })] });
+    expect(asked[0]?.freeText).toBe(true);
+    expect(asked[1]?.freeText).toBe(false);
+  });
+
+  test("a question with no options asks for prose", async () => {
+    const { tool, asked } = mount(local, () => "because of the index");
+    await tool?.execute("t", { questions: [{ question: "Why is it slow?" }] });
+    expect(asked[0]?.kind).toBe("text");
+    expect(asked[0]?.options).toBeUndefined();
+  });
+
+  test("multi-select travels as itself", async () => {
+    const { tool, asked } = mount(local, () => "a, b");
+    await tool?.execute("t", { questions: [one({ multiSelect: true })] });
+    expect(asked[0]?.multiSelect).toBe(true);
+  });
+
+  test("asking nothing is a mistake, not an empty answer", async () => {
+    const { tool } = mount(local, () => "a");
+    expect((await tool?.execute("t", { questions: [] }))?.isError).toBe(true);
+  });
+});