@yaag/extension 0.1.4 → 0.2.1

package/src/spawn-run.ts

@@ -38,6 +38,8 @@ export interface SpawnRunOptions extends StartRunOptions {
 export interface RunHandle {
   readonly outcome: Promise<RunOutcome>;
   readonly stop: () => void;
+  /** The child's pid, when the spawn produced one. */
+  readonly pid?: number | undefined;
 }
 
 /**
@@ -65,7 +67,7 @@ export function startRun(options: StartRunOptions): RunHandle {
           options.onProgress?.(summary, event, sequence);
         }),
   ]).then(([ended]) => ({ ...ended, summary }));
-  return { outcome, stop: child.stop };
+  return { outcome, stop: child.stop, pid: child.pid };
 }
 
 /**

package/src/status-tool.ts

@@ -2,7 +2,8 @@ import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-
 import type { RunSummary } from "@yaag/runtime";
 import { renderSnapshot, TreeState } from "@yaag/tui";
 import { Type } from "typebox";
-import type { RegisteredRun, RunRegistry } from "./run-registry.ts";
+import type { PersistedRunState } from "./run-record.ts";
+import type { RegisteredRun, RestoredRun, RunRegistry } from "./run-registry.ts";
 import { toUsage } from "./usage.ts";
 
 const parameters = Type.Object({
@@ -25,10 +26,15 @@ export interface StatusToolOptions {
 }
 
 const DESCRIPTION = [
-  "Show a snapshot of a Run started in this Host Session.",
+  "Show a snapshot of a Run started by yaag_run.",
   "",
   "With an id, returns that Run's live snapshot or its retained final snapshot.",
-  "Without an id, lists every Run started this session in registration order.",
+  "Run records outlive the Host Session, so an id from an earlier session still",
+  "resolves: a Run whose process died is reported as interrupted, and a Run whose",
+  "process is still alive is reported as orphaned.",
+  "",
+  "Without an id, lists this session's Runs plus every orphaned or interrupted",
+  "Run left by an earlier session.",
 ].join("\n");
 
 /**
@@ -50,7 +56,7 @@ export function createStatusTool(
     parameters,
     async execute(_id, params) {
       if (params.id === undefined) return overview(registry.runs, now, width);
-      const found = registry.lookup(params.id);
+      const found = await registry.recall(params.id);
       if (found.state === "unknown") throw unknownId(params.id, registry.knownIds);
       const details = detailsFor(found);
       return {
@@ -85,6 +91,7 @@ function overview(
 
 function detailsFor(run: RegisteredRun): SnapshotDetails {
   if (run.state === "live") return { id: run.run.id, summary: run.run.summary };
+  if (run.state === "restored") return restoredDetails(run.run);
   const { outcome } = run.run;
   return {
     id: run.run.id,
@@ -95,6 +102,34 @@ function detailsFor(run: RegisteredRun): SnapshotDetails {
   };
 }
 
+/**
+ * A Run of an earlier Host Session. Its persisted state is stated in the
+ * Result region, because the folded Summary alone cannot say that nobody owns
+ * the Run any more (ticket 02).
+ */
+function restoredDetails(run: RestoredRun): SnapshotDetails {
+  const { record } = run;
+  const state = `Run ${record.id} is ${record.state} (started ${record.startedAt}).`;
+  const alive =
+    record.state === "orphaned" && record.process !== null
+      ? ` Its process ${record.process.pid} is still running; stop it with yaag_stop.`
+      : "";
+  const detail = `${alive}${resumeHint(record.state, run.summary.artifact)}`;
+  const result = record.outcome?.kind === "fulfilled" ? `\n${record.outcome.result}` : "";
+  return { id: record.id, summary: run.summary, result: `${state}${detail}${result}` };
+}
+
+/**
+ * Names the Checkpoint an unowned Run left behind (ADR-0031). The Run
+ * republishes it at each Ask boundary, so it exists whenever the Run reached
+ * one, for a dead Run and for a still-running orphan alike.
+ */
+function resumeHint(state: PersistedRunState, artifact: string | null): string {
+  if (artifact === null) return "";
+  if (state !== "interrupted" && state !== "orphaned") return "";
+  return ` Resume it from its checkpoint: ${artifact}.`;
+}
+
 function snapshot(
   details: SnapshotDetails,
   now: () => number,

package/src/stop-tool.ts

@@ -1,7 +1,8 @@
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { RunSummary } from "@yaag/runtime";
 import { Type } from "typebox";
-import type { RunRegistry } from "./run-registry.ts";
+import { isProcessAlive } from "./process-liveness.ts";
+import type { RestoredRun, RunRegistry } from "./run-registry.ts";
 import { toUsage } from "./usage.ts";
 
 /** What the stop result carries for rendering — never shown to the model. */
@@ -18,6 +19,9 @@ const DESCRIPTION = [
   "",
   "The Run's Agents are reaped, and the report says what it got through and what",
   "it spent before it stopped.",
+  "",
+  "An orphaned Run left behind by an earlier Host Session is stopped too: its",
+  "process group is killed, and the report holds its last persisted Summary.",
 ].join("\n");
 
 /** What a stopped Run got through and what it cost, from the fold (ADR-0006). */
@@ -62,6 +66,38 @@ function agentStateReport(agent: RunSummary["agents"][string]): string {
   }
 }
 
+/**
+ * Ends a Run nobody owns any more. There is no reap ladder to run — its pipes
+ * belong to a dead Host Session — so the process group is killed outright
+ * (ADR-0008). The pid is re-probed first, because a record can name a pid that
+ * a different process has since inherited (ticket 02).
+ */
+function stopOrphan(run: RestoredRun): AgentToolResult<StopDetails> {
+  const { record } = run;
+  if (record.state !== "orphaned" || record.process === null)
+    throw new Error(`yaag_stop: Run ${record.id} has already finished`);
+  if (!isProcessAlive(record.process))
+    throw new Error(`yaag_stop: Run ${record.id} is no longer running`);
+  killGroup(record.process.pid);
+  return {
+    content: [{ type: "text", text: stopReport(record.id, record.summary) }],
+    details: { summary: record.summary },
+    usage: toUsage(record.summary),
+  };
+}
+
+function killGroup(pid: number): void {
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // The process ended between the liveness probe and the signal.
+    }
+  }
+}
+
 function toError(reason: unknown): Error {
   return reason instanceof Error ? reason : new Error(String(reason));
 }
