@yaag/extension 0.1.0

package/src/setup-workspace-command.ts

@@ -0,0 +1,45 @@
+import { SetupWorkspaceError, type SetupWorkspaceExecutor } from "./setup-workspace.ts";
+
+const DESCRIPTION = "Install or refresh editor types for programs under .yaag/.";
+
+/** The only pi UI capability workspace setup needs. */
+export interface SetupWorkspaceCommandContext {
+  readonly cwd: string;
+  readonly ui: {
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+  };
+}
+
+/** Definition suitable for `ExtensionAPI.registerCommand`. */
+export interface SetupWorkspaceCommand {
+  readonly description: string;
+  handler(args: string, ctx: SetupWorkspaceCommandContext): Promise<void>;
+}
+
+/**
+ * Creates `/yaag-setup-workspace`, the user-facing workspace setup command.
+ *
+ * It notifies the CLI report on success and expected setup failures on error;
+ * it has no Run, progress, summary, usage, or follow-up behavior.
+ */
+export function createSetupWorkspaceCommand(
+  executor: SetupWorkspaceExecutor,
+): SetupWorkspaceCommand {
+  return {
+    description: DESCRIPTION,
+    async handler(args, ctx): Promise<void> {
+      try {
+        const report = await executor.execute({ dir: args.trim() || ctx.cwd });
+        ctx.ui.notify(report, "info");
+      } catch (error: unknown) {
+        ctx.ui.notify(message(error), "error");
+      }
+    },
+  };
+}
+
+function message(error: unknown): string {
+  if (error instanceof SetupWorkspaceError) return error.message;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}

package/src/setup-workspace-tool.ts

@@ -0,0 +1,45 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { SetupWorkspaceExecutor } from "./setup-workspace.ts";
+
+const parameters = Type.Object({
+  dir: Type.Optional(
+    Type.String({
+      description: "Workspace root. Defaults to pi's current working directory.",
+    }),
+  ),
+});
+
+/** Dependencies for the direct `yaag_setup_workspace` CLI wrapper. */
+export interface SetupWorkspaceToolOptions {
+  readonly executor: SetupWorkspaceExecutor;
+}
+
+const DESCRIPTION = [
+  "Set up editor types for an Orchestration Program workspace.",
+  "Use this when a program author sees missing @yaag/runtime editor types.",
+  "Normally run it only once per workspace, then rerun after an upgrade to refresh generated declarations.",
+].join("\n");
+
+/**
+ * Creates `yaag_setup_workspace`, a direct wrapper around the Bun CLI setup command.
+ *
+ * It has no Run registry, Run id, Lifecycle Events, summaries, cassette behavior,
+ * usage, or follow-up channel. Throws actionable missing-Bun, setup-failure, or
+ * cancellation errors.
+ */
+export function createSetupWorkspaceTool(
+  options: SetupWorkspaceToolOptions,
+): ToolDefinition<typeof parameters, undefined> {
+  const { executor } = options;
+  return {
+    name: "yaag_setup_workspace",
+    label: "Set Up Workspace",
+    description: DESCRIPTION,
+    parameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const report = await executor.execute({ dir: params.dir ?? ctx.cwd, signal });
+      return { content: [{ type: "text", text: report }], details: undefined };
+    },
+  };
+}

package/src/setup-workspace.ts

