fix(sandbox-bridge): faithful body-size limit + timeout/error status mapping (#218)

Two bridge faithfulness fixes so documented agent flows don't fail opaquely:

1. Body-size cap 256KB -> 1MB. Issue documents (plans/specs) allow a 512KB
   body (upsertIssueDocumentSchema: z.string().max(524288)). A PUT wraps that
   in a JSON envelope and a GET returns it with metadata, so the old 256KB cap
   rejected real document reads/writes with an opaque 502. 1MB covers a max
   document plus envelope; the queue protocol already base64-chunks large bodies.

2. Host-proxy error mapping. A fetch timeout or oversized response previously
   threw into the worker's generic 502 with a vague message. Now:
   - AbortSignal timeout -> 504 with a clear "did not respond within 30s; the
     request may or may not have applied, re-read state before retrying" body.
     A timeout on a mutating call is ambiguous, and an agent that can't tell a
     timeout from a failure tends to confabulate an outcome.
   - Oversized response body -> 413 (call succeeded server-side, payload too
     large to relay) instead of implying the operation failed.
   - Other unreachable errors -> 502 with the underlying message.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: stubbi

packages/adapter-utils/src/execution-target.ts

@@ -1173,22 +1173,67 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
         }
         headers.set("authorization", `Bearer ${hostApiToken}`);
         headers.set("x-paperclip-run-id", input.runId);
-        const response = await fetch(buildBridgeForwardUrl(hostApiUrl, request), {
-          method,
-          headers,
-          ...(method === "GET" || method === "HEAD" ? {} : { body: request.body }),
-          signal: AbortSignal.timeout(30_000),
-        });
+        let response: Response;
+        try {
+          response = await fetch(buildBridgeForwardUrl(hostApiUrl, request), {
+            method,
+            headers,
+            ...(method === "GET" || method === "HEAD" ? {} : { body: request.body }),
+            signal: AbortSignal.timeout(30_000),
+          });
+        } catch (error) {
+          // Map fetch failures to a faithful status the in-sandbox agent can act
+          // on, instead of letting them surface as an opaque generic 502. A
+          // timeout in particular is ambiguous on a mutating call ("did my write
+          // land?"), so it must be distinguishable — otherwise the agent tends to
+          // confabulate an outcome.
+          const name = error instanceof Error ? error.name : "";
+          if (name === "TimeoutError" || name === "AbortError") {
+            return {
+              status: 504,
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify({
+                error: "The Paperclip API did not respond within the 30s bridge timeout. The request may or may not have been applied; re-read state before retrying.",
+                code: "bridge_upstream_timeout",
+              }),
+            };
+          }
+          return {
+            status: 502,
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              error: `Bridge could not reach the Paperclip API: ${error instanceof Error ? error.message : String(error)}`,
+              code: "bridge_upstream_unreachable",
+            }),
+          };
+        }
         if (bridgeDebugEnabled) {
           await onLog(
             "stdout",
             `[paperclip] Bridge proxy response ${response.status} for ${method} ${request.path}${request.query ? `?${request.query}` : ""}\n`,
           );
         }
+        let body: string;
+        try {
+          body = await readBridgeForwardResponseBody(response, maxBodyBytes);
+        } catch (error) {
+          // Oversized response body: surface a clear 413 (not a generic 502) so
+          // the agent knows the call succeeded server-side but the payload was
+          // too large to relay, rather than assuming the operation failed.
+          return {
+            status: 413,
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              error: error instanceof Error ? error.message : String(error),
+              code: "bridge_response_too_large",
+              upstreamStatus: response.status,
+            }),
+          };
+        }
         return {
           status: response.status,
           headers: buildBridgeResponseHeaders(response),
-          body: await readBridgeForwardResponseBody(response, maxBodyBytes),
+          body,
         };
       },
     });

packages/adapter-utils/src/sandbox-callback-bridge.ts

@@ -12,7 +12,13 @@ const DEFAULT_BRIDGE_POLL_INTERVAL_MS = 100;
 const DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS = 30_000;
 const DEFAULT_BRIDGE_STOP_TIMEOUT_MS = 2_000;
 const DEFAULT_BRIDGE_MAX_QUEUE_DEPTH = 64;
-const DEFAULT_BRIDGE_MAX_BODY_BYTES = 256 * 1024;
+// Must comfortably exceed the largest legitimate request/response an in-sandbox
+// agent exchanges over the bridge. Issue documents (plans/specs) allow a 512KB
+// body (upsertIssueDocumentSchema: z.string().max(524288)); a PUT wraps that in
+// a JSON envelope and a GET returns it with metadata, so 256KB rejected real
+// document reads/writes with an opaque 502. 1MB covers a max document plus its
+// JSON envelope with margin; the queue protocol already base64-chunks large bodies.
+const DEFAULT_BRIDGE_MAX_BODY_BYTES = 1024 * 1024;
 const REMOTE_WRITE_BASE64_CHUNK_SIZE = 32 * 1024;
 const SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT = "paperclip-bridge-server.mjs";
 const SANDBOX_EXEC_CHANNEL_ENV = "PAPERCLIP_SANDBOX_EXEC_CHANNEL";