pi-jar 0.1.0

package/src/settings-ui.ts

@@ -0,0 +1,154 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { FOOTER_FIELDS, type FooterField } from "./footer-settings.ts";
+import { GOAL_ROUND_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
+
+const LABELS: Record<FooterField, string> = {
+  model: "Model", effort: "Model effort", sessionName: "Session name", cwd: "Working directory",
+  context: "Context usage", memory: "Process RAM (RSS)", cost: "Session cost", quota: "Quota windows", roles: "Active roles",
+  extras: "Extension statuses", branch: "Git branch"
+};
+
+type Page = "appearance" | "footer" | "pi";
+const PAGES: Page[] = ["appearance", "footer", "pi"];
+
+/** Pi-level preferences pi-jar can toggle (written to Pi's own settings). */
+export interface PiPreferences {
+  get(): { fullscreen: boolean; copyOnSelect: boolean };
+  setFullscreen(enabled: boolean): void;
+  setCopyOnSelect(enabled: boolean): void;
+}
+
+/** A single settings screen, keyboard-accessible everywhere and clickable in Pi fullscreen mode. */
+export async function openJarSettings(
+  ctx: ExtensionContext,
+  current: () => JarVisualSettings,
+  update: (settings: JarVisualSettings) => void,
+  availableAccents: readonly string[],
+  pi?: PiPreferences
+): Promise<void> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return;
+  await ctx.ui.custom<void>((tui, theme, _keys, done) => {
+    let page: Page = "appearance";
+    let selected = 0;
+    let width = 64;
+    const accents: JarAccent[] = ["follow", ...availableAccents.filter((name): name is JarAccent =>
+      name === "default" || ["gray", "pink", "teal", "azure", "violet", "amber"].includes(name))];
+    const fields = () => page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 5 : 6;
+    const piError = (error: unknown) => ctx.ui.notify("Could not change Pi setting: " + (error as Error).message, "error");
+    const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - 9));
+    const firstVisible = () => Math.min(Math.max(0, selected - pageSize() + 1), Math.max(0, fields() - pageSize()));
+    const visibleCount = () => Math.min(pageSize(), fields());
+    const apply = (index: number) => {
+      const state = current();
+      if (page === "footer") {
+        const field = FOOTER_FIELDS[index];
+        if (field) update({ ...state, footer: { ...state.footer, [field]: !state.footer[field] } });
+      } else if (page === "pi") {
+        if (index === 0 && pi) { try { pi.setFullscreen(!pi.get().fullscreen); ctx.ui.notify("Pi TUI mode saved; restart Pi to apply", "info"); } catch (error) { piError(error); } }
+        else if (index === 1 && pi) { try { pi.setCopyOnSelect(!pi.get().copyOnSelect); } catch (error) { piError(error); } }
+        else if (index === 2) {
+          const at = GOAL_ROUND_CHOICES.indexOf(state.goalRounds as never);
+          update({ ...state, goalRounds: GOAL_ROUND_CHOICES[(at + 1) % GOAL_ROUND_CHOICES.length]! });
+        }
+        else if (index === 3) update({ ...state, advisor: !state.advisor });
+        else if (index === 4) update({ ...state, advisorGates: !state.advisorGates });
+      } else if (index === 0) {
+        const at = Math.max(0, accents.indexOf(state.accent));
+        update({ ...state, accent: accents[(at + 1) % accents.length]! });
+      } else if (index === 1) update({ ...state, animations: !state.animations });
+      else if (index === 2) update({ ...state, composer: !state.composer });
+      else if (index === 3) update({ ...state, mascot: !state.mascot });
+      else if (index === 4) update({ ...state, suggestions: !state.suggestions });
+      else if (index === 5) update({ ...state, ui: !state.ui });
+      tui.requestRender();
+    };
+    const row = (index: number, label: string, value: string, enabled: boolean) => {
+      const marker = selected === index ? theme.fg("accent", "❯") : " ";
+      const innerWidth = Math.max(0, width - 7);
+      const right = theme.fg(enabled ? "success" : "dim", value);
+      const room = Math.max(0, innerWidth - visibleWidth(right) - 1);
+      const left = truncateToWidth(label, room);
+      const body = marker + " " + left + " ".repeat(Math.max(1, innerWidth - visibleWidth(left) - visibleWidth(right))) + right;
+      return theme.fg("dim", "│  ") + truncateToWidth(body, Math.max(0, width - 5)) + theme.fg("dim", " │");
+    };
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        if (matchesKey(data, Key.escape) || data === "q") { done(); return; }
+        if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+          page = PAGES[(PAGES.indexOf(page) + 1) % PAGES.length]!;
+          selected = 0;
+        } else if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+          page = PAGES[(PAGES.indexOf(page) + PAGES.length - 1) % PAGES.length]!;
+          selected = 0;
+        } else if (matchesKey(data, Key.up)) selected = (selected + fields() - 1) % fields();
+        else if (matchesKey(data, Key.down)) selected = (selected + 1) % fields();
+        else if (data === " " || matchesKey(data, Key.enter)) apply(selected);
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type === "wheel" && event.wheelDelta) {
+          selected = Math.max(0, Math.min(fields() - 1, selected + Math.sign(event.wheelDelta)));
+          tui.requestRender(); return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left") return;
+        if (event.y === 0 && event.x >= width - 4) { done(); return { handled: true }; }
+        if (event.y === 1) {
+          if (event.x >= 2 && event.x < Math.min(width - 2, 19)) { page = "appearance"; selected = 0; }
+          else if (event.x >= 19 && event.x < Math.min(width - 2, 32)) { page = "footer"; selected = 0; }
+          else if (event.x >= 32 && event.x < width - 2) { page = "pi"; selected = 0; }
+          else return;
+          tui.requestRender(); return { handled: true, focus: true };
+        }
+        if (event.y >= 5 && event.y < 5 + visibleCount() && event.x >= 2 && event.x < width - 2) {
+          selected = firstVisible() + event.y - 5; apply(selected); return { handled: true, focus: true };
+        }
+        if (event.y === 5 + visibleCount() && event.x >= 2 && event.x < width - 2) { done(); return { handled: true }; }
+      },
+      render(available: number): string[] {
+        width = Math.max(8, available);
+        const state = current();
+        const fit = (text: string) => truncateToWidth(text, width);
+        const line = (text: string) => {
+          const inner = Math.max(0, width - 5);
+          const content = truncateToWidth(text, inner);
+          return fit(theme.fg("dim", "│  ") + content + " ".repeat(Math.max(0, inner - visibleWidth(content))) + theme.fg("dim", " │"));
+        };
+        const title = " pi-jar · settings ";
+        const top = theme.fg("accent", "╭─" + truncateToWidth(title, Math.max(0, width - 6))
+          + "─".repeat(Math.max(0, width - 4 - visibleWidth(title))) + "×╮");
+        const tabs = line(theme.fg(page === "appearance" ? "accent" : "muted", "[ Appearance ]")
+          + "   " + theme.fg(page === "footer" ? "accent" : "muted", "[ Footer ]")
+          + "   " + theme.fg(page === "pi" ? "accent" : "muted", "[ Pi ]"));
+        const prefs = pi?.get();
+        const divider = theme.fg("dim", "├" + "─".repeat(Math.max(0, width - 2)) + "┤");
+        const allRows = page === "footer"
+          ? FOOTER_FIELDS.map((field, index) => row(index, LABELS[field], state.footer[field] ? "ON" : "OFF", state.footer[field]))
+          : page === "pi" ? [
+            row(0, "Mouse clicks (Pi fullscreen, restart)", !prefs ? "N/A" : prefs.fullscreen ? "ON" : "OFF", !!prefs?.fullscreen),
+            row(1, "Copy on select", !prefs ? "N/A" : prefs.copyOnSelect ? "ON" : "OFF", !!prefs?.copyOnSelect),
+            row(2, "Goal auto rounds", String(state.goalRounds), true),
+            row(3, "Advisor (jar_advisor, /advisor)", state.advisor ? "ON" : "OFF", state.advisor),
+            row(4, "Advisor gates (loops, repeated failures)", state.advisorGates ? "ON" : "OFF", state.advisorGates)
+          ] : [
+            row(0, "Accent", state.accent === "follow" ? "FOLLOW PI" : state.accent.toUpperCase(), true),
+            row(1, "Motion", state.animations ? "ON" : "OFF", state.animations),
+            row(2, "Rounded composer", state.composer ? "ON" : "OFF", state.composer),
+            row(3, "Ember mascot", state.mascot ? "ON" : "OFF", state.mascot),
+            row(4, "Next-prompt suggestions", state.suggestions ? "ON" : "OFF", state.suggestions),
+            row(5, "Pi-jar UI", state.ui ? "ON" : "OFF", state.ui)
+          ];
+        const start = firstVisible();
+        const rows = allRows.slice(start, start + pageSize());
+        return [fit(top), tabs, divider,
+          line(theme.fg("accent", page === "footer" ? " FOOTER VISIBILITY" : page === "pi" ? " PI & WORKFLOWS" : " APPEARANCE & MOTION")),
+          line(theme.fg("dim", page === "footer" ? ` Footer fields ${start + 1}–${start + rows.length}/${fields()}`
+            : page === "pi" ? " Fullscreen mode enables clicks and copy-on-select" : " Accent cycles through loaded themes")),
+          ...rows.map(fit),
+          line(theme.fg("dim", " Tab: section · ↑↓: choose · Enter/click: change · Esc")),
+          fit(theme.fg("dim", "╰" + "─".repeat(Math.max(0, width - 2)) + "╯"))];
+      }
+    };
+  });
+}

