pi-ask-popup 0.1.0

package/src/tool/response-envelope.ts

@@ -0,0 +1,123 @@
+import { formatAnswerScalar } from "./format-answer.js";
+import type {
+  QuestionAnswer,
+  QuestionnaireResult,
+  QuestionParams,
+  UnansweredNote,
+} from "./types.js";
+
+export const DECLINE_MESSAGE = "User declined to answer questions";
+export const TIMED_OUT_MESSAGE =
+  "Questionnaire timed out — the user did not respond within the configured timeout. The user never saw a decline; do NOT treat this as a rejection. Ask the questions as plain chat text instead or retry.";
+export const ENVELOPE_PREFIX = "User has answered your questions:";
+export const ENVELOPE_SUFFIX = "You can now continue with the user's answers in mind.";
+/** Opens the segment for a note whose question was never answered. */
+export const UNANSWERED_NOTE_PREFIX = "note on";
+
+export interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: QuestionnaireResult;
+}
+
+/**
+ * Turn a questionnaire result into the envelope the model reads. Pure of
+ * `(result, params)`.
+ *
+ * Cancelled and "nothing to report" both collapse to `DECLINE_MESSAGE`, so the
+ * model sees one canonical "the user did not answer" signal rather than having
+ * to distinguish shades of it. Partial answers and a global note still ride
+ * along in `details` for anything replaying the session.
+ *
+ * "Nothing to report" means no answers AND no global note. The note segment is
+ * appended before that check on purpose: submitting a global note and nothing
+ * else is a real answer, not a decline.
+ */
+export function buildQuestionnaireResponse(
+  result: QuestionnaireResult | null | undefined,
+  params: QuestionParams,
+): ToolResult {
+  if (result?.error === "timed_out") {
+    return buildToolResult(TIMED_OUT_MESSAGE, {
+      answers: result.answers,
+      cancelled: true,
+      error: "timed_out",
+      ...(result.globalNote && result.globalNote.length > 0
+        ? { globalNote: result.globalNote }
+        : {}),
+      ...(result.unansweredNotes && result.unansweredNotes.length > 0
+        ? { unansweredNotes: result.unansweredNotes }
+        : {}),
+    });
+  }
+  if (!result || result.cancelled) {
+    // The decline text stays canonical even when a global note rides a
+    // cancelled result. The note survives in `details`, like partial answers.
+    return buildToolResult(DECLINE_MESSAGE, {
+      answers: result?.answers ?? [],
+      cancelled: true,
+      ...(result?.error ? { error: result.error } : {}),
+      ...(result?.globalNote && result.globalNote.length > 0
+        ? { globalNote: result.globalNote }
+        : {}),
+      ...(result?.unansweredNotes && result.unansweredNotes.length > 0
+        ? { unansweredNotes: result.unansweredNotes }
+        : {}),
+    });
+  }
+
+  const segments: string[] = [];
+  // Iterate the questions rather than the answers so segments always follow the
+  // order the model asked in, whatever order the user filled tabs.
+  for (let i = 0; i < params.questions.length; i++) {
+    const a = result.answers.find((x) => x.questionIndex === i);
+    if (a) {
+      segments.push(buildAnswerSegment(a));
+      continue;
+    }
+    // A note with no answer behind it still belongs in ask order, so it is
+    // emitted here rather than grouped at the end. Because this loop runs
+    // before the "nothing to report" check below, a questionnaire submitted
+    // with nothing but such a note counts as answered rather than declined.
+    const n = result.unansweredNotes?.find((x) => x.questionIndex === i);
+    if (n) segments.push(buildUnansweredNoteSegment(n));
+  }
+  if (result.globalNote && result.globalNote.length > 0) {
+    // Raw multiline echo, no reformatting, trailing period matching the shape
+    // of an answer segment.
+    segments.push(`global note: ${result.globalNote}.`);
+  }
+  if (segments.length === 0) {
+    return buildToolResult(DECLINE_MESSAGE, { answers: result.answers, cancelled: true });
+  }
+  return buildToolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, result);
+}
+
+/**
+ * One answer as an envelope segment: `"question"="answer"`, optionally followed
+ * by the preview the user was looking at and the note they wrote.
+ */
+export function buildAnswerSegment(a: QuestionAnswer): string {
+  const parts: string[] = [`"${a.question}"="${formatAnswerScalar(a, "envelope")}"`];
+  if (a.preview && a.preview.length > 0) parts.push(`selected preview: ${a.preview}`);
+  if (a.notes && a.notes.length > 0) parts.push(`user notes: ${a.notes}`);
+  return `${parts.join(". ")}.`;
+}
+
+/**
+ * A note whose question was never answered.
+ *
+ * Its own segment shape rather than an answer segment with a placeholder in the
+ * answer slot: there is no answer to place, and a second "(no answer)" string
+ * sitting one word away from `NO_INPUT_PLACEHOLDER` would be two
+ * near-identical placeholders meaning different things.
+ */
+export function buildUnansweredNoteSegment(n: UnansweredNote): string {
+  return `${UNANSWERED_NOTE_PREFIX} "${n.question}": ${n.note}.`;
+}
+
+export function buildToolResult(text: string, details: QuestionnaireResult): ToolResult {
+  return {
+    content: [{ type: "text" as const, text }],
+    details,
+  };
+}

