@tangle-network/agent-runtime 0.21.0 → 0.22.0

package/README.md

@@ -362,6 +362,94 @@ const researcherDelegate: ResearcherDelegate = async (args, ctx) => {
 createMcpServer({ researcherDelegate })
 ```
 
+## OpenAI-compat backend — tools + fail-loud errors
+
+`createOpenAICompatibleBackend` forwards an OpenAI Chat Completions
+`tools[]` array on every request when configured. Streamed tool calls
+(both OpenAI delta shape and the Anthropic `tool_use` shape proxied by
+the router) are assembled across SSE chunks and emitted as a single
+`tool_call` RuntimeStreamEvent per call. The backend does NOT execute
+tools — surfacing the call is the contract; dispatch is the caller's
+problem.
+
+```ts
+import {
+  createOpenAICompatibleBackend,
+  runAgentTaskStream,
+  type OpenAIChatTool,
+} from '@tangle-network/agent-runtime'
+
+const delegateResearch: OpenAIChatTool = {
+  type: 'function',
+  function: {
+    name: 'delegate_research',
+    description: 'Spin up a researcher loop and return a taskId.',
+    parameters: {
+      type: 'object',
+      properties: { question: { type: 'string' } },
+      required: ['question'],
+    },
+  },
+}
+
+const backend = createOpenAICompatibleBackend({
+  apiKey: process.env.TANGLE_API_KEY!,
+  baseUrl: 'https://router.tangle.tools/v1',
+  model: 'claude-sonnet-4-6',
+  tools: [delegateResearch /* + delegate_code, delegate_feedback, etc. */],
+  toolChoice: 'auto', // or 'none' | 'required' | { type: 'function', function: { name } }
+})
+
+for await (const event of runAgentTaskStream({ task, backend, input })) {
+  if (event.type === 'tool_call') {
+    // Dispatch through your MCP / sandbox runtime. `args` is JSON-parsed
+    // when the model produced a valid object, raw string otherwise.
+    const result = await dispatch(event.toolName, event.args)
+    // Feed `result` back on a follow-up turn via `input.messages`.
+  }
+}
+```
+
+Callers integrating with `agent-runtime/mcp` typically project the MCP
+server's `tools/list` response into this shape once at config time and
+pass the array as `tools`. The runtime intentionally does NOT depend on
+`@modelcontextprotocol/sdk` — keeping the backend transport thin lets
+domain repos own MCP plumbing.
+
+### Transport errors fail loud
+
+Non-success HTTP responses (4xx/5xx after retry exhaustion) and
+connection failures throw `BackendTransportError` from inside the
+`stream()` generator. `runAgentTaskStream` catches the throw and emits:
+
+- `backend_error` event with `error: { kind: 'transport', message, status, body }`
+- terminal `final` event with `status: 'failed'` carrying the same `error` detail
+
+Consumers building a `RunRecord` MUST map `final.error` onto
+`RunRecord.error`. Treating an empty `finalText` as "agent produced
+nothing" hides credit exhaustion (HTTP 402), auth failure (401),
+model-not-found (404), and upstream outages (5xx).
+
+```ts
+for await (const event of runAgentTaskStream({ task, backend, input })) {
+  run.observe(event)
+  if (event.type === 'final') {
+    run.complete({
+      status: event.status === 'completed' ? 'completed' : 'failed',
+      resultSummary: event.text ?? '',
+      error: event.error
+        ? `${event.error.kind} ${event.error.status ?? ''}: ${event.error.message}`
+        : undefined,
+    })
+  }
+}
+```
+
+The body is captured truncated to 2 KiB. By default the sanitized
+telemetry envelope surfaces `error.kind` + `error.status` but redacts
+`error.body` (it can echo user-visible text from a provider's error
+page). Opt in with `RuntimeTelemetryOptions.includeControlPayloads`.
+
 ## Error taxonomy
 
 | Error | When |
@@ -369,7 +457,7 @@ createMcpServer({ researcherDelegate })
 | `ValidationError` | Caller passed invalid arguments |
 | `ConfigError` | Required env / config missing |
 | `NotFoundError` | A named resource does not exist |
-| `BackendTransportError` | Backend HTTP / IPC call returned non-success |
+| `BackendTransportError` | Backend HTTP / IPC call returned non-success — carries `status` + truncated `body` |
 | `SessionMismatchError` | Resume requested against a different backend |
 | `RuntimeRunStateError` | `RuntimeRunHandle` lifecycle methods called out of order |
 
@@ -421,6 +509,10 @@ Runnable in [`examples/`](./examples/). Every example imports from
 - [`model-resolution/`](./examples/model-resolution/) — router catalog + fail-closed admission
 - [`agent-into-reviewer/`](./examples/agent-into-reviewer/) — pipe one runtime's stream into a reviewer agent
 - [`chat-handler/`](./examples/chat-handler/) — `handleChatTurn` (the centerpiece production pattern)
+- [`coder-loop/`](./examples/coder-loop/) — `coderProfile` + `runLoop` + `FanoutVote` (driven-loop kernel)
+- [`researcher-loop/`](./examples/researcher-loop/) — `researcherProfile` + `runLoop` + `FanoutVote` (peer dep: `@tangle-network/agent-knowledge`)
+- [`mcp-delegation/`](./examples/mcp-delegation/) — mount `agent-runtime-mcp` in a product `AgentProfile` + stdio `tools/list` smoke
+- [`fleet-delegation/`](./examples/fleet-delegation/) — `TANGLE_FLEET_ID` env flip + `createFleetWorkspaceExecutor` topology
 
 ## Tests
 

package/dist/agent.d.ts

@@ -1,6 +1,6 @@
 import * as _tangle_network_agent_eval from '@tangle-network/agent-eval';
 import { FindingSubject, TraceAnalystKindSpec, AnalystFinding } from '@tangle-network/agent-eval';
-import { R as RuntimeStreamEvent } from './types-DvJIha6w.js';
+import { R as RuntimeStreamEvent } from './types-BFgFD_sl.js';
 import { I as ImprovementAdapter, K as KnowledgeAdapter, a as RunAnalystLoopResult } from './types-D_MXrmJP.js';
 
 /**

package/dist/{chunk-EDVCVFQB.js → chunk-724Y4KHY.js}

@@ -1,6 +1,6 @@
 import {
   ValidationError
-} from "./chunk-RZAOYKCO.js";
+} from "./chunk-XZYF3YJN.js";
 
 // src/loops/drivers/refine.ts
 function createRefineDriver(options = {}) {
@@ -405,4 +405,4 @@ export {
   refineWinnerIndex,
   runLoop
 };
-//# sourceMappingURL=chunk-EDVCVFQB.js.map
+//# sourceMappingURL=chunk-724Y4KHY.js.map

package/dist/{chunk-Z5LKAYAS.js → chunk-CBQVID7G.js}

@@ -1,6 +1,6 @@
 import {
   createFanoutVoteDriver
-} from "./chunk-XLWPTPRP.js";
+} from "./chunk-URDSRUPQ.js";
 
 // src/profiles/coder.ts
 var DEFAULT_MAX_DIFF_LINES = 400;
@@ -245,4 +245,4 @@ export {
   multiHarnessCoderFanout,
   createCoderValidator
 };
-//# sourceMappingURL=chunk-Z5LKAYAS.js.map
+//# sourceMappingURL=chunk-CBQVID7G.js.map

package/dist/{chunk-4XA4TWKW.js → chunk-FTWTA6YE.js}

@@ -1,13 +1,13 @@
 import {
   runLoop
-} from "./chunk-EDVCVFQB.js";
+} from "./chunk-724Y4KHY.js";
 import {
   coderProfile,
   multiHarnessCoderFanout
-} from "./chunk-Z5LKAYAS.js";
+} from "./chunk-CBQVID7G.js";
 import {
   NotFoundError
-} from "./chunk-RZAOYKCO.js";
+} from "./chunk-XZYF3YJN.js";
 
 // src/mcp/executor.ts
 function createSiblingSandboxExecutor(options) {
@@ -1048,7 +1048,7 @@ import { createInterface } from "readline";
 import { Readable, Writable } from "stream";
 var PROTOCOL_VERSION = "2024-11-05";
 var DEFAULT_SERVER_NAME = "agent-runtime-mcp";
-var DEFAULT_SERVER_VERSION = "0.21.0";
+var DEFAULT_SERVER_VERSION = "0.22.0";
 function createMcpServer(options = {}) {
   const queue = options.queue ?? new DelegationTaskQueue();
   const feedbackStore = options.feedbackStore ?? new InMemoryFeedbackStore();
@@ -1268,4 +1268,4 @@ export {
   createMcpServer,
   createInProcessTransport
 };
-//# sourceMappingURL=chunk-4XA4TWKW.js.map
+//# sourceMappingURL=chunk-FTWTA6YE.js.map