@tangle-network/agent-provider-tangle 1.1.8 → 1.1.10

package/README.md

@@ -11,10 +11,16 @@ import { Sandbox } from "@tangle-network/sandbox";
 import { createTangleProvider } from "@tangle-network/agent-provider-tangle";
 
 const provider = createTangleProvider({
-  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  client: new Sandbox({
+    apiKey: process.env.TANGLE_API_KEY,
+    baseUrl: process.env.TANGLE_SANDBOX_URL || "https://sandbox.tangle.tools",
+  }),
 });
 ```
 
+`Sandbox` requires an explicit `baseUrl`.
+Set `TANGLE_SANDBOX_URL` to use another deployment.
+
 ## `create()` returns a ready environment
 
 `provider.create()` does not return until the sandbox reports `running`.
@@ -32,7 +38,10 @@ Composing an environment also reads the sandbox's deployment capability document
 
 ```ts
 const provider = createTangleProvider({
-  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  client: new Sandbox({
+    apiKey: process.env.TANGLE_API_KEY,
+    baseUrl: process.env.TANGLE_SANDBOX_URL || "https://sandbox.tangle.tools",
+  }),
   readyTimeoutMs: 180_000,
 });
 
@@ -280,7 +289,10 @@ The adapter does not trust the requested nonce, child metadata, or any legacy
 
 ```ts
 const provider = createTangleProvider({
-  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  client: new Sandbox({
+    apiKey: process.env.TANGLE_API_KEY,
+    baseUrl: process.env.TANGLE_SANDBOX_URL || "https://sandbox.tangle.tools",
+  }),
   confidentialAttestationVerifier: async ({ report, attestation }) =>
     (await verifyTangleQuote({ report, attestation })) ?? null,
 });
@@ -360,7 +372,10 @@ Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one
 
 ```ts
 const provider = createTangleProvider({
-  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  client: new Sandbox({
+    apiKey: process.env.TANGLE_API_KEY,
+    baseUrl: process.env.TANGLE_SANDBOX_URL || "https://sandbox.tangle.tools",
+  }),
   exactProcess: {},
 });
 

package/dist/tangle-prompt.d.ts

@@ -80,6 +80,13 @@ type ValidatedSandboxPromptResult = Record<string, unknown> & {
     durationMs: number;
     executionId?: string;
 };
