@pi-kaush/pi-tool-call-markers 0.3.5 → 0.3.7

package/src/prompt-shell.ts

@@ -0,0 +1,174 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+// The submitted-prompt shell, shared by every execution row that should read
+// as user input: user-run `!` bash blocks and asked-question blocks. Pi's own
+// submitted user messages are drawn with the same rail, surface, inset, and
+// body padding by pi-content-layout, which owns the message surface and never
+// tool rows. The geometry here mirrors that package's `renderSubmittedUserLines`
+// and `contentInset`; change the two together.
+
+export const PROMPT_RAIL = "▎";
+
+export type PromptShellTheme = {
+  fg(color: string, text: string): string;
+  getBgAnsi?(color: string): string;
+};
+
+// The prompt surface paints with the theme's userMessageBg token, matching
+// pi-content-layout's surfaces. userMessageBg is a required pi theme token;
+// the legacy hex remains only as a fallback for theme lookalikes without
+// getBgAnsi.
+const PROMPT_SURFACE_BG_FALLBACK = "\x1b[48;2;7;19;18m"; // #071312
+
+const PROMPT_BLOCK_INSET = 2;
+
+function promptSurfaceBg(theme: PromptShellTheme): string {
+  try {
+    return theme.getBgAnsi?.("userMessageBg") ?? PROMPT_SURFACE_BG_FALLBACK;
+  } catch {
+    return PROMPT_SURFACE_BG_FALLBACK;
+  }
+}
+
+// Prompt-shell blocks align with the message inset pi-content-layout applies
+// to transcript lines: 2 columns outside the rail for any width above 4.
+export function promptBlockInset(width: number): number {
+  return width > PROMPT_BLOCK_INSET * 2 ? PROMPT_BLOCK_INSET : 0;
+}
+
+// Inside the rail, a block's body is padded on both sides. Pi's submitted user
+// messages carry one column left and two right, which the shorter right column
+// of the rail glyph's cell makes read as equal. A user `!` block keeps Pi's own
+// body and pads left only.
+export type PromptBlockPadding = { left: number; right: number };
+
+export const SUBMITTED_PROMPT_PADDING: PromptBlockPadding = {
+  left: 1,
+  right: 2,
+};
+
+const BASH_BLOCK_PADDING: PromptBlockPadding = { left: 1, right: 0 };
+
+// Columns available to pre-wrapped content lines: the inset on both sides, the
+// rail, and the body padding `renderRailedBlockLines` applies.
+export function promptBlockContentWidth(
+  width: number,
+  inset = promptBlockInset(width),
+  padding: PromptBlockPadding = BASH_BLOCK_PADDING,
+): number {
+  if (inset === 0) return Math.max(1, width);
+  return Math.max(
+    1,
+    width -
+      inset * 2 -
+      visibleWidth(PROMPT_RAIL) -
+      padding.left -
+      padding.right,
+  );
+}
+
+const SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
+const BACKGROUND_PATTERN =
+  /\x1b\[(?:4[0-8]|10[0-7]|48;5;\d{1,3}|48;2;\d{1,3};\d{1,3};\d{1,3})m/g;
+const DISPLAY_ANSI_PATTERN = /\x1b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+
+function semanticControlEnd(text: string, offset: number): number | undefined {
+  if (text[offset] !== "\x1b") return undefined;
+  const kind = text[offset + 1];
+  if (kind !== "]" && kind !== "_" && kind !== "P" && kind !== "^") {
+    return undefined;
+  }
+  for (let index = offset + 2; index < text.length; index++) {
+    if (text[index] === "\x07") return index + 1;
+    if (text[index] === "\x1b" && text[index + 1] === "\\") {
+      return index + 2;
+    }
+  }
+  return undefined;
+}
+
+function splitLeadingSemanticControls(line: string): {
+  controls: string;
+  content: string;
+} {
+  let offset = 0;
+  while (offset < line.length) {
+    const end = semanticControlEnd(line, offset);
+    if (end === undefined) break;
+    offset = end;
+  }
+  return { controls: line.slice(0, offset), content: line.slice(offset) };
+}
+
+export function fitLine(line: string, width: number): string {
+  if (width <= 0) return "";
+  const clipped = truncateToWidth(line, width, "");
+  return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+function reapplyBackgroundAfterReset(
+  text: string,
+  backgroundAnsi: string,
+): string {
+  return text.replace(SGR_PATTERN, (sequence, rawParameters: string) => {
+    const parameters =
+      rawParameters === "" ? [0] : rawParameters.split(";").map(Number);
+    return parameters.includes(0) || parameters.includes(49)
+      ? `${sequence}${backgroundAnsi}`
+      : sequence;
+  });
+}
+
+function paintBackground(
+  line: string,
+  width: number,
+  backgroundAnsi: string,
+): string {
+  const fitted = fitLine(line, width);
+  // Mirrors Theme.bg: background, content, then a background-only reset.
+  return `${backgroundAnsi}${reapplyBackgroundAfterReset(fitted, backgroundAnsi)}\x1b[49m`;
+}
+
+export function stripDisplayAnsi(text: string): string {
+  return text.replace(DISPLAY_ANSI_PATTERN, "");
+}
+
+function replaceBackground(text: string, backgroundAnsi: string): string {
+  return text.replace(BACKGROUND_PATTERN, backgroundAnsi);
+}
+
+// Renders lines inside a railed, dark-surfaced block (the submitted-prompt
+// shell): optional leading semantic controls stay outside the inset, the rail
+// is recolored, and content backgrounds are normalized to the prompt surface.
+// A blank input line becomes a fully painted body row, which is how the shell
+// gets its background padding rows above and below.
+export function renderRailedBlockLines(
+  lines: string[],
+  width: number,
+  theme: PromptShellTheme,
+  inset: number,
+  railColor: string,
+  padding: PromptBlockPadding = BASH_BLOCK_PADDING,
+): string[] {
+  const blockWidth = width - inset * 2;
+  if (inset === 0 || blockWidth <= visibleWidth(PROMPT_RAIL)) {
+    return lines.map((line) => fitLine(line, width));
+  }
+  const bodyWidth = blockWidth - visibleWidth(PROMPT_RAIL);
+  const margin = " ".repeat(inset);
+  const leftPad = " ".repeat(padding.left);
+  const rightPad = " ".repeat(padding.right);
+  const contentWidth = Math.max(1, bodyWidth - padding.left - padding.right);
+  const surfaceBg = promptSurfaceBg(theme);
+  return lines.map((line) => {
+    const { controls, content } = splitLeadingSemanticControls(line);
+    const recolored = replaceBackground(content, surfaceBg);
+    const rail = theme.fg(railColor, PROMPT_RAIL);
+    const body = paintBackground(
+      `${leftPad}${fitLine(recolored, contentWidth)}${rightPad}`,
+      bodyWidth,
+      surfaceBg,
+    );
+    return `${controls}${margin}${rail}${body}${margin}`;
+  });
+}

package/src/question-block.ts

@@ -0,0 +1,328 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import {
+  SUBMITTED_PROMPT_PADDING,
+  promptBlockContentWidth,
+  promptBlockInset,
+  renderRailedBlockLines,
+  type PromptShellTheme,
+} from "./prompt-shell.ts";
+import { sanitizeInline } from "./sanitize.ts";
+
+// An asked question is a user-input moment inside the transcript, not an
+// execution row, so it takes the submitted-prompt shell instead of the
+// tool-call rail: the questions read as quoted prose and the answers as the
+// user's own text. The data comes entirely from what Pi already hands the
+// tool row — `args.questions` and `result.details.answers` — so no coupling to
+// any particular question-tool implementation is needed.
+
+type QuestionTheme = PromptShellTheme & {
+  fg(color: string, text: string): string;
+  italic?(text: string): string;
+};
+
+type QuestionRow = {
+  toolName?: string;
+  args?: unknown;
+  isPartial?: boolean;
+  result?: {
+    isError?: boolean;
+    details?: Record<string, unknown>;
+  };
+};
+
+type AnswerEntry = {
+  question: string;
+  questionIndex?: number | undefined;
+  kind?: string | undefined;
+  answer?: string | null | undefined;
+  selected?: string[] | undefined;
+};
+
+type QuestionLine =
+  | { kind: "question"; text: string }
+  | { kind: "answer"; text: string }
+  | { kind: "status"; text: string; tone: "muted" | "warning" };
+
+// rpiv's canonical decline text, reused verbatim so the transcript says what
+// the model was told.
+const DECLINE_TEXT = "User declined to answer questions";
+const AWAITING_TEXT = "awaiting your answer…";
+const NO_ANSWER_TEXT = "(no answer)";
+const QUESTION_PREFIX = "> ";
+const ANSWER_PREFIX = "User: ";
+
+// Question tools keep the ask-tool vocabulary in their name even when they
+// invent their own result shape. The result-shape check is the primary signal;
+// this pattern is the fallback for calls that never reached an answer.
+const QUESTION_TOOL_NAME_RE =
+  /(^|_)(ask_?user_?question|ask_?user|user_?question|questionnaire)($|_)/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeToolName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+function isQuestionToolName(name: string | undefined): boolean {
+  if (!name) return false;
+  return QUESTION_TOOL_NAME_RE.test(normalizeToolName(name));
+}
+
+// The rpiv result contract: `details.answers` is always an array of entries
+// carrying the question text, and each entry's answer arrives as `answer`
+// (option label or typed text) or `selected` (multi-select labels). Any
+// deviation fails the shape check so an unrelated tool is never reshaped.
+function parseAnswerEntries(details: unknown): AnswerEntry[] | undefined {
+  if (!isRecord(details)) return undefined;
+  const raw = details.answers;
+  if (!Array.isArray(raw)) return undefined;
+  const entries: AnswerEntry[] = [];
+  for (const item of raw) {
+    if (!isRecord(item) || typeof item.question !== "string") return undefined;
+    const answer = item.answer;
+    if (answer !== undefined && answer !== null && typeof answer !== "string") {
+      return undefined;
+    }
+    const selected = item.selected;
+    if (
+      selected !== undefined &&
+      !(
+        Array.isArray(selected) &&
+        selected.every((label) => typeof label === "string")
+      )
+    ) {
+      return undefined;
+    }
+    entries.push({
+      question: item.question,
+      questionIndex:
+        typeof item.questionIndex === "number" ? item.questionIndex : undefined,
+      kind: typeof item.kind === "string" ? item.kind : undefined,
+      answer,
+      selected: selected as string[] | undefined,
+    });
+  }
+  return entries;
+}
+
+function hasQuestionDetails(details: unknown): boolean {
+  const entries = parseAnswerEntries(details);
+  if (entries === undefined) return false;
+  if (entries.length > 0) return true;
+  if (!isRecord(details)) return false;
+  // An empty `answers` array only means a questionnaire when the details also
+  // carry the outcome that emptied it: a decline, or a validation failure.
+  return details.cancelled === true || typeof details.error === "string";
+}
+
+function parseAskedQuestions(args: unknown): string[] | undefined {
+  if (!isRecord(args) || !Array.isArray(args.questions)) return undefined;
+  const questions: string[] = [];
+  for (const item of args.questions) {
+    if (!isRecord(item) || typeof item.question !== "string") return undefined;
+    questions.push(item.question);
+  }
+  return questions.length > 0 ? questions : undefined;
+}
+
+function answerText(entry: AnswerEntry | undefined): string | undefined {
+  if (!entry) return undefined;
+  if (entry.kind === "multi" || entry.selected !== undefined) {
+    return entry.selected && entry.selected.length > 0
+      ? entry.selected.join(", ")
+      : undefined;
+  }
+  return entry.answer && entry.answer.length > 0 ? entry.answer : undefined;
+}
+
+function entryForIndex(
+  entries: AnswerEntry[],
+  index: number,
+  questionCount: number,
+): AnswerEntry | undefined {
+  const indexed = entries.find((entry) => entry.questionIndex === index);
+  if (indexed) return indexed;
+  // Entries without a `questionIndex` still arrive in ask order.
+  return entries.some((entry) => entry.questionIndex !== undefined) ||
+    entries.length !== questionCount
+    ? undefined
+    : entries[index];
+}
+
+function questionLines(
+  row: QuestionRow,
+  details: unknown,
+): QuestionLine[] | undefined {
+  const entries = parseAnswerEntries(details) ?? [];
+  const asked = parseAskedQuestions(row.args);
+  const pairs: Array<{ question: string; answer: string | undefined }> = [];
+  if (asked) {
+    asked.forEach((question, index) => {
+      const entry = entryForIndex(entries, index, asked.length);
+      pairs.push({ question, answer: answerText(entry) });
+    });
+  } else {
+    for (const entry of entries) {
+      pairs.push({ question: entry.question, answer: answerText(entry) });
+    }
+  }
+  if (pairs.length === 0) return undefined;
+
+  const lines: QuestionLine[] = [];
+  const questions = pairs.map(
+    (pair): QuestionLine => ({ kind: "question", text: pair.question }),
+  );
+  if (row.isPartial === true) {
+    return [
+      ...questions,
+      { kind: "status", text: AWAITING_TEXT, tone: "warning" },
+    ];
+  }
+  if (
+    isRecord(details) &&
+    details.cancelled === true &&
+    pairs.every((pair) => pair.answer === undefined)
+  ) {
+    return [
+      ...questions,
+      { kind: "status", text: DECLINE_TEXT, tone: "muted" },
+    ];
+  }
+  for (const pair of pairs) {
+    lines.push({ kind: "question", text: pair.question });
+    lines.push({ kind: "answer", text: pair.answer ?? NO_ANSWER_TEXT });
+  }
+  return lines;
+}
+
+function fg(theme: QuestionTheme, token: string, text: string): string {
+  if (text === "") return "";
+  try {
+    return theme.fg(token, text);
+  } catch {
+    return text;
+  }
+}
+
+// The question is the model's text read inside a user-input shell, so it takes
+// the quotation's italics; the answer is the user's own words and stays upright.
+// A theme without italics simply renders the question plainly.
+function italics(theme: QuestionTheme, text: string): string {
+  if (text === "" || typeof theme.italic !== "function") return text;
+  try {
+    return theme.italic(text);
+  } catch {
+    return text;
+  }
+}
+
+// Plain-text word wrap with a hanging indent, so a wrapped question stays
+// visually attached to its `> ` prefix. Wrapping before styling keeps the
+// width math exact and lets the shell's own fit pass stay a no-op.
+function wrapPlain(text: string, width: number): string[] {
+  const max = Math.max(1, width);
+  const words = text.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+  if (words.length === 0) return [""];
+
+  const lines: string[] = [];
+  let current = "";
+  const push = (word: string) => {
+    const candidate = current === "" ? word : `${current} ${word}`;
+    if (visibleWidth(candidate) <= max) {
+      current = candidate;
+      return;
+    }
+    if (current !== "") lines.push(current);
+    // A single token wider than the line is hard-split rather than truncated.
+    let rest = word;
+    while (visibleWidth(rest) > max) {
+      let cut = rest.length;
+      while (cut > 1 && visibleWidth(rest.slice(0, cut)) > max) cut--;
+      lines.push(rest.slice(0, cut));
+      rest = rest.slice(cut);
+    }
+    current = rest;
+  };
+  for (const word of words) push(word);
+  if (current !== "") lines.push(current);
+  return lines;
+}
+
+function styleLine(
+  line: QuestionLine,
+  width: number,
+  theme: QuestionTheme,
+): string[] {
+  const prefix =
+    line.kind === "question"
+      ? QUESTION_PREFIX
+      : line.kind === "answer"
+        ? ANSWER_PREFIX
+        : "";
+  const prefixToken = line.kind === "question" ? "borderAccent" : "muted";
+  const textToken =
+    line.kind === "question"
+      ? "text"
+      : line.kind === "answer"
+        ? "userMessageText"
+        : line.tone;
+  const hang = " ".repeat(visibleWidth(prefix));
+  const body = wrapPlain(line.text, Math.max(1, width - visibleWidth(prefix)));
+  return body.map(
+    (piece, index) =>
+      fg(theme, prefixToken, index === 0 ? prefix : hang) +
+      (line.kind === "question"
+        ? italics(theme, fg(theme, textToken, piece))
+        : fg(theme, textToken, piece)),
+  );
+}
+
+/**
+ * True when the row should read as an asked question rather than an execution
+ * row. Shape first, so another author's question tool works unedited; the tool
+ * name is the fallback for calls that failed before answering.
+ */
+export function isQuestionToolCall(row: QuestionRow): boolean {
+  if (hasQuestionDetails(row.result?.details)) return true;
+  return isQuestionToolName(row.toolName);
+}
+
+/**
+ * Renders the question/answer block in the submitted-prompt shell, or
+ * `undefined` when the row should keep the generic collapsed presentation.
+ * A failed questionnaire is one such case: its details carry an error code
+ * rather than a state worth a block, and the generic failure row already
+ * reports it in the error tone.
+ */
+export function renderQuestionBlock(
+  row: QuestionRow,
+  width: number,
+  theme: QuestionTheme,
+): string[] | undefined {
+  const details = row.result?.details;
+  if (!isQuestionToolCall(row)) return undefined;
+  if (isRecord(details) && typeof details.error === "string") return undefined;
+
+  const lines = questionLines(row, details);
+  if (!lines) return undefined;
+
+  const inset = promptBlockInset(width);
+  const padding = SUBMITTED_PROMPT_PADDING;
+  const contentWidth = promptBlockContentWidth(width, inset, padding);
+  const styled = lines.flatMap((line) => styleLine(line, contentWidth, theme));
+  // The blank rows top and bottom are the shell's background padding, matching
+  // a submitted user message; they become fully painted body rows.
+  return renderRailedBlockLines(
+    ["", ...styled, ""],
+    width,
+    theme,
+    inset,
+    "borderAccent",
+    padding,
+  );
+}

package/src/sanitize.ts

@@ -0,0 +1,20 @@
+// Command output and model-supplied text can carry cursor-moving control
+// bytes, raw terminal sequences, line feeds, and tabs. Collapsed rows and
+// prompt blocks are width-fitted single lines, so scraped text is stripped of
+// display sequences and all C0 controls before it can reach them; otherwise
+// control bytes could split or overwrite a row.
+
+const INLINE_CONTROL_RE = /[\x00-\x1f\x7f]/g;
+
+// OSC first: the two-byte alternative would otherwise consume `\x1b]` and
+// leave the hyperlink payload behind as visible text. OSC sequences (OSC 8
+// hyperlinks, titles) end at their first BEL/ST terminator; a payload match
+// must stop there too, because the visible text sits BETWEEN two OSC
+// sequences — Pi wraps read paths as `ESC]8;;url ESC\ <path> ESC]8;; ESC\`,
+// and a greedy `[^\x07]*` would swallow that path along with the sequences.
+const DISPLAY_ANSI_RE =
+  /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)|\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+
+export function sanitizeInline(text: string): string {
+  return text.replace(DISPLAY_ANSI_RE, "").replace(INLINE_CONTROL_RE, " ");
+}