@tangle-network/agent-runtime 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { AgentEvalError, KnowledgeReadinessReport, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
 export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
-import { a as AgentBackendInput, b as AgentExecutionBackend, c as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, d as RunAgentTaskOptions, e as AgentTaskRunResult, f as RunAgentTaskStreamOptions, g as AgentRuntimeEvent, h as AgentTaskStatus, i as RuntimeSessionStore, j as RuntimeSession } from './types-DvJIha6w.js';
-export { k as AgentAdapter, l as AgentKnowledgeProvider, m as AgentRuntimeEventSink, n as AgentTaskContext, A as AgentTaskSpec } from './types-DvJIha6w.js';
-export { R as RuntimeRunHandle, a as RuntimeRunPersistenceAdapter, b as RuntimeRunRow, s as startRuntimeRun } from './runtime-run-B2j-hvBj.js';
+import { a as AgentBackendInput, b as AgentExecutionBackend, O as OpenAIChatTool, c as OpenAIChatToolChoice, d as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, e as RunAgentTaskOptions, f as AgentTaskRunResult, g as RunAgentTaskStreamOptions, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-BFgFD_sl.js';
+export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext, A as AgentTaskSpec, B as BackendErrorDetail } from './types-BFgFD_sl.js';
+export { R as RuntimeRunHandle, a as RuntimeRunPersistenceAdapter, b as RuntimeRunRow, s as startRuntimeRun } from './runtime-run-D5ItCKl_.js';
 
 /**
  * @stable
@@ -68,11 +68,59 @@ interface BackendRetryPolicy {
      */
     requestTimeoutMs?: number;
 }
+/**
+ * @stable
+ *
+ * OpenAI-compat streaming backend. Routes `runAgentTaskStream` through any
+ * `POST /chat/completions` endpoint that speaks OpenAI's SSE protocol —
+ * Tangle Router, OpenAI direct, OpenRouter, Groq, DeepSeek, Together. The
+ * router also fronts Anthropic models in Anthropic-native SSE shape; this
+ * backend handles both.
+ *
+ * ### Tool calls
+ *
+ * Pass `tools` (and optionally `toolChoice`) to forward an OpenAI Chat
+ * Completions `tools[]` array on every request. Streamed `tool_call` chunks
+ * are buffered until the model finalizes them (either `finish_reason:
+ * 'tool_calls'` for OpenAI shape or a `content_block_stop` for Anthropic
+ * `tool_use` blocks proxied through the router), then emitted as a single
+ * `tool_call` RuntimeStreamEvent with the assembled `args`.
+ *
+ * The backend does NOT execute tools — it surfaces calls for the caller's
+ * own dispatcher (typically the product's MCP / sandbox runtime) to fulfill
+ * and feed back as a subsequent `messages` turn. This keeps the transport
+ * thin and lets the agent host own tool dispatch policy.
+ *
+ * ### Fail-loud errors
+ *
+ * Non-success HTTP responses (4xx/5xx) and exhausted retry budgets throw
+ * `BackendTransportError` from inside the `stream()` generator. The runtime
+ * catches the throw, yields a `backend_error` with a typed `error` field
+ * (`kind`, `status`, truncated `body`) and a terminal `final` event with
+ * `status: 'failed'` carrying the same detail. Consumers MUST map
+ * `final.error` onto their `RunRecord.error` — silently treating an empty
+ * `finalText` as "agent produced nothing" hides credit exhaustion, auth
+ * failure, and upstream outages.
+ */
 declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput = AgentBackendInput>(options: {
     apiKey: string;
     baseUrl: string;
     model: string;
     kind?: string;
+    /**
+     * OpenAI Chat Completions `tools[]` definitions surfaced to the model on
+     * every request. Omit to send a tool-free request (existing behavior).
+     * The runtime makes no assumption about the dispatcher — calls stream out
+     * as `tool_call` events and the caller is responsible for executing them
+     * and feeding `tool_result` messages back on a follow-up turn.
+     */
+    tools?: ReadonlyArray<OpenAIChatTool>;
+    /**
+     * OpenAI Chat Completions `tool_choice`. Default `undefined` (request
+     * omits the field; provider falls back to its own default — typically
+     * `'auto'`).
+     */
+    toolChoice?: OpenAIChatToolChoice;
     fetchImpl?: typeof fetch;
     retry?: BackendRetryPolicy;
 }): AgentExecutionBackend<TInput>;