@@ -0,0 +1,69 @@
+import { type CliChild, type CliChildOptions, startCliChild } from "./cli-child.ts";
+import { statusReport } from "./status.ts";
+
+/** Injectable boundary for starting the Bun CLI child. */
+export type StartCliChild = (options: CliChildOptions) => CliChild;
+
+/** Dependencies resolved once when the extension loads. */
+export interface SetupWorkspaceExecutorOptions {
+  readonly bun: string | null;
+  readonly cli: string;
+  readonly startChild?: StartCliChild;
+}
+
+/** One requested workspace-setup execution. */
+export interface SetupWorkspaceRequest {
+  readonly dir: string;
+  readonly signal?: AbortSignal;
+}
+
+/** Shared setup boundary used by the model tool and slash command. */
+export interface SetupWorkspaceExecutor {
+  execute(request: SetupWorkspaceRequest): Promise<string>;
+}
+
+/** An expected Bun bridge, CLI, or cancellation failure during workspace setup. */
+export class SetupWorkspaceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SetupWorkspaceError";
+  }
+}
+
+/**
+ * Creates the sole extension-side executor for `bun cli.ts setup-workspace`.
+ *
+ * Resolves with the CLI report verbatim. Throws `SetupWorkspaceError` for a
+ * missing Bun bridge, failed CLI invocation, or cancellation; it never owns
+ * workspace artifact policy.
+ */
+export function createSetupWorkspaceExecutor(
+  options: SetupWorkspaceExecutorOptions,
+): SetupWorkspaceExecutor {
+  const { bun, cli, startChild = startCliChild } = options;
+  return {
+    async execute({ dir, signal }: SetupWorkspaceRequest): Promise<string> {
+      if (bun === null) throw new SetupWorkspaceError(statusReport(null, cli));
+      const child = startChild({ bun, cli, argv: ["setup-workspace", dir] });
+      signal?.addEventListener("abort", child.stop, { once: true });
+      if (signal?.aborted === true) child.stop();
+      try {
+        const outcome = await child.outcome;
+        if (signal?.aborted === true)
+          throw new SetupWorkspaceError("yaag_setup_workspace: cancelled");
+        if (outcome.code !== 0)
+          throw new SetupWorkspaceError(failure(outcome.code, outcome.stderr));
+        return outcome.stdout;
+      } finally {
+        signal?.removeEventListener("abort", child.stop);
+      }
+    },
+  };
+}
+
+function failure(code: number | null, stderr: string): string {
+  const tail = stderr.trimEnd();
+  const what =
+    code === null ? "workspace setup was killed" : `workspace setup failed (exit ${code})`;
+  return tail === "" ? `yaag_setup_workspace: ${what}` : `yaag_setup_workspace: ${what}\n${tail}`;
+}

package/src/spawn-run.ts

@@ -0,0 +1,84 @@
+import { applyEvent, initialSummary, type LifecycleEvent, type RunSummary } from "@yaag/runtime";
+import { startCliChild } from "./cli-child.ts";
+import { readEvents } from "./event-reader.ts";
+
+/** Everything one Run of the CLI produced, once the child has exited. */
+export interface RunOutcome {
+  readonly code: number | null;
+  /** The Run's return value, verbatim from stdout. */
+  readonly stdout: string;
+  /** The bounded tail of the child's error output. */
+  readonly stderr: string;
+  readonly summary: RunSummary;
+}
+
+export interface StartRunOptions {
+  readonly bun: string;
+  readonly cli: string;
+  readonly file: string;
+  /** Opaque JSON, forwarded untouched: the program validates it (ADR-0010). */
+  readonly args?: string;
+  /** Cassette path to write, forwarded as `--record` (ADR-0013). */
+  readonly record?: string;
+  /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
+  readonly resume?: string;
+  /**
+   * Called after each event is folded. `sequence` identifies this fd 3 stream
+   * occurrence, not an event value or timestamp; it makes renderer observation
+   * idempotent while preserving equal-valued consecutive events.
+   */
+  readonly onProgress?: (summary: RunSummary, event: LifecycleEvent, sequence: number) => void;
+}
+
+export interface SpawnRunOptions extends StartRunOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** A Run in flight: its eventual outcome, and the reap ladder that ends it. */
+export interface RunHandle {
+  readonly outcome: Promise<RunOutcome>;
+  readonly stop: () => void;
+}
+
+/**
+ * Starts one Orchestration Program as a child `bun` process without waiting for
+ * it. Descriptor 3 remains exclusive to Run Lifecycle Events (ADR-0016).
+ *
+ * Never throws for a failed Run — the exit code and error tail are part of its
+ * outcome; callers choose how that failure reaches the Host Session.
+ */
+export function startRun(options: StartRunOptions): RunHandle {
+  const argv = ["run", options.file, "--events-fd", "3"];
+  if (options.args !== undefined) argv.push("--args", options.args);
+  if (options.record !== undefined) argv.push("--record", options.record);
+  if (options.resume !== undefined) argv.push("--resume", options.resume);
+  const child = startCliChild({ bun: options.bun, cli: options.cli, argv, events: true });
+  let summary: RunSummary = initialSummary();
+  let sequence = 0;
+  const outcome = Promise.all([
+    child.outcome,
+    child.events === undefined
+      ? Promise.resolve()
+      : readEvents(child.events, (event) => {
+          summary = applyEvent(summary, event);
+          sequence += 1;
+          options.onProgress?.(summary, event, sequence);
+        }),
+  ]).then(([ended]) => ({ ...ended, summary }));
+  return { outcome, stop: child.stop };
+}
+
+/**
+ * Runs one Orchestration Program to completion, stopping it if `signal` aborts.
+ * The blocking convenience wrapper over {@link startRun}; same failure contract.
+ */
+export async function spawnRun(options: SpawnRunOptions): Promise<RunOutcome> {
+  const handle = startRun(options);
+  options.signal?.addEventListener("abort", handle.stop, { once: true });
+  if (options.signal?.aborted === true) handle.stop();
+  try {
+    return await handle.outcome;
+  } finally {
+    options.signal?.removeEventListener("abort", handle.stop);
+  }
+}

