@agents24/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talmudpedia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# `@agents24/client`
+
+Last Updated: 2026-07-16
+
+Framework-neutral end-user runtime client for one deployment-scoped Agents24 Agent. It supports public client sessions, authenticated streaming, durable reconnect, threads, attachments, HITL, and MCP without accepting organization API keys.
+
+The root package uses structural capabilities and resolves without DOM or Node declarations. Runtime adapter subpaths provide verified global-capability bindings. The canonical wire validators and SSE parser are exported from `@agents24/client/protocol`.
+
+Persistent refresh grants require DPoP and an explicit storage adapter. `createFencedRefreshCoordinator` accepts an atomic compare-and-swap store for cross-tab refresh rotation; lease takeovers retain the server idempotency operation ID and stale owners cannot write rotated credentials. Access tokens remain memory-only.
+
+Allowlisted host headers can be carried through `chat.stream` and durable `runs.attach`; authentication, DPoP, Origin, cache, content-type, and idempotency headers remain client-owned and cannot be overridden.
+
+## Browser quickstart
+
+```ts
+import { createAnonymousSessionProvider } from "@agents24/client";
+import { createBrowserAgentClient } from "@agents24/client/browser";
+
+const baseUrl = "https://api.agents24.example";
+const deploymentId = "public-deployment-id";
+const sessionProvider = createAnonymousSessionProvider({ baseUrl, deploymentId });
+const client = createBrowserAgentClient({ baseUrl, deploymentId, sessionProvider });
+
+await client.chat.stream({ input: "Hello" }, (event) => {
+  console.log(event.seq, event.event, event.payload);
+});
+```
+
+Use `createManagedSessionProvider` when a trusted backend mints a session after authenticating the user. The backend must derive the subject from its own session and accept only deployment-registered origins/native profiles. Use `createHostedOidcSessionProvider` for hosted Authorization Code + PKCE. Organization keys, raw customer identities, tenant IDs, Agent/version choices, and fixed credential bindings never belong in client runtime requests.
+
+The client also exposes threads, thread-summary events, run attach/cancel, attachments, HITL resume, MCP authorization, refresh, and revoke. Aborting a stream detaches locally; call `client.runs.cancel` for durable cancellation.
+
+`compatibility.json` contains the exact generated contract hash, protocol versions, peers, and target operation counts. Do not infer compatibility from semver alone.
+
+## Runtime status
+
+| Runtime | Status |
+| --- | --- |
+| Browser/Vite, dedicated workers, Node 22/24 | GA candidates; promotion requires the final cross-browser and CI matrix |
+| Cloudflare Workers | Pre-beta; packed local workerd conformance passes, but the deployed Worker smoke is not yet authorized or verified |
+| Bun 1.3 and Deno 2 | Pre-beta; packed local portable matrix passes, dedicated CI must be green for promotion |
+| Service Workers | Experimental; packed termination/restart with durable cursor reattach passes, full operation coverage is pending |
+| Electron 43 renderer | Pre-beta on macOS; packaged sandbox/context isolation passes, native secure-store/session evidence is pending |
+| Tauri 2 and Expo iOS/Android | Experimental and unverified; no support claim |
+| Bare React Native/Metro | Experimental compile-only; packed iOS and Android bundles pass |
+
+Run the maintained non-UI gates with `pnpm check:bun`, `pnpm check:deno`, `pnpm check:service-worker`, `pnpm check:electron`, and `pnpm check:metro`. Every gate installs an `npm pack` artifact rather than a workspace link.

package/compatibility.json