@@ -220,6 +268,30 @@ declare function deriveExecutionId(input: {
  * importing the runtime.
  */
 
+/**
+ * @stable
+ *
+ * A backend transport call (HTTP, gRPC, sidecar IPC) failed with a non-success
+ * status. Distinct from `JudgeError` (which is structural / unrecoverable)
+ * because backend failures are sometimes retryable and consumers may want to
+ * branch on the upstream status code.
+ */
+declare class BackendTransportError extends AgentEvalError {
+    readonly backend: string;
+    readonly status?: number;
+    /**
+     * Truncated upstream response body (≤2 KiB) when available. Diagnostic
+     * only — surfaces in `backend_error.error.body` and `final.error.body`
+     * so operators can see "free_tier_limit", "invalid_api_key", etc. without
+     * cracking the log line open.
+     */
+    readonly body?: string;
+    constructor(backend: string, message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        body?: string;
+    });
+}
 /**
  * @stable
  *
@@ -504,4 +576,4 @@ declare function readinessServerSentEvent(report: KnowledgeReadinessReport, opti
 /** @stable */
 declare function runtimeStreamServerSentEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, DEFAULT_ROUTER_BASE_URL, InMemoryRuntimeSessionStore, type ModelInfo, type ResolvedChatModel, type RouterEnv, type RunChatTurnInput, type RuntimeEventCollector, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, cleanModelId, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, decideKnowledgeReadiness, deriveExecutionId, getModels, handleChatTurn, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, validateChatModelId };
+export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, BackendTransportError, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, DEFAULT_ROUTER_BASE_URL, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, type ResolvedChatModel, type RouterEnv, type RunChatTurnInput, type RuntimeEventCollector, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, cleanModelId, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, decideKnowledgeReadiness, deriveExecutionId, getModels, handleChatTurn, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, validateChatModelId };

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   RuntimeRunStateError,
   SessionMismatchError,
   ValidationError
-} from "./chunk-RZAOYKCO.js";
+} from "./chunk-XZYF3YJN.js";
 import "./chunk-DGUM43GV.js";
 
 // src/sessions.ts
