@yaag/runtime 0.1.0

package/src/ask-output-tail.ts

@@ -0,0 +1,166 @@
+import type { AskOutputChannel } from "./events.ts";
+import type { Frame } from "./transport.ts";
+import {
+  ASK_OUTPUT_FLUSH_INTERVAL_MS,
+  ASK_OUTPUT_MAX_BYTES,
+  ASK_OUTPUT_TRUNCATION_MARKER,
+} from "./wire-constants.ts";
+
+/** The timer boundary used to test output batching without changing its wire rate. */
+export interface AskOutputTailScheduler<Handle = unknown> {
+  schedule(callback: () => void): Handle;
+  cancel(timer: Handle): void;
+}
+
+interface AskOutputTailOptions {
+  readonly report: (channel: AskOutputChannel, text: string) => void;
+  readonly scheduler?: AskOutputTailScheduler;
+}
+
+interface OutputSegment {
+  readonly channel: AskOutputChannel;
+  readonly text: string;
+}
+
+const encoder = new TextEncoder();
+const scheduler: AskOutputTailScheduler<ReturnType<typeof setTimeout>> = {
+  schedule: (callback) => setTimeout(callback, ASK_OUTPUT_FLUSH_INTERVAL_MS),
+  cancel: (timer) => clearTimeout(timer),
+};
+
+/**
+ * Coalesces live assistant deltas into channel-tagged, UTF-8-bounded output tails.
+ *
+ * Malformed and unsupported frames are ignored. `close()` flushes synchronously and
+ * prevents a timer from emitting after an Ask terminal event.
+ */
+export class AskOutputTail {
+  readonly #report: (channel: AskOutputChannel, text: string) => void;
+  readonly #scheduler: AskOutputTailScheduler;
+  #segments: OutputSegment[] = [];
+  #timer: unknown;
+  #truncated = false;
+  #closed = false;
+
+  constructor(options: AskOutputTailOptions) {
+    this.#report = options.report;
+    this.#scheduler = options.scheduler ?? scheduler;
+  }
+
+  /** Inspects one frame and queues only non-empty assistant thinking or text deltas. */
+  observe(frame: Frame): void {
+    if (this.#closed) return;
+    const segment = outputFromFrame(frame);
+    if (segment === null) return;
+    this.#append(segment);
+    if (this.#timer === undefined) this.#timer = this.#scheduler.schedule(() => this.flush());
+  }
+
+  /** Emits one pending batch immediately and cancels its scheduled trailing flush. */
+  flush(): void {
+    this.#cancelTimer();
+    if (this.#segments.length === 0) return;
+    const segments = this.#truncated ? prependMarker(this.#segments) : this.#segments;
+    this.#segments = [];
+    this.#truncated = false;
+    for (const segment of segments) this.#report(segment.channel, segment.text);
+  }
+
+  /** Flushes remaining output and prevents future observations or timer emissions. */
+  close(): void {
+    this.flush();
+    this.#closed = true;
+  }
+
+  #append(segment: OutputSegment): void {
+    const previous = this.#segments.at(-1);
+    this.#segments =
+      previous?.channel === segment.channel
+        ? [
+            ...this.#segments.slice(0, -1),
+            { channel: segment.channel, text: previous.text + segment.text },
+          ]
+        : [...this.#segments, segment];
+    if (this.#truncated || byteLength(this.#segments) > ASK_OUTPUT_MAX_BYTES) {
+      this.#truncated = true;
+      this.#segments = coalesce(
+        newestTail(this.#segments, ASK_OUTPUT_MAX_BYTES - bytes(ASK_OUTPUT_TRUNCATION_MARKER)),
+      );
+    }
+  }
+
+  #cancelTimer(): void {
+    if (this.#timer === undefined) return;
+    this.#scheduler.cancel(this.#timer);
+    this.#timer = undefined;
+  }
+}
+
+function outputFromFrame(frame: Frame): OutputSegment | null {
+  if (frame.type !== "message_update" || !isRecord(frame.assistantMessageEvent)) return null;
+  const { type, delta } = frame.assistantMessageEvent;
+  if (typeof delta !== "string" || delta === "") return null;
+  if (type === "text_delta") return { channel: "text", text: delta };
+  if (type === "thinking_delta") return { channel: "thinking", text: delta };
+  return null;
+}
+
+function prependMarker(segments: readonly OutputSegment[]): OutputSegment[] {
+  const first = segments[0];
+  if (first === undefined) return [];
+  return [{ ...first, text: ASK_OUTPUT_TRUNCATION_MARKER + first.text }, ...segments.slice(1)];
+}
+
+function coalesce(segments: readonly OutputSegment[]): OutputSegment[] {
+  const coalesced: OutputSegment[] = [];
+  for (const segment of segments) {
+    const previous = coalesced.at(-1);
+    if (previous?.channel === segment.channel) {
+      coalesced[coalesced.length - 1] = {
+        channel: segment.channel,
+        text: previous.text + segment.text,
+      };
+    } else {
+      coalesced.push(segment);
+    }
+  }
+  return coalesced;
+}
+
+function newestTail(segments: readonly OutputSegment[], limit: number): OutputSegment[] {
+  let remaining = limit;
+  const tail: OutputSegment[] = [];
+  for (const segment of [...segments].reverse()) {
+    if (remaining === 0) break;
+    const text = suffixWithinBytes(segment.text, remaining);
+    if (text !== "") {
+      tail.unshift({ channel: segment.channel, text });
+      remaining -= bytes(text);
+    }
+  }
+  return tail;
+}
+
+function suffixWithinBytes(value: string, limit: number): string {
+  let total = 0;
+  let start = value.length;
+  for (const point of Array.from(value).reverse()) {
+    const size = bytes(point);
+    if (total + size > limit) break;
+    total += size;
+    start -= point.length;
+  }
+  return value.slice(start);
+}
+
+function byteLength(segments: readonly OutputSegment[]): number {
+  return segments.reduce((total, segment) => total + bytes(segment.text), 0);
+}
+
+function bytes(value: string): number {
+  return encoder.encode(value).byteLength;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}

package/src/ask-output.ts

@@ -0,0 +1,109 @@
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+import type { AskInvalidOutputOutcome } from "./errors.ts";
+import { YaagError } from "./errors.ts";
+import type { AskInvalidOutputPlayback } from "./transport.ts";
+import { formatValidationErrors } from "./validation-errors.ts";
+
+/** Versioned extraction behavior. It becomes Cassette identity in issue 04. */
+export const ASK_OUTPUT_EXTRACTION_POLICY = "json-first-block/v1";
+
+/** The currently implemented extraction policy identifier. */
+export type AskOutputExtractionPolicy = typeof ASK_OUTPUT_EXTRACTION_POLICY;
+
+export type AskOutputResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly errors: readonly string[] };
+
+/** Extracts the first parseable JSON object or array and validates it without coercion. */
+export function validateAskOutput(text: string, schema: TSchema): AskOutputResult {
+  const value = firstJsonBlock(text);
+  if (value === undefined) return { ok: false, errors: ["$: no parseable JSON block found"] };
+  const errors = formatValidationErrors(value, Value.Errors(schema, value));
+  return errors.length === 0 ? { ok: true, value } : { ok: false, errors };
+}
+
+/** Produces the deterministic prompt for one correction effort. */
+export function formatAskOutputCorrection(errors: readonly string[]): string {
+  return [
+    "Your previous result did not satisfy the required JSON output schema:",
+    ...errors,
+    "Please resend a complete conforming JSON result.",
+  ].join("\n");
+}
+
+/**
+ * Resolves a replayed Ask's structured output from its recorded text and outcome.
+ *
+ * A recorded invalid-output outcome rethrows deterministically (ADR-0027); otherwise
+ * the text is re-validated so playback and live settlement agree. Throws the same
+ * recoverable ASK_INVALID_OUTPUT error as a live Ask on validation failure.
+ */
+export function resolvePlaybackAskOutput(
+  agent: string,
+  schema: TSchema,
+  text: string,
+  recordedOutcome: AskInvalidOutputPlayback | undefined,
+): unknown {
+  const result = validateAskOutput(text, schema);
+  const errors = result.ok ? [] : result.errors;
+  if (recordedOutcome !== undefined) {
+    throw invalidAskOutputError(agent, {
+      steeringEfforts: recordedOutcome.steeringEfforts,
+      errors,
+    });
+  }
+  if (result.ok) return result.value;
+  throw invalidAskOutputError(agent, { steeringEfforts: 0, errors });
+}
+
+/** Creates the recoverable error for final structured-output validation failure. */
+export function invalidAskOutputError(agent: string, outcome: AskInvalidOutputOutcome): YaagError {
+  return new YaagError(
+    "ASK_INVALID_OUTPUT",
+    `agent "${agent}": invalid structured output after ${outcome.steeringEfforts} steering efforts: ${outcome.errors.join("\n")}`,
+    agent,
+    outcome,
+  );
+}
+
+function firstJsonBlock(text: string): unknown | undefined {
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] !== "{" && text[index] !== "[") continue;
+    const candidate = balancedJson(text, index);
+    if (candidate === undefined) continue;
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      // The first syntactically balanced source fragment need not be valid JSON.
+    }
+  }
+  return undefined;
+}
+
+function balancedJson(text: string, start: number): string | undefined {
+  const opens: string[] = [];
+  let quote = false;
+  let escaped = false;
+  for (let index = start; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') quote = false;
+      continue;
+    }
+    if (character === '"') {
+      quote = true;
+      continue;
+    }
+    if (character === "{" || character === "[") opens.push(character);
+    if (character !== "}" && character !== "]") continue;
+    const opening = opens.pop();
+    if ((character === "}" && opening !== "{") || (character === "]" && opening !== "[")) {
+      return undefined;
+    }
+    if (opens.length === 0) return text.slice(start, index + 1);
+  }
+  return undefined;
+}

