@fitchmultz/pi-ask-question 0.6.5 → 0.6.6

package/extensions/lib/question-observer.ts

@@ -1,14 +1,19 @@
+/** Runtime-local observer for the cooperative answer-bus protocol. */
+
 import { createHash, randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord, validId } from "./validate.ts";
 
-type Target = {
+/** A prompt target: which prompt, question, and revision an answer applies to. */
+export type Target = {
   promptId: string;
   questionId: string;
   revision: number;
   deadline: number;
 };
 
-type Waiting = Target & {
+/** The waiting state an owner publishes while a prompt is accepting answers. */
+export type Waiting = Target & {
   status: "waiting";
   timeoutActive: boolean;
   question: string;
@@ -16,120 +21,191 @@ type Waiting = Target & {
   multiSelect: boolean;
 };
 
-function record(data: unknown): Record<string, unknown> | undefined {
-  return data !== null && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
-}
+/** Identity fields shared by every protocol message from one owner. */
+export type ObserverIdentity = {
+  protocolVersion: number;
+  ownerGeneration: string;
+  nativeRoot: string | undefined;
+};
 
-function validId(value: unknown): value is string {
-  return typeof value === "string" && Boolean(value.trim()) && value.length <= 128;
-}
+/** A recorded answer receipt: target plus request identity and fingerprint. */
+type Receipt = Target & { requestId: string; answerFingerprint: string };
+
+/** The observer surface consumed by the ask UI. */
+export type QuestionObserver = {
+  identify: (ctx: ExtensionContext) => void;
+  identity: () => ObserverIdentity;
+  watch: (getState: () => Waiting | undefined) => () => void;
+  matches: (request: Record<string, unknown>, deadline: number) => boolean;
+  accept: (target: Target, requestId: string, answer: string | string[]) => void;
+};
+
+/**
+ * Track the owning extension instance on the cooperative answer bus.
+ * Runtime-local receipts attest application only. They are not a durable answer queue.
+ */
+class RuntimeObserver implements QuestionObserver {
+  private readonly pi: ExtensionAPI;
+  private readonly ownerGeneration = randomUUID();
+  private readonly protocolVersion = 1;
+  private readonly accepted = new Map<string, Receipt>();
+  private readonly unsubscribeQuery: () => void;
+  private readonly unsubscribeLookup: () => void;
+  private nativeRoot: string | undefined;
+  private mode: ExtensionContext["mode"] | undefined;
+  private current: (() => Waiting | undefined) | undefined;
+
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi;
+    this.unsubscribeQuery = pi.events.on("pi-ask-question:query", (data) => {
+      if (!isRecord(data)) {
+        return;
+      }
+      this.emitSnapshot(data);
+    });
+    this.unsubscribeLookup = pi.events.on("pi-ask-question:lookup", (data) => {
+      if (!isRecord(data)) {
+        return;
+      }
+      this.emitLookupResult(data);
+    });
+    pi.on("session_start", (_event, ctx) => {
+      this.identify(ctx);
+    });
+    pi.on("session_shutdown", () => {
+      this.current = undefined;
+      this.accepted.clear();
+      this.unsubscribeQuery();
+      this.unsubscribeLookup();
+    });
+  }
+
+  identify(ctx: ExtensionContext): void {
+    this.nativeRoot = ctx.sessionManager.getSessionId();
+    this.mode = ctx.mode;
+  }
 
-// Runtime-local receipts attest application only. They are not a durable answer queue.
-export function createQuestionObserver(pi: ExtensionAPI) {
-  const ownerGeneration = randomUUID();
-  const protocolVersion = 1;
-  const accepted = new Map<string, Target & { requestId: string; answerFingerprint: string }>();
-  let nativeRoot: string | undefined;
-  let mode: ExtensionContext["mode"] | undefined;
-  let current: (() => Waiting | undefined) | undefined;
-
-  const identity = () => ({ protocolVersion, ownerGeneration, nativeRoot });
-  const identify = (ctx: ExtensionContext) => {
-    nativeRoot = ctx.sessionManager.getSessionId();
-    mode = ctx.mode;
-  };
-  const unsubscribeQuery = pi.events.on("pi-ask-question:query", (data) => {
-    const query = record(data);
-    if (!query || !validId(query.queryId)) return;
+  identity(): ObserverIdentity {
+    return {
+      protocolVersion: this.protocolVersion,
+      ownerGeneration: this.ownerGeneration,
+      nativeRoot: this.nativeRoot,
+    };
+  }
+
+  watch(getState: () => Waiting | undefined): () => void {
+    this.current = getState;
+    return () => {
+      if (this.current === getState) {
+        this.current = undefined;
+      }
+    };
+  }
+
+  matches(request: Record<string, unknown>, deadline: number): boolean {
+    // Existing unversioned clients keep their original prompt/revision contract.
+    return (
+      request.protocolVersion === undefined ||
+      (request.protocolVersion === this.protocolVersion &&
+        request.ownerGeneration === this.ownerGeneration &&
+        request.nativeRoot === this.nativeRoot &&
+        request.deadline === deadline)
+    );
+  }
+
+  accept(target: Target, requestId: string, answer: string | string[]): void {
+    const fingerprint = createHash("sha256")
+      .update(
+        JSON.stringify([
+          this.protocolVersion,
+          this.ownerGeneration,
+          this.nativeRoot,
+          target.promptId,
+          target.questionId,
+          target.revision,
+          target.deadline,
+          answer,
+        ]),
+      )
+      .digest("hex");
+    this.accepted.set(JSON.stringify([target.promptId, requestId]), {
+      ...target,
+      requestId,
+      answerFingerprint: fingerprint,
+    });
+    if (this.accepted.size > 1024) {
+      const oldest = this.accepted.keys().next().value;
+      if (oldest !== undefined) {
+        this.accepted.delete(oldest);
+      }
+    }
+  }
+
+  private emitSnapshot(query: Record<string, unknown>): void {
+    if (!validId(query.queryId)) {
+      return;
+    }
     const waiting =
-      query.protocolVersion === protocolVersion && mode === "tui" ? current?.() : undefined;
-    pi.events.emit("pi-ask-question:snapshot", {
+      query.protocolVersion === this.protocolVersion && this.mode === "tui"
+        ? this.current?.()
+        : undefined;
+    this.pi.events.emit("pi-ask-question:snapshot", {
       queryId: query.queryId,
-      ...identity(),
-      mode,
-      status: query.protocolVersion !== protocolVersion || mode !== "tui" ? "unsupported" : "idle",
+      ...this.identity(),
+      mode: this.mode,
+      status: this.snapshotStatus(query),
       ...waiting,
     });
-  });
-  const unsubscribeLookup = pi.events.on("pi-ask-question:lookup", (data) => {
-    const query = record(data);
+  }
+
+  private snapshotStatus(query: Record<string, unknown>): "unsupported" | "idle" {
+    if (query.protocolVersion !== this.protocolVersion || this.mode !== "tui") {
+      return "unsupported";
+    }
+    return "idle";
+  }
+
+  private emitLookupResult(query: Record<string, unknown>): void {
     if (
-      !query ||
       !validId(query.queryId) ||
       !validId(query.requestId) ||
       typeof query.promptId !== "string"
-    )
+    ) {
       return;
-    const status =
-      query.protocolVersion !== protocolVersion || mode !== "tui"
-        ? "unsupported"
-        : query.ownerGeneration !== ownerGeneration || query.nativeRoot !== nativeRoot
-          ? "stale"
-          : undefined;
-    const receipt = status
-      ? undefined
-      : accepted.get(JSON.stringify([query.promptId, query.requestId]));
-    pi.events.emit("pi-ask-question:lookup-result", {
+    }
+    const status = lookupStatus(query, this.owner());
+    const receipt =
+      status === undefined
+        ? this.accepted.get(JSON.stringify([query.promptId, query.requestId]))
+        : undefined;
+    this.pi.events.emit("pi-ask-question:lookup-result", {
       queryId: query.queryId,
-      ...identity(),
+      ...this.identity(),
       promptId: query.promptId,
       requestId: query.requestId,
-      status: status ?? (receipt ? "answered" : "unknown"),
+      status: status ?? (receipt !== undefined ? "answered" : "unknown"),
       ...receipt,
     });
-  });
-  pi.on("session_start", (_event, ctx) => {
-    identify(ctx);
-  });
-  pi.on("session_shutdown", () => {
-    current = undefined;
-    accepted.clear();
-    unsubscribeQuery();
-    unsubscribeLookup();
-  });
-
-  return {
-    identify,
-    identity,
-    watch(getState: () => Waiting | undefined) {
-      current = getState;
-      return () => {
-        if (current === getState) current = undefined;
-      };
-    },
-    matches(request: Record<string, unknown>, deadline: number) {
-      // Existing unversioned clients keep their original prompt/revision contract.
-      return (
-        request.protocolVersion === undefined ||
-        (request.protocolVersion === protocolVersion &&
-          request.ownerGeneration === ownerGeneration &&
-          request.nativeRoot === nativeRoot &&
-          request.deadline === deadline)
-      );
-    },
-    accept(target: Target, requestId: string, answer: string | string[]) {
-      const answerFingerprint = createHash("sha256")
-        .update(
-          JSON.stringify([
-            protocolVersion,
-            ownerGeneration,
-            nativeRoot,
-            target.promptId,
-            target.questionId,
-            target.revision,
-            target.deadline,
-            answer,
-          ]),
-        )
-        .digest("hex");
-      accepted.set(JSON.stringify([target.promptId, requestId]), {
-        ...target,
-        requestId,
-        answerFingerprint,
-      });
-      if (accepted.size > 1024) accepted.delete(accepted.keys().next().value!);
-    },
-  };
+  }
+
+  private owner(): ObserverIdentity & { mode: ExtensionContext["mode"] | undefined } {
+    return { ...this.identity(), mode: this.mode };
+  }
 }
 
-export type QuestionObserver = ReturnType<typeof createQuestionObserver>;
+export function createQuestionObserver(pi: ExtensionAPI): QuestionObserver {
+  return new RuntimeObserver(pi);
+}
+
+function lookupStatus(
+  query: Record<string, unknown>,
+  owner: ObserverIdentity & { mode: ExtensionContext["mode"] | undefined },
+): "unsupported" | "stale" | undefined {
+  if (query.protocolVersion !== owner.protocolVersion || owner.mode !== "tui") {
+    return "unsupported";
+  }
+  if (query.ownerGeneration !== owner.ownerGeneration || query.nativeRoot !== owner.nativeRoot) {
+    return "stale";
+  }
+  return undefined;
+}

package/extensions/lib/remote-answers.ts

@@ -0,0 +1,73 @@
+/** Cooperative answer-bus protocol: request shapes and validation. */
+
+import { clean } from "./normalize.ts";
+import { MAX_REMOTE_ANSWER_LENGTH, type NormalizedQuestion } from "./types.ts";
+import { isRecord, isStringArray, validId } from "./validate.ts";
+
+/** A shape-checked request from the cooperative answer bus. */
+export type RemoteAnswerRequest = {
+  requestId: string;
+  [key: string]: unknown;
+};
+
+/** The published waiting state for one prompt on the cooperative bus. */
+export type WaitingPromptState = {
+  status: "waiting";
+  protocolVersion: number;
+  ownerGeneration: string;
+  nativeRoot: string | undefined;
+  promptId: string;
+  questionId: string;
+  revision: number;
+  deadline: number;
+  timeoutActive: boolean;
+  question: string;
+  options: string[];
+  multiSelect: boolean;
+};
+
+/** A validated remote answer, discriminated by kind. */
+export type ValidatedRemoteAnswer =
+  | { kind: "text"; text: string }
+  | { kind: "options"; options: string[] };
+
+/** Shape-check one cooperative-bus answer event. */
+export function parseRemoteAnswerRequest(data: unknown): RemoteAnswerRequest | undefined {
+  if (!isRecord(data)) {
+    return undefined;
+  }
+  const requestId = data.requestId;
+  if (!validId(requestId)) {
+    return undefined;
+  }
+  return { ...data, requestId };
+}
+
+/** Validate an answer payload against the question contract. */
+export function validateRemoteAnswer(
+  answer: unknown,
+  question: NormalizedQuestion,
+): ValidatedRemoteAnswer | undefined {
+  if (typeof answer === "string") {
+    const valid = answer.length <= MAX_REMOTE_ANSWER_LENGTH && clean(answer) !== undefined;
+    return valid ? { kind: "text", text: answer } : undefined;
+  }
+  if (!isStringArray(answer)) {
+    return undefined;
+  }
+  if (!question.multiSelect || !validMultiSelectOptions(answer, question)) {
+    return undefined;
+  }
+  return { kind: "options", options: answer };
+}
+
+/** Multi-select answers must be unique, known, and within size limits. */
+function validMultiSelectOptions(answer: string[], question: NormalizedQuestion): boolean {
+  const unique = new Set(answer).size === answer.length;
+  const known = answer.every((value) => question.options.includes(value));
+  const sized =
+    answer.length > 0 &&
+    answer.length <= question.options.length &&
+    answer.reduce((size, value) => size + value.length, 0) <= MAX_REMOTE_ANSWER_LENGTH;
+  return unique && known && sized;
+}

package/extensions/lib/schema.ts

@@ -0,0 +1,49 @@
+/** Tool parameter schemas for ask_question. */
+
+import { Type } from "typebox";
+
+const QuestionSchema = Type.Object(
+  {
+    id: Type.Optional(
+      Type.String({
+        description: "Stable answer id. Defaults to question_<n>; duplicates are auto-suffixed.",
+      }),
+    ),
+    question: Type.String({ minLength: 1, description: "Question to ask the user." }),
+    options: Type.Optional(
+      Type.Array(Type.String({ minLength: 1 }), {
+        description: "Choices, ordered from most recommended to least recommended.",
+      }),
+    ),
+    multiSelect: Type.Optional(
+      Type.Boolean({
+        description: "Allow selecting more than one option for this question. Defaults to false.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const AskQuestionParams = Type.Object(
+  {
+    question: Type.Optional(Type.String({ minLength: 1, description: "Single question to ask." })),
+    options: Type.Optional(
+      Type.Array(Type.String({ minLength: 1 }), {
+        description: "Choices, ordered from most recommended to least recommended.",
+      }),
+    ),
+    multiSelect: Type.Optional(
+      Type.Boolean({
+        description:
+          "Allow selecting more than one option for the single question. Defaults to false.",
+      }),
+    ),
+    questions: Type.Optional(
+      Type.Array(QuestionSchema, {
+        description:
+          "Ask several questions in order. When provided, takes precedence over the single-question fields.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);

package/extensions/lib/text.ts

@@ -0,0 +1,32 @@
+/** Text rendering helpers that preserve exact answer text. */
+
+import { sliceByColumn, Text, visibleWidth, type Component } from "@earendil-works/pi-tui";
+
+/** Word wrapping drops spaces at line breaks; JSON answer text must keep them. */
+export function wrapByColumn(text: string, width: number): string[] {
+  const lines: string[] = [];
+  let rest = text;
+  while (visibleWidth(rest) > width) {
+    const wide = sliceByColumn(rest, 0, width, true);
+    const part = wide !== "" ? wide : sliceByColumn(rest, 0, width);
+    lines.push(part);
+    rest = rest.slice(part.length);
+  }
+  return [...lines, rest];
+}
+
+/** Render text without re-wrapping, so exact JSON answer text survives. */
+export function exactText(text: string): Component {
+  return {
+    render(width: number): string[] {
+      const wrapped = text
+        .split("\n")
+        .flatMap((line) => wrapByColumn(line, width))
+        .join("\n");
+      return new Text(wrapped, 0, 0).render(width);
+    },
+    invalidate() {
+      // Nothing is cached; every render recomputes from the exact text.
+    },
+  };
+}

package/extensions/lib/tool.ts

@@ -0,0 +1,150 @@
+/** The ask_question tool definition. */
+
+import {
+  defineTool,
+  type AgentToolResult,
+  type ExtensionAPI,
+  type Theme,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+import type { Static } from "typebox";
+import { askWithDialogs } from "./ask-dialogs.ts";
+import { askWithKeyboard } from "./ask-keyboard.ts";
+import { formatAnswer, normalize, summarize } from "./normalize.ts";
+import type { QuestionObserver } from "./question-observer.ts";
+import { AskQuestionParams } from "./schema.ts";
+import { exactText } from "./text.ts";
+import {
+  QUESTION_TIMEOUT_MS,
+  TIMEOUT_MESSAGE,
+  type AskQuestionDetails,
+  type QuestionTimeout,
+} from "./types.ts";
+
+function createQuestionTimeout(): {
+  timeout: QuestionTimeout;
+  signal: AbortSignal;
+  dispose: () => void;
+} {
+  const controller = new AbortController();
+  const deadline = Date.now() + QUESTION_TIMEOUT_MS;
+  const timer = setTimeout(() => controller.abort(), QUESTION_TIMEOUT_MS);
+  let active = true;
+  const timeout: QuestionTimeout = {
+    deadline,
+    get active() {
+      return active;
+    },
+    stop() {
+      if (!active) {
+        return false;
+      }
+      active = false;
+      clearTimeout(timer);
+      return true;
+    },
+  };
+  return { timeout, signal: controller.signal, dispose: () => clearTimeout(timer) };
+}
+
+function renderAskCall(args: Static<typeof AskQuestionParams>, theme: Theme): Component {
+  const questions = normalize(args);
+  const count = questions.length;
+  const labels = questions.map((question) => question.id).join(", ");
+  let text = theme.fg("toolTitle", theme.bold("ask_question "));
+  text += theme.fg("muted", `${count} question${count !== 1 ? "s" : ""}`);
+  if (labels !== "") {
+    text += theme.fg("dim", ` (${labels})`);
+  }
+  return new Text(text, 0, 0);
+}
+
+function renderAskResult(result: AgentToolResult<AskQuestionDetails>, theme: Theme): Component {
+  const details = result.details;
+  if (details.timedOut) {
+    const content = result.content[0];
+    const text = theme.fg("warning", content?.type === "text" ? content.text : TIMEOUT_MESSAGE);
+    return details.answers.some((answer) => answer.selectedOptions !== undefined)
+      ? exactText(text)
+      : new Text(text, 0, 0);
+  }
+  if (details.cancelled) {
+    return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+  }
+  const lines = details.questions.map((question) => {
+    const answer = details.answers.find((entry) => entry.id === question.id);
+    return `${theme.fg("success", "✓ ")}${theme.fg("accent", question.id)}: ${formatAnswer(answer)}`;
+  });
+  const text = lines.join("\n");
+  return details.answers.some((answer) => answer.selectedOptions !== undefined)
+    ? exactText(text)
+    : new Text(text, 0, 0);
+}
+
+/** Build the registered ask_question tool bound to one observer. */
+export function createAskQuestionTool(
+  pi: ExtensionAPI,
+  observer: QuestionObserver,
+): ToolDefinition<typeof AskQuestionParams, AskQuestionDetails> {
+  return defineTool<typeof AskQuestionParams, AskQuestionDetails>({
+    name: "ask_question",
+    label: "Ask Question",
+    description:
+      "Ask the user one or more clarifying questions through pi's UI. After 5 minutes without interaction, returns an AFK reply so you can continue using your best judgement.",
+    promptSnippet: "Ask the user clarifying questions through pi's UI",
+    promptGuidelines: [
+      "For ask_question, list options from most recommended to least; the first option is the recommended choice, and do not label it as recommended.",
+      "For ask_question, set multiSelect:true only when the user may need to choose more than one option.",
+      "For ask_question, a typed custom-answer option is added automatically; do not include your own.",
+    ],
+    parameters: AskQuestionParams,
+    executionMode: "sequential",
+
+    // oxlint-disable-next-line eslint/max-params -- QX-001: defineTool's execute callback signature is fixed by the Pi SDK at five parameters.
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const questions = normalize(params);
+      if (questions.length === 0) {
+        throw new Error("ask_question needs either question or questions[].");
+      }
+      if (!ctx.hasUI) {
+        throw new Error("ask_question needs Pi TUI or RPC UI support.");
+      }
+
+      observer.identify(ctx);
+      const { timeout, signal: timeoutSignal, dispose } = createQuestionTimeout();
+      const questionSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+      try {
+        const result =
+          ctx.mode === "tui"
+            ? await askWithKeyboard({
+                questions,
+                ui: ctx.ui,
+                pi,
+                observer,
+                timeout,
+                signal: questionSignal,
+              })
+            : await askWithDialogs(questions, ctx.ui, timeout, questionSignal);
+        const answers = new Map(result.answers.map((answer) => [answer.id, answer]));
+        const timedOut = result.cancelled && timeoutSignal.aborted && signal?.aborted !== true;
+        const cancelled = result.cancelled && !timedOut;
+
+        return {
+          content: [{ type: "text", text: summarize(questions, answers, cancelled, timedOut) }],
+          details: {
+            questions,
+            answers: result.answers,
+            cancelled,
+            timedOut,
+          },
+        };
+      } finally {
+        dispose();
+      }
+    },
+
+    renderCall: (args, theme, _context) => renderAskCall(args, theme),
+    renderResult: (result, _options, theme, _context) => renderAskResult(result, theme),
+  });
+}

package/extensions/lib/types.ts

@@ -0,0 +1,56 @@
+/** Shared domain types and constants for the ask_question extension. */
+
+/** A single question as received through the tool schema. */
+export type Question = {
+  id?: string;
+  question: string;
+  options?: string[];
+  multiSelect?: boolean;
+};
+
+/** A question after normalization: identified, cleaned, and complete. */
+export type NormalizedQuestion = {
+  id: string;
+  question: string;
+  options: string[];
+  multiSelect: boolean;
+};
+
+/** A user answer for one question. */
+export type Answer = {
+  id: string;
+  question: string;
+  answer: string;
+  selectedOptions?: string[];
+  wasCustom: boolean;
+};
+
+/** Structured details attached to a finished ask_question tool result. */
+export type AskQuestionDetails = {
+  questions: NormalizedQuestion[];
+  answers: Answer[];
+  cancelled: boolean;
+  timedOut: boolean;
+};
+
+/** Outcome of asking one question set through any UI mode. */
+export type QuestionResult = {
+  answers: Answer[];
+  cancelled: boolean;
+};
+
+/** Cooperative five-minute inactivity timeout for one question set. */
+export type QuestionTimeout = {
+  deadline: number;
+  readonly active: boolean;
+  stop: () => boolean;
+};
+
+export const QUESTION_TIMEOUT_MS = 5 * 60 * 1000;
+export const TIMEOUT_MESSAGE =
+  "Mitch is currently AFK. Use your best judgement to choose the option Mitch would choose.";
+export const CUSTOM_OPTION = "Type a custom answer";
+export const DONE_OPTION = "Done selecting";
+export const MAX_REMOTE_ANSWER_LENGTH = 16_384;
+// ponytail: bound deduplication to 1024 commits per prompt; raise with a higher-volume client.
+export const MAX_REMOTE_REQUESTS = 1024;