@@ -0,0 +1,54 @@
+{
+  "contractHash": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+  "contractVersion": "0.2.0",
+  "corpus": "conformance/v1/corpus.json",
+  "generatedBy": "@agents24/sdk-contract",
+  "packages": {
+    "@agents24/ai-sdk": {
+      "ai": ">=7 <8",
+      "aiSdkReact": ">=4 <5",
+      "peer": "@agents24/client"
+    },
+    "@agents24/chat-react": {
+      "peer": "@agents24/react",
+      "react": ">=19 <20",
+      "reactDom": ">=19 <20"
+    },
+    "@agents24/client": {
+      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "runtime": "run-stream.v2"
+    },
+    "@agents24/node": {
+      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "node": "^22.0.0 || ^24.0.0"
+    },
+    "@agents24/react": {
+      "peer": "@agents24/client",
+      "react": ">=19 <20"
+    },
+    "@talmudpedia/runtime-sdk": {
+      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "protocolOwner": "@agents24/client"
+    },
+    "agents24": {
+      "contract": "de2b507f5d56de2bf7c4d6739c03617c4b4feef6ae827aaaac5f1d6150ec678e",
+      "python": ">=3.10"
+    }
+  },
+  "protocols": {
+    "runtime": {
+      "minimum": "2.0.0",
+      "wire": "run-stream.v2"
+    },
+    "threadSummary": {
+      "minimum": "1.0.0",
+      "wire": "agents24.thread_summary_event.v1"
+    }
+  },
+  "schemaVersion": "agents24.compatibility.v1",
+  "targetOperationCounts": {
+    "client": 19,
+    "node": 55,
+    "python": 55
+  }
+}

package/dist/adapters/browser.d.ts

@@ -0,0 +1,3 @@
+import type { AgentClient, Agents24ClientOptions } from "../types.js";
+export declare const runtimeAdapter: "browser";
+export declare function createBrowserAgentClient(options: Agents24ClientOptions): AgentClient;

package/dist/adapters/browser.js

@@ -0,0 +1,12 @@
+import { createAgents24Client } from '../chunk-45ITVMX3.js';
+import '../chunk-VVLMMNXI.js';
+
+// src/adapters/browser.ts
+var runtimeAdapter = "browser";
+function createBrowserAgentClient(options) {
+  return createAgents24Client(options);
+}
+
+export { createBrowserAgentClient, runtimeAdapter };
+//# sourceMappingURL=browser.js.map
+//# sourceMappingURL=browser.js.map

package/dist/adapters/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/browser.ts"],"names":[],"mappings":";;;;AAGO,IAAM,cAAA,GAAiB;AAEvB,SAAS,yBAAyB,OAAA,EAA6C;AACpF,EAAA,OAAO,qBAAqB,OAAO,CAAA;AACrC","file":"browser.js","sourcesContent":["import { createAgents24Client } from \"../client.js\";\nimport type { AgentClient, Agents24ClientOptions } from \"../types.js\";\n\nexport const runtimeAdapter = \"browser\" as const;\n\nexport function createBrowserAgentClient(options: Agents24ClientOptions): AgentClient {\n  return createAgents24Client(options);\n}\n"]}

package/dist/adapters/cloudflare.d.ts

@@ -0,0 +1,3 @@
+import type { AgentClient, Agents24ClientOptions } from "../types.js";
+export declare const runtimeAdapter: "cloudflare";
+export declare function createCloudflareAgentClient(options: Agents24ClientOptions): AgentClient;

package/dist/adapters/cloudflare.js

@@ -0,0 +1,12 @@
+import { createAgents24Client } from '../chunk-45ITVMX3.js';
+import '../chunk-VVLMMNXI.js';
+
+// src/adapters/cloudflare.ts
+var runtimeAdapter = "cloudflare";
+function createCloudflareAgentClient(options) {
+  return createAgents24Client(options);
+}
+
+export { createCloudflareAgentClient, runtimeAdapter };
+//# sourceMappingURL=cloudflare.js.map
+//# sourceMappingURL=cloudflare.js.map

package/dist/adapters/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":";;;;AAGO,IAAM,cAAA,GAAiB;AAEvB,SAAS,4BAA4B,OAAA,EAA6C;AACvF,EAAA,OAAO,qBAAqB,OAAO,CAAA;AACrC","file":"cloudflare.js","sourcesContent":["import { createAgents24Client } from \"../client.js\";\nimport type { AgentClient, Agents24ClientOptions } from \"../types.js\";\n\nexport const runtimeAdapter = \"cloudflare\" as const;\n\nexport function createCloudflareAgentClient(options: Agents24ClientOptions): AgentClient {\n  return createAgents24Client(options);\n}\n"]}

