@tangle-network/agent-runtime 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,11 +1,61 @@
-// src/index.ts
+// src/errors.ts
+import { AgentEvalError } from "@tangle-network/agent-eval";
 import {
-  acquisitionPlansForKnowledgeGaps,
-  blockingKnowledgeEval,
-  runAgentControlLoop,
-  scoreKnowledgeReadiness,
-  userQuestionsForKnowledgeGaps
+  AgentEvalError as AgentEvalError2,
+  CaptureIntegrityError,
+  ConfigError,
+  JudgeError,
+  NotFoundError,
+  ReplayError,
+  ValidationError,
+  VerificationError
 } from "@tangle-network/agent-eval";
+var SessionMismatchError = class extends AgentEvalError {
+  sessionBackend;
+  requestedBackend;
+  constructor(sessionBackend, requestedBackend, options) {
+    super(
+      "validation",
+      `Cannot resume ${sessionBackend} session with ${requestedBackend} backend`,
+      options
+    );
+    this.sessionBackend = sessionBackend;
+    this.requestedBackend = requestedBackend;
+  }
+};
+var BackendTransportError = class extends AgentEvalError {
+  backend;
+  status;
+  constructor(backend, message, options) {
+    super("config", message, options);
+    this.backend = backend;
+    this.status = options?.status;
+  }
+};
+var RuntimeRunStateError = class extends AgentEvalError {
+  constructor(message, options) {
+    super("validation", message, options);
+  }
+};
+
+// src/sessions.ts
+function newRuntimeSession(backend, requestedId, metadata) {
+  const now = nowIso();
+  return {
+    id: requestedId || crypto.randomUUID(),
+    backend,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    metadata
+  };
+}
+function touchSession(session) {
+  return { ...session, updatedAt: nowIso() };
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
 var InMemoryRuntimeSessionStore = class {
   sessions = /* @__PURE__ */ new Map();
   events = /* @__PURE__ */ new Map();
@@ -24,6 +74,277 @@ var InMemoryRuntimeSessionStore = class {
     return [...this.events.get(sessionId) ?? []];
   }
 };
+
+// src/backends.ts
+function createIterableBackend(options) {
+  return options;
+}
+function createSandboxPromptBackend(options) {
+  const kind = options.kind ?? "sandbox";
+  return {
+    kind,
+    async start(input, context) {
+      const box = await options.getBox(input, context);
+      return newRuntimeSession(
+        kind,
+        options.getSessionId?.(box, input) ?? context.requestedSessionId,
+        { resumable: true }
+      );
+    },
+    resume(session) {
+      return touchSession({ ...session, status: "active" });
+    },
+    async *stream(input, context) {
+      const box = await options.getBox(input, context);
+      const message = input.message ?? input.messages?.at(-1)?.content ?? context.task.intent;
+      for await (const event of options.streamPrompt(box, message, context)) {
+        const mapped = options.mapEvent?.(event, context) ?? mapCommonBackendEvent(event, context);
+        if (mapped) yield mapped;
+      }
+    }
+  };
+}
+function createOpenAICompatibleBackend(options) {
+  const fetcher = options.fetchImpl ?? fetch;
+  const kind = options.kind ?? "tcloud";
+  return {
+    kind,
+    start(_input, context) {
+      return newRuntimeSession(kind, context.requestedSessionId);
+    },
+    async *stream(input, context) {
+      const response = await fetcher(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${options.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          model: options.model,
+          stream: true,
+          messages: input.messages ?? [
+            { role: "user", content: input.message ?? context.task.intent }
+          ]
+        }),
+        signal: context.signal
+      });
+      if (!response.ok) {
+        throw new BackendTransportError(kind, `chat backend returned ${response.status}`, {
+          status: response.status
+        });
+      }
+      yield* streamResponseEvents(response, context);
+    }
+  };
+}
+function normalizeBackendStreamEvent(event, task, session) {
+  if ("task" in event && event.task && "session" in event && event.session && "timestamp" in event && event.timestamp) {
+    return event;
+  }
+  return {
+    ...event,
+    task: "task" in event && event.task ? event.task : task,
+    session: "session" in event && event.session ? event.session : session,
+    timestamp: "timestamp" in event && event.timestamp ? event.timestamp : nowIso()
+  };
+}
+function mapCommonBackendEvent(event, context) {
+  if (!event || typeof event !== "object") return void 0;
+  const record = event;
+  const type = String(record.type ?? "");
+  const data = record.data && typeof record.data === "object" ? record.data : record;
+  if (type === "message.part.updated" || type === "text_delta" || type === "delta") {
+    const text = stringValue(data.text) ?? stringValue(data.delta) ?? stringValue(record.text);
+    return text ? {
+      type: "text_delta",
+      task: context.task,
+      session: context.session,
+      text,
+      timestamp: nowIso()
+    } : void 0;
+  }
+  if (type === "reasoning_delta") {
+    const text = stringValue(data.text) ?? stringValue(record.text);
+    return text ? {
+      type: "reasoning_delta",
+      task: context.task,
+      session: context.session,
+      text,
+      timestamp: nowIso()
+    } : void 0;
+  }
+  if (type === "tool_call") {
+    return {
+      type: "tool_call",
+      task: context.task,
+      session: context.session,
+      toolName: stringValue(data.name) ?? stringValue(record.toolName) ?? "tool",
+      toolCallId: stringValue(data.id) ?? stringValue(record.toolCallId),
+      args: data.args ?? data.input ?? record.args,
+      timestamp: nowIso()
+    };
+  }
+  if (type === "tool_result") {
+    return {
+      type: "tool_result",
+      task: context.task,
+      session: context.session,
+      toolName: stringValue(data.name) ?? stringValue(record.toolName) ?? "tool",
+      toolCallId: stringValue(data.id) ?? stringValue(record.toolCallId),
+      result: data.result ?? data.output ?? record.result,
+      timestamp: nowIso()
+    };
+  }
+  if (type === "result" || type === "final") {
+    const text = stringValue(data.finalText) ?? stringValue(data.text) ?? stringValue(record.text);
+    return text ? {
+      type: "text_delta",
+      task: context.task,
+      session: context.session,
+      text,
+      timestamp: nowIso()
+    } : void 0;
+  }
+  return void 0;
+}
+async function* streamResponseEvents(response, context) {
+  const body = response.body;
+  if (!body) return;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+    for (const event of drainStreamBuffer(false)) yield event;
+  }
+  buffer += decoder.decode().replace(/\r\n/g, "\n");
+  for (const event of drainStreamBuffer(true)) yield event;
+  if (buffer.trim()) {
+    const event = parseStreamChunk(buffer, context);
+    if (event) yield event;
+  }
+  function* drainStreamBuffer(flush) {
+    for (; ; ) {
+      const sseBoundary = buffer.indexOf("\n\n");
+      if (sseBoundary >= 0) {
+        const chunk = buffer.slice(0, sseBoundary);
+        buffer = buffer.slice(sseBoundary + 2);
+        const event = parseStreamChunk(chunk, context);
+        if (event) yield event;
+        continue;
+      }
+      const newline = buffer.indexOf("\n");
+      if (newline >= 0 && !buffer.slice(0, newline).startsWith("data:")) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        const event = parseStreamChunk(line, context);
+        if (event) yield event;
+        continue;
+      }
+      if (flush && buffer.trim() && !buffer.trimStart().startsWith("data:")) {
+        const line = buffer;
+        buffer = "";
+        const event = parseStreamChunk(line, context);
+        if (event) yield event;
+        continue;
+      }
+      break;
+    }
+  }
+}
+function parseStreamChunk(chunk, context) {
+  const lines = chunk.split(/\r?\n/);
+  const dataLines = lines.filter((line) => line.startsWith("data:"));
+  const data = dataLines.length > 0 ? dataLines.map((line) => line.slice(5).trimStart()).join("\n") : chunk.trim();
+  if (!data || data === "[DONE]") return void 0;
+  try {
+    const parsed = JSON.parse(data);
+    const choices = parsed.choices;
+    const choice = Array.isArray(choices) ? choices[0] : void 0;
+    const delta = choice?.delta;
+    const message = choice?.message;
+    const text = stringValue(delta?.content) ?? stringValue(message?.content) ?? stringValue(parsed.text);
+    if (text) {
+      return {
+        type: "text_delta",
+        task: context.task,
+        session: context.session,
+        text,
+        timestamp: nowIso()
+      };
+    }
+    return mapCommonBackendEvent(parsed, context);
+  } catch {
+    return {
+      type: "text_delta",
+      task: context.task,
+      session: context.session,
+      text: data,
+      timestamp: nowIso()
+    };
+  }
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/readiness.ts
+var DEFAULT_MINIMUM_READINESS_SCORE = 0.7;
+function decideKnowledgeReadiness(report, options = {}) {
+  const minimumScore = options.minimumScore ?? DEFAULT_MINIMUM_READINESS_SCORE;
+  if (!Number.isFinite(minimumScore) || minimumScore < 0 || minimumScore > 1) {
+    throw new ValidationError(
+      `minimumScore must be a finite number in [0, 1]; received ${String(minimumScore)}`
+    );
+  }
+  const blockingGapIds = report.blockingMissingRequirements.map((requirement) => requirement.id);
+  const nonBlockingGapIds = report.nonBlockingGaps.map((requirement) => requirement.id);
+  if (blockingGapIds.length > 0) {
+    return {
+      passed: false,
+      status: "blocked",
+      reason: report.reason,
+      readinessScore: report.readinessScore,
+      recommendedAction: report.recommendedAction,
+      severity: report.severity,
+      blockingGapIds,
+      nonBlockingGapIds
+    };
+  }
+  if (report.readinessScore < minimumScore) {
+    return {
+      passed: false,
+      status: "caveat",
+      reason: `Knowledge readiness score ${report.readinessScore.toFixed(3)} is below minimum ${minimumScore.toFixed(3)}.`,
+      readinessScore: report.readinessScore,
+      recommendedAction: report.recommendedAction,
+      severity: report.severity,
+      blockingGapIds,
+      nonBlockingGapIds
+    };
+  }
+  return {
+    passed: true,
+    status: "ready",
+    reason: report.reason,
+    readinessScore: report.readinessScore,
+    recommendedAction: report.recommendedAction,
+    severity: report.severity,
+    blockingGapIds,
+    nonBlockingGapIds
+  };
+}
+
+// src/run.ts
+import {
+  acquisitionPlansForKnowledgeGaps,
+  blockingKnowledgeEval,
+  runAgentControlLoop,
+  scoreKnowledgeReadiness,
+  userQuestionsForKnowledgeGaps
+} from "@tangle-network/agent-eval";
 async function runAgentTask(options) {
   const task = options.task;
   await emit(options.onEvent, { type: "task_start", task });
@@ -35,7 +356,13 @@ async function runAgentTask(options) {
     ...knowledge.blockingMissingRequirements,
     ...knowledge.nonBlockingGaps
   ]);
-  const preflight = await runKnowledgePreflight(task, questions, acquisitionPlans, options.knowledge, options.onEvent);
+  const preflight = await runKnowledgePreflight(
+    task,
+    questions,
+    acquisitionPlans,
+    options.knowledge,
+    options.onEvent
+  );
   if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
     await emit(options.onEvent, { type: "readiness_start", task });
     knowledge = await options.knowledge.refreshReadiness({
@@ -58,13 +385,26 @@ async function runAgentTask(options) {
     variantId: options.variantId,
     observe: ({ history, abortSignal }) => options.adapter.observe({ task, knowledge, history, abortSignal }),
     validate: async ({ state, history, abortSignal }) => {
-      const readinessEval = blockingKnowledgeEval(knowledge, { minimumScore: options.minimumReadinessScore });
-      const evals = await options.adapter.validate({ task, knowledge, state, history, abortSignal });
+      const readinessEval = blockingKnowledgeEval(knowledge, {
+        minimumScore: options.minimumReadinessScore
+      });
+      const evals = await options.adapter.validate({
+        task,
+        knowledge,
+        state,
+        history,
+        abortSignal
+      });
       return [readinessEval, ...evals];
     },
     decide: (ctx) => {
       if (isKnowledgeBlocked(ctx.evals)) {
-        return options.adapter.onKnowledgeBlocked?.({ task, knowledge, questions, acquisitionPlans }) ?? {
+        return options.adapter.onKnowledgeBlocked?.({
+          task,
+          knowledge,
+          questions,
+          acquisitionPlans
+        }) ?? {
           type: "stop",
           pass: false,
           score: knowledge.readinessScore,
@@ -90,7 +430,9 @@ async function runAgentTask(options) {
     userAnswers: preflight.userAnswers,
     acquiredEvidenceIds: preflight.acquiredEvidenceIds,
     control,
-    runRecords: (options.adapter.projectRunRecords?.(control, task) ?? []).map((record) => record.scenarioId === void 0 ? { ...record, scenarioId } : record)
+    runRecords: (options.adapter.projectRunRecords?.(control, task) ?? []).map(
+      (record) => record.scenarioId === void 0 ? { ...record, scenarioId } : record
+    )
   };
 }
 function summarizeAgentTaskRun(result) {
@@ -102,7 +444,9 @@ function summarizeAgentTaskRun(result) {
     readinessStatus: decideKnowledgeReadiness(result.knowledge).status,
     readinessScore: result.knowledge.readinessScore,
     recommendedAction: result.knowledge.recommendedAction,
-    blockingGapIds: result.knowledge.blockingMissingRequirements.map((requirement) => requirement.id),
+    blockingGapIds: result.knowledge.blockingMissingRequirements.map(
+      (requirement) => requirement.id
+    ),
     nonBlockingGapIds: result.knowledge.nonBlockingGaps.map((requirement) => requirement.id),
     questionCount: result.questions.length,
     acquisitionPlanCount: result.acquisitionPlans.length,
@@ -117,17 +461,20 @@ function summarizeAgentTaskRun(result) {
 async function* runAgentTaskStream(options) {
   const task = options.task;
   const input = { task, ...options.input ?? {} };
-  const started = streamEvent({ type: "task_start", task });
-  yield started;
-  const readinessStart = streamEvent({ type: "readiness_start", task });
-  yield readinessStart;
+  yield streamEvent({ type: "task_start", task });
+  yield streamEvent({ type: "readiness_start", task });
   let knowledge = await buildReadiness(task, options.knowledge);
   const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements);
   const acquisitionPlans = acquisitionPlansForKnowledgeGaps([
     ...knowledge.blockingMissingRequirements,
     ...knowledge.nonBlockingGaps
   ]);
-  const preflight = await runKnowledgePreflightStream(task, questions, acquisitionPlans, options.knowledge);
+  const preflight = await runKnowledgePreflightStream(
+    task,
+    questions,
+    acquisitionPlans,
+    options.knowledge
+  );
   for (const event of preflight.events) yield event;
   if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
     yield streamEvent({ type: "readiness_start", task });
@@ -138,7 +485,9 @@ async function* runAgentTaskStream(options) {
       acquiredEvidenceIds: preflight.acquiredEvidenceIds
     });
   }
-  const decision = decideKnowledgeReadiness(knowledge, { minimumScore: options.minimumReadinessScore });
+  const decision = decideKnowledgeReadiness(knowledge, {
+    minimumScore: options.minimumReadinessScore
+  });
   yield streamEvent({ type: "readiness_end", task, knowledge, decision });
   if (!decision.passed && decision.status === "blocked") {
     const reason = `knowledge readiness blocked: ${decision.reason}`;
@@ -149,7 +498,16 @@ async function* runAgentTaskStream(options) {
   const store = options.sessionStore;
   const existing = options.sessionId ? await store?.get(options.sessionId) : void 0;
   const shouldResume = Boolean(options.resume && existing);
-  let session = shouldResume && existing ? await resumeBackendSession(options.backend, existing, input, { task, knowledge, signal: options.signal }) : await startBackendSession(options.backend, input, { task, knowledge, signal: options.signal }, options.sessionId);
+  let session = shouldResume && existing ? await resumeBackendSession(options.backend, existing, input, {
+    task,
+    knowledge,
+    signal: options.signal
+  }) : await startBackendSession(
+    options.backend,
+    input,
+    { task, knowledge, signal: options.signal },
+    options.sessionId
+  );
   await store?.put(session);
   const sessionEvent = streamEvent({
     type: shouldResume ? "session_resumed" : "session_created",
@@ -158,12 +516,22 @@ async function* runAgentTaskStream(options) {
   });
   await store?.appendEvent?.(session.id, sessionEvent);
   yield sessionEvent;
-  const backendStart = streamEvent({ type: "backend_start", task, session, backend: options.backend.kind });
+  const backendStart = streamEvent({
+    type: "backend_start",
+    task,
+    session,
+    backend: options.backend.kind
+  });
   await store?.appendEvent?.(session.id, backendStart);
   yield backendStart;
   let finalText = "";
   try {
-    for await (const rawEvent of options.backend.stream(input, { task, knowledge, session, signal: options.signal })) {
+    for await (const rawEvent of options.backend.stream(input, {
+      task,
+      knowledge,
+      session,
+      signal: options.signal
+    })) {
       const event = normalizeBackendStreamEvent(rawEvent, task, session);
       if (event.type === "text_delta") finalText += event.text;
       await store?.appendEvent?.(session.id, event);
@@ -172,14 +540,26 @@ async function* runAgentTaskStream(options) {
     const completedStatus = "completed";
     session = touchSession({ ...session, status: completedStatus });
     await store?.put(session);
-    const backendEnd = streamEvent({ type: "backend_end", task, session, backend: options.backend.kind });
+    const backendEnd = streamEvent({
+      type: "backend_end",
+      task,
+      session,
+      backend: options.backend.kind
+    });
     await store?.appendEvent?.(session.id, backendEnd);
     yield backendEnd;
     const reason = "backend completed";
     const taskEnd = streamEvent({ type: "task_end", task, status: completedStatus, reason });
     await store?.appendEvent?.(session.id, taskEnd);
     yield taskEnd;
-    const final = streamEvent({ type: "final", task, session, status: completedStatus, reason, text: finalText || void 0 });
+    const final = streamEvent({
+      type: "final",
+      task,
+      session,
+      status: completedStatus,
+      reason,
+      text: finalText || void 0
+    });
     await store?.appendEvent?.(session.id, final);
     yield final;
   } catch (err) {
@@ -206,50 +586,226 @@ async function* runAgentTaskStream(options) {
     const taskEnd = streamEvent({ type: "task_end", task, status, reason: message });
     await store?.appendEvent?.(session.id, taskEnd);
     yield taskEnd;
-    const final = streamEvent({ type: "final", task, session, status, reason: message, text: finalText || void 0 });
+    const final = streamEvent({
+      type: "final",
+      task,
+      session,
+      status,
+      reason: message,
+      text: finalText || void 0
+    });
     await store?.appendEvent?.(session.id, final);
     yield final;
   }
 }
-function decideKnowledgeReadiness(report, options = {}) {
-  const minimumScore = options.minimumScore ?? 0.7;
-  const blockingGapIds = report.blockingMissingRequirements.map((requirement) => requirement.id);
-  const nonBlockingGapIds = report.nonBlockingGaps.map((requirement) => requirement.id);
-  if (blockingGapIds.length > 0) {
-    return {
-      passed: false,
-      status: "blocked",
-      reason: report.reason,
-      readinessScore: report.readinessScore,
-      recommendedAction: report.recommendedAction,
-      severity: report.severity,
-      blockingGapIds,
-      nonBlockingGapIds
-    };
+async function runKnowledgePreflight(task, questions, acquisitionPlans, provider, onEvent) {
+  let userAnswers = {};
+  let acquiredEvidenceIds = [];
+  if (questions.length > 0 && provider?.answerQuestions) {
+    await emit(onEvent, { type: "questions_start", task, questions });
+    userAnswers = await provider.answerQuestions(questions, task);
+    await emit(onEvent, { type: "questions_end", task, questions, userAnswers });
   }
-  if (report.readinessScore < minimumScore) {
-    return {
-      passed: false,
-      status: "caveat",
-      reason: `Knowledge readiness score ${report.readinessScore.toFixed(3)} is below minimum ${minimumScore.toFixed(3)}.`,
-      readinessScore: report.readinessScore,
-      recommendedAction: report.recommendedAction,
-      severity: report.severity,
-      blockingGapIds,
-      nonBlockingGapIds
-    };
+  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
+    await emit(onEvent, { type: "acquisition_start", task, acquisitionPlans });
+    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
+    await emit(onEvent, {
+      type: "acquisition_end",
+      task,
+      acquisitionPlans,
+      acquiredEvidenceIds
+    });
+  }
+  return { userAnswers, acquiredEvidenceIds };
+}
+async function runKnowledgePreflightStream(task, questions, acquisitionPlans, provider) {
+  const events = [];
+  let userAnswers = {};
+  let acquiredEvidenceIds = [];
+  if (questions.length > 0 && provider?.answerQuestions) {
+    events.push(streamEvent({ type: "questions_start", task, questions }));
+    userAnswers = await provider.answerQuestions(questions, task);
+    events.push(streamEvent({ type: "questions_end", task, questions, userAnswers }));
+  }
+  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
+    events.push(streamEvent({ type: "acquisition_start", task, acquisitionPlans }));
+    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
+    events.push(
+      streamEvent({ type: "acquisition_end", task, acquisitionPlans, acquiredEvidenceIds })
+    );
+  }
+  return { userAnswers, acquiredEvidenceIds, events };
+}
+function streamEvent(event) {
+  return { ...event, timestamp: nowIso() };
+}
+async function startBackendSession(backend, input, context, requestedSessionId) {
+  if (backend.start) return backend.start(input, { ...context, requestedSessionId });
+  return newRuntimeSession(backend.kind, requestedSessionId);
+}
+async function resumeBackendSession(backend, session, input, context) {
+  if (session.backend !== backend.kind) {
+    throw new SessionMismatchError(session.backend, backend.kind);
+  }
+  if (backend.resume) return backend.resume(session, input, context);
+  return touchSession({ ...session, status: "active" });
+}
+function buildReadiness(task, provider) {
+  if (provider?.buildReadiness) return provider.buildReadiness(task);
+  return scoreKnowledgeReadiness({
+    taskId: task.id,
+    requirements: task.requiredKnowledge ?? [],
+    metadata: { domain: task.domain, ...task.metadata }
+  });
+}
+function isKnowledgeBlocked(evals) {
+  return evals.some((evalResult) => evalResult.id === "knowledge-ready" && !evalResult.passed);
+}
+function statusFromControl(control) {
+  if (control.stoppedBy === "abort") return "aborted";
+  if (control.reason.includes("knowledge readiness blocked")) return "blocked";
+  if (control.pass) return "completed";
+  return "failed";
+}
+async function emit(sink, event) {
+  await sink?.(event);
+}
+function toAgentContext(task, knowledge, ctx) {
+  return {
+    task,
+    knowledge,
+    state: ctx.state,
+    evals: ctx.evals,
+    history: ctx.history,
+    budget: ctx.budget,
+    stepIndex: ctx.stepIndex,
+    wallMs: ctx.wallMs,
+    spentCostUsd: ctx.spentCostUsd,
+    remainingCostUsd: ctx.remainingCostUsd,
+    abortSignal: ctx.abortSignal
+  };
+}
+
+// src/runtime-run.ts
+function startRuntimeRun(options) {
+  if (!options.workspaceId) {
+    throw new ValidationError("startRuntimeRun: workspaceId is required");
   }
+  if (!options.taskSpec?.id) {
+    throw new ValidationError("startRuntimeRun: taskSpec.id is required");
+  }
+  const now = options.now ?? Date.now;
+  const startedAtMs = now();
+  const startedAt = new Date(startedAtMs).toISOString();
+  const id = options.id ?? `${options.taskSpec.id}:${randomSuffix()}`;
+  let status = "running";
+  let completedAtMs;
+  let resultSummary;
+  let error;
+  let completionMetadata;
+  const ledger = {
+    tokensIn: 0,
+    tokensOut: 0,
+    costUsd: 0,
+    wallMs: 0,
+    llmCalls: 0
+  };
+  const snapshotCost = () => ({
+    tokensIn: ledger.tokensIn,
+    tokensOut: ledger.tokensOut,
+    costUsd: ledger.costUsd,
+    wallMs: (completedAtMs ?? now()) - startedAtMs,
+    llmCalls: ledger.llmCalls
+  });
+  const buildRow = (extraMetadata) => ({
+    id,
+    workspaceId: options.workspaceId,
+    sessionId: options.sessionId,
+    agentId: options.agentId,
+    domain: options.taskSpec.domain,
+    taskId: options.taskSpec.id,
+    scenarioId: options.scenarioId,
+    status,
+    resultSummary,
+    error,
+    cost: snapshotCost(),
+    startedAt,
+    completedAt: completedAtMs !== void 0 ? new Date(completedAtMs).toISOString() : void 0,
+    metadata: mergeMetadata(completionMetadata, extraMetadata)
+  });
   return {
-    passed: true,
-    status: "ready",
-    reason: report.reason,
-    readinessScore: report.readinessScore,
-    recommendedAction: report.recommendedAction,
-    severity: report.severity,
-    blockingGapIds,
-    nonBlockingGapIds
+    id,
+    workspaceId: options.workspaceId,
+    sessionId: options.sessionId,
+    taskSpec: options.taskSpec,
+    get status() {
+      return status;
+    },
+    observe(event) {
+      if (event.type !== "llm_call") return;
+      ledger.llmCalls += 1;
+      if (typeof event.tokensIn === "number" && Number.isFinite(event.tokensIn)) {
+        ledger.tokensIn += event.tokensIn;
+      }
+      if (typeof event.tokensOut === "number" && Number.isFinite(event.tokensOut)) {
+        ledger.tokensOut += event.tokensOut;
+      }
+      if (typeof event.costUsd === "number" && Number.isFinite(event.costUsd)) {
+        ledger.costUsd += event.costUsd;
+      }
+    },
+    cost: snapshotCost,
+    complete(input) {
+      if (input.status === "running") {
+        throw new ValidationError('complete() requires a terminal status, got "running"');
+      }
+      if (status !== "running") {
+        if (status === input.status) return;
+        throw new RuntimeRunStateError(
+          `Cannot transition runtime run from "${status}" to "${input.status}"`
+        );
+      }
+      status = input.status;
+      completedAtMs = now();
+      resultSummary = input.resultSummary;
+      error = input.error;
+      completionMetadata = input.metadata;
+      if (input.cost) {
+        if (typeof input.cost.tokensIn === "number" && Number.isFinite(input.cost.tokensIn)) {
+          ledger.tokensIn = input.cost.tokensIn;
+        }
+        if (typeof input.cost.tokensOut === "number" && Number.isFinite(input.cost.tokensOut)) {
+          ledger.tokensOut = input.cost.tokensOut;
+        }
+        if (typeof input.cost.costUsd === "number" && Number.isFinite(input.cost.costUsd)) {
+          ledger.costUsd = input.cost.costUsd;
+        }
+        if (typeof input.cost.llmCalls === "number" && Number.isFinite(input.cost.llmCalls)) {
+          ledger.llmCalls = input.cost.llmCalls;
+        }
+      }
+    },
+    toRow(metadata) {
+      return buildRow(metadata);
+    },
+    async persist(metadata) {
+      if (status === "running") {
+        throw new RuntimeRunStateError("Cannot persist a runtime run before complete() is called");
+      }
+      if (!options.adapter) return;
+      await options.adapter.upsert(buildRow(metadata));
+    }
   };
 }
+function mergeMetadata(base, extra) {
+  if (!base && !extra) return void 0;
+  return { ...base ?? {}, ...extra ?? {} };
+}
+function randomSuffix() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+// src/sanitize.ts
 function sanitizeKnowledgeReadinessReport(report, options = {}) {
   return {
     taskId: report.taskId,
@@ -277,7 +833,10 @@ function sanitizeAgentRuntimeEvent(event, options = {}) {
     return { ...base, knowledge: sanitizeKnowledgeReadinessReport(event.knowledge, options) };
   }
   if (event.type === "questions_start") {
-    return { ...base, questions: event.questions.map((question) => sanitizeQuestion(question, options)) };
+    return {
+      ...base,
+      questions: event.questions.map((question) => sanitizeQuestion(question, options))
+    };
   }
   if (event.type === "questions_end") {
     return {
@@ -318,7 +877,12 @@ function sanitizeRuntimeStreamEvent(event, options = {}) {
     };
   }
   if (event.type === "questions_start") {
-    return { type: event.type, ...withTask, timestamp: event.timestamp, questions: event.questions.map((question) => sanitizeQuestion(question, options)) };
+    return {
+      type: event.type,
+      ...withTask,
+      timestamp: event.timestamp,
+      questions: event.questions.map((question) => sanitizeQuestion(question, options))
+    };
   }
   if (event.type === "questions_end") {
     return {
@@ -330,7 +894,12 @@ function sanitizeRuntimeStreamEvent(event, options = {}) {
     };
   }
   if (event.type === "acquisition_start") {
-    return { type: event.type, ...withTask, timestamp: event.timestamp, acquisitionPlans: event.acquisitionPlans.map(sanitizeAcquisitionPlan) };
+    return {
+      type: event.type,
+      ...withTask,
+      timestamp: event.timestamp,
+      acquisitionPlans: event.acquisitionPlans.map(sanitizeAcquisitionPlan)
+    };
   }
   if (event.type === "acquisition_end") {
     return {
@@ -364,6 +933,20 @@ function sanitizeRuntimeStreamEvent(event, options = {}) {
       result: options.includeControlPayloads ? event.result : void 0
     };
   }
+  if (event.type === "llm_call") {
+    return {
+      type: event.type,
+      ...withTask,
+      ...withSession,
+      timestamp: event.timestamp,
+      model: event.model,
+      tokensIn: event.tokensIn,
+      tokensOut: event.tokensOut,
+      costUsd: event.costUsd,
+      latencyMs: event.latencyMs,
+      finishReason: event.finishReason
+    };
+  }
   if (event.type === "artifact") {
     return {
       type: event.type,
@@ -397,198 +980,48 @@ function sanitizeRuntimeStreamEvent(event, options = {}) {
     ...pickPublicStreamFields(event)
   };
 }
-function createRuntimeEventCollector(options = {}) {
-  const events = [];
+function sanitizeTask(task, options) {
   return {
-    events,
-    onEvent: (event) => {
-      events.push(sanitizeAgentRuntimeEvent(event, options));
-    }
+    id: task.id,
+    intent: task.intent,
+    domain: task.domain,
+    inputs: options.includeInputs ? task.inputs : task.inputs ? "[redacted]" : void 0,
+    requiredKnowledge: task.requiredKnowledge?.map(
+      (requirement) => sanitizeKnowledgeRequirement(requirement, options)
+    ),
+    metadata: options.includeMetadata ? task.metadata : task.metadata ? "[redacted]" : void 0
   };
 }
-function createRuntimeStreamEventCollector(options = {}) {
-  const events = [];
-  const eventCountsByType = {};
-  let firstSessionId;
-  let finalStatus;
-  let finalReason;
-  let finalText = "";
+function sanitizeRuntimeSession(session, options) {
   return {
-    events,
-    onEvent: (event) => {
-      events.push(sanitizeRuntimeStreamEvent(event, options));
-      eventCountsByType[event.type] = (eventCountsByType[event.type] ?? 0) + 1;
-      if (event.type === "text_delta") finalText += event.text;
-      if (!firstSessionId && (event.type === "session_created" || event.type === "session_resumed")) {
-        firstSessionId = event.session.id;
-      }
-      if (event.type === "final") {
-        finalStatus = event.status;
-        finalReason = event.reason;
-      }
-    },
-    summary() {
-      return {
-        eventCount: events.length,
-        eventCountsByType: { ...eventCountsByType },
-        firstSessionId,
-        finalStatus,
-        finalReason,
-        finalText
-      };
-    }
+    id: session.id,
+    backend: session.backend,
+    status: session.status,
+    hasResumeToken: Boolean(session.resumeToken),
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+    metadata: options.includeMetadata ? session.metadata : session.metadata ? "[redacted]" : void 0
   };
 }
-function encodeServerSentEvent(data, options = {}) {
-  const lines = [];
-  if (options.id) lines.push(`id: ${stripNewlines(options.id)}`);
-  if (options.event) lines.push(`event: ${stripNewlines(options.event)}`);
-  if (typeof options.retry === "number" && Number.isFinite(options.retry) && options.retry >= 0) {
-    lines.push(`retry: ${Math.floor(options.retry)}`);
-  }
-  const payload = typeof data === "string" ? data : JSON.stringify(data);
-  for (const line of payload.split(/\r?\n/)) {
-    lines.push(`data: ${line}`);
-  }
-  return `${lines.join("\n")}
-
-`;
-}
-function readinessServerSentEvent(report, options = {}) {
-  const { event, id, retry, ...telemetryOptions } = options;
-  return encodeServerSentEvent({
-    type: "readiness",
-    readiness: sanitizeKnowledgeReadinessReport(report, telemetryOptions)
-  }, { event, id, retry });
-}
-function runtimeStreamServerSentEvent(event, options = {}) {
-  const { event: sseEvent, id, retry, ...telemetryOptions } = options;
-  return encodeServerSentEvent(sanitizeRuntimeStreamEvent(event, telemetryOptions), { event: sseEvent, id, retry });
-}
-function createIterableBackend(options) {
-  return options;
+function sanitizeKnowledgeRequirement(requirement, options) {
+  const includeDescription = options.includeRequirementDescriptions && requirement.sensitivity !== "secret";
+  return {
+    id: requirement.id,
+    description: includeDescription ? requirement.description : void 0,
+    requiredFor: requirement.requiredFor,
+    category: requirement.category,
+    acquisitionMode: requirement.acquisitionMode,
+    importance: requirement.importance,
+    freshness: requirement.freshness,
+    sensitivity: requirement.sensitivity,
+    confidenceNeeded: requirement.confidenceNeeded,
+    currentConfidence: requirement.currentConfidence,
+    evidenceCount: requirement.evidenceIds.length,
+    evidenceIds: options.includeEvidenceIds ? requirement.evidenceIds : void 0,
+    fallbackPolicy: requirement.fallbackPolicy
+  };
 }
-function createSandboxPromptBackend(options) {
-  return {
-    kind: options.kind ?? "sandbox",
-    async start(input, context) {
-      const box = await options.getBox(input, context);
-      return newRuntimeSession(options.kind ?? "sandbox", options.getSessionId?.(box, input) ?? context.requestedSessionId, {
-        resumable: true
-      });
-    },
-    resume(session) {
-      return touchSession({ ...session, status: "active" });
-    },
-    async *stream(input, context) {
-      const box = await options.getBox(input, context);
-      const message = input.message ?? input.messages?.at(-1)?.content ?? context.task.intent;
-      for await (const event of options.streamPrompt(box, message, context)) {
-        const mapped = options.mapEvent?.(event, context) ?? mapCommonBackendEvent(event, context);
-        if (mapped) yield mapped;
-      }
-    }
-  };
-}
-function createOpenAICompatibleBackend(options) {
-  const fetcher = options.fetchImpl ?? fetch;
-  return {
-    kind: options.kind ?? "tcloud",
-    start(_input, context) {
-      return newRuntimeSession(options.kind ?? "tcloud", context.requestedSessionId);
-    },
-    async *stream(input, context) {
-      const response = await fetcher(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${options.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          model: options.model,
-          stream: true,
-          messages: input.messages ?? [{ role: "user", content: input.message ?? context.task.intent }]
-        }),
-        signal: context.signal
-      });
-      if (!response.ok) throw new Error(`chat backend returned ${response.status}`);
-      yield* streamResponseEvents(response, context);
-    }
-  };
-}
-async function runKnowledgePreflight(task, questions, acquisitionPlans, provider, onEvent) {
-  let userAnswers = {};
-  let acquiredEvidenceIds = [];
-  if (questions.length > 0 && provider?.answerQuestions) {
-    await emit(onEvent, { type: "questions_start", task, questions });
-    userAnswers = await provider.answerQuestions(questions, task);
-    await emit(onEvent, { type: "questions_end", task, questions, userAnswers });
-  }
-  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
-    await emit(onEvent, { type: "acquisition_start", task, acquisitionPlans });
-    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
-    await emit(onEvent, { type: "acquisition_end", task, acquisitionPlans, acquiredEvidenceIds });
-  }
-  return { userAnswers, acquiredEvidenceIds };
-}
-async function runKnowledgePreflightStream(task, questions, acquisitionPlans, provider) {
-  const events = [];
-  let userAnswers = {};
-  let acquiredEvidenceIds = [];
-  if (questions.length > 0 && provider?.answerQuestions) {
-    events.push(streamEvent({ type: "questions_start", task, questions }));
-    userAnswers = await provider.answerQuestions(questions, task);
-    events.push(streamEvent({ type: "questions_end", task, questions, userAnswers }));
-  }
-  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
-    events.push(streamEvent({ type: "acquisition_start", task, acquisitionPlans }));
-    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
-    events.push(streamEvent({ type: "acquisition_end", task, acquisitionPlans, acquiredEvidenceIds }));
-  }
-  return { userAnswers, acquiredEvidenceIds, events };
-}
-function sanitizeTask(task, options) {
-  return {
-    id: task.id,
-    intent: task.intent,
-    domain: task.domain,
-    inputs: options.includeInputs ? task.inputs : task.inputs ? "[redacted]" : void 0,
-    requiredKnowledge: task.requiredKnowledge?.map(
-      (requirement) => sanitizeKnowledgeRequirement(requirement, options)
-    ),
-    metadata: options.includeMetadata ? task.metadata : task.metadata ? "[redacted]" : void 0
-  };
-}
-function sanitizeRuntimeSession(session, options) {
-  return {
-    id: session.id,
-    backend: session.backend,
-    status: session.status,
-    hasResumeToken: Boolean(session.resumeToken),
-    createdAt: session.createdAt,
-    updatedAt: session.updatedAt,
-    metadata: options.includeMetadata ? session.metadata : session.metadata ? "[redacted]" : void 0
-  };
-}
-function sanitizeKnowledgeRequirement(requirement, options) {
-  const includeDescription = options.includeRequirementDescriptions && requirement.sensitivity !== "secret";
-  return {
-    id: requirement.id,
-    description: includeDescription ? requirement.description : void 0,
-    requiredFor: requirement.requiredFor,
-    category: requirement.category,
-    acquisitionMode: requirement.acquisitionMode,
-    importance: requirement.importance,
-    freshness: requirement.freshness,
-    sensitivity: requirement.sensitivity,
-    confidenceNeeded: requirement.confidenceNeeded,
-    currentConfidence: requirement.currentConfidence,
-    evidenceCount: requirement.evidenceIds.length,
-    evidenceIds: options.includeEvidenceIds ? requirement.evidenceIds : void 0,
-    fallbackPolicy: requirement.fallbackPolicy
-  };
-}
-function sanitizeQuestion(question, options) {
+function sanitizeQuestion(question, options) {
   return {
     id: question.id,
     question: options.includeRequirementDescriptions && question.answerType !== "credential" ? question.question : void 0,
@@ -657,207 +1090,294 @@ function summarizeEvals(evals, options) {
 function redactRecord(record) {
   return Object.fromEntries(Object.keys(record).map((key) => [key, "[redacted]"]));
 }
-function stripNewlines(value) {
-  return value.replace(/[\r\n]/g, " ");
-}
-function timestamp() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function streamEvent(event) {
-  return { ...event, timestamp: timestamp() };
-}
-function newRuntimeSession(backend, requestedId, metadata) {
-  const now = timestamp();
-  return {
-    id: requestedId || crypto.randomUUID(),
-    backend,
-    status: "active",
-    createdAt: now,
-    updatedAt: now,
-    metadata
-  };
-}
-function touchSession(session) {
-  return { ...session, updatedAt: timestamp() };
-}
-async function startBackendSession(backend, input, context, requestedSessionId) {
-  if (backend.start) return backend.start(input, { ...context, requestedSessionId });
-  return newRuntimeSession(backend.kind, requestedSessionId);
-}
-async function resumeBackendSession(backend, session, input, context) {
-  if (session.backend !== backend.kind) {
-    throw new Error(`Cannot resume ${session.backend} session with ${backend.kind} backend`);
-  }
-  if (backend.resume) return backend.resume(session, input, context);
-  return touchSession({ ...session, status: "active" });
-}
-function normalizeBackendStreamEvent(event, task, session) {
-  if ("task" in event && event.task && "session" in event && event.session && "timestamp" in event && event.timestamp) return event;
-  return {
-    ...event,
-    task: "task" in event && event.task ? event.task : task,
-    session: "session" in event && event.session ? event.session : session,
-    timestamp: "timestamp" in event && event.timestamp ? event.timestamp : timestamp()
-  };
-}
 function pickPublicStreamFields(event) {
   if (event.type === "session_created" || event.type === "session_resumed") return {};
-  if (event.type === "backend_start" || event.type === "backend_end") return { backend: event.backend };
-  if (event.type === "backend_error") return { backend: event.backend, message: event.message, recoverable: event.recoverable };
+  if (event.type === "backend_start" || event.type === "backend_end")
+    return { backend: event.backend };
+  if (event.type === "backend_error") {
+    return { backend: event.backend, message: event.message, recoverable: event.recoverable };
+  }
   if (event.type === "task_end") return { status: event.status, reason: event.reason };
   if (event.type === "text_delta" || event.type === "reasoning_delta") return { text: event.text };
   return {};
 }
-function mapCommonBackendEvent(event, context) {
-  if (!event || typeof event !== "object") return void 0;
-  const record = event;
-  const type = String(record.type ?? "");
-  const data = record.data && typeof record.data === "object" ? record.data : record;
-  if (type === "message.part.updated" || type === "text_delta" || type === "delta") {
-    const text = stringValue(data.text) ?? stringValue(data.delta) ?? stringValue(record.text);
-    return text ? { type: "text_delta", task: context.task, session: context.session, text, timestamp: timestamp() } : void 0;
-  }
-  if (type === "reasoning_delta") {
-    const text = stringValue(data.text) ?? stringValue(record.text);
-    return text ? { type: "reasoning_delta", task: context.task, session: context.session, text, timestamp: timestamp() } : void 0;
-  }
-  if (type === "tool_call") {
-    return {
-      type: "tool_call",
-      task: context.task,
-      session: context.session,
-      toolName: stringValue(data.name) ?? stringValue(record.toolName) ?? "tool",
-      toolCallId: stringValue(data.id) ?? stringValue(record.toolCallId),
-      args: data.args ?? data.input ?? record.args,
-      timestamp: timestamp()
-    };
-  }
-  if (type === "tool_result") {
-    return {
-      type: "tool_result",
-      task: context.task,
-      session: context.session,
-      toolName: stringValue(data.name) ?? stringValue(record.toolName) ?? "tool",
-      toolCallId: stringValue(data.id) ?? stringValue(record.toolCallId),
-      result: data.result ?? data.output ?? record.result,
-      timestamp: timestamp()
-    };
-  }
-  if (type === "result" || type === "final") {
-    const text = stringValue(data.finalText) ?? stringValue(data.text) ?? stringValue(record.text);
-    return text ? { type: "text_delta", task: context.task, session: context.session, text, timestamp: timestamp() } : void 0;
-  }
-  return void 0;
+function createRuntimeEventCollector(options = {}) {
+  const events = [];
+  return {
+    events,
+    onEvent: (event) => {
+      events.push(sanitizeAgentRuntimeEvent(event, options));
+    }
+  };
 }
-async function* streamResponseEvents(response, context) {
-  const body = response.body;
-  if (!body) return;
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
-    for (const event of drainStreamBuffer(false)) yield event;
-  }
-  buffer += decoder.decode().replace(/\r\n/g, "\n");
-  for (const event of drainStreamBuffer(true)) yield event;
-  if (buffer.trim()) {
-    const event = parseStreamChunk(buffer, context);
-    if (event) yield event;
-  }
-  function* drainStreamBuffer(flush) {
-    for (; ; ) {
-      const sseBoundary = buffer.indexOf("\n\n");
-      if (sseBoundary >= 0) {
-        const chunk = buffer.slice(0, sseBoundary);
-        buffer = buffer.slice(sseBoundary + 2);
-        const event = parseStreamChunk(chunk, context);
-        if (event) yield event;
-        continue;
-      }
-      const newline = buffer.indexOf("\n");
-      if (newline >= 0 && !buffer.slice(0, newline).startsWith("data:")) {
-        const line = buffer.slice(0, newline);
-        buffer = buffer.slice(newline + 1);
-        const event = parseStreamChunk(line, context);
-        if (event) yield event;
-        continue;
+function createRuntimeStreamEventCollector(options = {}) {
+  const events = [];
+  const eventCountsByType = {};
+  let firstSessionId;
+  let finalStatus;
+  let finalReason;
+  let finalText = "";
+  return {
+    events,
+    onEvent: (event) => {
+      events.push(sanitizeRuntimeStreamEvent(event, options));
+      eventCountsByType[event.type] = (eventCountsByType[event.type] ?? 0) + 1;
+      if (event.type === "text_delta") finalText += event.text;
+      if (!firstSessionId && (event.type === "session_created" || event.type === "session_resumed")) {
+        firstSessionId = event.session.id;
       }
-      if (flush && buffer.trim() && !buffer.trimStart().startsWith("data:")) {
-        const line = buffer;
-        buffer = "";
-        const event = parseStreamChunk(line, context);
-        if (event) yield event;
-        continue;
+      if (event.type === "final") {
+        finalStatus = event.status;
+        finalReason = event.reason;
       }
-      break;
+    },
+    summary() {
+      return {
+        eventCount: events.length,
+        eventCountsByType: { ...eventCountsByType },
+        firstSessionId,
+        finalStatus,
+        finalReason,
+        finalText
+      };
     }
-  }
+  };
 }
-function parseStreamChunk(chunk, context) {
-  const lines = chunk.split(/\r?\n/);
-  const dataLines = lines.filter((line) => line.startsWith("data:"));
-  const data = dataLines.length > 0 ? dataLines.map((line) => line.slice(5).trimStart()).join("\n") : chunk.trim();
-  if (!data || data === "[DONE]") return void 0;
-  try {
-    const parsed = JSON.parse(data);
-    const choice = Array.isArray(parsed.choices) ? parsed.choices[0] : void 0;
-    const delta = choice?.delta;
-    const message = choice?.message;
-    const text = stringValue(delta?.content) ?? stringValue(message?.content) ?? stringValue(parsed.text);
-    if (text) return { type: "text_delta", task: context.task, session: context.session, text, timestamp: timestamp() };
-    return mapCommonBackendEvent(parsed, context);
-  } catch {
-    return { type: "text_delta", task: context.task, session: context.session, text: data, timestamp: timestamp() };
+
+// src/sse.ts
+function encodeServerSentEvent(data, options = {}) {
+  const lines = [];
+  if (options.id) lines.push(`id: ${stripNewlines(options.id)}`);
+  if (options.event) lines.push(`event: ${stripNewlines(options.event)}`);
+  if (typeof options.retry === "number" && Number.isFinite(options.retry) && options.retry >= 0) {
+    lines.push(`retry: ${Math.floor(options.retry)}`);
   }
+  const payload = typeof data === "string" ? data : JSON.stringify(data);
+  for (const line of payload.split(/\r?\n/)) {
+    lines.push(`data: ${line}`);
+  }
+  return `${lines.join("\n")}
+
+`;
 }
-function stringValue(value) {
-  return typeof value === "string" && value.length > 0 ? value : void 0;
+function readinessServerSentEvent(report, options = {}) {
+  const { event, id, retry, ...telemetryOptions } = options;
+  return encodeServerSentEvent(
+    {
+      type: "readiness",
+      readiness: sanitizeKnowledgeReadinessReport(report, telemetryOptions)
+    },
+    { event, id, retry }
+  );
 }
-function buildReadiness(task, provider) {
-  if (provider?.buildReadiness) return provider.buildReadiness(task);
-  return scoreKnowledgeReadiness({
-    taskId: task.id,
-    requirements: task.requiredKnowledge ?? [],
-    metadata: { domain: task.domain, ...task.metadata }
+function runtimeStreamServerSentEvent(event, options = {}) {
+  const { event: sseEvent, id, retry, ...telemetryOptions } = options;
+  return encodeServerSentEvent(sanitizeRuntimeStreamEvent(event, telemetryOptions), {
+    event: sseEvent,
+    id,
+    retry
   });
 }
-function isKnowledgeBlocked(evals) {
-  return evals.some((evalResult) => evalResult.id === "knowledge-ready" && !evalResult.passed);
-}
-function statusFromControl(control) {
-  if (control.stoppedBy === "abort") return "aborted";
-  if (control.reason.includes("knowledge readiness blocked")) return "blocked";
-  if (control.pass) return "completed";
-  return "failed";
-}
-async function emit(sink, event) {
-  await sink?.(event);
+function stripNewlines(value) {
+  return value.replace(/[\r\n]/g, " ");
 }
-function toAgentContext(task, knowledge, ctx) {
+
+// src/trace-bridge.ts
+function createTraceBridge(options) {
+  if (!options.runId) {
+    throw new ValidationError("createTraceBridge: runId is required");
+  }
+  let counter = 0;
+  const newEventId = options.newEventId ?? (() => `evt-${++counter}`);
+  const baseSpanId = options.spanId;
+  const toTraceEvent = (event) => {
+    const projection = projectToTraceEvent(event);
+    if (!projection) return void 0;
+    return {
+      eventId: newEventId(),
+      runId: options.runId,
+      spanId: baseSpanId,
+      kind: projection.kind,
+      timestamp: timestampFor(event),
+      payload: projection.payload
+    };
+  };
   return {
-    task,
-    knowledge,
-    state: ctx.state,
-    evals: ctx.evals,
-    history: ctx.history,
-    budget: ctx.budget,
-    stepIndex: ctx.stepIndex,
-    wallMs: ctx.wallMs,
-    spentCostUsd: ctx.spentCostUsd,
-    remainingCostUsd: ctx.remainingCostUsd,
-    abortSignal: ctx.abortSignal
+    toTraceEvent,
+    drain(events) {
+      const out = [];
+      for (const event of events) {
+        const trace = toTraceEvent(event);
+        if (trace) out.push(trace);
+      }
+      return out;
+    }
   };
 }
+function toAgentEvalTrace(event, options) {
+  return createTraceBridge(options).toTraceEvent(event);
+}
+function projectToTraceEvent(event) {
+  switch (event.type) {
+    case "task_start":
+      return {
+        kind: "log",
+        payload: { phase: "task_start", taskId: event.task.id, intent: event.task.intent }
+      };
+    case "readiness_start":
+      return { kind: "log", payload: { phase: "readiness_start", taskId: event.task.id } };
+    case "readiness_end":
+      return {
+        kind: event.decision.passed ? "log" : "policy_violation",
+        payload: {
+          phase: "readiness_end",
+          taskId: event.task.id,
+          status: event.decision.status,
+          readinessScore: event.decision.readinessScore,
+          blockingGapIds: event.decision.blockingGapIds,
+          nonBlockingGapIds: event.decision.nonBlockingGapIds,
+          reason: event.decision.reason
+        }
+      };
+    case "questions_start":
+      return {
+        kind: "log",
+        payload: { phase: "questions_start", questionCount: event.questions.length }
+      };
+    case "questions_end":
+      return {
+        kind: "log",
+        payload: {
+          phase: "questions_end",
+          questionCount: event.questions.length,
+          answerCount: Object.keys(event.userAnswers).length
+        }
+      };
+    case "acquisition_start":
+      return {
+        kind: "log",
+        payload: { phase: "acquisition_start", planCount: event.acquisitionPlans.length }
+      };
+    case "acquisition_end":
+      return {
+        kind: "log",
+        payload: {
+          phase: "acquisition_end",
+          planCount: event.acquisitionPlans.length,
+          evidenceCount: event.acquiredEvidenceIds.length
+        }
+      };
+    case "session_created":
+    case "session_resumed":
+      return {
+        kind: "log",
+        payload: {
+          phase: event.type,
+          sessionId: event.session.id,
+          backend: event.session.backend
+        }
+      };
+    case "backend_start":
+    case "backend_end":
+      return { kind: "log", payload: { phase: event.type, backend: event.backend } };
+    case "backend_error":
+      return {
+        kind: "error",
+        payload: {
+          backend: event.backend,
+          message: event.message,
+          recoverable: event.recoverable
+        }
+      };
+    case "tool_call":
+      return {
+        kind: "log",
+        payload: {
+          phase: "tool_call",
+          toolName: event.toolName,
+          toolCallId: event.toolCallId
+          // Args intentionally omitted at this layer; consumers attach the
+          // payload to a `ToolSpan` if they need to retain it. Trace events
+          // are point-in-time markers, not the canonical store for tool I/O.
+        }
+      };
+    case "tool_result":
+      return {
+        kind: "log",
+        payload: {
+          phase: "tool_result",
+          toolName: event.toolName,
+          toolCallId: event.toolCallId
+        }
+      };
+    case "llm_call":
+      return {
+        kind: "log",
+        payload: {
+          phase: "llm_call",
+          model: event.model,
+          tokensIn: event.tokensIn,
+          tokensOut: event.tokensOut,
+          costUsd: event.costUsd,
+          latencyMs: event.latencyMs,
+          finishReason: event.finishReason
+        }
+      };
+    case "artifact":
+      return {
+        kind: "state_mutation",
+        payload: {
+          phase: "artifact",
+          artifactId: event.artifactId,
+          name: event.name,
+          mimeType: event.mimeType
+        }
+      };
+    case "task_end":
+      return {
+        kind: event.status === "failed" || event.status === "aborted" ? "error" : "log",
+        payload: { phase: "task_end", status: event.status, reason: event.reason }
+      };
+    case "final":
+      return {
+        kind: event.status === "failed" || event.status === "aborted" ? "error" : "log",
+        payload: { phase: "final", status: event.status, reason: event.reason }
+      };
+    case "text_delta":
+    case "reasoning_delta":
+      return void 0;
+    default: {
+      const exhaust = event;
+      void exhaust;
+      return void 0;
+    }
+  }
+}
+function timestampFor(event) {
+  const iso = "timestamp" in event ? event.timestamp : void 0;
+  if (!iso) return Date.now();
+  const parsed = Date.parse(iso);
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
 export {
+  AgentEvalError2 as AgentEvalError,
+  BackendTransportError,
+  CaptureIntegrityError,
+  ConfigError,
   InMemoryRuntimeSessionStore,
+  JudgeError,
+  NotFoundError,
+  ReplayError,
+  RuntimeRunStateError,
+  SessionMismatchError,
+  ValidationError,
+  VerificationError,
   createIterableBackend,
   createOpenAICompatibleBackend,
   createRuntimeEventCollector,
   createRuntimeStreamEventCollector,
   createSandboxPromptBackend,
+  createTraceBridge,
   decideKnowledgeReadiness,
   encodeServerSentEvent,
   readinessServerSentEvent,
@@ -867,6 +1387,8 @@ export {
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
   sanitizeRuntimeStreamEvent,
-  summarizeAgentTaskRun
+  startRuntimeRun,
+  summarizeAgentTaskRun,
+  toAgentEvalTrace
 };
 //# sourceMappingURL=index.js.map