@yaag/runtime 0.1.0

package/src/pi-state.ts

@@ -0,0 +1,108 @@
+import type { AgentStats, Frame, OpenOptions, TokenBreakdown } from "./transport.ts";
+
+/** The command line for one Agent. */
+export function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[] {
+  const cmd = ["pi", "--mode", "rpc"];
+  if (options.model) cmd.push("--model", options.model);
+  if (options.systemPrompt) cmd.push("--system-prompt", options.systemPrompt);
+  if (options.thinking !== undefined) cmd.push("--thinking", options.thinking);
+  if (options.appendSystemPrompt !== undefined) {
+    cmd.push("--append-system-prompt", options.appendSystemPrompt);
+  }
+  appendCapabilities(cmd, options, toolProbeExtensionPath);
+  if (options.sessionDir) cmd.push("--session-dir", options.sessionDir);
+  if (options.sessionFile) cmd.push("--session", options.sessionFile);
+  // No --approve: Agents inherit the user's saved project-trust decision (ADR-0009).
+  return cmd;
+}
+
+function appendCapabilities(
+  cmd: string[],
+  options: OpenOptions,
+  toolProbeExtensionPath: string | undefined,
+): void {
+  const hermetic = options.inherit !== true;
+  if (options.tools === undefined) {
+    if (hermetic) cmd.push("--no-tools");
+  } else if (options.tools.length === 0) {
+    cmd.push("--no-tools");
+  } else {
+    cmd.push("--tools", options.tools.join(","));
+  }
+  if (options.resolvedSkillPaths === undefined) {
+    if (hermetic) cmd.push("--no-skills");
+  } else {
+    cmd.push("--no-skills");
+    for (const path of options.resolvedSkillPaths) cmd.push("--skill", path);
+  }
+  if (hermetic) {
+    cmd.push("--no-extensions", "--no-context-files", "--no-prompt-templates");
+  }
+  for (const path of options.resolvedExtensionPaths ?? []) cmd.push("-e", path);
+  if (
+    options.tools !== undefined &&
+    options.tools.length > 0 &&
+    toolProbeExtensionPath !== undefined
+  ) {
+    cmd.push("-e", toolProbeExtensionPath);
+  }
+  if (options.disallowedTools !== undefined) {
+    cmd.push("--exclude-tools", options.disallowedTools.join(","));
+  }
+}
+
+/**
+ * `provider/id` from a `get_state` response — what the Agent actually resolved
+ * to, not the pattern that was requested. Null when the payload has no model.
+ */
+export function readModel(response: Frame): string | null {
+  const data: unknown = response.data;
+  if (typeof data !== "object" || data === null || !("model" in data)) return null;
+  const model: unknown = data.model;
+  if (typeof model !== "object" || model === null) return null;
+  if (!("id" in model) || typeof model.id !== "string") return null;
+  const provider =
+    "provider" in model && typeof model.provider === "string" ? model.provider : null;
+  return provider ? `${provider}/${model.id}` : model.id;
+}
+
+/** Returns pi's persisted session path from a startup `get_state` response, when valid. */
+export function readSessionFile(response: Frame): string | null {
+  const data: unknown = response.data;
+  if (typeof data !== "object" || data === null || !("sessionFile" in data)) return null;
+  return typeof data.sessionFile === "string" ? data.sessionFile : null;
+}
+
+/**
+ * The full token breakdown and cost from a `get_session_stats` response.
+ * Missing fields become null rather than 0, so "unknown" and "free" stay
+ * distinguishable (ADR-0012); a partial breakdown is treated as unknown.
+ */
+export function readStats(response: Frame): AgentStats {
+  const data: unknown = response.data;
+  if (typeof data !== "object" || data === null) return { tokens: null, cost: null };
+  const cost = "cost" in data && typeof data.cost === "number" ? data.cost : null;
+  return { tokens: readBreakdown("tokens" in data ? data.tokens : null), cost };
+}
+
+function readBreakdown(tokens: unknown): TokenBreakdown | null {
+  if (typeof tokens !== "object" || tokens === null) return null;
+  const record: Record<string, unknown> = { ...tokens };
+  const read = (key: string): number | null =>
+    typeof record[key] === "number" ? record[key] : null;
+  const input = read("input");
+  const output = read("output");
+  const cacheRead = read("cacheRead");
+  const cacheWrite = read("cacheWrite");
+  const total = read("total");
+  if (
+    input === null ||
+    output === null ||
+    cacheRead === null ||
+    cacheWrite === null ||
+    total === null
+  ) {
+    return null;
+  }
+  return { input, output, cacheRead, cacheWrite, total };
+}