package/src/status-tool.ts

@@ -0,0 +1,118 @@
+import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
+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 { toUsage } from "./usage.ts";
+
+const parameters = Type.Object({
+  id: Type.Optional(Type.String({ description: "The Run id returned by yaag_run (e.g. r1)" })),
+});
+
+/** Canonical facts returned by a requested status snapshot. */
+export interface SnapshotDetails {
+  readonly id: string;
+  readonly summary: RunSummary;
+  readonly result?: string;
+}
+
+/** Details are populated only when a specific Run was requested. */
+export type StatusDetails = SnapshotDetails | Record<never, never>;
+
+export interface StatusToolOptions {
+  readonly now?: () => number;
+  readonly width?: number;
+}
+
+const DESCRIPTION = [
+  "Show a snapshot of a Run started in this Host Session.",
+  "",
+  "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.",
+].join("\n");
+
+/**
+ * The `yaag_status` tool renders session-local Run snapshots for the model.
+ *
+ * Throws if an id was not started in this session; finished Runs remain
+ * queryable and are never restarted or controlled by this tool.
+ */
+export function createStatusTool(
+  registry: RunRegistry,
+  options: StatusToolOptions = {},
+): ToolDefinition<typeof parameters, StatusDetails> {
+  const now = options.now ?? Date.now;
+  const width = options.width ?? 80;
+  return {
+    name: "yaag_status",
+    label: "Run Status",
+    description: DESCRIPTION,
+    parameters,
+    async execute(_id, params) {
+      if (params.id === undefined) return overview(registry.runs, now, width);
+      const found = registry.lookup(params.id);
+      if (found.state === "unknown") throw unknownId(params.id, registry.knownIds);
+      const details = detailsFor(found);
+      return {
+        content: [{ type: "text", text: snapshot(details, now, width) }],
+        details,
+        usage: toUsage(details.summary),
+      };
+    },
+  };
+}
+
+function overview(
+  runs: readonly RegisteredRun[],
+  now: () => number,
+  width: number,
+): AgentToolResult<StatusDetails> {
+  if (runs.length === 0)
+    return {
+      content: [{ type: "text", text: "No Runs started this session." }],
+      details: { summary: undefined },
+    };
+  return {
+    content: [
+      {
+        type: "text",
+        text: runs.map((run) => snapshot(detailsFor(run), now, width, true)).join("\n"),
+      },
+    ],
+    details: { summary: undefined },
+  };
+}
+
+function detailsFor(run: RegisteredRun): SnapshotDetails {
+  if (run.state === "live") return { id: run.run.id, summary: run.run.summary };
+  const { outcome } = run.run;
+  return {
+    id: run.run.id,
+    summary: run.run.summary,
+    ...(outcome.kind === "fulfilled" && outcome.outcome.code === 0
+      ? { result: outcome.outcome.stdout.trimEnd() }
+      : {}),
+  };
+}
+
+function snapshot(
+  details: SnapshotDetails,
+  now: () => number,
+  width: number,
+  headerOnly = false,
+): string {
+  const state = TreeState.fromSummary(details.summary);
+  const lines = renderSnapshot(state, {
+    now: now(),
+    width,
+    label: details.id,
+    ...(details.result === undefined ? {} : { result: details.result }),
+  });
+  return (headerOnly ? lines.slice(0, 1) : lines).join("\n");
+}
+
+function unknownId(id: string, knownIds: readonly string[]): Error {
+  const known =
+    knownIds.length === 0 ? "there are no known ids" : `known ids: ${knownIds.join(", ")}`;
+  return new Error(`yaag_status: no Run with id ${id}; ${known}`);
+}

package/src/status.ts

