@yaag/runtime 0.1.0

package/src/resume-transport.ts

@@ -0,0 +1,165 @@
+import type { Cassette, CassetteAgent } from "./cassette.ts";
+import { CassetteReplay } from "./cassette-replay.ts";
+import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
+import { FrameQueue } from "./frame-queue.ts";
+import { replayMismatch } from "./replay-divergence.ts";
+import { checkResumePreconditions } from "./resume-preconditions.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  AskMarker,
+  AskPlayback,
+  Frame,
+  OpenOptions,
+  TransportFactory,
+  TransportStartupObserver,
+} from "./transport.ts";
+
+/**
+ * Creates a Cassette-prefix transport that continues with live pi at divergence.
+ *
+ * Matched Agents validate their recorded continuation point before replaying.
+ * Spawn mismatches intentionally bypass those checks and start a fresh Agent.
+ */
+export function resumeTransport(cassette: Cassette, live: TransportFactory): 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) return live.open(options, observeStartup);
+      await checkResumePreconditions(agent);
+      const worktree = worktreeResolution(agent);
+      observeStartup?.({
+        ...(agent.sessionFile === undefined ? {} : { sessionFile: agent.sessionFile }),
+        ...(worktree === undefined ? {} : { worktree }),
+      });
+      return new ResumeTransport(agent, live, options);
+    },
+  };
+}
+
+class ResumeTransport implements AgentTransport {
+  readonly model: string;
+  readonly #agent: CassetteAgent;
+  readonly #liveFactory: TransportFactory;
+  readonly #continuation: OpenOptions;
+  readonly #replay: CassetteReplay;
+  readonly #frames = new FrameQueue();
+  readonly #buffered: Frame[] = [];
+  #askCursor = 0;
+  #mode: "replay" | "activating" | "live" = "replay";
+  #live: AgentTransport | null = null;
+  #activation: Promise<void> | null = null;
+  #activationFailed = false;
+  #closed: Promise<AgentStats> | null = null;
+
+  constructor(agent: CassetteAgent, liveFactory: TransportFactory, options: OpenOptions) {
+    this.#agent = agent;
+    this.#liveFactory = liveFactory;
+    this.#continuation = continuationOptions(agent, options);
+    this.#replay = new CassetteReplay(agent);
+    this.model = agent.model;
+    void this.#forward(this.#replay.frames());
+  }
+
+  send(frame: Frame): void {
+    if (this.#mode === "replay") {
+      this.#replay.send(frame);
+      return;
+    }
+    if (this.#mode === "activating") {
+      this.#buffered.push(frame);
+      return;
+    }
+    this.#live?.send(frame);
+  }
+
+  frames(): AsyncIterable<Frame> {
+    return this.#frames.frames();
+  }
+
+  beginAsk(marker: AskMarker): AskPlayback | undefined {
+    if (this.#mode === "live") return this.#live?.beginAsk(marker);
+    if (this.#mode === "activating") return undefined;
+    const mismatch = replayMismatch.ask(this.#agent, this.#askCursor, marker);
+    if (!mismatch) {
+      this.#askCursor += 1;
+      return this.#replay.beginAsk(marker);
+    }
+    this.#mode = "activating";
+    this.#activation = this.#activate(marker);
+    return undefined;
+  }
+
+  finishAsk(
+    outcome?: AskLimitOutcome,
+    stalled?: AskStalledOutcome,
+    invalidOutput?: import("./transport.ts").AskInvalidOutputPlayback,
+  ): void {
+    if (this.#mode === "live") this.#live?.finishAsk(outcome, stalled, invalidOutput);
+  }
+
+  close(): Promise<AgentStats> {
+    this.#closed ??= this.#shutdown();
+    return this.#closed;
+  }
+
+  async #activate(marker: AskMarker): Promise<void> {
+    // End the old source before attaching the new one, but keep the outward
+    // queue open so Connection remains attached across the handoff.
+    this.#replay.finish();
+    try {
+      const live = await this.#liveFactory.open(this.#continuation);
+      this.#live = live;
+      live.beginAsk(marker);
+      for (const frame of this.#buffered.splice(0)) live.send(frame);
+      this.#mode = "live";
+      void this.#forward(live.frames());
+    } catch {
+      this.#activationFailed = true;
+      this.#frames.end();
+    }
+  }
+
+  async #shutdown(): Promise<AgentStats> {
+    if (this.#mode === "replay") {
+      this.#replay.finish();
+      this.#frames.end();
+      return this.#replay.stats;
+    }
+    await this.#activation;
+    this.#frames.end();
+    if (this.#live) return this.#live.close();
+    return this.#activationFailed ? { tokens: null, cost: null } : this.#replay.stats;
+  }
+
+  async #forward(source: AsyncIterable<Frame>): Promise<void> {
+    for await (const frame of source) this.#frames.push(frame);
+  }
+}
+
+function continuationOptions(agent: CassetteAgent, original: OpenOptions): OpenOptions {
+  const { worktree: _worktree, ...spawn } = agent.spawn;
+  const worktree = worktreeResolution(agent);
+  return {
+    ...spawn,
+    ...(original.resolvedExtensionPaths === undefined
+      ? {}
+      : { resolvedExtensionPaths: original.resolvedExtensionPaths }),
+    ...(worktree === undefined ? {} : { cwd: worktree.cwd }),
+    ...(agent.sessionFile === undefined ? {} : { sessionFile: agent.sessionFile }),
+  };
+}
+
+/**
+ * The resolution counts only when the recorded spawn actually requested a
+ * worktree: stray metadata on an ordinary spawn must not relocate the Agent
+ * or lend it a worktree identity.
+ */
+function worktreeResolution(agent: CassetteAgent): CassetteAgent["worktree"] {
+  return agent.spawn.worktree === true ? agent.worktree : undefined;
+}

package/src/run-checkpoint.ts

@@ -0,0 +1,93 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { CassetteCollector, CassetteRun } from "./cassette.ts";
+import { publishCassette } from "./cassette-publish.ts";
+import { checkpointFileName } from "./checkpoint-dir.ts";
+import type { RunOutcome } from "./events.ts";
+
+/**
+ * One Run's publication request: what settled, what it collected, and where the
+ * artifact may go. `record` wins over `checkpointDir`; a Run that neither
+ * recorded nor stopped publishes nothing.
+ */
+export interface RunCheckpointOptions {
+  /** Terminal outcome of the Run; only `stopped` publishes without `record`. */
+  readonly outcome: RunOutcome;
+  readonly collector: CassetteCollector;
+  /** Explicit `--record` destination; overrides the default checkpoint directory. */
+  readonly record: string | undefined;
+  /** Already-resolved default directory a stopped Run publishes into. */
+  readonly checkpointDir: string;
+  /** Program entry point recorded as invocation identity; omitted when unknown. */
+  readonly programFile: string | undefined;
+  readonly args: unknown;
+}
+
+/**
+ * Publishes the collected Cassette when the Run must be restorable: always under
+ * `--record`, and additionally into the checkpoint directory when the Run
+ * stopped (ADR-0021/0024). Returns the error that must become the Run's outcome,
+ * or null when there was nothing to publish or a primary program error owns it.
+ */
+export async function publishRunCheckpoint(options: RunCheckpointOptions): Promise<unknown | null> {
+  const destination = checkpointDestination(options);
+  if (destination === null) return null;
+  try {
+    if (options.record === undefined) {
+      // Only the default directory is created; an explicit --record path keeps
+      // today's rule that its directory must already exist.
+      await mkdir(options.checkpointDir, { recursive: true, mode: 0o700 });
+    }
+    await publishCassette(destination, options.collector.cassette(await runBlock(options)));
+    return null;
+  } catch (error) {
+    // A secondary publication failure must not displace a primary program error.
+    if (options.outcome === "failed") {
+      writeRecordingDiagnostic(error);
+      return null;
+    }
+    if (options.outcome === "stopped") {
+      return new Error(`run stopped but is not restorable: ${String(error)}`, { cause: error });
+    }
+    // A requested checkpoint silently going missing is worse than rejecting an
+    // otherwise successful Run (ADR-0021).
+    return error;
+  }
+}
+
+function checkpointDestination(options: RunCheckpointOptions): string | null {
+  if (options.record !== undefined) return options.record;
+  if (options.outcome !== "stopped") return null;
+  return join(options.checkpointDir, checkpointFileName());
+}
+
+async function runBlock(options: RunCheckpointOptions): Promise<CassetteRun> {
+  const { outcome, programFile } = options;
+  if (programFile === undefined) return { outcome };
+  const programHash = await hashProgram(programFile);
+  return {
+    outcome,
+    programFile,
+    args: options.args,
+    ...(programHash === null ? {} : { programHash }),
+  };
+}
+
+/** Advisory only: an unreadable program file omits the hash and never fails the Run. */
+async function hashProgram(programFile: string): Promise<string | null> {
+  try {
+    const bytes = await Bun.file(programFile).arrayBuffer();
+    return new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
+export function writeRecordingDiagnostic(error: unknown): void {
+  try {
+    process.stderr.write(`[yaag] ${String(error)}\n`);
+  } catch {
+    // stderr diagnostics are best-effort: a broken stderr must not mask the Run's error either.
+  }
+}

package/src/run-context.ts

@@ -0,0 +1,19 @@
+import type { AgentDefinition } from "./define-agent.ts";
+import type { Handle, SpawnOptions, SpawnOverrides } from "./types.ts";
+
+/** What an Orchestration Program is handed. */
+export interface RunContext<Args = unknown> {
+  /** Program arguments, validated when the program declares a schema (ADR-0010). */
+  readonly args: Args;
+  /**
+   * Starts an Agent and resolves once it is confirmed up.
+   *
+   * Waits on a `get_state` round-trip, so a bad model fails here, before any
+   * tokens are spent. Killed automatically when the Run ends. Worktrees survive
+   * the Run and are never managed after creation. Definitions own policy;
+   * spawn overrides own topology. Runtime callers are validated even when they
+   * bypass TypeScript.
+   */
+  spawn(options?: SpawnOptions): Promise<Handle>;
+  spawn(definition: AgentDefinition, overrides?: SpawnOverrides): Promise<Handle>;
+}

package/src/run.ts

@@ -0,0 +1,274 @@
+import type { TSchema } from "typebox";
+import type { Agent } from "./agent.ts";
+import { validateArgs } from "./args-validation.ts";
+import { type Cassette, CassetteCollector } from "./cassette.ts";
+import { loadCassette } from "./cassette-loader.ts";
+import { cleanStaleCheckpointTemp, resolveCheckpointDirectory } from "./checkpoint-dir.ts";
+import { type OrchestrationProgram, programDefinition } from "./define-run.ts";
+import { isYaagError, YaagError } from "./errors.ts";
+import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "./events.ts";
+import { liveTransport } from "./live-transport.ts";
+import { recordingTransport } from "./recording-transport.ts";
+import { replayTransport } from "./replay-transport.ts";
+import { resumeTransport } from "./resume-transport.ts";
+import { publishRunCheckpoint, writeRecordingDiagnostic } from "./run-checkpoint.ts";
+import type { RunContext } from "./run-context.ts";
+import { liveSkillProbe, type SkillProbeFactory } from "./skill-probe.ts";
+import { skillRestrictionTransport } from "./skill-restriction-transport.ts";
+import { makeSpawn } from "./spawn.ts";
+import { applyEvent, initialSummary, type RunSummary } from "./summary.ts";
+import type { TransportFactory } from "./transport.ts";
+import { worktreeTransport } from "./worktree-transport.ts";
+
+export interface RunOptions {
+  /** Where Agents come from. Defaults to real `pi --mode rpc` processes. */
+  readonly transport?: TransportFactory;
+  readonly events?: StampedEventSink;
+  /** Delivered as `ctx.args`; validated when the program declares an args schema (ADR-0010). */
+  readonly args?: unknown;
+  /** Session storage directory for every Agent of this Run (ticket 06). */
+  readonly sessionDir?: string;
+  /**
+   * Absolute Orchestration Program source path used to resolve portable relative
+   * extension declarations. This is Run context, never an Agent working directory.
+   */
+  readonly programFile?: string;
+  /** Resolves pi's enabled skills for live restriction requests. */
+  readonly skillProbe?: SkillProbeFactory;
+  /** Write every public transport-seam frame once the Run settles. */
+  readonly record?: string;
+  /** Re-run against this versioned Cassette instead of opening a live transport. */
+  readonly replay?: string;
+  /** Replay a matching Cassette prefix, then continue live from its session. */
+  readonly resume?: string;
+  /** Ends the Run early; every Agent is still reaped and costed. */
+  readonly signal?: AbortSignal;
+  /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
+  readonly checkpointDir?: string;
+}
+
+/**
+ * Executes one Orchestration Program and resolves with its return value.
+ *
+ * Every Agent is dead by the time this settles — on success, on failure, and on
+ * abort (ADR-0002) — and every Agent's cost has been emitted. Rejects with
+ * ARGS_INVALID before emitting an event when declared argument schema validation fails.
+ */
+export async function executeRun<Args, Result>(
+  program: OrchestrationProgram<Args, Result>,
+  options: RunOptions = {},
+): Promise<Result> {
+  if (options.record !== undefined && options.replay !== undefined) {
+    throw new YaagError("OPTIONS_CONFLICT", "cannot use record and replay together");
+  }
+  if (options.resume !== undefined && options.replay !== undefined) {
+    throw new YaagError("OPTIONS_CONFLICT", "cannot use resume and replay together");
+  }
+  const checkpointDir = options.checkpointDir ?? resolveCheckpointDirectory();
+  try {
+    // Best-effort, and emits no event, so the ARGS_INVALID "no events before
+    // rejection" rule still holds.
+    await cleanStaleCheckpointTemp(checkpointDir);
+  } catch (error) {
+    writeRecordingDiagnostic(error);
+  }
+  const replay = options.replay === undefined ? null : await loadCassette(options.replay);
+  const resume = options.resume === undefined ? null : await loadCassette(options.resume);
+  const definition = programDefinition(program);
+  // Collection is universal so every Run can checkpoint. Only pause, stop and
+  // --record flush (ADR-0021). That memory is potentially unbounded over
+  // arbitrarily many Asks — yaag has no Run token budget (ADR-0012/0017), and
+  // this ADR does not pretend one exists.
+  const collector = new CassetteCollector();
+  const args: unknown = Object.hasOwn(options, "args") ? options.args : {};
+  try {
+    assertArgs<Args>(definition.args, args);
+  } catch (error) {
+    await publishRunCheckpoint({
+      outcome: "failed",
+      collector,
+      record: options.record,
+      checkpointDir,
+      programFile: options.programFile,
+      args,
+    });
+    throw error;
+  }
+
+  let summary: RunSummary = initialSummary();
+  const sink: StampedEventSink = options.events ?? (() => {});
+  // Every event the Run emits also feeds the fold, so its own final accounting
+  // is derived exactly the way an outside observer would derive it. `at` is
+  // stamped here, once, so no individual emitter touches the wall clock.
+  const emit: EventSink = (body) => {
+    const event: LifecycleEvent = { ...body, at: Date.now() };
+    summary = applyEvent(summary, event);
+    sink(event);
+  };
+  const factory = selectFactory({ options, collector, replay, resume });
+  const agents: Agent[] = [];
+  const startedAt = Date.now();
+  const spawnGate = makeSpawn({
+    factory,
+    agents,
+    emit,
+    sessionDir: options.sessionDir,
+    programFile: options.programFile,
+  });
+
+  const ctx: RunContext<Args> = { args, spawn: spawnGate.spawn };
+  emit({ type: "run_start", program: definition.name ?? "program" });
+
+  // The program's settlement is held rather than rethrown from a `finally`, so
+  // publication can displace it when the checkpoint fails (ADR-0021).
+  let outcome: RunOutcome = "failed";
+  let settled: Settlement<Result>;
+  try {
+    const value = await Promise.race([definition.run(ctx), stopped(options.signal)]);
+    outcome = "completed";
+    settled = { ok: true, value };
+  } catch (error) {
+    outcome = stopOutcome(error);
+    settled = { ok: false, error };
+  }
+  spawnGate.close();
+  await reapAll({ agents, emit });
+  // run_end is the acknowledgement: nothing may report an outcome before the
+  // checkpoint's destination-directory fsync has landed (ADR-0021).
+  const failure = await publishRunCheckpoint({
+    outcome,
+    collector,
+    record: options.record,
+    checkpointDir,
+    programFile: options.programFile,
+    args,
+  });
+  emitRunEnd({
+    emit,
+    outcome: failure === null ? outcome : "failed",
+    durationMs: Date.now() - startedAt,
+    summary,
+  });
+  if (failure !== null) throw failure;
+  if (!settled.ok) throw settled.error;
+  return settled.value;
+}
+
+/** What the Orchestration Program body produced, before the Run acknowledges it. */
+type Settlement<Result> =
+  | { readonly ok: true; readonly value: Result }
+  | { readonly ok: false; readonly error: unknown };
+
+/** The stop signal is the only rejection that is not a Run failure (ADR-0022). */
+function stopOutcome(error: unknown): RunOutcome {
+  return isYaagError(error) && error.code === "RUN_STOPPED" ? "stopped" : "failed";
+}
+
+/**
+ * Narrows the Run's incoming args to the program's declared Args at the one
+ * boundary where untyped input enters typed code. Schema programs are proven
+ * here by `validateArgs` (rejects ARGS_INVALID); schemaless programs declared
+ * Args themselves in `defineRun`, so the narrowing restates the program's own
+ * contract rather than inventing one.
+ */
+function assertArgs<Args>(schema: TSchema | undefined, value: unknown): asserts value is Args {
+  if (schema !== undefined) validateArgs(schema, value);
+}
+
+/**
+ * Inputs that select the Run's transport composition. The collector receives
+ * every frame from every Run. Replay and resume hold the loaded Cassettes, or
+ * null when the Run does not use them.
+ */
+export interface FactorySelection {
+  readonly options: RunOptions;
+  readonly collector: CassetteCollector;
+  readonly replay: Cassette | null;
+  readonly resume: Cassette | null;
+}
+
+/**
+ * Composes the Run's transport. Strict replay deliberately bypasses the
+ * worktree wrapper; resume retains its worktree-wrapped live side for unmatched
+ * spawns (ADR-0013). The live order is worktree → skill restriction → live, so
+ * skill discovery occurs in the resolved worktree cwd.
+ *
+ * The recorder is the outermost wrapper of every composition, replay included:
+ * it observes only, and never changes delegation (ADR-0013/0021).
+ */
+export function selectFactory(selection: FactorySelection): TransportFactory {
+  const base =
+    selection.replay !== null ? replayTransport(selection.replay) : selectLiveFactory(selection);
+  return recordingTransport(base, selection.collector);
+}
+
+function selectLiveFactory(selection: FactorySelection): TransportFactory {
+  const restricted = skillRestrictionTransport(
+    selection.options.transport ?? liveTransport,
+    selection.options.skillProbe ?? liveSkillProbe,
+  );
+  const live = worktreeTransport(restricted);
+  return selection.resume === null ? live : resumeTransport(selection.resume, live);
+}
+
+/** Rejects when the Run is stopped; never resolves. */
+function stopped(signal: AbortSignal | undefined): Promise<never> {
+  return new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    if (signal.aborted) reject(new YaagError("RUN_STOPPED", "run stopped"));
+    signal.addEventListener("abort", () => reject(new YaagError("RUN_STOPPED", "run stopped")), {
+      once: true,
+    });
+  });
+}
+
+interface ReapOptions {
+  readonly agents: readonly Agent[];
+  readonly emit: EventSink;
+}
+
+/** Reaping never throws: a failed shutdown must not mask the Run's own error. */
+async function reapAll({ agents, emit }: ReapOptions): Promise<void> {
+  await Promise.all(
+    agents.map(async (agent) => {
+      try {
+        await agent.close();
+      } catch {
+        // close() threw, so the Agent never emitted its own exit. Emit one, or
+        // the fold — and every observer — would lose the Agent entirely.
+        emit({
+          type: "agent_exit",
+          agent: agent.name,
+          tokens: null,
+          cost: null,
+          incomplete: true,
+          ...(agent.branch === undefined
+            ? {}
+            : { worktree: { cwd: agent.cwd, branch: agent.branch } }),
+        });
+      }
+    }),
+  );
+}
+
+interface RunEndOptions {
+  readonly emit: EventSink;
+  readonly outcome: RunOutcome;
+  readonly durationMs: number;
+  /** Settled fold: every Agent is reaped and the checkpoint is published by now. */
+  readonly summary: RunSummary;
+}
+
+/** Emits the Run's acknowledgement, the last Lifecycle Event of every Run. */
+function emitRunEnd({ emit, outcome, durationMs, summary }: RunEndOptions): void {
+  emit({
+    type: "run_end",
+    ok: outcome === "completed",
+    outcome,
+    durationMs,
+    cost: summary.cost,
+    tokens: summary.tokens,
+    incomplete: summary.incomplete,
+    worstFrameGapMs: summary.worstFrameGapMs,
+  });
+}