@tangle-network/agent-runtime 0.84.0 → 0.85.0

package/dist/{chunk-UJW6EVNY.js → chunk-DLAEEF26.js}

@@ -24,8 +24,12 @@ import {
   stringifySafe,
   zeroTokenUsage
 } from "./chunk-BZF3KQ6G.js";
+import {
+  mapSandboxEvent
+} from "./chunk-4J6RBI3K.js";
 import {
   AnalystError,
+  BackendTransportError,
   PlannerError,
   ValidationError
 } from "./chunk-YEJR7IXO.js";
@@ -678,8 +682,14 @@ function inlineSandboxClient(factory) {
       const createOptions = options;
       return {
         id,
-        async *streamPrompt(message) {
+        async *streamPrompt(message, opts) {
           const controller = new AbortController();
+          const callerSignal = opts?.signal;
+          const onAbort = () => controller.abort(callerSignal?.reason ?? new Error("prompt aborted"));
+          if (callerSignal) {
+            if (callerSignal.aborted) onAbort();
+            else callerSignal.addEventListener("abort", onAbort, { once: true });
+          }
           const spec = { profile: { name: id }, harness: null };
           const exec = factory(spec, { signal: controller.signal, seams: { createOptions } });
           try {
@@ -706,6 +716,7 @@ function inlineSandboxClient(factory) {
               }
             };
           } finally {
+            callerSignal?.removeEventListener("abort", onAbort);
             await exec.teardown("brutalKill").catch(() => {
             });
           }
@@ -4138,6 +4149,800 @@ ${summary}`,
   };
 }
 
+// src/runtime/stream-agent-turn.ts
+import { scoreKnowledgeReadiness } from "@tangle-network/agent-eval";
+
+// 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();
+  get(sessionId) {
+    return this.sessions.get(sessionId);
+  }
+  put(session) {
+    this.sessions.set(session.id, session);
+  }
+  appendEvent(sessionId, event) {
+    const existing = this.events.get(sessionId) ?? [];
+    existing.push(event);
+    this.events.set(sessionId, existing);
+  }
+  listEvents(sessionId) {
+    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;
+      }
+    }
+  };
+}
+var DEFAULT_RETRY_STATUSES = [408, 425, 429, 500, 502, 503, 504];
+function pickRetryDelayMs(attempt, policy) {
+  const exp = policy.initialBackoffMs * 2 ** (attempt - 1);
+  const capped = Math.min(exp, policy.maxBackoffMs);
+  const jitter = capped * policy.jitter * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+function withTimeout(callerSignal, timeoutMs) {
+  if (timeoutMs <= 0) {
+    return { signal: callerSignal ?? new AbortController().signal, dispose: () => void 0 };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new Error(`request timed out after ${timeoutMs}ms`)),
+    timeoutMs
+  );
+  if (typeof timer.unref === "function") {
+    ;
+    timer.unref();
+  }
+  const onCallerAbort = () => controller.abort(callerSignal?.reason ?? new Error("aborted"));
+  if (callerSignal) {
+    if (callerSignal.aborted) onCallerAbort();
+    else callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function createOpenAICompatibleBackend(options) {
+  const fetcher = options.fetchImpl ?? fetch;
+  const kind = options.kind ?? "tcloud";
+  const retryPolicy = {
+    maxAttempts: options.retry?.maxAttempts ?? 5,
+    initialBackoffMs: options.retry?.initialBackoffMs ?? 1e3,
+    maxBackoffMs: options.retry?.maxBackoffMs ?? 3e4,
+    jitter: options.retry?.jitter ?? 0.25,
+    retryStatuses: options.retry?.retryStatuses ?? DEFAULT_RETRY_STATUSES,
+    requestTimeoutMs: options.retry?.requestTimeoutMs ?? 12e4
+  };
+  return {
+    kind,
+    start(_input, context) {
+      return newRuntimeSession(kind, context.requestedSessionId);
+    },
+    async *stream(input, context) {
+      const url = `${options.baseUrl.replace(/\/$/, "")}/chat/completions`;
+      const bodyPayload = {
+        model: options.model,
+        stream: true,
+        stream_options: { include_usage: true },
+        messages: input.messages ?? [
+          { role: "user", content: input.message ?? context.task.intent }
+        ]
+      };
+      if (options.tools && options.tools.length > 0) {
+        bodyPayload.tools = options.tools;
+        if (options.toolChoice !== void 0) bodyPayload.tool_choice = options.toolChoice;
+      }
+      if (options.responseFormat !== void 0) {
+        bodyPayload.response_format = options.responseFormat;
+      }
+      const requestBody = JSON.stringify(bodyPayload);
+      let response;
+      let lastStatus = 0;
+      let lastThrown;
+      for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt++) {
+        lastThrown = void 0;
+        const attemptSignal = withTimeout(context.signal, retryPolicy.requestTimeoutMs);
+        try {
+          response = await fetcher(url, {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${options.apiKey}`,
+              "Content-Type": "application/json",
+              // Cross-gateway forwarding: when this call is part of a
+              // multi-agent conversation, the runner stamps run/turn/
+              // depth/forwarded-auth headers onto the context. They flow
+              // through to the downstream gateway verbatim so the original
+              // user gets billed, the recursion depth stays bounded, and
+              // the trace correlates across hops.
+              ...context.propagatedHeaders ?? {}
+            },
+            body: requestBody,
+            signal: attemptSignal.signal
+          });
+        } catch (err) {
+          attemptSignal.dispose();
+          if (context.signal?.aborted) throw err;
+          lastThrown = err;
+          response = void 0;
+          if (attempt === retryPolicy.maxAttempts) break;
+          await sleep2(pickRetryDelayMs(attempt, retryPolicy), context.signal);
+          continue;
+        }
+        attemptSignal.dispose();
+        if (response.ok) break;
+        lastStatus = response.status;
+        if (!retryPolicy.retryStatuses.includes(response.status)) break;
+        if (attempt === retryPolicy.maxAttempts) break;
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        const delayMs = pickRetryDelayMs(attempt, retryPolicy);
+        await sleep2(delayMs, context.signal);
+      }
+      if (!response) {
+        const reason = lastThrown instanceof Error ? lastThrown.message : String(lastThrown);
+        throw new BackendTransportError(
+          kind,
+          `chat backend unreachable after ${retryPolicy.maxAttempts} attempts: ${reason}`,
+          { status: 0 }
+        );
+      }
+      if (!response.ok) {
+        let body;
+        try {
+          const raw = await response.text();
+          body = raw.length > MAX_ERROR_BODY_BYTES ? `${raw.slice(0, MAX_ERROR_BODY_BYTES)}\u2026` : raw;
+        } catch {
+          body = void 0;
+        }
+        throw new BackendTransportError(kind, `chat backend returned ${lastStatus || "unknown"}`, {
+          status: lastStatus || 0,
+          body
+        });
+      }
+      yield* streamResponseEvents(response, context, options.model);
+    }
+  };
+}
+var MAX_ERROR_BODY_BYTES = 2048;
+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 part = data.part;
+    const partText = part !== void 0 && typeof part === "object" && (part.type === "text" || part.type === void 0) ? stringValue(part.text) : void 0;
+    const text = stringValue(data.text) ?? stringValue(data.delta) ?? stringValue(record.text) ?? partText;
+    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 === "artifact") {
+    const artifactId = stringValue(data.artifactId) ?? stringValue(data.id) ?? stringValue(record.artifactId);
+    if (!artifactId) return void 0;
+    return {
+      type: "artifact",
+      task: context.task,
+      session: context.session,
+      artifactId,
+      name: stringValue(data.name) ?? stringValue(record.name),
+      mimeType: stringValue(data.mimeType) ?? stringValue(record.mimeType),
+      uri: stringValue(data.uri) ?? stringValue(record.uri),
+      content: stringValue(data.content) ?? stringValue(data.body) ?? stringValue(record.content),
+      metadata: data.metadata && typeof data.metadata === "object" ? data.metadata : void 0,
+      timestamp: nowIso()
+    };
+  }
+  if (type === "proposal_created" || type === "proposal" || type === "filing") {
+    const proposalId = stringValue(data.proposalId) ?? stringValue(data.id) ?? stringValue(record.proposalId);
+    if (!proposalId) return void 0;
+    const status = stringValue(data.status) ?? stringValue(record.status);
+    return {
+      type: "proposal_created",
+      task: context.task,
+      session: context.session,
+      proposalId,
+      title: stringValue(data.title) ?? stringValue(record.title) ?? proposalId,
+      status: status === "pending" || status === "approved" || status === "rejected" ? status : void 0,
+      content: stringValue(data.content) ?? stringValue(data.body) ?? stringValue(record.content),
+      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, requestedModel) {
+  const body = response.body;
+  if (!body) return;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const usage = { saw: false };
+  const toolCalls = /* @__PURE__ */ new Map();
+  const startedAt = Date.now();
+  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()) {
+    for (const event of parseStreamChunk(buffer, context, usage, toolCalls)) yield event;
+  }
+  for (const event of flushPendingToolCalls(toolCalls, context)) yield event;
+  if (usage.saw) {
+    yield {
+      type: "llm_call",
+      task: context.task,
+      session: context.session,
+      model: usage.model ?? requestedModel,
+      tokensIn: usage.tokensIn,
+      tokensOut: usage.tokensOut,
+      // `costUsd` is intentionally absent — pricing tables live in consumers
+      // (agent-eval's `estimateCost`, MetricsCollector). Emitting a wrong
+      // number here is worse than emitting none.
+      latencyMs: Date.now() - startedAt,
+      finishReason: usage.finishReason,
+      timestamp: nowIso()
+    };
+  }
+  function* drainStreamBuffer(flush) {
+    for (; ; ) {
+      const sseBoundary = buffer.indexOf("\n\n");
+      if (sseBoundary >= 0) {
+        const chunk = buffer.slice(0, sseBoundary);
+        buffer = buffer.slice(sseBoundary + 2);
+        for (const event of parseStreamChunk(chunk, context, usage, toolCalls)) 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);
+        for (const event of parseStreamChunk(line, context, usage, toolCalls)) yield event;
+        continue;
+      }
+      if (flush && buffer.trim() && !buffer.trimStart().startsWith("data:")) {
+        const line = buffer;
+        buffer = "";
+        for (const event of parseStreamChunk(line, context, usage, toolCalls)) yield event;
+        continue;
+      }
+      break;
+    }
+  }
+}
+function* parseStreamChunk(chunk, context, usage, toolCalls) {
+  const lines = chunk.split(/\r?\n/);
+  const dataLines = lines.filter((line) => line.startsWith("data:"));
+  if (dataLines.length === 0 && lines.every((line) => {
+    const trimmed = line.trim();
+    return trimmed.length === 0 || trimmed.startsWith(":");
+  })) {
+    return;
+  }
+  const data = dataLines.length > 0 ? dataLines.map((line) => line.slice(5).trimStart()).join("\n") : chunk.trim();
+  if (!data || data === "[DONE]") return;
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    yield {
+      type: "text_delta",
+      task: context.task,
+      session: context.session,
+      text: data,
+      timestamp: nowIso()
+    };
+    return;
+  }
+  captureStreamUsage(parsed, usage);
+  const choices = parsed.choices;
+  const choice = Array.isArray(choices) ? choices[0] : void 0;
+  const delta = choice?.delta;
+  const message = choice?.message;
+  const deltaToolCalls = delta?.tool_calls;
+  if (Array.isArray(deltaToolCalls)) {
+    for (const tc of deltaToolCalls) {
+      if (!tc || typeof tc !== "object") continue;
+      const rec = tc;
+      const idx = numberValue(rec.index) ?? 0;
+      const key = `openai:${idx}`;
+      const acc = toolCalls.get(key) ?? { argsRaw: "", source: "openai", finalized: false };
+      const id = stringValue(rec.id);
+      if (id) acc.id = id;
+      const fn = rec.function;
+      const name = stringValue(fn?.name);
+      if (name) acc.name = name;
+      const args = stringValue(fn?.arguments);
+      if (args) acc.argsRaw += args;
+      toolCalls.set(key, acc);
+    }
+  }
+  const messageToolCalls = message?.tool_calls;
+  if (Array.isArray(messageToolCalls)) {
+    for (const tc of messageToolCalls) {
+      if (!tc || typeof tc !== "object") continue;
+      const rec = tc;
+      const fn = rec.function;
+      const idx = numberValue(rec.index) ?? messageToolCalls.indexOf(tc);
+      const key = `openai:${idx}`;
+      const acc = toolCalls.get(key) ?? { argsRaw: "", source: "openai", finalized: false };
+      const id = stringValue(rec.id);
+      if (id) acc.id = id;
+      const name = stringValue(fn?.name);
+      if (name) acc.name = name;
+      const args = stringValue(fn?.arguments);
+      if (args) acc.argsRaw += args;
+      acc.finalized = true;
+      toolCalls.set(key, acc);
+    }
+  }
+  const finishReason = stringValue(choice?.finish_reason);
+  if (finishReason === "tool_calls") {
+    for (const [key, acc] of toolCalls) {
+      if (acc.source === "openai" && !acc.finalized) acc.finalized = true;
+      toolCalls.set(key, acc);
+    }
+  }
+  const eventType = stringValue(parsed.type);
+  if (eventType === "content_block_start") {
+    const block = parsed.content_block;
+    if (block && stringValue(block.type) === "tool_use") {
+      const idx = numberValue(parsed.index) ?? 0;
+      const key = `anthropic:${idx}`;
+      toolCalls.set(key, {
+        id: stringValue(block.id),
+        name: stringValue(block.name),
+        argsRaw: "",
+        source: "anthropic",
+        finalized: false
+      });
+    }
+  }
+  if (eventType === "content_block_delta") {
+    const d = parsed.delta;
+    const dType = stringValue(d?.type);
+    if (dType === "input_json_delta") {
+      const idx = numberValue(parsed.index) ?? 0;
+      const key = `anthropic:${idx}`;
+      const acc = toolCalls.get(key);
+      if (acc) {
+        const partial = stringValue(d?.partial_json) ?? "";
+        acc.argsRaw += partial;
+        toolCalls.set(key, acc);
+      }
+    } else {
+      const text2 = stringValue(d?.text);
+      if (text2) {
+        yield {
+          type: "text_delta",
+          task: context.task,
+          session: context.session,
+          text: text2,
+          timestamp: nowIso()
+        };
+      }
+    }
+  }
+  if (eventType === "content_block_stop") {
+    const idx = numberValue(parsed.index) ?? 0;
+    const key = `anthropic:${idx}`;
+    const acc = toolCalls.get(key);
+    if (acc) {
+      acc.finalized = true;
+      toolCalls.set(key, acc);
+    }
+  }
+  for (const event of drainFinalizedToolCalls(toolCalls, context)) yield event;
+  const text = stringValue(delta?.content) ?? stringValue(message?.content) ?? stringValue(parsed.text);
+  if (text) {
+    yield {
+      type: "text_delta",
+      task: context.task,
+      session: context.session,
+      text,
+      timestamp: nowIso()
+    };
+    return;
+  }
+  const mapped = mapCommonBackendEvent(parsed, context);
+  if (mapped) yield mapped;
+}
+function* drainFinalizedToolCalls(toolCalls, context) {
+  for (const [key, acc] of toolCalls) {
+    if (!acc.finalized) continue;
+    toolCalls.delete(key);
+    yield buildToolCallEvent(acc, context);
+  }
+}
+function* flushPendingToolCalls(toolCalls, context) {
+  for (const [key, acc] of toolCalls) {
+    toolCalls.delete(key);
+    yield buildToolCallEvent(acc, context);
+  }
+}
+function buildToolCallEvent(acc, context) {
+  let args = acc.argsRaw;
+  if (acc.argsRaw.length > 0) {
+    try {
+      args = JSON.parse(acc.argsRaw);
+    } catch {
+      args = acc.argsRaw;
+    }
+  } else {
+    args = {};
+  }
+  return {
+    type: "tool_call",
+    task: context.task,
+    session: context.session,
+    toolName: acc.name ?? "tool",
+    toolCallId: acc.id,
+    args,
+    timestamp: nowIso()
+  };
+}
+function captureStreamUsage(parsed, usage) {
+  const model = stringValue(parsed.model);
+  if (model && !usage.model) usage.model = model;
+  const openAiUsage = parsed.usage;
+  if (openAiUsage && typeof openAiUsage === "object") {
+    const promptTokens = numberValue(openAiUsage.prompt_tokens);
+    const completionTokens = numberValue(openAiUsage.completion_tokens);
+    const inputTokens = numberValue(openAiUsage.input_tokens);
+    const outputTokens = numberValue(openAiUsage.output_tokens);
+    if (promptTokens !== void 0) {
+      usage.tokensIn = promptTokens;
+      usage.saw = true;
+    } else if (inputTokens !== void 0) {
+      usage.tokensIn = (usage.tokensIn ?? 0) + inputTokens;
+      usage.saw = true;
+    }
+    if (completionTokens !== void 0) {
+      usage.tokensOut = completionTokens;
+      usage.saw = true;
+    } else if (outputTokens !== void 0) {
+      usage.tokensOut = (usage.tokensOut ?? 0) + outputTokens;
+      usage.saw = true;
+    }
+  }
+  const type = stringValue(parsed.type);
+  if (type === "message_start") {
+    const message = parsed.message;
+    const messageModel = stringValue(message?.model);
+    if (messageModel && !usage.model) usage.model = messageModel;
+    const messageUsage = message?.usage;
+    const inputTokens = numberValue(messageUsage?.input_tokens);
+    if (inputTokens !== void 0) {
+      usage.tokensIn = inputTokens;
+      usage.saw = true;
+    }
+    const outputTokens = numberValue(messageUsage?.output_tokens);
+    if (outputTokens !== void 0) {
+      usage.tokensOut = (usage.tokensOut ?? 0) + outputTokens;
+      usage.saw = true;
+    }
+  }
+  if (type === "message_delta") {
+    const delta = parsed.delta;
+    const stopReason = stringValue(delta?.stop_reason);
+    if (stopReason) usage.finishReason = stopReason;
+  }
+  const choices = parsed.choices;
+  if (Array.isArray(choices)) {
+    const finishReason = stringValue(
+      choices[0]?.finish_reason
+    );
+    if (finishReason) usage.finishReason = finishReason;
+  }
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/runtime/stream-agent-turn.ts
+async function* streamAgentTurn(backend, prompt, opts = {}) {
+  const label = backend.kind === "chat" ? backend.backend.kind : backend.kind;
+  const task = { id: `turn-${crypto.randomUUID()}`, intent: prompt };
+  const acc = { deltaText: "", input: 0, output: 0, costUsd: 0 };
+  const deadline = deriveTurnSignal(opts.signal, opts.timeoutMs ?? 0);
+  let session;
+  try {
+    session = await startTurnSession(backend, task, prompt, deadline.signal, label);
+    yield { type: "backend_start", task, session, backend: label, timestamp: nowIso() };
+    const inner = backend.kind === "chat" ? driveChatTurn(backend.backend, task, session, prompt, deadline.signal, acc) : driveBoxTurn(
+      backend.kind === "box" ? backend.box : await inlineSandboxClient(backend.factory).create(),
+      prompt,
+      deadline.signal,
+      backend.agentRunName ?? "agent",
+      acc
+    );
+    for await (const event of inner) {
+      yield event;
+      throwIfAborted(deadline.signal);
+    }
+    yield buildFinalEvent(task, session, acc, { status: "completed", reason: "turn completed" });
+  } catch (err) {
+    const callerAborted = opts.signal?.aborted === true;
+    const status = callerAborted ? "aborted" : "failed";
+    const message = err instanceof Error ? err.message : String(err);
+    const error = err instanceof BackendTransportError ? { kind: "transport", message, status: err.status, body: err.body } : { kind: "backend", message };
+    yield {
+      type: "backend_error",
+      task,
+      ...session ? { session } : {},
+      backend: label,
+      message,
+      recoverable: !callerAborted,
+      error,
+      timestamp: nowIso()
+    };
+    yield buildFinalEvent(task, session, acc, { status, reason: message, error });
+  } finally {
+    deadline.dispose();
+  }
+}
+async function collectAgentTurn(stream) {
+  const events = [];
+  for await (const event of stream) events.push(event);
+  const final = events.at(-1);
+  if (!final || final.type !== "final") {
+    throw new Error(
+      `collectAgentTurn: stream ended without a terminal 'final' event (last: ${final ? final.type : "none"})`
+    );
+  }
+  const metadata = final.metadata ?? {};
+  const tokenUsage = metadata.tokenUsage && typeof metadata.tokenUsage === "object" ? metadata.tokenUsage : {};
+  const usage = {
+    input: finiteNumber(tokenUsage.input) ?? 0,
+    output: finiteNumber(tokenUsage.output) ?? 0
+  };
+  const costUsd = finiteNumber(metadata.costUsd);
+  if (costUsd !== void 0) usage.costUsd = costUsd;
+  if (typeof metadata.model === "string" && metadata.model.length > 0) {
+    usage.model = metadata.model;
+  }
+  return {
+    finalText: final.text ?? "",
+    usage,
+    events,
+    status: final.status,
+    ...final.error ? { error: final.error } : {}
+  };
+}
+async function startTurnSession(backend, task, prompt, signal, label) {
+  if (backend.kind === "chat" && backend.backend.start) {
+    return backend.backend.start(
+      { task, message: prompt },
+      { task, knowledge: emptyReadiness(task), signal }
+    );
+  }
+  return newRuntimeSession(label);
+}
+async function* driveBoxTurn(box, prompt, signal, agentRunName, acc) {
+  for await (const event of box.streamPrompt(prompt, { signal })) {
+    const terminalText = terminalTextFromSandboxEvent(event);
+    if (terminalText !== void 0) acc.terminalText = terminalText;
+    const mapped = mapSandboxEvent(event, { agentRunName });
+    if (!mapped) continue;
+    foldEvent(mapped, acc, agentRunName);
+    yield mapped;
+  }
+}
+async function* driveChatTurn(backend, task, session, prompt, signal, acc) {
+  const input = { task, message: prompt };
+  const context = { task, knowledge: emptyReadiness(task), session, signal };
+  for await (const raw of backend.stream(input, context)) {
+    const event = normalizeBackendStreamEvent(raw, task, session);
+    foldEvent(event, acc);
+    yield event;
+  }
+}
+function foldEvent(event, acc, fallbackModelLabel) {
+  if (event.type === "text_delta") {
+    acc.deltaText += event.text;
+    return;
+  }
+  if (event.type === "llm_call") {
+    acc.input += event.tokensIn ?? 0;
+    acc.output += event.tokensOut ?? 0;
+    acc.costUsd += event.costUsd ?? 0;
+    if (event.model && event.model !== fallbackModelLabel) acc.model = event.model;
+  }
+}
+function terminalTextFromSandboxEvent(event) {
+  if (!event || typeof event !== "object") return void 0;
+  const type = String(event.type ?? "");
+  if (type !== "result" && type !== "done" && type !== "final") return void 0;
+  const data = event.data && typeof event.data === "object" ? event.data : {};
+  for (const key of ["finalText", "text", "response", "content"]) {
+    const value = data[key];
+    if (typeof value === "string") return value;
+  }
+  return void 0;
+}
+function buildFinalEvent(task, session, acc, outcome) {
+  const finalText = acc.terminalText ?? acc.deltaText;
+  return {
+    type: "final",
+    task,
+    ...session ? { session } : {},
+    status: outcome.status,
+    reason: outcome.reason,
+    ...finalText ? { text: finalText } : {},
+    metadata: {
+      tokenUsage: { input: acc.input, output: acc.output },
+      ...acc.costUsd > 0 ? { costUsd: acc.costUsd } : {},
+      ...acc.model ? { model: acc.model } : {}
+    },
+    ...outcome.error ? { error: outcome.error } : {},
+    timestamp: nowIso()
+  };
+}
+function emptyReadiness(task) {
+  return scoreKnowledgeReadiness({ taskId: task.id, requirements: [] });
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function throwIfAborted(signal) {
+  if (!signal.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+}
+function deriveTurnSignal(callerSignal, timeoutMs) {
+  const controller = new AbortController();
+  const timer = timeoutMs > 0 ? setTimeout(
+    () => controller.abort(new Error(`agent turn timed out after ${timeoutMs}ms`)),
+    timeoutMs
+  ) : void 0;
+  if (timer && typeof timer.unref === "function") {
+    ;
+    timer.unref();
+  }
+  const onCallerAbort = () => controller.abort(callerSignal?.reason ?? new Error("agent turn aborted"));
+  if (callerSignal) {
+    if (callerSignal.aborted) onCallerAbort();
+    else callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+
 // src/runtime/supervise/detector-monitor.ts
 import {
   argHash,
@@ -4946,6 +5751,14 @@ function tail(s) {
 }
 
 export {
+  newRuntimeSession,
+  touchSession,
+  nowIso,
+  InMemoryRuntimeSessionStore,
+  createIterableBackend,
+  createSandboxPromptBackend,
+  createOpenAICompatibleBackend,
+  normalizeBackendStreamEvent,
   anytimeReport,
   renderAnytimeTable,
   defaultAuditorInstruction,
@@ -5016,6 +5829,8 @@ export {
   pickChampion,
   selectChampion,
   runStrategyEvolution,
+  streamAgentTurn,
+  collectAgentTurn,
   defaultToolDetectors,
   watchTrace,
   runCoderChecks,
@@ -5036,4 +5851,4 @@ export {
   computeFindingId,
   makeFinding2 as makeFinding
 };
-//# sourceMappingURL=chunk-UJW6EVNY.js.map
+//# sourceMappingURL=chunk-DLAEEF26.js.map