@yaag/runtime 0.1.4 → 0.2.0

package/src/run.ts

@@ -1,9 +1,15 @@
+import { join } from "node:path";
 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 Cassette, CassetteCollector, type CassetteSink } from "./cassette.ts";
+import { assertReplayable, interruptedResumeWarning, loadCassette } from "./cassette-loader.ts";
+import {
+  checkpointFileName,
+  cleanStaleCheckpointTemp,
+  resolveCheckpointDirectory,
+} from "./checkpoint-dir.ts";
+import { createCheckpointFlusher, flushingSink } from "./checkpoint-flush.ts";
 import { type OrchestrationProgram, programDefinition } from "./define-run.ts";
 import { isYaagError, YaagError } from "./errors.ts";
 import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "./events.ts";
@@ -11,7 +17,12 @@ 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 {
+  publishRunCheckpoint,
+  type RunCheckpointResult,
+  resolveRunIdentity,
+  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";
@@ -72,26 +83,28 @@ export async function executeRun<Args, Result>(
   } 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 replay = await loadReplay(options.replay);
+  const resume = await loadResume(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.
+  // Collection is universal so every Run can checkpoint, and every Run flushes
+  // that collection at each Ask boundary (ADR-0031). Only a stopped Run and a
+  // --record Run keep the artifact once the Run settles (ADR-0021). That memory
+  // is potentially unbounded over arbitrarily many Asks — yaag has no Run token
+  // budget (ADR-0012/0017), and these ADRs do not pretend one exists.
   const collector = new CassetteCollector();
   const args: unknown = Object.hasOwn(options, "args") ? options.args : {};
+  // Fixed here, so every Ask-boundary flush and the settlement write one file,
+  // and so run_start can name it (ADR-0031).
+  const destination = options.record ?? join(checkpointDir, checkpointFileName());
+  const identity = await resolveRunIdentity(options.programFile, args);
+  const checkpoint = { collector, record: options.record, destination, identity };
   try {
     assertArgs<Args>(definition.args, args);
   } catch (error) {
-    await publishRunCheckpoint({
-      outcome: "failed",
-      collector,
-      record: options.record,
-      checkpointDir,
-      programFile: options.programFile,
-      args,
-    });
+    // The result is discarded on purpose: this rejection precedes run_start, and
+    // no event may precede an ARGS_INVALID rejection, so a lost Checkpoint here
+    // stays a stderr diagnostic (ticket 04).
+    await publishRunCheckpoint({ outcome: "failed", ...checkpoint });
     throw error;
   }
 
@@ -105,7 +118,13 @@ export async function executeRun<Args, Result>(
     summary = applyEvent(summary, event);
     sink(event);
   };
-  const factory = selectFactory({ options, collector, replay, resume });
+  const flusher = createCheckpointFlusher(checkpoint);
+  const factory = selectFactory({
+    options,
+    collector: flushingSink(collector, flusher),
+    replay,
+    resume,
+  });
   const agents: Agent[] = [];
   const startedAt = Date.now();
   const spawnGate = makeSpawn({
@@ -117,7 +136,7 @@ export async function executeRun<Args, Result>(
   });
 
   const ctx: RunContext<Args> = { args, spawn: spawnGate.spawn };
-  emit({ type: "run_start", program: definition.name ?? "program" });
+  emit({ type: "run_start", program: definition.name ?? "program", artifact: destination });
 
   // The program's settlement is held rather than rethrown from a `finally`, so
   // publication can displace it when the checkpoint fails (ADR-0021).
@@ -133,27 +152,40 @@ export async function executeRun<Args, Result>(
   }
   spawnGate.close();
   await reapAll({ agents, emit });
+  // No flush may land after the settled artifact, or an acknowledged Run would
+  // be overwritten by an `interrupted` one.
+  await flusher.quiesce();
   // 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,
-  });
+  const publication = await publishRunCheckpoint({ outcome, ...checkpoint });
   emitRunEnd({
     emit,
-    outcome: failure === null ? outcome : "failed",
     durationMs: Date.now() - startedAt,
     summary,
+    ...endingFrom(publication, outcome),
   });
-  if (failure !== null) throw failure;
+  if (publication.kind === "displaced") throw publication.error;
   if (!settled.ok) throw settled.error;
   return settled.value;
 }
 
