@agents24/node 0.1.0 → 0.2.1

package/README.md

@@ -1,17 +1,17 @@
 # `@agents24/node`
 
-Last Updated: 2026-07-16
+Last Updated: 2026-08-07
 
 Trusted-server Agents24 SDK for organization-authenticated control-plane, server embed, authoring, artifact, client-deployment, and client-session mint operations. It supports Node 22 and 24 with ESM and CJS entrypoints.
 
+Runtime attachment uploads return durable metadata. Use `agents.createAttachmentContentAccess(...)` for internal attachments or `embed.createAttachmentContentAccess(...)` for server-embed attachments to mint a short-lived private inline or direct-download URL.
+
 ```ts
 import { Agents24 } from "@agents24/node";
 
 const agents24 = new Agents24({
   baseUrl: process.env.AGENTS24_BASE_URL!,
   apiKey: process.env.AGENTS24_API_KEY!,
-  organizationId: process.env.AGENTS24_ORGANIZATION_ID!,
-  projectId: process.env.AGENTS24_PROJECT_ID!,
 });
 ```
 
@@ -31,6 +31,15 @@ const session = await agents24.clientSessions.createBackendSession(
 
 Administer deployments through `agents24.clientDeployments`; use `agents24.agents`, `agents24.runs`, and `agents24.embed` for trusted Agent operations. End-user token networking remains in `@agents24/client`.
 
+HITL V2 includes `respond` for Agent-requested user input. Its payload contains ordered answers with `question_id`, `selected_option_ids`, and optional `custom_text`; use the existing resume method and then reattach to the same run.
+
+Deployment administration uses reversible `lifecycle_status: "active" | "inactive"` updates and irreversible `clientDeployments.delete(...)`. Active deployments require a Resource Policy; removing it makes the deployment inactive and invalidates issued sessions. There is no `revoke()` method.
+
+New deployments follow the latest published Agent version by default. Use
+`version_policy: { mode: "pinned", version_id: "..." }` for a fixed client deployment.
+Server embed requests accept an optional `agent_version_id`; omission resolves latest published.
+Every run stores the exact resolved version, so later publications do not change historical runs.
+
 Artifact source imports the transport-free declaration DSL:
 
 ```ts
@@ -38,5 +47,18 @@ import { defineArtifact, tool } from "@agents24/node/artifacts";
 ```
 
 Self-hosted Node artifact servers use `@agents24/node/server`. That server subpath does not re-export the declaration DSL.
+`createArtifactServer` exposes manifest, health, connection-verification, and
+invocation routes. Registration uses
+`POST /.well-known/agents24/artifact/verify`; signed servers prove possession
+of the configured secret without transmitting it, while `authMode: "none"`
+servers return the matching unsigned challenge with no proof.
 
 This package is server-only. Never expose an organization API key to browser code. Persistent or native client-session enrollment requires DPoP; pass the proof as `dpopProof` in the mint request options and read a nonce challenge from `Agents24SDKError.responseHeaders`.
+
+## Same-origin BFF
+
+`@agents24/node/bff` exports `createAgents24BffHandler(...)`. Mount its returned Fetch handler at a same-origin path, provide the deployment ID, and resolve authenticated customers as `{ issuer, subject }`. Pair it with `createBffAgentClient` from `@agents24/client/bff`. The handler rejects cross-site browser requests before principal resolution, forwards durable attach cursors, and preserves caller idempotency keys for retryable mutations. The bridge keeps the API key, Agent, deployment, and optional exact Agent version on the server. `npm create agents24-app@latest` generates the complete Hono/Vite arrangement.
+
+## Customer Resource Policies
+
+`agents24.resourcePolicies` lists dashboard-authored Policy Sets and manages customer assignment, effective projection, quota schedules, and explicit resets. Raw `{ issuer, subject }` identity is sent only in request bodies. Supply `{ idempotencyKey }` to mutations. Organization keys need `resource_policies.read`, plus `resource_policies.write` for mutation methods.

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "contractHash": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+  "contractHash": "13f59fd11fc838b1f7a51afe15afcdb6f1429fed94e37a1341c97061882e57d2",
   "contractVersion": "0.2.0",
   "corpus": "conformance/v1/corpus.json",
   "generatedBy": "@agents24/sdk-contract",
@@ -15,11 +15,11 @@
       "reactDom": ">=19 <20"
     },
     "@agents24/client": {
-      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
-      "runtime": "run-stream.v2"
+      "contract": "13f59fd11fc838b1f7a51afe15afcdb6f1429fed94e37a1341c97061882e57d2",
+      "runtime": "run-stream.v3"
     },
     "@agents24/node": {
-      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "contract": "13f59fd11fc838b1f7a51afe15afcdb6f1429fed94e37a1341c97061882e57d2",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -27,18 +27,18 @@
       "react": ">=19 <20"
     },
     "@talmudpedia/runtime-sdk": {
-      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "contract": "13f59fd11fc838b1f7a51afe15afcdb6f1429fed94e37a1341c97061882e57d2",
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "contract": "13f59fd11fc838b1f7a51afe15afcdb6f1429fed94e37a1341c97061882e57d2",
       "python": ">=3.10"
     }
   },
   "protocols": {
     "runtime": {
       "minimum": "2.0.0",
-      "wire": "run-stream.v2"
+      "wire": "run-stream.v3"
     },
     "threadSummary": {
       "minimum": "1.0.0",
@@ -47,8 +47,8 @@
   },
   "schemaVersion": "agents24.compatibility.v1",
   "targetOperationCounts": {
-    "client": 19,
-    "node": 55,
-    "python": 55
+    "client": 22,
+    "node": 78,
+    "python": 69
   }
 }

