@agents24/node 0.4.0 → 0.5.0

package/README.md

@@ -1,9 +1,11 @@
 # `@agents24/node`
 
-Last Updated: 2026-08-13
+Last Updated: 2026-08-24
 
 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.
 
+`resourcePackages.validatePackage(...)` returns the authoritative package identity, diagnostics, and `package_hash` when the package compiles successfully. Use that hash value for safe preview/import retry semantics instead of independently hashing package contents.
+
 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
@@ -31,6 +33,8 @@ 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`.
 
+For Git-owned Package V2 products, `agents24.resourcePackages.getExportability()` returns the closed machine-readable field-classification contract used by Bundle projection and pull. `agents24.resourceInstallations` includes `plan`, `planPull`, `downloadPull`, `acceptPull`, draft-only `apply`, `publish`, `get`, and related resource/discovery helpers. Pull is the reverse sync path from platform drafts into canonical local package files and verifies portable semantic equality before any write. `get(...)` exposes `latest_apply`, `latest_pull`, `last_sync_direction`, `last_synchronized_at`, `synchronized_package_hash`, divergence from the synchronized snapshot, and the latest pull summary.
+
 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.
@@ -57,7 +61,27 @@ This package is server-only. Never expose an organization API key to browser cod
 
 ## Same-origin BFF
 
-`@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 needs organization-wide governance. The bridge keeps the API key, Agent, and optional exact Agent version on the server; it does not use a Client Deployment. It can explicitly use draft runtime only with `agents.execute`; direct clients stay published-only.
+`@agents24/node/bff` exports `createAgents24BffHandler(...)`. Mount its
+returned Fetch handler at a same-origin path, provide an API-key client plus
+an `agents` array plus `conversationScope`, and resolve a stable customer
+`subject`. Supply an optional `issuer` only when an authenticated customer
+needs organization-wide governance. The bridge keeps the API key, configured
+Agents, and any optional exact Agent versions on the server; it does not use a
+Client Deployment. It can explicitly use draft runtime only with
+`agents.execute`; direct clients stay published-only.
+
+The root BFF surface is conversation-scoped and Agent-neutral: `/threads`,
+`/threads/events`, `/threads/{threadId}`, `PATCH /threads/{threadId}/runtime-selection`,
+and `DELETE /threads/{threadId}` operate across the configured Agent set.
+Run-owned routes resolve the authoritative Agent from the stored run. The same
+browser client continues to use `createBffAgentClient({ basePath })`.
+
+Subject-only BFF principals use that stable subject directly with no identity
+or Resource Policy preflight. When `issuer` is present, the BFF resolves one
+opaque organization customer principal through
+`agents24.embed.resolveCustomerPrincipal({ issuer, subject })`, caches that
+lookup with a bounded 60-second single-flight window across conversation-scoped routes,
+and fetches Resource Policy only for explicit policy/bootstrap UI needs.
 
 ## Customer Resource Policies
 

package/compatibility.json

@@ -1,6 +1,6 @@
 {
-  "contractHash": "4012be62020727eb18b7e88cdc8067dcc605e1ecbe9d5acd12c51268e351a289",
-  "contractVersion": "0.2.0",
+  "contractHash": "55fa8df5285c62edb41ce640b217eafbb17f32296ead83ae1b8d34c96d0c21f1",
+  "contractVersion": "0.3.0",
   "corpus": "conformance/v1/corpus.json",
   "generatedBy": "@agents24/sdk-contract",
   "packages": {
@@ -19,7 +19,7 @@
       "runtime": "run-stream.v3"
     },
     "@agents24/node": {
-      "contract": "4012be62020727eb18b7e88cdc8067dcc605e1ecbe9d5acd12c51268e351a289",
+      "contract": "55fa8df5285c62edb41ce640b217eafbb17f32296ead83ae1b8d34c96d0c21f1",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -31,7 +31,7 @@
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "4012be62020727eb18b7e88cdc8067dcc605e1ecbe9d5acd12c51268e351a289",
+      "contract": "55fa8df5285c62edb41ce640b217eafbb17f32296ead83ae1b8d34c96d0c21f1",
       "python": ">=3.10"
     }
   },
@@ -48,7 +48,7 @@
   "schemaVersion": "agents24.compatibility.v1",
   "targetOperationCounts": {
     "client": 22,
-    "node": 93,
-    "python": 84
+    "node": 106,
+    "python": 99
   }
 }