@ory/cloudflare-agents 0.10.0 → 0.11.1

package/README.md

@@ -10,28 +10,74 @@ and propagating user → agent identity — built on [`@ory/argus`](../core).
 npm install @ory/cloudflare-agents
 ```
 
+## Usage on Workers
+
+The Workers runtime has no filesystem, so the shared
+`~/.config/ory-agent-plugins/config.json` that the Node integrations read and write does not
+exist there — and OAuth2 Dynamic Client Registration (which persists issued credentials to
+that file) can't be used either. Construct the `OryAgentClient` explicitly with **static
+agent credentials** from your Worker's bindings and inject it via the `client` option.
+
+Instantiate the client and the wrapped tool set **once per agent instance** (or at module
+scope), never inside `onChatMessage` — a fresh wrapper per message would re-run the Ory
+session gates on every message.
+
 ```ts
 import { AIChatAgent } from "agents/ai-chat-agent";
-import { streamText } from "ai";
-import { withOry } from "@ory/cloudflare-agents";
+import { openai } from "@ai-sdk/openai";
+import { streamText, tool } from "ai";
+import { z } from "zod";
+import { withOry, OryAgentClient } from "@ory/cloudflare-agents";
+
+const getWeather = tool({
+  description: "Get the weather for a city",
+  inputSchema: z.object({ city: z.string() }),
+  execute: async ({ city }) => `Sunny in ${city}`,
+});
 
 export class MyAgent extends AIChatAgent<Env> {
+  // One client + wrapped tool set per agent instance — not per message.
+  ory = new OryAgentClient({
+    projectUrl: this.env.ORY_PROJECT_URL,
+    apiKey: this.env.ORY_AGENT_API_KEY, // static agent credential — no DCR on Workers
+    harness: "cloudflare-agents",
+  });
+  tools = withOry({ getWeather }, { client: this.ory });
+
   async onChatMessage(onFinish) {
-    return streamText({
-      model: this.model,
+    const result = streamText({
+      model: openai("gpt-4o"),
       messages: this.messages,
-      tools: withOry({ ...this.tools, ...this.mcp.getAITools() }), // gate every tool
+      tools: this.tools,
       onFinish,
     });
+    // onChatMessage must return a Response.
+    return result.toUIMessageStreamResponse();
   }
 }
 ```
 
+To gate MCP tools too, include them where you assemble the wrapped tool map:
+`withOry({ getWeather, ...this.mcp.getAITools() }, { client: this.ory })`.
+
+In a multi-user Worker, attribute each call to the acting user with `subjectFromOptions` — a
+non-empty return value takes precedence over the client's user principal and env overrides
+for that call:
+
+```ts
+withOry(tools, {
+  client: ory,
+  subjectFromOptions: (o) => (o as { experimental_context?: { userId?: string } })?.experimental_context?.userId,
+});
+```
+
 In **enforce** mode (`ORY_PERMISSION_MODE=enforce`) a denied tool throws — the error surfaces
 to the model and the tool never runs. In **observe** mode (default) the tool runs and a
 `permission.observe_deny` span is recorded. Spans are tagged with the `cloudflare-agents`
 integration so the audit trail distinguishes Cloudflare from a plain Vercel app.
 
-Depends only on `@ory/argus` (not `ai`/`agents`); tools are duck-typed. Credentials come from
-the shared `~/.config/ory-agent-plugins/config.json`. See
+Depends only on `@ory/argus` (not `ai`/`agents`); tools are duck-typed. The package requires
+the `nodejs_compat` compatibility flag (the Agents SDK already requires it). On Node (tests,
+local dev) the default `OryAgentClient.fromEnv("cloudflare-agents")` and the shared config
+file still work; on Workers always inject an explicitly constructed client. See
 [docs/sdk-integrations.md](../../docs/sdk-integrations.md).

package/dist/index.d.ts

@@ -26,13 +26,24 @@ export interface AiTool {
 }
 export type ToolSet = Record<string, AiTool>;
 export interface WithOryOptions {
-    /** Client to use. Defaults to `OryAgentClient.fromEnv("cloudflare-agents")`. */
+    /**
+     * Client to use. Defaults to `OryAgentClient.fromEnv("cloudflare-agents")`. On the Workers
+     * runtime there is no filesystem-backed shared config, so construct an `OryAgentClient`
+     * explicitly (with static agent credentials from your Worker's env bindings) and pass it
+     * here — see the README.
+     */
     client?: OryAgentClient;
     /** Override the Ory project URL for the session gates. */
     projectUrl?: string;
     /** Whether a denied tool is hard-blocked (throws). Default true. */
     canBlock?: boolean;
-    /** Derive the permission subject from the AI SDK call options (e.g. a thread/user id). */
+    /**
+     * Derive the permission subject from the AI SDK call options (e.g. a thread/user id). A
+     * non-empty return value takes precedence over the client's user principal and env
+     * overrides for that call — this is how multi-user Workers attribute each request to its
+     * own acting user. When the function returns undefined/empty, resolution falls back to
+     * the principal / env chain.
+     */
     subjectFromOptions?: (options: unknown) => string | undefined;
 }
 /**

package/dist/index.js

@@ -32,19 +32,22 @@ const HARNESS = "cloudflare-agents";
 function withOry(tools, options = {}) {
     const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
     const canBlock = options.canBlock ?? true;
-    let sessionStarted = false;
-    const ensureSession = async () => {
-        if (sessionStarted)
-            return;
-        sessionStarted = true;
-        try {
-            await (0, argus_1.sessionStart)(client, { harness: HARNESS, projectUrl: options.projectUrl });
-        }
-        catch (err) {
+    let sessionPromise;
+    // Cache the in-flight promise (not a boolean) so concurrent first calls all
+    // await the same session start instead of racing past a still-running gate.
+    // Fail-open: a rejection is logged, never rethrown, and clears the cache so
+    // a later call can retry.
+    const ensureSession = () => {
+        sessionPromise ??= (0, argus_1.sessionStart)(client, {
+            harness: HARNESS,
+            projectUrl: options.projectUrl,
+        }).then(() => undefined, (err) => {
+            sessionPromise = undefined;
             client.logger.warn("session_start.failed", {
                 message: err instanceof Error ? err.message : String(err),
             });
-        }
+        });
+        return sessionPromise;
     };
     const wrapped = {};
     for (const [name, tool] of Object.entries(tools)) {
@@ -57,13 +60,14 @@ function withOry(tools, options = {}) {
             ...tool,
             execute: async (input, callOptions) => {
                 await ensureSession();
-                const result = await (0, argus_1.gate)(client, {
+                // A per-call subject wins over the client principal / env overrides.
+                const subjectOverride = options.subjectFromOptions?.(callOptions);
+                const result = await (0, argus_1.runWithUserSubject)(subjectOverride, () => (0, argus_1.gate)(client, {
                     harness: HARNESS,
                     toolName: name,
                     toolArgs: input,
-                    subjectFallback: options.subjectFromOptions?.(callOptions),
                     canBlock,
-                });
+                }));
                 if (result.blocked) {
                     throw new argus_1.OryDenialError({
                         tool: name,

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@ory/cloudflare-agents",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Ory Agent Security for the Cloudflare Agents SDK — per-tool authorization, tracing, and identity propagation by wrapping the AI SDK tools passed to streamText. Built on @ory/argus.",
   "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -25,7 +30,7 @@
     "ai"
   ],
   "dependencies": {
-    "@ory/argus": "0.10.0"
+    "@ory/argus": "0.11.1"
   },
   "devDependencies": {
     "typescript": "^6.0.2",