@agents24/node 0.3.0 → 0.5.0

package/README.md

@@ -1,9 +1,11 @@
 # `@agents24/node`
 
-Last Updated: 2026-08-12
+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.
@@ -46,7 +50,7 @@ Artifact source imports the transport-free declaration DSL:
 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.
+Self-hosted Node artifact servers use `@agents24/node/server`. That server subpath does not re-export the declaration DSL. Remote Artifacts and their generated Tools/Toolsets are stable unversioned live identities: trusted draft execution resolves the active managed development relay, while published execution resolves the active production binding. A run freezes that live catalog at admission; relay liveness and production drift stay live safety gates.
 `createArtifactServer` exposes manifest, health, connection-verification, and
 invocation routes. Registration uses
 `POST /.well-known/agents24/artifact/verify`; signed servers prove possession
@@ -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 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.
+`@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": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
-  "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": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
+      "contract": "55fa8df5285c62edb41ce640b217eafbb17f32296ead83ae1b8d34c96d0c21f1",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -31,7 +31,7 @@
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "a409af6996d10a8d94e0f6332c9a381c3535a9c8511314b6c42b237d7e057029",
+      "contract": "55fa8df5285c62edb41ce640b217eafbb17f32296ead83ae1b8d34c96d0c21f1",
       "python": ">=3.10"
     }
   },
@@ -48,7 +48,7 @@
   "schemaVersion": "agents24.compatibility.v1",
   "targetOperationCounts": {
     "client": 22,
-    "node": 79,
-    "python": 70
+    "node": 106,
+    "python": 99
   }
 }