package/src/settings.ts

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ACCENT_NAMES } from "./accent.ts";
+import { DEFAULT_FOOTER_SETTINGS, FOOTER_FIELDS, loadFooterSettings, type FooterSettings } from "./footer-settings.ts";
+
+export type JarAccent = "follow" | "default" | (typeof ACCENT_NAMES)[number];
+export interface JarVisualSettings {
+  version: 1;
+  accent: JarAccent;
+  animations: boolean;
+  ui: boolean;
+  composer: boolean;
+  /** Ember mascot perched on the composer. */
+  mascot: boolean;
+  /** Agent-provided next-prompt ghost text in the composer. */
+  suggestions: boolean;
+  /** Automatic implement/audit rounds per user message while a goal is active. */
+  goalRounds: number;
+  /** The jar_advisor second-opinion tool and /advisor. */
+  advisor: boolean;
+  /** Consult the advisor automatically when the agent repeats a tool call or keeps failing. */
+  advisorGates: boolean;
+  footer: FooterSettings;
+}
+
+export const GOAL_ROUND_CHOICES = [4, 8, 12, 20] as const;
+
+export const SETTINGS_FILE = "pi-jar-settings.json";
+export function defaultVisualSettings(footer: FooterSettings = DEFAULT_FOOTER_SETTINGS): JarVisualSettings {
+  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, advisor: true, advisorGates: true, footer: { ...footer } };
+}
+
+/** Legacy footer choices are imported only while the new file is absent. Never modify the old file. */
+export function loadVisualSettings(directory: string): JarVisualSettings {
+  let text: string;
+  try { text = readFileSync(join(directory, SETTINGS_FILE), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return defaultVisualSettings(loadFooterSettings(directory));
+    return defaultVisualSettings();
+  }
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { return defaultVisualSettings(); }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return defaultVisualSettings();
+  const value = raw as Record<string, unknown>;
+  if (value.version !== 1) return defaultVisualSettings();
+  const fallback = defaultVisualSettings();
+  const footer = value.footer && typeof value.footer === "object" && !Array.isArray(value.footer)
+    ? value.footer as Record<string, unknown> : {};
+  return {
+    version: 1,
+    accent: value.accent === "follow" || value.accent === "default" || ACCENT_NAMES.some((name) => name === value.accent)
+      ? value.accent as JarAccent : fallback.accent,
+    animations: typeof value.animations === "boolean" ? value.animations : fallback.animations,
+    ui: typeof value.ui === "boolean" ? value.ui : fallback.ui,
+    composer: typeof value.composer === "boolean" ? value.composer : fallback.composer,
+    mascot: typeof value.mascot === "boolean" ? value.mascot : fallback.mascot,
+    suggestions: typeof value.suggestions === "boolean" ? value.suggestions : fallback.suggestions,
+    goalRounds: typeof value.goalRounds === "number" && Number.isInteger(value.goalRounds) && value.goalRounds >= 1 && value.goalRounds <= 50
+      ? value.goalRounds : fallback.goalRounds,
+    advisor: typeof value.advisor === "boolean" ? value.advisor : fallback.advisor,
+    advisorGates: typeof value.advisorGates === "boolean" ? value.advisorGates : fallback.advisorGates,
+    footer: Object.fromEntries(FOOTER_FIELDS.map((field) => [field,
+      typeof footer[field] === "boolean" ? footer[field] : fallback.footer[field]])) as FooterSettings
+  };
+}
+
+export function migrateLegacySettings(directory: string): boolean {
+  if (existsSync(join(directory, SETTINGS_FILE)) || !existsSync(join(directory, "pi-jar-footer.json"))) return false;
+  try {
+    const legacy: unknown = JSON.parse(readFileSync(join(directory, "pi-jar-footer.json"), "utf8"));
+    if (!legacy || typeof legacy !== "object" || Array.isArray(legacy)) return false;
+    saveVisualSettings(directory, defaultVisualSettings(loadFooterSettings(directory)));
+    return true;
+  } catch { return false; } // Leave malformed legacy preferences untouched for manual repair.
+}
+
+export function saveVisualSettings(directory: string, settings: JarVisualSettings): void {
+  mkdirSync(directory, { recursive: true });
+  const target = join(directory, SETTINGS_FILE);
+  if (existsSync(target)) {
+    let prior: unknown;
+    try { prior = JSON.parse(readFileSync(target, "utf8")); }
+    catch { throw new Error("Cannot overwrite malformed pi-jar settings"); }
+    if (!prior || typeof prior !== "object" || (prior as Record<string, unknown>).version !== 1) {
+      throw new Error("Cannot overwrite unknown pi-jar settings version");
+    }
+  }
+  const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify(settings, null, 2) + "\n", { flag: "wx" });
+    renameSync(temporary, target);
+  } catch (error) {
+    try { unlinkSync(temporary); } catch { /* No temporary file to clean up. */ }
+    throw error;
+  }
+}