package/src/tool/types.ts

@@ -0,0 +1,193 @@
+import { type Static, Type } from "typebox";
+import { LABELS_BY_KIND, ROW_INTENT_META } from "../state/row-intent.js";
+
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER_LENGTH = 16;
+export const MAX_LABEL_LENGTH = 60;
+
+/**
+ * User-facing labels for the sentinel rows, keyed by row kind. Sourced from the
+ * row-intent table so there is one definition. Adding a sentinel there extends
+ * this map automatically.
+ */
+export const SENTINEL_LABELS = LABELS_BY_KIND;
+
+export type { SentinelKind } from "../state/row-intent.js";
+export type SentinelLabel = (typeof SENTINEL_LABELS)[keyof typeof SENTINEL_LABELS];
+
+/**
+ * Labels an author may not use. Two come from the row-intent table; `"Other"`
+ * has no runtime row kind and is reserved anyway, because models are
+ * conditioned to reach for it as a free-text escape and the runtime sentinel
+ * must stay the only route there.
+ *
+ * Reserved unconditionally: every question mode rejects these, even where the
+ * corresponding sentinel is not appended in that mode.
+ *
+ * The explicit literal order is load-bearing for consumers that index into the
+ * array or compare it whole.
+ */
+export const RESERVED_LABELS = [
+  "Other",
+  ROW_INTENT_META.other.label,
+  ROW_INTENT_META.next.label,
+] as const;
+export type ReservedLabel = (typeof RESERVED_LABELS)[number];
+
+export const OptionSchema = Type.Object({
+  label: Type.String({
+    maxLength: MAX_LABEL_LENGTH,
+    description: `MAX ${MAX_LABEL_LENGTH} CHARACTERS — hard limit, requests over the limit are rejected. The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.`,
+  }),
+  description: Type.String({
+    description:
+      "Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
+  }),
+  preview: Type.Optional(
+    Type.String({
+      description:
+        "Optional preview content rendered when this option is focused. Use for mockups, code snippets, or visual comparisons that help users compare options. See the tool description for the expected content format.",
+    }),
+  ),
+});
+
+export const QuestionSchema = Type.Object({
+  question: Type.String({
+    description:
+      'The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: "Which library should we use for date formatting?" If multiSelect is true, phrase it accordingly, e.g. "Which features do you want to enable?"',
+  }),
+  header: Type.String({
+    maxLength: MAX_HEADER_LENGTH,
+    description: `MAX ${MAX_HEADER_LENGTH} CHARACTERS — hard limit, requests over the limit are rejected. Very short chip/tag shown next to the question. Examples: "Auth method", "Library", "Approach".`,
+  }),
+  options: Type.Array(OptionSchema, {
+    minItems: MIN_OPTIONS,
+    maxItems: MAX_OPTIONS,
+    description:
+      "The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). The 'Type something.' row is appended automatically — do NOT author it.",
+  }),
+  multiSelect: Type.Optional(
+    Type.Boolean({
+      default: false,
+      description:
+        "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
+    }),
+  ),
+});
+
+export const QuestionsSchema = Type.Array(QuestionSchema, {
+  minItems: 1,
+  maxItems: MAX_QUESTIONS,
+  description: "Questions to ask the user (1-4 questions)",
+});
+
+export const QuestionParamsSchema = Type.Object({
+  questions: QuestionsSchema,
+  timeout: Type.Optional(
+    Type.Integer({
+      minimum: 1000,
+      description:
+        'Optional timeout in milliseconds after which the questionnaire auto-dismisses with a live countdown. When it expires the tool returns cancelled:true with error "timed_out" — not a decline. The user never saw a timeout as a rejection; retry or fall back to asking in chat instead.',
+    }),
+  ),
+});
+
+export type OptionData = Static<typeof OptionSchema>;
+export type QuestionData = Static<typeof QuestionSchema>;
+export type QuestionParams = Static<typeof QuestionParamsSchema>;
+
+/**
+ * Answer-intent union. `kind` is the only discriminator; parallel boolean flags
+ * are banned and a test enforces that.
+ *
+ * - `option` — the user picked an authored option. `answer` is its label.
+ * - `custom` — the user typed free text in the "Type something." row.
+ *   `answer` is the text, or null when they committed nothing.
+ * - `multi` — the user committed multi-select choices. `selected` carries the
+ *   chosen labels and `answer` is null.
+ */
+export interface QuestionAnswer {
+  questionIndex: number;
+  question: string;
+  kind: "option" | "custom" | "multi";
+  answer: string | null;
+  selected?: string[];
+  notes?: string;
+  /**
+   * Markdown copied from the chosen option's `preview`, populated only when a
+   * single-select answer landed on a preview-bearing option. The envelope
+   * echoes it back so the model knows which artifact the user actually saw.
+   * Undefined for multi-select and free-text answers.
+   */
+  preview?: string;
+}
+
+/**
+ * A note the user wrote on a question they never answered.
+ *
+ * These cannot ride in `answers`. `notesByTab` is decoupled from `answers` so
+ * that writing a note does not mark a question answered, and folding a
+ * note-only entry into `answers` would flip its tab to answered and silence the
+ * Submit tab's missing-question warning. They get their own field instead,
+ * exactly as `globalNote` does.
+ *
+ * `question` is copied alongside the index for the same reason `QuestionAnswer`
+ * copies it: a replayed session reads standalone, with no access to the params
+ * the questionnaire was built from.
+ */
+export interface UnansweredNote {
+  questionIndex: number;
+  question: string;
+  note: string;
+}
+
+export type QuestionnaireError =
+  | "no_ui"
+  | "no_custom_ui"
+  | "no_questions"
+  | "empty_options"
+  | "too_many_questions"
+  | "duplicate_question"
+  | "duplicate_option_label"
+  | "reserved_label"
+  | "session_load_failed"
+  | "stale_module_cache"
+  | "timed_out";
+
+export interface QuestionnaireResult {
+  answers: QuestionAnswer[];
+  cancelled: boolean;
+  /**
+   * A note covering the whole questionnaire rather than one question, authored
+   * on the Submit tab. Attached on cancel as well as submit, mirroring
+   * per-question notes.
+   *
+   * Conditional-spread contract: the key appears only via conditional spread of
+   * a non-empty string. Never assigned `undefined`, never kept for a
+   * whitespace-only draft, so a note-free result stays byte-identical and
+   * `!("globalNote" in result)` holds.
+   */
+  globalNote?: string;
+  /**
+   * Notes on questions that were never answered, in the order the questions
+   * were asked. Without this field they were discarded silently: the note lived
+   * in `notesByTab`, and both the envelope and the Submit review skipped any
+   * tab with no answer.
+   *
+   * Same conditional-spread contract as `globalNote`: the key appears only via
+   * conditional spread of a non-empty array, is never assigned `undefined`, and
+   * so a result with no such notes stays byte-identical and
+   * `!("unansweredNotes" in result)` holds. Attached on cancel as well as
+   * submit, mirroring per-question notes.
+   */
+  unansweredNotes?: UnansweredNote[];
+  error?: QuestionnaireError;
+}
+
+export function isQuestionnaireResult(value: unknown): value is QuestionnaireResult {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return Array.isArray(v.answers) && typeof v.cancelled === "boolean";
+}

