@yaag/extension 0.1.4 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -24,9 +24,10 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.1.4",
-    "@yaag/tui": "0.1.4",
-    "@yaag/cli": "0.1.4"
+    "@yaag/cli": "0.2.1",
+    "@yaag/runtime": "0.2.1",
+    "@yaag/tui": "0.2.1",
+    "nanoid": "^6.0.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/background-status.ts

@@ -0,0 +1,94 @@
+/**
+ * The footer segment for every live background Run (architecture §9).
+ *
+ * A background Run costs no scrollback and owns no widget: it reports itself in
+ * one cooperative footer segment, `yaag: 2 live · $0.42`, which pi lays out
+ * beside the segments of every other extension. The segment is cleared as soon
+ * as the last background Run ends.
+ */
+import { costText } from "@yaag/tui";
+import type { RunRegistry } from "./run-registry.ts";
+import type { RunTreeStore } from "./run-trees.ts";
+
+/** The one footer key this extension owns. */
+export const STATUS_KEY = "yaag";
+
+/** The only pi capability the footer segment needs. */
+export interface StatusSurface {
+  setStatus(key: string, text: string | undefined): void;
+}
+
+/** What the footer segment reads: the Run registry and the projection store. */
+export interface BackgroundStatusOptions {
+  readonly registry: RunRegistry;
+  readonly store: RunTreeStore;
+}
+
+/** The footer controller: bind it once, then refresh it on every occurrence. */
+export interface BackgroundStatus {
+  /**
+   * Binds the pi UI surface, once the Host Session has one, and writes the
+   * current text. A `StatusSurface.setStatus()` that throws propagates here.
+   */
+  bind(surface: StatusSurface): void;
+  /**
+   * Rewrites the segment; drops the write before `bind`, and skips unchanged
+   * text. A bound `StatusSurface.setStatus()` that throws propagates here.
+   */
+  refresh(): void;
+}
+
+/**
+ * Builds the footer segment over this session's Run registry and projections.
+ *
+ * An unbound controller drops every refresh, and a Run without a projection is
+ * skipped. The controller lives for the whole Host Session, so it never
+ * unsubscribes. Construction itself never throws, but `bind()` and `refresh()`
+ * call the caller's `StatusSurface.setStatus()` and propagate whatever it
+ * throws; the store subscription also propagates it into the `ingest()` that
+ * caused the rewrite.
+ */
+export function createBackgroundStatus(options: BackgroundStatusOptions): BackgroundStatus {
+  let surface: StatusSurface | undefined;
+  let written: string | undefined;
+
+  const refresh = (): void => {
+    if (surface === undefined) return;
+    const text = statusText(options);
+    if (written === text) return;
+    written = text;
+    surface.setStatus(STATUS_KEY, text);
+  };
+
+  options.store.subscribe(() => refresh());
+
+  return {
+    bind(bound: StatusSurface): void {
+      surface = bound;
+      written = undefined;
+      refresh();
+    },
+    refresh,
+  };
+}
+
+/**
+ * The segment text, or undefined when no background Run is live.
+ *
+ * The cost is the sum over every live background Run, and it carries
+ * `+incomplete` when any of those Runs reports its cost as a floor (ADR-0012).
+ */
+function statusText(options: BackgroundStatusOptions): string | undefined {
+  let count = 0;
+  let cost: number | null = null;
+  let incomplete = false;
+  for (const run of options.registry.live) {
+    if (options.store.kind(run.id) !== "background") continue;
+    count += 1;
+    const summary = run.summary;
+    if (summary.cost !== null) cost = (cost ?? 0) + summary.cost;
+    if (summary.incomplete) incomplete = true;
+  }
+  if (count === 0) return undefined;
+  return `${STATUS_KEY}: ${count} live · ${costText(cost, incomplete)}`;
+}

package/src/cli-child.ts

