@ory/argus 0.13.3 → 0.13.5

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "repo": "ory-agent-plugins",
-  "commit": "c04784bfd67acdce0133aca0ebcd335e326b9251",
-  "commitShort": "c04784b",
+  "commit": "6a1250a1a231524d64aed17df86d694f829cf938",
+  "commitShort": "6a1250a",
   "branch": "main",
-  "commitDate": "2026-07-14T15:46:39-07:00",
+  "commitDate": "2026-07-15T07:09:03-07:00",
   "dirty": false,
-  "builtAt": "2026-07-14T22:51:01.241Z"
+  "builtAt": "2026-07-15T14:13:28.336Z"
 }

package/dist/client.d.ts

@@ -58,6 +58,23 @@ export declare class OryAgentClient {
      * Ory API calls. Populated by `ensureAgentIdentity`.
      */
     private _agentPrincipal;
+    /**
+     * Admin credential — an Ory Network **project API key** (`ory_pat_…`) —
+     * used to authenticate the Keto Permission and Relationship APIs.
+     *
+     * This is deliberately distinct from the agent principal's token. Ory
+     * Network's permission APIs authenticate with a project API key and
+     * **reject project-issued OAuth2 access tokens** (a DCR client-credentials
+     * token is answered with `401 "Access token is not active"`). So when the
+     * agent identity resolves to a DCR OAuth2 client — the default path — its
+     * token cannot authenticate permission checks. Holding the admin key here
+     * lets {@link buildApis} route Keto through it while the agent OAuth2 token
+     * still authenticates the OAuth2 / Frontend APIs and carries attribution.
+     *
+     * When unset, Keto calls fall back to the agent token (legacy
+     * single-credential behavior, unchanged for static-key deployments).
+     */
+    private _adminApiKey?;
     constructor(config: OryAgentConfig);
     /** Build a fresh set of Ory API instances using the current agent token. */
     private buildApis;
@@ -78,13 +95,25 @@ export declare class OryAgentClient {
      * Pass `{}` (or fields set to undefined) to clear.
      */
     setUserPrincipal(principal: PrincipalIdentity): void;
-    /**
-     * Set or update the AI agent principal. The agent's token (when
-     * present) is used in the Authorization header for all outgoing Ory
-     * API calls — so the audit log shows "agent X acting on behalf of
-     * user Y". Rebuilds the underlying Ory API instances when the token
-     * actually changes so subsequent calls pick it up; otherwise leaves
-     * the API instances alone (so test stubs survive a no-op update).
+    /** Whether an admin API key is set for the Keto APIs (never exposes it). */
+    get hasAdminApiKey(): boolean;
+    /**
+     * Set or update the admin API key (an Ory Network project API key) used to
+     * authenticate the Keto Permission / Relationship APIs. Rebuilds those API
+     * instances when the key changes; a no-op update leaves them alone so test
+     * stubs survive. See {@link _adminApiKey} for why Keto needs a credential
+     * distinct from the agent's OAuth2 token.
+     */
+    setAdminApiKey(apiKey: string | undefined): void;
+    /**
+     * Set or update the AI agent principal. The agent's token (when present)
+     * authenticates outgoing calls to the OAuth2 / Frontend APIs and carries
+     * audit attribution ("agent X acting on behalf of user Y"). Note the Keto
+     * Permission / Relationship APIs authenticate with {@link _adminApiKey}
+     * instead when one is set — Ory Network rejects OAuth2 tokens there.
+     * Rebuilds the underlying Ory API instances when the token actually changes
+     * so subsequent calls pick it up; otherwise leaves the API instances alone
+     * (so test stubs survive a no-op update).
      */
     setAgentPrincipal(principal: PrincipalIdentity): void;
     /**
@@ -146,6 +175,15 @@ export declare class OryAgentClient {
      * across the user/agent split.
      */
     private principalSpanAttributes;
+    /**
+     * When a Keto call is auth-rejected while it was authenticated by something
+     * other than an Ory Network project API key (`ory_pat_…`) — e.g. a DCR
+     * OAuth2 access token — the credential *type* is wrong, not merely expired.
+     * Ory Network's Permission / Relationship APIs only accept a project API
+     * key. Emit an actionable hint so the failure isn't misread as a stale
+     * session (the generic `session_inactive` classification of the raw 401).
+     */
+    private warnIfKetoCredentialMismatch;
     /**
      * Classify an error from any Ory API call into a structured OryError.
      */

package/dist/client.js

@@ -42,6 +42,7 @@ const path = __importStar(require("node:path"));
 const logger_js_1 = require("./logger.js");
 const tracer_js_1 = require("./tracer.js");
 const config_js_1 = require("./config.js");
+const auth_store_js_1 = require("./auth-store.js");
 const otlp_js_1 = require("./otel/otlp.js");
 class OryAgentClient {
     frontend;
@@ -63,6 +64,23 @@ class OryAgentClient {
      * Ory API calls. Populated by `ensureAgentIdentity`.
      */
     _agentPrincipal = {};
+    /**
+     * Admin credential — an Ory Network **project API key** (`ory_pat_…`) —
+     * used to authenticate the Keto Permission and Relationship APIs.
+     *
+     * This is deliberately distinct from the agent principal's token. Ory
+     * Network's permission APIs authenticate with a project API key and
+     * **reject project-issued OAuth2 access tokens** (a DCR client-credentials
+     * token is answered with `401 "Access token is not active"`). So when the
+     * agent identity resolves to a DCR OAuth2 client — the default path — its
+     * token cannot authenticate permission checks. Holding the admin key here
+     * lets {@link buildApis} route Keto through it while the agent OAuth2 token
+     * still authenticates the OAuth2 / Frontend APIs and carries attribution.
+     *
+     * When unset, Keto calls fall back to the agent token (legacy
+     * single-credential behavior, unchanged for static-key deployments).
+     */
+    _adminApiKey;
     constructor(config) {
         this.config = config;
         this.sessionCacheTtlMs = config.sessionCacheTtlMs ?? 60_000;
@@ -83,6 +101,13 @@ class OryAgentClient {
         // call sites keep working until they migrate to ensureAgentIdentity.
         if (config.apiKey)
             this._agentPrincipal.token = config.apiKey;
+        // The `apiKey` is also the admin credential for the Keto Permission /
+        // Relationship APIs. Seed it separately so that when `ensureAgentIdentity`
+        // later replaces the agent token with a DCR OAuth2 token, permission
+        // checks keep authenticating with the project API key rather than the
+        // OAuth2 token Ory Network rejects. See {@link _adminApiKey}.
+        if (config.apiKey)
+            this._adminApiKey = config.apiKey;
         const { frontend, oauth2, permission, relationship } = this.buildApis();
         this.frontend = frontend;
         this.oauth2 = oauth2;
@@ -96,11 +121,23 @@ class OryAgentClient {
             basePath: this.config.projectUrl,
             ...(accessToken ? { accessToken } : {}),
         });
+        // Keto (Permission + Relationship) authenticates with the admin project
+        // API key when one is set; otherwise it reuses the agent token (legacy
+        // single-credential behavior). When the two credentials are identical we
+        // reuse the same Configuration object so a single-credential deployment —
+        // and tests that stub one Configuration — see exactly one.
+        const ketoToken = this._adminApiKey ?? accessToken;
+        const ketoConfig = ketoToken === accessToken
+            ? apiConfig
+            : new client_1.Configuration({
+                basePath: this.config.projectUrl,
+                ...(ketoToken ? { accessToken: ketoToken } : {}),
+            });
         return {
             frontend: new client_1.FrontendApi(apiConfig),
             oauth2: new client_1.OAuth2Api(apiConfig),
-            permission: new client_1.PermissionApi(apiConfig),
-            relationship: new client_1.RelationshipApi(apiConfig),
+            permission: new client_1.PermissionApi(ketoConfig),
+            relationship: new client_1.RelationshipApi(ketoConfig),
         };
     }
     /** Snapshot of the current user principal. */
@@ -128,13 +165,36 @@ class OryAgentClient {
     setUserPrincipal(principal) {
         this._userPrincipal = { ...principal };
     }
+    /** Whether an admin API key is set for the Keto APIs (never exposes it). */
+    get hasAdminApiKey() {
+        return !!this._adminApiKey;
+    }
     /**
-     * Set or update the AI agent principal. The agent's token (when
-     * present) is used in the Authorization header for all outgoing Ory
-     * API calls — so the audit log shows "agent X acting on behalf of
-     * user Y". Rebuilds the underlying Ory API instances when the token
-     * actually changes so subsequent calls pick it up; otherwise leaves
-     * the API instances alone (so test stubs survive a no-op update).
+     * Set or update the admin API key (an Ory Network project API key) used to
+     * authenticate the Keto Permission / Relationship APIs. Rebuilds those API
+     * instances when the key changes; a no-op update leaves them alone so test
+     * stubs survive. See {@link _adminApiKey} for why Keto needs a credential
+     * distinct from the agent's OAuth2 token.
+     */
+    setAdminApiKey(apiKey) {
+        if (this._adminApiKey === apiKey)
+            return;
+        this._adminApiKey = apiKey;
+        const { frontend, oauth2, permission, relationship } = this.buildApis();
+        this.frontend = frontend;
+        this.oauth2 = oauth2;
+        this.permission = permission;
+        this.relationship = relationship;
+    }
+    /**
+     * Set or update the AI agent principal. The agent's token (when present)
+     * authenticates outgoing calls to the OAuth2 / Frontend APIs and carries
+     * audit attribution ("agent X acting on behalf of user Y"). Note the Keto
+     * Permission / Relationship APIs authenticate with {@link _adminApiKey}
+     * instead when one is set — Ory Network rejects OAuth2 tokens there.
+     * Rebuilds the underlying Ory API instances when the token actually changes
+     * so subsequent calls pick it up; otherwise leaves the API instances alone
+     * (so test stubs survive a no-op update).
      */
     setAgentPrincipal(principal) {
         const tokenChanged = this._agentPrincipal.token !== principal.token;
@@ -320,6 +380,7 @@ class OryAgentClient {
         }
         catch (err) {
             const oryErr = this.classifyError(err);
+            this.warnIfKetoCredentialMismatch(oryErr);
             this.logger.error("permission.check.failed", {
                 code: oryErr.code,
                 status: oryErr.status,
@@ -394,6 +455,7 @@ class OryAgentClient {
         }
         catch (err) {
             const oryErr = this.classifyError(err);
+            this.warnIfKetoCredentialMismatch(oryErr);
             this.logger.error("permission.batch_check.failed", {
                 code: oryErr.code,
                 status: oryErr.status,
@@ -475,6 +537,7 @@ class OryAgentClient {
                 });
                 return { created: false, alreadyExisted: true };
             }
+            this.warnIfKetoCredentialMismatch(oryErr);
             this.logger.error("relationship.create.failed", {
                 code: oryErr.code,
                 status: oryErr.status,
@@ -534,6 +597,7 @@ class OryAgentClient {
                 });
                 return { deleted: false, notFound: true };
             }
+            this.warnIfKetoCredentialMismatch(oryErr);
             this.logger.error("relationship.delete.failed", {
                 code: oryErr.code,
                 status: oryErr.status,
@@ -560,6 +624,29 @@ class OryAgentClient {
             out.agentSubject = this._agentPrincipal.subject;
         return out;
     }
+    /**
+     * When a Keto call is auth-rejected while it was authenticated by something
+     * other than an Ory Network project API key (`ory_pat_…`) — e.g. a DCR
+     * OAuth2 access token — the credential *type* is wrong, not merely expired.
+     * Ory Network's Permission / Relationship APIs only accept a project API
+     * key. Emit an actionable hint so the failure isn't misread as a stale
+     * session (the generic `session_inactive` classification of the raw 401).
+     */
+    warnIfKetoCredentialMismatch(oryErr) {
+        if (oryErr.code !== "session_inactive" && oryErr.code !== "forbidden")
+            return;
+        const ketoToken = this._adminApiKey ?? this._agentPrincipal.token;
+        // A real project API key is already in use — treat as a genuine auth error.
+        if (typeof ketoToken === "string" && ketoToken.startsWith("ory_pat_"))
+            return;
+        this.logger.warn("permission.credential_mismatch", {
+            code: oryErr.code,
+            message: "Ory Network's Permission/Relationship APIs require a project API key " +
+                "(ory_pat_…); the agent's OAuth2 access token is not accepted. Create a " +
+                "key in the Ory Console (Project settings → API keys) and set it with " +
+                "`configure --api-key <key>` or the ORY_AGENT_API_KEY env var.",
+        });
+    }
     // ─── Error Classification ────────────────────────────────────────
     /**
      * Classify an error from any Ory API call into a structured OryError.
@@ -666,6 +753,7 @@ class OryAgentClient {
                     "Ory integration is disabled — all hooks will pass through. " +
                     "Set ORY_PROJECT_URL or run the plugin's configure command.",
             });
+            rehydrateUserPrincipal(client);
             attachOtlpExporterFromEnv(client, harness);
             return client;
         }
@@ -684,11 +772,45 @@ class OryAgentClient {
             projectUrlSource: resolved.projectUrlSource,
             apiKeySource: resolved.apiKeySource,
         });
+        rehydrateUserPrincipal(client);
         attachOtlpExporterFromEnv(client, harness);
         return client;
     }
 }
 exports.OryAgentClient = OryAgentClient;
+/**
+ * Rehydrate the user principal from persisted OAuth2 tokens.
+ *
+ * The interactive user login ({@link ensureUserAuthenticated}) populates
+ * `client.userPrincipal` in memory *and* caches the tokens to the shared
+ * config file. But subprocess-hook harnesses (claude-code, codex,
+ * gemini-cli) spawn a fresh process — and thus a fresh client via
+ * {@link OryAgentClient.fromEnv} — for every lifecycle event. Only the
+ * `SessionStart` process runs the login gate, so on later events (e.g.
+ * `PreToolUse`) the in-memory principal is gone and permission checks
+ * would fall back to a per-launch `session:<id>` subject that matches no
+ * bootstrapped tuple.
+ *
+ * Seeding the principal from the cached tokens here makes the *stable*
+ * user subject available on every constructed client, independent of which
+ * lifecycle event is running. The live login gate still overwrites this
+ * with fresh values when it runs at `SessionStart`.
+ *
+ * The subject is attached whenever it is known — even for an expired token,
+ * since the subject is what permission checks resolve against and Keto
+ * checks authenticate with the admin API key, not this token. The access
+ * token itself is only carried forward while still valid, so nothing
+ * authenticates with a stale bearer.
+ */
+function rehydrateUserPrincipal(client) {
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    if (!tokens?.subject)
+        return;
+    client.setUserPrincipal({
+        subject: tokens.subject,
+        token: (0, auth_store_js_1.isExpired)(tokens) ? undefined : tokens.accessToken,
+    });
+}
 /** Default debug-log path under the shared per-harness data dir. */
 exports.DEFAULT_DEBUG_LOG_FILENAME = "ory-agent-debug.log";
 /** Default trace (NDJSON) path under the shared per-harness data dir. */

package/dist/interactive-setup.d.ts

@@ -23,7 +23,10 @@
  * rather than re-implementing the Console API: the CLI already owns Network
  * browser login + account creation, workspace/project listing, and OAuth2
  * client creation, and the client it creates is exactly the one the plugin
- * READMEs document for manual setup.
+ * READMEs document for manual setup. The one exception is minting the project
+ * API key that runtime permission checks need — the CLI exposes no command for
+ * it, so that single step calls the Console API directly, reusing the CLI's
+ * stored session for auth (see {@link createProjectApiKeyViaConsole}).
  */
 import { OryAgentClient } from "./client.js";
 import { ensureUserAuthenticated } from "./user-login.js";
@@ -83,6 +86,20 @@ export interface InteractiveSetupDeps {
      * failed. Defaults to a real `npm install` of {@link ORY_CLI_NPM_SPEC}.
      */
     installOryCliFn?: () => Promise<OryCliRunner | null>;
+    /**
+     * Injectable project-API-key minter. Returns the `ory_pat_…` value or null on
+     * any failure. Defaults to {@link createProjectApiKeyViaConsole} (Ory Console
+     * API, authenticated with the `ory` CLI's stored session). Tests stub this to
+     * avoid real HTTP.
+     */
+    createProjectApiKeyFn?: (args: CreateProjectApiKeyArgs) => Promise<string | null>;
+    /**
+     * Injectable validity probe for an already-stored project API key. Returns
+     * true when the key still authenticates against Keto, false when it's been
+     * revoked/deleted (so provisioning re-mints one). Defaults to
+     * {@link apiKeyAuthenticates}. Tests stub this to avoid real HTTP.
+     */
+    validateApiKeyFn?: (apiKey: string, projectUrl: string) => Promise<boolean>;
 }
 export type InteractiveSetupOutcome = "skipped_flag" | "skipped_no_tty" | "skipped_configured" | "audit_only" | "local_configured" | "network_configured" | "network_fallback";
 export interface InteractiveSetupResult {
@@ -121,3 +138,28 @@ export declare function runInteractiveSetup(binName: string, harness: string, ar
  * silently misconfigure the plugin.
  */
 export declare function projectUrlFromSlug(slug: string): string;
+export interface CreateProjectApiKeyArgs {
+    projectId: string;
+    /** Human-readable label shown in the Console's API-keys list. */
+    name: string;
+}
+/**
+ * Mint an Ory Network **project API key** via the Console API
+ * (`POST /projects/{id}/tokens`), authenticated with the `ory` CLI session.
+ * Returns the `ory_pat_…` value, or null on any failure (no session, non-2xx,
+ * missing value). Never throws — provisioning is best-effort.
+ *
+ * This is the one place the wizard reaches past the `ory` CLI to the Console
+ * API: the CLI (as of v1.3) exposes no project-API-key command, and Keto
+ * permission checks can't authenticate without one.
+ */
+export declare function createProjectApiKeyViaConsole(args: CreateProjectApiKeyArgs): Promise<string | null>;
+/**
+ * Best-effort check that an already-stored project API key still authenticates
+ * against Keto. Runs one permission check with the key: if it completes (any
+ * `allowed` value) the key is valid; an auth rejection (`session_inactive` /
+ * `forbidden` / `session_aal2_required`) means it was revoked or deleted, so we
+ * return false and the caller re-provisions. Transient failures (network /
+ * rate-limit / unknown) return true so we don't re-mint on a blip. Never throws.
+ */
+export declare function apiKeyAuthenticates(apiKey: string, projectUrl: string): Promise<boolean>;

package/dist/interactive-setup.js

@@ -24,7 +24,10 @@
  * rather than re-implementing the Console API: the CLI already owns Network
  * browser login + account creation, workspace/project listing, and OAuth2
  * client creation, and the client it creates is exactly the one the plugin
- * READMEs document for manual setup.
+ * READMEs document for manual setup. The one exception is minting the project
+ * API key that runtime permission checks need — the CLI exposes no command for
+ * it, so that single step calls the Console API directly, reusing the CLI's
+ * stored session for auth (see {@link createProjectApiKeyViaConsole}).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -65,6 +68,8 @@ exports.createOryRunner = createOryRunner;
 exports.runPostInstall = runPostInstall;
 exports.runInteractiveSetup = runInteractiveSetup;
 exports.projectUrlFromSlug = projectUrlFromSlug;
+exports.createProjectApiKeyViaConsole = createProjectApiKeyViaConsole;
+exports.apiKeyAuthenticates = apiKeyAuthenticates;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
@@ -601,6 +606,12 @@ async function configureNetwork(binName, harness, ctx) {
     if (subject) {
         await bootstrapPermissionsViaOry(runner, project.id, harness, subject, prompt);
     }
+    // 10. Provision the project API key runtime permission *checks* need. Same
+    //     root cause as bootstrap's admin path — the DCR OAuth2 token can't
+    //     authenticate Ory Network's Permission API — but this credential is used
+    //     at runtime, so it's persisted to config. Placed last so its prompt
+    //     doesn't consume answers meant for earlier steps.
+    await maybeProvisionProjectApiKey(binName, harness, project.id, projectUrl, prompt, ctx.deps.createProjectApiKeyFn ?? createProjectApiKeyViaConsole, ctx.deps.validateApiKeyFn ?? apiKeyAuthenticates);
     return {
         outcome: "network_configured",
         projectUrl,
@@ -1317,3 +1328,171 @@ function printManualOAuth2ClientHelp(binName, projectId) {
     ui.blank();
     ui.command(`${(0, cli_invocation_js_1.oryNpx)(binName)} configure --oauth2-client-id <CLIENT_ID>`);
 }
+/** Ory Console API base. The `ory` CLI has no project-API-key command, so key
+ *  provisioning talks to the Console API directly, authenticated with the CLI's
+ *  stored Ory Network session. Override with `ORY_CONSOLE_API_URL`. */
+const CONSOLE_API_URL = process.env.ORY_CONSOLE_API_URL?.trim() || "https://api.console.ory.sh";
+/** Path to the session the `ory` CLI persists after `ory auth`. */
+const ORY_CLI_SESSION_FILE = ".ory-cloud.json";
+/**
+ * Read the Ory Network session bearer the `ory` CLI stores at
+ * `~/.ory-cloud.json`. Returns null when the file is absent, unparseable, has
+ * no token, or the token has expired. Never throws.
+ */
+function readConsoleSessionToken() {
+    try {
+        const raw = fs.readFileSync(path.join(os.homedir(), ORY_CLI_SESSION_FILE), "utf-8");
+        const parsed = JSON.parse(raw);
+        const token = parsed.access_token?.access_token;
+        if (!token)
+            return null;
+        const expiry = parsed.access_token?.expiry;
+        if (expiry) {
+            const expMs = Date.parse(expiry);
+            if (Number.isFinite(expMs) && expMs <= Date.now())
+                return null;
+        }
+        return token;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Mint an Ory Network **project API key** via the Console API
+ * (`POST /projects/{id}/tokens`), authenticated with the `ory` CLI session.
+ * Returns the `ory_pat_…` value, or null on any failure (no session, non-2xx,
+ * missing value). Never throws — provisioning is best-effort.
+ *
+ * This is the one place the wizard reaches past the `ory` CLI to the Console
+ * API: the CLI (as of v1.3) exposes no project-API-key command, and Keto
+ * permission checks can't authenticate without one.
+ */
+async function createProjectApiKeyViaConsole(args) {
+    const token = readConsoleSessionToken();
+    if (!token)
+        return null;
+    try {
+        const res = await fetch(`${CONSOLE_API_URL}/projects/${args.projectId}/tokens`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name: args.name }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.value === "string" && body.value.length > 0 ? body.value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort check that an already-stored project API key still authenticates
+ * against Keto. Runs one permission check with the key: if it completes (any
+ * `allowed` value) the key is valid; an auth rejection (`session_inactive` /
+ * `forbidden` / `session_aal2_required`) means it was revoked or deleted, so we
+ * return false and the caller re-provisions. Transient failures (network /
+ * rate-limit / unknown) return true so we don't re-mint on a blip. Never throws.
+ */
+async function apiKeyAuthenticates(apiKey, projectUrl) {
+    try {
+        // Direct construction (no fromEnv) seeds the key as both agent token and
+        // admin key and skips DCR, so the probe uses exactly this key. No trace
+        // file is configured, so nothing is written to disk.
+        const probe = new client_js_1.OryAgentClient({ projectUrl, apiKey, harness: "install-probe" });
+        await probe.checkPermission({
+            namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
+            object: "__ory_agent_key_probe__",
+            relation: "__ory_agent_key_probe__",
+            subjectId: "__ory_agent_key_probe__",
+        });
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "session_inactive" || code === "forbidden" || code === "session_aal2_required") {
+            return false;
+        }
+        return true;
+    }
+}
+/**
+ * Manual fallback steps for the project API key, shown when auto-provisioning
+ * is declined or fails. The `configure --api-key` command is the stable part;
+ * the Console link is a convenience.
+ */
+function printManualApiKeySteps(binName, projectId) {
+    ui.info("Create one in the Ory Console (Project settings → API keys):");
+    ui.command(`https://console.ory.sh/projects/${projectId}/settings`);
+    ui.info("then store it so permission checks authenticate with it:");
+    ui.command(`${(0, cli_invocation_js_1.oryNpx)(binName)} configure --api-key <ory_pat_…>`);
+    ui.hint("Observe mode works without it; enforce mode needs it to allow tools.");
+}
+/**
+ * Provision the project API key that runtime Keto permission checks
+ * authenticate with. The agent's DCR OAuth2 token can't — Ory Network rejects
+ * it — so `enforce` mode needs a project API key. Best-effort and skippable:
+ * offers to mint one via the Console API and persist it, and on decline / no
+ * TTY / any failure falls back to manual guidance. No-ops when a key is already
+ * configured (env or config file).
+ */
+async function maybeProvisionProjectApiKey(binName, harness, projectId, projectUrl, prompt, createFn, validateFn) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    if (resolved.apiKey) {
+        // An operator-set env key is authoritative — never touch it.
+        if (resolved.apiKeySource === "env")
+            return;
+        // A stored (config-file) key that no longer authenticates — revoked or
+        // deleted — must not wedge setup: validate it and re-provision if it's
+        // dead. Presence alone isn't enough (a dangling key still fails at runtime
+        // with session_inactive).
+        if (await validateFn(resolved.apiKey, projectUrl))
+            return;
+        ui.heading("Project API key");
+        ui.warning("The stored project API key is no longer valid (revoked or deleted).");
+    }
+    else {
+        ui.heading("Project API key");
+        ui.info("Runtime permission checks call Ory's Permission API, which authenticates");
+        ui.hint("with a project API key — the agent's OAuth2 token isn't accepted there.");
+        ui.hint("(Observe mode works without it; enforce mode needs it to allow tools.)");
+    }
+    ui.blank();
+    const answer = await prompt(ui.promptLine("Create a project API key now and store it?", { hint: "[Y/n]" }));
+    // `null` = no TTY / cancelled; treat as skip so we never mint without consent.
+    if (answer !== null && !isNo(answer)) {
+        ui.step("Creating a project API key via the Ory Console…");
+        let key = null;
+        try {
+            // Name each key uniquely (harness + host + timestamp) so keys are
+            // distinguishable in the Console and a re-provision never collides with
+            // an existing entry.
+            key = await createFn({ projectId, name: projectApiKeyName(harness) });
+        }
+        catch {
+            key = null;
+        }
+        if (key) {
+            (0, config_js_1.saveConfig)({ apiKey: key });
+            ui.success("Project API key created and stored — permission checks will use it.");
+            return;
+        }
+        ui.warning("Couldn't create a project API key automatically (Console session may be missing or expired).");
+    }
+    printManualApiKeySteps(binName, projectId);
+}
+/** Distinguishable, collision-free label for a provisioned project API key. */
+function projectApiKeyName(harness) {
+    let host = "unknown-host";
+    try {
+        host = os.hostname();
+    }
+    catch {
+        /* keep fallback */
+    }
+    return `ory-agent-plugins ${harness} ${host} ${new Date().toISOString()}`;
+}

package/dist/permissions-cli.js

@@ -71,21 +71,6 @@ const ENV_PERMISSION_MODE = "ORY_PERMISSION_MODE";
 function resolveNamespace() {
     return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
 }
-/**
- * Apply persisted user OAuth2 tokens (if any) to the client's user
- * principal so downstream subject resolution and tuple writes see a
- * concrete identity. Mirrors what `ensureUserAuthenticated` does on a
- * cache hit — but works whether or not `ORY_USER_LOGIN` is enabled.
- */
-function attachCachedUserPrincipal(client) {
-    const tokens = (0, auth_store_js_1.loadTokens)();
-    if (!tokens || (0, auth_store_js_1.isExpired)(tokens))
-        return;
-    client.setUserPrincipal({
-        subject: tokens.subject,
-        token: tokens.accessToken,
-    });
-}
 /**
  * Entry point invoked by each harness CLI's `permissions` case.
  *
@@ -178,7 +163,6 @@ async function runPermissionsStatus(binName, harness) {
         return 0;
     }
     const client = client_js_1.OryAgentClient.fromEnv(harness);
-    attachCachedUserPrincipal(client);
     await (0, agent_auth_js_1.ensureAgentIdentity)(client, { projectUrl: resolved.projectUrl }).catch(() => {
         /* best-effort; status keeps working in pass-through */
     });
@@ -260,7 +244,6 @@ async function runPermissionsBootstrap(binName, harness, args) {
         return 1;
     }
     const client = client_js_1.OryAgentClient.fromEnv(harness);
-    attachCachedUserPrincipal(client);
     await (0, agent_auth_js_1.ensureAgentIdentity)(client, { projectUrl: resolved.projectUrl }).catch(() => {
         /* best-effort; the write may still succeed with the API key or no auth (local Keto) */
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",