Implemented asking questions during the planning mode or conversations

Author: Relrin

bun.lock

@@ -19,6 +19,7 @@
     "iconv-lite": "0.6.3",
     "ignore": "7.0.5",
     "tree-kill": "1.2.2",
+    "typebox": "1.1.38",
     "vscode-jsonrpc": "9.0.0",
     "vscode-languageserver-protocol": "3.18.0",
     "ws": "~8.20.1",

packages/core/package.json

@@ -25,6 +25,11 @@ export const DEFAULT_READ_ONLY_TOOLS: ReadonlySet<string> = new Set([
   "ls",
   "glob",
   "tree",
+
+  // A shortcut to enable interactions between an agent and a developer. This flow would
+  // allow to ask questions and then get a response from the user. The response is used
+  // by the agent to make a decision
+  "ask_user_question",
 ]);
 
 /** Plan mode defaults to prompting (rather than blocking) for non-read-only operations. */

packages/core/src/extensions/agent-mode/decision.ts

@@ -31,8 +31,10 @@ function planSection(planFilePath: string): string {
     "except for the plan file itself (see below). Other writes will be blocked by the host.",
     "",
     "Use read-only tools (read, grep, glob, web fetch) to research about the problem and prepare",
-    "code before you commit to anything. If the request is ambiguous, ask focused clarifying",
-    "questions as your final message and stop — the user answers in their next turn.",
+    "code before you commit to anything. When a decision is genuinely open or ambiguous and",
+    "when its possible to offer concrete options (e.g. with code / diff previews) — ask a user",
+    "instead of writing the options into the plan or listing them as prose. It renders an interactive ",
+    "picker and pauses for the answer, which then steers the plan.",
     "",
     "When the request is clear enough, you MUST save the plan to the file with the write",
     "tool. Any further updates also should be applied and reflected in the plan file. Write " +

packages/core/src/extensions/agent-mode/plan-prompt.ts

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+import {
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionFactory,
+} from "@earendil-works/pi-coding-agent";
+import type { AskUserAnswer } from "../../protocol/commands.js";
+import type { AskUserQuestion } from "../../protocol/events.js";
+import type { AskFrontend } from "./frontend.js";
+import { AskUserToolParams } from "./schema.js";
+
+/** The tool id the model calls. */
+export const ASK_USER_TOOL_NAME = "ask_user_question";
+
+const TOOL_DESCRIPTION =
+  "Ask the user one to four structured multiple-choice questions and wait for their answer. " +
+  "Reach for this the moment a decision is ambiguous and costly to reverse, or to let the user " +
+  "steer a plan - instead of guessing or listing the options as prose. " +
+  "IMPORTANT: when you ask, CALL THIS TOOL as your action; do NOT also write the question or its " +
+  "options as assistant text - the card renders them. The UI always offers the user a free-text " +
+  '"Something else" answer, so you never need to add your own "other" option. ' +
+  "Set `multiSelect` for 'choose any', and give an option a `preview` (markdown, e.g. a fenced " +
+  "code/diff block) to show what it would change. The tool returns the user's selections as text.";
+
+const TOOL_PROMPT_SNIPPET =
+  "ask_user_question — ask the user 1–4 multiple-choice questions and wait for their pick; use " +
+  "when a decision is ambiguous or to let them steer a plan.";
+
+const TOOL_GUIDELINES = [
+  "When a choice is ambiguous and hard to undo, call ask_user_question instead of guessing.",
+  "Call the tool directly - do not first write the question or options as plain text; the card " +
+    "renders them. Narrating them as prose and then calling the tool duplicates everything.",
+  "Keep each question focused with 2–4 distinct options and a one-line description each.",
+  "Use one question for a single decision, or several to gather related choices at once " +
+    "(typical while planning).",
+  "A free-text answer is always available to the user - don't add your own 'other' / " +
+    "'something else' option.",
+  "Don't use it for trivial or easily reversible choices - just proceed.",
+];
+
+export interface AskUserExtensionOptions {
+  /** Where questions are presented and answers collected. pi-deck injects a GUI frontend. */
+  frontend: AskFrontend;
+}
+
+export interface AskUserController {
+  /** Pass to `DefaultResourceLoader({ extensionFactories: [...] })`. */
+  readonly factory: ExtensionFactory;
+  /** Cancel any in-flight questions (delegates to the frontend). */
+  dispose(): void;
+}
+
+/**
+ * pi-deck's self-contained "ask the user a question" plugin. It registers the
+ * `ask_user_question` tool; its `execute()` suspends on the injected {@link AskFrontend} and
+ * returns the user's answer as a clean tool result (no terminal dependency, no block-hack).
+ *
+ * The plugin owns no IO and no network: just the tool and a frontend port, so it can later be
+ * lifted into a standalone package.
+ */
+export function createAskUserExtension(options: AskUserExtensionOptions): AskUserController {
+  const { frontend } = options;
+
+  const factory: ExtensionFactory = (pi: ExtensionAPI) => {
+    pi.registerTool(
+      defineTool({
+        name: ASK_USER_TOOL_NAME,
+        label: "Ask the user",
+        description: TOOL_DESCRIPTION,
+        promptSnippet: TOOL_PROMPT_SNIPPET,
+        promptGuidelines: TOOL_GUIDELINES,
+        parameters: AskUserToolParams,
+        async execute(toolCallId, params, signal) {
+          const questions = params.questions as AskUserQuestion[];
+          const answer = await frontend.present(
+            { askId: randomUUID(), toolCallId, questions },
+            signal,
+          );
+          return {
+            content: [{ type: "text" as const, text: formatAnswers(questions, answer) }],
+            details: undefined,
+          };
+        },
+      }),
+    );
+  };
+
+  return {
+    factory,
+    dispose() {
+      frontend.dispose?.();
+    },
+  };
+}
+
+/**
+ * Render the user's answer as a compact, model-friendly transcript that becomes the tool
+ * result. Index-aligned to `questions`, tolerant of a short/partial answers array.
+ */
+export function formatAnswers(questions: AskUserQuestion[], answer: AskUserAnswer): string {
+  if (answer.cancelled) {
+    return (
+      "The user dismissed the question without answering. Proceed using your best judgment, " +
+      "or ask again if you still need a decision."
+    );
+  }
+  const blocks = questions.map((q, i) => {
+    const n = i + 1;
+    const a = answer.answers[i];
+    let ans: string;
+    if (!a || a.skipped) {
+      ans = "(skipped)";
+    } else {
+      const picks: string[] = [];
+      for (const idx of a.optionIndices) {
+        const opt = q.options[idx];
+        if (opt) picks.push(opt.label);
+      }
+
+      if (a.custom?.trim()) picks.push(a.custom.trim());
+      ans = picks.length > 0 ? picks.join(", ") : "(no selection)";
+    }
+    return `Q${n}: ${q.question}\nA${n}: ${ans}`;
+  });
+  return blocks.join("\n\n");
+}

packages/core/src/extensions/ask-user/ask-user.ts

@@ -0,0 +1,108 @@
+import type { AskUserAnswer } from "../../protocol/commands.js";
+import type { AskUserQuestion } from "../../protocol/events.js";
+
+/** Default wait before an unanswered question auto-cancels. Questions (especially plan-steering
+ * ones) can take a while to think through, so this is far longer than the approval timeout. */
+export const ASK_USER_TIMEOUT_MS = 30 * 60_000;
+
+/** A pending question handed to whatever frontend is wired in. */
+export interface AskRequest {
+  askId: string;
+  toolCallId: string;
+  questions: AskUserQuestion[];
+}
+
+/**
+ * Frontend-agnostic port the ask-user tool talks to. The tool doesn't know or care whether a
+ * GUI or a TUI is on the other end - it just `present()`s a request and awaits an answer.
+ * pi-deck injects a GUI frontend (see `createDeferredFrontend`); a terminal presenter is a
+ * clean future drop-in against the same interface.
+ */
+export interface AskFrontend {
+  present(request: AskRequest, signal?: AbortSignal): Promise<AskUserAnswer>;
+  /** Optional: cancel any in-flight questions when the session shuts down. */
+  dispose?(): void;
+}
+
+export interface DeferredFrontendOptions {
+  /** Called synchronously when a question needs to reach the user (e.g. emit a host event). */
+  onAskRequest: (request: AskRequest) => void;
+  /** Auto-cancel timeout. Defaults to {@link ASK_USER_TIMEOUT_MS}. */
+  timeoutMs?: number;
+  /** Injectable timers for deterministic tests. */
+  timers?: {
+    setTimeout: (cb: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+  };
+}
+
+export interface DeferredFrontend extends AskFrontend {
+  /** Resolve a pending question with the user's answer. Unknown ids are a no-op so a stale or
+   * duplicate reply from the renderer doesn't throw. */
+  resolveAsk(askId: string, answer: AskUserAnswer): void;
+  /** Snapshot of currently pending question ids. */
+  pendingAskIds(): string[];
+  /** Cancel every pending question; used when the worker shuts down mid-turn. */
+  dispose(): void;
+}
+
+const CANCELLED: AskUserAnswer = { answers: [], cancelled: true };
+
+interface PendingEntry {
+  resolve: (answer: AskUserAnswer) => void;
+  cleanup: () => void;
+}
+
+/**
+ * The host-driven realization of {@link AskFrontend}: `present()` registers a pending entry,
+ * fires `onAskRequest`, and suspends until `resolveAsk()` is called from the host (with the
+ * renderer's answer), the timeout elapses, or the turn's `AbortSignal` fires. This is exactly
+ * what the GUI flow needs - it mirrors the agent-mode approval suspend/resume machinery.
+ */
+export function createDeferredFrontend(options: DeferredFrontendOptions): DeferredFrontend {
+  const timers = options.timers ?? {
+    setTimeout: (cb, ms) => globalThis.setTimeout(cb, ms),
+    clearTimeout: (h) => globalThis.clearTimeout(h as ReturnType<typeof globalThis.setTimeout>),
+  };
+  const timeoutMs = options.timeoutMs ?? ASK_USER_TIMEOUT_MS;
+  const pending = new Map<string, PendingEntry>();
+
+  function finish(askId: string, answer: AskUserAnswer): void {
+    const entry = pending.get(askId);
+    if (!entry) return;
+    pending.delete(askId);
+    entry.cleanup();
+    entry.resolve(answer);
+  }
+
+  return {
+    present(request, signal) {
+      return new Promise<AskUserAnswer>((resolve) => {
+        if (signal?.aborted) {
+          resolve(CANCELLED);
+          return;
+        }
+        const timerHandle = timers.setTimeout(() => finish(request.askId, CANCELLED), timeoutMs);
+        const onAbort = () => finish(request.askId, CANCELLED);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        pending.set(request.askId, {
+          resolve,
+          cleanup: () => {
+            timers.clearTimeout(timerHandle);
+            signal?.removeEventListener("abort", onAbort);
+          },
+        });
+        options.onAskRequest(request);
+      });
+    },
+    resolveAsk(askId, answer) {
+      finish(askId, answer);
+    },
+    pendingAskIds() {
+      return [...pending.keys()];
+    },
+    dispose() {
+      for (const askId of [...pending.keys()]) finish(askId, CANCELLED);
+    },
+  };
+}

packages/core/src/extensions/ask-user/frontend.ts

@@ -0,0 +1,16 @@
+export {
+  ASK_USER_TOOL_NAME,
+  type AskUserController,
+  type AskUserExtensionOptions,
+  createAskUserExtension,
+  formatAnswers,
+} from "./ask-user.js";
+export {
+  ASK_USER_TIMEOUT_MS,
+  type AskFrontend,
+  type AskRequest,
+  createDeferredFrontend,
+  type DeferredFrontend,
+  type DeferredFrontendOptions,
+} from "./frontend.js";
+export { type AskUserToolInput, AskUserToolParams } from "./schema.js";

packages/core/src/extensions/ask-user/index.ts

@@ -0,0 +1,69 @@
+import { type Static, Type } from "typebox";
+
+/**
+ * TypeBox parameter schema for the `ask_user_question` tool - this is what the model fills in.
+ * It is deliberately our *own*, presentation-agnostic shape (content + semantics only, no
+ * layout/pixel fields) so the same payload can be rendered by the pi-deck GUI today or a TUI.
+ *
+ * The wire/runtime question shape is defined once as Zod in `protocol/events.ts`
+ * (`AskUserQuestionSchema`); a runtime test keeps the two in lock-step.
+ */
+const AskUserOptionParams = Type.Object(
+  {
+    id: Type.Optional(Type.String({ description: "Optional stable id for the option." })),
+    label: Type.String({ description: "Short option label shown to the user." }),
+    description: Type.Optional(
+      Type.String({ description: "One-line explanation of what this option means or does." }),
+    ),
+    preview: Type.Optional(
+      Type.String({
+        description:
+          "Optional preview of the concrete change this option makes - ONLY a fenced code or " +
+          "diff block (```lang ... ```). It opens a side-by-side code pane. Do NOT put prose " +
+          "trade-offs here (those go in `description`); a non-code preview is ignored.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const AskUserQuestionParams = Type.Object(
+  {
+    id: Type.Optional(Type.String({ description: "Optional stable id for the question." })),
+    header: Type.String({ description: "Very short section/tab label, e.g. 'Theme strategy'." }),
+    question: Type.String({ description: "The question to put to the user." }),
+    options: Type.Array(AskUserOptionParams, {
+      minItems: 2,
+      maxItems: 4,
+      description: "Two to four options the user can pick from.",
+    }),
+    multiSelect: Type.Optional(
+      Type.Boolean({ description: "Allow selecting several options (checkbox list)." }),
+    ),
+    allowCustom: Type.Optional(
+      Type.Boolean({ description: "Offer a free-text 'Something else' answer." }),
+    ),
+    minSelect: Type.Optional(
+      Type.Number({ description: "Minimum selections for a multiSelect question." }),
+    ),
+    maxSelect: Type.Optional(
+      Type.Number({ description: "Maximum selections for a multiSelect question." }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const AskUserToolParams = Type.Object(
+  {
+    questions: Type.Array(AskUserQuestionParams, {
+      minItems: 1,
+      maxItems: 4,
+      description:
+        "One to four questions to put to the user. Use a single question for a focused " +
+        "decision; use several to gather a few related choices at once (e.g. while planning).",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+export type AskUserToolInput = Static<typeof AskUserToolParams>;

packages/core/src/extensions/ask-user/schema.ts

@@ -437,6 +437,11 @@ const handlers: { [C in CommandName]: CommandHandler } = {
     );
     return { ok: true as const };
   },
+  "session.answerQuestion": async (ctx, payload) => {
+    const parsed = CommandSchemas["session.answerQuestion"].request.parse(payload);
+    await ctx.sessionManager.answerQuestion(parsed.sessionId, parsed.askId, parsed.answer);
+    return { ok: true as const };
+  },
   "plan.file.read": async (ctx, payload) => {
     const parsed = CommandSchemas["plan.file.read"].request.parse(payload);
     const record = ctx.sessionManager.get(parsed.sessionId);