package/src/ask-settlement.ts

@@ -0,0 +1,37 @@
+import { YaagError } from "./errors.ts";
+
+export interface AwaitAskSettlementOptions {
+  readonly settled: Promise<void>;
+  readonly closed: Promise<void>;
+  readonly timeoutMs: number | undefined;
+  readonly controlFailure: Promise<never>;
+  readonly error: (code: YaagError["code"], message: string) => YaagError;
+  readonly close: () => void;
+}
+
+/** Waits for one effort's settlement while preserving the Ask-wide timeout and death semantics. */
+export async function awaitAskSettlement(options: AwaitAskSettlementOptions): Promise<void> {
+  const death = options.closed.then(() => {
+    throw options.error("AGENT_DIED", "agent exited with an Ask pending");
+  });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expiry =
+    options.timeoutMs === undefined
+      ? new Promise<never>(() => {})
+      : new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(
+            () => reject(options.error("ASK_TIMEOUT", `no answer in ${options.timeoutMs}ms`)),
+            options.timeoutMs,
+          );
+        });
+  try {
+    await Promise.race([options.settled, death, expiry, options.controlFailure]);
+  } catch (error) {
+    if (error instanceof YaagError && (error.code === "ASK_TIMEOUT" || error.destructive)) {
+      options.close();
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/ask-turn.ts

@@ -0,0 +1,70 @@
+import type { Frame } from "./transport.ts";
+
+interface AssistantEnd {
+  readonly stopReason: string | null;
+  readonly errorMessage: string | null;
+}
+
+/**
+ * Interprets the frames of one Ask (ticket 01's 8-point contract).
+ *
+ * Two rules here are counter-intuitive and load-bearing:
+ * - `agent_end` is ignored entirely. `willRetry: true` is followed by a second
+ *   `agent_start` for the same Ask; only `agent_settled` terminates one.
+ * - Only the *last* assistant `message_end` decides success. A retried-then-
+ *   successful Ask emits an early `stopReason: "error"`, so an earlier one would
+ *   falsely reject a recovered turn.
+ */
+export class AskTurn {
+  #stopReason: string | null = null;
+  #errorMessage: string | null = null;
+  #settled = false;
+
+  observe(frame: Frame): void {
+    if (frame.type === "agent_settled") {
+      this.#settled = true;
+      return;
+    }
+    if (frame.type !== "message_end") return;
+    const end = assistantEnd(frame);
+    if (!end) return;
+    this.#stopReason = end.stopReason;
+    this.#errorMessage = end.errorMessage;
+  }
+
+  /** True once `agent_settled` has been seen — settled says nothing about success. */
+  get settled(): boolean {
+    return this.#settled;
+  }
+
+  /** Starts a new correction effort without retaining the preceding terminal state. */
+  rearm(): void {
+    this.#stopReason = null;
+    this.#errorMessage = null;
+    this.#settled = false;
+  }
+
+  /**
+   * The failure message when the turn ended badly, else null.
+   * `agent_settled` fires on failed turns too, so this check is what
+   * distinguishes them (ticket 01 §3).
+   */
+  failure(): string | null {
+    if (this.#stopReason !== "error" && this.#stopReason !== "aborted") return null;
+    return this.#errorMessage ?? `turn ended with stopReason "${this.#stopReason}"`;
+  }
+}
+
+/** Reads an assistant `message_end`; null for user and toolResult messages. */
+function assistantEnd(frame: Frame): AssistantEnd | null {
+  const message: unknown = frame.message;
+  if (typeof message !== "object" || message === null) return null;
+  if (!("role" in message) || message.role !== "assistant") return null;
+  const stopReason =
+    "stopReason" in message && typeof message.stopReason === "string" ? message.stopReason : null;
+  const errorMessage =
+    "errorMessage" in message && typeof message.errorMessage === "string"
+      ? message.errorMessage
+      : null;
+  return { stopReason, errorMessage };
+}

package/src/cassette-loader.ts

@@ -0,0 +1,131 @@
+import { Value } from "typebox/value";
+import {
+  validateCanonicalOutputSchema,
+  validateExtractionPolicy,
+} from "./ask-contract-identity.ts";
+import {
+  CASSETTE_VERSION,
+  type Cassette,
+  type CassetteArtifact,
+  type CassetteAsk,
+} from "./cassette.ts";
+import { CassetteSchema } from "./cassette-schema.ts";
+import { formatValidationErrors } from "./validation-errors.ts";
+
+/**
+ * Reads and validates one Cassette artifact before replay begins.
+ *
+ * Rejects unreadable, unparsable, unsupported, and malformed artifacts at the
+ * filesystem boundary; replay never receives unchecked external data. The
+ * schema checks structure; the five named invariants below check semantics.
+ * A version 1 artifact is upgraded in memory to version 2 (ADR-0021).
+ * Unknown fields are retained, never dropped (forward tolerance).
+ */
+export async function loadCassette(path: string): Promise<Cassette> {
+  let text: string;
+  try {
+    text = await Bun.file(path).text();
+  } catch (error) {
+    throw new Error(`cannot read cassette "${path}": ${String(error)}`, { cause: error });
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`cannot parse cassette "${path}": ${String(error)}`, { cause: error });
+  }
+  gateVersion(value, path);
+  const errors = Value.Errors(CassetteSchema, value);
+  if (errors.length > 0) malformed(path, formatValidationErrors(value, errors).join("; "));
+  const artifact = value as CassetteArtifact; // sound: CassetteSchemaIsSound (cassette-schema.ts)
+  assertRunPresence(artifact, path);
+  for (const [agentIndex, agent] of artifact.agents.entries()) {
+    agent.asks.forEach((ask, askIndex) => {
+      const label = `agents[${agentIndex}].asks[${askIndex}]`;
+      assertAskPosition(ask, askIndex, path, label);
+      assertContract(ask, path, label);
+      if (ask.context !== undefined) assertContract(ask.context.ask, path, `${label}.context.ask`);
+    });
+  }
+  return upgrade(artifact);
+}
+
+/** Invariant 1: the version gate, with its distinct non-"malformed" message. */
+function gateVersion(value: unknown, path: string): void {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    malformed(path, "root must be an object");
+  }
+  const version = (value as Record<string, unknown>).v;
+  if (typeof version !== "number") malformed(path, "v must be a number");
+  if (version !== 1 && version !== CASSETTE_VERSION) {
+    throw new Error(`cassette version ${version} is unsupported; runtime expects version 1 or 2`);
+  }
+}
+
+/**
+ * Invariant 2: Ask indices are monotonic per Agent from 0 (AskMarker); each
+ * recorded Ask must sit at its own position, or replay's index-based matching
+ * would lie.
+ */
+function assertAskPosition(ask: CassetteAsk, position: number, path: string, label: string): void {
+  if (ask.index !== position) {
+    malformed(path, `${label}.index must be ${position}, the Ask's position in sequence`);
+  }
+}
+
+/** Invariants 3 + 4: contract co-presence, then canonical identity checks. */
+function assertContract(
+  contract: {
+    readonly outputSchema?: unknown;
+    readonly maxSteers?: number;
+    readonly extractionPolicy?: string;
+  },
+  path: string,
+  label: string,
+): void {
+  const hasSchema = contract.outputSchema !== undefined;
+  const hasPolicy = contract.extractionPolicy !== undefined;
+  const hasMaxSteers = contract.maxSteers !== undefined;
+  if (!hasSchema && !hasPolicy && !hasMaxSteers) return;
+  if (!hasSchema) {
+    malformed(
+      path,
+      `${label}.${hasPolicy ? "outputSchema" : "maxSteers"} must accompany outputSchema`,
+    );
+  }
+  if (!hasPolicy) malformed(path, `${label}.extractionPolicy must accompany outputSchema`);
+  try {
+    validateCanonicalOutputSchema(contract.outputSchema);
+  } catch (error) {
+    malformed(path, `${label}.outputSchema ${message(error)}`);
+  }
+  try {
+    validateExtractionPolicy(contract.extractionPolicy);
+  } catch (error) {
+    malformed(path, `${label}.extractionPolicy ${message(error)}`);
+  }
+}
+
+/**
+ * Invariant 5: an artifact from version 2 on states its Run's outcome. A
+ * version 1 artifact was only ever written on settlement, so it loads as
+ * `completed`. Keyed on `v !== 1` so a future version bump cannot silently
+ * lapse the check.
+ */
+function assertRunPresence(artifact: CassetteArtifact, path: string): void {
+  if (artifact.v !== 1 && artifact.run === undefined) {
+    malformed(path, "run must be present in a version 2 cassette");
+  }
+}
+
+function upgrade(artifact: CassetteArtifact): Cassette {
+  return { ...artifact, v: CASSETTE_VERSION, run: artifact.run ?? { outcome: "completed" } };
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : "is invalid";
+}
+
+function malformed(path: string, detail: string): never {
+  throw new Error(`malformed cassette "${path}": ${detail}`);
+}

package/src/cassette-publish.ts

@@ -0,0 +1,55 @@
+import { open, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import type { Cassette } from "./cassette.ts";
+
+/** Prefix of every in-flight publication temp file, so a later start can clean stale ones (ADR-0021). */
+export const CASSETTE_TEMP_PREFIX = ".yaag-tmp-";
+
+/**
+ * Publishes a Cassette crash-durably: temp file, fsync, rename, destination
+ * directory fsync. Resolves only after all four steps complete (ADR-0021).
+ *
+ * Rejects with an error naming `path` when any step fails; the temp file is
+ * removed on a best-effort basis first.
+ */
+export async function publishCassette(path: string, cassette: Cassette): Promise<void> {
+  const directory = dirname(path);
+  const temp = join(directory, `${CASSETTE_TEMP_PREFIX}${process.pid}-${basename(path)}`);
+  try {
+    await writeDurable(temp, JSON.stringify(cassette));
+    await rename(temp, path);
+    await syncDirectory(directory);
+  } catch (error) {
+    await discard(temp);
+    throw new Error(`failed to publish cassette ${path}: ${String(error)}`, { cause: error });
+  }
+}
+
+/** Private artifact: the checkpoint may quote Agent output, so it is owner-only (ADR-0021). */
+async function writeDurable(path: string, contents: string): Promise<void> {
+  const file = await open(path, "w", 0o600);
+  try {
+    await file.writeFile(contents);
+    await file.sync();
+  } finally {
+    await file.close();
+  }
+}
+
+/** A rename is only durable once its directory entry is on disk (ADR-0021). */
+async function syncDirectory(directory: string): Promise<void> {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function discard(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch {
+    // The temp file may never have existed; a stale one is cleaned at a later start.
+  }
+}