+/** Loads a strict-replay source, which must be a settled Cassette (ADR-0031). */
+async function loadReplay(path: string | undefined): Promise<Cassette | null> {
+  if (path === undefined) return null;
+  const cassette = await loadCassette(path);
+  assertReplayable(cassette, path);
+  return cassette;
+}
+
+/** Loads a resume source, warning once when it came from a hard death (ADR-0031). */
+async function loadResume(path: string | undefined): Promise<Cassette | null> {
+  if (path === undefined) return null;
+  const cassette = await loadCassette(path);
+  const warning = interruptedResumeWarning(cassette, path);
+  if (warning !== null) writeRecordingDiagnostic(warning);
+  return cassette;
+}
+
 /** What the Orchestration Program body produced, before the Run acknowledges it. */
 type Settlement<Result> =
   | { readonly ok: true; readonly value: Result }
@@ -182,7 +214,8 @@ function assertArgs<Args>(schema: TSchema | undefined, value: unknown): asserts
  */
 export interface FactorySelection {
   readonly options: RunOptions;
-  readonly collector: CassetteCollector;
+  /** Receives every frame; wrapped so Ask boundaries flush the Checkpoint (ADR-0031). */
+  readonly collector: CassetteSink;
   readonly replay: Cassette | null;
   readonly resume: Cassette | null;
 }
@@ -257,12 +290,33 @@ interface RunEndOptions {
   readonly durationMs: number;
   /** Settled fold: every Agent is reaped and the checkpoint is published by now. */
   readonly summary: RunSummary;
+  /** Publication error text when a requested Checkpoint was lost (ticket 04). */
+  readonly checkpointLost?: string;
+}
+
+/**
+ * Folds one publication result into how the Run ends. A displaced publication
+ * takes the outcome; a lost Checkpoint keeps it and reports the loss instead.
+ */
+function endingFrom(
+  publication: RunCheckpointResult,
+  outcome: RunOutcome,
+): { readonly outcome: RunOutcome; readonly checkpointLost?: string } {
+  switch (publication.kind) {
+    case "published":
+      return { outcome };
+    case "lost":
+      return { outcome, checkpointLost: publication.message };
+    case "displaced":
+      return { outcome: "failed" };
+  }
 }
 
 /** Emits the Run's acknowledgement, the last Lifecycle Event of every Run. */
