@fitchmultz/pi-ask-question 0.6.5 → 0.6.7

package/extensions/lib/form-scrolls.ts

@@ -0,0 +1,250 @@
+/** Scroll state and paging math for the question form. */
+
+import { sliceByColumn } from "@earendil-works/pi-tui";
+
+import type { FormView, PageBuilder } from "./form-page.ts";
+
+/** Question-section clipping outcome: how many lines exist and fit. */
+type QuestionWindow = {
+  lineCount: number;
+  rows: number;
+};
+
+/** Scroll positions and window sizes for question, choice, and review sections. */
+export class FormScrolls {
+  optionScroll = 0;
+  labelScroll = 0;
+  pageRows = 0;
+  maxLabelScroll = 0;
+  questionScroll = 0;
+  questionPageRows = 0;
+  maxQuestionScroll = 0;
+  reviewScroll: number | undefined;
+  reviewPageRows = 0;
+  maxReviewScroll = 0;
+
+  resetForWidth(): void {
+    this.optionScroll = 0;
+    this.labelScroll = 0;
+    this.questionScroll = 0;
+  }
+
+  pageQuestionUp(): void {
+    this.questionScroll = Math.max(0, this.questionScroll - Math.max(1, this.questionPageRows - 1));
+  }
+
+  pageQuestionDown(): void {
+    this.questionScroll = Math.min(
+      this.maxQuestionScroll,
+      this.questionScroll + Math.max(1, this.questionPageRows - 1),
+    );
+  }
+
+  pageChoiceUp(): void {
+    if (this.labelScroll > 0) {
+      this.labelScroll = Math.max(0, this.labelScroll - Math.max(1, this.pageRows - 1));
+    } else {
+      this.pageQuestionUp();
+    }
+  }
+
+  pageChoiceDown(): void {
+    if (this.questionScroll < this.maxQuestionScroll) {
+      this.pageQuestionDown();
+    } else {
+      this.labelScroll = Math.min(
+        this.maxLabelScroll,
+        this.labelScroll + Math.max(1, this.pageRows - 1),
+      );
+    }
+  }
+
+  pageReviewUp(): void {
+    this.reviewScroll = Math.max(
+      0,
+      (this.reviewScroll ?? this.maxReviewScroll) - Math.max(1, this.reviewPageRows - 1),
+    );
+  }
+
+  pageReviewDown(): void {
+    this.reviewScroll = Math.min(
+      this.maxReviewScroll,
+      (this.reviewScroll ?? this.maxReviewScroll) + Math.max(1, this.reviewPageRows - 1),
+    );
+  }
+
+  /** Window the question and choice sections to the terminal height. */
+  applyQuestionScrolling(page: PageBuilder, view: FormView, height: number): void {
+    const questionLines = page.lines.slice(page.questionStart, page.questionEnd);
+    const question = this.clipQuestionLines(page, questionLines, view, height);
+    this.applyOptionScrolling(page, view, height, question);
+  }
+
+  /** Row ranges exist for every rendered choice; indexing is total by construction. */
+  private optionRow(page: PageBuilder, index: number): { start: number; end: number } {
+    const range = page.optionRows[index];
+    if (range !== undefined) {
+      return range;
+    }
+    throw new Error(`ask-question: option row ${index} is missing`);
+  }
+
+  private clipQuestionLines(
+    page: PageBuilder,
+    questionLines: string[],
+    view: FormView,
+    height: number,
+  ): QuestionWindow {
+    const selectedRow = view.editing ? 0 : view.option;
+    const selectedHeight =
+      this.optionRow(page, selectedRow).end - this.optionRow(page, selectedRow).start;
+    const room = Math.max(
+      2,
+      height - (page.lines.length - questionLines.length - (page.optionEnd - page.optionStart)),
+    );
+    const questionRows = Math.max(1, room - selectedHeight);
+    this.maxQuestionScroll = Math.max(0, questionLines.length - questionRows);
+    this.questionScroll = Math.min(this.questionScroll, this.maxQuestionScroll);
+    this.questionPageRows = questionRows;
+    if (this.maxQuestionScroll > 0) {
+      page.lines.splice(
+        page.questionStart,
+        questionLines.length,
+        ...questionLines.slice(this.questionScroll, this.questionScroll + questionRows),
+      );
+      page.shiftOptions(questionLines.length - questionRows);
+    }
+    return { lineCount: questionLines.length, rows: questionRows };
+  }
+
+  private applyOptionScrolling(
+    page: PageBuilder,
+    view: FormView,
+    height: number,
+    question: QuestionWindow,
+  ): void {
+    const optionLines = page.lines.slice(page.optionStart, page.optionEnd);
+    const available = Math.max(1, height);
+    const visibleOptions = Math.max(1, available - (page.lines.length - optionLines.length));
+    let optionStatus = "";
+    if (optionLines.length > visibleOptions) {
+      optionStatus = this.scrollOptionsIntoView(page, view, optionLines, visibleOptions);
+    } else {
+      this.optionScroll = 0;
+      this.labelScroll = 0;
+      this.maxLabelScroll = 0;
+    }
+    if (this.maxQuestionScroll > 0 || optionStatus !== "") {
+      this.addScrollStatus(page, view, optionStatus, question);
+    }
+  }
+
+  private scrollOptionsIntoView(
+    page: PageBuilder,
+    view: FormView,
+    optionLines: string[],
+    visibleOptions: number,
+  ): string {
+    const selectedRow = view.editing ? 0 : view.option;
+    // Scroll at choice boundaries so labels that fit are shown in full.
+    this.optionScroll = Math.min(this.optionScroll, selectedRow);
+    const end = this.findChoiceWindow(page, selectedRow, visibleOptions);
+    while (
+      this.optionScroll > 0 &&
+      this.optionRow(page, end - 1).end - this.optionRow(page, this.optionScroll - 1).start <=
+        visibleOptions
+    ) {
+      this.optionScroll -= 1;
+    }
+    this.maxLabelScroll = Math.max(
+      0,
+      this.optionRow(page, selectedRow).end -
+        this.optionRow(page, selectedRow).start -
+        visibleOptions,
+    );
+    this.labelScroll = Math.min(this.labelScroll, this.maxLabelScroll);
+    this.pageRows = visibleOptions;
+    const startLine = this.optionRow(page, this.optionScroll).start + this.labelScroll;
+    const endLine = Math.min(this.optionRow(page, end - 1).end, startLine + visibleOptions);
+    const above = this.optionScroll > 0 || this.labelScroll > 0 ? "↑ " : "";
+    const below = endLine < optionLines.length ? " ↓" : "";
+    page.lines.splice(
+      page.optionStart,
+      optionLines.length,
+      ...optionLines.slice(startLine, endLine),
+    );
+    return `${above}${view.option + 1}/${view.choices().length}${below}`;
+  }
+
+  private findChoiceWindow(page: PageBuilder, selectedRow: number, visibleOptions: number): number {
+    while (
+      this.optionScroll < selectedRow &&
+      this.optionRow(page, selectedRow).end - this.optionRow(page, this.optionScroll).start >
+        visibleOptions
+    ) {
+      this.optionScroll += 1;
+    }
+    let end = selectedRow + 1;
+    while (
+      end < page.optionRows.length &&
+      this.optionRow(page, end).end - this.optionRow(page, this.optionScroll).start <=
+        visibleOptions
+    ) {
+      end += 1;
+    }
+    return end;
+  }
+
+  private addScrollStatus(
+    page: PageBuilder,
+    view: FormView,
+    optionStatus: string,
+    question: QuestionWindow,
+  ): void {
+    const questionStatus =
+      this.maxQuestionScroll > 0
+        ? `Q ${this.questionScroll + 1}-${Math.min(
+            this.questionScroll + question.rows,
+            question.lineCount,
+          )}/${question.lineCount}`
+        : "";
+    const read =
+      !view.editing && (this.maxQuestionScroll > 0 || this.maxLabelScroll > 0)
+        ? ` • ${view.keyText("tui.select.pageUp")}/${view.keyText("tui.select.pageDown")} read (Shift+Page fullscreen)`
+        : "";
+    const status =
+      view.editing && this.maxQuestionScroll > 0
+        ? `Shift+PageUp/Down question • ${questionStatus}`
+        : `${[questionStatus, optionStatus].filter(Boolean).join(" • ")}${read}`;
+    page.setLine(
+      page.optionStart - 1,
+      sliceByColumn(view.theme.fg("dim", ` ${status}`), 0, page.width, true),
+    );
+  }
+
+  /** Window the review section to the terminal height, sticking to the end. */
+  applyReviewScrolling(page: PageBuilder, view: FormView, height: number): void {
+    const answerLines = page.lines.slice(page.reviewStart, page.reviewEnd);
+    const visibleAnswers = Math.max(1, height - (page.lines.length - answerLines.length));
+    const wasAtEnd = this.reviewScroll === undefined || this.reviewScroll === this.maxReviewScroll;
+    this.maxReviewScroll = Math.max(0, answerLines.length - visibleAnswers);
+    this.reviewScroll = wasAtEnd
+      ? this.maxReviewScroll
+      : Math.min(this.reviewScroll ?? 0, this.maxReviewScroll);
+    this.reviewPageRows = visibleAnswers;
+    if (this.maxReviewScroll > 0) {
+      const above = this.reviewScroll > 0 ? "↑ " : "";
+      const below = this.reviewScroll < this.maxReviewScroll ? " ↓" : "";
+      const read = `${view.keyText("tui.select.pageUp")}/${view.keyText("tui.select.pageDown")} read answers (Shift+Page fullscreen)`;
+      page.setLine(
+        page.reviewStart - 1,
+        sliceByColumn(view.theme.fg("dim", ` ${above}${read}${below}`), 0, page.width, true),
+      );
+      page.lines.splice(
+        page.reviewStart,
+        answerLines.length,
+        ...answerLines.slice(this.reviewScroll, this.reviewScroll + visibleAnswers),
+      );
+    }
+  }
+}