package/src/prompt-gist.ts

@@ -0,0 +1,13 @@
+import { PROMPT_GIST_MAX_CHARS } from "./wire-constants.ts";
+
+/**
+ * Condenses an Ask prompt for the `ask_start` Lifecycle Event.
+ *
+ * Selects the first non-blank line, collapses its whitespace, and caps it at
+ * `PROMPT_GIST_MAX_CHARS`; it never includes content from later lines. Returns
+ * `""` for an all-whitespace prompt and never throws.
+ */
+export function promptGist(prompt: string): string {
+  const firstLine = prompt.trimStart().split("\n", 1)[0] ?? "";
+  return firstLine.replace(/\s+/g, " ").trim().slice(0, PROMPT_GIST_MAX_CHARS);
+}

package/src/prompt.ts

@@ -0,0 +1,80 @@
+const BLANK_LINE = /^[\t ]*$/;
+const INDENTATION = /^[\t ]*/;
+const INTERPOLATION_MARKER = "x";
+
+/**
+ * Renders an indented template literal as a clean prompt string.
+ *
+ * Dedents static template text only and inserts interpolated values verbatim.
+ * Strings pass through, numbers and booleans stringify, and arrays render their
+ * items recursively separated by newlines. Throws `TypeError` for unsupported
+ * values or static indentation that mixes tabs and spaces.
+ */
+export function prompt(strings: TemplateStringsArray, ...values: unknown[]): string {
+  const indent = commonIndent(strings.raw);
+  let result = "";
+
+  for (let index = 0; index < strings.raw.length; index += 1) {
+    result += dedentChunk(strings.raw[index] ?? "", indent);
+    if (index < values.length) {
+      result += renderValue(values[index]);
+    }
+  }
+
+  return normalizeBlankLines(result);
+}
+
+function commonIndent(chunks: readonly string[]): number {
+  const lines = chunks.join(INTERPOLATION_MARKER).split("\n").slice(1);
+  let shortest: number | undefined;
+  let indentationKind: "spaces" | "tabs" | undefined;
+
+  for (const line of lines) {
+    if (BLANK_LINE.test(line)) continue;
+
+    const indent = INDENTATION.exec(line)?.[0] ?? "";
+    const kind = indentationKindFor(indent);
+    if (kind !== undefined) {
+      if (indentationKind !== undefined && indentationKind !== kind) {
+        throw new TypeError("prompt: mixed tabs and spaces in indentation");
+      }
+      indentationKind = kind;
+    }
+
+    if (shortest === undefined || indent.length < shortest) shortest = indent.length;
+  }
+
+  return shortest ?? 0;
+}
+
+function indentationKindFor(indent: string): "spaces" | "tabs" | undefined {
+  const hasSpaces = indent.includes(" ");
+  const hasTabs = indent.includes("\t");
+  if (hasSpaces && hasTabs) {
+    throw new TypeError("prompt: mixed tabs and spaces in indentation");
+  }
+  if (hasSpaces) return "spaces";
+  if (hasTabs) return "tabs";
+  return undefined;
+}
+
+function dedentChunk(chunk: string, indent: number): string {
+  return chunk
+    .split("\n")
+    .map((line, index) => (index === 0 ? line : line.slice(indent)))
+    .join("\n");
+}
+
+function renderValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return value.map(renderValue).join("\n");
+  throw new TypeError(`prompt: cannot interpolate ${value === null ? "null" : typeof value}`);
+}
+
+function normalizeBlankLines(text: string): string {
+  const lines = text.split("\n");
+  if (BLANK_LINE.test(lines[0] ?? "")) lines.shift();
+  if (BLANK_LINE.test(lines.at(-1) ?? "")) lines.pop();
+  return lines.map((line) => (BLANK_LINE.test(line) ? "" : line)).join("\n");
+}

