pi-jar 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-jar",
+  "version": "0.1.0",
+  "description": "A warm, role-aware Pi terminal workspace with animated UI, plan and goal workflows, tasks, change review, model roles, background shells and subagents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ygrip/pi-jar.git"
+  },
+  "homepage": "https://github.com/ygrip/pi-jar#readme",
+  "bugs": {
+    "url": "https://github.com/ygrip/pi-jar/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-theme",
+    "pi-extension",
+    "terminal",
+    "multi-agent",
+    "plan-mode",
+    "goal",
+    "model-roles"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "themes",
+    "docs/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "themes": [
+      "./themes"
+    ],
+    "image": "https://raw.githubusercontent.com/ygrip/pi-jar/main/docs/assets/pi-jar-demo.gif"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "themes:build": "node --experimental-strip-types scripts/build-accents.mjs",
+    "test": "node --experimental-strip-types --test tests/*.test.ts"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1",
+    "typebox": "^1.3.34",
+    "typescript": "5.9.2"
+  }
+}

package/src/accent.ts

@@ -0,0 +1,36 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Sharpened pi-jar dark preset values; keep these in sync with bundled theme vars. */
+export const ACCENTS = {
+  gray: { accent: "#D0D9E5", selected: "#252B35" },
+  pink: { accent: "#FF88C6", selected: "#3B1D2D" },
+  teal: { accent: "#45DDD1", selected: "#123433" },
+  azure: { accent: "#75BCFF", selected: "#132A41" },
+  violet: { accent: "#BCA0FF", selected: "#2C2350" },
+  amber: { accent: "#F7B955", selected: "#3A2B0F" }
+} as const;
+
+export type AccentName = keyof typeof ACCENTS;
+export const ACCENT_NAMES = Object.keys(ACCENTS) as AccentName[];
+
+/** A loaded extension is not proof that Pi also discovered its package themes. */
+export function loadedAccents(ctx: ExtensionContext): string[] {
+  if (!ctx.hasUI || ctx.mode !== "tui") return [];
+  try {
+    return ["default", ...ACCENT_NAMES].filter((name) =>
+      Boolean(ctx.ui.getTheme(name === "default" ? "pi-jar-dark" : `pi-jar-dark-${name}`)));
+  } catch { return []; }
+}
+
+/** Only switch among complete bundled themes; never mutate semantic status colors. */
+export function selectAccent(ctx: ExtensionContext, value: string): boolean {
+  if (!ctx.hasUI || ctx.mode !== "tui") return false;
+  const themeName = value === "default" ? "pi-jar-dark"
+    : Object.hasOwn(ACCENTS, value) ? `pi-jar-dark-${value}` : undefined;
+  if (!themeName) return false;
+  try {
+    if (!ctx.ui.getTheme(themeName)) return false;
+    // Switching by name persists Pi's theme setting; passing a Theme instance does not.
+    return ctx.ui.setTheme(themeName).success;
+  } catch { return false; }
+}

package/src/advisor.ts