package/dist/bff.cjs

@@ -0,0 +1,466 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/bff.ts
+
+// src/errors.ts
+var Agents24SDKError = class extends Error {
+  kind;
+  status;
+  failure;
+  responseHeaders;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "Agents24SDKError";
+    this.kind = options.kind;
+    this.status = options.status;
+    this.failure = options.failure;
+    this.responseHeaders = options.responseHeaders;
+  }
+  get code() {
+    return this.failure?.code;
+  }
+  get category() {
+    return this.failure?.category;
+  }
+  get failureId() {
+    return this.failure?.failure_id;
+  }
+  get requestId() {
+    return this.failure?.request_id ?? void 0;
+  }
+  get retryable() {
+    return this.failure?.retryable ?? false;
+  }
+  get retryAfterMs() {
+    return this.failure?.retry_after_ms ?? void 0;
+  }
+  get details() {
+    return this.failure?.details ?? {};
+  }
+};
+
+// src/bff.ts
+var JSON_LIMIT_BYTES = 1048576;
+function normalized(value, field) {
+  const result = String(value || "").trim();
+  if (!result || /[\r\n\0]/.test(result)) throw new Error(`${field} is required.`);
+  return result;
+}
+function normalizeBasePath(value) {
+  const path = String(value || "/api/agents24").trim().replace(/\/+$/, "");
+  if (!path.startsWith("/") || /[\r\n\0?#]/.test(path)) throw new Error("basePath must be an absolute path.");
+  return path;
+}
+function browserRequestIsSameOrigin(request) {
+  const fetchSite = String(request.headers.get("sec-fetch-site") || "").trim().toLowerCase();
+  if (fetchSite) return fetchSite === "same-origin";
+  const rawOrigin = String(request.headers.get("origin") || "").trim();
+  if (!rawOrigin) return true;
+  try {
+    return rawOrigin !== "null" && new URL(rawOrigin).origin === new URL(request.url).origin;
+  } catch {
+    return false;
+  }
+}
+function publicError(status, code, message, retryable = false, violations) {
+  const category = status === 401 ? "authentication" : status === 403 ? "authorization" : status === 404 ? "not_found" : status === 409 ? "conflict" : status === 429 ? "rate_limit" : status >= 500 ? "internal" : "validation";
+  return Response.json({
+    schema_version: "agents24.failure.v1",
+    failure_id: crypto.randomUUID(),
+    code,
+    category,
+    message,
+    request_id: crypto.randomUUID(),
+    retryable,
+    retry_after_ms: null,
+    details: {}
+  }, {
+    status,
+    headers: { "Cache-Control": "no-store", "Content-Type": "application/json; charset=utf-8" }
+  });
+}
+function safeResourcePolicyError(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;
+  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 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))
+    )];
+  }).filter((item) => Object.keys(item).length > 0).slice(0, 20) : void 0;
+  return {
+    failureId,
+    code,
+    category: code === "RESOURCE_POLICY_QUOTA_EXCEEDED" ? "quota" : "policy",
+    message,
+    requestId: typeof candidate.request_id === "string" ? candidate.request_id : null,
+    retryable: candidate.retryable === true,
+    retryAfterMs: typeof candidate.retry_after_ms === "number" && candidate.retry_after_ms >= 0 ? candidate.retry_after_ms : null,
+    ...violations?.length ? { violations } : {}
+  };
+}
+function resourcePolicyFailureResponse(status, failure) {
+  return Response.json({
+    schema_version: "agents24.failure.v1",
+    failure_id: failure.failureId,
+    code: failure.code,
+    category: failure.category,
+    message: failure.message,
+    retryable: failure.retryable,
+    request_id: failure.requestId,
+    retry_after_ms: failure.retryAfterMs,
+    details: failure.violations?.length ? { violations: failure.violations } : {}
+  }, {
+    status,
+    headers: { "Cache-Control": "no-store", "Content-Type": "application/json; charset=utf-8" }
+  });
+}
+function errorResponse(error) {
+  const isSdkError = error instanceof Agents24SDKError || error instanceof Error && error.name === "Agents24SDKError" && "kind" in error && ["protocol", "network", "http"].includes(String(error.kind));
+  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);
+    }
+    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);
+}
+function mergeHeaders(response, additional) {
+  if (!additional) return response;
+  const headers = new Headers(response.headers);
+  const extras = new Headers(additional);
+  for (const [name, value] of extras) headers.append(name, value);
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+function json(value, headers, status = 200) {
+  const responseHeaders = new Headers(headers);
+  responseHeaders.set("Cache-Control", "no-store");
+  responseHeaders.set("Content-Type", "application/json; charset=utf-8");
+  return new Response(JSON.stringify(value), { status, headers: responseHeaders });
+}
+async function requestJson(request) {
+  const contentLength = Number(request.headers.get("content-length") || 0);
+  if (contentLength > JSON_LIMIT_BYTES) throw new BffInputError(413, "REQUEST_TOO_LARGE", "The request body is too large.");
+  const value = await request.json().catch(() => null);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new BffInputError(400, "INVALID_JSON", "A JSON object is required.");
+  }
+  return value;
+}
+var BffInputError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+  status;
+  code;
+};
+function stringValue(value) {
+  const result = typeof value === "string" ? value.trim() : "";
+  return result || void 0;
+}
+function stringList(value) {
+  return Array.isArray(value) ? value.map(stringValue).filter((item) => Boolean(item)) : [];
+}
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function routeId(path, pattern, field) {
+  const match = pattern.exec(path);
+  if (!match?.[1]) throw new BffInputError(404, "NOT_FOUND", "The requested BFF route does not exist.");
+  try {
+    return normalized(decodeURIComponent(match[1]), field);
+  } catch {
+    throw new BffInputError(400, "INVALID_PATH", `${field} is invalid.`);
+  }
+}
+function sseHeaders(headers) {
+  const result = new Headers(headers);
+  result.set("Cache-Control", "no-cache, no-transform");
+  result.set("Content-Type", "text/event-stream; charset=utf-8");
+  result.set("X-Accel-Buffering", "no");
+  return result;
+}
+function sseResponse(execute, headers) {
+  const stream = new TransformStream();
+  const writer = stream.writable.getWriter();
+  const encoder = new TextEncoder();
+  const write = (value) => writer.write(encoder.encode(`data: ${JSON.stringify(value)}
+
+`));
+  void execute(write).catch(async (error) => {
+    const message = "The Agent stream failed.";
+    const event = {
+      version: "run-stream.v3",
+      seq: Number.MAX_SAFE_INTEGER,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "run.failed",
+      run_id: "bff-stream-error",
+      stage: "run",
+      payload: { error: message }
+    };
+    await write(event).catch(() => void 0);
+  }).finally(() => writer.close().catch(() => void 0));
+  return new Response(stream.readable, { headers: sseHeaders(headers) });
+}
+function bootstrapDocument(raw, agentVersionId) {
+  const features = objectValue(raw.features);
+  const selectable = objectValue(features.models).selectable === true;
+  const resolvedVersionId = stringValue(raw.agent_version_id) || agentVersionId || "";
+  const versionNumber = Number(raw.agent_version_number || 0);
+  return {
+    version: String(raw.version || "agents24.embed.bootstrap.v1"),
+    deployment: {
+      id: "server-embed",
+      name: String(raw.agent_name || "Agents24 Agent"),
+      version_policy: agentVersionId ? { mode: "pinned", version_id: agentVersionId } : { mode: "latest_published" },
+      resolved_agent_version_id: resolvedVersionId,
+      resolved_agent_version_number: Number.isFinite(versionNumber) ? versionNumber : 0,
+      policy_epoch: 0
+    },
+    authentication: { modes: ["server_embed"], access_token_lifetime_seconds: 0, jwks_path: "" },
+    capabilities: ["attachments.read", "attachments.write", "feedback.write", ...selectable ? ["models.select"] : []],
+    features,
+    native_profiles: []
+  };
+}
+function createAgents24BffHandler(options) {
+  const agentId = normalized(options.agentId, "agentId");
+  const agentVersionId = stringValue(options.agentVersionId);
+  const deploymentId = normalized(options.deploymentId, "deploymentId");
+  const basePath = normalizeBasePath(options.basePath);
+  const embed = options.client.embed;
+  return async (request) => {
+    const url = new URL(request.url);
+    if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
+      return publicError(404, "NOT_FOUND", "The requested BFF route does not exist.");
+    }
+    if (!browserRequestIsSameOrigin(request)) {
+      return publicError(403, "BFF_ORIGIN_DENIED", "The BFF accepts same-origin browser requests only.");
+    }
+    const path = url.pathname.slice(basePath.length) || "/";
+    let resolution;
+    try {
+      resolution = await options.resolvePrincipal(request);
+      resolution.principal.issuer = normalized(resolution.principal.issuer, "issuer");
+      resolution.principal.subject = normalized(resolution.principal.subject, "subject");
+    } catch {
+      return publicError(401, "PRINCIPAL_REQUIRED", "A valid application session is required.");
+    }
+    const principal = resolution.principal;
+    const idempotencyKey = stringValue(request.headers.get("idempotency-key"));
+    try {
+      let customerPrincipalRef = "";
+      if (!(request.method === "GET" && (path === "/bootstrap" || path === "/resource-policy"))) {
+        const entitlement = await options.client.resourcePolicies.getEffectiveCustomerPolicy({
+          issuer: principal.issuer,
+          subject: principal.subject,
+          deployment_id: deploymentId
+        });
+        customerPrincipalRef = normalized(
+          String(entitlement.customer_principal_ref || ""),
+          "customerPrincipalRef"
+        );
+      }
+      const identity = {
+        external_user_id: customerPrincipalRef,
+        ...principal.externalSessionId ? { external_session_id: principal.externalSessionId } : {}
+      };
+      const threadIdentity = {
+        externalUserId: customerPrincipalRef,
+        ...principal.externalSessionId ? { externalSessionId: principal.externalSessionId } : {}
+      };
+      let response;
+      if (request.method === "GET" && path === "/bootstrap") {
+        const raw = await embed.getRuntimeBootstrap(agentId, agentVersionId);
+        response = json(bootstrapDocument(raw, agentVersionId));
+      } else if (request.method === "GET" && path === "/resource-policy") {
+        response = json(await options.client.resourcePolicies.getEffectiveCustomerPolicy({
+          issuer: principal.issuer,
+          subject: principal.subject,
+          deployment_id: deploymentId
+        }));
+      } else if (request.method === "POST" && path === "/chat/stream") {
+        const body = await requestJson(request);
+        const input = stringValue(body.input);
+        const attachmentIds = stringList(body.attachmentIds);
+        if (!input && attachmentIds.length === 0) throw new BffInputError(400, "INPUT_REQUIRED", "A message or attachment is required.");
+        response = sseResponse(async (write) => {
+          await embed.streamAgent(agentId, {
+            ...identity,
+            ...agentVersionId ? { agent_version_id: agentVersionId } : {},
+            ...input ? { input } : {},
+            attachment_ids: attachmentIds,
+            ...stringValue(body.threadId) ? { thread_id: stringValue(body.threadId) } : {},
+            ...stringValue(body.requestedModelId) ? { requested_model_id: stringValue(body.requestedModelId) } : {},
+            tool_inputs: objectValue(body.toolInputs),
+            metadata: objectValue(body.metadata),
+            client: objectValue(body.client)
+          }, (event) => write(event), { idempotencyKey, signal: request.signal });
+        });
+      } else if (request.method === "POST" && /^\/runs\/[^/]+\/attach$/.test(path)) {
+        const runId = routeId(path, /^\/runs\/([^/]+)\/attach$/, "runId");
+        const body = await requestJson(request);
+        const cursor = body.cursor;
+        if (cursor !== void 0 && (!Number.isInteger(cursor) || Number(cursor) < 0)) {
+          throw new BffInputError(400, "INVALID_CURSOR", "cursor must be a non-negative integer.");
+        }
+        response = sseResponse(async (write) => {
+          await embed.attachAgentRun(agentId, runId, {
+            ...identity,
+            ...cursor === void 0 ? {} : { cursor: Number(cursor) }
+          }, (event) => write(event), {
+            idempotencyKey,
+            signal: request.signal
+          });
+        });
+      } else if (request.method === "POST" && /^\/runs\/[^/]+\/cancel$/.test(path)) {
+        const runId = routeId(path, /^\/runs\/([^/]+)\/cancel$/, "runId");
+        response = json(await embed.cancelAgentRun(agentId, runId, threadIdentity, { idempotencyKey }));
+      } else if (request.method === "PUT" && /^\/runs\/[^/]+\/feedback$/.test(path)) {
+        const runId = routeId(path, /^\/runs\/([^/]+)\/feedback$/, "runId");
+        const body = await requestJson(request);
+        const rating = body.rating === null ? null : stringValue(body.rating);
+        const reasons = /* @__PURE__ */ new Set(["incorrect", "irrelevant", "incomplete", "unsafe", "citation_issue", "other"]);
+        const reason = stringValue(body.reason);
+        const comment = stringValue(body.comment);
+        if (rating !== null && rating !== "like" && rating !== "dislike") {
+          throw new BffInputError(422, "INVALID_FEEDBACK", "rating must be like, dislike, or null.");
+        }
+        if (reason && !reasons.has(reason)) {
+          throw new BffInputError(422, "INVALID_FEEDBACK", "The feedback reason is invalid.");
+        }
+        if (comment && comment.length > 1e3) {
+          throw new BffInputError(422, "INVALID_FEEDBACK", "The feedback comment is too long.");
+        }
+        response = json(await embed.setAgentRunFeedback(agentId, runId, {
+          ...identity,
+          rating,
+          ...rating === "dislike" && reason ? { reason } : {},
+          ...rating === "dislike" && comment ? { comment } : {}
+        }));
+      } else if (request.method === "GET" && path === "/threads") {
+        const skip = Number(url.searchParams.get("skip") || 0);
+        const limit = Number(url.searchParams.get("limit") || 20);
+        response = json(await embed.listAgentThreads(agentId, {
+          ...threadIdentity,
+          skip: Number.isFinite(skip) ? skip : 0,
+          limit: Number.isFinite(limit) ? limit : 20
+        }));
+      } else if (request.method === "GET" && path === "/threads/events") {
+        const rawCursor = url.searchParams.get("cursor");
+        const cursor = rawCursor === null ? void 0 : Number(rawCursor);
+        response = sseResponse(async (write) => {
+          await embed.subscribeAgentThreadEvents(agentId, {
+            ...threadIdentity,
+            ...cursor !== void 0 && Number.isFinite(cursor) ? { cursor } : {},
+            signal: request.signal
+          }, (event) => write(event));
+        });
+      } else if (/^\/threads\/[^/]+$/.test(path) && request.method === "GET") {
+        const threadId = routeId(path, /^\/threads\/([^/]+)$/, "threadId");
+        const rawBefore = url.searchParams.get("before_turn_index");
+        const rawLimit = url.searchParams.get("limit");
+        const before = rawBefore === null ? void 0 : Number(rawBefore);
+        const limit = rawLimit === null ? void 0 : Number(rawLimit);
+        response = json(await embed.getAgentThread(agentId, threadId, {
+          ...threadIdentity,
+          ...before !== void 0 && Number.isFinite(before) ? { beforeTurnIndex: before } : {},
+          ...limit !== void 0 && Number.isFinite(limit) ? { limit } : {}
+        }));
+      } else if (/^\/threads\/[^/]+$/.test(path) && request.method === "DELETE") {
+        const threadId = routeId(path, /^\/threads\/([^/]+)$/, "threadId");
+        response = json(await embed.deleteAgentThread(agentId, threadId, threadIdentity, { idempotencyKey }));
+      } else if (request.method === "POST" && path === "/attachments/upload") {
+        const form = await request.formData();
+        const files = form.getAll("files").filter((entry) => entry instanceof File);
+        if (files.length === 0) throw new BffInputError(400, "ATTACHMENT_REQUIRED", "At least one attachment is required.");
+        response = json(await embed.uploadAgentAttachments(agentId, {
+          ...threadIdentity,
+          files,
+          ...stringValue(form.get("thread_id")) ? { threadId: stringValue(form.get("thread_id")) } : {},
+          idempotencyKey
+        }));
+      } else if (request.method === "POST" && /^\/attachments\/[^/]+\/content-access$/.test(path)) {
+        const attachmentId = routeId(path, /^\/attachments\/([^/]+)\/content-access$/, "attachmentId");
+        const body = await requestJson(request);
+        const disposition = stringValue(body.disposition);
+        if (disposition !== "inline" && disposition !== "attachment") {
+          throw new BffInputError(400, "INVALID_DISPOSITION", "Attachment disposition is invalid.");
+        }
+        response = json(await embed.createAttachmentContentAccess(agentId, attachmentId, {
+          external_user_id: threadIdentity.externalUserId,
+          ...threadIdentity.externalSessionId ? { external_session_id: threadIdentity.externalSessionId } : {},
+          disposition
+        }));
+      } else if (request.method === "POST" && /^\/runs\/[^/]+\/hitl\/[^/]+\/resume$/.test(path)) {
+        const match = /^\/runs\/([^/]+)\/hitl\/([^/]+)\/resume$/.exec(path);
+        const runId = routeId(path, /^\/runs\/([^/]+)\/hitl\//, "runId");
+        const interruptId = match?.[2] ? decodeURIComponent(match[2]) : "";
+        const body = await requestJson(request);
+        response = json(await embed.resumeAgentRun(agentId, runId, {
+          ...identity,
+          schema_version: "agents24.hitl.resume.v2",
+          interrupt_id: normalized(interruptId, "interruptId"),
+          action: normalized(String(body.action || ""), "action"),
+          ...stringValue(body.comment) ? { comment: stringValue(body.comment) } : {},
+          ...Array.isArray(body.answers) ? { answers: body.answers } : {}
+        }, { idempotencyKey }));
+      } else if (request.method === "POST" && /^\/runs\/[^/]+\/mcp\/servers\/[^/]+\/auth\/start$/.test(path)) {
+        const match = /^\/runs\/([^/]+)\/mcp\/servers\/([^/]+)\/auth\/start$/.exec(path);
+        const runId = match?.[1] ? decodeURIComponent(match[1]) : "";
+        const serverId = match?.[2] ? decodeURIComponent(match[2]) : "";
+        const body = await requestJson(request);
+        const callbackOrigin = new URL(request.url).origin;
+        response = json(await embed.startAgentRunMcpAuth(agentId, normalized(runId, "runId"), normalized(serverId, "serverId"), {
+          ...identity,
+          interrupt_id: normalized(String(body.interruptId || ""), "interruptId"),
+          callback_origin: callbackOrigin,
+          popup_nonce: normalized(String(body.popupNonce || ""), "popupNonce")
+        }, { idempotencyKey }));
+      } else if (request.method === "POST" && path === "/mcp/callback/redeem") {
+        throw new BffInputError(409, "MCP_CALLBACK_DIRECT", "Server-embed MCP callbacks complete in the authorization popup.");
+      } else if (request.method === "POST" && path === "/session/revoke") {
+        const headers = await options.revokePrincipal?.(request, principal);
+        response = new Response(null, { status: 204, ...headers ? { headers } : {} });
+      } else {
+        response = publicError(404, "NOT_FOUND", "The requested BFF route does not exist.");
+      }
+      return mergeHeaders(response, 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);
+    }
+  };
+}
+
+exports.createAgents24BffHandler = createAgents24BffHandler;
+//# sourceMappingURL=bff.cjs.map
+//# sourceMappingURL=bff.cjs.map