package/src/reap.ts

@@ -0,0 +1,59 @@
+/** The process facts reaping needs. Kept behind an interface so it is testable. */
+export interface ReapTarget {
+  /** Resolves when the Agent's process is gone. */
+  readonly exited: Promise<unknown>;
+  /** Close the Agent's stdin. */
+  endStdin(): void;
+  /** SIGTERM to the pid — pi handles it and still reaps its own children. */
+  terminate(): void;
+  /** SIGKILL to the process group. Last resort; may leak bash-tool children. */
+  destroyGroup(): void;
+}
+
+export type ReapPath = "stdin-close" | "sigterm" | "sigkill";
+
+const reaping = new WeakMap<ReapTarget, Promise<ReapPath>>();
+
+/**
+ * Shuts an Agent down (ticket 02's shutdown contract).
+ *
+ * Repeated requests for the same process share the initial attempt and its
+ * outcome. stdin EOF first, because pi's graceful shutdown is the only thing
+ * that reaps the bash-tool children it spawned into their own process groups —
+ * a group SIGKILL kills pi and leaves the user's `npm run dev` running. SIGINT
+ * is never sent: RPC mode registers SIGTERM and SIGHUP only.
+ */
+export function reap(target: ReapTarget, graceMs = 2000): Promise<ReapPath> {
+  const existing = reaping.get(target);
+  if (existing !== undefined) return existing;
+
+  // Queue the ladder after caching it: endStdin() can synchronously trigger a
+  // second close request through an embedding process's callbacks.
+  const current = Promise.resolve().then(() => reapOnce(target, graceMs));
+  reaping.set(target, current);
+  return current;
+}
+
+async function reapOnce(target: ReapTarget, graceMs: number): Promise<ReapPath> {
+  target.endStdin();
+  if (await exitedWithin(target.exited, graceMs)) return "stdin-close";
+
+  target.terminate();
+  if (await exitedWithin(target.exited, graceMs)) return "sigterm";
+
+  target.destroyGroup();
+  await target.exited;
+  return "sigkill";
+}
+
+async function exitedWithin(exited: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const pending = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  try {
+    return await Promise.race([exited.then(() => true), pending]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/recording-transport.ts

@@ -0,0 +1,97 @@
+import type { CassetteSink } from "./cassette.ts";
+import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
+import { readGitFacts } from "./git-facts.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  AskMarker,
+  AskPlayback,
+  Frame,
+  OpenOptions,
+  TransportFactory,
+  TransportStartup,
+  TransportStartupObserver,
+} from "./transport.ts";
+
+/**
+ * Wraps a transport factory and records frames at the public transport seam.
+ *
+ * Delegation is unchanged; failures from the wrapped factory and transport are
+ * preserved. The supplied sink holds the artifact until its owner serializes it.
+ */
+export function recordingTransport(inner: TransportFactory, sink: CassetteSink): TransportFactory {
+  return {
+    async open(
+      options: OpenOptions,
+      observeStartup?: TransportStartupObserver,
+    ): Promise<AgentTransport> {
+      const recorder = sink.reserve(options);
+      let startup: TransportStartup = {};
+      try {
+        const transport = await inner.open(options, (report) => {
+          startup = { ...startup, ...report };
+          observeStartup?.(report);
+        });
+        recorder.opened({
+          model: transport.model,
+          ...startup,
+          git: await readGitFacts(startup.worktree?.cwd ?? options.cwd),
+        });
+        return new RecordingTransport(transport, recorder);
+      } catch (error) {
+        recorder.failed();
+        throw error;
+      }
+    },
+  };
+}
+
+class RecordingTransport implements AgentTransport {
+  readonly model: string;
+  readonly #inner: AgentTransport;
+  readonly #recorder: ReturnType<CassetteSink["reserve"]>;
+  #close: Promise<AgentStats> | null = null;
+
+  constructor(inner: AgentTransport, recorder: ReturnType<CassetteSink["reserve"]>) {
+    this.model = inner.model;
+    this.#inner = inner;
+    this.#recorder = recorder;
+  }
+
+  send(frame: Frame): void {
+    this.#recorder.sent(frame);
+    this.#inner.send(frame);
+  }
+
+  async *frames(): AsyncIterable<Frame> {
+    for await (const frame of this.#inner.frames()) {
+      this.#recorder.received(frame);
+      yield frame;
+    }
+  }
+
+  beginAsk(marker: AskMarker): AskPlayback | undefined {
+    this.#recorder.beginAsk(marker);
+    return this.#inner.beginAsk(marker);
+  }
+
+  finishAsk(
+    outcome?: AskLimitOutcome,
+    stalled?: AskStalledOutcome,
+    invalidOutput?: import("./transport.ts").AskInvalidOutputPlayback,
+  ): void {
+    this.#recorder.finishAsk(outcome, stalled, invalidOutput);
+    this.#inner.finishAsk(outcome, stalled, invalidOutput);
+  }
+
+  close(): Promise<AgentStats> {
+    this.#close ??= this.#closeAndRecord();
+    return this.#close;
+  }
+
+  async #closeAndRecord(): Promise<AgentStats> {
+    const stats = await this.#inner.close();
+    this.#recorder.closed(stats);
+    return stats;
+  }
+}

package/src/replay-divergence.ts

@@ -0,0 +1,155 @@
+import type { CassetteAgent, CassetteAsk, CassetteSpawn } from "./cassette.ts";
+import { YaagError } from "./errors.ts";
+import type { AskMarker, AskMarkerContext, OpenOptions } from "./transport.ts";
+
+/** A pure description of the first strict replay identity mismatch. */
+export interface ReplayMismatch {
+  readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
+  readonly agent: string;
+  readonly index?: number;
+  readonly expectedHash: string;
+  readonly actualHash: string;
+  readonly definitionName?: string;
+  readonly changedFields?: readonly string[];
+}
+
+/** Pure identity comparisons that ADR-0014 can reuse with a lenient reaction. */
+export const replayMismatch = {
+  spawn(expected: CassetteAgent | null, actual: OpenOptions): ReplayMismatch | null {
+    if (expected === null) {
+      return {
+        kind: "unexpected-spawn",
+        agent: actual.name,
+        expectedHash: "<none>",
+        actualHash: spawnHash(actual),
+      };
+    }
+    const expectedHash = spawnHash(expected.spawn);
+    const actualHash = spawnHash(actual);
+    return expectedHash === actualHash
+      ? null
+      : { kind: "spawn-options", agent: actual.name, expectedHash, actualHash };
+  },
+
+  ask(agent: CassetteAgent, cursor: number, actual: AskMarker): ReplayMismatch | null {
+    const expected = agent.asks[cursor];
+    if (!expected) {
+      return {
+        kind: "extra-ask",
+        agent: agent.spawn.name,
+        index: actual.index,
+        expectedHash: "<none>",
+        actualHash: actual.hash,
+      };
+    }
+    return askMatches(expected, actual)
+      ? null
+      : {
+          kind: "changed-ask",
+          agent: agent.spawn.name,
+          index: actual.index,
+          expectedHash: expected.hash,
+          actualHash: actual.hash,
+          ...(expected.definitionName === undefined
+            ? {}
+            : {
+                definitionName: expected.definitionName,
+                ...(expected.context === undefined || actual.context === undefined
+                  ? {}
+                  : { changedFields: changedFields(expected.context, actual.context) }),
+              }),
+        };
+  },
+};
+
+/** Converts a detected mismatch into strict replay's public failure. */
+export function strictReplay(mismatch: ReplayMismatch): never {
+  if (mismatch.kind === "changed-ask" && mismatch.definitionName !== undefined) {
+    const fields = mismatch.changedFields?.join(", ") ?? "hash inputs";
+    throw new YaagError(
+      "REPLAY_DIVERGED",
+      `replay diverged for agent "${mismatch.agent}" at ask #${mismatch.index}: definition "${mismatch.definitionName}" changed since recording (${fields})`,
+      mismatch.agent,
+    );
+  }
+  const at = mismatch.index === undefined ? "spawn" : `Ask ${mismatch.index}`;
+  throw new YaagError(
+    "REPLAY_DIVERGED",
+    `replay diverged for agent "${mismatch.agent}" at ${at}: expected ${mismatch.expectedHash}, actual ${mismatch.actualHash}`,
+    mismatch.agent,
+  );
+}
+
+function askMatches(expected: CassetteAsk, actual: AskMarker): boolean {
+  return (
+    expected.index === actual.index &&
+    expected.hash === actual.hash &&
+    JSON.stringify(expected.outputSchema) === JSON.stringify(actual.outputSchema) &&
+    expected.maxSteers === actual.maxSteers &&
+    expected.extractionPolicy === actual.extractionPolicy
+  );
+}
+
+function changedFields(expected: AskMarkerContext, actual: AskMarkerContext): readonly string[] {
+  const fields: string[] = [];
+  if (expected.prompt !== actual.prompt) fields.push("prompt");
+  for (const field of [
+    "cwd",
+    "model",
+    "systemPrompt",
+    "thinking",
+    "appendSystemPrompt",
+    "tools",
+    "disallowedTools",
+    "skills",
+    "disallowedSkills",
+    "worktree",
+  ] as const) {
+    if (JSON.stringify(expected.spawn[field]) !== JSON.stringify(actual.spawn[field])) {
+      fields.push(field);
+    }
+  }
+  for (const field of [
+    "maxTurns",
+    "maxToolCalls",
+    "maxDurationMs",
+    "idleMs",
+    "wrapUpPrompt",
+    "outputSchema",
+    "maxSteers",
+    "extractionPolicy",
+  ] as const) {
+    const unchanged =
+      field === "outputSchema"
+        ? JSON.stringify(expected.ask.outputSchema) === JSON.stringify(actual.ask.outputSchema)
+        : expected.ask[field] === actual.ask[field];
+    if (!unchanged) fields.push(field);
+  }
+  return fields;
+}
+
+function spawnHash(options: CassetteSpawn | OpenOptions): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(
+    JSON.stringify({
+      name: options.name,
+      cwd: options.cwd,
+      model: options.model ?? null,
+      systemPrompt: options.systemPrompt ?? null,
+      ...(options.tools === undefined ? {} : { tools: options.tools }),
+      ...(options.disallowedTools === undefined
+        ? {}
+        : { disallowedTools: options.disallowedTools }),
+      ...(options.skills === undefined ? {} : { skills: options.skills }),
+      ...(options.disallowedSkills === undefined
+        ? {}
+        : { disallowedSkills: options.disallowedSkills }),
+      ...(options.worktree === true ? { worktree: true } : {}),
+      ...(options.thinking === undefined ? {} : { thinking: options.thinking }),
+      ...(options.appendSystemPrompt === undefined
+        ? {}
+        : { appendSystemPrompt: options.appendSystemPrompt }),
+    }),
+  );
+  return hasher.digest("hex");
+}