@@ -22,6 +22,8 @@ export interface CliChildOptions {
 export interface CliChild {
   readonly outcome: Promise<CliChildOutcome>;
   readonly events: Readable | undefined;
+  /** The child's pid, and the group id its reap ladder signals. */
+  readonly pid?: number | undefined;
   stop(): void;
 }
 
@@ -53,6 +55,7 @@ export function startCliChild(options: CliChildOptions): CliChild {
   const eventStream = options.events === true ? child.stdio[3] : undefined;
   return {
     outcome,
+    pid: child.pid,
     events: isReadable(eventStream) ? eventStream : undefined,
     stop: () => void reap(target),
   };

package/src/fake-extension-ui.ts

@@ -1,7 +1,8 @@
 /**
  * A fully typed `ExtensionUIContext` for the tui-mode test context.
  *
- * `custom`, `notify`, `editor`, `setWidget`, and a scripted `select` work;
+ * `custom`, `notify`, `editor`, `setWidget`, `setStatus`, and a scripted
+ * `select` work;
  * every other capability throws, so a dependency a view is not supposed to
  * have fails loudly. The
  * class implements the interface, so pi's UI surface is checked at compile
@@ -54,6 +55,8 @@ export class FakeExtensionUi implements ExtensionUIContext {
   readonly edits: OpenedEditor[] = [];
   /** The latest frame per widget key; `undefined` means the key was cleared. */
   readonly widgets = new Map<string, string[] | undefined>();
+  /** The latest text per footer key; `undefined` means the key was cleared. */
+  readonly statuses = new Map<string, string | undefined>();
   /** Answers `select` in order; an empty queue answers `undefined`, i.e. esc. */
   readonly selections: string[] = [];
   /** The component `custom` opened, once a Run opened one. */
@@ -116,8 +119,8 @@ export class FakeExtensionUi implements ExtensionUIContext {
   onTerminalInput(): () => void {
     return unavailable("ui.onTerminalInput");
   }
-  setStatus(): void {
-    unavailable("ui.setStatus");
+  setStatus(key: string, text: string | undefined): void {
+    this.statuses.set(key, text);
   }
   setWorkingMessage(): void {
     unavailable("ui.setWorkingMessage");

package/src/fake-tui.ts

@@ -1,7 +1,7 @@
 /**
  * Fully typed `TUI` and `Terminal` doubles for the tui-mode test context.
  *
- * The foreground Run view uses three capabilities only: `terminal.rows`,
+ * The Run view uses three capabilities only: `terminal.rows`,
  * `terminal.columns`, and `requestRender()`. Every other member of `Terminal`
  * and `TUI` — fields and getters included — throws on access, so a component
  * that starts to depend on the terminal fails loudly in the test instead of

package/src/index.ts

@@ -1,11 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createBackgroundWidget } from "./background-widget.ts";
+import { createBackgroundStatus } from "./background-status.ts";
 import { createDescribeTool } from "./describe-tool.ts";
 import { findProgramDirectories } from "./program-directories.ts";
 import { resolveBun } from "./resolve-bun.ts";
 import { resolveCliEntry } from "./resolve-cli.ts";
 import { createRunCompleteRenderer } from "./run-complete-renderer.ts";
 import { RunRegistry } from "./run-registry.ts";
+import { RunStore } from "./run-store.ts";
 import { createRunTool } from "./run-tool.ts";
 import { RunTreeStore } from "./run-trees.ts";
 import { createSetupWorkspaceExecutor } from "./setup-workspace.ts";
@@ -31,14 +32,16 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   const cli = resolveCliEntry();
   const report = statusReport(bun, cli);
 
-  // One registry per session retains every foreground and background Run.
-  const registry = new RunRegistry();
-  // The renderer projections and the one combined inline widget both live for
+  // One registry per session, mirrored to a durable store so a restart of this
+  // Host Session keeps every Run id addressable (ticket 02).
+  const registry = new RunRegistry({ store: new RunStore() });
+  await registry.restore();
+  // The renderer projections and the background footer segment both live for
   // the session, beside the registry, so a background Run keeps a tree.
   const store = new RunTreeStore();
-  const widget = createBackgroundWidget({ registry, store });
+  const status = createBackgroundStatus({ registry, store });
   pi.registerTool(
-    createRunTool({ bun, cli, registry, store, widget, sendMessage: pi.sendMessage.bind(pi) }),
+    createRunTool({ bun, cli, registry, store, status, sendMessage: pi.sendMessage.bind(pi) }),
   );
   pi.registerTool(createStatusTool(registry));
   pi.registerMessageRenderer("yaag-run-complete", createRunCompleteRenderer());
@@ -55,7 +58,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
   pi.on("session_start", (_event, ctx) => {
     if (bun === null) ctx.ui.notify(report, "error");
-    if (ctx.hasUI) widget.bind(ctx.ui);
+    if (ctx.hasUI) status.bind(ctx.ui);
   });
 
   // Commands and tools have separate namespaces: this CLI-resolution command

package/src/process-liveness.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+
+/** What a Run record remembers about the process that carried it. */
+export interface ProcessIdentity {
+  readonly pid: number;
+  /** Kernel start time of that pid, when the platform exposes it. */
+  readonly startedAt: string | null;
+}
+
+/**
+ * Reads the start time of a live pid, so a later session can tell the original
+ * process from an unrelated one that inherited the pid. Linux exposes it as
+ * field 22 of `/proc/<pid>/stat`; every other platform returns `null` and the
+ * liveness probe falls back to the pid alone.
+ */
+export function readProcessStart(pid: number): string | null {
+  if (process.platform !== "linux") return null;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // The second field is the executable name in parentheses and may itself
+    // contain spaces and parentheses, so fields are counted after the last ")".
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    return fields[19] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reports whether the exact process a record names is still running. A pid that
+ * exists but reports a different start time is a reused pid, and is treated as
+ * dead: killing it would end an unrelated process.
+ */
+export function isProcessAlive(identity: ProcessIdentity): boolean {
+  if (!Number.isInteger(identity.pid) || identity.pid <= 0) return false;
+  try {
+    process.kill(identity.pid, 0);
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return isPermissionError(error);
+  }
+  if (identity.startedAt === null) return true;
+  const current = readProcessStart(identity.pid);
+  return current === null || current === identity.startedAt;
+}
+
+function isPermissionError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  const { code } = error;
+  return code === "EPERM";
+}

package/src/run-details.ts

@@ -43,7 +43,8 @@ function isRunSummary(value: unknown): value is RunSummary {
     value.runState === "ended" &&
     isOutcome(value.outcome) &&
     typeof value.ok === "boolean" &&
-    nullableNumber(value.endedAt)
+    nullableNumber(value.endedAt) &&
+    optionalString(value.checkpointLost)
   );
 }
 
@@ -207,7 +208,8 @@ function isEvent(value: unknown): value is LifecycleEvent {
         number(value.cost) &&
         nullableTokens(value.tokens) &&
         typeof value.incomplete === "boolean" &&
-        natural(value.worstFrameGapMs)
+        natural(value.worstFrameGapMs) &&
+        optionalString(value.checkpointLost)
       );
     default:
       return false;

package/src/run-foreground.ts

@@ -1,19 +1,36 @@
 /**
- * The two blocking `yaag_run` paths (spec §4): the details-only stream every
- * client gets, and the interactive tree a tui-mode Host Session gets.
+ * The two blocking `yaag_run` paths (architecture §9): the details-only stream every
+ * client gets, and the inline frame a tui-mode Host Session also draws.
  *
- * Both return the same model-visible contract, so opening the interactive view
- * changes nothing the model can see.
+ * Both return the same model-visible contract, so drawing the frame changes
+ * nothing the model can see, and neither path opens a modal: the Host Session
+ * keeps its input loop while the tool call blocks.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { TreeState } from "@yaag/tui";
+import { renderInlineRun, type TreeState } from "@yaag/tui";
 import type { RunDetails } from "./run-details.ts";
-import { openRunTreeView } from "./run-foreground-view.ts";
 import type { LiveRun, RunRegistry, RunSettlement } from "./run-registry.ts";
-import { failure, observedSettlement, toError, viewResult } from "./run-settlement.ts";
+import { failure, observedSettlement, toError } from "./run-settlement.ts";
 import type { RunTreeStore } from "./run-trees.ts";
 import { toUsage } from "./usage.ts";
 
+/**
+ * The pi widget key one blocking Run draws under.
+ *
+ * The key carries the Run id, because pi executes sibling tool calls
+ * concurrently: two blocking Runs keep two frames, and each one clears only
+ * its own.
+ */
+export function foregroundWidgetKey(id: string): string {
+  return `yaag-run:${id}`;
+}
+
+/** Line budget for the inline frame; pi truncates a widget past 10 lines. */
+const WIDGET_MAX_LINES = 10;
+
+/** Width the inline frame is clamped to; pi wraps nothing for a widget. */
+const WIDGET_WIDTH = 100;
+
 /** What `execute` returns for a blocking Run. */
 export interface ForegroundResult {
   content: { type: "text"; text: string }[];
@@ -34,25 +51,23 @@ export interface ForegroundOptions {
 }
 
 /**
- * `ForegroundOptions` plus what opening the interactive tree needs.
+ * `ForegroundOptions` plus what drawing the inline frame needs.
  *
- * Only valid when `interactiveAvailable()` is true; `ctx.ui` is touched on no
- * other path.
+ * Only valid when `inlineAvailable()` is true; `ctx.ui` is touched on no other
+ * path.
  */
-export interface InteractiveOptions extends ForegroundOptions {
+export interface InlineOptions extends ForegroundOptions {
   readonly ctx: ExtensionContext;
-  /** Ingested from Run start, so the tree misses no early Ask. */
+  /** Ingested from Run start by the caller, so the frame misses no early Ask. */
   readonly state: TreeState;
-  /** Detaching hands the Run to the combined inline widget. */
+  /** Detaching hands the Run to the footer segment. */
   readonly store: RunTreeStore;
   /** Registers the `yaag-run-complete` follow-up; called only on detach. */
   announce(): void;
-  /** Receives the redraw handle, so a pushed fd 3 update can reach the view. */
-  onOpen?(view: { touch(): void }): void;
 }
 
-/** Whether this call may open the interactive tree (spec §4: tui mode only). */
-export function interactiveAvailable(ctx: ExtensionContext, background: boolean): boolean {
+/** Whether this call may draw the inline frame; tui mode only (architecture §9). */
+export function inlineAvailable(ctx: ExtensionContext, background: boolean): boolean {
   return !background && ctx.mode === "tui" && ctx.hasUI;
 }
 
@@ -77,63 +92,95 @@ export async function foregroundResult(options: ForegroundOptions): Promise<Fore
 }
 
 /**
- * The interactive path: the reader watches the tree while the Run executes, then
- * dismisses it or detaches the Run.
+ * The inline path: a read-only frame of the Run tree is drawn beside the chat
+ * while the tool call blocks, and the frame is cleared when the call returns.
  *
- * Dismissal returns exactly what `foregroundResult` returns, throw included.
- * Detach returns an acknowledgement and leaves the Run executing as `rN`, with
- * its completion delivered by the `yaag-run-complete` follow-up. Every path
- * closes the view, so `ctx.ui.custom()` cannot outlive the tool call.
+ * `esc` aborts the tool call, and an abort detaches rather than stops: the Run
+ * becomes a background Run, joins the footer segment, and its completion
+ * arrives through the `yaag-run-complete` follow-up. Stopping a Run is `/yaag`
+ * → `ctrl+q` → Stop Run (ADR-0008).
  */
-export async function foregroundInteractive(
-  options: InteractiveOptions,
-): Promise<ForegroundResult> {
+export async function foregroundInline(options: InlineOptions): Promise<ForegroundResult> {
   const { run, registry, signal, ctx } = options;
-  const view = openRunTreeView({
-    ctx,
-    state: options.state,
-    id: run.id,
-    stop: run.stop,
-    onDetach: () => options.store.adopt(run.id),
+  const frame = createFrame(ctx, run.id, options.state);
+  let detached = false;
+  // Resolved by the detach itself, so the abort needs no second listener and
+  // leaves nothing registered on a signal the tool call outlives.
+  let onDetached: () => void = () => {};
+  const detaching = new Promise<undefined>((resolve) => {
+    onDetached = () => resolve(undefined);
   });
-  options.onOpen?.(view);
-  const abort = (): void => {
-    run.stop();
-    view.close("dismissed");
+  const detach = (): void => {
+    if (detached) return;
+    detached = true;
+    options.store.adopt(run.id);
+    options.announce();
+    onDetached();
   };
-  signal?.addEventListener("abort", abort, { once: true });
-  if (signal?.aborted === true) abort();
+  signal?.addEventListener("abort", detach, { once: true });
+  const unsubscribe = options.store.subscribe((id) => {
+    if (id === run.id && !detached) frame.draw();
+  });
+  frame.draw();
   try {
-    // Kept as a settled-shaped promise so a detach — which leaves this promise
-    // pending — cannot surface as an unhandled rejection.
+    if (signal?.aborted === true) detach();
+    if (detached) return detachedResult(run);
     const settled = observedSettlement(run.id, run.outcome, registry).then(
-      (settlement): SettledRace => ({ kind: "settled", settlement }),
-      (reason): SettledRace => ({ kind: "settled", settlement: { kind: "rejected", reason } }),
+      (settlement): RunSettlement => settlement,
+      (reason): RunSettlement => ({ kind: "rejected", reason }),
     );
-    const first = await Promise.race([
-      settled,
-      view.exit.then((exit) => ({ kind: "exit", exit }) as const),
-    ]);
-    if (first.kind === "exit" && first.exit === "detached") {
-      options.announce();
+    // The detach resolves this race, so the tool call returns while the Run
+    // keeps executing; `settled` stays a handled promise either way.
+    const settlement = await Promise.race([settled, detaching]);
+    // `detached` is checked beside the settlement: an abort that lands in the
+    // same synchronous stretch as the settlement already announced the Run, and
+    // returning its value here would report the same Run to the model twice.
+    if (settlement === undefined || detached) {
+      detach();
       return detachedResult(run);
     }
-    if (first.kind === "settled") view.settle(viewResult(first.settlement));
-    const exit = await view.exit;
-    if (exit === "detached") {
-      options.announce();
-      return detachedResult(run);
-    }
-    if (signal?.aborted === true) throw new Error("yaag_run: cancelled");
-    return finalResult(run.id, await settled.then(({ settlement }) => settlement));
+    return finalResult(run.id, settlement);
   } finally {
-    signal?.removeEventListener("abort", abort);
-    view.close("dismissed");
-    view.dispose();
+    signal?.removeEventListener("abort", detach);
+    unsubscribe();
+    frame.clear();
   }
 }
 
-type SettledRace = { readonly kind: "settled"; readonly settlement: RunSettlement };
+/** One inline frame: a redraw and a clear, both idempotent after the clear. */
+interface InlineFrame {
+  draw(): void;
+  clear(): void;
+}
+
+function createFrame(ctx: ExtensionContext, id: string, state: TreeState): InlineFrame {
+  const key = foregroundWidgetKey(id);
+  let cleared = false;
+  let drawn: readonly string[] | undefined;
+  return {
+    draw(): void {
+      if (cleared) return;
+      const lines = renderInlineRun(state, {
+        now: Date.now(),
+        width: WIDGET_WIDTH,
+        label: id,
+        maxLines: WIDGET_MAX_LINES,
+      });
+      if (drawn !== undefined && sameLines(drawn, lines)) return;
+      drawn = lines;
+      ctx.ui.setWidget(key, [...lines]);
+    },
+    clear(): void {
+      if (cleared) return;
+      cleared = true;
+      ctx.ui.setWidget(key, undefined);
+    },
+  };
+}
+
+function sameLines(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((line, index) => line === right[index]);
+}
 
 function finalResult(id: string, settlement: RunSettlement): ForegroundResult {
   if (settlement.kind === "rejected") throw toError(settlement.reason);

package/src/run-id.ts

@@ -0,0 +1,24 @@
+import { customAlphabet } from "nanoid";
+
+/**
+ * Lowercase letters and digits only: a Run id is typed back by a human into
+ * `yaag_status` and `yaag_stop`, so the alphabet holds no case distinction and
+ * no punctuation.
+ */
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+/** Nine random characters over 36 symbols; the `r` prefix is not random. */
+const ID_LENGTH = 9;
+
+const nanoid = customAlphabet(ALPHABET, ID_LENGTH);
+
+/**
+ * Mints one globally unique Run id.
+ *
+ * The id must stay unique across Host Sessions, because Run records outlive the
+ * session that started them (ticket 02); a per-session counter would collide
+ * with every earlier session's `r1`.
+ */
+export function mintRunId(): string {
+  return `r${nanoid()}`;
+}

package/src/run-record.ts

@@ -0,0 +1,91 @@
+import { initialSummary, type RunSummary } from "@yaag/runtime";
+import type { ProcessIdentity } from "./process-liveness.ts";
+
+/**
+ * The durable state of a Run.
+ *
+ * `live` and `finished` are written by the session that owns the Run.
+ * `interrupted` and `orphaned` are written by a later session that found a
+ * `live` record its own memory knows nothing about: the child is dead, or the
+ * child is still running without an owner (ticket 02).
+ */
+export type PersistedRunState = "live" | "finished" | "interrupted" | "orphaned";
+
+/** How a Run ended, reduced to values that survive JSON. */
+export type PersistedOutcome =
+  | { readonly kind: "fulfilled"; readonly code: number | null; readonly result: string }
+  | { readonly kind: "rejected"; readonly reason: string };
+
+/** What starting a Run said about it; enough to describe it in a later session. */
+export interface RunLaunch {
+  readonly file: string;
+  readonly args?: string;
+  readonly record?: string;
+  readonly resume?: string;
+}
+
+/** One Run as stored on disk, at `<runs dir>/<id>.json`. */
+export interface RunRecord {
+  readonly id: string;
+  readonly launch: RunLaunch;
+  readonly process: ProcessIdentity | null;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly state: PersistedRunState;
+  readonly summary: RunSummary;
+  readonly outcome: PersistedOutcome | null;
+}
+
+/**
+ * Narrows an untrusted parsed JSON value to a {@link RunRecord}.
+ *
+ * A record may have been written by an older yaag, or truncated by a crash, so
+ * every field the extension reads is checked here and a record that fails is
+ * dropped rather than repaired.
+ */
+export function isRunRecord(value: unknown): value is RunRecord {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate: Record<string, unknown> = { ...value };
+  return (
+    typeof candidate["id"] === "string" &&
+    typeof candidate["startedAt"] === "string" &&
+    isState(candidate["state"]) &&
+    isLaunch(candidate["launch"]) &&
+    isSummary(candidate["summary"])
+  );
+}
+
+/** A Run record for a Run that has just started. */
+export function startedRecord(options: {
+  readonly id: string;
+  readonly launch: RunLaunch;
+  readonly process: ProcessIdentity | null;
+  readonly now: string;
+}): RunRecord {
+  return {
+    id: options.id,
+    launch: options.launch,
+    process: options.process,
+    startedAt: options.now,
+    endedAt: null,
+    state: "live",
+    summary: initialSummary(),
+    outcome: null,
+  };
+}
+
+function isState(value: unknown): value is PersistedRunState {
+  return (
+    value === "live" || value === "finished" || value === "interrupted" || value === "orphaned"
+  );
+}
+
+function isLaunch(value: unknown): value is RunLaunch {
+  return (
+    typeof value === "object" && value !== null && "file" in value && typeof value.file === "string"
+  );
+}
+
+function isSummary(value: unknown): value is RunSummary {
+  return typeof value === "object" && value !== null && "runState" in value;
+}