@@ -0,0 +1,194 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { ModelRoleManager } from "./model-roles.ts";
+import { askRole, type SideUsage } from "./side-model.ts";
+import { ROLE_PREFIX } from "./status.ts";
+
+export const ADVISOR_TOOL = "jar_advisor";
+export const ADVISOR_MESSAGE = "pi-jar.advisor";
+const TRANSCRIPT_LIMIT = 24_000;
+const GIT_LIMIT = 4_000;
+/** Identical tool calls (same tool and input) within the recent window that count as a loop. */
+export const LOOP_REPEATS = 3;
+/** Consecutive failing tool results that count as stuck. */
+export const FAILURE_STREAK = 3;
+/** Automatic consultations allowed per user prompt. */
+export const GATES_PER_PROMPT = 2;
+const WINDOW = 8;
+
+export const ADVISOR_SYSTEM = [
+  "You are the advisor: a senior engineer giving a second opinion to a coding agent (the executor) mid-task.",
+  "You see a transcript excerpt and the repository state; you cannot run tools.",
+  "Be direct and specific. Lead with your verdict (proceed / revise / stop and ask the user), then the reasons,",
+  "then concrete next steps. Point out wrong assumptions, missed edge cases, simpler approaches and risks.",
+  "Keep it under 250 words. Do not restate the transcript."
+].join("\n");
+
+type Entry = { type: string; message?: { role?: string; content?: unknown; toolName?: string; isError?: boolean; customType?: string } };
+
+const textOf = (content: unknown): string => typeof content === "string" ? content
+  : Array.isArray(content) ? content.map((part: { type?: string; text?: string; name?: string; arguments?: unknown }) =>
+    part.type === "text" ? part.text ?? "" : part.type === "toolCall" ? `[tool ${part.name} ${JSON.stringify(part.arguments ?? {}).slice(0, 300)}]` : "").filter(Boolean).join("\n")
+    : "";
+
+/** The most recent conversation, newest last, capped to `limit` characters. */
+export function transcript(entries: readonly Entry[], limit = TRANSCRIPT_LIMIT): string {
+  const parts: string[] = [];
+  let size = 0;
+  for (let index = entries.length - 1; index >= 0 && size < limit; index--) {
+    const message = entries[index]!.type === "message" ? entries[index]!.message : undefined;
+    if (!message?.role) continue;
+    let body = textOf(message.content).trim();
+    if (!body) continue;
+    if (message.role === "toolResult" && body.length > 1200) body = body.slice(0, 1200) + " …";
+    const label = message.role === "toolResult" ? `tool result (${message.toolName ?? "?"}${message.isError ? ", error" : ""})` : message.role;
+    const part = `### ${label}\n${body}`;
+    parts.unshift(part.slice(0, limit - size));
+    size += part.length;
+  }
+  return parts.join("\n\n");
+}
+
+export interface AdvisorRequest { question?: string; draft?: string; trigger?: string }
+
+export function advisorPrompt(request: AdvisorRequest, conversation: string, git: string): string {
+  return [
+    request.trigger ? `Automatic consultation: ${request.trigger}` : "",
+    request.question ? `Executor's question: ${request.question}` : "Executor asks for a general review of its current direction.",
+    request.draft ? `Executor's draft / candidate approach:\n${request.draft}` : "",
+    git ? `Repository state:\n${git}` : "",
+    `Recent conversation:\n${conversation || "(empty)"}`
+  ].filter(Boolean).join("\n\n");
+}
+
+/** Stable key for loop detection. */
+export const callKey = (tool: string, input: unknown) => tool + " " + JSON.stringify(input ?? {});
+
+/** Tracks repeated calls and failure streaks within one user prompt. */
+export class StuckDetector {
+  private recent: string[] = [];
+  private failures = 0;
+  private gates = 0;
+  reset(): void { this.recent = []; this.failures = 0; this.gates = 0; }
+  /** Returns a trigger description when this call completes a loop. */
+  call(key: string): string | undefined {
+    this.recent.push(key);
+    if (this.recent.length > WINDOW) this.recent.shift();
+    const count = this.recent.filter((item) => item === key).length;
+    if (count < LOOP_REPEATS || !this.take()) return undefined;
+    this.recent = [];
+    return `the executor has made the same tool call ${count} times: ${key.slice(0, 200)}`;
+  }
+  /** Returns a trigger description when a failure streak is reached. */
+  result(isError: boolean, tool: string): string | undefined {
+    this.failures = isError ? this.failures + 1 : 0;
+    if (this.failures < FAILURE_STREAK || !this.take()) return undefined;
+    this.failures = 0;
+    return `${FAILURE_STREAK} tool calls in a row failed (last: ${tool})`;
+  }
+  private take(): boolean { if (this.gates >= GATES_PER_PROMPT) return false; this.gates++; return true; }
+}
+
+export interface AdvisorOptions { enabled: () => boolean; gates: () => boolean; usage: SideUsage }
+
+/** First-class advisor: the jar_advisor tool, /advisor, and automatic gates for loops and failure streaks. */
+export function registerAdvisor(pi: ExtensionAPI, roles: ModelRoleManager, options: AdvisorOptions) {
+  const stuck = new StuckDetector();
+  let busy = 0;
+
+  const status = (ctx: ExtensionContext, task?: string) => {
+    if (!ctx.hasUI) return;
+    try {
+      ctx.ui.setStatus(ROLE_PREFIX + "advisor", task ? JSON.stringify({ name: "Advisor", label: "advisor", state: "working", task, expiresAt: Date.now() + 30_000 }) : undefined);
+    } catch { /* status is decoration */ }
+  };
+
+  const gitState = async (ctx: ExtensionContext): Promise<string> => {
+    try {
+      const [st, stat] = await Promise.all([
+        pi.exec("git", ["status", "--short", "--branch"], { cwd: ctx.cwd, timeout: 5_000 }),
+        pi.exec("git", ["diff", "--stat", "HEAD"], { cwd: ctx.cwd, timeout: 5_000 })
+      ]);
+      if (st.code !== 0) return "";
+      return (st.stdout.trim() + (stat.code === 0 && stat.stdout.trim() ? "\n" + stat.stdout.trim() : "")).slice(0, GIT_LIMIT);
+    } catch { return ""; } // repository state is optional context; not a git repo or git missing
+  };
+
+  const consult = async (ctx: ExtensionContext, request: AdvisorRequest, signal?: AbortSignal) => {
+    busy++;
+    status(ctx, request.trigger ?? request.question ?? "reviewing the current direction");
+    try {
+      const conversation = transcript(ctx.sessionManager.getBranch() as readonly Entry[]);
+      return await askRole(ctx, roles, options.usage, "advisor", ADVISOR_SYSTEM, advisorPrompt(request, conversation, await gitState(ctx)), signal);
+    } finally { if (--busy === 0) status(ctx); }
+  };
+
+  const Parameters = Type.Object({
+    question: Type.Optional(Type.String({ description: "A focused question or decision for the advisor" })),
+    draft: Type.Optional(Type.String({ description: "Your candidate plan, answer or fix for the advisor to critique" }))
+  });
+
+  if (typeof (pi as ExtensionAPI & { registerTool?: unknown }).registerTool === "function") pi.registerTool({
+    name: ADVISOR_TOOL,
+    label: "advisor",
+    description: "Ask the advisor (a stronger reviewer model with a fresh view of this conversation and the repo state) for a second opinion. Returns its advice.",
+    promptSnippet: "Use jar_advisor for a second opinion on consequential decisions, when stuck, or before declaring hard work done.",
+    promptGuidelines: [
+      "Call jar_advisor before committing to a risky or hard-to-reverse approach, after two failed attempts at the same problem, and before declaring a complex task complete.",
+      "Form your own candidate first and pass it as draft; ask a specific question. Do not call it for routine steps."
+    ],
+    parameters: Parameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      if (!options.enabled()) throw new Error("the advisor is turned off in /jar settings");
+      const answer = await consult(ctx, { ...(params.question ? { question: params.question } : {}), ...(params.draft ? { draft: params.draft } : {}) }, signal);
+      return { content: [{ type: "text", text: answer.text }], details: { model: answer.model } };
+    }
+  });
+
+  const deliver = (ctx: ExtensionContext, heading: string, text: string) => {
+    pi.sendMessage({ customType: ADVISOR_MESSAGE, content: `${heading}\n\n${text}`, display: true },
+      ctx.isIdle() ? { deliverAs: "nextTurn" } : { deliverAs: "steer" });
+  };
+
+  pi.registerCommand("advisor", {
+    description: "Ask the advisor for a second opinion on the current work: /advisor [focus]",
+    handler: async (args, ctx) => {
+      if (!options.enabled()) { ctx.ui.notify("The advisor is off; turn it on in /jar settings → Pi", "warning"); return; }
+      const focus = args.trim();
+      ctx.ui.notify("Consulting the advisor…", "info");
+      try {
+        const answer = await consult(ctx, focus ? { question: focus } : {});
+        deliver(ctx, `◆ Advisor · ${answer.model}${focus ? " · " + focus : ""}`, answer.text);
+      } catch (error) { ctx.ui.notify("Advisor failed: " + (error instanceof Error ? error.message : String(error)), "error"); }
+    }
+  });
+
+  pi.on("input", (event) => { if (event.source === "interactive") stuck.reset(); });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === ADVISOR_TOOL || !options.enabled() || !options.gates()) return;
+    const trigger = stuck.call(callKey(event.toolName, event.input));
+    if (!trigger) return;
+    try {
+      const answer = await consult(ctx, { trigger }, ctx.signal);
+      return { block: true, reason: `Loop detected: ${trigger}. The advisor (${answer.model}) reviewed the situation:\n\n${answer.text}` };
+    } catch (error) {
+      ctx.ui.notify("Advisor gate failed: " + (error instanceof Error ? error.message : String(error)), "warning");
+      return undefined;
+    }
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.toolName === ADVISOR_TOOL || !options.enabled() || !options.gates()) return;
+    const trigger = stuck.result(event.isError, event.toolName);
+    if (!trigger) return;
+    try {
+      const answer = await consult(ctx, { trigger }, ctx.signal);
+      deliver(ctx, `◆ Advisor · ${answer.model} · ${trigger}`, answer.text);
+    } catch (error) {
+      ctx.ui.notify("Advisor gate failed: " + (error instanceof Error ? error.message : String(error)), "warning");
+    }
+  });
+
+  return { consult, stuck };
+}