@@ -82,10 +118,12 @@ export function createStopTool(
     description: DESCRIPTION,
     parameters,
     async execute(_id, params) {
-      const status = registry.lookup(params.id);
+      const status = await registry.recall(params.id);
       switch (status.state) {
         case "unknown":
           throw new Error(`yaag_stop: no Run with id ${params.id}`);
+        case "restored":
+          return stopOrphan(status.run);
         case "finished":
           throw new Error(`yaag_stop: Run ${params.id} has already finished`);
         case "live": {

package/src/test-tui-context.ts

@@ -1,5 +1,6 @@
 /**
- * A tui-mode ExtensionContext double for the interactive foreground view.
+ * A tui-mode ExtensionContext double for the `/yaag` view and the inline
+ * frames of a blocking Run.
  *
  * `ui.custom` invokes the factory synchronously against a fake TUI, so a test
  * can feed key bytes and read rendered frames. `TestExtensionContext` still
@@ -62,6 +63,11 @@ export class TestTuiContext implements ExtensionContext {
     return this.ui.widgets;
   }
 
+  /** The latest footer segment text per key. */
+  get statuses(): ReadonlyMap<string, string | undefined> {
+    return this.ui.statuses;
+  }
+
   /** Scripted answers for `ui.select`, consumed in order. */
   get selections(): string[] {
     return this.ui.selections;

package/src/yaag-command.ts

@@ -1,26 +1,19 @@
 /**
- * The `/yaag` command (spec §4): pick a Run of this session and open the same
- * interactive tree the foreground `yaag_run` opens, over the background
- * surface.
+ * The `/yaag` command (ADR-0008): pick a Run of this session and open the
+ * interactive tree over it.
  *
  * It replaces `/yaag-peek`'s Run→Agent→menu picker chain: every surviving
  * action lives in the tree's per-node menu, and the view stays read-only apart
- * from the Run's own reap-ladder stop. In a settled view `esc` closes it; in a
- * live view `q` opens the three-way prompt, where `Detach (keep running)`
- * means "close the view, the Run keeps running".
+ * from the Run's own reap-ladder stop. `esc` at tree level closes the view,
+ * live or settled, and a live Run keeps executing after that; `ctrl+q` opens
+ * the two-way Stop Run prompt.
  */
 import type {
   ExtensionContext,
   ExtensionUIContext,
   RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
-import {
-  createRunTreeView,
-  type RunTreeViewHost,
-  type RunViewExit,
-  type RunViewResult,
-  TreeState,
-} from "@yaag/tui";
+import { createRunTreeView, type RunTreeViewHost, type RunViewResult, TreeState } from "@yaag/tui";
 import { type PickableRun, pickableRuns, runFromLabel, runPickerLabel } from "./run-picker.ts";
 import type { RunRegistry, RunSettlement } from "./run-registry.ts";
 import { observedSettlement, viewResult } from "./run-settlement.ts";
@@ -102,17 +95,17 @@ async function openRun(
   // neither the view nor the renderer.
   let live = true;
   try {
-    await ctx.ui.custom<RunViewExit>((tui, _theme, keybindings, done) => {
+    await ctx.ui.custom<void>((tui, _theme, keybindings, done) => {
       const host: RunTreeViewHost = {
         ...createRunTreeHost({ ui: ctx.ui, tui, keybindings, state }),
         stop: () => {
           if (found.state === "live") found.run.stop();
         },
-        // The Run is already a background Run: leaving the view is the detach.
-        detach: () => {},
-        done,
+        // The Run keeps executing after the view closes; there is nothing to
+        // hand over, because a Run of this session is already addressable.
+        done: () => done(),
       };
-      const view = createRunTreeView({ state, host, label: run.id, surface: "background" });
+      const view = createRunTreeView({ state, host, label: run.id });
       if (found.state === "finished")
         settle(state, view, found.run.outcome, options.registry, run.id);
       else if (found.state === "live") {
@@ -120,7 +113,7 @@ async function openRun(
           if (id === run.id && live) view.touch();
         });
         // A view opened while live must reach the settled phase itself, or `esc`
-        // would keep live behavior after the Run ended (spec §4).
+        // would keep live behavior after the Run ended (ADR-0008).
         const onSettled = (settlement: RunSettlement): void => {
           if (!live) return;
           settle(state, view, settlement, options.registry, run.id);

package/src/background-widget.ts

@@ -1,107 +0,0 @@
-/**
- * The single combined inline widget for every live background Run (spec §1).
- *
- * One pi widget key holds every Run, so a Run starting or ending costs no
- * extra scrollback. The frame is a `string[]`, which pi never routes input to,
- * so the widget consumes no key by construction.
- */
-import { renderRunsWidget, type WidgetRun } from "@yaag/tui";
-import type { RunRegistry } from "./run-registry.ts";
-import type { RunTreeStore } from "./run-trees.ts";
-
-/** The one pi widget key; every Run shares it. */
-export const WIDGET_KEY = "yaag-runs";
-
-/** The only pi capability the widget needs. */
-export interface WidgetSurface {
-  setWidget(key: string, lines: string[] | undefined): void;
-}
-
-/**
- * What the combined widget needs: the Run registry it reads live Runs from,
- * the projection store it reads their `TreeState` from, and the render budget.
- */
-export interface BackgroundWidgetOptions {
-  readonly registry: RunRegistry;
-  readonly store: RunTreeStore;
-  readonly now?: () => number;
-  readonly width?: number;
-  readonly maxLines?: number;
-}
-
-/** The widget controller: bind it once, then refresh it on every occurrence. */
-export interface BackgroundWidget {
-  /**
-   * Binds the pi UI surface, once the Host Session has one, and draws the
-   * current frame. A `WidgetSurface.setWidget()` that throws propagates here.
-   */
-  bind(surface: WidgetSurface): void;
-  /**
-   * Redraws the frame; drops the redraw before `bind`, and skips an unchanged
-   * frame. A bound `WidgetSurface.setWidget()` that throws propagates here.
-   */
-  refresh(): void;
-  /**
-   * Unsubscribes from the store and clears the widget. A bound
-   * `WidgetSurface.setWidget()` that throws propagates here.
-   */
-  dispose(): void;
-}
-
-/**
- * Builds the combined widget over this session's Run registry and projections.
- *
- * An unbound controller drops every refresh, and a Run without a projection is
- * skipped. Construction itself never throws, but `bind()`, `refresh()`, and
- * `dispose()` call the caller's `WidgetSurface.setWidget()` and propagate
- * whatever it throws; the store subscription also propagates it into the
- * `ingest()` that caused the redraw.
- */
-export function createBackgroundWidget(options: BackgroundWidgetOptions): BackgroundWidget {
-  const now = options.now ?? Date.now;
-  const width = options.width ?? 100;
-  let surface: WidgetSurface | undefined;
-  let drawn: readonly string[] | undefined;
-
-  const entries = (): readonly WidgetRun[] => {
-    const runs: WidgetRun[] = [];
-    for (const run of options.registry.live) {
-      if (options.store.kind(run.id) !== "background") continue;
-      const state = options.store.get(run.id);
-      if (state !== undefined) runs.push({ id: run.id, state });
-    }
-    return runs;
-  };
-
-  const refresh = (): void => {
-    if (surface === undefined) return;
-    const lines = renderRunsWidget(entries(), {
-      now: now(),
-      width,
-      ...(options.maxLines === undefined ? {} : { maxLines: options.maxLines }),
-    });
-    if (drawn !== undefined && sameLines(drawn, lines)) return;
-    drawn = lines;
-    surface.setWidget(WIDGET_KEY, lines.length === 0 ? undefined : [...lines]);
-  };
-
-  const unsubscribe = options.store.subscribe(() => refresh());
-
-  return {
-    bind(bound: WidgetSurface): void {
-      surface = bound;
-      drawn = undefined;
-      refresh();
-    },
-    refresh,
-    dispose(): void {
-      unsubscribe();
-      surface?.setWidget(WIDGET_KEY, undefined);
-      surface = undefined;
-    },
-  };
-}
-
-function sameLines(left: readonly string[], right: readonly string[]): boolean {
-  return left.length === right.length && left.every((line, index) => line === right[index]);
-}

package/src/run-foreground-view.ts

@@ -1,95 +0,0 @@
-/**
- * Opens the interactive Run tree for a blocking `yaag_run` in tui mode
- * (spec §4), and adapts the Host Session's capabilities to
- * `RunTreeViewHost`.
- *
- * The host surface is read-only except for the Run's own reap-ladder stop and
- * the detach request: nothing here can prompt an Agent (ADR — a Peek observes,
- * it never sends).
- */
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-  createRunTreeView,
-  type RunTreeView,
-  type RunTreeViewHost,
-  type RunViewExit,
-  type TreeState,
-} from "@yaag/tui";
-import { createRunTreeHost } from "./run-tree-host.ts";
-
-/**
- * What `openRunTreeView` needs to adapt one Run to the interactive view.
- *
- * The caller must supply a tui-mode `ctx` with UI; `openRunTreeView` throws
- * when `ctx.ui` is absent, because there is no surface to open.
- */
-export interface OpenRunTreeViewOptions {
-  readonly ctx: ExtensionContext;
-  /** Created and ingested from Run start, so no early Ask is missed. */
-  readonly state: TreeState;
-  readonly id: string;
-  /** Runs the reap ladder for this Run (ADR-0008). */
-  stop(): void;
-  /** Converts the Run to a background Run. */
-  onDetach(): void;
-}
-
-/** The opened view: its exit promise, plus the handles the tool drives. */
-export interface OpenedRunTreeView {
-  /** Resolves when the reader dismisses or detaches the view. */
-  readonly exit: Promise<RunViewExit>;
-  /** The Run settled; freeze the tree and show the Result region. */
-  settle(result: Parameters<RunTreeView["settle"]>[0]): void;
-  /** A pushed fd 3 update landed in the TreeState; redraw. */
-  touch(): void;
-  /** Closes the view from the host's side, e.g. on an abort. */
-  close(exit: RunViewExit): void;
-  dispose(): void;
-}
-
-/**
- * Opens the view through `ctx.ui.custom()`.
- *
- * The returned `exit` promise always settles: the reader's `q`/detach resolves
- * it, and `close` resolves it for a host-side abort, so a tool call can never
- * hang on the view.
- */
-export function openRunTreeView(options: OpenRunTreeViewOptions): OpenedRunTreeView {
-  const state = options.state;
-  let view: RunTreeView | undefined;
-  let finish: ((exit: RunViewExit) => void) | undefined;
-  let pendingExit: RunViewExit | undefined;
-  let pendingSettle: Parameters<RunTreeView["settle"]>[0] | undefined;
-
-  const exit = options.ctx.ui.custom<RunViewExit>((tui, _theme, keybindings, done) => {
-    finish = done;
-    const host: RunTreeViewHost = {
-      ...createRunTreeHost({ ui: options.ctx.ui, tui, keybindings, state }),
-      stop: options.stop,
-      detach: options.onDetach,
-      done,
-    };
-    view = createRunTreeView({ state, host, label: options.id, surface: "foreground" });
-    if (pendingSettle !== undefined) view.settle(pendingSettle);
-    if (pendingExit !== undefined) done(pendingExit);
-    return view;
-  });
-
-  return {
-    exit,
-    settle(result): void {
-      if (view === undefined) pendingSettle = result;
-      else view.settle(result);
-    },
-    touch(): void {
-      view?.touch();
-    },
-    close(kind): void {
-      if (finish === undefined) pendingExit = kind;
-      else finish(kind);
-    },
-    dispose(): void {
-      view?.dispose();
-    },
-  };
-}