@@ -0,0 +1,13 @@
+/**
+ * The one message the extension has to say about itself: either the bridge to
+ * the Bun CLI is in place, or exactly what is missing and how to install it.
+ */
+export function statusReport(bun: string | null, cli: string): string {
+  if (bun === null) {
+    return (
+      "yaag needs Bun and could not find it on PATH or in ~/.bun/bin. " +
+      "Install it with: curl -fsSL https://bun.sh/install | bash"
+    );
+  }
+  return `yaag ready — bun: ${bun}, cli: ${cli}`;
+}

package/src/stderr-buffer.ts

@@ -0,0 +1,34 @@
+/** Default tail size: enough for a stack trace, small enough to hand a model. */
+const DEFAULT_LIMIT = 8192;
+
+/**
+ * The last `limit` bytes of a child's error output.
+ *
+ * Bounded on purpose: a Run that floods stderr must not grow the host session's
+ * memory, and only the end of the output explains why it failed.
+ */
+export class StderrTail {
+  readonly #limit: number;
+  #chunks: Buffer[] = [];
+  #size = 0;
+
+  constructor(limit: number = DEFAULT_LIMIT) {
+    this.#limit = limit;
+  }
+
+  /** Appends output, discarding whatever no longer fits in the tail. */
+  write(chunk: string | Buffer): void {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    this.#chunks.push(buffer);
+    this.#size += buffer.length;
+    if (this.#size <= this.#limit) return;
+    const joined = Buffer.concat(this.#chunks).subarray(this.#size - this.#limit);
+    this.#chunks = [joined];
+    this.#size = joined.length;
+  }
+
+  /** The retained tail, decoded as UTF-8. */
+  text(): string {
+    return Buffer.concat(this.#chunks).toString("utf8");
+  }
+}

package/src/stop-tool.ts

@@ -0,0 +1,115 @@
+import type { 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 { toUsage } from "./usage.ts";
+
+/** What the stop result carries for rendering — never shown to the model. */
+export interface StopDetails {
+  readonly summary: RunSummary;
+}
+
+const parameters = Type.Object({
+  id: Type.String({ description: "The Run id to stop, as returned by yaag_run (e.g. r1)" }),
+});
+
+const DESCRIPTION = [
+  "Stop a background Run started by yaag_run, by its Run id.",
+  "",
+  "The Run's Agents are reaped, and the report says what it got through and what",
+  "it spent before it stopped.",
+].join("\n");
+
+/** What a stopped Run got through and what it cost, from the fold (ADR-0006). */
+export function stopReport(id: string, summary: RunSummary): string {
+  const agents = Object.keys(summary.agents).length;
+  const cost = summary.incomplete
+    ? `at least $${summary.cost.toFixed(4)}`
+    : `$${summary.cost.toFixed(4)}`;
+  const tokens = summary.tokens === null ? "unknown tokens" : `${summary.tokens.total} tokens`;
+  return [
+    `Run ${id} stopped.`,
+    `Program: ${summary.program === "" ? "unknown" : summary.program}`,
+    `Agents seen: ${agents}`,
+    `Asks settled: ${summary.asksSettled}/${summary.asksStarted}`,
+    `Spent: ${cost}, ${tokens}`,
+    ...Object.entries(summary.agents)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, agent]) => agentReport(name, agent)),
+  ].join("\n");
+}
+
+function agentReport(name: string, agent: RunSummary["agents"][string]): string {
+  const state = agentStateReport(agent);
+  const cost = agent.cost === null ? "unknown cost" : `$${agent.cost.toFixed(4)}`;
+  const tokens = agent.tokens === null ? "unknown tokens" : `${agent.tokens.total} tokens`;
+  const branch = agent.branch === null ? "" : `, branch ${agent.branch}`;
+  return `Agent ${name}: ${state}, ${cost}, ${tokens}${branch}`;
+}
+
+function agentStateReport(agent: RunSummary["agents"][string]): string {
+  switch (agent.state) {
+    case "idle":
+      return "idle";
+    case "asking":
+      return `ask #${agent.askIndex}${agent.promptGist === "" ? "" : `, ${agent.promptGist}`}`;
+    case "exited":
+      return "exited";
+    default: {
+      const never: never = agent;
+      throw new Error(`yaag_stop: unhandled Agent state: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+function toError(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(String(reason));
+}
+
+/**
+ * The `yaag_stop` tool: ends one background Run by name, through the same reap
+ * ladder an abort uses (ADR-0008).
+ *
+ * `execute` throws when the id is unknown or its Run has already finished —
+ * both are worth saying out loud rather than reporting a stop that did nothing.
+ */
+export function createStopTool(
+  registry: RunRegistry,
+): ToolDefinition<typeof parameters, StopDetails> {
+  return {
+    name: "yaag_stop",
+    label: "Stop Run",
+    description: DESCRIPTION,
+    parameters,
+    async execute(_id, params) {
+      const status = registry.lookup(params.id);
+      switch (status.state) {
+        case "unknown":
+          throw new Error(`yaag_stop: no Run with id ${params.id}`);
+        case "finished":
+          throw new Error(`yaag_stop: Run ${params.id} has already finished`);
+        case "live": {
+          const { run } = status;
+          run.stop();
+          try {
+            await run.outcome;
+          } catch {}
+          const settled = registry.lookup(run.id);
+          if (settled.state !== "finished")
+            throw new Error(`yaag_stop: Run ${run.id} settled without registry retention`);
+          if (settled.run.outcome.kind === "rejected") throw toError(settled.run.outcome.reason);
+          const { outcome } = settled.run.outcome;
+          return {
+            content: [{ type: "text", text: stopReport(run.id, outcome.summary) }],
+            details: { summary: outcome.summary },
+            usage: toUsage(outcome.summary),
+          };
+        }
+        default: {
+          const never: never = status;
+          throw new Error(`yaag_stop: unhandled Run status: ${JSON.stringify(never)}`);
+        }
+      }
+    },
+  };
+}

package/src/system-prompt-append.ts

@@ -0,0 +1,53 @@
+/** Builds the host-visible yaag block appended to pi's system prompt. */
+export function yaagPromptBlock(directories: readonly string[]): string {
+  const list = directories.join(", ");
+  return [
+    "## yaag Orchestration Programs",
+    "",
+    `Program Directories (each contains \`.yaag/\`): ${list}.`,
+    "Orchestration Programs are the `.ts` files there: TypeScript modules that",
+    "default-export `defineRun(...)`. Run one with the `yaag_run` tool; inspect",
+    "its declared args with `yaag_describe`.",
+    "",
+    "Minimal program:",
+    "",
+    "```ts",
+    'import { defineRun, prompt } from "@yaag/runtime";',
+    "",
+    "export default defineRun({",
+    '  name: "example",',
+    "  async run(ctx) {",
+    '    const agent = await ctx.spawn({ name: "worker" });',
+    "    const text = await agent.ask(prompt`Do one focused thing and report.`);",
+    "    return text; // the Run's result",
+    "  },",
+    "});",
+    "```",
+    "",
+    "Full authoring surface (defineAgent, args schemas, ask limits, worktrees):",
+    "read `<program dir>/.yaag/types/runtime/index.d.ts`.",
+  ].join("\n");
+}
+
+interface BeforePrompt {
+  readonly systemPrompt: string;
+}
+
+/**
+ * Creates the `before_agent_start` handler. Caches the first non-empty scan
+ * for the session; while empty it re-scans each turn so a mid-session
+ * `yaag_setup_workspace` surfaces on the next turn.
+ */
+export function createSystemPromptAppender(
+  scan: () => Promise<readonly string[]>,
+): (event: BeforePrompt) => Promise<{ systemPrompt: string } | undefined> {
+  let cached: readonly string[] | null = null;
+  return async (event) => {
+    if (cached === null) {
+      const dirs = await scan();
+      if (dirs.length === 0) return undefined;
+      cached = dirs;
+    }
+    return { systemPrompt: `${event.systemPrompt}\n\n${yaagPromptBlock(cached)}` };
+  };
+}

package/src/test-extension-context.ts

@@ -0,0 +1,59 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/**
+ * A fully typed ExtensionContext stub for tool tests.
+ *
+ * Every capability a Run tool never touches throws on access, so a test that
+ * accidentally depends on session state fails loudly instead of silently.
+ */
+export class TestExtensionContext implements ExtensionContext {
+  readonly mode: ExtensionContext["mode"] = "json";
+  readonly hasUI = false;
+  readonly model: ExtensionContext["model"] = undefined;
+  readonly scopedModels: ExtensionContext["scopedModels"] = [];
+  readonly signal: ExtensionContext["signal"] = undefined;
+
+  constructor(readonly cwd: string) {}
+
+  get ui(): ExtensionContext["ui"] {
+    return unavailable("ui");
+  }
+
+  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}`);
+}