package/src/animations.ts

@@ -0,0 +1,23 @@
+import type { RoleState } from "./roles.ts";
+
+const FRAMES: Record<RoleState, readonly string[]> = {
+  idle: ["◇"],
+  thinking: ["◈", "◆"],
+  working: ["◐", "◓", "◑", "◒"],
+  waiting: ["◇"],
+  reviewing: ["◔", "◑", "◕", "●"],
+  done: ["✓"],
+  failed: ["×"]
+};
+
+export function roleFrame(state: RoleState, frame: number, animations = true): string {
+  const frames = FRAMES[state];
+  if (!animations || frames.length === 1) {
+    return frames[0] ?? "◇";
+  }
+  return frames[frame % frames.length] ?? frames[0] ?? "◇";
+}
+
+export const WORKING_FRAMES = ["◇", "◆", "◇", "◈"] as const;
+/** Pixel-fire tick for the welcome flame; frozen when motion is disabled. */
+export const WELCOME_INTERVAL_MS = 90;

package/src/ask-tool.ts

@@ -0,0 +1,185 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { cleanText } from "./status.ts";
+
+const OptionSchema = Type.Object({
+  label: Type.String({ maxLength: 160 }),
+  description: Type.Optional(Type.String({ maxLength: 320 }))
+});
+const QuestionSchema = Type.Object({
+  id: Type.Optional(Type.String({ maxLength: 64 })),
+  header: Type.Optional(Type.String({ maxLength: 48 })),
+  question: Type.String({ maxLength: 1000 }),
+  multi: Type.Optional(Type.Boolean({ description: "Show checkboxes so the user can select several options." })),
+  allowCustom: Type.Optional(Type.Boolean()),
+  options: Type.Optional(Type.Array(OptionSchema, { maxItems: 12 }))
+});
+const Parameters = Type.Object({
+  questions: Type.Array(QuestionSchema, { minItems: 1, maxItems: 8 })
+});
+
+type AskOption = { label: string; description?: string };
+type AskQuestion = { id?: string; header?: string; question: string; multi?: boolean; allowCustom?: boolean; options?: AskOption[] };
+type AskAnswer = { id: string; answer?: string; selected?: string[]; chat?: string; cancelled?: boolean };
+type PickResult = { kind: "answer"; selected: string[] } | { kind: "custom" } | { kind: "chat" } | { kind: "cancel" };
+
+const fit = (line: string, width: number) => truncateToWidth(line, Math.max(0, width));
+
+async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index: number, total: number): Promise<PickResult> {
+  const options = (question.options ?? []).map((option) => ({
+    label: cleanText(option.label, 120),
+    description: option.description ? cleanText(option.description, 240) : undefined
+  })).filter((option) => !!option.label);
+  if (!ctx.hasUI || ctx.mode !== "tui") return { kind: "cancel" };
+  return ctx.ui.custom<PickResult>((tui, theme, _keys, done) => {
+    const multi = !!question.multi;
+    const allowCustom = question.allowCustom !== false;
+    const actions = [
+      ...(allowCustom ? [{ kind: "custom" as const, label: "Type your own answer", icon: "✎" }] : []),
+      { kind: "chat" as const, label: "Chat about this", icon: "◇" },
+      ...(multi ? [{ kind: "submit" as const, label: "Continue with selection", icon: "✓" }] : [])
+    ];
+    let selected = 0;
+    const checked = new Set<number>();
+    let hitRows: number[] = [];
+    let scroll = 0;
+    let lastSelected = selected;
+    const totalRows = () => options.length + actions.length;
+    const choose = () => {
+      if (selected < options.length) {
+        if (multi) {
+          if (checked.has(selected)) checked.delete(selected); else checked.add(selected);
+          return;
+        }
+        return done({ kind: "answer", selected: [options[selected]!.label] });
+      }
+      const action = actions[selected - options.length];
+      if (!action) return;
+      if (action.kind === "custom") return done({ kind: "custom" });
+      if (action.kind === "chat") return done({ kind: "chat" });
+      return done({ kind: "answer", selected: [...checked].sort((a, b) => a - b).map((at) => options[at]!.label) });
+    };
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        if (matchesKey(data, Key.escape)) return done({ kind: "cancel" });
+        if (matchesKey(data, Key.up)) selected = (selected + totalRows() - 1) % totalRows();
+        else if (matchesKey(data, Key.down)) selected = (selected + 1) % totalRows();
+        else if (multi && data === "a") {
+          // Select all, or clear when everything is already checked.
+          if (checked.size === options.length) checked.clear(); else options.forEach((_option, at) => checked.add(at));
+        } else if (/^[1-9]$/.test(data)) {
+          const at = Number(data) - 1;
+          if (at < options.length) { selected = at; choose(); }
+        } else if (matchesKey(data, Key.enter) || data === " ") choose();
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type === "wheel" && event.wheelDelta) {
+          scroll = Math.max(0, scroll + Math.sign(event.wheelDelta) * 3);
+          tui.requestRender(); return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left") return;
+        const index = hitRows[event.y];
+        if (index === undefined) return;
+        selected = index;
+        choose();
+        tui.requestRender();
+        return { handled: true };
+      },
+      render(width: number): string[] {
+        hitRows = [];
+        const inner = Math.max(1, width - 4);
+        const badge = "◆ QUESTION " + String(index + 1) + "/" + String(total) + (multi ? " · MULTI SELECT" : "");
+        const title = question.header ? cleanText(question.header, 48) : "Clarification";
+        const lines: string[] = [
+          fit(theme.fg("accent", "╭─ " + badge + " ─"), width),
+          fit(theme.fg("muted", "│ " + title), width)
+        ];
+        const content: { line: string; target?: number }[] = [];
+        for (const row of wrapTextWithAnsi(cleanText(question.question, 900), inner)) content.push({ line: fit("│ " + row, width) });
+        content.push({ line: fit(theme.fg("dim", "├" + "─".repeat(Math.max(0, width - 1))), width) });
+        options.forEach((option, at) => {
+          const active = selected === at;
+          const marker = multi ? (checked.has(at) ? "☑" : "☐") : (active ? "●" : "○");
+          const number = String(at + 1).padStart(2, " ") + ".";
+          content.push({ target: at, line: fit(theme.fg(active ? "accent" : "muted", "│ " + (active ? "❯ " : "  ") + marker + " " + number + " " + option.label), width) });
+          if (option.description) content.push({ target: at, line: fit(theme.fg("dim", "│      " + option.description), width) });
+        });
+        actions.forEach((action, at) => {
+          const row = options.length + at;
+          const active = row === selected;
+          const label = action.kind === "submit" ? `Continue with ${checked.size ? checked.size + " selected" : "none selected"}` : action.label;
+          const chip = "[ " + action.icon + " " + label + " ]";
+          content.push({ target: row, line: fit(theme.fg(active ? "accent" : "dim", "│ " + (active ? "❯ " : "  ") + chip), width) });
+        });
+        const page = Math.max(3, Math.min(16, (process.stdout.rows ?? 24) - 5));
+        if (selected !== lastSelected) {
+          const target = content.findIndex((row) => row.target === selected);
+          if (target < scroll) scroll = target;
+          else if (target >= scroll + page) scroll = target - page + 1;
+          lastSelected = selected;
+        }
+        scroll = Math.max(0, Math.min(scroll, Math.max(0, content.length - page)));
+        content.slice(scroll, scroll + page).forEach((row) => {
+          if (row.target !== undefined) hitRows[lines.length] = row.target;
+          lines.push(row.line);
+        });
+        const hint = multi ? `${checked.size}/${options.length} checked · ↑↓ move · Space/Enter toggle · a all · Esc cancel` : "↑↓ move · Enter choose · wheel scroll · Esc cancel";
+        lines.push(fit(theme.fg("dim", `╰─ ${scroll + 1}–${Math.min(scroll + page, content.length)}/${content.length} · ${hint}`), width));
+        return lines.map((line) => visibleWidth(line) <= width ? line : fit(line, width));
+      }
+    };
+  });
+}
+
+async function askOne(ctx: ExtensionContext, question: AskQuestion, index: number, total: number): Promise<AskAnswer> {
+  const id = cleanText(question.id ?? "q" + String(index + 1), 64) || "q" + String(index + 1);
+  const picked = await pickQuestion(ctx, question, index, total);
+  if (!picked || picked.kind === "cancel") return { id, cancelled: true };
+  if (picked.kind === "custom") {
+    const text = await ctx.ui.editor("✎ Your answer · " + cleanText(question.header ?? "Question", 48), "");
+    return text?.trim() ? { id, answer: text.trim() } : { id, cancelled: true };
+  }
+  if (picked.kind === "chat") {
+    const text = await ctx.ui.editor("◇ Chat about this · " + cleanText(question.header ?? "Question", 48), "I want to discuss this before I answer. ");
+    return text?.trim() ? { id, chat: text.trim() } : { id, cancelled: true };
+  }
+  return question.multi ? { id, selected: picked.selected } : { id, answer: picked.selected[0] ?? "" };
+}
+
+export function registerAskTool(pi: ExtensionAPI): void {
+  if (typeof (pi as ExtensionAPI & { registerTool?: unknown }).registerTool !== "function") return;
+  pi.registerTool({
+    name: "jar_ask",
+    label: "ask user",
+    description: "Ask the user one or more structured clarification questions with described choices, multi-select checkboxes, custom text, or a chat-about-this path.",
+    promptSnippet: "Use jar_ask when a decision or clarification is needed; prefer concise options with useful descriptions.",
+    promptGuidelines: [
+      "Use jar_ask instead of writing ad-hoc numbered questions when the user needs to choose between options or provide clarification.",
+      "Use multi=true only when several answers may be selected. Include short descriptions when labels alone are ambiguous.",
+      "If a jar_ask result contains chat, respond to that discussion before asking for a final choice again."
+    ],
+    parameters: Parameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const questions = params.questions as AskQuestion[];
+      if (!ctx.hasUI || ctx.mode !== "tui") {
+        return { content: [{ type: "text", text: "Structured questions require Pi's interactive TUI." }], details: { answers: [] } };
+      }
+      const answers: AskAnswer[] = [];
+      for (let index = 0; index < questions.length; index++) {
+        const answer = await askOne(ctx, questions[index]!, index, questions.length);
+        answers.push(answer);
+        if (answer.cancelled || answer.chat) break;
+      }
+      const summary = answers.map((answer) => {
+        if (answer.cancelled) return answer.id + ": cancelled";
+        if (answer.chat) return answer.id + ": CHAT: " + answer.chat;
+        if (answer.selected) return answer.id + ": " + (answer.selected.length ? answer.selected.join(", ") : "(none selected)");
+        return answer.id + ": " + (answer.answer ?? "");
+      }).join("\n");
+      return { content: [{ type: "text", text: summary || "No answers." }], details: { answers } };
+    }
+  });
+}

