@yaag/runtime 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@yaag/runtime",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src",
+    "test:e2e": "bun test e2e"
+  },
+  "dependencies": {
+    "typebox": "1.3.7"
+  }
+}

package/src/agent-names.ts

@@ -0,0 +1,20 @@
+/**
+ * Every Lifecycle Event identifies its Agent, so an unnamed Agent still needs a
+ * name and a duplicate is suffixed rather than rejected — spawning in a loop
+ * must not fail.
+ *
+ * `taken` is mutated: the chosen name is reserved.
+ */
+export function uniqueAgentName(
+  requested: string | undefined,
+  ordinal: number,
+  taken: Set<string>,
+): string {
+  const base = requested ?? `a${ordinal + 1}`;
+  let name = base;
+  for (let suffix = 2; taken.has(name); suffix++) {
+    name = `${base}-${suffix}`;
+  }
+  taken.add(name);
+  return name;
+}

package/src/agent-usage.ts

@@ -0,0 +1,72 @@
+import type { Frame, TokenBreakdown } from "./transport.ts";
+
+export interface AgentUsageSnapshot {
+  readonly tokens: TokenBreakdown;
+  readonly cost: number;
+}
+
+/**
+ * Accumulates complete assistant `message_end` usage across an Agent's lifetime.
+ *
+ * Invalid or non-assistant frames never change the reported accounting.
+ */
+export class AgentUsage {
+  readonly #report: (snapshot: AgentUsageSnapshot) => void;
+  #tokens: TokenBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+  #cost = 0;
+
+  constructor(report: (snapshot: AgentUsageSnapshot) => void) {
+    this.#report = report;
+  }
+
+  /** Observes one raw Agent frame and reports after each valid assistant completion. */
+  observe(frame: Frame): void {
+    const usage = usageFromFrame(frame);
+    if (usage === null) return;
+    this.#tokens = {
+      input: this.#tokens.input + usage.tokens.input,
+      output: this.#tokens.output + usage.tokens.output,
+      cacheRead: this.#tokens.cacheRead + usage.tokens.cacheRead,
+      cacheWrite: this.#tokens.cacheWrite + usage.tokens.cacheWrite,
+      total: this.#tokens.total + usage.tokens.total,
+    };
+    this.#cost += usage.cost;
+    this.#report({ tokens: { ...this.#tokens }, cost: this.#cost });
+  }
+}
+
+function usageFromFrame(frame: Frame): AgentUsageSnapshot | null {
+  if (frame.type !== "message_end" || !isRecord(frame.message)) return null;
+  if (frame.message.role !== "assistant" || !isRecord(frame.message.usage)) return null;
+  const usage = frame.message.usage;
+  if (!isNumber(usage.input) || !isNumber(usage.output) || !isNumber(usage.cacheRead)) return null;
+  if (!isNumber(usage.cacheWrite) || !isNumber(usage.totalTokens) || !isRecord(usage.cost))
+    return null;
+  if (
+    !isNumber(usage.cost.input) ||
+    !isNumber(usage.cost.output) ||
+    !isNumber(usage.cost.cacheRead) ||
+    !isNumber(usage.cost.cacheWrite) ||
+    !isNumber(usage.cost.total)
+  ) {
+    return null;
+  }
+  return {
+    tokens: {
+      input: usage.input,
+      output: usage.output,
+      cacheRead: usage.cacheRead,
+      cacheWrite: usage.cacheWrite,
+      total: usage.totalTokens,
+    },
+    cost: usage.cost.total,
+  };
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}

package/src/agent.ts

