@agents24/node 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,17 @@
 # `@agents24/node`
 
-Last Updated: 2026-07-19
+Last Updated: 2026-08-12
 
 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,10 @@ 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.
@@ -43,9 +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, supply an authenticated external principal through `resolvePrincipal`, and pair it with `createBffAgentClient` from `@agents24/client/bff`. The bridge uses only `client.embed`; it keeps the API key, Agent ID, and optional exact Agent version on the server. `npm create agents24-app@latest` generates the complete Hono/Vite arrangement.
+`@agents24/node/bff` exports `createAgents24BffHandler(...)`. Mount its returned Fetch handler at a same-origin path, provide an API-key client plus Agent ID, and resolve a stable customer `subject`. Supply an optional `issuer` only when an authenticated customer must receive organization-wide governance across Agents or applications. 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, and optional exact Agent version on the server; it does not use a Client Deployment. `npm create agents24-app@latest` generates the complete Hono/Vite arrangement, including an auto-generated cookie secret for its default guest session.
+
+## 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": "90a64d2df2facc3c4510edc7a0762cb86a336578667d3bc6cfeb7ae035133e00",
+  "contractHash": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
   "contractVersion": "0.2.0",
   "corpus": "conformance/v1/corpus.json",
   "generatedBy": "@agents24/sdk-contract",
@@ -15,11 +15,11 @@
       "reactDom": ">=19 <20"
     },
     "@agents24/client": {
-      "contract": "90a64d2df2facc3c4510edc7a0762cb86a336578667d3bc6cfeb7ae035133e00",
-      "runtime": "run-stream.v2"
+      "contract": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
+      "runtime": "run-stream.v3"
     },
     "@agents24/node": {
-      "contract": "90a64d2df2facc3c4510edc7a0762cb86a336578667d3bc6cfeb7ae035133e00",
+      "contract": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -27,18 +27,18 @@
       "react": ">=19 <20"
     },
     "@talmudpedia/runtime-sdk": {
-      "contract": "90a64d2df2facc3c4510edc7a0762cb86a336578667d3bc6cfeb7ae035133e00",
+      "contract": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "90a64d2df2facc3c4510edc7a0762cb86a336578667d3bc6cfeb7ae035133e00",
+      "contract": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
       "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": 60,
-    "python": 55
+    "client": 22,
+    "node": 79,
+    "python": 70
   }
 }

package/dist/bff.cjs

@@ -8,16 +8,37 @@ var crypto = require('crypto');
 var Agents24SDKError = class extends Error {
   kind;
   status;
-  details;
+  failure;
   responseHeaders;
   constructor(message, options) {
     super(message, { cause: options.cause });
     this.name = "Agents24SDKError";
     this.kind = options.kind;
     this.status = options.status;
-    this.details = options.details;
+    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
@@ -32,15 +53,98 @@ function normalizeBasePath(value) {
   if (!path.startsWith("/") || /[\r\n\0?#]/.test(path)) throw new Error("basePath must be an absolute path.");
   return path;
 }
-function publicError(status, code, message, retryable = false) {
-  return Response.json({ code, message, request_id: crypto.randomUUID(), retryable }, {
+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) {
-  if (error instanceof Agents24SDKError) {
-    const status = error.status && error.status >= 400 && error.status <= 599 ? error.status : 502;
+  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);
@@ -112,22 +216,21 @@ function sseResponse(execute, headers) {
   void execute(write).catch(async (error) => {
     const message = "The Agent stream failed.";
     const event = {
-      version: "run-stream.v2",
+      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 },
-      diagnostics: [{ message }]
+      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 selector = objectValue(raw.model_selector);
-  const selectable = Boolean(selector.selectable);
+  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 {
@@ -141,8 +244,8 @@ function bootstrapDocument(raw, agentVersionId) {
       policy_epoch: 0
     },
     authentication: { modes: ["server_embed"], access_token_lifetime_seconds: 0, jwks_path: "" },
-    capabilities: ["attachments.write", ...selectable ? ["models.select"] : []],
-    features: { models: selector },
+    capabilities: ["attachments.read", "attachments.write", "feedback.write", ...selectable ? ["models.select"] : []],
+    features,
     native_profiles: []
   };
 }
@@ -156,29 +259,50 @@ function createAgents24BffHandler(options) {
     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.externalUserId = normalized(resolution.principal.externalUserId, "externalUserId");
+      resolution.principal.subject = normalized(resolution.principal.subject, "subject");
+      if (resolution.principal.issuer !== void 0) {
+        resolution.principal.issuer = normalized(resolution.principal.issuer, "issuer");
+      }
     } catch {
       return publicError(401, "PRINCIPAL_REQUIRED", "A valid application session is required.");
     }
     const principal = resolution.principal;
-    const identity = {
-      external_user_id: principal.externalUserId,
-      ...principal.externalSessionId ? { external_session_id: principal.externalSessionId } : {}
-    };
-    const threadIdentity = {
-      externalUserId: principal.externalUserId,
-      ...principal.externalSessionId ? { externalSessionId: principal.externalSessionId } : {}
-    };
     const idempotencyKey = stringValue(request.headers.get("idempotency-key"));
     try {
+      let customerPrincipalRef = "";
+      if (!(request.method === "GET" && (path === "/bootstrap" || path === "/resource-policy"))) {
+        const entitlement = await embed.getResourcePolicy(agentId, {
+          external_user_id: principal.subject,
+          ...principal.issuer ? { external_user_issuer: principal.issuer } : {},
+          ...agentVersionId ? { agent_version_id: agentVersionId } : {}
+        });
+        customerPrincipalRef = stringValue(entitlement.customer_principal_ref) || principal.subject;
+      }
+      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 embed.getResourcePolicy(agentId, {
+          external_user_id: principal.subject,
+          ...principal.issuer ? { external_user_issuer: principal.issuer } : {},
+          ...agentVersionId ? { agent_version_id: agentVersionId } : {}
+        }));
       } else if (request.method === "POST" && path === "/chat/stream") {
         const body = await requestJson(request);
         const input = stringValue(body.input);
@@ -199,15 +323,45 @@ function createAgents24BffHandler(options) {
         });
       } 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, (event) => write(event), {
+          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));
+        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);
@@ -217,27 +371,29 @@ function createAgents24BffHandler(options) {
           limit: Number.isFinite(limit) ? limit : 20
         }));
       } else if (request.method === "GET" && path === "/threads/events") {
-        const cursor = Number(url.searchParams.get("cursor"));
+        const rawCursor = url.searchParams.get("cursor");
+        const cursor = rawCursor === null ? void 0 : Number(rawCursor);
         response = sseResponse(async (write) => {
           await embed.subscribeAgentThreadEvents(agentId, {
             ...threadIdentity,
-            ...Number.isFinite(cursor) ? { cursor } : {},
+            ...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 before = Number(url.searchParams.get("before_turn_index"));
-        const limit = Number(url.searchParams.get("limit"));
+        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,
-          ...Number.isFinite(before) ? { beforeTurnIndex: before } : {},
-          ...Number.isFinite(limit) ? { limit } : {},
-          includeRunEvents: url.searchParams.get("include_run_events") === "true"
+          ...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));
+        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);
@@ -248,6 +404,18 @@ function createAgents24BffHandler(options) {
           ...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");
@@ -258,7 +426,8 @@ function createAgents24BffHandler(options) {
           schema_version: "agents24.hitl.resume.v2",
           interrupt_id: normalized(interruptId, "interruptId"),
           action: normalized(String(body.action || ""), "action"),
-          ...stringValue(body.comment) ? { comment: stringValue(body.comment) } : {}
+          ...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);