-function emitRunEnd({ emit, outcome, durationMs, summary }: RunEndOptions): void {
+function emitRunEnd({ emit, outcome, durationMs, summary, checkpointLost }: RunEndOptions): void {
   emit({
     type: "run_end",
+    ...(checkpointLost === undefined ? {} : { checkpointLost }),
     ok: outcome === "completed",
     outcome,
     durationMs,

package/src/spawn.ts

@@ -5,9 +5,16 @@ import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "
 import { YaagError } from "./errors.ts";
 import type { EventSink } from "./events.ts";
 import { resolveExtensionPaths } from "./extension-paths.ts";
+import { normalizeModelResolution } from "./model-resolution.ts";
 import type { RunContext } from "./run-context.ts";
 import type { AgentTransport, TransportFactory, TransportStartup } from "./transport.ts";
-import type { AskOptions, Handle, SpawnOptions, SpawnOverrides } from "./types.ts";
+import type {
+  AskOptions,
+  Handle,
+  ResolvedSpawnOptions,
+  SpawnOptions,
+  SpawnOverrides,
+} from "./types.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
 export interface SpawnDependencies {
@@ -41,12 +48,13 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
     const request = resolveRequest(definitionOrOptions, overrides);
     const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
     const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, taken);
+    const spawnOptions = resolveSpawnSelection(request.spawnOptions, name);
     try {
       const opened = await openTransport({
         factory: deps.factory,
         name,
         cwd,
-        spawnOptions: request.spawnOptions,
+        spawnOptions,
         sessionDir: deps.sessionDir,
         programFile: deps.programFile,
       });
@@ -59,7 +67,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
         branch,
         transport: opened.transport,
         emit: deps.emit,
-        spawnOptions: request.spawnOptions,
+        spawnOptions,
         ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
         ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
       });
@@ -92,6 +100,23 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   };
 }
 
+/**
+ * Attempt-0 shim for Model Resolution: one selection, no retry loop.
+ * Ticket 02 replaces this with the fallback loop and MODEL_RESOLUTION_FAILED.
+ */
+function resolveSpawnSelection(options: SpawnOptions, name: string): ResolvedSpawnOptions {
+  const selection = normalizeModelResolution(options).resolve([]);
+  if (selection === undefined) {
+    throw new YaagError("SPAWN_FAILED", `agent "${name}": no model candidate to try`, name);
+  }
+  const { model: _model, thinking: _thinking, ...rest } = options;
+  return {
+    ...rest,
+    ...(selection.model === undefined ? {} : { model: selection.model }),
+    ...(selection.thinking === undefined ? {} : { thinking: selection.thinking }),
+  };
+}
+
 type MutableSpawnOverrides = { -readonly [Key in keyof SpawnOverrides]: SpawnOverrides[Key] };
 
 interface SpawnRequest {
@@ -180,7 +205,7 @@ interface OpenTransportOptions {
   readonly factory: TransportFactory;
   readonly name: string;
   readonly cwd: string;
-  readonly spawnOptions: SpawnOptions;
+  readonly spawnOptions: ResolvedSpawnOptions;
   readonly sessionDir: string | undefined;
   readonly programFile: string | undefined;
 }

package/src/stall-watchdog.ts

@@ -0,0 +1,193 @@
+import type { CommandResponse } from "./connection.ts";
+import type { AskStalledOutcome } from "./errors.ts";
+import { readAgentProgress } from "./pi-state.ts";
+import type { Frame } from "./transport.ts";
+
+/** Silence allowed on a live Ask before the Stall Watchdog probes the Agent. */
+export const DEFAULT_STALL_MS = 600_000;
+/** Time allowed for the `get_state` probe to answer before yaag kills the Agent. */
+export const STALL_PROBE_SETTLE_MS = 45_000;
+
+/** Why an Ask settled: normal frames, watchdog recovery, or a stall rejection. */
+export type SettlementCause = "normal" | "recovered" | "stalled";
+
+/** Rejection carried by {@link StallWatchdog.failed} for both stall outcomes. */
+export class StallSignal extends Error {
+  readonly outcome: AskStalledOutcome;
+
+  constructor(outcome: AskStalledOutcome) {
+    super(
+      `no frame for ${outcome.idleMs}ms and the state probe ${
+        outcome.destructive ? "did not answer" : "reported work in progress"
+      }`,
+    );
+    this.name = "StallSignal";
+    this.outcome = outcome;
+  }
+}
+
+export interface StallWatchdogOptions {
+  /** Silence, in milliseconds, that arms the probe. */
+  readonly stallMs: number;
+  /** Bounded wait for the probe response; defaults to 45s. */
+  readonly probeSettleMs?: number;
+  /** Sends one command to the Agent and resolves with its response. */
+  readonly command: (frame: Frame) => Promise<CommandResponse>;
+  /** True when this Ask already observed a terminal assistant `message_end`. */
+  readonly terminal: () => boolean;
+  /** Settles the Ask from the observed terminal state. */
+  readonly recover: () => void;
+}
+
+/**
+ * Default liveness guard for every live Ask (ADR-0029).
+ *
+ * It measures silence, not wall time: any Agent frame resets the timer, so a
+ * legitimately long Ask is never punished. On expiry it sends one `get_state`
+ * probe and takes one of three exits:
+ * - the probe answers, the Agent is not working, and this Ask already saw a
+ *   terminal assistant `message_end` — the Ask settles as `recovered`;
+ * - the probe answers and the Agent is still working — the Ask fails with a
+ *   recoverable `ASK_STALLED` and the Agent stays alive;
+ * - the probe stays silent — the Ask fails with a destructive `ASK_STALLED`
+ *   and the Agent is killed.
+ */
+export class StallWatchdog {
+  readonly #stallMs: number;
+  readonly #probeSettleMs: number;
+  readonly #command: (frame: Frame) => Promise<CommandResponse>;
+  readonly #terminal: () => boolean;
+  readonly #recover: () => void;
+  readonly #failure: Promise<never>;
+  #reject: (reason: unknown) => void = () => {};
+  #stallTimer: ReturnType<typeof setTimeout> | undefined;
+  #probeTimer: ReturnType<typeof setTimeout> | undefined;
+  #tripped = false;
+  #done = false;
+  #cause: SettlementCause = "normal";
+  #result: AskStalledOutcome | null = null;
+
+  constructor(options: StallWatchdogOptions) {
+    this.#stallMs = options.stallMs;
+    this.#probeSettleMs = options.probeSettleMs ?? STALL_PROBE_SETTLE_MS;
+    this.#command = options.command;
+    this.#terminal = options.terminal;
+    this.#recover = options.recover;
+    this.#failure = new Promise<never>((_resolve, reject) => {
+      this.#reject = reject;
+    });
+    // The race may settle before the Ask starts awaiting it.
+    void this.#failure.catch(() => {});
+  }
+
+  /** Arms the silence timer immediately before the prompt command is sent. */
+  start(): void {
+    this.#arm();
+  }
+
+  /** Resets the silence timer. Frames that arrive after the probe are ignored. */
+  observe(_frame: Frame): void {
+    if (this.#done || this.#tripped) return;
+    this.#arm();
+  }
+
+  /**
+   * Disarms the watchdog for a settled turn, so the commands that follow
+   * settlement — `get_last_assistant_text` and output steering — can never be
+   * mistaken for Agent silence. Idempotent.
+   */
+  settled(): void {
+    if (this.#tripped) return;
+    this.cleanup();
+  }
+
+  /** Re-arms the timer for a further effort in the same Ask. Inert after a trip. */
+  rearm(): void {
+    if (this.#done || this.#tripped) return;
+    this.#arm();
+  }
+
+  /** Cancels every timer once the Ask leaves. Idempotent. */
+  cleanup(): void {
+    clearTimeout(this.#stallTimer);
+    clearTimeout(this.#probeTimer);
+    this.#stallTimer = undefined;
+    this.#probeTimer = undefined;
+  }
+
+  /** How this Ask settled, as reported in its `ask_end` Lifecycle Event. */
+  get cause(): SettlementCause {
+    return this.#cause;
+  }
+
+  /** The stalled outcome, once the probe protocol resolved either way. */
+  get result(): AskStalledOutcome | null {
+    return this.#result;
+  }
+
+  /** Rejects with a {@link StallSignal} on both stall exits. */
+  get failed(): Promise<never> {
+    return this.#failure;
+  }
+
+  #arm(): void {
+    clearTimeout(this.#stallTimer);
+    this.#stallTimer = setTimeout(() => this.#trip(), this.#stallMs);
+  }
+
+  #trip(): void {
+    if (this.#done || this.#tripped) return;
+    this.#tripped = true;
+    clearTimeout(this.#stallTimer);
+    this.#stallTimer = undefined;
+    this.#probeTimer = setTimeout(() => this.#fail(true), this.#probeSettleMs);
+    void this.#probe();
+  }
+
+  async #probe(): Promise<void> {
+    let response: CommandResponse;
+    try {
+      response = await this.#command({ type: "get_state" });
+    } catch {
+      // A dead Agent or a refused probe is silence: the kill timer decides.
+      return;
+    }
+    if (this.#done) return;
+    const progress = readAgentProgress(response.data);
+    // Unreadable state is treated as work in progress: yaag never invents a
+    // settlement it did not observe.
+    if (progress !== null && !progress.working && this.#terminal()) {
+      this.#done = true;
+      this.#cause = "recovered";
+      this.cleanup();
+      this.#recover();
+      return;
+    }
+    this.#fail(false, progress ?? undefined);
+  }
+
+  #fail(destructive: boolean, state?: AskStalledOutcome["state"]): void {
+    if (this.#done) return;
+    this.#done = true;
+    this.#cause = "stalled";
+    this.#result = {
+      idleMs: this.#stallMs,
+      destructive,
+      ...(state === undefined ? {} : { state }),
+    };
+    this.cleanup();
+    this.#reject(new StallSignal(this.#result));
+  }
+}
+
+/**
+ * Resolves the effective stall budget.
+ *
+ * `false` and any value that is not above zero disable the watchdog for one
+ * Ask. An absent value takes the 10-minute default.
+ */
+export function stallBudgetMs(stallMs: number | false | undefined): number | null {
+  if (stallMs === false) return null;
+  if (stallMs === undefined) return DEFAULT_STALL_MS;
+  return stallMs > 0 ? stallMs : null;
+}

package/src/summary-agent.ts

@@ -184,11 +184,19 @@ export function setActivity(
  * Folds an Ask settlement into the idle arm, retaining the settled Ask identity.
  * Older stamped events are ignored and legacy unstamped events use stream order.
  */
+/** One Ask settlement as the fold sees it. */
+export interface AskSettlement {
+  readonly index: number;
+  /** A recovered settlement makes this Agent's accounting a floor, not a total. */
+  readonly recovered: boolean;
+}
+
 export function endAsk(
   current: AgentRecord | undefined,
-  index: number,
+  settlement: AskSettlement,
   at: number | null,
 ): AgentRecord {
+  const { index, recovered } = settlement;
   const agent = current ?? placeholderAgent();
   if (
     !canChangeAskState(agent, at) ||
@@ -202,6 +210,7 @@ export function endAsk(
     state: "idle",
     askIndex: index,
     activity: null,
+    incomplete: agent.incomplete || recovered,
     stateChangedAt: at,
   };
 }
@@ -268,7 +277,7 @@ export function totalsFromAgents(agents: Readonly<Record<string, AgentRecord>>):
       ? null
       : records.reduce(addTokens, zeroTokens()),
     incomplete: records.some(
-      (agent) => agent.state === "exited" && (agent.incomplete || agent.cost === null),
+      (agent) => agent.incomplete || (agent.state === "exited" && agent.cost === null),
     ),
   };
 }

package/src/summary.ts

@@ -31,6 +31,11 @@ export type RunState = "running" | "ended";
 interface RunSummaryBase {
   readonly program: string;
   readonly startedAt: number | null;
+  /**
+   * Path of the Run's Checkpoint, as `run_start` named it (ADR-0031). It is
+   * null for a Run whose CLI is older than that event field.
+   */
+  readonly artifact: string | null;
   readonly agents: Readonly<Record<string, AgentInfo>>;
   readonly asksStarted: number;
   readonly asksSettled: number;
@@ -55,6 +60,11 @@ export interface EndedRunSummary extends RunSummaryBase {
   readonly ok: boolean;
   /** The `run_end.at` event fact used to reject strictly older stamped endings. */
   readonly endedAt: number | null;
+  /**
+   * The Run asked for a Checkpoint with `--record`, failed, and lost the
+   * artifact too. Carries the publication error text (ticket 04).
+   */
+  readonly checkpointLost?: string;
 }
 
 /**
@@ -82,6 +92,7 @@ export function initialSummary(): RunningRunSummary {
     runState: "running",
     outcome: null,
     startedAt: null,
+    artifact: null,
     agents: {},
     asksStarted: 0,
     asksSettled: 0,
@@ -111,7 +122,12 @@ export function applyEvent(
   const at = "at" in event ? event.at : null;
   switch (event.type) {
     case "run_start":
-      return { ...summary, program: event.program, startedAt: at };
+      return {
+        ...summary,
+        program: event.program,
+        startedAt: at,
+        artifact: event.artifact ?? null,
+      };
     case "agent_spawn":
       return withAgent(summary, event.agent, spawnAgent(summary.agents[event.agent], event, at));
     case "ask_start":
@@ -158,6 +174,7 @@ function endRun(
     endedAt: at,
     durationMs: event.durationMs,
     worstFrameGapMs: event.worstFrameGapMs,
+    ...(event.checkpointLost === undefined ? {} : { checkpointLost: event.checkpointLost }),
   };
 }
 
@@ -195,7 +212,11 @@ function settleAsk(
   const next = withAgent(
     { ...summary, asksSettled: summary.asksSettled + 1 },
     event.agent,
-    endAsk(summary.agents[event.agent], event.index, at),
+    endAsk(
+      summary.agents[event.agent],
+      { index: event.index, recovered: event.cause === "recovered" },
+      at,
+    ),
   );
   return {
     ...next,

package/src/thinking-level.ts

@@ -0,0 +1,32 @@
+/**
+ * pi's supported thinking levels.
+ *
+ * Lives in its own leaf module so both `types.ts` and the Model Resolution
+ * modules can depend on it without forming an import cycle.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/**
+ * The closed level list, authored as a total record so that adding a level to
+ * `ThinkingLevel` breaks this build instead of silently omitting the level.
+ * Authority: pi `docs/rpc.md` "Levels:".
+ */
+const levels: Record<ThinkingLevel, true> = {
+  off: true,
+  minimal: true,
+  low: true,
+  medium: true,
+  high: true,
+  xhigh: true,
+  max: true,
+};
+
+/** Every thinking level pi accepts, in documented order. */
+export const THINKING_LEVELS: readonly ThinkingLevel[] = Object.freeze(
+  Object.keys(levels) as ThinkingLevel[],
+);
+
+/** True only for one of pi's thinking levels; case-sensitive and total. */
+export function isThinkingLevel(value: unknown): value is ThinkingLevel {
+  return typeof value === "string" && Object.hasOwn(levels, value);
+}