@@ -0,0 +1,130 @@
+import type { Static, TSchema } from "typebox";
+import { AgentUsage } from "./agent-usage.ts";
+import { exchangeAsk } from "./ask-exchange.ts";
+import type { EffectiveAskOptions } from "./ask-hash.ts";
+import { Connection } from "./connection.ts";
+import { agentError } from "./errors.ts";
+import type { EventSink } from "./events.ts";
+import type { AgentStats, AgentTransport } from "./transport.ts";
+import type { AskOptions, Handle, SpawnOptions, StructuredAskOptions } from "./types.ts";
+
+export interface AgentOptions {
+  readonly name: string;
+  readonly cwd: string;
+  readonly branch: string | undefined;
+  readonly transport: AgentTransport;
+  readonly emit: EventSink;
+  /** The options this Agent was spawned with, for the ADR-0014 Ask hash. */
+  readonly spawnOptions: SpawnOptions;
+  /** Definition-owned defaults merged below explicit per-Ask options. */
+  readonly askDefaults?: AskOptions;
+  /** Definition identity recorded on its Asks, outside replay identity. */
+  readonly definitionName?: string;
+  /** Test-only override for the fixed duration-limit grace. */
+  readonly askLimitGraceMs?: number;
+  /** Test-only override for the bounded wait for `agent_settled` after an idle abort. */
+  readonly idleAbortSettleMs?: number;
+}
+
+/** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
+export class Agent implements Handle {
+  readonly name: string;
+  readonly cwd: string;
+  readonly branch: string | undefined;
+  readonly model: string;
+
+  readonly #transport: AgentTransport;
+  readonly #connection: Connection;
+  readonly #emit: EventSink;
+  readonly #spawnOptions: SpawnOptions;
+  readonly #askDefaults: AskOptions;
+  readonly #definitionName: string | undefined;
+  readonly #askLimitGraceMs: number | undefined;
+  readonly #idleAbortSettleMs: number | undefined;
+  readonly #usage: AgentUsage;
+  #busy = false;
+  #incomplete = false;
+  #askIndex = 0;
+  #closing: Promise<AgentStats> | null = null;
+
+  constructor(options: AgentOptions) {
+    this.name = options.name;
+    this.cwd = options.cwd;
+    this.branch = options.branch;
+    this.model = options.transport.model;
+    this.#transport = options.transport;
+    this.#emit = options.emit;
+    this.#spawnOptions = options.spawnOptions;
+    this.#askDefaults = options.askDefaults ?? {};
+    this.#definitionName = options.definitionName;
+    this.#askLimitGraceMs = options.askLimitGraceMs;
+    this.#idleAbortSettleMs = options.idleAbortSettleMs;
+    this.#usage = new AgentUsage((snapshot) =>
+      this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
+    );
+    this.#connection = new Connection(options.transport, options.name);
+  }
+
+  async ask<Schema extends TSchema>(
+    prompt: string,
+    options: StructuredAskOptions<Schema>,
+  ): Promise<Static<Schema>>;
+  async ask(prompt: string, options?: AskOptions): Promise<string>;
+  async ask(prompt: string, options?: EffectiveAskOptions): Promise<unknown> {
+    if (this.#connection.dead)
+      throw agentError(this.name, "AGENT_DIED", "agent is no longer running");
+    if (this.#busy) {
+      throw agentError(
+        this.name,
+        "AGENT_BUSY",
+        "an Ask is already in flight — is an await missing?",
+      );
+    }
+    this.#busy = true;
+    const index = this.#askIndex++;
+    try {
+      return await exchangeAsk({
+        agent: this.name,
+        connection: this.#connection,
+        transport: this.#transport,
+        prompt,
+        index,
+        ask: { ...this.#askDefaults, ...options },
+        spawnOptions: this.#spawnOptions,
+        definitionName: this.#definitionName,
+        emit: this.#emit,
+        usage: this.#usage,
+        close: () => void this.close().catch(() => {}),
+        askLimitGraceMs: this.#askLimitGraceMs,
+        idleAbortSettleMs: this.#idleAbortSettleMs,
+      });
+    } finally {
+      this.#busy = false;
+    }
+  }
+
+  /** True when the Agent was killed mid-Ask, so its cost is a floor (ADR-0012). */
+  get incomplete(): boolean {
+    return this.#incomplete;
+  }
+
+  /** Shuts the Agent down and reports its cost. Idempotent. */
+  close(): Promise<AgentStats> {
+    this.#closing ??= this.#shutdown(this.#busy);
+    return this.#closing;
+  }
+
+  async #shutdown(midAsk: boolean): Promise<AgentStats> {
+    this.#incomplete = midAsk;
+    const stats = await this.#transport.close();
+    this.#emit({
+      type: "agent_exit",
+      agent: this.name,
+      tokens: stats.tokens,
+      cost: stats.cost,
+      incomplete: midAsk,
+      ...(this.branch === undefined ? {} : { worktree: { cwd: this.cwd, branch: this.branch } }),
+    });
+    return stats;
+  }
+}