package/src/tool/validate-questionnaire.ts

@@ -0,0 +1,74 @@
+import {
+  MAX_QUESTIONS,
+  MIN_OPTIONS,
+  type QuestionnaireError,
+  type QuestionParams,
+  RESERVED_LABELS,
+} from "./types.js";
+
+export const ERROR_NO_QUESTIONS = "Error: At least one question is required";
+export const ERROR_TOO_MANY_QUESTIONS = `Error: At most ${MAX_QUESTIONS} questions are allowed per invocation`;
+export const ERROR_DUPLICATE_QUESTION = "Error: Question text must be unique within an invocation";
+export const ERROR_TOO_FEW_OPTIONS = `Error: Each question requires at least ${MIN_OPTIONS} options`;
+export const ERROR_RESERVED_LABEL = `Error: Option label is reserved (${RESERVED_LABELS.join(", ")})`;
+export const ERROR_DUPLICATE_OPTION_LABEL = "Error: Option labels must be unique within a question";
+
+const RESERVED_LABEL_SET: ReadonlySet<string> = new Set<string>(RESERVED_LABELS);
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; error: QuestionnaireError; message: string };
+
+/**
+ * Runtime validator for tool parameters. Pure. Covers every guard except
+ * `no_ui`, which depends on host state and stays at the call site.
+ *
+ * Upstream documents the reserved-label check as needing to precede the
+ * duplicate-label check. It reads well but is unobservable: a reserved label
+ * trips on its FIRST occurrence, when `seenLabels` cannot yet contain it, so no
+ * option is ever both reserved and a duplicate. Two `"Other"` options return
+ * `reserved_label` at index 0 under either ordering, and index 1 is
+ * unreachable. Swapping these two blocks changes no output for any input.
+ *
+ * The order is kept because it reads in order of severity, not because
+ * behavior depends on it. Do not add a test claiming to pin the precedence:
+ * it would pass under both orderings and assert nothing.
+ */
+export function validateQuestionnaire(typed: QuestionParams): ValidationResult {
+  if (typed.questions.length === 0) {
+    return { ok: false, error: "no_questions", message: ERROR_NO_QUESTIONS };
+  }
+  if (typed.questions.length > MAX_QUESTIONS) {
+    return { ok: false, error: "too_many_questions", message: ERROR_TOO_MANY_QUESTIONS };
+  }
+
+  const seenQuestions = new Set<string>();
+  for (const q of typed.questions) {
+    if (seenQuestions.has(q.question)) {
+      return { ok: false, error: "duplicate_question", message: ERROR_DUPLICATE_QUESTION };
+    }
+    seenQuestions.add(q.question);
+  }
+
+  for (const q of typed.questions) {
+    if (q.options.length < MIN_OPTIONS) {
+      return { ok: false, error: "empty_options", message: ERROR_TOO_FEW_OPTIONS };
+    }
+    const seenLabels = new Set<string>();
+    for (const o of q.options) {
+      if (RESERVED_LABEL_SET.has(o.label)) {
+        return { ok: false, error: "reserved_label", message: ERROR_RESERVED_LABEL };
+      }
+      if (seenLabels.has(o.label)) {
+        return {
+          ok: false,
+          error: "duplicate_option_label",
+          message: ERROR_DUPLICATE_OPTION_LABEL,
+        };
+      }
+      seenLabels.add(o.label);
+    }
+  }
+
+  return { ok: true };
+}

