@ory/argus 0.9.1 → 0.11.0

package/dist/local/manager.js

@@ -57,6 +57,7 @@ exports.localEnv = localEnv;
 exports.localConfigure = localConfigure;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
 const configs_js_1 = require("./configs.js");
 const health_js_1 = require("./health.js");
@@ -196,28 +197,86 @@ function dumpCapturedOutput(label, result) {
     process.stderr.write(`── end ${label} output ──\n\n`);
 }
 // ─── Write config files ────────────────────────────────────────────
+/**
+ * Render the full set of local-stack config files as `{ relPath, content }`
+ * pairs. Pure function of the code, `projectRoot`, and `consoleCfg` — no I/O.
+ * `writeConfigs` writes these and `configFingerprint` hashes them, so the
+ * on-disk stack and its change-detection signal never drift.
+ */
+function renderConfigs(projectRoot, consoleCfg) {
+    return [
+        {
+            relPath: "docker-compose.yml",
+            content: (0, configs_js_1.dockerComposeYaml)(projectRoot, consoleCfg),
+        },
+        { relPath: "kratos/kratos.yml", content: (0, configs_js_1.kratosConfigYaml)() },
+        {
+            relPath: "kratos/identity-schema.json",
+            content: (0, configs_js_1.kratosIdentitySchema)(),
+        },
+        { relPath: "keto/keto.yml", content: (0, configs_js_1.ketoConfigYaml)() },
+        { relPath: "hydra/hydra.yml", content: (0, configs_js_1.hydraConfigYaml)() },
+        // nginx config is always emitted — the gateway is no longer optional.
+        { relPath: "nginx/nginx.conf", content: (0, configs_js_1.nginxConf)() },
+    ];
+}
+/**
+ * Stable content hash of the rendered config set. Used to decide whether an
+ * already-running stack still matches the config the current code would
+ * generate; a change (e.g. the login-UI port, a service env var) invalidates
+ * the fast-path short-circuit so the stack is reconciled instead of reused.
+ */
+function configFingerprint(projectRoot, consoleCfg) {
+    const hash = crypto.createHash("sha256");
+    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg)) {
+        hash.update(relPath);
+        hash.update("\0");
+        hash.update(content);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+const CONFIG_FINGERPRINT_FILE = ".config-fingerprint";
+/** Read the fingerprint recorded after the last successful bring-up. */
+function readConfigFingerprint(localDir) {
+    try {
+        return fs
+            .readFileSync(path.join(localDir, CONFIG_FINGERPRINT_FILE), "utf8")
+            .trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Record the fingerprint of the config the running stack was brought up with. */
+function writeConfigFingerprint(localDir, fingerprint) {
+    try {
+        fs.writeFileSync(path.join(localDir, CONFIG_FINGERPRINT_FILE), fingerprint + "\n");
+    }
+    catch {
+        // Best-effort: a missing fingerprint only costs a reconcile next launch.
+    }
+}
 function writeConfigs(localDir, projectRoot, consoleCfg) {
     ensureDir(localDir);
     ensureDir(path.join(localDir, "kratos"));
     ensureDir(path.join(localDir, "keto"));
     ensureDir(path.join(localDir, "hydra"));
     ensureDir(path.join(localDir, "nginx"));
-    fs.writeFileSync(path.join(localDir, "docker-compose.yml"), (0, configs_js_1.dockerComposeYaml)(projectRoot, consoleCfg));
-    fs.writeFileSync(path.join(localDir, "kratos", "kratos.yml"), (0, configs_js_1.kratosConfigYaml)());
-    fs.writeFileSync(path.join(localDir, "kratos", "identity-schema.json"), (0, configs_js_1.kratosIdentitySchema)());
-    fs.writeFileSync(path.join(localDir, "keto", "keto.yml"), (0, configs_js_1.ketoConfigYaml)());
-    fs.writeFileSync(path.join(localDir, "hydra", "hydra.yml"), (0, configs_js_1.hydraConfigYaml)());
-    // nginx config is always emitted — the gateway is no longer optional.
-    fs.writeFileSync(path.join(localDir, "nginx", "nginx.conf"), (0, configs_js_1.nginxConf)());
+    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg)) {
+        fs.writeFileSync(path.join(localDir, relPath), content);
+    }
 }
 /**
  * Bring up the local Ory stack and wait for the gateway to be healthy.
  *
  * Idempotent and fail-graceful: returns a typed result instead of exiting.
- * If the gateway is already healthy the function short-circuits without
- * touching Docker. When `quiet` is set, progress is logged to stderr only
- * (suitable for the dev launcher); otherwise it prints to stdout in the
- * format `localUp` historically used.
+ * If the gateway is already healthy AND the running stack's config matches
+ * what the current code generates (verified by a config fingerprint), the
+ * function short-circuits without touching Docker; otherwise it regenerates
+ * the config and runs `docker compose up -d --wait` to reconcile. When
+ * `quiet` is set, progress is logged to stderr only (suitable for the dev
+ * launcher); otherwise it prints to stdout in the format `localUp` historically used.
  */
 async function ensureLocalOryStack(opts = {}) {
     const localDir = opts.localDir ?? getLocalDir();
@@ -232,13 +291,25 @@ async function ensureLocalOryStack(opts = {}) {
     }
     const gatewayCfg = (0, configs_js_1.getGatewayConfig)();
     const healthUrl = `${configs_js_1.GATEWAY_URL}${gatewayCfg.healthPath}`;
-    // Short-circuit if the gateway is already serving — keeps repeated dev
-    // launches fast and avoids re-pulling/restarting healthy containers.
-    // Skip the short-circuit when ORY_CONSOLE_LITE_PATH is explicitly set so
-    // a path change on a subsequent run actually triggers a rebuild (compose
-    // diffs the regenerated YAML and recreates the console when needed).
+    // Short-circuit if the gateway is already serving AND the running stack was
+    // brought up with the same config the current code would generate — keeps
+    // repeated dev launches fast without re-pulling/restarting healthy
+    // containers. Gateway health alone is not enough: a config change to any
+    // service (e.g. the login-UI port, a service env var) leaves the gateway
+    // healthy while the rest of the stack runs stale config, so we also require
+    // the config fingerprint to match. On a mismatch we fall through and let
+    // `docker compose up -d --wait` diff the regenerated YAML and recreate only
+    // the changed containers.
+    //
+    // Skip the short-circuit entirely when ORY_CONSOLE_LITE_PATH is explicitly
+    // set so a rebuild is forced even when the path is unchanged (the console
+    // source tree behind the path may have changed, which the fingerprint of the
+    // generated config can't see).
     const explicitConsoleLiteOverride = (process.env.ORY_CONSOLE_LITE_PATH ?? "").trim() !== "";
+    const fingerprint = configFingerprint(projectRoot, consoleCfg);
+    const configUnchanged = readConfigFingerprint(localDir) === fingerprint;
     if (!explicitConsoleLiteOverride &&
+        configUnchanged &&
         (await isGatewayHealthy(1_500, healthUrl))) {
         return { status: "already-running", gatewayUrl: configs_js_1.GATEWAY_URL, localDir };
     }
@@ -320,6 +391,10 @@ async function ensureLocalOryStack(opts = {}) {
             detail: "Gateway did not become healthy within 2 minutes.",
         };
     }
+    // Record the fingerprint of the config the stack was actually brought up
+    // with (consoleCfg may have fallen back to disabled above), so the next
+    // launch can short-circuit only while the config is unchanged.
+    writeConfigFingerprint(localDir, configFingerprint(projectRoot, consoleCfg));
     return { status: "started", gatewayUrl: configs_js_1.GATEWAY_URL, localDir };
 }
 async function localUp(opts = {}) {

package/dist/permissions.d.ts

@@ -12,8 +12,15 @@
  *          return `{ kind: "observe", … }` so the caller allows the
  *          tool through.
  *        - `enforce` — return `{ kind: "deny", … }` so the caller blocks.
- *   3. On a thrown {@link OryError} (network_error, rate_limited, etc.),
- *      returns `{ kind: "fail_open", … }`. Callers should log and allow.
+ *   3. On a thrown {@link OryError}, inspects the classified code:
+ *        - Infrastructure errors (`network_error`, `rate_limited`,
+ *          `not_found`, `unknown`) — returns `{ kind: "fail_open", … }`.
+ *          Callers should log and allow.
+ *        - Auth-rejected check calls (`forbidden`, `session_inactive`,
+ *          `session_aal2_required` — the check itself was rejected, so
+ *          its result cannot be trusted) — in `enforce` mode returns
+ *          `{ kind: "deny", … }` so the caller blocks; in `observe`
+ *          mode falls back to `fail_open` (observe never blocks).
  *
  * The discriminated `kind` lets plugins map cleanly to their native
  * decision shape (claude-code exit codes, openclaw `{ block: true }`,
@@ -22,7 +29,7 @@
  */
 import type { OryAgentClient } from "./client.js";
 import { type PermissionMode } from "./config.js";
-import type { OryError, PermissionCheck, PermissionResult } from "./types.js";
+import type { OryError, OryErrorCode, PermissionCheck, PermissionResult } from "./types.js";
 /**
  * Attributes describing *what was checked* and *under which posture*.
  * Plugins spread this onto their `tool.invoke` / `tool.block` spans so
@@ -36,6 +43,13 @@ export interface DecisionSpanAttributes {
     subjectId?: string;
     /** SubjectSet rendered as `<namespace>:<object>#<relation>` when used. */
     subjectSet?: string;
+    /**
+     * Set when the check call itself was auth-rejected and enforce mode
+     * turned that into a deny — the classified {@link OryErrorCode} that
+     * caused it. Makes the "denied because the check failed" case
+     * distinguishable from a normal Keto deny in the audit trail.
+     */
+    checkRejected?: OryErrorCode;
 }
 export type PermissionDecision = {
     kind: "allow";
@@ -118,12 +132,20 @@ export interface ApplyPermissionModeContext {
  */
 export declare function applyPermissionMode(client: OryAgentClient, allowed: boolean, context?: ApplyPermissionModeContext): ModeDecision;
 /**
- * Outcome of {@link gateToolCall}. Either the tool is a user-interaction
+ * Outcome of {@link gateToolCall}. Either Ory is disabled entirely
+ * (`config.auditOnly` kill switch), the tool is a user-interaction
  * primitive (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, …) and we
  * pass through with a single audit span, or it's a real tool execution
  * and the caller gets the standard {@link PermissionDecision}.
  */
 export type ToolGateOutcome = {
+    kind: "audit_only";
+    /** Attributes to attach to the caller's pass-through trace, if any. */
+    spanAttributes: {
+        auditOnly: true;
+        toolName: string;
+    };
+} | {
     kind: "interactive";
     /** Attributes to attach to the caller's pass-through trace, if any. */
     spanAttributes: {
@@ -147,8 +169,12 @@ export interface GateToolCallArgs {
     modeOverride?: PermissionMode;
 }
 /**
- * Single entry point for the pre-tool-use gate. Splits the harness's
- * incoming "tool" into two semantic categories:
+ * Single entry point for the pre-tool-use gate. Applies the
+ * `config.auditOnly` kill switch first — when set, Ory is disabled
+ * entirely and the caller gets `{ kind: "audit_only" }` back without any
+ * permission check (record the invocation as an audit span and proceed).
+ * Otherwise splits the harness's incoming "tool" into two semantic
+ * categories:
  *
  *   - **Interactive** — the tool surfaces UI to the user
  *     (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, plus anything
@@ -170,7 +196,9 @@ export interface GateToolCallArgs {
 export declare function gateToolCall(client: OryAgentClient, args: GateToolCallArgs): Promise<ToolGateOutcome>;
 /**
  * Run a permission check and resolve the configured mode against the
- * result. Never throws — fail-open scenarios are surfaced as a typed
- * `{ kind: "fail_open" }` decision.
+ * result. Never throws — infrastructure errors surface as a typed
+ * `{ kind: "fail_open" }` decision, and auth-rejected check calls in
+ * enforce mode as `{ kind: "deny" }` (see
+ * {@link CHECK_AUTH_REJECTED_CODES}).
  */
 export declare function checkAndDecide(client: OryAgentClient, check: PermissionCheck, opts?: CheckAndDecideOptions): Promise<PermissionDecision>;

package/dist/permissions.js

@@ -13,8 +13,15 @@
  *          return `{ kind: "observe", … }` so the caller allows the
  *          tool through.
  *        - `enforce` — return `{ kind: "deny", … }` so the caller blocks.
- *   3. On a thrown {@link OryError} (network_error, rate_limited, etc.),
- *      returns `{ kind: "fail_open", … }`. Callers should log and allow.
+ *   3. On a thrown {@link OryError}, inspects the classified code:
+ *        - Infrastructure errors (`network_error`, `rate_limited`,
+ *          `not_found`, `unknown`) — returns `{ kind: "fail_open", … }`.
+ *          Callers should log and allow.
+ *        - Auth-rejected check calls (`forbidden`, `session_inactive`,
+ *          `session_aal2_required` — the check itself was rejected, so
+ *          its result cannot be trusted) — in `enforce` mode returns
+ *          `{ kind: "deny", … }` so the caller blocks; in `observe`
+ *          mode falls back to `fail_open` (observe never blocks).
  *
  * The discriminated `kind` lets plugins map cleanly to their native
  * decision shape (claude-code exit codes, openclaw `{ block: true }`,
@@ -27,6 +34,19 @@ exports.gateToolCall = gateToolCall;
 exports.checkAndDecide = checkAndDecide;
 const config_js_1 = require("./config.js");
 const tool_catalog_js_1 = require("./tool-catalog.js");
+/**
+ * Error codes meaning the check call itself was rejected for
+ * authentication/authorization reasons — an expired or misconfigured
+ * agent credential, an inactive session, or a missing MFA step. The
+ * check result cannot be trusted, so `enforce` mode denies instead of
+ * failing open. Infrastructure errors (`network_error`, `rate_limited`,
+ * `not_found`, `unknown`) keep the fail-open posture.
+ */
+const CHECK_AUTH_REJECTED_CODES = new Set([
+    "forbidden",
+    "session_inactive",
+    "session_aal2_required",
+]);
 function formatSubjectSet(set) {
     if (!set)
         return undefined;
@@ -78,8 +98,12 @@ function applyPermissionMode(client, allowed, context = {}) {
     return { kind: "deny", mode: "enforce", spanAttributes };
 }
 /**
- * Single entry point for the pre-tool-use gate. Splits the harness's
- * incoming "tool" into two semantic categories:
+ * Single entry point for the pre-tool-use gate. Applies the
+ * `config.auditOnly` kill switch first — when set, Ory is disabled
+ * entirely and the caller gets `{ kind: "audit_only" }` back without any
+ * permission check (record the invocation as an audit span and proceed).
+ * Otherwise splits the harness's incoming "tool" into two semantic
+ * categories:
  *
  *   - **Interactive** — the tool surfaces UI to the user
  *     (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, plus anything
@@ -99,6 +123,17 @@ function applyPermissionMode(client, allowed, context = {}) {
  * semantics; the new `interactive` kind means "do nothing else."
  */
 async function gateToolCall(client, args) {
+    if ((0, config_js_1.resolveConfig)().auditOnly) {
+        client.logger.debug("tool.audit_only", {
+            harness: args.harness,
+            toolName: args.toolName,
+            note: "audit-only mode — skipping permission check",
+        });
+        return {
+            kind: "audit_only",
+            spanAttributes: { auditOnly: true, toolName: args.toolName },
+        };
+    }
     if ((0, tool_catalog_js_1.isInteractiveTool)(args.harness, args.toolName)) {
         client.logger.debug("tool.interactive", {
             harness: args.harness,
@@ -125,8 +160,10 @@ async function gateToolCall(client, args) {
 }
 /**
  * Run a permission check and resolve the configured mode against the
- * result. Never throws — fail-open scenarios are surfaced as a typed
- * `{ kind: "fail_open" }` decision.
+ * result. Never throws — infrastructure errors surface as a typed
+ * `{ kind: "fail_open" }` decision, and auth-rejected check calls in
+ * enforce mode as `{ kind: "deny" }` (see
+ * {@link CHECK_AUTH_REJECTED_CODES}).
  */
 async function checkAndDecide(client, check, opts = {}) {
     const mode = opts.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
@@ -138,7 +175,25 @@ async function checkAndDecide(client, check, opts = {}) {
         });
     }
     catch (err) {
-        return { kind: "fail_open", error: err, mode, spanAttributes };
+        const oryErr = err;
+        if (mode === "enforce" && oryErr && CHECK_AUTH_REJECTED_CODES.has(oryErr.code)) {
+            // The check call itself was rejected for auth reasons — the
+            // result cannot be trusted, so enforce mode must not fail open.
+            client.logger.warn("permission.check_rejected", {
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                code: oryErr.code,
+                note: `permission check rejected (${oryErr.code}); enforce mode denies when checks cannot be completed`,
+            });
+            return {
+                kind: "deny",
+                result: { allowed: false, checkedAt: new Date().toISOString(), check },
+                mode: "enforce",
+                spanAttributes: { ...spanAttributes, checkRejected: oryErr.code },
+            };
+        }
+        return { kind: "fail_open", error: oryErr, mode, spanAttributes };
     }
     const inner = applyPermissionMode(client, result.allowed, {
         namespace: check.namespace,

package/dist/subject.d.ts

@@ -27,7 +27,19 @@ export type UserSubjectRef = {
     };
 };
 /**
- * Resolve the user subject for permission checks. Prefers the user
+ * Run `fn` with a per-call user subject that takes precedence over the
+ * client's user principal and the env overrides in
+ * {@link resolveUserSubject}. The override only applies within `fn`'s
+ * async context, so concurrent calls cannot observe each other's subject.
+ * `ORY_USER_SUBJECT_NAMESPACE` SubjectSet shaping still applies.
+ *
+ * A missing/empty `subject` is a no-op: `fn` runs with the normal
+ * resolution chain.
+ */
+export declare function runWithUserSubject<T>(subject: string | undefined, fn: () => T): T;
+/**
+ * Resolve the user subject for permission checks. Prefers a per-call
+ * override installed via {@link runWithUserSubject}, then the user
  * login's `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
  * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).

package/dist/subject.js

@@ -18,10 +18,36 @@
  * falls back to the direct SubjectID chain.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithUserSubject = runWithUserSubject;
 exports.resolveUserSubject = resolveUserSubject;
 exports.subjectLabel = subjectLabel;
+const node_async_hooks_1 = require("node:async_hooks");
 /**
- * Resolve the user subject for permission checks. Prefers the user
+ * Per-async-context user-subject override. Populated by
+ * {@link runWithUserSubject} so multi-user server integrations (Vercel AI
+ * SDK, Cloudflare Agents) can attribute each request to its own acting
+ * user without mutating the shared client or process env — both of which
+ * would race under concurrent requests.
+ */
+const perCallUserSubject = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * Run `fn` with a per-call user subject that takes precedence over the
+ * client's user principal and the env overrides in
+ * {@link resolveUserSubject}. The override only applies within `fn`'s
+ * async context, so concurrent calls cannot observe each other's subject.
+ * `ORY_USER_SUBJECT_NAMESPACE` SubjectSet shaping still applies.
+ *
+ * A missing/empty `subject` is a no-op: `fn` runs with the normal
+ * resolution chain.
+ */
+function runWithUserSubject(subject, fn) {
+    if (!subject)
+        return fn();
+    return perCallUserSubject.run(subject, fn);
+}
+/**
+ * Resolve the user subject for permission checks. Prefers a per-call
+ * override installed via {@link runWithUserSubject}, then the user
  * login's `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
  * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
@@ -30,7 +56,8 @@ exports.subjectLabel = subjectLabel;
  * concrete subject is available; otherwise a direct SubjectID.
  */
 function resolveUserSubject(client, fallback) {
-    const subject = client.userPrincipal.subject
+    const subject = perCallUserSubject.getStore()
+        ?? client.userPrincipal.subject
         ?? process.env.ORY_USER_SUBJECT_ID
         ?? process.env.ORY_AGENT_SUBJECT_ID
         ?? fallback;

package/dist/testing.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared test utilities for Ory agent plugin integration tests.
+ *
+ * These helpers provide mock Ory API responses, error factories, and
+ * common assertion patterns so that harness plugin tests focus on
+ * harness-specific behavior rather than duplicating boilerplate.
+ */
+import { vi } from "vitest";
+import { OryAgentClient } from "./client.js";
+import type { TraceSpan, TraceEvent } from "./tracer.js";
+export { runHarnessContractSuite, type HarnessContractAdapter, type ContractContext, type ContractGates, type ContractOutcome, } from "./contract-suite.js";
+/**
+ * Create an OryAgentClient with session caching disabled.
+ * Pass overrides to customize (e.g. a different harness name).
+ */
+export declare function createMockClient(overrides?: Partial<ConstructorParameters<typeof OryAgentClient>[0]>): OryAgentClient;
+/**
+ * Stub an internal API instance method on the client.
+ * Returns a vi.fn mock so callers can assert on calls.
+ */
+export declare function stubApi<K extends "frontend" | "oauth2" | "permission" | "relationship">(client: OryAgentClient, api: K, method: string, impl: (...args: unknown[]) => unknown): ReturnType<typeof vi.fn>;
+/** Successful session verification response (wraps Ory API shape). */
+export declare const MOCK_SESSION_RESPONSE: {
+    data: {
+        id: string;
+        active: boolean;
+        authenticated_at: string;
+        expires_at: string;
+        authenticator_assurance_level: string;
+        authentication_methods: {
+            method: string;
+            completed_at: string;
+        }[];
+        identity: {
+            id: string;
+            traits: {
+                email: string;
+            };
+        };
+    };
+};
+/** Inactive session (same shape, active: false). */
+export declare const MOCK_INACTIVE_SESSION_RESPONSE: {
+    data: {
+        active: boolean;
+        id: string;
+        authenticated_at: string;
+        expires_at: string;
+        authenticator_assurance_level: string;
+        authentication_methods: {
+            method: string;
+            completed_at: string;
+        }[];
+        identity: {
+            id: string;
+            traits: {
+                email: string;
+            };
+        };
+    };
+};
+/** Successful OAuth2 token introspection response. */
+export declare const MOCK_OAUTH2_RESPONSE: {
+    data: {
+        active: boolean;
+        client_id: string;
+        sub: string;
+        scope: string;
+        aud: string[];
+        exp: number;
+        iat: number;
+    };
+};
+/** Inactive OAuth2 token response. */
+export declare const MOCK_INACTIVE_OAUTH2_RESPONSE: {
+    data: {
+        active: boolean;
+    };
+};
+/** Permission check allowed response. */
+export declare const PERMISSION_ALLOWED: {
+    data: {
+        allowed: boolean;
+    };
+};
+/** Permission check denied response. */
+export declare const PERMISSION_DENIED: {
+    data: {
+        allowed: boolean;
+    };
+};
+/** Batch permission check: both results allowed. */
+export declare const BATCH_BOTH_ALLOWED: {
+    data: {
+        results: {
+            allowed: boolean;
+        }[];
+    };
+};
+/** Batch permission check: server allowed, tool denied. */
+export declare const BATCH_SERVER_ALLOWED_TOOL_DENIED: {
+    data: {
+        results: {
+            allowed: boolean;
+        }[];
+    };
+};
+/** Batch permission check: server denied. */
+export declare const BATCH_SERVER_DENIED: {
+    data: {
+        results: {
+            allowed: boolean;
+        }[];
+    };
+};
+/** Create an Axios-shaped error with a response. */
+export declare function makeAxiosError(status: number, body?: unknown, code?: string): Record<string, unknown>;
+/** Create a Node.js network error (ECONNREFUSED, ETIMEDOUT, etc.). */
+export declare function makeNetworkError(code?: string): NodeJS.ErrnoException;
+/** Axios 429 rate-limit error. */
+export declare function makeRateLimitError(): Record<string, unknown>;
+/** Axios 403 with session_aal2_required error id. */
+export declare function makeMfaRequiredError(): Record<string, unknown>;
+/** Axios 401 with session_inactive error id. */
+export declare function makeSessionInactiveError(): Record<string, unknown>;
+/**
+ * Get all recorded trace spans from a client, optionally filtered by event.
+ */
+export declare function getTraceSpans(client: OryAgentClient, event?: TraceEvent): TraceSpan[];
+/**
+ * Assert the tracer recorded the expected tool names for a given event type.
+ * Checks the `toolName` attribute on each span.
+ */
+export declare function expectTracedTools(client: OryAgentClient, event: TraceEvent, expectedTools: string[]): void;
+/**
+ * Set standard Ory env vars for a configured + authenticated test.
+ * Returns a cleanup function that restores the previous state.
+ */
+export declare function setOryEnv(overrides?: Partial<{
+    projectUrl: string;
+    sessionToken: string;
+    oauth2Token: string;
+    subjectId: string;
+    namespace: string;
+    /**
+     * Permission mode for the test. Defaults to `"enforce"` so existing
+     * test assertions that exercise the deny path still see a block.
+     * Pass `"observe"` explicitly to exercise the new observe branch.
+     */
+    permissionMode: "observe" | "enforce";
+}>): () => void;
+/**
+ * Point `XDG_CONFIG_HOME` at a fresh temp directory so `resolveConfig()`
+ * reads from a known-empty state instead of the developer's real
+ * `~/.config/ory-agent-plugins/config.json`. Returns a cleanup function
+ * that restores the env var and removes the temp directory.
+ *
+ * Use `saveConfig(...)` from `./config.js` inside the test to shape the
+ * isolated config (e.g. `saveConfig({ auditOnly: true })`).
+ */
+export declare function useTempConfigDir(): () => void;
+/**
+ * Clear all Ory env vars (simulate unconfigured state).
+ */
+export declare function clearOryEnv(): void;
+/** Stub verifySession to succeed. */
+export declare function stubSessionSuccess(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub verifySession to return inactive. */
+export declare function stubSessionInactive(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub verifySession to throw a network error. */
+export declare function stubSessionNetworkError(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub verifySession to throw MFA required. */
+export declare function stubSessionMfaRequired(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub verifySession to throw session_inactive. */
+export declare function stubSessionExpired(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub introspectToken to succeed. */
+export declare function stubOAuth2Success(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub introspectToken to return inactive. */
+export declare function stubOAuth2Inactive(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub checkPermission to allow. */
+export declare function stubPermissionAllowed(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub checkPermission to deny. */
+export declare function stubPermissionDenied(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub checkPermission to throw a network error. */
+export declare function stubPermissionNetworkError(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub checkPermission to throw a rate-limit error. */
+export declare function stubPermissionRateLimited(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/**
+ * Spy on the public `createRelationship` method and resolve successfully.
+ * Prefer this over stubbing the internal relationship API: `setAgentPrincipal`
+ * rebuilds the API instances when the agent token changes (e.g. inside
+ * `sessionStart`), which silently discards API-level stubs.
+ */
+export declare function spyRelationshipCreated(client: OryAgentClient): import("vitest").Mock<(check: import("./types.js").PermissionCheck, options?: {
+    spanAttributes?: Record<string, unknown>;
+}) => Promise<{
+    created: boolean;
+    alreadyExisted: boolean;
+}>>;
+/** Spy on the public `createRelationship` method and reject. */
+export declare function spyRelationshipCreateError(client: OryAgentClient): import("vitest").Mock<(check: import("./types.js").PermissionCheck, options?: {
+    spanAttributes?: Record<string, unknown>;
+}) => Promise<{
+    created: boolean;
+    alreadyExisted: boolean;
+}>>;
+/** Stub both checkPermission (server allow) and batchCheckPermission (both allow). */
+export declare function stubMcpAllowed(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub checkPermission to deny (server-only MCP check). */
+export declare function stubMcpServerDenied(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub batchCheckPermission: server allowed, tool denied. */
+export declare function stubMcpToolDenied(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;
+/** Stub checkPermission to throw network error (MCP fail-open). */
+export declare function stubMcpNetworkError(client: OryAgentClient): import("vitest").Mock<import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Procedure | import(".pnpm/@vitest+spy@4.1.7/node_modules/@vitest/spy", { with: { "resolution-mode": "import" } }).Constructable>;