package/src/args-validation.ts

@@ -0,0 +1,11 @@
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+import { YaagError } from "./errors.ts";
+import { formatValidationErrors } from "./validation-errors.ts";
+
+/** Throws ARGS_INVALID when value violates schema, without changing value. */
+export function validateArgs(schema: TSchema, value: unknown): void {
+  const errors = Value.Errors(schema, value);
+  if (errors.length === 0) return;
+  throw new YaagError("ARGS_INVALID", formatValidationErrors(value, errors).join("\n"));
+}

package/src/ask-activity.ts

@@ -0,0 +1,84 @@
+import type { AgentActivity } from "./events.ts";
+import type { Frame } from "./transport.ts";
+import { TOOL_ARGS_GIST_MAX_CHARS } from "./wire-constants.ts";
+
+/** Reports complete Ask activity transitions derived from already-observed frames. */
+export class AskActivityTracker {
+  readonly #onChange: (activity: AgentActivity) => void;
+  #last: AgentActivity | null = null;
+
+  constructor(onChange: (activity: AgentActivity) => void) {
+    this.#onChange = onChange;
+  }
+
+  /** Inspects one Agent frame and ignores malformed or unsupported shapes. */
+  observe(frame: Frame): void {
+    const activity = activityFromFrame(frame);
+    if (activity === null || sameActivity(activity, this.#last)) return;
+    this.#last = activity;
+    this.#onChange(activity);
+  }
+}
+
+function activityFromFrame(frame: Frame): AgentActivity | null {
+  if (frame.type === "message_update") return messageActivity(frame.assistantMessageEvent);
+  if (frame.type === "tool_execution_start") return toolActivity(frame);
+  if (frame.type === "compaction_start") return { type: "compacting" };
+  if (frame.type === "auto_retry_start" || frame.type === "summarization_retry_start") {
+    return retryActivity(frame);
+  }
+  return null;
+}
+
+function messageActivity(value: unknown): AgentActivity | null {
+  if (!isRecord(value) || typeof value.type !== "string") return null;
+  if (value.type === "thinking_start" || value.type === "thinking_delta")
+    return { type: "thinking" };
+  if (value.type === "text_start" || value.type === "text_delta") return { type: "writing" };
+  return null;
+}
+
+function toolActivity(frame: Frame): AgentActivity | null {
+  if (typeof frame.toolName !== "string") return null;
+  return { type: "tool", name: frame.toolName, argsGist: toolArgsGist(frame.args) };
+}
+
+function retryActivity(frame: Frame): AgentActivity | null {
+  if (typeof frame.attempt !== "number" || typeof frame.maxAttempts !== "number") return null;
+  return { type: "retrying", attempt: frame.attempt, max: frame.maxAttempts };
+}
+
+function toolArgsGist(args: unknown): string {
+  const command = isRecord(args) && typeof args.command === "string" ? args.command : undefined;
+  const value = command ?? json(args);
+  return value === undefined ? "" : oneLine(value).slice(0, TOOL_ARGS_GIST_MAX_CHARS);
+}
+
+function json(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const serialized = JSON.stringify(value);
+    return typeof serialized === "string" ? serialized : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function oneLine(value: string): string {
+  return value.replaceAll(/\s+/g, " ").trim();
+}
+
+function sameActivity(left: AgentActivity, right: AgentActivity | null): boolean {
+  if (right === null || left.type !== right.type) return false;
+  if (left.type === "tool" && right.type === "tool") {
+    return left.name === right.name && left.argsGist === right.argsGist;
+  }
+  if (left.type === "retrying" && right.type === "retrying") {
+    return left.attempt === right.attempt && left.max === right.max;
+  }
+  return true;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}

package/src/ask-contract-identity.ts

@@ -0,0 +1,96 @@
+import type { TSchema } from "typebox";
+import { ASK_OUTPUT_EXTRACTION_POLICY } from "./ask-output.ts";
+
+/** A JSON value suitable for deterministic Cassette identity. */
+export type CanonicalJson =
+  | null
+  | boolean
+  | number
+  | string
+  | CanonicalJson[]
+  | CanonicalJsonObject;
+
+/** A JSON object with recursively sorted keys. */
+export interface CanonicalJsonObject {
+  readonly [key: string]: CanonicalJson;
+}
+
+/** The conditional behavioral output contract of a structured Ask. */
+export interface AskOutputContract {
+  readonly outputSchema: CanonicalJsonObject;
+  readonly extractionPolicy: string;
+  readonly maxSteers?: number;
+}
+
+/**
+ * Copies a TypeBox schema into recursively key-sorted JSON form without mutating it.
+ *
+ * Throws when the value cannot be represented in a Cassette JSON artifact.
+ */
+export function canonicalizeSchema(value: unknown): CanonicalJsonObject {
+  if (!isObject(value)) throw new TypeError("outputSchema must be a JSON-compatible schema object");
+  return canonicalize(value, new Set<object>()) as CanonicalJsonObject;
+}
+
+/** Builds the recorded and hashed behavioral contract for one structured Ask. */
+export function createAskOutputContract(schema: TSchema, maxSteers?: number): AskOutputContract {
+  return {
+    outputSchema: canonicalizeSchema(schema),
+    extractionPolicy: ASK_OUTPUT_EXTRACTION_POLICY,
+    ...(maxSteers === undefined ? {} : { maxSteers }),
+  };
+}
+
+/** Validates an externally supplied canonical schema representation. */
+export function validateCanonicalOutputSchema(value: unknown): CanonicalJsonObject {
+  const canonical = canonicalizeSchema(value);
+  if (JSON.stringify(value) !== JSON.stringify(canonical)) {
+    throw new TypeError("outputSchema must be in canonical form");
+  }
+  return canonical;
+}
+
+/** Validates a policy identifier while allowing future versions to load and diverge at replay. */
+export function validateExtractionPolicy(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-z][a-z0-9-]*\/v[1-9][0-9]*$/.test(value)) {
+    throw new TypeError("extractionPolicy must be a valid policy identifier");
+  }
+  return value;
+}
+
+function canonicalize(value: unknown, ancestors: Set<object>): CanonicalJson {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("outputSchema must be JSON-compatible");
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) throw new TypeError("outputSchema must be JSON-compatible");
+    ancestors.add(value);
+    const result = value.map((entry) => canonicalize(entry, ancestors));
+    ancestors.delete(value);
+    return result;
+  }
+  if (!isObject(value)) throw new TypeError("outputSchema must be JSON-compatible");
+  if (ancestors.has(value)) throw new TypeError("outputSchema must be JSON-compatible");
+  ancestors.add(value);
+  const result: Record<string, CanonicalJson> = {};
+  for (const key of Object.keys(value).sort()) {
+    const entry = canonicalize(value[key], ancestors);
+    // JSON Schema defines `required` as a set; TypeBox derives its order from
+    // author property insertion, which is not behavioral identity.
+    result[key] = key === "required" && Array.isArray(entry) ? sortRequired(entry) : entry;
+  }
+  ancestors.delete(value);
+  return result;
+}
+
+function sortRequired(value: CanonicalJson[]): CanonicalJson[] {
+  return value.every((entry) => typeof entry === "string") ? [...value].sort() : value;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/ask-exchange-events.ts

@@ -0,0 +1,60 @@
+import type { AgentActivity, AskOutputChannel, EventSink } from "./events.ts";
+import { agentAskPath, childPath } from "./node-path.ts";
+import type { NodeSnapshot } from "./node-tracker.ts";
+import { promptGist } from "./prompt-gist.ts";
+
+/** Emits the four Ask-scoped Lifecycle Events for one exchange. */
+export class AskEvents {
+  readonly #emit: EventSink;
+  readonly #agent: string;
+  readonly #index: number;
+
+  constructor(emit: EventSink, agent: string, index: number) {
+    this.#emit = emit;
+    this.#agent = agent;
+    this.#index = index;
+  }
+
+  start(prompt: string, replayed: boolean): void {
+    this.#emit({
+      type: "ask_start",
+      agent: this.#agent,
+      index: this.#index,
+      promptGist: promptGist(prompt),
+      promptChars: prompt.length,
+      ...(replayed ? { replayed: true } : {}),
+    });
+  }
+
+  activity = (activity: AgentActivity): void => {
+    this.#emit({ type: "ask_activity", agent: this.#agent, index: this.#index, activity });
+  };
+
+  output = (channel: AskOutputChannel, text: string): void => {
+    this.#emit({ type: "ask_output", agent: this.#agent, index: this.#index, channel, text });
+  };
+
+  /** Composes the Nested Node path from this Ask's identity, then reports it. */
+  node = (snapshot: NodeSnapshot): void => {
+    const path = snapshot.segments.reduce(childPath, agentAskPath(this.#agent, this.#index));
+    this.#emit({
+      type: "node_update",
+      agent: this.#agent,
+      path,
+      state: snapshot.state,
+      ...(snapshot.activityGist === undefined ? {} : { activityGist: snapshot.activityGist }),
+      ...(snapshot.usage === undefined ? {} : { usage: snapshot.usage }),
+    });
+  };
+
+  end(durationMs: number, ok: boolean, maxFrameGapMs: number | undefined): void {
+    this.#emit({
+      type: "ask_end",
+      agent: this.#agent,
+      index: this.#index,
+      durationMs,
+      ok,
+      ...(maxFrameGapMs === undefined ? {} : { maxFrameGapMs }),
+    });
+  }
+}