package/src/view/component-binding.ts

@@ -0,0 +1,51 @@
+import type {
+  BindingContext,
+  GlobalSelector,
+  PerTabBindingContext,
+  PerTabSelector,
+} from "../state/selectors/contract.js";
+import type { QuestionnaireState } from "../state/state.js";
+import type { StatefulView } from "./stateful-view.js";
+import type { TabComponents } from "./tab-components.js";
+
+/** A cross-tab component and the selector that computes its props. */
+export interface ComponentBinding<P> {
+  readonly component: StatefulView<P>;
+  readonly select: GlobalSelector<P>;
+}
+
+/**
+ * A per-tab component kind. `resolve` picks the instance out of a tab, and may
+ * return undefined for kinds a tab does not have (only multiSelect questions
+ * carry a `MultiSelectView`). `predicate` skips the write entirely.
+ */
+export interface PerTabBinding<P> {
+  readonly resolve: (tab: TabComponents) => StatefulView<P> | undefined;
+  readonly select: PerTabSelector<P>;
+  readonly predicate?: PerTabSelector<boolean>;
+}
+
+export interface BoundGlobalBinding {
+  apply(state: QuestionnaireState, ctx: BindingContext): void;
+  invalidate(): void;
+}
+
+export interface BoundPerTabBinding {
+  apply(state: QuestionnaireState, ctx: PerTabBindingContext): void;
+}
+
+export function globalBinding<P>(spec: ComponentBinding<P>): BoundGlobalBinding {
+  return {
+    apply: (state, ctx) => spec.component.setProps(spec.select(state, ctx)),
+    invalidate: () => spec.component.invalidate(),
+  };
+}
+
+export function perTabBinding<P>(spec: PerTabBinding<P>): BoundPerTabBinding {
+  return {
+    apply: (state, ctx) => {
+      if (spec.predicate && !spec.predicate(state, ctx)) return;
+      spec.resolve(ctx.tab)?.setProps(spec.select(state, ctx));
+    },
+  };
+}