package/src/shells.ts

@@ -0,0 +1,319 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, Text, truncateToWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { safeLine } from "./diff-view.ts";
+import { cleanText } from "./status.ts";
+import { contentRows, optionList, sidebarWidth, splitFrame } from "./split-view.ts";
+
+export const SHELL_TOOL = "jar_shell";
+export const SHELL_MESSAGE = "pi-jar.shell";
+export const MAX_RUNNING_SHELLS = 8;
+const MAX_KEPT_SHELLS = 20;
+const MAX_LINES = 2000;
+const MAX_LINE_CHARS = 2000;
+const KILL_GRACE_MS = 3000;
+
+export type ShellStatus = "running" | "exited" | "killed" | "failed";
+export interface ShellJob {
+  id: string;
+  name: string;
+  command: string;
+  cwd: string;
+  pid?: number;
+  startedAt: number;
+  endedAt?: number;
+  status: ShellStatus;
+  exitCode?: number | null;
+  signal?: string | null;
+  error?: string;
+  watch?: string;
+  matched?: string;
+  /** Wake the agent when the pattern matches or the process ends. */
+  notify: boolean;
+  lines: string[];
+  /** Lines dropped from the front of the ring buffer. */
+  dropped: number;
+}
+export type ShellEvent = { kind: "match" | "exit"; job: ShellJob };
+export interface StartOptions { command: string; cwd: string; name?: string; watch?: string; notify?: boolean }
+
+const ANSI = /\x1b\][^\x07]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]|\x1b./g;
+
+/** Long-running shell commands with bounded output and optional pattern watches. */
+export class ShellManager {
+  private jobs = new Map<string, { job: ShellJob; child?: ChildProcess; pattern?: RegExp; partial: string; timer?: ReturnType<typeof setTimeout> }>();
+  private next = 1;
+  private readonly onEvent: (event: ShellEvent) => void;
+  private readonly spawnShell: typeof spawn;
+  onChange?: () => void;
+  constructor(onEvent: (event: ShellEvent) => void, spawnShell: typeof spawn = spawn) { this.onEvent = onEvent; this.spawnShell = spawnShell; }
+
+  list(): ShellJob[] { return [...this.jobs.values()].map(({ job }) => ({ ...job, lines: [...job.lines] })); }
+  get(id: string): ShellJob | undefined { const entry = this.jobs.get(id); return entry && { ...entry.job, lines: [...entry.job.lines] }; }
+  running(): number { return [...this.jobs.values()].filter(({ job }) => job.status === "running").length; }
+
+  start(options: StartOptions): ShellJob {
+    const command = options.command.trim();
+    if (!command) throw new Error("command is required");
+    if (this.running() >= MAX_RUNNING_SHELLS) throw new Error(`at most ${MAX_RUNNING_SHELLS} shells can run at once; kill one first`);
+    let pattern: RegExp | undefined;
+    if (options.watch) {
+      if (options.watch.length > 200) throw new Error("watch pattern is too long");
+      try { pattern = new RegExp(options.watch); } catch (error) { throw new Error("invalid watch pattern: " + (error instanceof Error ? error.message : String(error))); }
+    }
+    this.prune();
+    const id = "s" + this.next++;
+    const job: ShellJob = { id, name: cleanText(options.name || command, 40), command, cwd: options.cwd, startedAt: Date.now(), status: "running",
+      notify: options.notify ?? true, lines: [], dropped: 0, ...(options.watch ? { watch: options.watch } : {}) };
+    const entry: { job: ShellJob; child?: ChildProcess; pattern?: RegExp; partial: string; timer?: ReturnType<typeof setTimeout> } = { job, partial: "", ...(pattern ? { pattern } : {}) };
+    this.jobs.set(id, entry);
+    // Own process group so kill() stops the whole tree (dev servers spawn children).
+    const child = this.spawnShell("/bin/sh", ["-c", command], { cwd: options.cwd, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    entry.child = child;
+    if (child.pid !== undefined) job.pid = child.pid;
+    const receive = (chunk: Buffer | string) => this.receive(entry, String(chunk));
+    child.stdout?.on("data", receive);
+    child.stderr?.on("data", receive);
+    child.on("error", (error) => {
+      if (job.status !== "running") return;
+      job.status = "failed";
+      job.error = error.message;
+      job.endedAt = Date.now();
+      this.finish(entry);
+    });
+    child.on("close", (code, signal) => {
+      if (entry.partial) { this.push(entry, entry.partial); entry.partial = ""; }
+      if (job.status === "running") job.status = "exited";
+      job.exitCode = code;
+      job.signal = signal;
+      job.endedAt ??= Date.now();
+      this.finish(entry);
+    });
+    this.onChange?.();
+    return { ...job, lines: [] };
+  }
+
+  private receive(entry: { job: ShellJob; pattern?: RegExp; partial: string }, text: string): void {
+    const parts = (entry.partial + text.replace(/\r\n/g, "\n")).split("\n");
+    entry.partial = parts.pop() ?? "";
+    if (entry.partial.length > MAX_LINE_CHARS) { this.push(entry, entry.partial); entry.partial = ""; }
+    for (const line of parts) this.push(entry, line);
+  }
+
+  private push(entry: { job: ShellJob; pattern?: RegExp }, raw: string): void {
+    const line = raw.replace(ANSI, "").replace(/\r/g, "").slice(0, MAX_LINE_CHARS);
+    const { job } = entry;
+    job.lines.push(line);
+    if (job.lines.length > MAX_LINES) { job.lines.splice(0, job.lines.length - MAX_LINES); job.dropped++; }
+    if (entry.pattern && !job.matched && entry.pattern.test(line)) {
+      job.matched = line;
+      this.onEvent({ kind: "match", job: { ...job, lines: [...job.lines] } });
+    }
+  }
+
+  private finish(entry: { job: ShellJob; timer?: ReturnType<typeof setTimeout> }): void {
+    if (entry.timer) clearTimeout(entry.timer);
+    this.onEvent({ kind: "exit", job: { ...entry.job, lines: [...entry.job.lines] } });
+    this.onChange?.();
+  }
+
+  /** Last `count` lines (1–400). */
+  output(id: string, count = 40): string[] {
+    const entry = this.jobs.get(id);
+    if (!entry) throw new Error("no shell " + id);
+    const lines = [...entry.job.lines, ...(entry.partial ? [entry.partial] : [])];
+    return lines.slice(-Math.max(1, Math.min(400, Math.floor(count))));
+  }
+
+  kill(id: string): boolean {
+    const entry = this.jobs.get(id);
+    if (!entry) throw new Error("no shell " + id);
+    if (entry.job.status !== "running" || !entry.child) return false;
+    entry.job.status = "killed";
+    entry.job.endedAt = Date.now();
+    const signal = (name: NodeJS.Signals) => {
+      const pid = entry.child?.pid;
+      try { if (pid && process.platform !== "win32") process.kill(-pid, name); else entry.child?.kill(name); }
+      catch { entry.child?.kill(name); }
+    };
+    signal("SIGTERM");
+    entry.timer = setTimeout(() => signal("SIGKILL"), KILL_GRACE_MS);
+    entry.timer.unref?.();
+    this.onChange?.();
+    return true;
+  }
+
+  /** Forget finished jobs beyond the retention limit (oldest first). */
+  private prune(): void {
+    const finished = [...this.jobs.values()].filter(({ job }) => job.status !== "running");
+    for (const { job } of finished.slice(0, Math.max(0, this.jobs.size - MAX_KEPT_SHELLS + 1))) this.jobs.delete(job.id);
+  }
+
+  dispose(): void {
+    for (const id of this.jobs.keys()) { try { this.kill(id); } catch { /* already gone */ } }
+    this.jobs.clear();
+  }
+}
+
+const elapsed = (job: ShellJob, now = Date.now()) => {
+  const seconds = Math.max(0, Math.round(((job.endedAt ?? now) - job.startedAt) / 1000));
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+};
+export const shellState = (job: ShellJob) => job.status === "running" ? "running"
+  : job.status === "exited" ? `exited ${job.exitCode ?? "?"}` : job.status === "failed" ? `failed: ${cleanText(job.error ?? "", 60)}` : "killed";
+const describe = (job: ShellJob) => `${job.id} · ${job.name} · ${shellState(job)} · ${elapsed(job)}${job.watch ? ` · watch /${job.watch}/${job.matched ? " matched" : ""}` : ""}`;
+
+/** The message that wakes the agent when a watched shell matches or ends. */
+export function shellEventMessage(event: ShellEvent): string {
+  const { job } = event;
+  const head = event.kind === "match"
+    ? `Background shell ${job.id} (${job.name}) matched /${job.watch}/: ${job.matched}`
+    : `Background shell ${job.id} (${job.name}) ${shellState(job)} after ${elapsed(job)}.`;
+  const tail = job.lines.slice(-20);
+  return head + (tail.length ? `\nLast ${tail.length} line(s):\n` + tail.join("\n") : "") + `\nUse ${SHELL_TOOL} output/kill with id ${job.id} as needed.`;
+}
+
+const Parameters = Type.Object({
+  action: Type.Unsafe<"start" | "list" | "output" | "kill">({ type: "string", enum: ["start", "list", "output", "kill"] }),
+  command: Type.Optional(Type.String({ description: "Shell command to run in the background (start)." })),
+  name: Type.Optional(Type.String({ description: "Short label, e.g. \"dev server\"." })),
+  watch: Type.Optional(Type.String({ description: "Regex; when a line matches you are woken once, e.g. \"ready on|error\"." })),
+  notify: Type.Optional(Type.Boolean({ description: "Wake you when the pattern matches or the process ends (default true)." })),
+  id: Type.Optional(Type.String({ description: "Shell id for output/kill, e.g. s1." })),
+  lines: Type.Optional(Type.Number({ description: "How many trailing output lines to return (default 40, max 400)." }))
+});
+
+export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | undefined): void {
+  if (typeof (pi as ExtensionAPI & { registerTool?: unknown }).registerTool !== "function") return;
+  pi.registerTool({
+    name: SHELL_TOOL,
+    label: "shell",
+    description: "Run long-lived commands (dev servers, watchers, long test runs) in the background. start returns immediately; you are woken when an optional watch pattern matches or the process exits. Use output to read recent lines and kill to stop it.",
+    promptSnippet: "Use jar_shell for long-running or never-ending commands instead of blocking bash.",
+    promptGuidelines: [
+      "Use jar_shell start for servers, watchers and slow commands; set watch to a regex for the line you are waiting for (e.g. \"listening|ready|error\").",
+      "Do not poll: after starting, continue other work or end your turn; a message wakes you when the watch matches or the process ends. Kill shells you no longer need."
+    ],
+    parameters: Parameters,
+    async execute(_id, params, _signal, _update, ctx) {
+      const manager = shells();
+      const reply = (text: string, jobs: ShellJob[] = manager?.list() ?? []) => ({ content: [{ type: "text" as const, text }], details: { jobs } });
+      if (!manager) return reply("Background shells are unavailable before a Pi session starts.");
+      try {
+        switch (params.action) {
+          case "start": {
+            const job = manager.start({ command: params.command ?? "", cwd: ctx.cwd, ...(params.name ? { name: params.name } : {}), ...(params.watch ? { watch: params.watch } : {}),
+              ...(params.notify !== undefined ? { notify: params.notify } : {}) });
+            return reply(`Started ${describe(job)} (pid ${job.pid ?? "?"}). ${job.notify ? "You will be woken when it " + (job.watch ? "matches or " : "") + "exits." : "Notifications are off; check it with output."}`);
+          }
+          case "output": {
+            if (!params.id) return reply("output needs an id.");
+            const lines = manager.output(params.id, params.lines ?? 40);
+            return reply(`${describe(manager.get(params.id)!)}\n${lines.length ? lines.join("\n") : "(no output yet)"}`);
+          }
+          case "kill":
+            if (!params.id) return reply("kill needs an id.");
+            return reply(manager.kill(params.id) ? `Stopping ${params.id}.` : `${params.id} is not running.`);
+          default: {
+            const jobs = manager.list();
+            return reply(jobs.length ? jobs.map(describe).join("\n") : "No background shells.", jobs);
+          }
+        }
+      } catch (error) {
+        return reply(`${params.action} failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    },
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("shell")) + " " + theme.fg("accent", args.action);
+      if (args.command) text += " " + theme.fg("muted", cleanText(args.command, 80));
+      if (args.id) text += " " + theme.fg("muted", args.id);
+      if (args.watch) text += theme.fg("dim", ` watch /${cleanText(args.watch, 40)}/`);
+      return new Text(text, 0, 0);
+    },
+    renderResult(result, { expanded }, theme) {
+      const text = result.content.map((part) => part.type === "text" ? part.text : "").join("\n");
+      const lines = text.split("\n");
+      const shown = expanded ? lines : lines.slice(0, 6);
+      return new Text(shown.map((line, index) => theme.fg(index ? "muted" : "accent", safeLine(line))).join("\n")
+        + (shown.length < lines.length ? "\n" + theme.fg("dim", `… +${lines.length - shown.length} lines (expand)`) : ""), 0, 0);
+    }
+  });
+}
+
+const SHELL_ACTIONS = [
+  { key: "x", label: "Kill the selected shell" },
+  { key: "f", label: "Follow the latest output" }
+] as const;
+
+/** Overlay: shells on the left, the selected shell's live output on the right; k kills. */
+export async function openShellsView(ctx: ExtensionContext, manager: ShellManager): Promise<void> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return;
+  if (!manager.list().length) { ctx.ui.notify("pi-jar: no background shells (the agent starts them with jar_shell)", "info"); return; }
+  await ctx.ui.custom<void>((tui, theme, _keys, done) => {
+    let selected = 0;
+    let follow = true;
+    let scroll = 0;
+    let rows = 0;
+    let width = 80;
+    let layout = { top: 1, rows: 0, leftWidth: 0, bodyX: 2, footerTop: 0 };
+    const fg = (color: string, text: string) => theme.fg(color as never, text);
+    const previous = manager.onChange;
+    const timer = setInterval(() => tui.requestRender(), 500);
+    timer.unref?.();
+    manager.onChange = () => { previous?.(); tui.requestRender(); };
+    const close = () => { clearInterval(timer); manager.onChange = previous; done(); };
+    const component = {
+      invalidate() {},
+      handleInput(data: string) {
+        const jobs = manager.list();
+        if (matchesKey(data, Key.escape) || data === "q") return close();
+        if (matchesKey(data, Key.up) || data === "k") selected = Math.max(0, selected - 1);
+        else if (matchesKey(data, Key.down) || data === "j") selected = Math.min(jobs.length - 1, selected + 1);
+        else if (data === "x" || data === "K") { const job = jobs[selected]; if (job) { try { manager.kill(job.id); } catch (error) { ctx.ui.notify("pi-jar: " + String(error), "error"); } } }
+        else if (matchesKey(data, Key.pageUp)) { follow = false; scroll = Math.max(0, scroll - Math.max(1, rows - 2)); }
+        else if (matchesKey(data, Key.pageDown)) scroll += Math.max(1, rows - 2);
+        else if (data === "f" || data === "G") follow = true;
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        const row = event.y - layout.top;
+        if (event.type === "wheel" && event.wheelDelta) { follow = false; scroll = Math.max(0, scroll + Math.sign(event.wheelDelta) * 3); tui.requestRender(); return { handled: true }; }
+        if (event.type !== "click" || event.button !== "left") return;
+        if (event.y === 0 && event.x >= width - 3) { close(); return { handled: true }; }
+        if (row >= 0 && row < layout.rows && layout.leftWidth && event.x < layout.leftWidth + 3 && row < manager.list().length) { selected = row; follow = true; tui.requestRender(); return { handled: true, focus: true }; }
+        const action = SHELL_ACTIONS[event.y - layout.footerTop];
+        if (action) { component.handleInput(action.key); return { handled: true }; }
+      },
+      render(available: number): string[] {
+        width = Math.max(24, available);
+        rows = contentRows(6 + SHELL_ACTIONS.length, 6);
+        const jobs = manager.list();
+        selected = Math.min(selected, Math.max(0, jobs.length - 1));
+        const job = jobs[selected];
+        const listWidth = sidebarWidth(width, 20, 34);
+        const bodyWidth = listWidth ? width - listWidth - 6 : width - 4;
+        const output = job ? manager.output(job.id, 400) : [];
+        const maxScroll = Math.max(0, output.length - rows);
+        scroll = follow ? maxScroll : Math.min(scroll, maxScroll);
+        if (scroll >= maxScroll) follow = true;
+        const list = jobs.slice(0, rows).map((item, index) => {
+          const color = item.status === "running" ? "accent" : item.status === "exited" && item.exitCode === 0 ? "success" : item.status === "killed" ? "dim" : "error";
+          const glyph = item.status === "running" ? "●" : item.status === "exited" && item.exitCode === 0 ? "✔" : item.status === "killed" ? "■" : "✖";
+          return fg(index === selected ? "accent" : "muted", (index === selected ? "▌" : " ")) + fg(color, glyph + " ") + fg(index === selected ? "accent" : "muted", truncateToWidth(`${item.id} ${item.name}`, Math.max(4, listWidth - 4)));
+        });
+        const body = output.slice(scroll, scroll + rows).map((line) => fg("muted", truncateToWidth(safeLine(line), bodyWidth)));
+        if (job && !output.length) body.push(fg("dim", "(no output yet)"));
+        const title = `⚙ SHELLS · ${manager.running()} running` + (job ? ` · ${describe(job)}` : "");
+        const footer = [
+          ...optionList(theme, SHELL_ACTIONS.map((item) => item.label), -1, SHELL_ACTIONS.map((item) => item.key)),
+          fg("dim", (job ? "$ " + truncateToWidth(cleanText(job.command, 400), Math.max(8, width - 60)) + "   " : "") + "↑↓ shell · PgUp/PgDn scroll · Esc close")
+        ];
+        const split = splitFrame(theme, width, title, list, body, footer, rows, listWidth);
+        layout = split.layout;
+        return split.lines;
+      }
+    };
+    return component;
+  }, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%" } });
+}

package/src/side-model.ts

@@ -0,0 +1,48 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelRoleManager, ThinkingLevel } from "./model-roles.ts";
+
+/** One model call pi-jar made outside the main conversation (advisor, commit message, ...). */
+export interface SideCall {
+  role: string;
+  model: string;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  at: number;
+}
+
+/** Session-scoped record of side calls, so /usage can show what they cost. */
+export class SideUsage {
+  private calls: SideCall[] = [];
+  add(call: SideCall): void { this.calls.push(call); if (this.calls.length > 500) this.calls.shift(); }
+  all(): readonly SideCall[] { return this.calls; }
+  clear(): void { this.calls = []; }
+}
+
+export interface SideAnswer { text: string; model: string }
+
+/**
+ * Ask the model assigned to `role` (or the current model) a one-shot question outside the
+ * conversation. Throws on a missing model, provider error or empty answer.
+ */
+export async function askRole(ctx: ExtensionContext, roles: ModelRoleManager, usage: SideUsage | undefined, role: string,
+  systemPrompt: string, prompt: string, signal?: AbortSignal): Promise<SideAnswer> {
+  const assigned = roles.resolve(role);
+  const model = assigned ? ctx.modelRegistry.find(assigned.provider, assigned.model) : ctx.model;
+  if (!model) throw new Error(assigned ? `model not found for role ${role}: ${assigned.provider}/${assigned.model}` : "no model selected");
+  const thinking: ThinkingLevel | undefined = assigned?.thinking;
+  const reasoning = thinking && thinking !== "off" ? thinking : undefined;
+  const result = await ctx.modelRegistry.streamSimple(model,
+    { systemPrompt, messages: [{ role: "user", content: prompt, timestamp: Date.now() }] },
+    { ...(reasoning ? { reasoning } : {}), ...(signal ? { signal } : {}) }).result();
+  const name = `${model.provider}/${model.id}`;
+  const cost = result.usage?.cost?.total;
+  usage?.add({ role, model: name, input: result.usage?.input ?? 0, output: result.usage?.output ?? 0, cacheRead: result.usage?.cacheRead ?? 0,
+    cacheWrite: result.usage?.cacheWrite ?? 0, cost: Number.isFinite(cost) ? cost! : 0, at: Date.now() });
+  if (result.stopReason === "error" || result.stopReason === "aborted") throw new Error(result.errorMessage || `${name} ${result.stopReason}`);
+  const text = result.content.filter((part) => part.type === "text").map((part) => (part as { text: string }).text).join("").trim();
+  if (!text) throw new Error(`${name} returned an empty answer`);
+  return { text, model: name };
+}