package/src/attachments.ts

@@ -0,0 +1,79 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, resolve } from "node:path";
+
+export interface ImageInfo { path: string; name: string; bytes: number; width?: number; height?: number; format: string }
+
+const IMAGE = /\.(png|jpe?g|gif|webp)$/i;
+const HEADER_BYTES = 64 * 1024;
+const cache = new Map<string, { mtime: number; info: ImageInfo }>();
+
+/** Width × height from an image header (PNG, GIF, JPEG, WebP), or undefined. */
+export function imageSize(header: Buffer): { width: number; height: number; format: string } | undefined {
+  if (header.length >= 24 && header.readUInt32BE(0) === 0x89504e47 && header.toString("ascii", 12, 16) === "IHDR") {
+    return { width: header.readUInt32BE(16), height: header.readUInt32BE(20), format: "PNG" };
+  }
+  if (header.length >= 10 && header.toString("ascii", 0, 3) === "GIF") return { width: header.readUInt16LE(6), height: header.readUInt16LE(8), format: "GIF" };
+  if (header.length >= 30 && header.toString("ascii", 0, 4) === "RIFF" && header.toString("ascii", 8, 12) === "WEBP") {
+    const chunk = header.toString("ascii", 12, 16);
+    if (chunk === "VP8X") return { width: 1 + header.readUIntLE(24, 3), height: 1 + header.readUIntLE(27, 3), format: "WebP" };
+    if (chunk === "VP8 ") return { width: header.readUInt16LE(26) & 0x3fff, height: header.readUInt16LE(28) & 0x3fff, format: "WebP" };
+    if (chunk === "VP8L") {
+      const bits = header.readUInt32LE(21);
+      return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1, format: "WebP" };
+    }
+  }
+  if (header.length >= 4 && header[0] === 0xff && header[1] === 0xd8) {
+    let at = 2;
+    while (at + 9 < header.length) {
+      if (header[at] !== 0xff) { at++; continue; }
+      const marker = header[at + 1]!;
+      // Start-of-frame markers carry the dimensions (C4, C8 and CC are not frames).
+      if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+        return { width: header.readUInt16BE(at + 7), height: header.readUInt16BE(at + 5), format: "JPEG" };
+      }
+      if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { at += 2; continue; }
+      at += 2 + header.readUInt16BE(at + 2);
+    }
+  }
+  return undefined;
+}
+
+/** Image file paths mentioned in a draft (Pi pastes clipboard images as temp file paths). */
+export function imagePaths(text: string, cwd = process.cwd()): string[] {
+  const found = new Set<string>();
+  const tokens = text.match(/"[^"\n]+"|'[^'\n]+'|(?:\\ |[^\s"'])+/g) ?? [];
+  for (const raw of tokens) {
+    const token = raw.replace(/^["']|["']$/g, "").replace(/\\ /g, " ").replace(/^@/, "");
+    if (!IMAGE.test(token)) continue;
+    const path = token.startsWith("~/") ? resolve(homedir(), token.slice(2)) : isAbsolute(token) ? token : resolve(cwd, token);
+    if (existsSync(path)) found.add(path);
+  }
+  return [...found].slice(0, 8);
+}
+
+export function imageInfo(path: string): ImageInfo | undefined {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile()) return undefined;
+    const cached = cache.get(path);
+    if (cached && cached.mtime === stat.mtimeMs) return cached.info;
+    const header = Buffer.alloc(Math.min(HEADER_BYTES, stat.size));
+    const fd = openSync(path, "r");
+    try { readSync(fd, header, 0, header.length, 0); } finally { closeSync(fd); }
+    const size = imageSize(header);
+    const info: ImageInfo = { path, name: basename(path), bytes: stat.size, format: size?.format ?? (path.split(".").pop() ?? "").toUpperCase(),
+      ...(size ? { width: size.width, height: size.height } : {}) };
+    cache.set(path, { mtime: stat.mtimeMs, info });
+    if (cache.size > 64) cache.delete(cache.keys().next().value!);
+    return info;
+  } catch { return undefined; }
+}
+
+export const formatBytes = (bytes: number) => bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${Math.round(bytes / 1024)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+
+/** Short chip text: "▣ shot.png · 1280×720 · 240 KB". Temp clipboard names are shortened. */
+export function imageChip(info: ImageInfo): string {
+  const name = /^pi-clipboard-/.test(info.name) ? `pasted ${info.format.toLowerCase()}` : info.name;
+  return `▣ ${name}${info.width ? ` · ${info.width}×${info.height}` : ""} · ${formatBytes(info.bytes)}`;
+}