@ory/argus 0.9.0 → 0.10.0

package/dist/adapters.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared adapter primitives for Agent SDK integrations (and harness plugins).
+ *
+ * These extract the session-start sequencing and the `tool.invoke` / `tool.block` /
+ * `tool.complete` span boilerplate that each integration would otherwise re-implement, so
+ * an SDK binding is a thin translation between the SDK's hook signature and these calls.
+ * They are the TypeScript twin of `ory_argus.adapters` in the Python core.
+ *
+ *   - {@link sessionStart} — run the user + agent auth gates and write the user→agent
+ *     delegation tuple; returns whether the session may proceed.
+ *   - {@link gate} — resolve the subject, run {@link gateToolCall}, record the spans, and
+ *     return a normalized {@link GateResult}.
+ *   - {@link complete} — record the `tool.complete` span.
+ *   - {@link registerSubagent} — resolve a sub-agent identity + agent→subagent tuple.
+ *   - {@link wrapTool} — wrap a plain `execute(args)` with gate+complete, for SDKs whose
+ *     only veto point is the tool boundary (Vercel AI SDK, etc.).
+ *
+ * Every primitive is best-effort and fail-open.
+ */
+import type { OryAgentClient } from "./client.js";
+import { ensureAgentIdentity, ensureSubAgentIdentity } from "./agent-auth.js";
+import { ensureUserAuthenticated } from "./user-login.js";
+import { type PermissionDecision } from "./permissions.js";
+export declare function resolveNamespace(): string;
+export interface SessionStartResult {
+    proceed: boolean;
+    userMode: string;
+    userReason: string;
+    agentKind: string;
+}
+export interface SessionStartOptions {
+    harness: string;
+    allowBlock?: boolean;
+    projectUrl?: string;
+    binName?: string;
+    /** Injectable gates (tests). */
+    userLogin?: typeof ensureUserAuthenticated;
+    agentGate?: typeof ensureAgentIdentity;
+}
+/**
+ * Run both auth gates and write the user→agent delegation tuple. `allowBlock` is advisory
+ * for in-process SDK integrations (the agent can't be prevented from constructing), but the
+ * user gate still runs, refreshes tokens, and records the `user.auth` span.
+ */
+export declare function sessionStart(client: OryAgentClient, opts: SessionStartOptions): Promise<SessionStartResult>;
+export interface RegisterSubagentOptions {
+    harness: string;
+    subAgentType: string;
+    projectUrl?: string;
+    subAgentGate?: typeof ensureSubAgentIdentity;
+}
+export declare function registerSubagent(client: OryAgentClient, opts: RegisterSubagentOptions): Promise<void>;
+export interface GateResult {
+    /** False only when the tool was hard-denied in enforce mode. */
+    proceed: boolean;
+    /** True only for that deny (and only when `canBlock`). */
+    blocked: boolean;
+    /** Discriminator: allow / observe / deny / fail_open / interactive / audit_only. */
+    kind: string;
+    decision: ToolGateOutcomeLike;
+    subject: string;
+    namespace: string;
+    denialMessage?: string;
+}
+type ToolGateOutcomeLike = {
+    kind: "audit_only";
+    spanAttributes: Record<string, unknown>;
+} | {
+    kind: "interactive";
+    spanAttributes: Record<string, unknown>;
+} | PermissionDecision;
+export interface GateOptions {
+    harness: string;
+    toolName: string;
+    toolArgs?: unknown;
+    subjectFallback?: string;
+    /** Whether the calling integration can actually stop the tool. */
+    canBlock?: boolean;
+    extraSpanAttributes?: Record<string, unknown>;
+}
+/**
+ * Authorize a tool call, record the spans, and return a normalized {@link GateResult}.
+ * Records `tool.invoke` on allow/observe and `tool.block` on deny/observe — identical span
+ * semantics to the harness plugins.
+ */
+export declare function gate(client: OryAgentClient, opts: GateOptions): Promise<GateResult>;
+export declare function complete(client: OryAgentClient, opts: {
+    toolName: string;
+    output?: unknown;
+    extraSpanAttributes?: Record<string, unknown>;
+    status?: "ok" | "error";
+}): void;
+export interface WrapToolOptions {
+    harness: string;
+    toolName: string;
+    canBlock?: boolean;
+}
+/**
+ * Wrap a plain `execute(args)` callable with gate + complete. On a hard deny it throws
+ * {@link OryDenialError} (the veto mechanism for tool-boundary SDKs like Vercel AI SDK);
+ * otherwise the tool runs and `tool.complete` is recorded.
+ */
+export declare function wrapTool<A, R>(client: OryAgentClient, opts: WrapToolOptions, execute: (args: A) => R | Promise<R>): (args: A) => Promise<R>;
+export {};

