pi-jar 0.1.8 → 0.2.0

package/src/shells.ts

@@ -13,9 +13,19 @@ const MAX_KEPT_SHELLS = 20;
 const MAX_LINES = 2000;
 const LINE_PRUNE_BATCH = 128;
 const MAX_LINE_CHARS = 2000;
+/** Per-job cap. Alone it would let every retained job pin ~1 MiB of logs. */
 const MAX_RETAINED_CHARS = 1024 * 1024;
+/** All jobs together. Floors below (8 live tails + 20 compact tails) stay well under it. */
+const DEFAULT_BUDGET_CHARS = 4 * 1024 * 1024;
+/** Budget pressure never trims a live job below this, so services stay observable. */
+const DEFAULT_LIVE_TAIL_CHARS = 64 * 1024;
 const MAX_TOOL_OUTPUT_CHARS = 32 * 1024;
+/** A surfaced finished job keeps exactly what one `output` call can return. */
+const COMPACT_TAIL_CHARS = MAX_TOOL_OUTPUT_CHARS;
+const MAX_OUTPUT_LINES = 400;
 const KILL_GRACE_MS = 3000;
+/** Trim 1/16 below a cap so a chatty job does not re-trim on every following line. */
+const slack = (chars: number) => chars - (chars >> 4);
 
 export type ShellStatus = "running" | "exited" | "killed" | "failed";
 export interface ShellJob {
@@ -42,6 +52,19 @@ export interface ShellJob {
 }
 export type ShellEvent = { kind: "match" | "exit"; job: ShellJob };
 export interface StartOptions { command: string; cwd: string; name?: string; watch?: string; notify?: boolean; purpose?: "task" | "service" }
+export interface ShellManagerOptions { budgetChars?: number; liveTailChars?: number }
+export interface ShellStats {
+  /** Processes still alive, including killed jobs in their grace period and draining trees. */
+  live: number;
+  finished: number;
+  retainedChars: number;
+  budgetChars: number;
+  /** Live jobs marked purpose: service — expected long-lived processes, not leftovers. */
+  services: number;
+  oldestLiveStartedAt?: number;
+  /** `pid` is reported only while the process group is alive; a finished pid may be reused. */
+  jobs: Array<{ id: string; name: string; status: ShellStatus; purpose: "task" | "service"; pid?: number; chars: number }>;
+}
 
 const ANSI = /\x1b\][^\x07]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]|\x1b./g;
 
@@ -50,23 +73,33 @@ interface ShellEntry {
   child?: ChildProcess;
   pattern?: RegExp;
   partial: string;
+  /** Retained line characters, maintained incrementally with the manager total. */
+  chars: number;
   timer?: ReturnType<typeof setTimeout>;
   closeTimer?: ReturnType<typeof setTimeout>;
   finished?: boolean;
 }
 
-/** Long-running shell commands with bounded output and optional pattern watches. */
+/** Long-running shell commands with bounded output and optional pattern watches. Retained logs
+ * are bounded per job and globally; log pressure trims text, never processes. */
 export class ShellManager {
   private jobs = new Map<string, ShellEntry>();
   private next = 1;
   private pending = new Map<string, ShellEvent>();
   private listeners = new Set<() => void>();
   private disposed = false;
-  private lineChars = new Map<string, number>();
+  private retained = 0;
+  private readonly budgetChars: number;
+  private readonly liveTailChars: number;
   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; }
+  constructor(onEvent: (event: ShellEvent) => void, spawnShell: typeof spawn = spawn, options: ShellManagerOptions = {}) {
+    this.onEvent = onEvent;
+    this.spawnShell = spawnShell;
+    this.budgetChars = Math.max(1, Math.floor(options.budgetChars ?? DEFAULT_BUDGET_CHARS));
+    this.liveTailChars = Math.max(0, Math.floor(options.liveTailChars ?? DEFAULT_LIVE_TAIL_CHARS));
+  }
 
   list(): ShellJob[] { return [...this.jobs.values()].map(({ job }) => ({ ...job, lines: [...job.lines] })); }
   /** Read by the footer on every render: one shallow copy per job, never the output lines. */
