@pify/ask-question 0.1.0 → 0.3.0

package/README.md

@@ -9,7 +9,9 @@ Part of the [Pify suite](https://github.com/pifydev). Install with [`pify instal
 - **`ask_question`** — the agent batches up to 4 questions, each with up to 4 options (`label` + `description` trade-offs, recommendation marked "(Recommended)" and listed first), optional `multiSelect`, and free-text via "Other…".
 - **Built entirely on pi's built-in dialogs** (`select`/`input`) — no custom TUI overlay, so it works identically in the terminal and RPC/GUI hosts and can't break with pi UI changes. Multi-select is a checkbox toggle loop with `✓ Done`.
 - **Discipline encoded in the tool description** (zhushanwen's three conditions): only when 2+ reasonable approaches exist, context is already gathered, and a wrong pick means rework. Never for permissions or things the agent can look up.
-- **Declining is an answer**: Esc cleanly reports "the user declined" for the rest of the batch — no error, no re-asking. Headless runs get "proceed with your best judgment and state the assumption" instead of a failure (asking is advisory, unlike the fail-closed safety gates).
+- **Declining is an answer**: Esc cleanly reports "the user declined" for the rest of the batch — no error, no re-asking. Headless runs get the full questionnaire back — every question with its options — plus "proceed with your best judgment and say which option you assumed", so the decision stays in the CI transcript instead of vanishing (asking is advisory, unlike the fail-closed safety gates).
+- **The decisions stay on the record** (v0.3): every questionnaire is appended to the session as its own entry, and `/ask` prints the last one (`/ask all` for the whole history) with what you chose or declined. Forks and `/reload` keep their own history, because the entries live on the branch.
+- **Rows the user can actually pick** (v0.2): two options sharing a label, or one labelled `Other…`, used to render as indistinguishable rows where the second was unselectable. Duplicates are now suffixed, reserved labels renamed, and every pick resolves by its position in the dialog rather than by its text.
 - Structured results return to the model as both readable text and `details.answers`.
 
 ## Why no fancy overlay?

package/extensions/ask-question.ts

@@ -20,12 +20,17 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 
 import {
+  ASK_STATE,
   DONE_LABEL,
   OTHER_LABEL,
   formatAnswers,
-  labelFromDisplay,
-  optionDisplay,
+  headlessText,
+  parseAskRoute,
+  parseSingleRow,
   parseToggleRow,
+  replayRounds,
+  routeText,
+  singleRows,
   toggleRows,
   validateQuestions,
   type AskAnswer,
@@ -36,30 +41,29 @@ type UiContext = ExtensionContext;
 
 export default function askQuestion(pi: ExtensionAPI) {
   async function askSingle(ctx: UiContext, q: AskQuestion): Promise<AskAnswer> {
-    const rows = [...q.options.map(optionDisplay), ...(q.allowOther ? [OTHER_LABEL] : [])];
+    const rows = singleRows(q.options, q.allowOther);
     const picked = await ctx.ui.select(q.question, rows);
     if (picked === undefined) return { question: q.question, answers: [], declined: true };
-    if (picked === OTHER_LABEL) {
+    const action = parseSingleRow(picked, rows, q.options);
+    if (!action) return { question: q.question, answers: [], declined: true };
+    if (action.kind === "other") {
       const text = await ctx.ui.input(q.question, "Type your answer");
       if (text === undefined || !text.trim()) {
         return { question: q.question, answers: [], declined: true };
       }
       return { question: q.question, answers: [], other: text.trim() };
     }
-    const label = labelFromDisplay(picked, q.options);
-    return { question: q.question, answers: label ? [label] : [] };
+    return { question: q.question, answers: [q.options[action.index]!.label] };
   }
 
   async function askMulti(ctx: UiContext, q: AskQuestion): Promise<AskAnswer> {
     const selected = new Set<number>();
     let other: string | undefined;
     for (;;) {
-      const picked = await ctx.ui.select(
-        `${q.question}\n(toggle options, then ${DONE_LABEL})`,
-        toggleRows(q.options, selected, q.allowOther),
-      );
+      const rows = toggleRows(q.options, selected, q.allowOther);
+      const picked = await ctx.ui.select(`${q.question}\n(toggle options, then ${DONE_LABEL})`, rows);
       if (picked === undefined) return { question: q.question, answers: [], declined: true };
-      const action = parseToggleRow(picked, q.options);
+      const action = parseToggleRow(picked, rows, q.options);
       if (!action) continue;
       if (action.kind === "done") break;
       if (action.kind === "other") {
@@ -114,13 +118,8 @@ export default function askQuestion(pi: ExtensionAPI) {
 
       if (!uiCtx.hasUI) {
         return {
-          content: [
-            {
-              type: "text",
-              text: "No UI is available to ask the user. Proceed with your best judgment and clearly state the assumption you made.",
-            },
-          ],
-          details: { headless: true },
+          content: [{ type: "text", text: headlessText(result.questions) }],
+          details: { headless: true, questions: result.questions },
         };
       }
 
@@ -137,6 +136,10 @@ export default function askQuestion(pi: ExtensionAPI) {
         }
       }
 
+      // Record the round so /ask can show it later, and a fork keeps its own
+      // history; appended per round, never overwritten.
+      pi.appendEntry(ASK_STATE, { timestamp: Date.now(), answers });
+
       const text = [
         formatAnswers(answers),
         ...(result.warnings.length > 0 ? [`Warnings: ${result.warnings.join("; ")}`] : []),
@@ -144,4 +147,13 @@ export default function askQuestion(pi: ExtensionAPI) {
       return { content: [{ type: "text", text }], details: { answers } };
     },
   });
+
+  pi.registerCommand("ask", {
+    description: "Show what the agent asked you and how you answered: /ask [last | all]",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) return;
+      const rounds = replayRounds(ctx.sessionManager.getBranch() as never);
+      ctx.ui.notify(routeText(parseAskRoute(args ?? ""), rounds), "info");
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/ask-question",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Let the model ask instead of guessing: CC AskUserQuestion-shaped tool on built-in dialogs - 1-4 questions, multi-select, Other free-text, works in TUI and RPC",
   "keywords": [
     "pi-package",

package/src/ask.ts

@@ -75,9 +75,11 @@ export function validateQuestions(raw: unknown): ValidationResult {
       warnings.push(`question "${entry.question.slice(0, 30)}" has no options and allowOther=false — dropped`);
       continue;
     }
+    const normalized = normalizeOptions(options);
+    warnings.push(...normalized.warnings);
     questions.push({
       question: entry.question.trim(),
-      options,
+      options: normalized.options,
       multiSelect: entry.multiSelect === true,
       allowOther,
     });
@@ -89,6 +91,34 @@ export function validateQuestions(raw: unknown): ValidationResult {
   return { questions, warnings, error: null };
 }
 
+/**
+ * Make every option in a question distinguishable in the dialog. Two options
+ * sharing a label render as identical rows (the second is then unselectable),
+ * and an option labelled like a control row steals that row's meaning — both
+ * are the model's doing, so they are repaired rather than rejected.
+ */
+export function normalizeOptions(options: AskOption[]): { options: AskOption[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const seen = new Map<string, number>();
+  const result: AskOption[] = [];
+  for (const option of options) {
+    let label = option.label;
+    if (label === OTHER_LABEL || label === DONE_LABEL) {
+      label = `${label} (option)`;
+      warnings.push(`renamed an option labelled "${option.label}" — that label is reserved`);
+    }
+    const count = seen.get(label) ?? 0;
+    seen.set(label, count + 1);
+    if (count > 0) {
+      const unique = `${label} (${count + 1})`;
+      warnings.push(`renamed a duplicate option label "${label}"`);
+      label = unique;
+    }
+    result.push({ ...option, label });
+  }
+  return { options: result, warnings };
+}
+
 /** Display string for one option in the select dialog. */
 export function optionDisplay(option: AskOption): string {
   const desc = option.description
@@ -97,10 +127,24 @@ export function optionDisplay(option: AskOption): string {
   return `${option.label}${desc}`;
 }
 
-/** Map a picked display string back to its option label. */
-export function labelFromDisplay(display: string, options: AskOption[]): string | null {
-  const found = options.find((o) => optionDisplay(o) === display);
-  return found ? found.label : null;
+/** Rows for a single-select question: the options, then Other… if allowed. */
+export function singleRows(options: AskOption[], allowOther: boolean): string[] {
+  const rows = options.map(optionDisplay);
+  if (allowOther) rows.push(OTHER_LABEL);
+  return rows;
+}
+
+export type SingleAction = { kind: "option"; index: number } | { kind: "other" };
+
+/**
+ * Resolve a pick by its position in the rows that were shown. Matching on the
+ * display string instead would confuse an option with the control row that
+ * happens to read the same.
+ */
+export function parseSingleRow(picked: string, rows: string[], options: AskOption[]): SingleAction | null {
+  const index = rows.indexOf(picked);
+  if (index < 0) return null;
+  return index < options.length ? { kind: "option", index } : { kind: "other" };
 }
 
 /** Rows for one round of the multi-select toggle loop. */
@@ -113,12 +157,105 @@ export function toggleRows(options: AskOption[], selected: ReadonlySet<number>,
 
 export type ToggleAction = { kind: "toggle"; index: number } | { kind: "done" } | { kind: "other" };
 
-export function parseToggleRow(row: string, options: AskOption[]): ToggleAction | null {
-  if (row === DONE_LABEL) return { kind: "done" };
-  if (row === OTHER_LABEL) return { kind: "other" };
-  const body = row.replace(/^\[[x ]\] /, "");
-  const index = options.findIndex((o) => optionDisplay(o) === body);
-  return index >= 0 ? { kind: "toggle", index } : null;
+export function parseToggleRow(row: string, rows: string[], options: AskOption[]): ToggleAction | null {
+  const index = rows.indexOf(row);
+  if (index < 0) return null;
+  if (index < options.length) return { kind: "toggle", index };
+  return index === options.length ? { kind: "done" } : { kind: "other" };
+}
+
+/**
+ * What the model gets back when there is nobody to ask (RPC, CI, headless).
+ * Replaying the questions and options keeps the decision in the transcript,
+ * so the assumption it states can be checked against what it offered.
+ */
+export function headlessText(questions: AskQuestion[]): string {
+  const blocks = questions.map((q) => {
+    const options = q.options.map((o) => `  - ${optionDisplay(o)}`);
+    if (q.allowOther) options.push("  - (free text)");
+    return [`Q: ${q.question}`, ...options].join("\n");
+  });
+  return [
+    "No UI is available to ask the user. These are the questions you would have asked:",
+    "",
+    blocks.join("\n\n"),
+    "",
+    "Proceed with your best judgment, and say plainly which option you assumed and why.",
+  ].join("\n");
+}
+
+export const ASK_STATE = "ask-question-round";
+
+export interface AskRound {
+  timestamp: number;
+  answers: AskAnswer[];
+}
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Every questionnaire is appended as its own entry (not a last-wins
+ * snapshot): the point of the record is the sequence of decisions, and an
+ * earlier answer stays true after a later one is given.
+ */
+export function replayRounds(entries: BranchEntryLike[]): AskRound[] {
+  const rounds: AskRound[] = [];
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== ASK_STATE) continue;
+    const data = entry.data;
+    if (!isRecord(data) || !Array.isArray(data.answers)) continue;
+    rounds.push({
+      timestamp: typeof data.timestamp === "number" ? data.timestamp : 0,
+      answers: data.answers as AskAnswer[],
+    });
+  }
+  return rounds;
+}
+
+export type AskRoute = { kind: "last" } | { kind: "all" } | { kind: "help" } | { kind: "unknown"; input: string };
+
+export const ASK_USAGE = "Usage: /ask [last | all]";
+
+export function parseAskRoute(raw: string): AskRoute {
+  const text = (raw ?? "").trim().toLowerCase();
+  if (!text || text === "last") return { kind: "last" };
+  if (text === "all" || text === "history") return { kind: "all" };
+  if (text === "help" || text === "?") return { kind: "help" };
+  return { kind: "unknown", input: text };
+}
+
+function stamp(timestamp: number): string {
+  if (!timestamp) return "";
+  const d = new Date(timestamp);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${pad(d.getHours())}:${pad(d.getMinutes())} `;
+}
+
+/** What /ask prints. */
+export function routeText(route: AskRoute, rounds: AskRound[]): string {
+  switch (route.kind) {
+    case "help":
+      return ASK_USAGE;
+    case "unknown":
+      return `Unknown route "${route.input}". ${ASK_USAGE}`;
+    case "last": {
+      const last = rounds[rounds.length - 1];
+      return last
+        ? `${stamp(last.timestamp)}last questionnaire\n${formatAnswers(last.answers)}`
+        : "No questions have been asked in this session.";
+    }
+    case "all":
+      return rounds.length === 0
+        ? "No questions have been asked in this session."
+        : rounds
+            .map((round, i) => `#${i + 1} ${stamp(round.timestamp)}\n${formatAnswers(round.answers)}`)
+            .join("\n\n");
+  }
 }
 
 /** Text block the model receives. */