@ory/openrouter-agent 0.0.0-bootstrap.0 → 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @ory/openrouter-agent
+
+Ory Agent Security for the [OpenRouter Agent SDK](https://openrouter.ai/docs/agent-sdk/overview).
+
+It authenticates each agent session, authorizes every client-side tool call against Ory
+Permissions, and records privacy-safe invocation activity through OpenRouter lifecycle hooks.
+
+```bash
+npm install @ory/openrouter-agent
+```
+
+```ts
+import { OpenRouter } from "@openrouter/agent";
+import { createOryHooks } from "@ory/openrouter-agent";
+
+const openrouter = new OpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+const result = openrouter.callModel({
+  model: "openai/gpt-5.4",
+  input: "Inspect the deployment configuration",
+  tools,
+  hooks: createOryHooks(),
+});
+
+console.log(await result.getText());
+```
+
+`createOryHooks()` returns inline `SessionStart`, `PreToolUse`, `PostToolUse`,
+`PostToolUseFailure`, and `SessionEnd` hooks. In **observe** mode (default), denies are logged
+but tools run. In **enforce** mode, a deny returns OpenRouter's native `{ block: reason }`
+result, so the client-side tool does not execute.
+
+For a multi-user service, resolve the acting user from the run's session context:
+
+```ts
+const hooks = createOryHooks({
+  subjectFromContext: ({ sessionId }) => usersBySession.get(sessionId)?.id,
+});
+```
+
+OpenRouter-hosted server tools execute remotely and do not cross the SDK's client-side
+`PreToolUse` boundary. Restrict those tools before the model request or enforce their access
+with OpenRouter-side policy. Local tools, including locally wrapped MCP tools, are gated.
+Child agents do not inherit their parent's hooks; pass `createOryHooks()` to each child run
+that should receive its own Ory session identity and tool gate.
+
+This package depends only on `@ory/argus`; its OpenRouter hook types are defined locally.
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ory Agent Security for the OpenRouter Agent SDK.
+ *
+ * Pass {@link createOryHooks} to `callModel({ hooks })`. The returned inline
+ * hooks authenticate each session, authorize every client-side tool before it
+ * executes, and record success or failure through `@ory/argus`.
+ */
+import { OryAgentClient } from "@ory/argus";
+import type { LifecycleHookContext, OryOpenRouterHooks } from "./types.js";
+export interface OryOpenRouterOptions {
+    /** Client to use. Defaults to `OryAgentClient.fromEnv("openrouter-agent")`. */
+    client?: OryAgentClient;
+    /** Override the Ory project URL for the session gates. */
+    projectUrl?: string;
+    /** Whether a denied tool is hard-blocked. Default true. */
+    canBlock?: boolean;
+    /** Resolve the acting user for a run from OpenRouter's lifecycle context. */
+    subjectFromContext?: (context: LifecycleHookContext) => string | undefined;
+}
+/** Build inline lifecycle hooks for `OpenRouter.callModel({ hooks })`. */
+export declare function createOryHooks(options?: OryOpenRouterOptions): OryOpenRouterHooks;
+export { OryAgentClient } from "@ory/argus";
+export type { HookEntry, HookHandler, LifecycleHookContext, OryOpenRouterHooks, PostToolUseFailurePayload, PostToolUsePayload, PreToolUsePayload, PreToolUseResult, SessionEndPayload, SessionStartPayload, SessionUsageTotals, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Ory Agent Security for the OpenRouter Agent SDK.
+ *
+ * Pass {@link createOryHooks} to `callModel({ hooks })`. The returned inline
+ * hooks authenticate each session, authorize every client-side tool before it
+ * executes, and record success or failure through `@ory/argus`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OryAgentClient = void 0;
+exports.createOryHooks = createOryHooks;
+const argus_1 = require("@ory/argus");
+const HARNESS = "openrouter-agent";
+/** Build inline lifecycle hooks for `OpenRouter.callModel({ hooks })`. */
+function createOryHooks(options = {}) {
+    const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
+    const canBlock = options.canBlock ?? true;
+    const sessionStarters = new Map();
+    const starterFor = (sessionId) => {
+        const existing = sessionStarters.get(sessionId);
+        if (existing)
+            return existing;
+        const starter = (0, argus_1.createSessionStarter)(client, {
+            harness: HARNESS,
+            projectUrl: options.projectUrl,
+        });
+        sessionStarters.set(sessionId, starter);
+        return starter;
+    };
+    const inContext = (context, work) => (0, argus_1.withHookContext)(client, { sessionId: context.sessionId }, () => (0, argus_1.runWithUserSubject)(options.subjectFromContext?.(context), work));
+    return {
+        SessionStart: [{
+                handler: (_payload, context) => inContext(context, () => starterFor(context.sessionId)()),
+            }],
+        PreToolUse: [{
+                handler: (payload, context) => inContext(context, async () => {
+                    await starterFor(context.sessionId)();
+                    const result = await (0, argus_1.gate)(client, {
+                        harness: HARNESS,
+                        toolName: payload.toolName,
+                        toolArgs: payload.toolInput,
+                        canBlock,
+                    });
+                    return result.kind === "deny" && result.blocked
+                        ? { block: result.denialMessage ?? "Ory: permission denied" }
+                        : undefined;
+                }),
+            }],
+        PostToolUse: [{
+                handler: (payload, context) => inContext(context, () => {
+                    (0, argus_1.complete)(client, {
+                        toolName: payload.toolName,
+                        input: payload.toolInput,
+                        output: payload.toolOutput,
+                    });
+                }),
+            }],
+        PostToolUseFailure: [{
+                handler: (payload, context) => inContext(context, () => {
+                    (0, argus_1.fail)(client, {
+                        toolName: payload.toolName,
+                        input: payload.toolInput,
+                        error: payload.error,
+                    });
+                }),
+            }],
+        SessionEnd: [{
+                handler: (_payload, context) => inContext(context, () => {
+                    sessionStarters.delete(context.sessionId);
+                }),
+            }],
+    };
+}
+var argus_2 = require("@ory/argus");
+Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return argus_2.OryAgentClient; } });

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal OpenRouter Agent SDK lifecycle-hook shapes.
+ *
+ * These mirror `@openrouter/agent` without making the SDK a runtime dependency.
+ */
+export interface LifecycleHookContext {
+    readonly signal: AbortSignal;
+    readonly hookName: string;
+    readonly sessionId: string;
+}
+export type HookHandler<Payload, Result = undefined> = (payload: Payload, context: LifecycleHookContext) => Result | void | Promise<Result | void>;
+export interface HookEntry<Payload, Result = undefined> {
+    readonly handler: HookHandler<Payload, Result>;
+    readonly matcher?: string | RegExp | ((toolName: string) => boolean);
+    readonly filter?: (payload: Payload) => boolean;
+}
+export interface SessionStartPayload {
+    readonly config?: Record<string, unknown>;
+}
+export interface ModelCallUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly cachedTokens: number;
+    readonly reasoningTokens: number;
+    readonly cost?: number;
+}
+export interface SessionUsageTotals extends ModelCallUsage {
+    readonly modelCalls: number;
+}
+export interface SessionEndPayload {
+    readonly reason: "user" | "error" | "max_turns" | "complete";
+    readonly totalUsage?: SessionUsageTotals;
+}
+export interface PreToolUsePayload {
+    readonly toolName: string;
+    readonly toolInput: Record<string, unknown>;
+}
+export interface PreToolUseResult {
+    readonly mutatedInput?: Record<string, unknown>;
+    readonly block?: boolean | string;
+}
+export interface PostToolUsePayload {
+    readonly toolName: string;
+    readonly toolInput: Record<string, unknown>;
+    readonly toolOutput: unknown;
+    readonly durationMs: number;
+}
+export interface PostToolUseFailurePayload {
+    readonly toolName: string;
+    readonly toolInput: Record<string, unknown>;
+    readonly error: unknown;
+}
+/** Inline hook configuration accepted by `callModel({ hooks })`. */
+export interface OryOpenRouterHooks {
+    readonly SessionStart: HookEntry<SessionStartPayload>[];
+    readonly PreToolUse: HookEntry<PreToolUsePayload, PreToolUseResult>[];
+    readonly PostToolUse: HookEntry<PostToolUsePayload>[];
+    readonly PostToolUseFailure: HookEntry<PostToolUseFailurePayload>[];
+    readonly SessionEnd: HookEntry<SessionEndPayload>[];
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Minimal OpenRouter Agent SDK lifecycle-hook shapes.
+ *
+ * These mirror `@openrouter/agent` without making the SDK a runtime dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1 +1,50 @@
-{"name":"@ory/openrouter-agent","version":"0.0.0-bootstrap.0","license":"Apache-2.0","description":"Bootstrap package for trusted publishing"}
+{
+  "name": "@ory/openrouter-agent",
+  "version": "1.0.0",
+  "description": "Ory Agent Security for the OpenRouter Agent SDK - per-tool authorization, activity auditing, and session identity via lifecycle hooks. Built on @ory/argus.",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "reova": {
+    "enabled": true,
+    "endpoint": "https://telemetry.reo.dev/data"
+  },
+  "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",
+    "openrouter",
+    "agent-sdk",
+    "authorization",
+    "agent",
+    "ai"
+  ],
+  "dependencies": {
+    "reova": "^0.7.0",
+    "@ory/argus": "1.0.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"
+  }
+}