@pi9/ask 0.1.0 → 0.3.0

package/README.md

@@ -5,6 +5,7 @@ Ask adds interactive questions to [Pi](https://github.com/earendil-works/pi-mono
 ## Feature overview
 
 - **Answer revisions** — Reopen an Ask entry from `/tree` and continue with a new answer.
+- **Tool-call rewriting** — Replace answered standalone Ask exchanges in model context with compact, decision-focused responses while preserving the original session history.
 - **Lean tool definition** — A highly optimized description and schema minimize prompt overhead while staying compatible across providers.
 - **Rich previews** — Inspect Markdown previews before choosing.
 - **Multi-select** — Choose any number of options, then submit them together.
@@ -61,6 +62,16 @@ Comments let you qualify a selection without writing a separate message. When a
 
 ## Advanced behavior
 
+### Tool-call rewriting
+
+Ask rewrites answered standalone exchanges before they are sent back to the model, replacing the Ask call and its answer record with a compact `ask_response` message. The replacement keeps the question, optional background, single- or multi-select mode, selected option labels and descriptions, comments, and any freeform response. It leaves out unselected options and all Markdown previews.
+
+The main purpose is to keep proposed alternatives from being mistaken for decisions. Once you choose an answer, the model sees only what you selected and the context attached to that selection—not every option it originally offered. As a secondary benefit, dropping unused answers, previews, and the surrounding tool-call protocol reduces the amount of context carried into later turns.
+
+The answer can come from either a successful native tool result or a valid revision submitted from `/tree`. A revision becomes the authoritative answer, replacing the earlier result in model context even if that result is absent or unsuccessful.
+
+This rewrite affects only the model-facing context. The original messages remain in the stored session, so the conversation still renders normally and the question can still be reopened from `/tree`. Ask rewrites only unambiguous calls and answers that validate against each other; otherwise, it leaves the messages untouched rather than risk producing a misleading response or an unmatched tool call.
+
 ### Responsive previews
 
 Previews appear beside the options in terminals at least 88 columns wide and stack below them in narrower layouts. They support Markdown and update as you move between options. While you edit a comment or freeform response, the preview is hidden to leave more room for writing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi9/ask",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Preview-rich, replayable Pi questions with multi-select and comments.",
   "license": "MIT",
   "author": "Chase Cummings <chaseecummings@gmail.com>",

package/src/component.ts

@@ -19,9 +19,9 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import {
   createQuestionnaireState,
   transitionQuestionnaire,
+  type QuestionnaireRow,
   type QuestionnaireState,
 } from "./state.js";
-import { CHECKED_BOX, EMPTY_BOX } from "./glyphs.js";
 import {
   composePreviewRow,
   getPreviewPaneLayout,
@@ -33,9 +33,11 @@ import {
   type FocusRange,
   type ViewportOverflow,
 } from "./viewport.js";
-import type { AskAnswer, ValidatedAskParams } from "./types.js";
+import type { Ask, AskAnswer } from "./domain.js";
 
-type AskComponentOptions = ValidatedAskParams & {
+const FRAME_WIDE_PREVIEW = true; // Set to false to compare the same layout without its outer frame.
+
+type AskComponentOptions = Ask & {
   tui: TUI;
   theme: Theme;
   keybindings: KeybindingsManager;
@@ -166,7 +168,14 @@ export class AskComponent implements Component, Focusable {
   }
 
   render(width: number): string[] {
-    const renderWidth = safeWidth(width);
+    const availableWidth = safeWidth(width);
+    const hasAuthoredPreviews = this.questionnaireState.rows.some(
+      row => row.kind === "option" && row.option.preview?.trim(),
+    );
+    const framed = FRAME_WIDE_PREVIEW
+      && hasAuthoredPreviews
+      && getPreviewPaneLayout(availableWidth - 4) !== undefined;
+    const renderWidth = framed ? availableWidth - 4 : availableWidth;
     const lines: string[] = [];
     const add = (line: string) => lines.push(fit(line, renderWidth));
     const addPrefixed = (prefix: string, text: string, color?: "text" | "muted" | "dim" | "accent") => {
@@ -176,11 +185,8 @@ export class AskComponent implements Component, Focusable {
 
     add(this.config.theme.fg("border", "─".repeat(renderWidth)));
 
-    if (this.config.context) {
-      addPrefixed(" ", this.config.context, "muted");
-      add("");
-    }
     addPrefixed(" ", this.config.theme.bold(this.config.question), "text");
+    if (this.config.context) addPrefixed(" ", this.config.context, "muted");
     add("");
 
     let focus: FocusRange | undefined;
@@ -198,16 +204,18 @@ export class AskComponent implements Component, Focusable {
     };
     if (this.questionnaireState.editor.kind === "select") {
       const preview = this.highlightedPreview();
-      const hasPreviews = this.questionnaireState.rows.some(
-        row => row.kind === "option" && row.option.preview?.trim(),
-      );
-      const paneLayout = hasPreviews ? getPreviewPaneLayout(renderWidth) : undefined;
+      const paneLayout = hasAuthoredPreviews ? getPreviewPaneLayout(renderWidth) : undefined;
       if (paneLayout) {
-        const optionLines: string[] = [];
+        const optionLines = [this.config.theme.fg("dim", " OPTIONS"), ""];
         const optionFocus = this.renderOptions(optionLines, paneLayout.leftWidth);
         const submitFocus = this.renderSubmit(optionLines, paneLayout.leftWidth);
         const sectionStart = lines.length;
-        const previewLines = this.renderPreview(preview, paneLayout.rightWidth);
+        const previewLines = [
+          this.config.theme.fg("dim", " PREVIEW · FOCUSED OPTION"),
+          this.config.theme.fg("dim", "─".repeat(paneLayout.rightWidth)),
+          "",
+          ...this.renderPreview(preview, paneLayout.rightWidth - 1).map(line => ` ${line}`),
+        ];
         const bodyHeight = Math.max(optionLines.length, previewLines.length);
         lines.push(...optionLines, ...Array.from({ length: bodyHeight - optionLines.length }, () => ""));
         wideBody = {
@@ -226,7 +234,7 @@ export class AskComponent implements Component, Focusable {
       } else {
         const optionFocus = this.renderOptions(lines, renderWidth);
         focus = optionFocus;
-        if (hasPreviews) {
+        if (hasAuthoredPreviews) {
           const previewStart = lines.length;
           const previewLines = this.renderPreview(preview, renderWidth);
           lines.push(...previewLines);
@@ -247,28 +255,57 @@ export class AskComponent implements Component, Focusable {
       footerStart = lines.length;
       addFooter(" ", this.config.theme.fg("dim", this.helpText()));
     } else {
+      const activeEditor = this.questionnaireState.editor;
       // Keep the options visible while editing so the comment remains tied to
       // the option it belongs to, and so freeform editing does not feel like a
       // separate prompt.
-      this.renderOptions(lines, renderWidth);
+      const paneLayout = hasAuthoredPreviews ? getPreviewPaneLayout(renderWidth) : undefined;
+      const optionLines = paneLayout
+        ? [this.config.theme.fg("dim", " OPTIONS"), ""]
+        : lines;
+      const optionWidth = paneLayout?.leftWidth ?? renderWidth;
       const inputPrefix = `    ${this.config.theme.fg("accent", "↳")} `;
       const continuationPrefix = " ".repeat(visibleWidth(inputPrefix));
-      const inputWidth = Math.max(1, renderWidth - visibleWidth(inputPrefix));
+      const inputWidth = Math.max(1, optionWidth - visibleWidth(inputPrefix));
       const editorLines = this.editor.render(inputWidth).filter(line => visibleWidth(line) > 0);
-      const editorStart = lines.length;
-      for (const [index, line] of editorLines.entries()) {
-        add(`${index === 0 ? inputPrefix : continuationPrefix}${line}`);
-      }
-      const editorEnd = lines.length;
+      let editorStart = -1;
+      let editorEnd = -1;
+      this.renderOptions(optionLines, optionWidth, (row) => {
+        if (row !== activeEditor.target) return;
+        editorStart = optionLines.length;
+        for (const [index, line] of editorLines.entries()) {
+          optionLines.push(fit(`${index === 0 ? inputPrefix : continuationPrefix}${line}`, optionWidth));
+        }
+        editorEnd = optionLines.length;
+      });
       if (editorEnd > editorStart) {
         const cursorLine = editorLines.findIndex(line => line.includes(CURSOR_MARKER));
         const focusedRow = cursorLine >= 0 ? editorStart + cursorLine : editorEnd - 1;
         focus = { start: focusedRow, end: focusedRow + 1 };
       }
 
+      this.renderSubmit(optionLines, optionWidth);
+      if (paneLayout) {
+        const sectionStart = lines.length;
+        const previewLines = [
+          this.config.theme.fg("dim", " PREVIEW · FOCUSED OPTION"),
+          this.config.theme.fg("dim", "─".repeat(paneLayout.rightWidth)),
+          "",
+          ...this.renderPreview(undefined, paneLayout.rightWidth - 1).map(line => ` ${line}`),
+        ];
+        const bodyHeight = Math.max(optionLines.length, previewLines.length);
+        lines.push(...optionLines, ...Array.from({ length: bodyHeight - optionLines.length }, () => ""));
+        wideBody = {
+          start: sectionStart,
+          end: sectionStart + bodyHeight,
+          previewLines,
+          layout: paneLayout,
+        };
+        if (focus) focus = { start: sectionStart + focus.start, end: sectionStart + focus.end };
+      }
+
       // The help line is the footer. Keep it adjacent to the bottom border so
       // fitViewport can keep both rows fixed while the editor is focused.
-      this.renderSubmit(lines, renderWidth);
       footerStart = lines.length;
       addFooter(continuationPrefix, this.config.theme.fg("dim", this.editorHelpText()));
     }
@@ -287,7 +324,7 @@ export class AskComponent implements Component, Focusable {
     const visibleRows = fitViewport(rows, focus, maxRows, 1, lines.length - footerStart);
     let previewIndex = 0;
 
-    return visibleRows.map(({ value: row, overflow }) => {
+    const projected = visibleRows.map(({ value: row, overflow }) => {
       if (row.kind === "full") {
         return projectFullRow(row.line, overflow, renderWidth);
       }
@@ -301,6 +338,7 @@ export class AskComponent implements Component, Focusable {
         this.config.theme.fg("dim", "│"),
       );
     });
+    return framed ? frameDialog(projected, availableWidth, this.config.theme) : projected;
   }
 
   /** Submit the current multi-select answer programmatically. */
@@ -320,7 +358,11 @@ export class AskComponent implements Component, Focusable {
     this.config.onCancel?.();
   }
 
-  private renderOptions(lines: string[], width: number): FocusRange | undefined {
+  private renderOptions(
+    lines: string[],
+    width: number,
+    afterRow?: (row: QuestionnaireRow) => void,
+  ): FocusRange | undefined {
     const addPrefixed = (prefix: string, text: string, color?: "text" | "muted" | "dim" | "accent") => {
       const styled = color ? this.config.theme.fg(color, text) : text;
       addWrappedWithPrefix(lines, prefix, styled, width);
@@ -331,34 +373,34 @@ export class AskComponent implements Component, Focusable {
       if (row.kind === "submit") continue;
       const selected = this.questionnaireState.highlightedRow === index;
       const start = lines.length;
-      const marker = selected ? this.config.theme.fg("accent", "› ") : "  ";
+      const marker = selected ? this.config.theme.fg("accent", "┃ ") : "  ";
 
       if (row.kind === "option") {
         const source = row.option;
-        const checked = this.questionnaireState.checked.has(source.label);
-        const check = this.questionnaireState.config.allowMultiple
-          ? `${this.config.theme.fg(checked ? "success" : "muted", checked ? CHECKED_BOX : EMPTY_BOX)} `
+        const checked = this.questionnaireState.checked.has(row.index);
+        const badge = this.questionnaireState.config.allowMultiple && checked
+          ? this.config.theme.fg("success", " [selected]")
           : "";
-        const comment = this.questionnaireState.comments.has(source.label)
+        const comment = this.questionnaireState.comments.has(row.index)
           ? this.config.theme.fg("warning", " ✎")
           : "";
-        addPrefixed("", `${marker}${check}${source.label}${comment}`, selected ? "accent" : "text");
-        if (source.description) addPrefixed("     ", source.description, "muted");
+        addPrefixed(marker, `${source.label}${badge}${comment}`, selected ? "accent" : "text");
+        if (source.description) addPrefixed("  ", source.description, "muted");
         if (selected) {
-          const commentText = this.questionnaireState.comments.get(source.label);
+          const commentText = this.questionnaireState.comments.get(row.index);
           if (commentText) addPrefixed("     ", `✎ ${commentText}`, "dim");
         }
       } else {
-        const checked = this.questionnaireState.freeformChecked;
-        const check = this.questionnaireState.config.allowMultiple
-          ? `${this.config.theme.fg(checked ? "success" : "muted", checked ? CHECKED_BOX : EMPTY_BOX)} `
+        const badge = this.questionnaireState.config.allowMultiple && this.questionnaireState.freeformChecked
+          ? this.config.theme.fg("success", " [selected]")
           : "";
         const suffix = this.questionnaireState.freeformDraft
           ? ` — ${this.questionnaireState.freeformDraft}`
           : "";
-        addPrefixed("", `${marker}${check}${this.config.theme.fg(selected ? "accent" : "text", `Type a response…${suffix}`)}`);
+        addPrefixed(marker, `Type a response…${suffix}${badge}`, selected ? "accent" : "text");
       }
       if (selected) focus = { start, end: lines.length };
+      afterRow?.(row);
     }
     return focus;
   }
@@ -367,7 +409,7 @@ export class AskComponent implements Component, Focusable {
     const submitIndex = this.questionnaireState.rows.findIndex(row => row.kind === "submit");
     if (submitIndex < 0) return undefined;
     const selected = this.questionnaireState.highlightedRow === submitIndex;
-    const marker = selected ? this.config.theme.fg("accent", "› ") : "  ";
+    const marker = selected ? this.config.theme.fg("accent", "┃ ") : "  ";
     lines.push("");
     const start = lines.length;
     addWrappedWithPrefix(
@@ -530,6 +572,17 @@ function overflowPrefix(overflow: ViewportOverflow | undefined): string {
   return "";
 }
 
+function frameDialog(lines: readonly string[], width: number, theme: Theme): string[] {
+  const border = (text: string) => theme.fg("border", text);
+  const innerWidth = width - 4;
+  return lines.map((line, index) => {
+    if (index === 0) return border(`╭${"─".repeat(width - 2)}╮`);
+    if (index === lines.length - 1) return border(`╰${"─".repeat(width - 2)}╯`);
+    const content = fit(line, innerWidth);
+    return `${border("│")} ${content}${" ".repeat(innerWidth - visibleWidth(content))} ${border("│")}`;
+  });
+}
+
 function safeWidth(width: number): number {
   return Math.max(1, Number.isFinite(width) ? Math.floor(width) : 1);
 }

package/src/deadline.ts

@@ -1,16 +1,41 @@
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+
+type AskEnvironment = Readonly<{
+  PI9_ASK_TIMEOUT_MS?: string;
+}>;
+
 export interface DeadlineSignal {
   signal: AbortSignal | undefined;
   readonly timedOut: boolean;
   dispose(): void;
 }
 
+export function resolveTimeoutMs(
+  perCallTimeout: number | undefined,
+  env: AskEnvironment,
+): number | undefined {
+  if (perCallTimeout !== undefined) {
+    return Number.isInteger(perCallTimeout) && perCallTimeout > 0 && perCallTimeout <= MAX_TIMEOUT_MS
+      ? perCallTimeout
+      : undefined;
+  }
+
+  const envTimeout = env.PI9_ASK_TIMEOUT_MS;
+  if (envTimeout === undefined || !/^\d+$/.test(envTimeout)) return undefined;
+
+  const timeout = Number(envTimeout);
+  return Number.isInteger(timeout) && timeout > 0 && timeout <= MAX_TIMEOUT_MS
+    ? timeout
+    : undefined;
+}
+
 export function createDeadlineSignal(
   parent: AbortSignal | undefined,
-  timeoutMs: number | undefined,
+  perCallTimeout: number | undefined,
+  env: AskEnvironment = {},
 ): DeadlineSignal {
-  const hasTimeout = timeoutMs !== undefined
-    && Number.isFinite(timeoutMs)
-    && timeoutMs > 0;
+  const timeoutMs = resolveTimeoutMs(perCallTimeout, env);
+  const hasTimeout = timeoutMs !== undefined;
 
   if (parent === undefined && !hasTimeout) {
     return {

package/src/domain.ts

@@ -0,0 +1,144 @@
+import { Type, type Static } from "typebox";
+import { Check } from "typebox/value";
+
+import { MAX_TIMEOUT_MS } from "./deadline.js";
+
+export const AskOptionSchema = Type.Object({
+  label: Type.String({ minLength: 1, description: "Short option title; keep distinct across options." }),
+  description: Type.Optional(Type.String({ description: "Brief explanation when the label alone is ambiguous." })),
+  preview: Type.Optional(Type.String({ description: "Markdown shown to the user, e.g. code, plans, or comparisons; not returned in the answer." })),
+}, { additionalProperties: false });
+
+export const AskParamsSchema = Type.Object({
+  question: Type.String({ minLength: 1 }),
+  context: Type.Optional(Type.String({ description: "Optional background shown above the question, e.g. what prompted the ask." })),
+  options: Type.Array(AskOptionSchema, { minItems: 1, description: "Suggested answers." }),
+  allowMultiple: Type.Optional(Type.Boolean({ default: false, description: "Allow selecting multiple options. Defaults to false." })),
+  allowFreeform: Type.Optional(Type.Boolean({ default: true, description: "Allow a typed response. Defaults to true." })),
+  timeout: Type.Optional(Type.Integer({ minimum: 0, maximum: MAX_TIMEOUT_MS, description: "Timeout in ms for answers that would go stale; the call returns unanswered on expiry. Zero disables any default." })),
+}, { additionalProperties: false });
+
+export const AskSelectionSchema = Type.Object({
+  option: Type.Integer({ minimum: 0 }),
+  comment: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+export const AskAnswerSchema = Type.Object({
+  selections: Type.Array(AskSelectionSchema),
+  freeform: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+export const AskReplayDetailsSchema = Type.Object({
+  toolCallId: Type.String({ minLength: 1 }),
+  answer: AskAnswerSchema,
+}, { additionalProperties: false });
+
+export const AskAnsweredDetailsSchema = Type.Object({
+  status: Type.Literal("answered"),
+  answer: AskAnswerSchema,
+}, { additionalProperties: false });
+
+export type AskOption = Static<typeof AskOptionSchema>;
+export type AskParams = Static<typeof AskParamsSchema>;
+export type AskSelection = Static<typeof AskSelectionSchema>;
+export type AskAnswer = Static<typeof AskAnswerSchema>;
+export type AskReplayDetails = Static<typeof AskReplayDetailsSchema>;
+export type AskAnsweredDetails = Static<typeof AskAnsweredDetailsSchema>;
+
+export type Ask = Omit<AskParams, "allowMultiple" | "allowFreeform"> & {
+  allowMultiple: boolean;
+  allowFreeform: boolean;
+};
+
+export type AskToolDetails =
+  | AskAnsweredDetails
+  | { status: "unanswered" | "cancelled" | "ui_unavailable" };
+
+export type AskResponse = {
+  content: Array<{ type: "text"; text: string }>;
+  details: AskToolDetails;
+};
+
+export function normalizeAsk(params: AskParams): Ask {
+  const question = params.question.trim();
+  if (!question) throw new Error("Ask question must not be empty.");
+
+  const context = trimOptional(params.context);
+  const options = params.options.map(normalizeOption);
+  if (options.length === 0) throw new Error("Ask needs at least one option.");
+
+  const labels = new Set<string>();
+  for (const option of options) {
+    if (labels.has(option.label)) throw new Error(`Ask options contain duplicate label: ${option.label}.`);
+    labels.add(option.label);
+  }
+
+  return {
+    question,
+    ...(context === undefined ? {} : { context }),
+    options,
+    allowMultiple: params.allowMultiple ?? false,
+    allowFreeform: params.allowFreeform ?? true,
+    ...(params.timeout === undefined ? {} : { timeout: params.timeout }),
+  };
+}
+
+export function parseAskReplayDetails(value: unknown): AskReplayDetails | undefined {
+  return Check(AskReplayDetailsSchema, value) ? value : undefined;
+}
+
+export function answerMatchesAsk(answer: AskAnswer, ask: Ask): boolean {
+  if (answer.selections.length > 1 && !ask.allowMultiple) return false;
+  if (answer.freeform !== undefined && !ask.allowFreeform) return false;
+
+  const selected = new Set<number>();
+  for (const selection of answer.selections) {
+    if (selection.option >= ask.options.length || selected.has(selection.option)) return false;
+    selected.add(selection.option);
+  }
+  return true;
+}
+
+export function formatAskAnswer(ask: Ask, answer: AskAnswer): string {
+  const lines = answer.selections.map((selection) => {
+    const option = ask.options[selection.option]!;
+    const description = option.description ? ` — ${option.description}` : "";
+    const comment = selection.comment ? ` (${selection.comment})` : "";
+    return `Selected: ${option.label}${description}${comment}`;
+  });
+  if (answer.freeform) lines.push(`Freeform: ${answer.freeform}`);
+  return lines.join("\n") || "No answer provided.";
+}
+
+export function buildAskResponse(ask: Ask, details: AskToolDetails): AskResponse {
+  if (details.status === "answered") {
+    return {
+      content: [{ type: "text", text: formatAskAnswer(ask, details.answer) }],
+      details,
+    };
+  }
+
+  const text = {
+    unanswered: "The question timed out without an answer.",
+    cancelled: "User cancelled the question.",
+    ui_unavailable: "Interactive UI is unavailable.",
+  }[details.status];
+  return { content: [{ type: "text", text }], details };
+}
+
+function normalizeOption(option: AskOption): AskOption {
+  const label = option.label.trim();
+  if (!label) throw new Error("Ask option label must not be empty.");
+  const description = trimOptional(option.description);
+  const preview = option.preview?.trim() ? option.preview : undefined;
+  return {
+    label,
+    ...(description === undefined ? {} : { description }),
+    ...(preview === undefined ? {} : { preview }),
+  };
+}
+
+function trimOptional(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}