package/src/replay-transport.ts

@@ -0,0 +1,72 @@
+import type { Cassette } from "./cassette.ts";
+import { CassetteReplay } from "./cassette-replay.ts";
+import { replayMismatch, strictReplay } from "./replay-divergence.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  AskMarker,
+  AskPlayback,
+  Frame,
+  OpenOptions,
+  TransportFactory,
+  TransportStartupObserver,
+} from "./transport.ts";
+
+/**
+ * Creates a strict Cassette-backed transport factory without starting pi.
+ *
+ * Each opened transport owns its Ask and frame cursors, so independent Agents
+ * may replay their recorded conversations in a different interleaving.
+ */
+export function replayTransport(cassette: Cassette): TransportFactory {
+  let spawnCursor = 0;
+  return {
+    async open(
+      options: OpenOptions,
+      observeStartup?: TransportStartupObserver,
+    ): Promise<AgentTransport> {
+      const agent = cassette.agents[spawnCursor] ?? null;
+      const mismatch = replayMismatch.spawn(agent, options);
+      if (mismatch) strictReplay(mismatch);
+      spawnCursor += 1;
+      if (agent.worktree !== undefined) observeStartup?.({ worktree: agent.worktree });
+      return new ReplayTransport(new CassetteReplay(agent));
+    },
+  };
+}
+
+class ReplayTransport implements AgentTransport {
+  readonly model: string;
+  readonly #replay: CassetteReplay;
+  #askCursor = 0;
+  #closed: Promise<AgentStats> | null = null;
+
+  constructor(replay: CassetteReplay) {
+    this.#replay = replay;
+    this.model = replay.model;
+  }
+
+  send(frame: Frame): void {
+    this.#replay.send(frame);
+  }
+
+  frames(): AsyncIterable<Frame> {
+    return this.#replay.frames();
+  }
+
+  beginAsk(marker: AskMarker): AskPlayback {
+    const mismatch = replayMismatch.ask(this.#replay.agent, this.#askCursor, marker);
+    if (mismatch) strictReplay(mismatch);
+    this.#askCursor += 1;
+    return this.#replay.beginAsk(marker);
+  }
+
+  finishAsk(): void {
+    // A completed replay does not alter the recorded Cassette.
+  }
+
+  close(): Promise<AgentStats> {
+    this.#closed ??= Promise.resolve(this.#replay.stats).finally(() => this.#replay.finish());
+    return this.#closed;
+  }
+}

package/src/resume-preconditions.ts

@@ -0,0 +1,59 @@
+import { stat } from "node:fs/promises";
+import type { CassetteAgent } from "./cassette.ts";
+import { YaagError } from "./errors.ts";
+
+/**
+ * Validates that a recorded Agent can safely continue from its persisted session.
+ *
+ * Rejects with RESUME_REFUSED before replaying any frames when its session or
+ * working-tree facts cannot establish the recorded continuation point.
+ */
+export async function checkResumePreconditions(agent: CassetteAgent): Promise<void> {
+  const { name } = agent.spawn;
+  const cwd = continuationCwd(agent);
+  let state: Awaited<ReturnType<typeof stat>>;
+  try {
+    state = await stat(cwd);
+  } catch {
+    refuse(name, `recorded cwd "${cwd}" no longer exists`);
+  }
+  if (!state.isDirectory()) refuse(name, `recorded cwd "${cwd}" is not a directory`);
+
+  if (agent.git) {
+    const current = await readHead(cwd);
+    if (current !== agent.git.head) {
+      refuse(
+        name,
+        `recorded branch ${agent.git.branch}, recorded HEAD ${agent.git.head}, current HEAD ${current ?? "unavailable"}`,
+      );
+    }
+  }
+  if (!agent.sessionFile)
+    refuse(name, "has no recorded session file; re-record this Run before resuming");
+}
+
+async function readHead(cwd: string): Promise<string | null> {
+  const process = Bun.spawn({
+    cmd: ["git", "-C", cwd, "rev-parse", "HEAD"],
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const [code, stdout] = await Promise.all([process.exited, new Response(process.stdout).text()]);
+  const head = stdout.trim();
+  return code === 0 && head !== "" ? head : null;
+}
+
+function continuationCwd(agent: CassetteAgent): string {
+  if (agent.spawn.worktree !== true) return agent.spawn.cwd;
+  if (agent.worktree === undefined) {
+    refuse(
+      agent.spawn.name,
+      "has no recorded worktree resolution; re-record this Run before resuming",
+    );
+  }
+  return agent.worktree.cwd;
+}
+
+function refuse(agent: string, detail: string): never {
+  throw new YaagError("RESUME_REFUSED", `resume refused for agent "${agent}": ${detail}`, agent);
+}