@agents24/node 0.5.7 → 0.5.9

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "contractHash": "18daf9ff1f2875f3945f292d0e188804259b35cf98eccd2662f9902e17beb42d",
+  "contractHash": "c8dfce18f633a53461f27cd14d0af66526765ad321dd98cb50d79288a6ef54f0",
   "contractVersion": "0.3.0",
   "corpus": "conformance/v1/corpus.json",
   "generatedBy": "@agents24/sdk-contract",
@@ -19,7 +19,7 @@
       "runtime": "run-stream.v3"
     },
     "@agents24/node": {
-      "contract": "18daf9ff1f2875f3945f292d0e188804259b35cf98eccd2662f9902e17beb42d",
+      "contract": "c8dfce18f633a53461f27cd14d0af66526765ad321dd98cb50d79288a6ef54f0",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -31,7 +31,7 @@
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "18daf9ff1f2875f3945f292d0e188804259b35cf98eccd2662f9902e17beb42d",
+      "contract": "c8dfce18f633a53461f27cd14d0af66526765ad321dd98cb50d79288a6ef54f0",
       "python": ">=3.10"
     }
   },
@@ -48,7 +48,7 @@
   "schemaVersion": "agents24.compatibility.v1",
   "targetOperationCounts": {
     "client": 22,
-    "node": 106,
-    "python": 99
+    "node": 107,
+    "python": 100
   }
 }

package/dist/bff.cjs

@@ -98,38 +98,59 @@ function publicError(status, code, message, retryable = false, violations) {
     headers: { "Cache-Control": "no-store", "Content-Type": "application/json; charset=utf-8" }
   });
 }