package/dist/adapters.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Shared adapter primitives for Agent SDK integrations (and harness plugins).
+ *
+ * These extract the session-start sequencing and the `tool.invoke` / `tool.block` /
+ * `tool.complete` span boilerplate that each integration would otherwise re-implement, so
+ * an SDK binding is a thin translation between the SDK's hook signature and these calls.
+ * They are the TypeScript twin of `ory_argus.adapters` in the Python core.
+ *
+ *   - {@link sessionStart} — run the user + agent auth gates and write the user→agent
+ *     delegation tuple; returns whether the session may proceed.
+ *   - {@link gate} — resolve the subject, run {@link gateToolCall}, record the spans, and
+ *     return a normalized {@link GateResult}.
+ *   - {@link complete} — record the `tool.complete` span.
+ *   - {@link registerSubagent} — resolve a sub-agent identity + agent→subagent tuple.
+ *   - {@link wrapTool} — wrap a plain `execute(args)` with gate+complete, for SDKs whose
+ *     only veto point is the tool boundary (Vercel AI SDK, etc.).
+ *
+ * Every primitive is best-effort and fail-open.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNamespace = resolveNamespace;
+exports.sessionStart = sessionStart;
+exports.registerSubagent = registerSubagent;
+exports.gate = gate;
+exports.complete = complete;
+exports.wrapTool = wrapTool;
+const config_js_1 = require("./config.js");
+const agent_auth_js_1 = require("./agent-auth.js");
+const user_login_js_1 = require("./user-login.js");
+const permissions_js_1 = require("./permissions.js");
+const subject_js_1 = require("./subject.js");
+const denial_js_1 = require("./denial.js");
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+/**
+ * Run both auth gates and write the user→agent delegation tuple. `allowBlock` is advisory
+ * for in-process SDK integrations (the agent can't be prevented from constructing), but the
+ * user gate still runs, refreshes tokens, and records the `user.auth` span.
+ */
+async function sessionStart(client, opts) {
+    const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
+    const userLogin = opts.userLogin ?? user_login_js_1.ensureUserAuthenticated;
+    const agentGate = opts.agentGate ?? agent_auth_js_1.ensureAgentIdentity;
+    const decision = await userLogin(client, {
+        binName: opts.binName ?? `ory-${opts.harness}`,
+        harness: opts.harness,
+        allowBlock: opts.allowBlock ?? false,
+    });
+    const creds = await agentGate(client, {
+        projectUrl,
+        harness: opts.harness,
+    });
+    await recordUserDelegatesAgent(client);
+    return {
+        proceed: decision.proceed,
+        userMode: decision.mode,
+        userReason: decision.reason,
+        agentKind: creds.kind,
+    };
+}
+async function recordUserDelegatesAgent(client) {
+    const user = client.userPrincipal.subject;
+    const agent = client.agentPrincipal.subject;
+    if (!user || !agent)
+        return;
+    try {
+        await client.createRelationship({
+            namespace: resolveNamespace(),
+            object: `agent:${agent}`,
+            relation: "delegate",
+            subjectId: `user:${user}`,
+        }, { spanAttributes: { delegation: "user-to-agent" } });
+    }
+    catch (err) {
+        client.logger.warn("delegation.user_to_agent.failed", {
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function registerSubagent(client, opts) {
+    const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
+    const subAgentGate = opts.subAgentGate ?? agent_auth_js_1.ensureSubAgentIdentity;
+    let identity;
+    try {
+        identity = await subAgentGate(client, {
+            subAgentType: opts.subAgentType,
+            projectUrl,
+            harness: opts.harness,
+        });
+    }
+    catch (err) {
+        client.logger.warn("subagent.identity.failed", {
+            subAgentType: opts.subAgentType,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    if (identity.kind !== "dynamic" || !identity.subject)
+        return;
+    const agent = client.agentPrincipal.subject;
+    if (!agent)
+        return;
+    try {
+        await client.createRelationship({
+            namespace: resolveNamespace(),
+            object: `subagent:${identity.subject}`,
+            relation: "delegate",
+            subjectId: `agent:${agent}`,
+        }, { spanAttributes: { delegation: "agent-to-subagent", subAgentType: opts.subAgentType } });
+    }
+    catch (err) {
+        client.logger.warn("delegation.agent_to_subagent.failed", {
+            subAgentType: opts.subAgentType,
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Authorize a tool call, record the spans, and return a normalized {@link GateResult}.
+ * Records `tool.invoke` on allow/observe and `tool.block` on deny/observe — identical span
+ * semantics to the harness plugins.
+ */
+async function gate(client, opts) {
+    const namespace = resolveNamespace();
+    const subjectRef = (0, subject_js_1.resolveUserSubject)(client, opts.subjectFallback);
+    const label = (0, subject_js_1.subjectLabel)(subjectRef);
+    const canBlock = opts.canBlock ?? true;
+    const spanAttrs = { toolName: opts.toolName, ...(opts.extraSpanAttributes ?? {}) };
+    const outcome = await (0, permissions_js_1.gateToolCall)(client, {
+        harness: opts.harness,
+        toolName: opts.toolName,
+        check: { namespace, object: opts.toolName, relation: "use", ...subjectRef },
+        spanAttributes: spanAttrs,
+    });
+    if (outcome.kind === "audit_only") {
+        // Kill switch: Ory is disabled. Audit the invocation, skip the check.
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { ...spanAttrs, auditOnly: true },
+        });
+        return { proceed: true, blocked: false, kind: "audit_only", decision: outcome, subject: label, namespace };
+    }
+    if (outcome.kind === "interactive") {
+        return { proceed: true, blocked: false, kind: "interactive", decision: outcome, subject: label, namespace };
+    }
+    const decisionAttrs = outcome.spanAttributes;
+    if (outcome.kind === "fail_open") {
+        client.logger.warn("permission.fail_open", { tool: opts.toolName, code: outcome.error.code });
+        return { proceed: true, blocked: false, kind: "fail_open", decision: outcome, subject: label, namespace };
+    }
+    if (outcome.kind === "allow") {
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { ...spanAttrs, ...decisionAttrs, allowed: true },
+        });
+        return { proceed: true, blocked: false, kind: "allow", decision: outcome, subject: label, namespace };
+    }
+    if (outcome.kind === "observe") {
+        client.tracer.record("tool.block", "denied", {
+            attributes: { ...spanAttrs, ...decisionAttrs, allowed: false, ...(0, denial_js_1.alertAttributes)(false) },
+        });
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { ...spanAttrs, ...decisionAttrs, allowed: false, observed: true },
+        });
+        return { proceed: true, blocked: false, kind: "observe", decision: outcome, subject: label, namespace };
+    }
+    // deny
+    client.tracer.record("tool.block", "denied", {
+        attributes: { ...spanAttrs, ...decisionAttrs, allowed: false, ...(0, denial_js_1.alertAttributes)(canBlock) },
+    });
+    const denialMessage = (0, denial_js_1.formatDenialMessage)({ tool: opts.toolName, subjectId: label, namespace });
+    client.logger.warn("tool.denied", { tool: opts.toolName, subjectId: label });
+    return { proceed: false, blocked: canBlock, kind: "deny", decision: outcome, subject: label, namespace, denialMessage };
+}
+function complete(client, opts) {
+    const attributes = { toolName: opts.toolName, ...(opts.extraSpanAttributes ?? {}) };
+    if (opts.output !== undefined)
+        attributes.hasOutput = true;
+    client.tracer.record("tool.complete", opts.status ?? "ok", { attributes });
+}
+/**
+ * Wrap a plain `execute(args)` callable with gate + complete. On a hard deny it throws
+ * {@link OryDenialError} (the veto mechanism for tool-boundary SDKs like Vercel AI SDK);
+ * otherwise the tool runs and `tool.complete` is recorded.
+ */
+function wrapTool(client, opts, execute) {
+    return async (args) => {
+        const result = await gate(client, {
+            harness: opts.harness,
+            toolName: opts.toolName,
+            toolArgs: args,
+            canBlock: opts.canBlock ?? true,
+        });
+        if (result.blocked) {
+            throw new denial_js_1.OryDenialError({ tool: opts.toolName, subjectId: result.subject, namespace: result.namespace });
+        }
+        const output = await execute(args);
+        complete(client, { toolName: opts.toolName, output });
+        return output;
+    };
+}

package/dist/agent-auth.js

@@ -384,6 +384,19 @@ async function fetchClientCredentialsToken(args) {
  * the agent identity was available for the session.
  */
 async function ensureAgentIdentity(client, options = {}) {
+    // Kill switch: audit-only mode disables Ory entirely — no agent auth,
+    // mirroring the user gate's audit_only short-circuit.
+    if ((0, config_js_1.resolveConfig)().auditOnly) {
+        const creds = {
+            kind: "none",
+            reason: "Configured for audit-only mode; agent identity is a no-op",
+            warnings: [],
+        };
+        client.tracer.record("agent.auth", "skipped", {
+            attributes: { kind: creds.kind, reason: creds.reason, auditOnly: true },
+        });
+        return creds;
+    }
     const resolveFn = options.resolveFn ?? resolveAgentCredentials;
     let creds;
     try {

package/dist/contract-suite.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared contract suite for harness plugin tests.
+ *
+ * Every harness plugin translates the same core decisions (session gates,
+ * `gateToolCall`, audit-only) onto its own native signals (exit codes,
+ * `{ decision: "block" }`, `{ block: true }`, thrown errors, …). The
+ * *decision semantics* are core-owned and tested once in `packages/core`;
+ * what varies per harness is only the translation. This suite re-runs the
+ * canonical scenario tables through a harness's real entry point via a
+ * small adapter, so a plugin cannot ship with a divergent understanding of
+ * observe / enforce / fail-open / audit-only — without each plugin
+ * re-transcribing the tables.
+ *
+ * A harness test file calls:
+ *
+ * ```ts
+ * runHarnessContractSuite({
+ *   harness: "claude-code",
+ *   tool: "Bash",
+ *   sessionCanBlock: true,
+ *   sessionStart: async ({ client, gates }) => {
+ *     const out = await handleHookEvent(sessionInput(), client, gates);
+ *     return { blocked: out.decision === "block", reason: out.reason };
+ *   },
+ *   toolBefore: async ({ client, gates }, tool) => { ... },
+ * });
+ * ```
+ *
+ * and then adds only its genuinely harness-specific tests: export shape,
+ * event-name dispatch, block-signal details, input parsing (MCP names,
+ * `subagent_type`), unique span enrichment, and the install CLI.
+ */
+import { OryAgentClient } from "./client.js";
+import type { ensureUserAuthenticated } from "./user-login.js";
+import type { ensureAgentIdentity, ensureSubAgentIdentity } from "./agent-auth.js";
+/** Normalized outcome of driving one lifecycle phase through the plugin. */
+export interface ContractOutcome {
+    /** True when the plugin emitted its native block signal. */
+    blocked: boolean;
+    /** The human-readable reason carried by the block signal, if any. */
+    reason?: string;
+}
+/**
+ * Injectable auth gates handed to the plugin under test. The suite swaps
+ * their behavior per scenario; the adapter forwards them into the plugin's
+ * `deps` parameter (every plugin exposes `userLogin` / `agentGate` /
+ * `subAgentGate` injection points per AGENTS.md Step 5).
+ */
+export interface ContractGates {
+    userLogin: typeof ensureUserAuthenticated;
+    agentGate: typeof ensureAgentIdentity;
+    subAgentGate: typeof ensureSubAgentIdentity;
+}
+export interface ContractContext {
+    client: OryAgentClient;
+    gates: ContractGates;
+}
+export interface HarnessContractAdapter {
+    /** Harness name — used for the describe label and the client. */
+    harness: string;
+    /** A real, non-interactive tool from this harness's catalog. */
+    tool: string;
+    /**
+     * Whether the harness's session-start primitive can carry a hard block
+     * (subprocess exit-code harnesses: true; in-process advisory: false).
+     */
+    sessionCanBlock: boolean;
+    /** Whether the tool gate can hard-block. Defaults to true. */
+    toolCanBlock?: boolean;
+    /** Set false when the plugin has no legacy OAuth2-token session path. */
+    legacyOAuth2?: boolean;
+    /** Drive the session-start phase through the plugin's real entry point. */
+    sessionStart(ctx: ContractContext): Promise<ContractOutcome>;
+    /** Drive the pre-tool gate for `tool` through the plugin's real entry point. */
+    toolBefore(ctx: ContractContext, tool: string): Promise<ContractOutcome>;
+    /** Drive the post-tool phase (must record `tool.complete`). Optional. */
+    toolAfter?(ctx: ContractContext, tool: string): Promise<void>;
+    /** Feed an event the plugin does not model; return the raw response. Optional. */
+    unknownEvent?(ctx: ContractContext): Promise<unknown>;
+    /** Expected raw response for `unknownEvent` (deep-equal). */
+    unknownEventOutput?: unknown;
+}
+/**
+ * Run the canonical harness contract scenarios through the adapter.
+ * Call once per harness test file, then add harness-specific tests.
+ */
+export declare function runHarnessContractSuite(adapter: HarnessContractAdapter): void;

package/dist/contract-suite.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Shared contract suite for harness plugin tests.
+ *
+ * Every harness plugin translates the same core decisions (session gates,
+ * `gateToolCall`, audit-only) onto its own native signals (exit codes,
+ * `{ decision: "block" }`, `{ block: true }`, thrown errors, …). The
+ * *decision semantics* are core-owned and tested once in `packages/core`;
+ * what varies per harness is only the translation. This suite re-runs the
+ * canonical scenario tables through a harness's real entry point via a
+ * small adapter, so a plugin cannot ship with a divergent understanding of
+ * observe / enforce / fail-open / audit-only — without each plugin
+ * re-transcribing the tables.
+ *
+ * A harness test file calls:
+ *
+ * ```ts
+ * runHarnessContractSuite({
+ *   harness: "claude-code",
+ *   tool: "Bash",
+ *   sessionCanBlock: true,
+ *   sessionStart: async ({ client, gates }) => {
+ *     const out = await handleHookEvent(sessionInput(), client, gates);
+ *     return { blocked: out.decision === "block", reason: out.reason };
+ *   },
+ *   toolBefore: async ({ client, gates }, tool) => { ... },
+ * });
+ * ```
+ *
+ * and then adds only its genuinely harness-specific tests: export shape,
+ * event-name dispatch, block-signal details, input parsing (MCP names,
+ * `subagent_type`), unique span enrichment, and the install CLI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHarnessContractSuite = runHarnessContractSuite;
+const vitest_1 = require("vitest");
+const config_js_1 = require("./config.js");
+const testing_js_1 = require("./testing.js");
+const DISABLED_DECISION = {
+    proceed: true,
+    mode: "disabled",
+    reason: "ORY_USER_LOGIN not enabled",
+};
+function makeGates(userDecision = DISABLED_DECISION) {
+    return {
+        userLogin: vitest_1.vi.fn(async () => userDecision),
+        agentGate: vitest_1.vi.fn(async () => ({
+            kind: "none",
+            reason: "not configured in contract suite",
+            warnings: [],
+        })),
+        subAgentGate: vitest_1.vi.fn(async () => ({
+            kind: "none",
+            subAgentType: "none",
+            reason: "not configured in contract suite",
+            warnings: [],
+        })),
+    };
+}
+const ENV_KEYS = [
+    "ORY_PROJECT_URL",
+    "ORY_API_KEY",
+    "ORY_SESSION_TOKEN",
+    "ORY_OAUTH2_TOKEN",
+    "ORY_USER_SESSION_TOKEN",
+    "ORY_USER_OAUTH2_TOKEN",
+    "ORY_USER_LOGIN",
+    "ORY_USER_SUBJECT_ID",
+    "ORY_USER_SUBJECT_NAMESPACE",
+    "ORY_AGENT_SUBJECT_ID",
+    "ORY_PERMISSION_MODE",
+    "ORY_PERMISSION_NAMESPACE",
+    "ORY_INTERACTIVE_TOOLS",
+];
+/**
+ * Run the canonical harness contract scenarios through the adapter.
+ * Call once per harness test file, then add harness-specific tests.
+ */
+function runHarnessContractSuite(adapter) {
+    const toolCanBlock = adapter.toolCanBlock ?? true;
+    (0, vitest_1.describe)(`${adapter.harness} — Ory harness contract`, () => {
+        let client;
+        let restoreConfigDir;
+        const savedEnv = {};
+        (0, vitest_1.beforeEach)(() => {
+            for (const key of ENV_KEYS) {
+                savedEnv[key] = process.env[key];
+                delete process.env[key];
+            }
+            restoreConfigDir = (0, testing_js_1.useTempConfigDir)();
+            process.env.ORY_PROJECT_URL = "https://test.projects.oryapis.com";
+            client = (0, testing_js_1.createMockClient)({ harness: adapter.harness });
+        });
+        (0, vitest_1.afterEach)(() => {
+            restoreConfigDir();
+            for (const key of ENV_KEYS) {
+                if (savedEnv[key] === undefined)
+                    delete process.env[key];
+                else
+                    process.env[key] = savedEnv[key];
+            }
+        });
+        const ctx = (gates = makeGates()) => ({ client, gates });
+        // ── Session start never blocks on auth/infra failures ─────────
+        (0, vitest_1.describe)("session start is fail-open", () => {
+            vitest_1.it.each([
+                { name: "valid session token", env: "session", stub: testing_js_1.stubSessionSuccess },
+                { name: "inactive session", env: "session", stub: testing_js_1.stubSessionInactive },
+                { name: "session network error", env: "session", stub: testing_js_1.stubSessionNetworkError },
+                { name: "MFA required", env: "session", stub: testing_js_1.stubSessionMfaRequired },
+                { name: "valid OAuth2 token", env: "oauth2", stub: testing_js_1.stubOAuth2Success },
+                { name: "inactive OAuth2 token", env: "oauth2", stub: testing_js_1.stubOAuth2Inactive },
+                { name: "unconfigured (no project URL)", env: "none", stub: undefined },
+            ])("proceeds with $name", async ({ env, stub, name }) => {
+                if (name.includes("OAuth2") && adapter.legacyOAuth2 === false)
+                    return;
+                if (env === "session")
+                    process.env.ORY_SESSION_TOKEN = "token-under-test";
+                if (env === "oauth2")
+                    process.env.ORY_OAUTH2_TOKEN = "token-under-test";
+                if (env === "none")
+                    delete process.env.ORY_PROJECT_URL;
+                stub?.(client);
+                const outcome = await adapter.sessionStart(ctx());
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+            });
+        });
+        // ── User-login gate translation ────────────────────────────────
+        (0, vitest_1.describe)("user-login gate", () => {
+            const declined = {
+                proceed: false,
+                mode: "declined",
+                reason: "User declined the OAuth2 consent screen",
+            };
+            (0, vitest_1.it)(adapter.sessionCanBlock
+                ? "translates a declined login into the native session block"
+                : "treats a declined login as advisory (no session block channel)", async () => {
+                const gates = makeGates(declined);
+                const outcome = await adapter.sessionStart(ctx(gates));
+                (0, vitest_1.expect)(outcome.blocked).toBe(adapter.sessionCanBlock);
+                if (adapter.sessionCanBlock) {
+                    (0, vitest_1.expect)(outcome.reason).toBeTruthy();
+                }
+            });
+            (0, vitest_1.it)("runs the agent gate even when the user gate declines", async () => {
+                const gates = makeGates(declined);
+                await adapter.sessionStart(ctx(gates));
+                (0, vitest_1.expect)(gates.agentGate).toHaveBeenCalledOnce();
+            });
+            (0, vitest_1.it)("proceeds without legacy verification when the gate handled auth", async () => {
+                process.env.ORY_SESSION_TOKEN = "should-not-be-verified";
+                const verify = (0, testing_js_1.stubSessionSuccess)(client);
+                const gates = makeGates({ proceed: true, mode: "ok", reason: "logged in" });
+                const outcome = await adapter.sessionStart(ctx(gates));
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)(verify).not.toHaveBeenCalled();
+            });
+            (0, vitest_1.it)("falls through to legacy verification when the gate is disabled", async () => {
+                process.env.ORY_SESSION_TOKEN = "legacy-token";
+                const verify = (0, testing_js_1.stubSessionSuccess)(client);
+                const outcome = await adapter.sessionStart(ctx());
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)(verify).toHaveBeenCalled();
+            });
+        });
+        // ── Tool gate translation ──────────────────────────────────────
+        (0, vitest_1.describe)("tool gate", () => {
+            vitest_1.it.each([
+                { check: "allowed", mode: "enforce", blocked: false, invoke: true, block: false },
+                { check: "denied", mode: "enforce", blocked: toolCanBlock, invoke: false, block: true },
+                { check: "denied", mode: "observe", blocked: false, invoke: true, block: true },
+                { check: "network_error", mode: "enforce", blocked: false, invoke: false, block: false },
+                { check: "rate_limited", mode: "enforce", blocked: false, invoke: false, block: false },
+            ])("check=$check × $mode → blocked=$blocked", async ({ check, mode, blocked, invoke, block }) => {
+                const stubs = {
+                    allowed: testing_js_1.stubPermissionAllowed,
+                    denied: testing_js_1.stubPermissionDenied,
+                    network_error: testing_js_1.stubPermissionNetworkError,
+                    rate_limited: testing_js_1.stubPermissionRateLimited,
+                };
+                stubs[check](client);
+                process.env.ORY_PERMISSION_MODE = mode;
+                const outcome = await adapter.toolBefore(ctx(), adapter.tool);
+                (0, vitest_1.expect)(outcome.blocked).toBe(blocked);
+                if (blocked)
+                    (0, vitest_1.expect)(outcome.reason).toBeTruthy();
+                const invokeSpans = (0, testing_js_1.getTraceSpans)(client, "tool.invoke");
+                const blockSpans = (0, testing_js_1.getTraceSpans)(client, "tool.block");
+                if (invoke) {
+                    (0, vitest_1.expect)(invokeSpans.length).toBeGreaterThanOrEqual(1);
+                    (0, vitest_1.expect)(invokeSpans[0].attributes?.toolName).toBe(adapter.tool);
+                }
+                else {
+                    (0, vitest_1.expect)(invokeSpans).toHaveLength(0);
+                }
+                if (block) {
+                    (0, vitest_1.expect)(blockSpans.length).toBeGreaterThanOrEqual(1);
+                    (0, vitest_1.expect)(blockSpans[0].attributes?.blocked).toBe(mode === "enforce" && toolCanBlock);
+                }
+                else {
+                    (0, vitest_1.expect)(blockSpans).toHaveLength(0);
+                }
+                // Observe-mode denies also emit the audit span; enforce must not.
+                const observeSpans = (0, testing_js_1.getTraceSpans)(client, "permission.observe_deny");
+                (0, vitest_1.expect)(observeSpans).toHaveLength(check === "denied" && mode === "observe" ? 1 : 0);
+            });
+            (0, vitest_1.it)("skips the permission check entirely in audit-only mode", async () => {
+                (0, config_js_1.saveConfig)({ auditOnly: true });
+                const checkSpy = vitest_1.vi.spyOn(client, "checkPermission");
+                process.env.ORY_PERMISSION_MODE = "enforce";
+                const outcome = await adapter.toolBefore(ctx(), adapter.tool);
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)(checkSpy).not.toHaveBeenCalled();
+            });
+            (0, vitest_1.it)("addresses the check to ORY_USER_SUBJECT_ID when set", async () => {
+                process.env.ORY_USER_SUBJECT_ID = "user:custom-override";
+                (0, testing_js_1.stubPermissionAllowed)(client);
+                await adapter.toolBefore(ctx(), adapter.tool);
+                const [span] = (0, testing_js_1.getTraceSpans)(client, "tool.invoke");
+                (0, vitest_1.expect)(span.attributes?.subjectId).toBe("user:custom-override");
+            });
+        });
+        // ── Post-tool + passthrough ────────────────────────────────────
+        if (adapter.toolAfter) {
+            (0, vitest_1.it)("records tool.complete after execution", async () => {
+                await adapter.toolAfter(ctx(), adapter.tool);
+                const spans = (0, testing_js_1.getTraceSpans)(client, "tool.complete");
+                (0, vitest_1.expect)(spans.length).toBeGreaterThanOrEqual(1);
+                (0, vitest_1.expect)(spans[0].attributes?.toolName).toBe(adapter.tool);
+            });
+        }
+        if (adapter.unknownEvent) {
+            (0, vitest_1.it)("passes unknown events through with the native empty response", async () => {
+                const raw = await adapter.unknownEvent(ctx());
+                (0, vitest_1.expect)(raw).toEqual(adapter.unknownEventOutput);
+            });
+        }
+    });
+}

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export { resolveUserSubject, subjectLabel, type UserSubjectRef, } from "./subjec
 export { formatDenialMessage, formatDenialSummary, formatAlertMessage, formatAlertSummary, alertAttributes, OryDenialError, type DenialContext, type AlertAttributes, } from "./denial.js";
 export { summarizeToolInput, summarizeToolOutput, type ToolInputSummary, type ToolOutputSummary, } from "./tool-metadata.js";
 export { OtlpExporter, otlpExporterFromEnv, parseKeyValueList, type SpanExporter, type OtlpExporterOptions, type OtlpProtocol, } from "./otel/index.js";
+export { resolveNamespace, sessionStart, gate, complete, registerSubagent, wrapTool, type SessionStartResult, type SessionStartOptions, type RegisterSubagentOptions, type GateResult, type GateOptions, type WrapToolOptions, } from "./adapters.js";