@ory/argus 0.14.0 → 1.0.1

package/dist/config.js

@@ -33,19 +33,49 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_AGENT_SECURITY_URL = exports.DEFAULT_AGENT_SECURITY_URL = exports.DEFAULT_OAUTH2_CLIENT_ID = exports.SESSIONLESS_KEY = exports.UNKNOWN_HARNESS_KEY = exports.DELEGATION_NODE_HISTORY = void 0;
 exports.getDataDir = getDataDir;
 exports.getHarnessDataDir = getHarnessDataDir;
 exports.getConfigPath = getConfigPath;
 exports.loadConfig = loadConfig;
+exports.listInstalledHarnesses = listInstalledHarnesses;
+exports.registerInstalledHarness = registerInstalledHarness;
+exports.unregisterInstalledHarness = unregisterInstalledHarness;
 exports.saveConfig = saveConfig;
 exports.mutateConfig = mutateConfig;
 exports.looksLikeProjectId = looksLikeProjectId;
+exports.isSecurityConnected = isSecurityConnected;
+exports.describeSecurityGap = describeSecurityGap;
 exports.resolveConfig = resolveConfig;
 exports.configPromptMessage = configPromptMessage;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const cli_invocation_js_1 = require("./cli-invocation.js");
+/**
+ * How many sessions' delegation node ids to keep per credential. Only the
+ * current session's is ever read; the rest are kept as a small audit tail and
+ * bounded so a long-lived install's config doesn't grow without limit.
+ */
+exports.DELEGATION_NODE_HISTORY = 10;
+/**
+ * Key used when a credential record carries no harness of its own — only
+ * reachable by migrating a config written before credentials were keyed by
+ * harness, where the `harness` field had never been persisted. Such a record
+ * is never re-used (no harness matches it), but it stays addressable so
+ * uninstall can still revoke the server-side client rather than orphaning it.
+ */
+exports.UNKNOWN_HARNESS_KEY = "unknown";
+/**
+ * Session key for a caller with no session concept — an Agent SDK integration
+ * embedded in a long-running service, or a one-off script. Such a caller gets
+ * one stable identity under this key rather than a new client per call, which
+ * is the only sensible reading of "per session" when there are no sessions.
+ * Credentials migrated from a config written before session keying also land
+ * here: the session they belonged to is not recoverable, but the record stays
+ * addressable so uninstall can revoke it.
+ */
+exports.SESSIONLESS_KEY = "sessionless";
 /**
  * Single OS-agnostic data directory for *all* Ory agent plugin state:
  * the shared config file, persisted DCR credentials, and any harness
@@ -116,6 +146,7 @@ function loadConfig() {
         const parsed = JSON.parse(raw);
         return {
             projectUrl: typeof parsed.projectUrl === "string" ? parsed.projectUrl : undefined,
+            agentSecurityUrl: typeof parsed.agentSecurityUrl === "string" ? parsed.agentSecurityUrl : undefined,
             projectId: typeof parsed.projectId === "string" && parsed.projectId.trim()
                 ? parsed.projectId.trim()
                 : undefined,
@@ -125,16 +156,17 @@ function loadConfig() {
             workspaceName: typeof parsed.workspaceName === "string" && parsed.workspaceName.trim()
                 ? parsed.workspaceName.trim()
                 : undefined,
-            apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : undefined,
-            apiKeyId: typeof parsed.apiKeyId === "string" && parsed.apiKeyId.trim()
-                ? parsed.apiKeyId.trim()
-                : undefined,
             oauth2ClientId: typeof parsed.oauth2ClientId === "string" ? parsed.oauth2ClientId : undefined,
-            auditOnly: parsed.auditOnly === true ? true : undefined,
-            permissionMode: parsePermissionMode(parsed.permissionMode),
+            // NOTE: a `dxOnly` key written by an older release is deliberately not
+            // parsed. Whether Agent Security runs is derived from the presence of
+            // `projectUrl` + `oauth2ClientId` (see resolveConfig), never from a
+            // stored flag — so the stale key is simply dropped on the next write.
+            permissionModeCache: parsePermissionModeCache(parsed),
             userSubjectNamespace: typeof parsed.userSubjectNamespace === "string" && parsed.userSubjectNamespace.trim()
                 ? parsed.userSubjectNamespace.trim()
                 : undefined,
+            installedHarnesses: parseInstalledHarnesses(parsed.installedHarnesses),
+            delegationAnchors: parseDelegationAnchors(parsed.delegationAnchors),
             user: parseUserCredentials(parsed),
             agent: parseAgentCredentials(parsed),
         };
@@ -143,32 +175,195 @@ function loadConfig() {
         return {};
     }
 }
+function parseDelegationAnchors(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const result = {};
+    for (const [harness, rawSessions] of Object.entries(value)) {
+        if (!rawSessions || typeof rawSessions !== "object" || Array.isArray(rawSessions))
+            continue;
+        const sessions = {};
+        for (const [session, nodeId] of Object.entries(rawSessions)) {
+            if (typeof nodeId === "string" && nodeId.length > 0)
+                sessions[session] = nodeId;
+        }
+        if (Object.keys(sessions).length > 0)
+            result[harness] = sessions;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function parsePermissionMode(value) {
     return value === "observe" || value === "enforce" ? value : undefined;
 }
+/**
+ * Parse the persisted {@link PermissionModeCache}. Also migrates a legacy
+ * top-level `permissionMode` string (the old user-set field) into the cache so
+ * an upgrade preserves the last posture until the first server read overwrites
+ * it (`fetchedAt: 0` marks it as never-server-confirmed).
+ */
+function parsePermissionModeCache(parsed) {
+    const raw = parsed.permissionModeCache;
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        const mode = parsePermissionMode(obj.mode);
+        if (mode) {
+            const fetchedAt = typeof obj.fetchedAt === "number" ? obj.fetchedAt : 0;
+            const scopes = {};
+            if (obj.scopes && typeof obj.scopes === "object") {
+                for (const [key, value] of Object.entries(obj.scopes)) {
+                    if (!value || typeof value !== "object")
+                        continue;
+                    const entry = value;
+                    const entryMode = parsePermissionMode(entry.mode);
+                    if (!entryMode)
+                        continue;
+                    scopes[key] = {
+                        mode: entryMode,
+                        fetchedAt: typeof entry.fetchedAt === "number" ? entry.fetchedAt : 0,
+                    };
+                }
+            }
+            return {
+                mode,
+                fetchedAt,
+                ...(typeof obj.projectUrl === "string" ? { projectUrl: obj.projectUrl } : {}),
+                ...(Object.keys(scopes).length ? { scopes } : {}),
+            };
+        }
+    }
+    const legacy = parsePermissionMode(parsed.permissionMode);
+    if (legacy)
+        return { mode: legacy, fetchedAt: 0 };
+    return undefined;
+}
 function parseAgentCredentials(parsed) {
     const raw = parsed.agent;
     if (!raw || typeof raw !== "object")
         return undefined;
     const block = raw;
-    const dynamic = parseAgentDynamicCredentials(block.dynamic);
+    const retired = parseRetiredCredentials(block.retired);
+    const dynamic = parseAgentDynamicByHarness(block.dynamic);
     const subAgents = parseSubAgentCredentials(block.subAgents);
-    if (!dynamic && !subAgents)
+    if (!dynamic && !subAgents && retired.length === 0)
         return undefined;
     return {
         ...(dynamic ? { dynamic } : {}),
         ...(subAgents ? { subAgents } : {}),
+        ...(retired.length > 0 ? { retired } : {}),
+    };
+}
+function parseRetiredCredentials(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const creds = parseAgentDynamicCredentials(entry);
+        if (creds)
+            out.push(creds);
+    }
+    return out;
+}
+/**
+ * True when `value` is a credential record itself rather than a map of them.
+ * A credential record always carries a string `clientId`; a keyed map never
+ * does. This is what lets the parser accept both the current harness-keyed
+ * shape and the pre-migration flat shape without a version field.
+ */
+function looksLikeCredentialRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    return typeof value.clientId === "string";
+}
+/**
+ * Parse `agent.dynamic` into `{ [harness]: { [session]: creds } }`.
+ *
+ * Three shapes have existed, and each is recognizable without a version field
+ * because only a credential record carries a string `clientId`:
+ *
+ *   1. one bare record                       — pre-harness keying
+ *   2. `{ [harness]: creds }`                — install-scoped release
+ *   3. `{ [harness]: { [session]: creds } }` — current
+ *
+ * Records without a known session migrate to {@link SESSIONLESS_KEY}.
+ */
+function parseAgentDynamicByHarness(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const result = {};
+    const put = (harness, session, creds) => {
+        (result[harness] ??= {})[session] = creds;
     };
+    // Shape 1: a single bare record, re-keyed under the harness it names.
+    if (looksLikeCredentialRecord(value)) {
+        const legacy = parseAgentDynamicCredentials(value);
+        if (!legacy)
+            return undefined;
+        put(legacy.harness ?? exports.UNKNOWN_HARNESS_KEY, exports.SESSIONLESS_KEY, legacy);
+        return result;
+    }
+    for (const [harness, raw] of Object.entries(value)) {
+        // Shape 2: harness → one install-scoped record.
+        if (looksLikeCredentialRecord(raw)) {
+            const creds = parseAgentDynamicCredentials(raw);
+            if (creds)
+                put(harness, exports.SESSIONLESS_KEY, creds);
+            continue;
+        }
+        // Shape 3: harness → session → record.
+        if (!raw || typeof raw !== "object")
+            continue;
+        for (const [session, entry] of Object.entries(raw)) {
+            const creds = parseAgentDynamicCredentials(entry);
+            if (creds)
+                put(harness, session, creds);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
 }
+/**
+ * Parse `agent.subAgents` into
+ * `{ [harness]: { [session]: { [type]: creds } } }`.
+ *
+ * As with `agent.dynamic`, three shapes have existed:
+ *
+ *   1. `{ [type]: creds }`                              — pre-harness keying
+ *   2. `{ [harness]: { [type]: creds } }`                — install-scoped release
+ *   3. `{ [harness]: { [session]: { [type]: creds } } }` — current
+ */
 function parseSubAgentCredentials(value) {
     if (!value || typeof value !== "object")
         return undefined;
-    const entries = value;
     const result = {};
-    for (const [key, raw] of Object.entries(entries)) {
-        const creds = parseAgentDynamicCredentials(raw);
-        if (creds)
-            result[key] = creds;
+    const put = (harness, session, subAgentType, creds) => {
+        ((result[harness] ??= {})[session] ??= {})[subAgentType] = creds;
+    };
+    for (const [key, raw] of Object.entries(value)) {
+        // Shape 1: `key` is the sub-agent type; the harness comes from the record.
+        if (looksLikeCredentialRecord(raw)) {
+            const creds = parseAgentDynamicCredentials(raw);
+            if (creds)
+                put(creds.harness ?? exports.UNKNOWN_HARNESS_KEY, exports.SESSIONLESS_KEY, key, creds);
+            continue;
+        }
+        if (!raw || typeof raw !== "object")
+            continue;
+        for (const [inner, entry] of Object.entries(raw)) {
+            // Shape 2: `inner` is the sub-agent type, sitting directly under harness.
+            if (looksLikeCredentialRecord(entry)) {
+                const creds = parseAgentDynamicCredentials(entry);
+                if (creds)
+                    put(key, exports.SESSIONLESS_KEY, inner, creds);
+                continue;
+            }
+            // Shape 3: `inner` is the session.
+            if (!entry || typeof entry !== "object")
+                continue;
+            for (const [subAgentType, leaf] of Object.entries(entry)) {
+                const creds = parseAgentDynamicCredentials(leaf);
+                if (creds)
+                    put(key, inner, subAgentType, creds);
+            }
+        }
     }
     return Object.keys(result).length > 0 ? result : undefined;
 }
@@ -192,8 +387,33 @@ function parseAgentDynamicCredentials(value) {
         ...(parseDelegationRecord(v.delegation)
             ? { delegation: parseDelegationRecord(v.delegation) }
             : {}),
+        ...(parseDelegationNodeIds(v.delegationNodeIds, v.delegationNodeId)
+            ? { delegationNodeIds: parseDelegationNodeIds(v.delegationNodeIds, v.delegationNodeId) }
+            : {}),
     };
 }
+/**
+ * Parse the per-session delegation node map, migrating the single
+ * `delegationNodeId` field earlier releases wrote.
+ *
+ * A migrated scalar lands under {@link SESSIONLESS_KEY}: the session it was
+ * recorded in was never persisted alongside it, and guessing would attribute a
+ * sub-agent to the wrong run. Landing it there means the next session records
+ * its own node id rather than inheriting a stale one — the correct outcome,
+ * since the node id is cheap to re-obtain (the broker's write is idempotent).
+ */
+function parseDelegationNodeIds(value, legacy) {
+    const result = {};
+    if (typeof legacy === "string" && legacy.length > 0)
+        result[exports.SESSIONLESS_KEY] = legacy;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        for (const [session, nodeId] of Object.entries(value)) {
+            if (typeof nodeId === "string" && nodeId.length > 0)
+                result[session] = nodeId;
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function parseDelegationRecord(value) {
     if (!value || typeof value !== "object")
         return undefined;
@@ -211,6 +431,57 @@ function parseDelegationRecord(value) {
         delegatedAt: typeof v.delegatedAt === "string" ? v.delegatedAt : "",
     };
 }
+function parseInstalledHarnesses(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const names = normalizeHarnessList(value.filter((v) => typeof v === "string"));
+    return names.length > 0 ? names : undefined;
+}
+/** De-duplicate, trim, and sort a harness list so the file stays stable. */
+function normalizeHarnessList(names) {
+    return [...new Set(names.map((n) => n.trim()).filter((n) => n.length > 0))].sort();
+}
+/**
+ * The harness plugins recorded as installed against this shared config.
+ * Returns an empty array when nothing has been registered yet (which, on a
+ * config written before the registry existed, is not the same as "nothing is
+ * installed" — callers that must not over-read that should reconcile against
+ * the runtime manifest and persisted credentials; see
+ * `resolveInstalledHarnesses` in `uninstall.ts`).
+ */
+function listInstalledHarnesses() {
+    return loadConfig().installedHarnesses ?? [];
+}
+/**
+ * Record a harness plugin as installed. Idempotent — installing twice leaves
+ * one entry. Returns the full list after the addition.
+ */
+function registerInstalledHarness(harness) {
+    let result = [];
+    mutateConfig((current) => {
+        result = normalizeHarnessList([...(current.installedHarnesses ?? []), harness]);
+        return { ...current, installedHarnesses: result };
+    });
+    return result;
+}
+/**
+ * Forget a harness plugin. Returns the harnesses still installed afterwards —
+ * what the uninstall path uses to decide whether the shared config is now
+ * unreferenced and safe to wipe.
+ */
+function unregisterInstalledHarness(harness) {
+    let result = [];
+    mutateConfig((current) => {
+        result = normalizeHarnessList(current.installedHarnesses ?? []).filter((h) => h !== harness.trim());
+        const next = { ...current };
+        if (result.length > 0)
+            next.installedHarnesses = result;
+        else
+            delete next.installedHarnesses;
+        return next;
+    });
+    return result;
+}
 function parseUserCredentials(parsed) {
     // Prefer the new nested shape; fall back to the legacy root-level
     // `oauth2` block so configs written before the user/agent split still
@@ -236,9 +507,6 @@ function parseOAuth2(value) {
         refreshToken: typeof v.refreshToken === "string" ? v.refreshToken : undefined,
         expiresAt: v.expiresAt,
         subject: typeof v.subject === "string" ? v.subject : undefined,
-        clientId: typeof v.clientId === "string" ? v.clientId : undefined,
-        idToken: typeof v.idToken === "string" ? v.idToken : undefined,
-        scope: typeof v.scope === "string" ? v.scope : undefined,
     };
 }
 /**
@@ -265,7 +533,8 @@ function mutateConfig(mutator) {
     try {
         const existing = loadConfig();
         const next = mutator(existing);
-        writeConfigAtomic(next);
+        if (next)
+            writeConfigAtomic(next);
     }
     finally {
         releaseLock(lock);
@@ -384,9 +653,101 @@ function releaseLock(lock) {
 function writeConfigAtomic(config) {
     const target = configFile();
     const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    fs.writeFileSync(tmp, JSON.stringify(compactPersistedConfig(config), null, 2) + "\n", {
+        mode: 0o600,
+    });
     fs.renameSync(tmp, target);
 }
+/**
+ * Keep only state that cannot be reconstructed safely in a later process.
+ * This is the one persistence boundary, so old verbose records are compacted
+ * by any subsequent config mutation regardless of which subsystem writes.
+ */
+function compactPersistedConfig(config) {
+    const userTokens = config.user?.oauth2;
+    const user = userTokens
+        ? {
+            oauth2: {
+                accessToken: userTokens.accessToken,
+                ...(userTokens.refreshToken ? { refreshToken: userTokens.refreshToken } : {}),
+                expiresAt: userTokens.expiresAt,
+                ...(userTokens.subject ? { subject: userTokens.subject } : {}),
+            },
+        }
+        : undefined;
+    const active = (creds) => ({
+        clientId: creds.clientId,
+        ...(creds.clientSecret ? { clientSecret: creds.clientSecret } : {}),
+        ...(creds.registrationAccessToken
+            ? { registrationAccessToken: creds.registrationAccessToken }
+            : {}),
+        ...(creds.registrationClientUri
+            ? { registrationClientUri: creds.registrationClientUri }
+            : {}),
+        registeredAt: creds.registeredAt,
+        projectUrl: creds.projectUrl,
+        ...(creds.delegation
+            ? {
+                delegation: {
+                    delegatedBy: creds.delegation.delegatedBy,
+                    delegationType: creds.delegation.delegationType,
+                },
+            }
+            : {}),
+        ...(creds.delegationNodeIds
+            ? { delegationNodeIds: creds.delegationNodeIds }
+            : {}),
+    });
+    const dynamic = config.agent?.dynamic
+        ? Object.fromEntries(Object.entries(config.agent.dynamic).map(([harness, sessions]) => [
+            harness,
+            Object.fromEntries(Object.entries(sessions).map(([session, creds]) => [session, active(creds)])),
+        ]))
+        : undefined;
+    const subAgents = config.agent?.subAgents
+        ? Object.fromEntries(Object.entries(config.agent.subAgents).map(([harness, sessions]) => [
+            harness,
+            Object.fromEntries(Object.entries(sessions).map(([session, byType]) => [
+                session,
+                Object.fromEntries(Object.entries(byType).map(([type, creds]) => [type, active(creds)])),
+            ])),
+        ]))
+        : undefined;
+    const retired = config.agent?.retired?.map((creds) => ({
+        clientId: creds.clientId,
+        projectUrl: creds.projectUrl,
+        ...(creds.harness ? { harness: creds.harness } : {}),
+        ...(creds.registrationAccessToken
+            ? { registrationAccessToken: creds.registrationAccessToken }
+            : {}),
+        ...(creds.registrationClientUri
+            ? { registrationClientUri: creds.registrationClientUri }
+            : {}),
+    }));
+    const agent = dynamic || subAgents || retired?.length
+        ? {
+            ...(dynamic ? { dynamic } : {}),
+            ...(subAgents ? { subAgents } : {}),
+            ...(retired?.length ? { retired } : {}),
+        }
+        : undefined;
+    return {
+        ...(config.projectUrl ? { projectUrl: config.projectUrl } : {}),
+        ...(config.agentSecurityUrl ? { agentSecurityUrl: config.agentSecurityUrl } : {}),
+        ...(config.projectId ? { projectId: config.projectId } : {}),
+        ...(config.oauth2ClientId ? { oauth2ClientId: config.oauth2ClientId } : {}),
+        ...(config.permissionModeCache ? { permissionModeCache: config.permissionModeCache } : {}),
+        ...(config.userSubjectNamespace
+            ? { userSubjectNamespace: config.userSubjectNamespace }
+            : {}),
+        ...(config.installedHarnesses?.length
+            ? { installedHarnesses: config.installedHarnesses }
+            : {}),
+        ...(config.delegationAnchors ? { delegationAnchors: config.delegationAnchors } : {}),
+        ...(user ? { user } : {}),
+        ...(agent ? { agent } : {}),
+    };
+}
 /** Matches an Ory project UUID (the value `ORY_PROJECT_ID` carries). */
 const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
@@ -402,6 +763,47 @@ const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]
 function looksLikeProjectId(value) {
     return PROJECT_ID_RE.test(value.trim());
 }
+/** Reserved public PKCE client provisioned by Ory Agent Security setup. */
+exports.DEFAULT_OAUTH2_CLIENT_ID = "ory-agent-security-login";
+exports.DEFAULT_AGENT_SECURITY_URL = "https://agents.console.ory.com";
+exports.LOCAL_AGENT_SECURITY_URL = "https://agents.console.ory:8080";
+function resolveSecurityConnection(projectUrl, agentSecurityUrl, oauth2ClientId) {
+    const missing = [];
+    if (!projectUrl?.trim())
+        missing.push("projectUrl");
+    if (!agentSecurityUrl?.trim())
+        missing.push("agentSecurityUrl");
+    if (!oauth2ClientId?.trim())
+        missing.push("oauth2ClientId");
+    return { connected: missing.length === 0, missing };
+}
+/**
+ * The one predicate the gates ask: is Agent Security connected?
+ *
+ * Shorthand for `resolveConfig().security.connected`, provided so the many
+ * call sites that only need the boolean read as a single question rather than
+ * a property walk. When this is false the plugin still runs — it just logs activity
+ * locally and gates nothing.
+ */
+function isSecurityConnected() {
+    return resolveConfig().security.connected;
+}
+/** The CLI flag / env var a user sets for each required value. */
+const SECURITY_VALUE_LABELS = {
+    projectUrl: "--project-url (ORY_PROJECT_URL)",
+    agentSecurityUrl: "--agent-security-url (ORY_AGENT_SECURITY_URL)",
+    oauth2ClientId: "--oauth2-client-id (ORY_OAUTH2_CLIENT_ID)",
+};
+/**
+ * Render why Agent Security isn't running, e.g.
+ * `"missing --oauth2-client-id (ORY_OAUTH2_CLIENT_ID)"`. Returns undefined when
+ * it *is* connected, so callers can `?? "connected"` at the display site.
+ */
+function describeSecurityGap(security = resolveConfig().security) {
+    if (security.connected)
+        return undefined;
+    return `missing ${security.missing.map((m) => SECURITY_VALUE_LABELS[m]).join(" and ")}`;
+}
 /**
  * Resolve config by checking environment variables first, then the config file.
  * Returns the merged result with the source of each value.
@@ -416,20 +818,17 @@ function resolveConfig() {
     // ORY_PROJECT_URL is the documented name; ORY_SDK_URL is the name the Ory
     // Console "Get Started" panel and the Ory SDKs use — accepted as an alias.
     const envProjectUrl = process.env.ORY_PROJECT_URL?.trim() || process.env.ORY_SDK_URL?.trim() || undefined;
+    const envAgentSecurityUrl = process.env.ORY_AGENT_SECURITY_URL?.trim() || undefined;
     const envProjectId = process.env.ORY_PROJECT_ID?.trim() || undefined;
-    // ORY_AGENT_API_KEY is the documented name; ORY_API_KEY is the deprecated
-    // alias kept for back-compat (agent-auth emits a warning when only the
-    // legacy form is set).
-    const envApiKey = process.env.ORY_AGENT_API_KEY ?? process.env.ORY_API_KEY;
-    const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
-    const envMode = parsePermissionMode(process.env.ORY_PERMISSION_MODE);
+    const envClientId = process.env.ORY_OAUTH2_CLIENT_ID?.trim() || undefined;
     const envUserSubjectNamespace = process.env.ORY_USER_SUBJECT_NAMESPACE?.trim() || undefined;
-    const permissionMode = envMode ?? file.permissionMode ?? "observe";
-    const permissionModeSource = envMode
-        ? "env"
-        : file.permissionMode
-            ? "config"
-            : "default";
+    // The mode is server-controlled (a Keto permission read per-check by
+    // resolvePermissionMode). Here we only surface the last cached value for the
+    // synchronous read path; there is no env or local override.
+    const permissionMode = file.permissionModeCache?.mode ?? "observe";
+    const permissionModeSource = file.permissionModeCache
+        ? "cache"
+        : "default";
     const projectId = envProjectId ?? file.projectId;
     // The SDK URL is only ever an explicit, slug-based URL (from ORY_PROJECT_URL,
     // ORY_SDK_URL, or the config file). The project id is NOT a URL source — it
@@ -440,16 +839,33 @@ function resolveConfig() {
         : file.projectUrl
             ? "config"
             : "none";
+    // Preserve the project URL fallback only for persisted pre-default configs.
+    // New env-only and configure flows use the production default unless they
+    // explicitly select staging, local, or a custom broker.
+    const legacyAgentSecurityUrl = !envProjectUrl && file.projectUrl?.trim() && !file.agentSecurityUrl ? file.projectUrl.trim() : undefined;
+    const agentSecurityUrl = envAgentSecurityUrl ?? file.agentSecurityUrl ?? legacyAgentSecurityUrl ?? exports.DEFAULT_AGENT_SECURITY_URL;
+    const agentSecurityUrlSource = envAgentSecurityUrl
+        ? "env"
+        : file.agentSecurityUrl
+            ? "config"
+            : legacyAgentSecurityUrl
+                ? "projectUrl"
+                : "default";
+    const fileClientId = file.oauth2ClientId?.trim() || undefined;
+    const oauth2ClientId = envClientId ?? fileClientId ?? exports.DEFAULT_OAUTH2_CLIENT_ID;
     return {
         projectUrl,
+        agentSecurityUrl,
         projectId,
         projectName: file.projectName,
         workspaceName: file.workspaceName,
-        apiKey: envApiKey ?? file.apiKey,
-        oauth2ClientId: envClientId ?? file.oauth2ClientId,
-        auditOnly: file.auditOnly === true,
+        oauth2ClientId,
+        // Agent Security runs exactly when all resolved values it needs are present.
+        // The broker origin can resolve through the legacy project URL fallback.
+        security: resolveSecurityConnection(projectUrl, agentSecurityUrl, oauth2ClientId),
         permissionMode,
         permissionModeSource,
+        permissionModeCache: file.permissionModeCache,
         userSubjectNamespace: envUserSubjectNamespace ?? file.userSubjectNamespace,
         userSubjectNamespaceSource: envUserSubjectNamespace
             ? "env"
@@ -457,22 +873,25 @@ function resolveConfig() {
                 ? "config"
                 : "none",
         projectUrlSource,
+        agentSecurityUrlSource,
         projectIdSource: envProjectId ? "env" : file.projectId ? "config" : "none",
-        apiKeySource: envApiKey ? "env" : file.apiKey ? "config" : "none",
-        oauth2ClientIdSource: envClientId ? "env" : file.oauth2ClientId ? "config" : "none",
+        oauth2ClientIdSource: envClientId ? "env" : fileClientId ? "config" : "default",
     };
 }
 /**
- * Build the "not configured" prompt message for a given harness CLI bin name.
+ * Build the "Agent Security is not connected" message for a harness CLI.
+ *
+ * Deliberately does not frame this as a degraded mode: the plugin is fully
+ * installed and its developer-experience half is working. The message states
+ * the one thing that is off and the values that turn it on.
  */
 function configPromptMessage(binName) {
-    return ("The Ory agent plugin is installed but not yet configured.\n" +
-        "\n" +
-        "  Option 1 — Connect to Ory (enables authentication and permission checks):\n" +
-        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]\n` +
+    return ("Ory Agent Security is not connected, so no sign-in or permission checks\n" +
+        "run. Everything else the plugin installs — skills, commands, the local Ory\n" +
+        "stack, the MCP server, and local activity logging — works as it is.\n" +
         "\n" +
-        "  Option 2 — Continue without authentication (audit logging only):\n" +
-        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --audit-only\n` +
+        "  Connect it with the values from the Ory Console (Agent Security):\n" +
+        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url <URL>\n` +
         "\n" +
         `Configuration is saved to ${configFile()} and shared across all agent plugins.`);
 }

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeCredential } from "./runtime-credential.js";
+export interface SessionContext {
+    sessionId?: string;
+    runtimeCredential?: RuntimeCredential;
+}
+export declare function currentSessionContext(): Readonly<SessionContext>;
+export declare function withSessionContext<T>(context: SessionContext, work: () => T): T;
+/** Test and low-level integration helper. Prefer `withHookContext` in adapters. */
+export declare function setSessionContext(context: SessionContext): void;
+export declare function clearSessionContext(): void;

package/dist/context.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentSessionContext = currentSessionContext;
+exports.withSessionContext = withSessionContext;
+exports.setSessionContext = setSessionContext;
+exports.clearSessionContext = clearSessionContext;
+const node_async_hooks_1 = require("node:async_hooks");
+const sessionStorage = new node_async_hooks_1.AsyncLocalStorage();
+function currentSessionContext() {
+    return sessionStorage.getStore() ?? {};
+}
+function withSessionContext(context, work) {
+    return sessionStorage.run({ ...currentSessionContext(), ...context }, work);
+}
+/** Test and low-level integration helper. Prefer `withHookContext` in adapters. */
+function setSessionContext(context) {
+    sessionStorage.enterWith({ ...context });
+}
+function clearSessionContext() {
+    sessionStorage.enterWith({});
+}