+/**
+ * The marker left in place of a tool result's discarded tail.
+ *
+ * It names the byte counts so a reader can tell a truncated result from a tool that genuinely
+ * returned little, and so a caller can decide to re-fetch rather than reason from a partial page.
+ */
+export declare function toolOutputTruncationMarker(keptBytes: number, originalBytes: number): string;
 export declare function validatedSandboxPromptResult(result: PromptResult): ValidatedSandboxPromptResult;
 export declare function agentTurnResultFromPromptRecord(record: ValidatedSandboxPromptResult, options?: {
     contextTransferRequested?: boolean;

package/dist/tangle-prompt.js

@@ -1,4 +1,4 @@
-import { agentProfileSchema, boundedEventContentRecordSchema, AgentExactRunControlRefSchema, AgentTurnInputSchema, ContextTransferReceiptSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
+import { agentProfileSchema, CONTRACT_MAX_JSON_BYTES, boundedEventContentRecordSchema, isBoundedEventContentJson, AgentExactRunControlRefSchema, AgentTurnInputSchema, ContextTransferReceiptSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
 import { tokenUsageFromData } from "./tangle-result-values.js";
 import { assertBoundedJson, boundedString } from "./tangle-contract-safety.js";
 export function promptFromTurnInput(input) {
@@ -359,6 +359,74 @@ const SANDBOX_OPTIONAL_RESULT_FIELDS = new Set([
     "usage",
     "costUsd",
 ]);
+/**
+ * The marker left in place of a tool result's discarded tail.
+ *
+ * It names the byte counts so a reader can tell a truncated result from a tool that genuinely
+ * returned little, and so a caller can decide to re-fetch rather than reason from a partial page.
+ */
+export function toolOutputTruncationMarker(keptBytes, originalBytes) {
+    return `\n\n[truncated by the Tangle provider: kept ${keptBytes} of ${originalBytes} bytes to stay inside the ${CONTRACT_MAX_JSON_BYTES}-byte record content bound]`;
+}
+/**
+ * Shrink oversized tool output until the whole record fits the content bound.
+ *
+ * Only `toolInvocations[].result` is touched, because it is the one field that carries arbitrary
+ * fetched material rather than identity, accounting, or control state. The largest result is cut
+ * first and the loop repeats, so a record with several big results converges instead of destroying
+ * the first one it meets.
+ *
+ * Returns the record unchanged when it already fits, so the common path allocates nothing.
+ */
+function withTruncatedToolOutput(record) {
+    if (isBoundedEventContentJson(record))
+        return { record, truncated: 0 };
+    const invocations = record.toolInvocations;
+    if (!Array.isArray(invocations))
+        return { record, truncated: 0 };
+    const next = invocations.map((entry) => entry && typeof entry === "object" && !Array.isArray(entry)
+        ? { ...entry }
+        : entry);
+    const originalLengths = new Map();
+    let truncated = 0;
+    // Each pass cuts the current widest result by the record's measured overflow, so a single huge
+    // value converges immediately and several large ones shrink in turn rather than the first being
+    // destroyed. The cap is a backstop: `isBoundedEventContentJson` also enforces node, depth, and
+    // array limits that trimming a string cannot satisfy, and those must fall through to the refusal
+    // rather than spin here.
+    for (let pass = 0; pass < next.length * 4 + 8; pass += 1) {
+        const candidate = { ...record, toolInvocations: next };
+        if (isBoundedEventContentJson(candidate))
+            return { record: candidate, truncated };
+        let widest = -1;
+        let widestLength = 0;
+        for (const [index, entry] of next.entries()) {
+            const value = entry?.result;
+            if (typeof value === "string" && value.length > widestLength) {
+                widest = index;
+                widestLength = value.length;
+            }
+        }
+        // Nothing left to shrink: the overflow is elsewhere, and the caller refuses rather than
+        // silently altering a field that is not tool output.
+        if (widest < 0 || widestLength === 0)
+            return { record, truncated };
+        const entry = next[widest];
+        const current = entry.result;
+        const original = originalLengths.get(widest) ?? current.length;
+        originalLengths.set(widest, original);
+        // Cut by what the record is actually over, plus room for the marker and for JSON escaping,
+        // which can widen a byte count well past the character count.
+        const serialized = Buffer.byteLength(JSON.stringify(candidate) ?? "", "utf8");
+        const overflow = Math.max(0, serialized - CONTRACT_MAX_JSON_BYTES);
+        const marker = toolOutputTruncationMarker(0, original).length;
+        const cut = Math.max(1, overflow + marker + 1024);
+        const kept = Math.max(0, current.length - cut);
+        entry.result = current.slice(0, kept) + toolOutputTruncationMarker(kept, original);
+        truncated += 1;
+    }
+    return { record, truncated };
+}
 export function validatedSandboxPromptResult(result) {
     if (!result || typeof result !== "object" || Array.isArray(result)) {
         throw new Error("Tangle prompt returned no result object");
@@ -371,13 +439,54 @@ export function validatedSandboxPromptResult(result) {
     // The Sandbox SDK materializes absent optional response fields as
     // `undefined`. They were absent on the JSON wire and must stay absent in the
     // provider-neutral result before the strict JSON check runs.
-    const record = Object.fromEntries(Object.entries(source).filter(([field, value]) => value !== undefined || !SANDBOX_OPTIONAL_RESULT_FIELDS.has(field)));
-    const content = boundedEventContentRecordSchema.safeParse(record);
+    let record = Object.fromEntries(Object.entries(source).filter(([field, value]) => value !== undefined || !SANDBOX_OPTIONAL_RESULT_FIELDS.has(field)));
+    // Oversized tool output is TRUNCATED, never thrown.
+    //
+    // This validator runs inside the terminal result read — after the live stream has drained and
+    // after the usage receipt has been credited — so a throw here cannot prevent the work or the
+    // charge. It can only discard a finished, fully paid turn, which a supervisor then reports as a
+    // child that did nothing at all. That failure mode cost one Discovery Lab 143 of 199 children
+    // across 16 pursuits, and its six-stage sourcing graph blocked in 24 of 24 invocations.
+    //
+    // Widening the bound alone does not remove it. The Sandbox SDK serializes each tool value up to
+    // MAX_SERIALIZED_TOOL_VALUE_BYTES (4 MiB) while this bound is CONTRACT_MAX_JSON_BYTES (1 MiB)
+    // across the WHOLE record, so a single 2 MiB fetch still dies, and so do two 0.6 MiB fetches
+    // together. Any bound that throws on this path is one large page away from discarding a paid
+    // turn again.
+    //
+    // So the bound is enforced by replacing what does not fit, and saying so in the record. The
+    // caller still receives the turn, its response text, its usage, and every tool call it made;
+    // what it loses is the tail of an oversized tool result, marked where it was cut. Only tool
+    // output is truncatable: every other field is identity, accounting, or control material where a
+    // silently shortened value would be worse than a refusal, so those still refuse below.
+    const bounded = withTruncatedToolOutput(record);
+    const content = boundedEventContentRecordSchema.safeParse(bounded.record);
     if (!content.success) {
         throw new Error("Tangle prompt result exceeded its JSON bound", { cause: content.error });
     }
-    // Response text is content; all other fields retain their metadata limits.
-    assertBoundedJson(Object.fromEntries(Object.entries(record).filter(([field]) => field !== "response" && field !== "text" && field !== "finalText")));
+    record = bounded.record;
+    // What the agent produced is content and is bounded as content by the check above; the fields
+    // that describe the turn keep their metadata limits.
+    //
+    // `toolInvocations` belongs with the response text, not with the metadata. It carries whatever a
+    // tool returned, and one `webfetch` of a paper or an API page is routinely tens or hundreds of
+    // kilobytes, while the metadata bound is CONTRACT_MAX_STRING_LENGTH — 16,384 characters per
+    // string. `isBoundedEventContentJson` was written for exactly this material ("content may contain
+    // a single large transcript or tool result") and the whole record has already passed it at
+    // CONTRACT_MAX_JSON_BYTES.
+    //
+    // Holding tool output to the metadata bound rejected a turn the Sandbox SDK had already accepted:
+    // it serializes each tool value up to MAX_SERIALIZED_TOOL_VALUE_BYTES (4 MiB), a 256x mismatch.
+    // Because this validator runs inside the terminal result read, AFTER the live stream has drained
+    // and the usage receipt has been credited, the rejection did not fail the tool call — it
+    // converted a finished, fully paid turn into an unreconcilable retained execution that a
+    // supervisor reports as a child that did no work at all. Measured 2026-09-11 in one Discovery Lab
+    // worktree: 143 of 199 children across 16 pursuits, every one at `iterations: 0`, and the
+    // enumerate and extract stages that fetch papers were the ones that died.
+    assertBoundedJson(Object.fromEntries(Object.entries(record).filter(([field]) => field !== "response" &&
+        field !== "text" &&
+        field !== "finalText" &&
+        field !== "toolInvocations")));
     if (typeof record.success !== "boolean") {
         throw new Error("Tangle prompt result omitted its success status");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",