-function safeResourcePolicyError(details) {
+var FAILURE_CATEGORIES = /* @__PURE__ */ new Set([
+  "validation",
+  "authentication",
+  "authorization",
+  "not_found",
+  "policy",
+  "conflict",
+  "billing",
+  "quota",
+  "rate_limit",
+  "capacity",
+  "dependency",
+  "protocol",
+  "timeout",
+  "internal"
+]);
+var SAFE_VIOLATION_KEYS = /* @__PURE__ */ new Set([
+  "field",
+  "code",
+  "message",
+  "policy_subject_type",
+  "rule_type",
+  "aggregation_scope",
+  "resource_type",
+  "resource_name",
+  "quota_unit",
+  "quota_window",
+  "limit",
+  "remaining",
+  "resets_at"
+]);
+function safeFailure(details) {
   if (!details || typeof details !== "object" || Array.isArray(details)) return null;
   const outer = details;
   const candidate = outer.schema_version === "agents24.failure.v1" ? outer : outer.detail && typeof outer.detail === "object" && !Array.isArray(outer.detail) ? outer.detail : outer;
-  const code = typeof candidate.code === "string" ? candidate.code : "";
-  if (!["RESOURCE_POLICY_ACCESS_DENIED", "RESOURCE_POLICY_QUOTA_EXCEEDED", "RESOURCE_POLICY_CONFIGURATION_ERROR"].includes(code)) return null;
+  if (candidate.schema_version !== "agents24.failure.v1") return null;
+  const code = typeof candidate.code === "string" && /^[A-Z0-9_]{2,128}$/.test(candidate.code) ? candidate.code : "";
+  const category = typeof candidate.category === "string" && FAILURE_CATEGORIES.has(candidate.category) ? candidate.category : "";
+  if (!code || !category) return null;
   const failureId = typeof candidate.failure_id === "string" && candidate.failure_id.trim() ? candidate.failure_id : "";
   if (!failureId) return null;
-  const message = typeof candidate.message === "string" && candidate.message.trim() ? candidate.message.trim() : "The resource policy prevented this request.";
-  const allowedViolationKeys = /* @__PURE__ */ new Set([
-    "policy_subject_type",
-    "rule_type",
-    "aggregation_scope",
-    "resource_type",
-    "resource_name",
-    "quota_unit",
-    "quota_window",
-    "limit",
-    "remaining",
-    "resets_at"
-  ]);
+  const message = typeof candidate.message === "string" && candidate.message.trim() && candidate.message.length <= 1e3 ? candidate.message.trim() : "The Agent request failed.";
   const candidateDetails = candidate.details && typeof candidate.details === "object" ? candidate.details : candidate;
   const violations = Array.isArray(candidateDetails.violations) ? candidateDetails.violations.flatMap((item) => {
     if (!item || typeof item !== "object" || Array.isArray(item)) return [];
     return [Object.fromEntries(
-      Object.entries(item).filter(([key, value]) => allowedViolationKeys.has(key) && ["string", "number"].includes(typeof value))
+      Object.entries(item).filter(([key, value]) => SAFE_VIOLATION_KEYS.has(key) && ["string", "number", "boolean"].includes(typeof value))
     )];
   }).filter((item) => Object.keys(item).length > 0).slice(0, 20) : void 0;
   return {
     failureId,
     code,
-    category: code === "RESOURCE_POLICY_QUOTA_EXCEEDED" ? "quota" : "policy",
+    category,
     message,
     requestId: typeof candidate.request_id === "string" ? candidate.request_id : null,
     retryable: candidate.retryable === true,
@@ -137,7 +158,8 @@ function safeResourcePolicyError(details) {
     ...violations?.length ? { violations } : {}
   };
 }
-function resourcePolicyFailureResponse(status, failure) {
+function upstreamFailureResponse(status, failure) {
+  const candidateDetails = failure.violations?.length ? { violations: failure.violations } : {};
   return Response.json({
     schema_version: "agents24.failure.v1",
     failure_id: failure.failureId,
@@ -147,7 +169,7 @@ function resourcePolicyFailureResponse(status, failure) {
     retryable: failure.retryable,
     request_id: failure.requestId,
     retry_after_ms: failure.retryAfterMs,
-    details: failure.violations?.length ? { violations: failure.violations } : {}
+    details: candidateDetails
   }, {
     status,
     headers: { "Cache-Control": "no-store", "Content-Type": "application/json; charset=utf-8" }
@@ -158,13 +180,41 @@ function errorResponse(error) {
   if (isSdkError) {
     const sdkError = error;
     const status = sdkError.status && sdkError.status >= 400 && sdkError.status <= 599 ? sdkError.status : 502;
-    const policyError = safeResourcePolicyError(sdkError.failure);
-    if (policyError) return resourcePolicyFailureResponse(status, policyError);
+    const upstreamFailure = safeFailure(sdkError.failure);
+    if (upstreamFailure) return upstreamFailureResponse(status, upstreamFailure);
     return publicError(status, `UPSTREAM_${status}`, "The Agent request failed.", status >= 500);
   }
   return publicError(500, "BFF_REQUEST_FAILED", "The Agent request could not be completed.", true);
 }
 
+// src/bff-diagnostics.ts
+function emitDiagnostic(callback, diagnostic) {
+  void Promise.resolve(callback(diagnostic)).catch(() => void 0);
+}
+function reportFailureResponse(callback, request, operation, response) {
+  if (!callback || response.status < 400) return response;
+  void response.clone().json().then((payload) => {
+    const row = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+    const clean2 = (value, pattern) => typeof value === "string" && pattern.test(value) ? value : void 0;
+    emitDiagnostic(callback, {
+      operation,
+      method: request.method,
+      path: new URL(request.url).pathname,
+      status: response.status,
+      ...clean2(row.failure_id, /^[A-Za-z0-9_-]{1,128}$/) ? { failureId: String(row.failure_id) } : {},
+      ...clean2(row.request_id, /^[A-Za-z0-9_.:-]{1,128}$/) ? { requestId: String(row.request_id) } : {},
+      ...clean2(row.code, /^[A-Z0-9_]{2,128}$/) ? { code: String(row.code) } : {},
+      ...clean2(row.category, /^[a-z_]{2,64}$/) ? { category: String(row.category) } : {}
+    });
+  }).catch(() => emitDiagnostic(callback, {
+    operation,
+    method: request.method,
+    path: new URL(request.url).pathname,
+    status: response.status
+  }));
+  return response;
+}
+
 // src/bff.ts
 var JSON_LIMIT_BYTES = 1048576;
 var MAX_INPUT_LENGTH = 2e5;
@@ -289,7 +339,7 @@ function sseHeaders(headers) {
   result.set("X-Accel-Buffering", "no");
   return result;
 }
-function sseResponse(execute, headers, failurePayload) {
+function sseResponse(execute, headers, failurePayload, onFailure) {
   const stream = new TransformStream();
   const writer = stream.writable.getWriter();
   const encoder = new TextEncoder();
@@ -297,6 +347,7 @@ function sseResponse(execute, headers, failurePayload) {
 
 `));
   void execute(write).catch(async (error) => {
+    onFailure?.(error);
     if (failurePayload) {
       await write(failurePayload(error)).catch(() => void 0);
       return;
@@ -344,6 +395,9 @@ function createAgents24BffHandlerWithResolver(options, resolveCustomerIdentity)
   if (runtimeTarget === "draft" && agentVersionId) throw new Error("agentVersionId cannot be used with draft runtimeTarget.");
   const basePath = normalizeBasePath(options.basePath);
   const embed = options.client.embed;
+  const streamFailure = (request, operation) => (error) => {
+    reportFailureResponse(options.onDiagnostic, request, operation, errorResponse(error));
+  };
   return async (request) => {
     const url = new URL(request.url);
     if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
@@ -412,7 +466,7 @@ function createAgents24BffHandlerWithResolver(options, resolveCustomerIdentity)
             metadata: objectValue(body.metadata),
             client: objectValue(body.client)
           }, (event) => write(event), { idempotencyKey, signal: request.signal });
-        });
+        }, void 0, void 0, streamFailure(request, "chat.stream"));
       } else if (request.method === "POST" && /^\/runs\/[^/]+\/attach$/.test(path)) {
         const runId = routeId(path, /^\/runs\/([^/]+)\/attach$/, "runId");
         const body = await requestJson(request);
@@ -430,7 +484,7 @@ function createAgents24BffHandlerWithResolver(options, resolveCustomerIdentity)
             idempotencyKey,
             signal: request.signal
           });
-        });
+        }, void 0, void 0, streamFailure(request, "run.attach"));
       } else if (request.method === "POST" && /^\/runs\/[^/]+\/cancel$/.test(path)) {
         const runId = routeId(path, /^\/runs\/([^/]+)\/cancel$/, "runId");
         response = json(await embed.cancelAgentRun(agentId, runId, {
@@ -492,7 +546,7 @@ function createAgents24BffHandlerWithResolver(options, resolveCustomerIdentity)
           event: "snapshot_required",
           cursor,
           reason: "stream_failed"
-        }));
+        }), streamFailure(request, "threads.events"));
       } else if (/^\/threads\/[^/]+$/.test(path) && request.method === "GET") {
         const threadId = routeId(path, /^\/threads\/([^/]+)$/, "threadId");
         const rawBefore = url.searchParams.get("before_turn_index");
@@ -589,9 +643,9 @@ function createAgents24BffHandlerWithResolver(options, resolveCustomerIdentity)
       return mergeHeaders(response, resolution.responseHeaders);
     } catch (error) {
       if (error instanceof BffInputError) {
-        return mergeHeaders(publicError(error.status, error.code, error.message), resolution.responseHeaders);
+        return mergeHeaders(reportFailureResponse(options.onDiagnostic, request, "request", publicError(error.status, error.code, error.message)), resolution.responseHeaders);
       }
-      return mergeHeaders(errorResponse(error), resolution.responseHeaders);
+      return mergeHeaders(reportFailureResponse(options.onDiagnostic, request, "request", errorResponse(error)), resolution.responseHeaders);
     }
   };
 }
@@ -625,7 +679,8 @@ function createResolvedAgents24BffHandler(options) {
       integrationName: options.integrationName,
       basePath: `${basePath}/agents/${encodeURIComponent(agent.agentId)}`,
       resolvePrincipal: options.resolvePrincipal,
-      revokePrincipal: options.revokePrincipal
+      revokePrincipal: options.revokePrincipal,
+      onDiagnostic: options.onDiagnostic
     }, resolveCustomerIdentity)
   ]));
   const agentBySelector = /* @__PURE__ */ new Map();
@@ -748,7 +803,7 @@ function createResolvedAgents24BffHandler(options) {
             metadata: objectValue(body.metadata),
             client: objectValue(body.client)
           }, (event) => write(event), { idempotencyKey: stringValue(request.headers.get("idempotency-key")), signal: request.signal });
-        }), resolution.responseHeaders);
+        }, void 0, void 0, (error) => reportFailureResponse(options.onDiagnostic, request, "chat.stream", errorResponse(error))), resolution.responseHeaders);
       }
       if (request.method === "GET" && path === "/threads") {
         const skip = Number(url.searchParams.get("skip") || 0);
@@ -787,7 +842,7 @@ function createResolvedAgents24BffHandler(options) {
           event: "snapshot_required",
           cursor,
           reason: "stream_failed"
-        })), resolution.responseHeaders);
+        }), (error) => reportFailureResponse(options.onDiagnostic, request, "threads.events", errorResponse(error))), resolution.responseHeaders);
       }
       if (/^\/threads\/[^/]+$/.test(path) && request.method === "GET") {
         const threadId = routeId(path, /^\/threads\/([^/]+)$/, "threadId");
@@ -862,8 +917,8 @@ function createResolvedAgents24BffHandler(options) {
       }
       return mergeHeaders(publicError(404, "NOT_FOUND", "The requested BFF route does not exist."), resolution.responseHeaders);
     } catch (error) {
-      if (error instanceof BffInputError) return mergeHeaders(publicError(error.status, error.code, error.message), resolution.responseHeaders);
-      return mergeHeaders(errorResponse(error), resolution.responseHeaders);
+      if (error instanceof BffInputError) return mergeHeaders(reportFailureResponse(options.onDiagnostic, request, "request", publicError(error.status, error.code, error.message)), resolution.responseHeaders);
+      return mergeHeaders(reportFailureResponse(options.onDiagnostic, request, "request", errorResponse(error)), resolution.responseHeaders);
     }
   };
 }
@@ -883,7 +938,7 @@ function createAgents24BffHandler(options) {
       return (await resolvedHandler)(request);
     } catch (error) {
       resolvedHandler = void 0;
-      return errorResponse(error);
+      return reportFailureResponse(options.onDiagnostic, request, "agent.resolve", errorResponse(error));
     }
   };
 }