@yaag/extension 0.1.0

package/src/test-tui-context.ts

@@ -0,0 +1,107 @@
+/**
+ * A tui-mode ExtensionContext double for the interactive foreground view.
+ *
+ * `ui.custom` invokes the factory synchronously against a fake TUI, so a test
+ * can feed key bytes and read rendered frames. `TestExtensionContext` still
+ * covers the rpc/json path, where every `ui` access must throw.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  FakeExtensionUi,
+  type Notice,
+  type OpenedComponent,
+  type OpenedEditor,
+} from "./fake-extension-ui.ts";
+
+export type { OpenedComponent } from "./fake-extension-ui.ts";
+
+export interface TestTuiContextOptions {
+  /** Terminal rows the fake TUI reports. */
+  readonly rows?: number;
+}
+
+/**
+ * A tui context whose UI is `FakeExtensionUi`: `custom`, `notify`, and
+ * `editor` work, and every other capability throws on access, so an
+ * accidental dependency fails loudly.
+ */
+export class TestTuiContext implements ExtensionContext {
+  readonly mode: ExtensionContext["mode"] = "tui";
+  readonly hasUI = true;
+  readonly model: ExtensionContext["model"] = undefined;
+  readonly scopedModels: ExtensionContext["scopedModels"] = [];
+  readonly signal: ExtensionContext["signal"] = undefined;
+  readonly ui: FakeExtensionUi;
+
+  constructor(
+    readonly cwd: string,
+    options: TestTuiContextOptions = {},
+  ) {
+    this.ui = new FakeExtensionUi({
+      ...(options.rows === undefined ? {} : { rows: options.rows }),
+    });
+  }
+
+  /** The component `ui.custom` opened, once a Run has opened one. */
+  get opened(): OpenedComponent | undefined {
+    return this.ui.opened;
+  }
+
+  /** Notifications the view sent to the Host Session. */
+  get notices(): readonly Notice[] {
+    return this.ui.notices;
+  }
+
+  /** Editors the view opened. */
+  get edits(): readonly OpenedEditor[] {
+    return this.ui.edits;
+  }
+
+  /** The latest inline widget frame per key. */
+  get widgets(): ReadonlyMap<string, string[] | undefined> {
+    return this.ui.widgets;
+  }
+
+  /** Scripted answers for `ui.select`, consumed in order. */
+  get selections(): string[] {
+    return this.ui.selections;
+  }
+
+  get sessionManager(): ExtensionContext["sessionManager"] {
+    return unavailable("sessionManager");
+  }
+
+  get modelRegistry(): ExtensionContext["modelRegistry"] {
+    return unavailable("modelRegistry");
+  }
+
+  isIdle(): boolean {
+    return true;
+  }
+
+  isProjectTrusted(): boolean {
+    return true;
+  }
+
+  abort(): void {}
+
+  hasPendingMessages(): boolean {
+    return false;
+  }
+
+  shutdown(): void {}
+
+  getContextUsage(): ReturnType<ExtensionContext["getContextUsage"]> {
+    return undefined;
+  }
+
+  compact(): void {}
+
+  getSystemPrompt(): string {
+    return "";
+  }
+}
+
+function unavailable<T>(dependency: string): T {
+  throw new Error(`unexpected test context dependency: ${dependency}`);
+}

package/src/usage.ts

@@ -0,0 +1,26 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { RunSummary } from "@yaag/runtime";
+
+/** pi's nested-usage shape, taken from the tool result so no extra dependency is needed. */
+type Usage = NonNullable<AgentToolResult<unknown>["usage"]>;
+
+/**
+ * Maps a Run Summary onto pi's nested-usage channel, so the Host Session's own
+ * accounting absorbs what the Run spent (ADR-0006).
+ *
+ * Undefined when the Summary's token total is unknown: pi would read a partial
+ * sum as a total, and an undercount is worse than a gap (ADR-0012). The Run's
+ * cost is only known in total, so it lands on `cost.total` alone.
+ */
+export function toUsage(summary: RunSummary): Usage | undefined {
+  const tokens = summary.tokens;
+  if (tokens === null) return undefined;
+  return {
+    input: tokens.input,
+    output: tokens.output,
+    cacheRead: tokens.cacheRead,
+    cacheWrite: tokens.cacheWrite,
+    totalTokens: tokens.total,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: summary.cost },
+  };
+}

package/src/yaag-command.ts

