@yaag/extension 0.1.0

package/README.md

@@ -0,0 +1,218 @@
+# @yaag/extension
+
+The yaag pi extension: run Orchestration Programs from a pi session.
+
+It is loaded by pi through jiti, in **Node**, and bridges to the `yaag` CLI,
+which runs on **Bun** (ADR-0005, ADR-0015).
+
+## Prerequisites
+
+**Bun is required.** The extension itself runs in pi's Node process, but every
+Orchestration Program runs on Bun. Bun must be on `PATH`, or at `~/.bun/bin/bun`:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+A missing Bun is reported once, when the extension loads, naming what to
+install — never as an `ENOENT` at the first tool call.
+
+## Install
+
+```bash
+pi install ./packages/extension     # from the monorepo root
+```
+
+Pi records the local path without copying, so the `workspace:*` dependency on
+the CLI resolves through the monorepo's `node_modules`. No publish, no bundle,
+no version bump.
+
+For a throwaway session instead: `pi -e ./packages/extension`.
+
+## What it provides
+
+### `yaag_run`
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `file` | `string` | Path to the Orchestration Program file |
+| `args` | `string?` | The program's arguments, as a JSON object string |
+| `background` | `boolean?` | Start the Run in the background and return its Run id |
+| `record` | `string?` | Write this Run's Cassette artifact to this path |
+| `resume` | `string?` | Replay a matching Cassette prefix, then continue live |
+
+Blocking by default: the call returns when the Run ends, and its content is the
+Run's return value. With `background: true` it returns at once with a short Run
+id (`r1`, `r2`, …) and the result arrives later as a follow-up message that
+triggers a turn. Background Runs may overlap; each has its own id and stop handle.
+
+The model sees only the Run's value (or the id). The user additionally sees the
+Run Summary — program, Agents, Asks settled, cost — refreshed after every
+Lifecycle Event. Blocking completion and `yaag_stop` report token usage on pi's
+nested-usage channel. Natural background completion is the exception: pi custom
+follow-ups have no usage field, so their summaries remain available for rendering
+without changing Host Session token or cost totals.
+
+### `yaag_describe`
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `file` | `string` | Path to the Orchestration Program file |
+
+Returns the program's declared `{ name, description, args }` contract verbatim.
+Use it to discover a known program's arguments before calling `yaag_run`; it does
+not execute the Run or enumerate programs.
+
+### `yaag_setup_workspace`
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `dir` | `string?` | Workspace root; omitted uses pi's current working directory |
+
+Use this when an Orchestration Program author sees missing `@yaag/runtime` editor/type
+resolution in their workspace. `dir` is optional and defaults to pi's current working
+directory. Normally run setup once for that workspace, and rerun it when an upgrade
+needs to refresh generated declarations. Its content is the CLI's verbatim per-artifact
+written/skipped report. Setup is not a Run: it has no Run id, summary, progress, usage,
+cassette, or follow-up behavior.
+
+### `yaag_stop`
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `id` | `string` | The Run id to stop, as returned by `yaag_run` |
+
+Reaps the Run's Agents and reports what it got through and what it spent:
+program, Agents seen, Asks settled, cost and tokens. Costs are reported as
+"at least" when the Summary is incomplete.
+
+### `/yaag-status`
+
+Shows the resolved `bun` executable and CLI entry point.
+
+### `/yaag-setup-workspace [dir]`
+
+Creates or refreshes editor type support for Orchestration Programs under `.yaag/`.
+The directory argument is optional and defaults to pi's current working directory.
+It displays the CLI's per-artifact written/skipped report. This is the user-facing
+counterpart of `yaag_setup_workspace`, not a Run: it has no Run id, summary,
+progress, usage, cassette, or follow-up behavior.
+
+## Where Orchestration Programs live
+
+By **convention**, in a `.yaag/` directory in your project — but nothing enforces
+that location, and `file` accepts any path. Run `yaag_setup_workspace` once to create
+`.yaag/tsconfig.json` and refresh `.yaag/types/`. The CLI vendors its runtime and
+TypeBox declarations there, so editors and type checkers work without installing
+workspace dependencies; execution separately uses the runtime shipped with the CLI.
+Setup creates no program scaffold: authored programs remain yours, separate from its
+generated declarations. In this monorepo the convention is
+[`examples/`](../../examples). A program is a user-authored TypeScript file whose
+default export is `defineRun({ run })`. Use file tools to find a known program, then use
+`yaag_describe({ file })` to discover its declared contract and arguments.
+
+## A worked example
+
+`.yaag/review.ts`:
+
+```ts
+import { defineRun, prompt } from "@yaag/runtime";
+
+export default defineRun({
+  name: "review",
+  description: "Review the working tree from one angle.",
+  run: async (ctx) => {
+    const agent = await ctx.spawn({
+      name: "reviewer",
+      tools: ["read", "grep"],
+      disallowedTools: ["yaag_run"],
+      skills: ["review"],
+      disallowedSkills: [],
+    });
+    return agent.ask(
+      prompt`
+        Audit this repo for issues.
+        Report the top three.
+      `,
+      {
+        maxTurns: 4,
+        maxToolCalls: 12,
+        maxDurationMs: 60_000,
+        wrapUpPrompt: "Give the findings now.",
+      },
+    );
+  },
+});
+```
+
+## Program author controls
+
+`prompt\`…\`` dedents static prompt text while preserving interpolated values.
+`tools` / `disallowedTools` and `skills` / `disallowedSkills` are spawn-level
+restrictions: a skill is a portable name, never a `SKILL.md` path. Tool allowlists
+are applied before denylists; explicit empty allowlists disable flag-controllable
+items.
+
+`maxTurns`, `maxToolCalls`, and `maxDurationMs` are per-Ask soft limits. They
+steer an Agent to wrap up, then abort only after grace; an `ASK_LIMIT` rejection
+is recoverable and the Handle can be asked again. `wrapUpPrompt` replaces the
+default steering message. This is intentionally different from `timeoutMs`, the
+destructive fallback that rejects with `ASK_TIMEOUT` and closes the Agent.
+
+The tool call:
+
+```json
+{ "file": ".yaag/review.ts", "args": "{\"focus\":\"security\"}" }
+```
+
+For this blocking call, what comes back:
+
+- **content** — the Run's return value, the reviewer's report (this is what the
+  model reads)
+- **details** — the Run Summary, rendered for the user
+- **usage** — the token breakdown: input, output, cache read, cache write, total
+
+The background variant:
+
+```json
+{ "file": ".yaag/review.ts", "background": true }
+```
+
+returns `Run r1 started in the background.` immediately; progress keeps
+streaming into the fold, and when the Run ends a follow-up message arrives with
+its value and final Run Summary in non-model-visible `details`. Pi's custom
+follow-up API has no nested-usage field, so natural completion does not alter
+Host Session token or cost totals. `yaag_stop({ "id": "r1" })` ends it early
+and reports its nested usage through the stop tool result.
+
+## Both entry points, one execution path
+
+```sh
+bun apps/yaag/src/cli.ts run .yaag/review.ts
+```
+
+and `yaag_run` are the same execution path. The extension spawns exactly this
+CLI as a child — `bun cli.ts run <file> --events-fd 3 --args <json>` — and reads
+structured Lifecycle Events from descriptor 3 while the CLI's own stderr format
+stays unchanged. **What you debug in a terminal is what the session runs.**
+
+## How stopping works
+
+One ladder, taken by every route: pressing Esc during a blocking Run, calling
+`yaag_stop` on a background Run, or closing the session.
+
+1. **stdin EOF** — the extension closes the child's stdin; the CLI unwinds
+   through the runtime's own Agent reap ladder.
+2. **SIGTERM** — if the CLI is still there.
+3. **group SIGKILL** — only if the CLI ignored both.
+
+It is the runtime's Agent reap ladder (ADR-0008), one process level up.
+
+## Docs
+
+Provided tools: `yaag_run`, `yaag_describe`, `yaag_setup_workspace`, `yaag_stop`.
+Provided commands: `/yaag-status`, `/yaag-setup-workspace [dir]`.
+
+- [`../../docs/architecture.md`](../../docs/architecture.md) — the diagrams
+- [`../../docs/adr/`](../../docs/adr) — why it is built this way
+- [ADR-0018: foreign workspaces use CLI aliases and vendored types](../../docs/adr/0018-foreign-workspaces-use-cli-aliases-and-vendored-types.md) — workspace setup and foreign-program support

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@yaag/extension",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "for file in src/*.test.ts; do bun test \"$file\" || exit 1; done",
+    "test:e2e": "bun test e2e"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "^0.84.0",
+    "@yaag/runtime": "0.0.0",
+    "@yaag/tui": "0.0.0",
+    "@yaag/cli": "0.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@types/node": "^22.0.0",
+    "typebox": "1.3.7"
+  }
+}

package/src/background-widget.ts

@@ -0,0 +1,107 @@
+/**
+ * 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/cli-child.ts

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import { type ReapTarget, reap } from "@yaag/runtime";
+import { StderrTail } from "./stderr-buffer.ts";
+
+/** The process-level output of one Bun CLI child. */
+export interface CliChildOutcome {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface CliChildOptions {
+  readonly bun: string;
+  readonly cli: string;
+  readonly argv: readonly string[];
+  /** Run reserves fd 3 for Lifecycle Events; ordinary CLI calls do not. */
+  readonly events?: boolean;
+}
+
+/** A detached Bun CLI child and the common reap ladder used to stop it. */
+export interface CliChild {
+  readonly outcome: Promise<CliChildOutcome>;
+  readonly events: Readable | undefined;
+  stop(): void;
+}
+
+/**
+ * Starts the resolved Bun CLI in its own process group.
+ *
+ * The returned `stop` closes stdin, then escalates through SIGTERM and group
+ * SIGKILL via `reap()`. It never interprets CLI argv, stdout, or fd 3.
+ */
+export function startCliChild(options: CliChildOptions): CliChild {
+  const child = spawn(options.bun, [options.cli, ...options.argv], {
+    stdio: options.events === true ? ["pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
+    detached: true,
+  });
+  const stderr = new StderrTail();
+  const exited = observeExit(child);
+  const target: ReapTarget = {
+    exited,
+    endStdin: () => endStdin(child.stdin),
+    terminate: () => void child.kill("SIGTERM"),
+    destroyGroup: () => destroyGroup(child),
+  };
+  const outcome = Promise.all([
+    text(child.stdout),
+    drain(child.stderr, (chunk) => stderr.write(chunk)),
+    exited,
+  ]).then(([stdout]) => ({ code: child.exitCode, stdout, stderr: stderr.text() }));
+  const eventStream = options.events === true ? child.stdio[3] : undefined;
+  return {
+    outcome,
+    events: isReadable(eventStream) ? eventStream : undefined,
+    stop: () => void reap(target),
+  };
+}
+
+function endStdin(stdin: Writable | null): void {
+  stdin?.end();
+}
+
+/** Last resort: the whole group, including processes the CLI may have spawned. */
+function destroyGroup(child: ReturnType<typeof spawn>): void {
+  try {
+    if (child.pid !== undefined) process.kill(-child.pid, "SIGKILL");
+    else child.kill("SIGKILL");
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+function isReadable(stream: unknown): stream is Readable {
+  return typeof stream === "object" && stream !== null && "on" in stream;
+}
+
+async function text(stream: Readable | null): Promise<string> {
+  if (stream === null) return "";
+  let out = "";
+  stream.setEncoding("utf8");
+  for await (const chunk of stream) out += String(chunk);
+  return out;
+}
+
+async function drain(stream: Readable | null, onChunk: (chunk: string) => void): Promise<void> {
+  if (stream === null) return;
+  stream.setEncoding("utf8");
+  for await (const chunk of stream) onChunk(String(chunk));
+}
+
+function observeExit(child: ReturnType<typeof spawn>): Promise<void> {
+  return new Promise((resolve, reject) => {
+    child.on("close", () => resolve());
+    child.on("error", reject);
+  });
+}

package/src/describe-tool.ts

@@ -0,0 +1,69 @@
+import { resolve } from "node:path";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { startCliChild } from "./cli-child.ts";
+import { statusReport } from "./status.ts";
+
+const parameters = Type.Object({
+  file: Type.String({ description: "Path to the Orchestration Program file" }),
+});
+
+export interface DescribeToolOptions {
+  readonly bun: string | null;
+  readonly cli: string;
+}
+
+const DESCRIPTION = [
+  "Return an Orchestration Program's declared name, description, and args schema.",
+  "",
+  "For program authors: use the prompt`…` helper for clean prompts. ctx.spawn restrictions",
+  "are spawn-level: tools/disallowedTools, and skills/disallowedSkills are names, not paths.",
+  "handle.ask supports maxTurns, maxToolCalls, maxDurationMs, and wrapUpPrompt as recoverable",
+  "ASK_LIMIT controls. These differ from timeoutMs, the destructive Agent-killing fallback.",
+  "",
+  "Describing imports the program and executes its module top level. Programs should keep",
+  "module top level side-effect free; use this only for reviewed, user-authored files.",
+].join("\n");
+
+/**
+ * Creates `yaag_describe`, which returns the CLI's program contract verbatim.
+ *
+ * Throws an actionable missing-Bun, CLI failure, or cancellation error. It has
+ * no Run registry, Lifecycle Event, progress, summary, or follow-up dependency.
+ */
+export function createDescribeTool(
+  options: DescribeToolOptions,
+): ToolDefinition<typeof parameters, undefined> {
+  const { bun, cli } = options;
+  return {
+    name: "yaag_describe",
+    label: "Describe Program",
+    description: DESCRIPTION,
+    parameters,
+    async execute(_id, params, signal) {
+      if (bun === null) throw new Error(statusReport(null, cli));
+      const child = startCliChild({ bun, cli, argv: ["describe", resolve(params.file)] });
+      signal?.addEventListener("abort", child.stop, { once: true });
+      if (wasAborted(signal)) child.stop();
+      try {
+        const outcome = await child.outcome;
+        if (wasAborted(signal)) throw new Error("yaag_describe: cancelled");
+        if (outcome.code !== 0) throw new Error(failure(outcome.code, outcome.stderr));
+        return { content: [{ type: "text", text: outcome.stdout }], details: undefined };
+      } finally {
+        signal?.removeEventListener("abort", child.stop);
+      }
+    },
+  };
+}
+
+function wasAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
+function failure(code: number | null, stderr: string): string {
+  const tail = stderr.trimEnd();
+  const what =
+    code === null ? "the description was killed" : `the description failed (exit ${code})`;
+  return tail === "" ? `yaag_describe: ${what}` : `yaag_describe: ${what}\n${tail}`;
+}

package/src/event-reader.ts

@@ -0,0 +1,47 @@
+import type { Readable } from "node:stream";
+import type { LifecycleEvent } from "@yaag/runtime";
+
+/**
+ * Reads Lifecycle Events from the CLI's dedicated descriptor: one JSON object
+ * per line, wrapped in the `{ v: 1, ... }` envelope (ADR-0016).
+ *
+ * Resolves when the stream ends. Never rejects on content: a line that is not
+ * JSON, or carries a wire version this host does not know, is skipped — a
+ * malformed record must not take down the Run that produced it.
+ */
+export async function readEvents(
+  stream: Readable,
+  onEvent: (event: LifecycleEvent) => void,
+): Promise<void> {
+  let pending = "";
+  stream.setEncoding("utf8");
+  for await (const chunk of stream) {
+    pending += String(chunk);
+    const lines = pending.split("\n");
+    pending = lines.pop() ?? "";
+    for (const line of lines) emit(line, onEvent);
+  }
+  emit(pending, onEvent);
+}
+
+function emit(line: string, onEvent: (event: LifecycleEvent) => void): void {
+  const event = parseEnvelope(line);
+  if (event !== null) onEvent(event);
+}
+
+function parseEnvelope(line: string): LifecycleEvent | null {
+  if (line.trim() === "") return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null) return null;
+  if (!("v" in value) || value.v !== 1) return null;
+  if (!("type" in value) || typeof value.type !== "string") return null;
+  const { v: _version, ...event } = value as { v: number } & Record<string, unknown>;
+  // Narrowed as far as the wire allows: the envelope is versioned, and the
+  // Summary fold ignores any type it does not recognise.
+  return event as unknown as LifecycleEvent;
+}