@ory/argus 0.9.1 → 0.10.0

package/assets/skills/auth-setup/SKILL.md

@@ -233,7 +233,9 @@ Create the following page structure:
 - `app/auth/registration/page.tsx` — `<Registration flow={flow} />`
 - `app/auth/recovery/page.tsx` — `<Recovery flow={flow} />`
 - `app/auth/verification/page.tsx` — `<Verification flow={flow} />`
-- `app/auth/settings/page.tsx` — `<Settings flow={flow} />`
+- `app/auth/settings/page.tsx` — `<Settings flow={flow} />`, wrapped in
+  `<SessionProvider>` from `@ory/elements-react/client` (Settings is the only
+  flow that needs it — see {{REF_LOGIN_FLOW}})
 
 Each page initializes its flow with `getLoginFlow`, `getRegistrationFlow`,
 etc. from `@ory/nextjs/app`, then hands the flow to the matching

package/assets/skills/login-flow/SKILL.md

@@ -264,6 +264,7 @@ Create `app/auth/settings/page.tsx`:
 
 ```typescript
 import { Settings } from "@ory/elements-react/theme"
+import { SessionProvider } from "@ory/elements-react/client"
 import { getSettingsFlow, OryPageLayout } from "@ory/nextjs/app"
 
 export default async function SettingsPage(props: {
@@ -278,16 +279,26 @@ export default async function SettingsPage(props: {
 
   return (
     <OryPageLayout>
-      <Settings flow={flow} />
+      <SessionProvider>
+        <Settings flow={flow} />
+      </SessionProvider>
     </OryPageLayout>
   )
 }
 ```
 
+Unlike the other flows, **`<Settings>` must be wrapped in `<SessionProvider>`**
+from `@ory/elements-react/client`. Settings renders session-dependent controls
+(connected social accounts, unlinking, logout of other sessions) that read from
+the session context; the pre-auth pages (login, registration, recovery,
+verification) have no session yet and do not need the provider.
+
 ### Settings — React SPA
 
 Initialize with `createBrowserSettingsFlow` and render
-`<Settings flow={flow} />` from `@ory/elements-react/theme`. The
+`<Settings flow={flow} />` from `@ory/elements-react/theme`, wrapped in
+`<SessionProvider>` from `@ory/elements-react/client` (the same requirement
+as the App Router page above — Settings reads session-dependent state). The
 component handles password changes, profile traits, MFA enrollment,
 and connected social providers.
 
@@ -385,6 +396,71 @@ For larger design changes, the Ory Elements primitives package exposes
 the underlying card, button, and input components — use those before
 falling back to custom node rendering.
 
+## Enable MFA and passkeys
+
+These are **project-side** capabilities: once enabled on the Ory project, the
+`<Login>`, `<Registration>`, and `<Settings>` components render the second-factor
+and passkey UI automatically — **no page code changes**. Configure them with the
+Ory CLI against your project (`ory list projects` for the id), the same idiom as
+{{REF_SOCIAL_LOGIN}}. Against the local stack, apply the equivalent keys to the
+local Kratos config instead ({{REF_LOCAL_DEV}}).
+
+### Passkeys
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/passkey/enabled=true' \
+  --add '/selfservice/methods/passkey/config/rp/display_name="My App"' \
+  --add '/selfservice/methods/passkey/config/rp/id="your-domain.com"' \
+  --add '/selfservice/methods/passkey/config/rp/origins=["https://your-domain.com"]'
+```
+
+- `rp.id` is the **domain only** — no scheme, no port (`example.com`, not
+  `https://example.com:3000`).
+- `rp.origins` must list the **exact scheme+host+port** the browser uses.
+- For local dev, WebAuthn treats `localhost` as a secure origin: set
+  `rp.id="localhost"` and `rp.origins=["http://localhost:3000"]` (match your app
+  URL). Passkeys registered against `localhost` won't work on the deployed domain
+  and vice-versa.
+
+### MFA methods
+
+Enable the second factors you want. Backup codes (`lookup_secret`) should always
+be enabled alongside any other method so a user who loses their device can
+recover.
+
+```bash
+# TOTP (authenticator app)
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/totp/enabled=true' \
+  --add '/selfservice/methods/totp/config/issuer="My App"'
+
+# Backup codes
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/lookup_secret/enabled=true'
+
+# Email code as a second factor
+ory patch identity-config <project-id> \
+  --add '/selfservice/methods/code/mfa_enabled=true'
+```
+
+### Require the second factor (do not skip)
+
+Enabling a method only lets users *enroll* — it does not *require* the second
+factor. Without this step MFA is opt-in and unenforced. Set the required
+assurance level to the highest the identity has available:
+
+```bash
+ory patch identity-config <project-id> \
+  --add '/selfservice/flows/settings/required_aal="highest_available"' \
+  --add '/session/whoami/required_aal="highest_available"'
+```
+
+With `highest_available`, `toSession()` / `getServerSession()` return an
+incomplete session (AAL1) until the user clears the second factor, and Elements
+prompts for it on the next `<Login>`. Your route protection should treat an
+AAL1 session on an MFA-enrolled user as unauthenticated.
+
 ## Test the flow
 
 Don't stop at "the page renders." Run these in order — each one isolates a