@@ -77,12 +110,23 @@ export class ShellManager {
     });
   }
   get(id: string): ShellJob | undefined { const entry = this.jobs.get(id); return entry && { ...entry.job, lines: [...entry.job.lines] }; }
-  acknowledge(ids: readonly string[]): void { for (const id of ids) this.pending.delete(id); }
-  takeNotifications(): ShellEvent[] { const events = [...this.pending.values()]; this.pending.clear(); return events; }
+  /** The agent saw these results: finished jobs drop everything but their compact summary. */
+  acknowledge(ids: readonly string[]): void {
+    for (const id of ids) { this.pending.delete(id); this.compact(id); }
+  }
+  /** Taken events are being delivered to the agent, which surfaces their results. */
+  takeNotifications(): ShellEvent[] {
+    const events = [...this.pending.values()];
+    this.pending.clear();
+    for (const event of events) this.compact(event.job.id);
+    return events;
+  }
   restoreNotifications(events: readonly ShellEvent[]): void {
     for (const event of events) if (this.jobs.has(event.job.id) && !this.pending.has(event.job.id)) this.pending.set(event.job.id, event);
   }
   pendingNotifications(): number { return this.pending.size; }
+  /** Non-consuming status snapshots for immediate UI feedback; never copy or expose log lines. */
+  notificationSnapshot(): ShellEvent[] { return [...this.pending.values()].map(event => ({ ...event, job: { ...event.job, lines: [] } })); }
   verificationPending(): Array<Omit<ShellJob, "lines">> {
     return [...this.jobs.values()].filter(entry => !entry.finished && entry.job.purpose !== "service").map(({ job }) => {
       const { lines: _lines, ...summary } = job;
@@ -135,9 +179,8 @@ export class ShellManager {
     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, complete: false, purpose: options.purpose ?? (options.watch ? "service" : "task"), lines: [], dropped: 0, ...(options.watch ? { watch: options.watch } : {}) };
-    const entry: ShellEntry = { job, partial: "", ...(pattern ? { pattern } : {}) };
+    const entry: ShellEntry = { job, partial: "", chars: 0, ...(pattern ? { pattern } : {}) };
     this.jobs.set(id, entry);
-    this.lineChars.set(id, 0);
     // 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;
@@ -184,34 +227,67 @@ export class ShellManager {
     return { ...job, lines: [] };
   }
 
-  private receive(entry: { job: ShellJob; pattern?: RegExp; partial: string }, text: string): void {
+  private receive(entry: ShellEntry, 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 {
+  private push(entry: ShellEntry, raw: string): void {
+    // Disposed jobs are forgotten while their trees wind down; late output must not be counted.
+    if (this.disposed) return;
     const line = raw.replace(ANSI, "").replace(/\r/g, "").slice(0, MAX_LINE_CHARS);
     const { job } = entry;
     job.lines.push(line);
-    this.lineChars.set(job.id, (this.lineChars.get(job.id) ?? 0) + line.length);
+    entry.chars += line.length;
+    this.retained += line.length;
     // Bound both line count and retained characters. A shell that prints very wide lines should
     // not quietly reserve several MiB forever just because it has not reached MAX_LINES yet.
-    while (job.lines.length > MAX_LINES + LINE_PRUNE_BATCH || (this.lineChars.get(job.id) ?? 0) > MAX_RETAINED_CHARS) {
-      const removed = job.lines.splice(0, Math.min(LINE_PRUNE_BATCH, job.lines.length));
-      let removedChars = 0;
-      for (const item of removed) removedChars += item.length;
-      this.lineChars.set(job.id, Math.max(0, (this.lineChars.get(job.id) ?? 0) - removedChars));
-      job.dropped += removed.length;
-      if (!removed.length) break;
-    }
+    if (job.lines.length > MAX_LINES + LINE_PRUNE_BATCH || entry.chars > MAX_RETAINED_CHARS) this.trim(entry, slack(MAX_RETAINED_CHARS), MAX_LINES);
+    if (this.retained > this.budgetChars) this.enforceBudget();
     if (entry.pattern && !job.matched && entry.pattern.test(line)) {
       job.matched = line;
       this.emitEvent("match", job);
     }
   }
 
+  /** Drop oldest lines until at most `chars` characters and `lines` lines remain. One splice. */
+  private trim(entry: ShellEntry, chars: number, lines = Infinity): void {
+    const buffer = entry.job.lines;
+    let count = 0;
+    let released = 0;
+    while (count < buffer.length && (entry.chars - released > chars || buffer.length - count > lines)) released += buffer[count++]!.length;
+    if (!count) return;
+    buffer.splice(0, count);
+    entry.chars -= released;
+    this.retained -= released;
+    entry.job.dropped += count;
+  }
+
+  /** Over budget: shrink oldest finished jobs to their compact tail, then oldest live jobs to
+   * their protected tail, then empty finished jobs. Jobs (≤ MAX_KEPT_SHELLS) iterate oldest
+   * first; the slack target keeps this off the per-line path. Processes are never touched. */
+  private enforceBudget(): void {
+    const target = slack(this.budgetChars);
+    for (const [floor, finished] of [[COMPACT_TAIL_CHARS, true], [this.liveTailChars, false], [0, true]] as const) {
+      for (const entry of this.jobs.values()) {
+        if (this.retained <= target) return;
+        if (!!entry.finished === finished) this.trim(entry, Math.max(floor, entry.chars - (this.retained - target)));
+      }
+    }
+  }
+
+  /** Keep exit status, command, timestamps, watch match and a bounded tail once surfaced. */
+  private compact(id: string): void {
+    const entry = this.jobs.get(id);
+    if (!entry?.finished) return;
+    this.trim(entry, COMPACT_TAIL_CHARS, MAX_OUTPUT_LINES);
+    // A finished job never reads its stream or matches again; release the process handle.
+    delete entry.child;
+    delete entry.pattern;
+  }
+
   private finish(entry: ShellEntry): void {
     if (entry.finished) return;
     entry.finished = true;
@@ -231,12 +307,34 @@ export class ShellManager {
   output(id: string, count = 40): string[] {
     const entry = this.jobs.get(id);
     if (!entry) throw new Error("no shell " + id);
-    const limit = Math.max(1, Math.min(400, Math.floor(count)));
+    const limit = Math.max(1, Math.min(MAX_OUTPUT_LINES, Math.floor(count)));
     if (!entry.partial) return entry.job.lines.slice(-limit);
     if (limit === 1) return [entry.partial];
     return [...entry.job.lines.slice(-(limit - 1)), entry.partial];
   }
 
+  /** Diagnostics snapshot, computed on demand in one pass over ≤ MAX_KEPT_SHELLS jobs. */
+  stats(): ShellStats {
+    let live = 0;
+    let services = 0;
+    let partials = 0;
+    let oldestLiveStartedAt: number | undefined;
+    const jobs: ShellStats["jobs"] = [];
+    for (const entry of this.jobs.values()) {
+      const { job } = entry;
+      const purpose = job.purpose ?? "task";
+      partials += entry.partial.length;
+      if (!entry.finished) {
+        live++;
+        if (purpose === "service") services++;
+        if (oldestLiveStartedAt === undefined || job.startedAt < oldestLiveStartedAt) oldestLiveStartedAt = job.startedAt;
+      }
+      jobs.push({ id: job.id, name: job.name, status: job.status, purpose, chars: entry.chars + entry.partial.length, ...(!entry.finished && job.pid !== undefined ? { pid: job.pid } : {}) });
+    }
+    return { live, finished: this.jobs.size - live, retainedChars: this.retained + partials, budgetChars: this.budgetChars, services,
+      ...(oldestLiveStartedAt !== undefined ? { oldestLiveStartedAt } : {}), jobs };
+  }
+
   kill(id: string): boolean {
     const entry = this.jobs.get(id);
     if (!entry) throw new Error("no shell " + id);
@@ -255,13 +353,17 @@ export class ShellManager {
     return true;
   }
 
-  /** Forget finished jobs beyond the retention limit (oldest first). */
+  /** Forget finished jobs beyond the retention limit (oldest first). A killed job still in its
+   * grace period or a draining tree is alive and stays managed until it finishes. */
   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);
-      this.lineChars.delete(job.id);
-      this.pending.delete(job.id);
+    let excess = this.jobs.size - MAX_KEPT_SHELLS + 1;
+    for (const [id, entry] of this.jobs) {
+      if (excess <= 0) return;
+      if (!entry.finished) continue;
+      this.jobs.delete(id);
+      this.retained -= entry.chars;
+      this.pending.delete(id);
+      excess--;
     }
   }
 
@@ -269,9 +371,14 @@ export class ShellManager {
     this.disposed = true;
     this.pending.clear();
     for (const listener of [...this.listeners]) listener();
-    for (const id of this.jobs.keys()) { try { this.kill(id); } catch { /* already gone */ } }
+    for (const entry of this.jobs.values()) {
+      if (entry.finished) continue;
+      // Running trees get SIGTERM plus the bounded SIGKILL grace. A draining tree (leader gone,
+      // descendants holding pipes) is reclaimed now rather than after its drain timer.
+      if (!this.kill(entry.job.id) && entry.job.status !== "killed") this.finish(entry);
+    }
     this.jobs.clear();
-    this.lineChars.clear();
+    this.retained = 0;
   }
 }
 
@@ -283,7 +390,8 @@ export const elapsed = (span: { startedAt: number; endedAt?: number }, now = Dat
 };
 export const shellState = (job: ShellMeta | ShellJob) => job.status === "running" ? "running"
   : job.status === "exited" ? `exited ${job.exitCode ?? "?"}${job.complete === false ? " (draining)" : ""}` : job.status === "failed" ? `failed: ${cleanText(job.error ?? "", 60)}` : "killed";
-export const describe = (job: ShellMeta | ShellJob) => `${job.id} · ${job.name} · ${shellState(job)} · ${elapsed(job)}${job.watch ? ` · watch /${job.watch}/${job.matched ? " matched" : ""}` : ""}`;
+// Services are labelled so a long-lived process reads as intended, not as a forgotten leftover.
+export const describe = (job: ShellMeta | ShellJob) => `${job.id} · ${job.name} · ${shellState(job)} · ${elapsed(job)}${job.purpose === "service" ? " · service" : ""}${job.watch ? ` · watch /${job.watch}/${job.matched ? " matched" : ""}` : ""}`;
 const boundedTail = (lines: readonly string[], limit = MAX_TOOL_OUTPUT_CHARS): string => {
   let size = 0;
   const kept: string[] = [];
@@ -332,6 +440,7 @@ export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | un
     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: work while commands run, then use wait with explicit ids for relevant checks before the final summary. A bounded wait returns pending jobs honestly; never claim success without their exit codes. Do not wait for services/watchers. output, peek, list and wait acknowledge observed events, preventing stale replay.",
+      "Completion events cannot interrupt an in-flight model response. If no useful work remains, call wait for the relevant finite jobs immediately instead of thinking or waiting for an automatic wake-up.",
       "Notifications contain coalesced status, not log dumps. Inspect output only for relevant diagnostics. Mark never-ending jobs purpose: service and kill shells you no longer need."
     ],
     parameters: Parameters,
@@ -347,7 +456,7 @@ export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | un
           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 } : {}), ...(params.purpose ? { purpose: params.purpose } : {}) });
-            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."}`);
+            return reply(`Started ${describe(job)} (pid ${job.pid ?? "?"}). ${job.notify ? "Completion reaches the model at the next safe turn boundary (or wakes it when idle). If no other useful work remains, use wait now." : "Notifications are off; check it with output."}`);
           }
           case "output": {
             if (!params.id) return reply("output needs an id.");

package/src/side-model.ts

@@ -30,7 +30,7 @@ export interface SideAnswer { text: string; model: string }
  * Ask the model assigned to `role` (or the current model) a one-shot question outside the
  * conversation. Tries configured fallbacks in order on failure; cancellation never retries.
  */
-export async function askRole(ctx: ExtensionContext, roles: ModelRoleManager, usage: SideUsage | undefined, role: string,
+export async function askRole(ctx: ExtensionContext, roles: ModelRoleManager, usage: Pick<SideUsage, "add"> | undefined, role: string,
   systemPrompt: string, prompt: string, signal?: AbortSignal): Promise<SideAnswer> {
   const fallbacks = roles.fallbackSpecs?.(role) ?? [];
   const failures: string[] = [];
@@ -52,6 +52,8 @@ export async function askRole(ctx: ExtensionContext, roles: ModelRoleManager, us
       const result = await ctx.modelRegistry.streamSimple(model,
         { systemPrompt, messages: [{ role: "user", content: prompt, timestamp: Date.now() }] },
         { ...(reasoning ? { reasoning } : {}), ...(signal ? { signal } : {}) }).result();
+      // Callers with detached work can supply a session-generation-safe usage sink.
+      // Returned attempts (including cancelled attempts) still account for actual usage.
       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() });

package/src/welcome.ts

@@ -1,4 +1,4 @@
-import { sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { FLAME_RAMP, FLAME_WIDTH, flameFrame, rgb, supportsTruecolor } from "./flame.ts";
 import { cleanText } from "./status.ts";
 import { iconSet, withIcon } from "./icons.ts";
@@ -10,6 +10,8 @@ export interface WelcomeInfo {
   model?: string;
   effort?: string;
   activeRole?: string;
+  /** Active configuration profile, shown even before a session is named. */
+  profile?: string;
   project?: string;
   context?: string;
   cost?: string;
@@ -189,6 +191,8 @@ function card(width: number, fg: Paint, info: WelcomeInfo): string[] {
     cell(center(fg("dim", "— welcome to ") + fg("accent", "pi-jar") + fg("dim", " —"), inner)),
     cell(""),
     divider,
+    ...wrapTextWithAnsi(cleanText(info.profile ?? "Default", 32) || "Default", Math.max(1, inner - labelWidth))
+      .map((line, index) => cell(index ? fg("dim", " ".repeat(labelWidth)) + fg("accent", line) : label("PROFILE", line, "accent"))),
     cell(label("PROJECT", withIcon("folder", info.project || "unavailable") + " · " + git, info.dirty ? "warning" : "muted")),
     cell(label("SESSION", [info.context ?? "ctx ?", quota, info.cost ?? ""].filter(Boolean).join(" · "))),
     divider,
@@ -262,6 +266,7 @@ function renderWelcome(width: number, frame: number, fg: Paint, info: WelcomeInf
       ...flame.slice(4).map((line) => fit(sliceByColumn(line, start, Math.min(width, FLAME_WIDTH)))),
       ...PI_COMPACT.map((line) => fit(fg("accent", line))),
       fit(fg("accent", "pi-jar")),
+      fit(fg("accent", "Profile: " + (cleanText(info.profile ?? "Default", 32) || "Default"))),
       ...wrap(cleanText(info.message ?? HOPEFUL_WELCOME_MESSAGES[0], 100), width).map((line) => fit("\x1b[1m" + fg("warning", line) + "\x1b[22m")),
       fit(fg(info.settingsClickable === false ? "dim" : "accent", info.settingsClickable === false ? "ctrl+alt+s settings" : "[ ⚙ Settings ]")),
       ""