@@ -144,14 +144,19 @@ function createOpenAICompatibleBackend(options) {
     },
     async *stream(input, context) {
       const url = `${options.baseUrl.replace(/\/$/, "")}/chat/completions`;
-      const requestBody = JSON.stringify({
+      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;
+      }
+      const requestBody = JSON.stringify(bodyPayload);
       let response;
       let lastStatus = 0;
       let lastThrown;
@@ -198,14 +203,23 @@ function createOpenAICompatibleBackend(options) {
         );
       }
       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
+          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;
@@ -315,6 +329,7 @@ async function* streamResponseEvents(response, context, requestedModel) {
   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();
@@ -325,9 +340,9 @@ async function* streamResponseEvents(response, context, requestedModel) {
   buffer += decoder.decode().replace(/\r\n/g, "\n");
   for (const event of drainStreamBuffer(true)) yield event;
   if (buffer.trim()) {
-    const event = parseStreamChunk(buffer, context, usage);
-    if (event) yield event;
+    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",
@@ -350,56 +365,124 @@ async function* streamResponseEvents(response, context, requestedModel) {
       if (sseBoundary >= 0) {
         const chunk = buffer.slice(0, sseBoundary);
         buffer = buffer.slice(sseBoundary + 2);
-        const event = parseStreamChunk(chunk, context, usage);
-        if (event) yield event;
+        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);
-        const event = parseStreamChunk(line, context, usage);
-        if (event) yield event;
+        for (const event of parseStreamChunk(line, context, usage, toolCalls)) yield event;
         continue;
       }
       if (flush && buffer.trim() && !buffer.trimStart().startsWith("data:")) {
         const line = buffer;
         buffer = "";
-        const event = parseStreamChunk(line, context, usage);
-        if (event) yield event;
+        for (const event of parseStreamChunk(line, context, usage, toolCalls)) yield event;
         continue;
       }
       break;
     }
   }
 }
-function parseStreamChunk(chunk, context, usage) {
+function* parseStreamChunk(chunk, context, usage, toolCalls) {
   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;
+  if (!data || data === "[DONE]") return;
+  let parsed;
   try {
-    const parsed = JSON.parse(data);
-    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 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()
-      };
+    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);
     }
-    if (stringValue(parsed.type) === "content_block_delta") {
-      const d = parsed.delta;
+  }
+  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) {
-        return {
+        yield {
           type: "text_delta",
           task: context.task,
           session: context.session,
@@ -408,17 +491,65 @@ function parseStreamChunk(chunk, context, usage) {
         };
       }
     }
-    return mapCommonBackendEvent(parsed, context);
-  } catch {
-    return {
+  }
+  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: data,
+      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;
@@ -888,13 +1019,21 @@ async function* runAgentTaskStream(options) {
     } catch (stopErr) {
       stopErrorMessage = stopErr instanceof Error ? stopErr.message : String(stopErr);
     }
+    const combinedMessage = stopErrorMessage ? `${message}; backend stop failed: ${stopErrorMessage}` : message;
+    const errorDetail = err instanceof BackendTransportError ? {
+      kind: "transport",
+      message: combinedMessage,
+      status: err.status,
+      body: err.body
+    } : { kind: "backend", message: combinedMessage };
     const backendError = streamEvent({
       type: "backend_error",
       task,
       session,
       backend: options.backend.kind,
-      message: stopErrorMessage ? `${message}; backend stop failed: ${stopErrorMessage}` : message,
-      recoverable: !options.signal?.aborted
+      message: combinedMessage,
+      recoverable: !options.signal?.aborted,
+      error: errorDetail
     });
     await store?.appendEvent?.(session.id, backendError);
     yield backendError;
@@ -908,7 +1047,8 @@ async function* runAgentTaskStream(options) {
       session,
       status,
       reason: message,
-      text: finalText || void 0
+      text: finalText || void 0,
+      error: errorDetail
     });
     await store?.appendEvent?.(session.id, final);
     yield final;
@@ -1289,6 +1429,12 @@ function sanitizeRuntimeStreamEvent(event, options = {}) {
     };
   }
   if (event.type === "final") {
+    const sanitizedError = event.error !== void 0 ? {
+      kind: event.error.kind,
+      message: event.error.message,
+      status: event.error.status,
+      body: options.includeControlPayloads ? event.error.body : void 0
+    } : void 0;
     return {
       type: event.type,
       ...withTask,
@@ -1297,7 +1443,8 @@ function sanitizeRuntimeStreamEvent(event, options = {}) {
       status: event.status,
       reason: event.reason,
       text: options.includeControlPayloads ? event.text : void 0,
-      metadata: options.includeMetadata ? event.metadata : void 0
+      metadata: options.includeMetadata ? event.metadata : void 0,
+      ...sanitizedError !== void 0 ? { error: sanitizedError } : {}
     };
   }
   return {
@@ -1423,7 +1570,16 @@ function pickPublicStreamFields(event) {
   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 };
+    const sanitizedError = event.error !== void 0 ? {
+      kind: event.error.kind,
+      status: event.error.status
+    } : void 0;
+    return {
+      backend: event.backend,
+      message: event.message,
+      recoverable: event.recoverable,
+      ...sanitizedError !== void 0 ? { error: sanitizedError } : {}
+    };
   }
   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 };
@@ -1511,6 +1667,7 @@ function stripNewlines(value) {
 }
 export {
   AgentEvalError,
+  BackendTransportError,
   ConfigError,
   DEFAULT_ROUTER_BASE_URL,
   InMemoryRuntimeSessionStore,