package/dist/adapters/node.d.ts

@@ -0,0 +1,3 @@
+import type { AgentClient, Agents24ClientOptions } from "../types.js";
+export declare const runtimeAdapter: "node";
+export declare function createNodeAgentClient(options: Agents24ClientOptions): AgentClient;

package/dist/adapters/node.js

@@ -0,0 +1,12 @@
+import { createAgents24Client } from '../chunk-45ITVMX3.js';
+import '../chunk-VVLMMNXI.js';
+
+// src/adapters/node.ts
+var runtimeAdapter = "node";
+function createNodeAgentClient(options) {
+  return createAgents24Client(options);
+}
+
+export { createNodeAgentClient, runtimeAdapter };
+//# sourceMappingURL=node.js.map
+//# sourceMappingURL=node.js.map

package/dist/adapters/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/node.ts"],"names":[],"mappings":";;;;AAGO,IAAM,cAAA,GAAiB;AAEvB,SAAS,sBAAsB,OAAA,EAA6C;AACjF,EAAA,OAAO,qBAAqB,OAAO,CAAA;AACrC","file":"node.js","sourcesContent":["import { createAgents24Client } from \"../client.js\";\nimport type { AgentClient, Agents24ClientOptions } from \"../types.js\";\n\nexport const runtimeAdapter = \"node\" as const;\n\nexport function createNodeAgentClient(options: Agents24ClientOptions): AgentClient {\n  return createAgents24Client(options);\n}\n"]}

package/dist/adapters/worker.d.ts

@@ -0,0 +1,3 @@
+import type { AgentClient, Agents24ClientOptions } from "../types.js";
+export declare const runtimeAdapter: "worker";
+export declare function createWorkerAgentClient(options: Agents24ClientOptions): AgentClient;

package/dist/adapters/worker.js

@@ -0,0 +1,12 @@
+import { createAgents24Client } from '../chunk-45ITVMX3.js';
+import '../chunk-VVLMMNXI.js';
+
+// src/adapters/worker.ts
+var runtimeAdapter = "worker";
+function createWorkerAgentClient(options) {
+  return createAgents24Client(options);
+}
+
+export { createWorkerAgentClient, runtimeAdapter };
+//# sourceMappingURL=worker.js.map
+//# sourceMappingURL=worker.js.map

package/dist/adapters/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/worker.ts"],"names":[],"mappings":";;;;AAGO,IAAM,cAAA,GAAiB;AAEvB,SAAS,wBAAwB,OAAA,EAA6C;AACnF,EAAA,OAAO,qBAAqB,OAAO,CAAA;AACrC","file":"worker.js","sourcesContent":["import { createAgents24Client } from \"../client.js\";\nimport type { AgentClient, Agents24ClientOptions } from \"../types.js\";\n\nexport const runtimeAdapter = \"worker\" as const;\n\nexport function createWorkerAgentClient(options: Agents24ClientOptions): AgentClient {\n  return createAgents24Client(options);\n}\n"]}

package/dist/base64url.d.ts

@@ -0,0 +1,2 @@
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function utf8Bytes(input: string): Uint8Array;

package/dist/capabilities.d.ts

@@ -0,0 +1,7 @@
+import type { Clock, FetchLike, IdProvider, TextDecoderLike, TextEncoderLike } from "./types.js";
+export declare function resolveFetch(injected?: FetchLike): FetchLike;
+export declare function resolveDecoderFactory(injected?: () => TextDecoderLike): () => TextDecoderLike;
+export declare function resolveEncoder(injected?: TextEncoderLike): TextEncoderLike;
+export declare function defaultClock(): Clock;
+export declare function defaultIds(): IdProvider;
+export declare function secureRandomBytes(length: number): Uint8Array;