package/extensions/lib/grill-me.ts

@@ -0,0 +1,152 @@
+/** /grill-me mode: command, persisted state, and agent guidance. */
+
+import type {
+  BeforeAgentStartEventResult,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { isRecord } from "./validate.ts";
+
+type GrillMeState = {
+  enabled: boolean;
+};
+
+type GrillMeAction = "toggle" | "enable" | "disable" | "status" | "invalid";
+
+const GRILL_ME_STATE_TYPE = "ask-question.grill-me";
+const GRILL_ME_STATUS_KEY = "ask-question.grill-me";
+const GRILL_ME_ARGUMENTS = ["on", "off", "status"];
+
+function grillMePrompt(useTool: boolean): string {
+  return `IMPORTANT: /grill-me mode is active.
+
+Pressure-test the user's request before doing meaningful work:
+- Walk the decision tree: resolve upstream choices before downstream details.
+- If a question can be answered by reading local files, docs, tests, or command output, inspect those sources instead of asking the user.
+- For non-trivial, risky, underspecified, or strategic requests, ${useTool ? "call ask_question first" : "ask clarifying questions first in normal text"}.
+- Ask exactly one blocking question at a time, then wait for the answer before asking the next one.
+- For every question, include your recommended answer as the first option and make it specific.
+- Do not ask when the next step is obvious, low-risk, or already constrained; proceed normally.
+- After the user answers, continue the work directly.`;
+}
+
+function parseGrillMeAction(args: string): GrillMeAction {
+  switch (args.trim().toLowerCase()) {
+    case "":
+      return "toggle";
+    case "on":
+      return "enable";
+    case "off":
+      return "disable";
+    case "status":
+      return "status";
+    default:
+      return "invalid";
+  }
+}
+
+function completeGrillMeArgs(prefix: string): AutocompleteItem[] | null {
+  const matches = GRILL_ME_ARGUMENTS.filter((arg) => arg.startsWith(prefix.trim().toLowerCase()));
+  return matches.length > 0 ? matches.map((value) => ({ value, label: value })) : null;
+}
+
+function isGrillMeState(data: unknown): data is GrillMeState {
+  return (
+    data !== null &&
+    typeof data === "object" &&
+    "enabled" in data &&
+    typeof data.enabled === "boolean"
+  );
+}
+
+function restoreGrillMeState(entries: Iterable<unknown>): boolean {
+  let enabled = false;
+  for (const entry of entries) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    if (
+      entry.type === "custom" &&
+      entry.customType === GRILL_ME_STATE_TYPE &&
+      isGrillMeState(entry.data)
+    ) {
+      enabled = entry.data.enabled;
+    }
+  }
+  return enabled;
+}
+
+/** Register the /grill-me command and its session-aware guidance hooks. */
+export function registerGrillMe(pi: ExtensionAPI): void {
+  let grillMeMode = false;
+
+  function persistGrillMeMode(): void {
+    pi.appendEntry<GrillMeState>(GRILL_ME_STATE_TYPE, { enabled: grillMeMode });
+  }
+
+  function updateGrillMeStatus(ctx: Pick<ExtensionContext, "mode" | "ui">): void {
+    if (ctx.mode !== "tui") {
+      return;
+    }
+    ctx.ui.setStatus(
+      GRILL_ME_STATUS_KEY,
+      grillMeMode ? ctx.ui.theme.fg("dim", "grill-mode") : undefined,
+    );
+  }
+
+  function restoreGrillMeMode(ctx: ExtensionContext): void {
+    grillMeMode = restoreGrillMeState(ctx.sessionManager.getBranch());
+  }
+
+  pi.registerCommand("grill-me", {
+    description: "Toggle a mode that makes the agent pressure-test requests with ask_question",
+    getArgumentCompletions: completeGrillMeArgs,
+    handler: async (args, ctx): Promise<void> => {
+      const action = parseGrillMeAction(args);
+      if (action === "enable") {
+        grillMeMode = true;
+      } else if (action === "disable") {
+        grillMeMode = false;
+      } else if (action === "toggle") {
+        grillMeMode = !grillMeMode;
+      } else if (action === "invalid") {
+        ctx.ui.notify("Usage: /grill-me [on|off|status]", "warning");
+        return;
+      }
+
+      if (action !== "status") {
+        persistGrillMeMode();
+      }
+      updateGrillMeStatus(ctx);
+      ctx.ui.notify(`Grill-me mode ${grillMeMode ? "enabled" : "disabled"}`, "info");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx): Promise<void> => {
+    restoreGrillMeMode(ctx);
+    updateGrillMeStatus(ctx);
+  });
+
+  pi.on("session_tree", async (_event, ctx): Promise<void> => {
+    restoreGrillMeMode(ctx);
+    updateGrillMeStatus(ctx);
+  });
+
+  pi.on(
+    "before_agent_start",
+    async (event, ctx): Promise<BeforeAgentStartEventResult | undefined> => {
+      if (!grillMeMode) {
+        return;
+      }
+      const useTool = ctx.hasUI && pi.getActiveTools().includes("ask_question");
+      const guidance = grillMePrompt(useTool);
+      if (event.systemPromptOptions.forceSystemPrompt === undefined) {
+        // oxlint-disable-next-line eslint/no-param-reassign -- QX-002: Pi documents systemPromptOptions.sections as mutable by handlers; mutation is the supported section-injection contract.
+        event.systemPromptOptions.sections.grill_me = guidance;
+        return;
+      }
+      return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` };
+    },
+  );
+}

package/extensions/lib/normalize.ts

@@ -0,0 +1,126 @@
+/** Question normalization and answer summarizing. */
+
+import { TIMEOUT_MESSAGE, type Answer, type NormalizedQuestion, type Question } from "./types.ts";
+
+/** Trim a value and drop empty results; undefined passes through. */
+export function clean(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (trimmed === undefined || trimmed.length === 0) {
+    return undefined;
+  }
+  return trimmed;
+}
+
+/** Add a numeric suffix until the label no longer collides with existing options. */
+export function uniqueOptionLabel(label: string, options: string[]): string {
+  let result = label;
+  for (let suffix = 2; options.includes(result); suffix += 1) {
+    result = `${label} (${suffix})`;
+  }
+  return result;
+}
+
+/** Normalize schema input into complete, deduplicated questions. */
+export function normalize(params: {
+  question?: string;
+  options?: string[];
+  multiSelect?: boolean;
+  questions?: Question[];
+}): NormalizedQuestion[] {
+  const questions = params.questions;
+  const raw =
+    questions !== undefined && questions.length > 0
+      ? questions
+      : [
+          {
+            id: "question_1",
+            question: params.question ?? "",
+            options: params.options,
+            multiSelect: params.multiSelect,
+          },
+        ];
+
+  const assigned = new Set<string>();
+  const result: NormalizedQuestion[] = [];
+
+  for (const [index, question] of raw.entries()) {
+    const text = clean(question.question);
+    if (text === undefined) {
+      continue;
+    }
+
+    const baseId = clean(question.id) ?? `question_${index + 1}`;
+    let id = baseId;
+    let suffix = 2;
+    while (assigned.has(id)) {
+      id = `${baseId}_${suffix}`;
+      suffix += 1;
+    }
+    assigned.add(id);
+
+    result.push({
+      id,
+      question: text,
+      options: (question.options ?? [])
+        .map(clean)
+        .filter((option): option is string => option !== undefined),
+      multiSelect: question.multiSelect === true,
+    });
+  }
+
+  return result;
+}
+
+/** Answers in question order, skipping unanswered questions. */
+export function orderedAnswers(
+  questions: NormalizedQuestion[],
+  answers: Map<string, Answer>,
+): Answer[] {
+  return questions
+    .map((question) => answers.get(question.id))
+    .filter((answer): answer is Answer => answer !== undefined);
+}
+
+/** One-line rendering of an answer for summaries and the review page. */
+export function formatAnswer(answer: Answer | undefined): string {
+  if (answer === undefined) {
+    return "unanswered";
+  }
+  return answer.selectedOptions !== undefined
+    ? JSON.stringify(answer.selectedOptions)
+    : answer.answer;
+}
+
+/** Human-readable summary returned as the tool result text. */
+export function summarize(
+  questions: NormalizedQuestion[],
+  answers: Map<string, Answer>,
+  cancelled: boolean,
+  timedOut: boolean,
+): string {
+  if (timedOut) {
+    return [
+      `Timed out after 5 minutes. ${TIMEOUT_MESSAGE}`,
+      ...(answers.size > 0
+        ? [
+            "",
+            "Answers already provided:",
+            ...orderedAnswers(questions, answers).map(
+              (answer) => `- ${answer.id}: ${formatAnswer(answer)}`,
+            ),
+          ]
+        : []),
+    ].join("\n");
+  }
+  if (cancelled) {
+    return "User cancelled the question.";
+  }
+  const [only] = questions;
+  if (questions.length === 1 && only !== undefined) {
+    return `User answered: ${formatAnswer(answers.get(only.id))}`;
+  }
+  return [
+    "User answered:",
+    ...questions.map((question) => `- ${question.id}: ${formatAnswer(answers.get(question.id))}`),
+  ].join("\n");
+}