@@ -415,6 +491,43 @@ If a submit fails with a CSRF error, the SDK URL is cross-site (trap #1). If a
 redirect 404s, a route doesn't match the project config (trap #2). Neither is a
 plugin bug — see the **App bug vs. plugin bug** triage in {{REF_AUTH_SETUP}}.
 
+### Writing E2E tests (Playwright)
+
+Automating these flows has three gotchas that cause flaky or wrong-for-the-wrong-
+reason failures. Get them right up front:
+
+1. **Match URLs by pattern, never literally.** Ory appends `?flow=<uuid>` on
+   every flow redirect, so an exact-string wait never matches.
+
+   ```typescript
+   await page.waitForURL(/\/auth\/login\?flow=/)   // regex
+   await page.waitForURL("**/dashboard**")          // glob — also matches query params
+   // wrong: await page.waitForURL("http://localhost:3000/auth/login")
+   ```
+
+2. **Use strong, dissimilar credentials.** Kratos rejects passwords that are too
+   similar to the identifier or that appear in a breach database — a weak fixture
+   password fails validation, not the flow you meant to test.
+
+   ```typescript
+   const email = `test-${Date.now()}-${Math.random().toString(36).slice(2)}@example.com`
+   const password = "Str0ngP@ssword!123"   // fixed, strong, not in any breach list
+   ```
+
+3. **Assert on Ory Elements' own testids, not form-level selectors.** Validation
+   messages render inside the auth card, keyed by Kratos UI message id (the
+   `4xxxxxx` range is validation errors), not on the flow wrapper.
+
+   ```typescript
+   page.locator('[data-testid^="ui/message/4"]')  // any validation error
+   page.locator('[data-testid="login-auth-card"]').getByText(/credentials|invalid/i)
+   // wrong: page.locator('[data-testid="login-flow"]').getByText(...) — errors aren't here
+   ```
+
+These selectors track the installed `@ory/elements-react` version; if a testid
+assertion breaks after an Elements upgrade, inspect the rendered DOM before
+assuming a flow bug.
+
 ## Fallback: rendering UI nodes by hand
 
 Use this path **only** when Ory Elements cannot run in the target
@@ -437,8 +550,9 @@ Ory flow API changes manually.
 - Add social login providers: use {{REF_SOCIAL_LOGIN}}.
   Elements renders the buttons automatically once providers are
   configured server-side.
-- Add multi-factor authentication via Ory project settings — the
-  `<Login>` and `<Settings>` components handle the second-factor UI.
+- Add multi-factor authentication and passkeys — see **Enable MFA and
+  passkeys** above. Once the project is configured, the `<Login>` and
+  `<Settings>` components render the second-factor and passkey UI automatically.
 - Customize the identity schema for additional profile fields. Elements
   reads the schema from the flow and renders new fields automatically.
 - Set up webhooks for registration events.

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;