package/src/view/components/inline-input.ts

@@ -0,0 +1,66 @@
+import { CURSOR_MARKER, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+// Grapheme-aware extraction at the cursor: pi-tui's Editor reports UTF-16
+// line/column positions, so the cursor can land between code units of one cluster
+// (emoji, ZWJ, combining marks). Single-code-unit slicing would split the cluster
+// across the SGR 7/27 boundary. Both single- and multi-select views share this
+// cursor-building core.
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+export interface RenderInlineInputOptions {
+  /** Live inline-input buffer. */
+  buffer: string;
+  /** Cursor offset; `undefined` / out-of-range → end-of-buffer fallback. */
+  cursorOffset: number | undefined;
+  /** Prefix for the first emitted line (e.g. `❯ 4. `). */
+  rowPrefix: string;
+  /** Prefix for continuation lines (whitespace of equal visible width). */
+  continuationPrefix: string;
+  /** Visible columns available for the buffer content (width − prefix width). */
+  contentWidth: number;
+  /** Per-line styling (single-select: `theme.selectedText`; multi-select: accent+bold). */
+  selectedText: (text: string) => string;
+}
+
+/**
+ * Resolve the cursor offset, falling back to end-of-buffer for `undefined`/out-of-range.
+ * Mirrors the original wrapping-select.resolveOffset exactly.
+ */
+function resolveCursorOffset(buffer: string, requested: number | undefined): number {
+  if (requested !== undefined && requested >= 0 && requested <= buffer.length) return requested;
+  return buffer.length;
+}
+
+/**
+ * Build the cursor-marked raw string for the whole buffer: `before | CURSOR_MARKER |
+ * SGR-7 reverse-video cell | SGR-27 | after`. The cell UNDER the cursor is the single
+ * grapheme at the offset (or U+00A0 NBSP at end-of-buffer / on a literal space — NBSP is
+ * wrap-safe where a literal space would tokenize as a wrap break). Zero characters shift;
+ * the column under the cursor inverts. `CURSOR_MARKER` is zero-width so wrap/truncate math
+ * is preserved.
+ */
+function buildCursorRaw(buffer: string, offset: number): string {
+  const before = buffer.slice(0, offset);
+  const [firstGrapheme] = graphemeSegmenter.segment(buffer.slice(offset));
+  const rawAt = firstGrapheme ? firstGrapheme.segment : "";
+  // A logical newline has no visible cell. Draw the cursor on an NBSP immediately
+  // before it and leave the newline unconsumed so the next logical line still renders.
+  const cursorAtLineEnd = rawAt === "\n";
+  const atCursor = rawAt === "" || rawAt === " " || cursorAtLineEnd ? "\xa0" : rawAt;
+  const after = buffer.slice(offset + (cursorAtLineEnd ? 0 : rawAt.length));
+  return `${before}${CURSOR_MARKER}\x1b[7m${atCursor}\x1b[27m${after}`;
+}
+
+/**
+ * Render the inline editor across logical and visually wrapped lines.
+ * Cursor visualization follows Pi's editor pattern: reverse-video on the cell at
+ * the cursor, with a non-breaking-space cell at end-of-line/end-of-buffer.
+ */
+export function renderInlineInputRow(opts: RenderInlineInputOptions): string[] {
+  const { buffer, cursorOffset, rowPrefix, continuationPrefix, contentWidth, selectedText } = opts;
+  const raw = buildCursorRaw(buffer, resolveCursorOffset(buffer, cursorOffset));
+  return wrapTextWithAnsi(raw, contentWidth).map((segment, index) => {
+    const prefix = index === 0 ? rowPrefix : continuationPrefix;
+    return selectedText(`${prefix}${segment}`);
+  });
+}