@yaag/extension 0.1.0

package/src/run-details.ts

@@ -0,0 +1,294 @@
+import type {
+  AgentActivity,
+  AgentInfo,
+  LifecycleEvent,
+  NodeInfo,
+  RunSummary,
+  TokenBreakdown,
+} from "@yaag/runtime";
+
+/** Renderer-only facts persisted with a Run tool result or completion message. */
+export interface RunDetails {
+  readonly summary: RunSummary;
+  /** Identifies an fd 3 stream occurrence, never an event value or timestamp. */
+  readonly sequence?: number;
+  readonly event?: LifecycleEvent;
+  readonly id?: string;
+  readonly result?: string;
+}
+
+/**
+ * Decodes persisted Run details without throwing.
+ *
+ * Returns undefined when historical or malformed message data cannot safely
+ * reach the tree renderer.
+ */
+export function parseRunDetails(value: unknown): RunDetails | undefined {
+  if (!isRecord(value) || !isRunSummary(value.summary)) return undefined;
+  if (!optionalString(value.id) || !optionalString(value.result)) return undefined;
+  if (!optionalSequence(value.sequence) || !optionalEvent(value.event)) return undefined;
+  return {
+    summary: normalizeAgents(value.summary),
+    ...(value.sequence === undefined ? {} : { sequence: value.sequence }),
+    ...(value.event === undefined ? {} : { event: value.event }),
+    ...(value.id === undefined ? {} : { id: value.id }),
+    ...(value.result === undefined ? {} : { result: value.result }),
+  };
+}
+
+function isRunSummary(value: unknown): value is RunSummary {
+  if (!isRecord(value) || !isSummaryBase(value) || !isAgentMap(value.agents)) return false;
+  if (value.runState === "running") return value.outcome === null && value.ok === null;
+  return (
+    value.runState === "ended" &&
+    isOutcome(value.outcome) &&
+    typeof value.ok === "boolean" &&
+    nullableNumber(value.endedAt)
+  );
+}
+
+function isSummaryBase(value: Record<string, unknown>): boolean {
+  return (
+    typeof value.program === "string" &&
+    nullableNumber(value.startedAt) &&
+    natural(value.asksStarted) &&
+    natural(value.asksSettled) &&
+    number(value.cost) &&
+    nullableTokens(value.tokens) &&
+    typeof value.incomplete === "boolean" &&
+    natural(value.durationMs) &&
+    natural(value.worstFrameGapMs)
+  );
+}
+
+function isAgentMap(value: unknown): boolean {
+  return isRecord(value) && Object.values(value).every(isAgent);
+}
+
+/**
+ * Normalizes each Agent's Nested Node table. A message persisted before the
+ * node table existed carries neither field, and must keep rendering, so the
+ * absent values become an empty table rather than a rejection.
+ */
+function normalizeAgents(value: RunSummary): RunSummary {
+  const agents: Record<string, AgentInfo> = {};
+  for (const [name, agent] of Object.entries(value.agents)) {
+    agents[name] = {
+      ...agent,
+      nodes: agent.nodes ?? [],
+      finishedNodesPruned: agent.finishedNodesPruned ?? 0,
+    };
+  }
+  return { ...value, agents };
+}
+
+function optionalNodes(value: unknown): boolean {
+  return value === undefined || (Array.isArray(value) && value.every(isNode));
+}
+
+function isNode(value: unknown): value is NodeInfo {
+  return (
+    isRecord(value) &&
+    typeof value.path === "string" &&
+    isNodeState(value.state) &&
+    nullableString(value.activityGist) &&
+    nullableTokens(value.tokens) &&
+    nullableNumber(value.cost) &&
+    nullableNumber(value.updatedAt)
+  );
+}
+
+function isNodeState(value: unknown): boolean {
+  return value === "running" || value === "exited" || value === "failed";
+}
+
+function optionalNodeUsage(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!isRecord(value)) return false;
+  return (
+    (value.tokens === undefined || isTokens(value.tokens)) &&
+    (value.cost === undefined || number(value.cost))
+  );
+}
+
+function isAgent(value: unknown): value is AgentInfo {
+  if (!isRecord(value) || !isAgentBase(value)) return false;
+  if (value.state === "asking") {
+    return (
+      natural(value.askIndex) &&
+      typeof value.promptGist === "string" &&
+      typeof value.replayed === "boolean"
+    );
+  }
+  return (
+    (value.state === "idle" || value.state === "exited") &&
+    nullableNatural(value.askIndex) &&
+    nullableString(value.promptGist)
+  );
+}
+
+function isAgentBase(value: Record<string, unknown>): boolean {
+  return (
+    nullableString(value.model) &&
+    nullableString(value.cwd) &&
+    nullableString(value.branch) &&
+    nullableString(value.sessionFile) &&
+    nullableActivity(value.activity) &&
+    nullableTokens(value.tokens) &&
+    nullableNumber(value.cost) &&
+    typeof value.incomplete === "boolean" &&
+    nullableNumber(value.stateChangedAt) &&
+    nullableNumber(value.usageUpdatedAt) &&
+    nullableNumber(value.askStartedAt) &&
+    optionalNodes(value.nodes) &&
+    (value.finishedNodesPruned === undefined || natural(value.finishedNodesPruned))
+  );
+}
+
+function optionalEvent(value: unknown): value is LifecycleEvent | undefined {
+  return value === undefined || isEvent(value);
+}
+
+function isEvent(value: unknown): value is LifecycleEvent {
+  if (!isRecord(value) || !number(value.at) || typeof value.type !== "string") return false;
+  switch (value.type) {
+    case "run_start":
+      return typeof value.program === "string";
+    case "agent_spawn":
+      return (
+        strings(value.agent, value.model, value.cwd) &&
+        optionalString(value.branch) &&
+        optionalString(value.sessionFile)
+      );
+    case "ask_start":
+      return (
+        strings(value.agent, value.promptGist) &&
+        natural(value.index) &&
+        natural(value.promptChars) &&
+        (value.replayed === undefined || value.replayed === true)
+      );
+    case "ask_activity":
+      return strings(value.agent) && natural(value.index) && isActivity(value.activity);
+    case "node_update":
+      return (
+        strings(value.agent, value.path) &&
+        isNodeState(value.state) &&
+        optionalString(value.activityGist) &&
+        optionalNodeUsage(value.usage)
+      );
+    case "ask_output":
+      return (
+        strings(value.agent, value.text) &&
+        natural(value.index) &&
+        (value.channel === "text" || value.channel === "thinking")
+      );
+    case "ask_end":
+      return (
+        strings(value.agent) &&
+        natural(value.index) &&
+        natural(value.durationMs) &&
+        typeof value.ok === "boolean" &&
+        (value.maxFrameGapMs === undefined || natural(value.maxFrameGapMs))
+      );
+    case "agent_usage":
+      return strings(value.agent) && isTokens(value.tokens) && number(value.cost);
+    case "agent_exit":
+      return (
+        strings(value.agent) &&
+        nullableTokens(value.tokens) &&
+        nullableNumber(value.cost) &&
+        typeof value.incomplete === "boolean" &&
+        optionalWorktree(value.worktree)
+      );
+    case "run_end":
+      return (
+        typeof value.ok === "boolean" &&
+        natural(value.durationMs) &&
+        number(value.cost) &&
+        nullableTokens(value.tokens) &&
+        typeof value.incomplete === "boolean" &&
+        natural(value.worstFrameGapMs)
+      );
+    default:
+      return false;
+  }
+}
+
+function nullableActivity(value: unknown): value is AgentActivity | null {
+  return value === null || isActivity(value);
+}
+
+function isActivity(value: unknown): value is AgentActivity {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  switch (value.type) {
+    case "thinking":
+    case "writing":
+    case "compacting":
+      return true;
+    case "tool":
+      return strings(value.name, value.argsGist);
+    case "retrying":
+      return natural(value.attempt) && natural(value.max);
+    default:
+      return false;
+  }
+}
+
+function optionalWorktree(value: unknown): boolean {
+  return value === undefined || (isRecord(value) && strings(value.cwd, value.branch));
+}
+
+function nullableTokens(value: unknown): value is TokenBreakdown | null {
+  return value === null || isTokens(value);
+}
+
+function isTokens(value: unknown): value is TokenBreakdown {
+  return (
+    isRecord(value) &&
+    natural(value.input) &&
+    natural(value.output) &&
+    natural(value.cacheRead) &&
+    natural(value.cacheWrite) &&
+    natural(value.total)
+  );
+}
+
+function isOutcome(value: unknown): boolean {
+  return value === "completed" || value === "failed" || value === "stopped" || value === "paused";
+}
+
+function optionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}
+
+function nullableString(value: unknown): boolean {
+  return value === null || typeof value === "string";
+}
+
+function optionalSequence(value: unknown): value is number | undefined {
+  return value === undefined || natural(value);
+}
+
+function nullableNumber(value: unknown): boolean {
+  return value === null || number(value);
+}
+
+function nullableNatural(value: unknown): boolean {
+  return value === null || natural(value);
+}
+
+function number(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function natural(value: unknown): value is number {
+  return number(value) && value >= 0 && Number.isInteger(value);
+}
+
+function strings(...values: readonly unknown[]): boolean {
+  return values.every((value) => typeof value === "string");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/run-foreground-view.ts

@@ -0,0 +1,95 @@
+/**
+ * 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();
+    },
+  };
+}

package/src/run-foreground.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.
+ *
+ * Both return the same model-visible contract, so opening the interactive view
+ * changes nothing the model can see.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import 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 type { RunTreeStore } from "./run-trees.ts";
+import { toUsage } from "./usage.ts";
+
+/** What `execute` returns for a blocking Run. */
+export interface ForegroundResult {
+  content: { type: "text"; text: string }[];
+  details: RunDetails;
+  usage?: ReturnType<typeof toUsage>;
+}
+
+/**
+ * What a blocking Run needs to be awaited.
+ *
+ * `signal` is the tool call's own abort signal; when it fires, the Run is
+ * stopped through the reap ladder and the call rejects as cancelled.
+ */
+export interface ForegroundOptions {
+  readonly run: LiveRun;
+  readonly registry: RunRegistry;
+  readonly signal: AbortSignal | undefined;
+}
+
+/**
+ * `ForegroundOptions` plus what opening the interactive tree needs.
+ *
+ * Only valid when `interactiveAvailable()` is true; `ctx.ui` is touched on no
+ * other path.
+ */
+export interface InteractiveOptions extends ForegroundOptions {
+  readonly ctx: ExtensionContext;
+  /** Ingested from Run start, so the tree misses no early Ask. */
+  readonly state: TreeState;
+  /** Detaching hands the Run to the combined inline widget. */
+  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 {
+  return !background && ctx.mode === "tui" && ctx.hasUI;
+}
+
+/**
+ * The details-only blocking path, unchanged for rpc and json clients.
+ *
+ * Throws on a failed, killed, or cancelled Run; the message carries the bounded
+ * tail of the Run's own stderr.
+ */
+export async function foregroundResult(options: ForegroundOptions): Promise<ForegroundResult> {
+  const { run, registry, signal } = options;
+  signal?.addEventListener("abort", run.stop, { once: true });
+  if (signal?.aborted === true) run.stop();
+  let settlement: RunSettlement;
+  try {
+    settlement = await observedSettlement(run.id, run.outcome, registry);
+  } finally {
+    signal?.removeEventListener("abort", run.stop);
+  }
+  if (signal?.aborted === true) throw new Error("yaag_run: cancelled");
+  return finalResult(run.id, settlement);
+}
+
+/**
+ * The interactive path: the reader watches the tree while the Run executes, then
+ * dismisses it or detaches the Run.
+ *
+ * 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.
+ */
+export async function foregroundInteractive(
+  options: InteractiveOptions,
+): 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),
+  });
+  options.onOpen?.(view);
+  const abort = (): void => {
+    run.stop();
+    view.close("dismissed");
+  };
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted === true) abort();
+  try {
+    // Kept as a settled-shaped promise so a detach — which leaves this promise
+    // pending — cannot surface as an unhandled rejection.
+    const settled = observedSettlement(run.id, run.outcome, registry).then(
+      (settlement): SettledRace => ({ kind: "settled", settlement }),
+      (reason): SettledRace => ({ kind: "settled", settlement: { 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();
+      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));
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    view.close("dismissed");
+    view.dispose();
+  }
+}
+
+type SettledRace = { readonly kind: "settled"; readonly settlement: RunSettlement };
+
+function finalResult(id: string, settlement: RunSettlement): ForegroundResult {
+  if (settlement.kind === "rejected") throw toError(settlement.reason);
+  const { outcome } = settlement;
+  if (outcome.code !== 0) throw new Error(failure(outcome.code, outcome.stderr));
+  return {
+    content: [{ type: "text", text: outcome.stdout.trimEnd() }],
+    details: { summary: outcome.summary, id, result: outcome.stdout.trimEnd() },
+    usage: toUsage(outcome.summary),
+  };
+}
+
+function detachedResult(run: LiveRun): ForegroundResult {
+  return {
+    content: [{ type: "text", text: `Run ${run.id} continues in the background.` }],
+    details: { summary: run.summary, id: run.id },
+  };
+}

package/src/run-picker.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure Run labels for the `/yaag` Run picker. Kept apart from the command so
+ * the list can be tested without a live UI.
+ */
+import type { RunSummary } from "@yaag/runtime";
+import type { RegisteredRun } from "./run-registry.ts";
+
+/** One Run the picker can open: its id, latest Summary fold, and liveness. */
+export interface PickableRun {
+  readonly id: string;
+  readonly summary: RunSummary;
+  readonly live: boolean;
+}
+
+/** Every registered Run, live and finished, in registration order. */
+export function pickableRuns(runs: readonly RegisteredRun[]): readonly PickableRun[] {
+  return runs.map((run) => ({
+    id: run.run.id,
+    summary: run.run.summary,
+    live: run.state === "live",
+  }));
+}
+
+/** A one-line Run label, e.g. `r1 — review-fanout (running, 3 Agents)`. */
+export function runPickerLabel(run: PickableRun): string {
+  const count = Object.keys(run.summary.agents).length;
+  const plural = count === 1 ? "Agent" : "Agents";
+  const state = run.summary.runState === "ended" ? (run.summary.outcome ?? "ended") : "running";
+  const program = run.summary.program === "" ? "program" : run.summary.program;
+  return `${run.id} — ${program} (${state}, ${count} ${plural})`;
+}
+
+/** The Run a picker label names, or undefined when no Run matches it. */
+export function runFromLabel(
+  runs: readonly PickableRun[],
+  label: string | undefined,
+): PickableRun | undefined {
+  if (label === undefined) return undefined;
+  return runs.find((run) => runPickerLabel(run) === label);
+}

package/src/run-registry.ts

@@ -0,0 +1,107 @@
+import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
+import type { RunOutcome } from "./spawn-run.ts";
+
+/** A Run in flight, including its stop capability and latest Summary fold. */
+export interface LiveRun {
+  readonly id: string;
+  readonly stop: () => void;
+  readonly outcome: Promise<RunOutcome>;
+  summary: RunSummary;
+}
+
+/** The first outcome observed for a retained Run. */
+export type RunSettlement =
+  | { readonly kind: "fulfilled"; readonly outcome: RunOutcome }
+  | { readonly kind: "rejected"; readonly reason: unknown };
+
+/** A completed Run retained for the lifetime of its Host Session. */
+export interface FinishedRun {
+  readonly id: string;
+  readonly summary: RunSummary;
+  readonly outcome: RunSettlement;
+}
+
+/** The retained state of a registered Run. */
+export type RegisteredRun =
+  | { readonly state: "live"; readonly run: LiveRun }
+  | { readonly state: "finished"; readonly run: FinishedRun };
+
+/** What the registry knows about an id. */
+export type RunStatus = RegisteredRun | { readonly state: "unknown" };
+
+/**
+ * Per-session source of truth for every Run started by the Host Session.
+ *
+ * It mints monotonically increasing ids, retains live stop capabilities, and
+ * preserves final outcomes for the rest of the session. Concurrent Runs remain
+ * independently controllable (ADR-0008).
+ */
+export class RunRegistry {
+  #counter = 0;
+  readonly #live = new Map<string, LiveRun>();
+  readonly #runs = new Map<string, RegisteredRun>();
+
+  /** The next Run id for this session; it is never reused. */
+  mint(): string {
+    this.#counter += 1;
+    return `r${this.#counter}`;
+  }
+
+  /** Every currently-live Run, in registration order. */
+  get live(): readonly LiveRun[] {
+    return [...this.#live.values()];
+  }
+
+  /** Every registered Run, live and finished, in registration order. */
+  get runs(): readonly RegisteredRun[] {
+    return [...this.#runs.values()];
+  }
+
+  /** Every registered Run id, in registration order. */
+  get knownIds(): readonly string[] {
+    return [...this.#runs.keys()];
+  }
+
+  /** Registers a newly-started Run and synchronously observes its settlement. */
+  add(run: LiveRun): void {
+    this.#live.set(run.id, run);
+    this.#runs.set(run.id, { state: "live", run });
+    void run.outcome.then(
+      (outcome) => this.finish(run.id, outcome),
+      (reason: unknown) => this.reject(run.id, reason),
+    );
+  }
+
+  /** Looks up a live capability or the retained completed Run. */
+  lookup(id: string): RunStatus {
+    return this.#runs.get(id) ?? { state: "unknown" };
+  }
+
+  /**
+   * Retains a Run's first observed final outcome and removes only its live
+   * capability. Repeated observers are harmless and cannot overwrite history.
+   */
+  finish(id: string, outcome: RunOutcome): void {
+    this.#settle(id, outcome.summary, { kind: "fulfilled", outcome });
+  }
+
+  /** Retains a rejected child outcome with its latest terminal accounting projection. */
+  reject(id: string, reason: unknown): void {
+    const record = this.#runs.get(id);
+    if (record === undefined || record.state === "finished") return;
+    this.#settle(id, failedSummary(record.run.summary), { kind: "rejected", reason });
+  }
+
+  #settle(id: string, summary: RunSummary, outcome: RunSettlement): void {
+    const record = this.#runs.get(id);
+    if (record === undefined || record.state === "finished") return;
+    this.#live.delete(id);
+    this.#runs.set(id, { state: "finished", run: { id, summary, outcome } });
+  }
+}
+
+function failedSummary(summary: RunSummary): EndedRunSummary {
+  if (summary.runState === "ended")
+    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
+  return { ...summary, runState: "ended", outcome: "failed", ok: false, endedAt: null };
+}