@@ -0,0 +1,163 @@
+/**
+ * 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.
+ *
+ * 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".
+ */
+import type {
+  ExtensionContext,
+  ExtensionUIContext,
+  RegisteredCommand,
+} from "@earendil-works/pi-coding-agent";
+import {
+  createRunTreeView,
+  type RunTreeViewHost,
+  type RunViewExit,
+  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";
+import { createRunTreeHost } from "./run-tree-host.ts";
+import type { RunTreeStore } from "./run-trees.ts";
+
+type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+
+const DESCRIPTION = "Open the interactive Run tree for a Run of this session";
+
+/** The per-session state `/yaag` reads: Run records plus their projections. */
+export interface YaagCommandOptions {
+  readonly registry: RunRegistry;
+  readonly store: RunTreeStore;
+}
+
+/** Everything `/yaag` needs from its pi context, and nothing more. */
+export interface YaagContext {
+  readonly mode: ExtensionContext["mode"];
+  readonly ui: Pick<ExtensionUIContext, "notify" | "select" | "custom" | "editor">;
+}
+
+/** Builds the `/yaag` command bound to this session's registry and projections. */
+export function createYaagCommand(options: YaagCommandOptions): CommandOptions {
+  return {
+    description: DESCRIPTION,
+    handler: async (_args, ctx) => {
+      await runYaagCommand(ctx, options);
+    },
+  };
+}
+
+/**
+ * Lists this session's Runs and opens the interactive tree for the chosen one.
+ *
+ * Resolves without opening anything when there is no Run, when the client is
+ * not the TUI, or when the reader cancels the picker.
+ */
+export async function runYaagCommand(ctx: YaagContext, options: YaagCommandOptions): Promise<void> {
+  const runs = pickableRuns(options.registry.runs);
+  if (runs.length === 0) {
+    ctx.ui.notify("yaag: no Runs started this session.", "info");
+    return;
+  }
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify("yaag: the Run tree needs the TUI; use yaag_status instead.", "warning");
+    return;
+  }
+  const run = await pickRun(ctx, runs);
+  if (run === undefined) return;
+  await openRun(ctx, run, options);
+}
+
+async function pickRun(
+  ctx: YaagContext,
+  runs: readonly PickableRun[],
+): Promise<PickableRun | undefined> {
+  const only = runs[0];
+  if (runs.length === 1 && only !== undefined) return only;
+  return runFromLabel(runs, await ctx.ui.select("yaag — pick a Run", runs.map(runPickerLabel)));
+}
+
+/**
+ * Opens the tree for one Run and resolves when the reader leaves it.
+ *
+ * A live Run keeps executing whatever the reader does here; a settled Run
+ * opens already frozen, with its Result region filled in.
+ */
+async function openRun(
+  ctx: YaagContext,
+  run: PickableRun,
+  options: YaagCommandOptions,
+): Promise<void> {
+  const state = options.store.get(run.id) ?? TreeState.fromSummary(run.summary);
+  const found = options.registry.lookup(run.id);
+  let unsubscribe: (() => void) | undefined;
+  // The observer below outlives no more than the `ctx.ui.custom()` call: once
+  // the view exits or the UI call rejects, a later settlement must touch
+  // neither the view nor the renderer.
+  let live = true;
+  try {
+    await ctx.ui.custom<RunViewExit>((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,
+      };
+      const view = createRunTreeView({ state, host, label: run.id, surface: "background" });
+      if (found.state === "finished")
+        settle(state, view, found.run.outcome, options.registry, run.id);
+      else if (found.state === "live") {
+        unsubscribe = options.store.subscribe((id) => {
+          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).
+        const onSettled = (settlement: RunSettlement): void => {
+          if (!live) return;
+          settle(state, view, settlement, options.registry, run.id);
+        };
+        void observedSettlement(run.id, found.run.outcome, options.registry)
+          .then(onSettled, (reason: unknown) => {
+            onSettled({ kind: "rejected", reason });
+          })
+          // A throwing view or renderer must not become an unhandled rejection.
+          .catch(() => {});
+      }
+      return view;
+    });
+  } finally {
+    live = false;
+    unsubscribe?.();
+  }
+}
+
+/**
+ * Freezes the view on the Run's retained settlement, after topping the
+ * projection up with the registry's retained final Summary.
+ *
+ * The top-up is unconditional: an already-ended projection can still hold a
+ * successful Summary that the registry later converted to failed accounting,
+ * for example when the outcome promise rejects after fd 3 delivered `run_end`.
+ * Skipping the top-up there would render a `completed` header beside a failed
+ * Result.
+ */
+function settle(
+  state: TreeState,
+  view: { settle(result: RunViewResult): void },
+  settlement: RunSettlement,
+  registry: RunRegistry,
+  id: string,
+): void {
+  const found = registry.lookup(id);
+  if (found.state === "finished") state.ingest({ summary: found.run.summary });
+  view.settle(viewResult(settlement));
+}