@ory/cloudflare-agents 0.10.0

package/README.md

@@ -0,0 +1,37 @@
+# @ory/cloudflare-agents
+
+Ory Agent Security for the [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/).
+
+Cloudflare Agents drive tool calls through the Vercel AI SDK (`streamText({ tools })`), so
+Ory wraps each tool's `execute` — authorizing every call against Ory Permissions, tracing it,
+and propagating user → agent identity — built on [`@ory/argus`](../core).
+
+```bash
+npm install @ory/cloudflare-agents
+```
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+import { streamText } from "ai";
+import { withOry } from "@ory/cloudflare-agents";
+
+export class MyAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return streamText({
+      model: this.model,
+      messages: this.messages,
+      tools: withOry({ ...this.tools, ...this.mcp.getAITools() }), // gate every tool
+      onFinish,
+    });
+  }
+}
+```
+
+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
+[docs/sdk-integrations.md](../../docs/sdk-integrations.md).

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Ory Agent Security for the Cloudflare Agents SDK.
+ *
+ * Cloudflare Agents drive their LLM tool calls through the **Vercel AI SDK** — inside an
+ * `AIChatAgent.onChatMessage` you call `streamText({ tools })` with AI-SDK tools (and
+ * `this.mcp.getAITools()` for MCP tools). The interception point is therefore the same:
+ * wrap each tool's `execute`. {@link withOry} authorizes every call against Ory Permissions,
+ * traces it, and (on the first call) runs the Ory session gates — under the
+ * `cloudflare-agents` harness identity so the audit trail attributes Cloudflare distinctly
+ * from a plain Vercel app.
+ *
+ *   import { withOry } from "@ory/cloudflare-agents";
+ *   const result = streamText({
+ *     model, messages,
+ *     tools: withOry({ ...this.tools, ...this.mcp.getAITools() }),
+ *   });
+ *
+ * Depends only on `@ory/argus` — the `ai` / `agents` packages are not dependencies; tools are
+ * duck-typed so any version works.
+ */
+import { OryAgentClient } from "@ory/argus";
+/** A Vercel AI SDK tool (as used by Cloudflare Agents) — duck-typed. */
+export interface AiTool {
+    execute?: (input: unknown, options?: unknown) => unknown;
+    [key: string]: unknown;
+}
+export type ToolSet = Record<string, AiTool>;
+export interface WithOryOptions {
+    /** Client to use. Defaults to `OryAgentClient.fromEnv("cloudflare-agents")`. */
+    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). */
+    subjectFromOptions?: (options: unknown) => string | undefined;
+}
+/**
+ * Wrap every tool in `tools` so its `execute` is gated through Ory. Tools without an
+ * `execute` (client-side / provider-defined) are passed through untouched. Apply it to the
+ * tool map you hand to `streamText` — including `this.mcp.getAITools()`.
+ */
+export declare function withOry(tools: ToolSet, options?: WithOryOptions): ToolSet;
+export { OryAgentClient, OryDenialError } from "@ory/argus";

package/dist/index.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Ory Agent Security for the Cloudflare Agents SDK.
+ *
+ * Cloudflare Agents drive their LLM tool calls through the **Vercel AI SDK** — inside an
+ * `AIChatAgent.onChatMessage` you call `streamText({ tools })` with AI-SDK tools (and
+ * `this.mcp.getAITools()` for MCP tools). The interception point is therefore the same:
+ * wrap each tool's `execute`. {@link withOry} authorizes every call against Ory Permissions,
+ * traces it, and (on the first call) runs the Ory session gates — under the
+ * `cloudflare-agents` harness identity so the audit trail attributes Cloudflare distinctly
+ * from a plain Vercel app.
+ *
+ *   import { withOry } from "@ory/cloudflare-agents";
+ *   const result = streamText({
+ *     model, messages,
+ *     tools: withOry({ ...this.tools, ...this.mcp.getAITools() }),
+ *   });
+ *
+ * Depends only on `@ory/argus` — the `ai` / `agents` packages are not dependencies; tools are
+ * duck-typed so any version works.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OryDenialError = exports.OryAgentClient = void 0;
+exports.withOry = withOry;
+const argus_1 = require("@ory/argus");
+const HARNESS = "cloudflare-agents";
+/**
+ * Wrap every tool in `tools` so its `execute` is gated through Ory. Tools without an
+ * `execute` (client-side / provider-defined) are passed through untouched. Apply it to the
+ * tool map you hand to `streamText` — including `this.mcp.getAITools()`.
+ */
+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) {
+            client.logger.warn("session_start.failed", {
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+    const wrapped = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        if (!tool || typeof tool.execute !== "function") {
+            wrapped[name] = tool;
+            continue;
+        }
+        const originalExecute = tool.execute.bind(tool);
+        wrapped[name] = {
+            ...tool,
+            execute: async (input, callOptions) => {
+                await ensureSession();
+                const result = await (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,
+                        subjectId: result.subject,
+                        namespace: result.namespace,
+                    });
+                }
+                const output = await originalExecute(input, callOptions);
+                (0, argus_1.complete)(client, { toolName: name, output });
+                return output;
+            },
+        };
+    }
+    return wrapped;
+}
+var argus_2 = require("@ory/argus");
+Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return argus_2.OryAgentClient; } });
+Object.defineProperty(exports, "OryDenialError", { enumerable: true, get: function () { return argus_2.OryDenialError; } });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ory/cloudflare-agents",
+  "version": "0.10.0",
+  "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "keywords": [
+    "ory",
+    "cloudflare",
+    "agents",
+    "workers",
+    "authorization",
+    "agent",
+    "ai"
+  ],
+  "dependencies": {
+    "@ory/argus": "0.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "4.1.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}