package/src/ask-exchange-options.ts

@@ -0,0 +1,32 @@
+import type { EffectiveAskOptions } from "./ask-hash.ts";
+import type { Connection } from "./connection.ts";
+import type { EventSink } from "./events.ts";
+import type { AgentTransport, Frame } from "./transport.ts";
+import type { SpawnOptions } from "./types.ts";
+
+/** A frame consumer whose lifetime exceeds one Ask; the Agent's AgentUsage satisfies it. */
+export interface FrameObserver {
+  observe(frame: Frame): void;
+}
+
+/** Options that connect one Ask exchange to its Agent's identity and event stream. */
+export interface AskExchangeOptions {
+  readonly agent: string;
+  readonly connection: Connection;
+  readonly transport: AgentTransport;
+  readonly prompt: string;
+  readonly index: number;
+  readonly ask: EffectiveAskOptions;
+  readonly spawnOptions: SpawnOptions;
+  readonly definitionName: string | undefined;
+  /** Lifecycle Event sink; the exchange emits every Ask-scoped event itself. */
+  readonly emit: EventSink;
+  /** The Agent's persistent usage accumulator; fed frames only during live Asks. */
+  readonly usage: FrameObserver;
+  /** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
+  readonly close: () => void;
+  /** Test-only override for the fixed duration-limit grace. */
+  readonly askLimitGraceMs: number | undefined;
+  /** Test-only override for the bounded settle wait after an idle abort. */
+  readonly idleAbortSettleMs: number | undefined;
+}