@ory/argus 1.2.4 → 1.3.1

package/dist/client.js

@@ -81,6 +81,7 @@ class OryAgentClient {
     logger;
     eventReporter;
     _runtimeCredential;
+    _runtimeContext;
     _runtimeCredentialsBySession = new Map();
     _runtimeCredentialsByPrincipalKey = new Map();
     sessionCache = new Map();
@@ -341,6 +342,17 @@ class OryAgentClient {
     get hasRuntimeCredential() {
         return this.runtimeCredential !== undefined;
     }
+    /** Process-local deployment context. It is never persisted or copied to the environment. */
+    get runtimeContext() {
+        return this._runtimeContext ? { ...this._runtimeContext } : undefined;
+    }
+    get runtimeRootDelegation() {
+        return this._runtimeContext?.rootDelegation;
+    }
+    setRuntimeContext(context) {
+        this._runtimeContext = { ...context };
+        this.setAgentPrincipal({ subject: context.subjectId });
+    }
     setRuntimeCredential(credential) {
         const sessionId = this.sessionId?.trim();
         if (sessionId) {
@@ -441,7 +453,10 @@ class OryAgentClient {
                             emitActivity: false,
                             signal: controller.signal,
                         }));
-                        if (identity.subject && identity.token) {
+                        if (identity.runtimeCredential) {
+                            this.rememberRuntimeCredential(identity.runtimeCredential);
+                        }
+                        else if (identity.subject && identity.token) {
                             this._eventPrincipalsByKey.set((0, event_reporter_js_1.eventPrincipalKey)(identity.subject), {
                                 subject: identity.subject,
                                 token: identity.token,
@@ -814,28 +829,30 @@ class OryAgentClient {
         };
         const activity = this.logger.startActivity("delegation.record", { delegationKind: input.kind, ...options?.activityAttributes }, sessionId);
         const url = `${this.agentSecurityUrl.replace(/\/+$/, "")}/agent-security/v1/delegations:record`;
-        // The user bearer authenticates who delegated; the agent or sub-agent bearer
-        // separately proves the principal being attached to the delegation edge.
+        // Interactive lineage uses separate user and runtime proofs. A validated
+        // preprovisioned root has no user bearer; its acting runtime authenticates
+        // directly in Authorization.
         const userToken = this.userPrincipalForSession(sessionId).token;
         const runtimeCredential = options?.runtimeCredential ?? (options?.agentToken
             ? (0, runtime_credential_js_1.talosRuntimeCredential)(options.agentToken)
             : this.runtimeCredential);
         try {
-            if (!userToken || !runtimeCredential) {
+            if (!runtimeCredential || (!userToken && !options?.preprovisionedRoot)) {
                 throw httpError(403, "User token and runtime credential are required");
             }
+            const runtimeOnly = options?.preprovisionedRoot === true;
             const res = await (0, runtime_credential_js_1.authenticatedRuntimeRequest)(runtimeCredential, {
                 url,
                 init: {
                     method: "POST",
                     headers: {
                         "content-type": "application/json",
-                        authorization: `Bearer ${userToken}`,
+                        ...(!runtimeOnly && userToken ? { authorization: `Bearer ${userToken}` } : {}),
                     },
                     body: JSON.stringify(body),
                     signal: options?.signal ?? AbortSignal.timeout(30_000),
                 },
-                authorizationHeader: "x-ory-agent-authorization",
+                authorizationHeader: runtimeOnly ? "authorization" : "x-ory-agent-authorization",
                 fetch: options?.fetchImpl,
             });
             if (!res.ok) {
@@ -1104,7 +1121,7 @@ function rehydrateUserPrincipal(client) {
     // without persisting it — so without this branch `ORY_USER_OAUTH2_TOKEN`
     // authenticated the session and then silently stopped
     // applying on every subsequent event. On a subprocess harness that left the
-    // tool-call client with no user credential for delegation or DCR bootstrap.
+    // tool-call client with no user credential for delegation or Talos enrollment.
     const env = (0, auth_store_js_1.readEnvUserCredential)();
     const tokens = (0, auth_store_js_1.loadTokens)();
     if (env.token) {

package/dist/config.d.ts

@@ -12,7 +12,7 @@ export interface OryOAuth2Tokens {
     expiresAt: number;
     /** Subject (sub claim) the token was issued for. */
     subject?: string;
-    /** Client ID the token was issued under. In-memory only. */
+    /** Client ID the token was issued under. Persisted to bind refreshes to that client. */
     clientId?: string;
     /** @deprecated Accepted in memory for older callers; never persisted. */
     idToken?: string;
@@ -104,6 +104,14 @@ export interface OryAgentDynamicCredentials {
  * bounded so a long-lived install's config doesn't grow without limit.
  */
 export declare const DELEGATION_NODE_HISTORY = 10;
+/** Opaque, administrator-provisioned root delegation node for headless agents. */
+export declare const AGENT_ROOT_DELEGATION_ENV_VAR = "ORY_AGENT_ROOT_DELEGATION";
+/** Validate an opaque broker node without interpreting its server-owned format. */
+export declare function validateAgentRootDelegation(raw: string | undefined): {
+    value?: string;
+    warning?: string;
+};
+export declare function readAgentRootDelegation(env?: NodeJS.ProcessEnv, warnings?: string[]): string | undefined;
 /**
  * Credentials for the AI agent principal (machine identity). Every harness
  * session owns a distinct DCR client, and every typed sub-agent in that session
@@ -183,7 +191,7 @@ export interface OryPluginConfig {
     projectUrl?: string;
     /**
      * Canonical Ory Agent Security broker URL. Broker calls resolve this value
-     * independently from {@link projectUrl}, which remains the OAuth2/DCR origin.
+     * independently from {@link projectUrl}, which remains the project and user-login origin.
      * Older configs fall back to `projectUrl` until this key is persisted.
      */
     agentSecurityUrl?: string;
@@ -250,7 +258,7 @@ export interface OryPluginConfig {
 }
 /**
  * Single OS-agnostic data directory for *all* Ory agent plugin state:
- * the shared config file, persisted DCR credentials, and any harness
+ * the shared config file, persisted legacy DCR credentials, and any harness
  * asset directories. One place per platform — never split across
  * `~/.ory/` and `~/.config/`.
  *
@@ -317,6 +325,18 @@ export declare function saveConfig(update: Partial<{
  * atomic via write-temp + rename.
  */
 export declare function mutateConfig(mutator: (current: OryPluginConfig) => OryPluginConfig | undefined): void;
+export interface AsyncConfigMutation<T> {
+    /** New config to persist while the lock is still held. Omit for a read-only result. */
+    config?: OryPluginConfig;
+    value: T;
+}
+/**
+ * Async read-modify-write transaction using the same config.json.lock as
+ * mutateConfig. The lock remains held while the callback awaits, which lets
+ * token refresh serialize its read/check/network/write sequence across
+ * JavaScript and Go processes without blocking the JavaScript event loop.
+ */
+export declare function mutateConfigAsync<T>(mutator: (current: OryPluginConfig) => Promise<AsyncConfigMutation<T>>): Promise<T>;
 /**
  * True when `value` looks like an Ory project **id** (a UUID) rather than a
  * project **slug**. Project slugs are human-readable tokens (e.g.

package/dist/config.js

@@ -33,7 +33,9 @@ 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.LOCAL_AGENT_SECURITY_URL = exports.DEFAULT_AGENT_SECURITY_URL = exports.DEFAULT_OAUTH2_CLIENT_ID = exports.SESSIONLESS_KEY = exports.UNKNOWN_HARNESS_KEY = exports.AGENT_ROOT_DELEGATION_ENV_VAR = exports.DELEGATION_NODE_HISTORY = void 0;
+exports.validateAgentRootDelegation = validateAgentRootDelegation;
+exports.readAgentRootDelegation = readAgentRootDelegation;
 exports.getDataDir = getDataDir;
 exports.getHarnessDataDir = getHarnessDataDir;
 exports.getConfigPath = getConfigPath;
@@ -43,6 +45,7 @@ exports.registerInstalledHarness = registerInstalledHarness;
 exports.unregisterInstalledHarness = unregisterInstalledHarness;
 exports.saveConfig = saveConfig;
 exports.mutateConfig = mutateConfig;
+exports.mutateConfigAsync = mutateConfigAsync;
 exports.looksLikeProjectId = looksLikeProjectId;
 exports.isSecurityConnected = isSecurityConnected;
 exports.describeSecurityGap = describeSecurityGap;
@@ -51,6 +54,7 @@ exports.configPromptMessage = configPromptMessage;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const cli_invocation_js_1 = require("./cli-invocation.js");
 /**
  * How many sessions' delegation node ids to keep per credential. Only the
@@ -58,6 +62,29 @@ const cli_invocation_js_1 = require("./cli-invocation.js");
  * bounded so a long-lived install's config doesn't grow without limit.
  */
 exports.DELEGATION_NODE_HISTORY = 10;
+/** Opaque, administrator-provisioned root delegation node for headless agents. */
+exports.AGENT_ROOT_DELEGATION_ENV_VAR = "ORY_AGENT_ROOT_DELEGATION";
+/** Validate an opaque broker node without interpreting its server-owned format. */
+function validateAgentRootDelegation(raw) {
+    if (raw === undefined)
+        return {};
+    const value = raw.trim();
+    if (!value) {
+        return { warning: `${exports.AGENT_ROOT_DELEGATION_ENV_VAR} is set but empty; ignoring it.` };
+    }
+    if (Buffer.byteLength(value, "utf8") > 255 || /[\0\r\n]/.test(raw)) {
+        return {
+            warning: `${exports.AGENT_ROOT_DELEGATION_ENV_VAR} must be at most 255 UTF-8 bytes and contain no NUL or newline characters; ignoring it.`,
+        };
+    }
+    return { value };
+}
+function readAgentRootDelegation(env = process.env, warnings) {
+    const { value, warning } = validateAgentRootDelegation(env[exports.AGENT_ROOT_DELEGATION_ENV_VAR]);
+    if (warning)
+        warnings?.push(warning);
+    return value;
+}
 /**
  * Key used when a credential record carries no harness of its own — only
  * reachable by migrating a config written before credentials were keyed by
@@ -78,7 +105,7 @@ exports.UNKNOWN_HARNESS_KEY = "unknown";
 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
+ * the shared config file, persisted legacy DCR credentials, and any harness
  * asset directories. One place per platform — never split across
  * `~/.ory/` and `~/.config/`.
  *
@@ -118,8 +145,11 @@ function configFile() {
 function configLockFile() {
     return configFile() + ".lock";
 }
-/** A lock that is older than this is considered stale and may be broken. */
-const LOCK_STALE_MS = 30_000;
+/** Age fallback for malformed or definitely cross-host lock owners. */
+const LOCK_STALE_FALLBACK_MS = 5 * 60_000;
+/** Lease used by nonce-bearing locks; async transactions refresh it. */
+const LOCK_LEASE_MS = 5_000;
+const LOCK_HEARTBEAT_MS = 1_000;
 /** Polling interval while waiting to acquire the lock. */
 const LOCK_POLL_MS = 25;
 /** Maximum total time to wait for the lock before giving up. */
@@ -507,6 +537,7 @@ 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,
     };
 }
 /**
@@ -540,6 +571,25 @@ function mutateConfig(mutator) {
         releaseLock(lock);
     }
 }
+/**
+ * Async read-modify-write transaction using the same config.json.lock as
+ * mutateConfig. The lock remains held while the callback awaits, which lets
+ * token refresh serialize its read/check/network/write sequence across
+ * JavaScript and Go processes without blocking the JavaScript event loop.
+ */
+async function mutateConfigAsync(mutator) {
+    ensureConfigDir();
+    const lock = await acquireLockAsync();
+    try {
+        const mutation = await mutator(loadConfig());
+        if (mutation.config)
+            writeConfigAtomic(mutation.config);
+        return mutation.value;
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
 function mergeConfig(existing, update) {
     const result = { ...existing };
     for (const key of Object.keys(update)) {
@@ -568,23 +618,16 @@ function acquireLock() {
     for (;;) {
         try {
             const fd = fs.openSync(lockPath, "wx", 0o600);
-            fs.writeSync(fd, String(process.pid));
-            return { fd };
+            const nonce = (0, node_crypto_1.randomBytes)(16).toString("hex");
+            fs.writeSync(fd, configLockOwner(nonce));
+            return { fd, nonce };
         }
         catch (err) {
             if (err.code !== "EEXIST")
                 throw err;
-            // Lock exists — check if it's stale.
             try {
-                const stat = fs.statSync(lockPath);
-                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-                    // Best-effort break; if another process beats us, we'll retry.
-                    try {
-                        fs.unlinkSync(lockPath);
-                    }
-                    catch {
-                        /* ignore */
-                    }
+                const observed = inspectConfigLock(lockPath);
+                if (observed.stale && removeObservedLock(lockPath, observed)) {
                     continue;
                 }
             }
@@ -606,6 +649,142 @@ function acquireLock() {
         }
     }
 }
+async function acquireLockAsync() {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    const lockPath = configLockFile();
+    for (;;) {
+        try {
+            const fd = fs.openSync(lockPath, "wx", 0o600);
+            const nonce = (0, node_crypto_1.randomBytes)(16).toString("hex");
+            fs.writeSync(fd, configLockOwner(nonce));
+            const lock = { fd, nonce };
+            lock.heartbeat = setInterval(() => heartbeatLock(lock), LOCK_HEARTBEAT_MS);
+            lock.heartbeat.unref?.();
+            return lock;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                const observed = inspectConfigLock(lockPath);
+                if (observed.stale && removeObservedLock(lockPath, observed)) {
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for config lock at ${lockPath}. ` +
+                    "Another process may be holding it; remove the file if you are sure no other process is running.");
+            }
+            await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+        }
+    }
+}
+function configLockOwner(nonce, now = Date.now()) {
+    return `${process.pid} ${os.hostname()} ${nonce} ${now + LOCK_LEASE_MS}`;
+}
+function inspectConfigLock(lockPath) {
+    const stat = fs.statSync(lockPath);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(lockPath, "utf8").trim();
+    }
+    catch {
+        return {
+            stale: Date.now() - stat.mtimeMs > LOCK_STALE_FALLBACK_MS,
+            raw,
+            dev: stat.dev,
+            ino: stat.ino,
+        };
+    }
+    const [pidText, hostname, nonce, leaseText] = raw.split(/\s+/, 4);
+    const pid = Number.parseInt(pidText ?? "", 10);
+    const leaseExpiresAt = Number.parseInt(leaseText ?? "", 10);
+    const hasLease = Boolean(nonce) && Number.isFinite(leaseExpiresAt);
+    if (hasLease && Date.now() > leaseExpiresAt) {
+        return { stale: true, raw, dev: stat.dev, ino: stat.ino };
+    }
+    if (Number.isInteger(pid) && pid > 0 && (!hostname || hostname === os.hostname())) {
+        try {
+            process.kill(pid, 0);
+            return {
+                stale: !hasLease && Date.now() - stat.mtimeMs > LOCK_STALE_FALLBACK_MS,
+                raw,
+                dev: stat.dev,
+                ino: stat.ino,
+            };
+        }
+        catch (err) {
+            if (err.code === "EPERM") {
+                return {
+                    stale: !hasLease && Date.now() - stat.mtimeMs > LOCK_STALE_FALLBACK_MS,
+                    raw,
+                    dev: stat.dev,
+                    ino: stat.ino,
+                };
+            }
+            if (err.code === "ESRCH") {
+                return { stale: true, raw, dev: stat.dev, ino: stat.ino };
+            }
+        }
+    }
+    return {
+        stale: Date.now() - stat.mtimeMs > LOCK_STALE_FALLBACK_MS,
+        raw,
+        dev: stat.dev,
+        ino: stat.ino,
+    };
+}
+function removeObservedLock(lockPath, observed) {
+    try {
+        const stat = fs.statSync(lockPath);
+        if (stat.dev !== observed.dev || stat.ino !== observed.ino)
+            return false;
+        if (fs.readFileSync(lockPath, "utf8").trim() !== observed.raw)
+            return false;
+        fs.unlinkSync(lockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ownsLock(lock) {
+    if (lock.fd === null || !lock.nonce)
+        return false;
+    try {
+        const held = fs.fstatSync(lock.fd);
+        const current = fs.statSync(configLockFile());
+        if (held.dev !== current.dev || held.ino !== current.ino)
+            return false;
+        const [, , nonce] = fs.readFileSync(configLockFile(), "utf8").trim().split(/\s+/, 4);
+        return nonce === lock.nonce;
+    }
+    catch {
+        return false;
+    }
+}
+function heartbeatLock(lock) {
+    if (lock.fd === null || !lock.nonce || !ownsLock(lock)) {
+        if (lock.heartbeat)
+            clearInterval(lock.heartbeat);
+        lock.heartbeat = undefined;
+        return;
+    }
+    const record = configLockOwner(lock.nonce);
+    try {
+        fs.ftruncateSync(lock.fd, 0);
+        fs.writeSync(lock.fd, record, 0, "utf8");
+        fs.fsyncSync(lock.fd);
+    }
+    catch {
+        if (lock.heartbeat)
+            clearInterval(lock.heartbeat);
+        lock.heartbeat = undefined;
+    }
+}
 /**
  * Lazily initialized buffer for `Atomics.wait`-based synchronous sleep.
  * `undefined` = not yet probed; `null` = unavailable on this runtime.
@@ -637,14 +816,18 @@ function sleepSync(ms) {
 function releaseLock(lock) {
     if (lock.fd === null)
         return; // lock-less fallback: nothing to release
+    if (lock.heartbeat)
+        clearInterval(lock.heartbeat);
+    lock.heartbeat = undefined;
     try {
-        fs.closeSync(lock.fd);
+        if (ownsLock(lock))
+            fs.unlinkSync(configLockFile());
     }
     catch {
         /* ignore */
     }
     try {
-        fs.unlinkSync(configLockFile());
+        fs.closeSync(lock.fd);
     }
     catch {
         /* ignore */
@@ -672,6 +855,7 @@ function compactPersistedConfig(config) {
                 ...(userTokens.refreshToken ? { refreshToken: userTokens.refreshToken } : {}),
                 expiresAt: userTokens.expiresAt,
                 ...(userTokens.subject ? { subject: userTokens.subject } : {}),
+                ...(userTokens.clientId ? { clientId: userTokens.clientId } : {}),
             },
         }
         : undefined;

package/dist/contract-suite.d.ts

@@ -17,7 +17,6 @@
  * 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 };
@@ -60,13 +59,6 @@ export interface HarnessContractAdapter {
     harness: string;
     /** A real, non-interactive tool from this harness's catalog. */
     tool: string;
-    /**
-     * @deprecated Ignored. Session start is now uniformly non-blocking on every
-     * harness (authentication never blocks; enforcement is governed by
-     * `permissionMode` at tool-call time). Kept optional so existing adapters
-     * that still pass it type-check.
-     */
-    sessionCanBlock?: boolean;
     /** Whether the tool gate can hard-block. Defaults to true. */
     toolCanBlock?: boolean;
     /** Drive the session-start phase through the plugin's real entry point. */

package/dist/contract-suite.js

@@ -18,7 +18,6 @@
  * 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 };

package/dist/event-reporter.d.ts

@@ -49,6 +49,7 @@ export declare class AgentSecurityEventReporter {
     private readonly retryBaseMs;
     private readonly retryMaxMs;
     private readonly random;
+    private readonly reportedAuthFailures;
     constructor(options: EventReporterOptions);
     get pending(): number;
     get pendingScopes(): ReadonlyArray<PendingEventScope>;

package/dist/event-reporter.js

@@ -105,6 +105,7 @@ class AgentSecurityEventReporter {
     retryBaseMs;
     retryMaxMs;
     random;
+    reportedAuthFailures = new Set();
     constructor(options) {
         this.options = options;
         this.fetcher = options.fetch ?? globalThis.fetch;
@@ -328,14 +329,27 @@ class AgentSecurityEventReporter {
                 this.diagnostic("events.batch_rejected", new Error(`HTTP ${response.status}`));
                 return "reject";
             }
-            if (response.status === 401) {
+            if (response.status === 401 || response.status === 403) {
                 try {
-                    if (token)
+                    if (response.status === 401 && token) {
                         this.options.onUnauthorized?.(scope.sessionId, scope.principalKey, token);
+                    }
                 }
                 catch (error) {
                     this.diagnostic("events.credential_invalidation_failed", error);
                 }
+                const failureKey = `${scopeKey(scope)}:${response.status}`;
+                if (!this.reportedAuthFailures.has(failureKey)) {
+                    this.reportedAuthFailures.add(failureKey);
+                    this.options.logger?.activity("events.record", "error", {
+                        sessionId: scope.sessionId,
+                        attributes: {
+                            failureType: "authentication",
+                            reasonCode: response.status === 401 ? "session_inactive" : "forbidden",
+                            count: batch.length,
+                        },
+                    });
+                }
                 return "retain";
             }
             if (response.status === 429 || (response.status >= 500 && response.status <= 599)) {
@@ -359,6 +373,9 @@ class AgentSecurityEventReporter {
                 this.diagnostic("events.invalid_response", new Error("response event IDs did not match request order"));
                 return "retain";
             }
+            const acceptedScope = scopeKey(scope);
+            this.reportedAuthFailures.delete(`${acceptedScope}:401`);
+            this.reportedAuthFailures.delete(`${acceptedScope}:403`);
             return "accepted";
         }
         finally {

package/dist/hook-timeout.d.ts

@@ -29,8 +29,8 @@
  * can be given — which is why the login window has to fit inside 120s.
  */
 /**
- * Wall-clock budget for a session-start hook: the interactive login, plus the
- * agent DCR registration and delegation record that follow it.
+ * Wall-clock budget for a session-start hook: the interactive login, plus Talos
+ * credential loading or enrollment and the delegation record that follow it.
  *
  * Generous on purpose. It is an upper bound on a hook that is *waiting*, not a
  * latency target — nothing is spinning, and the login gives up on its own well

package/dist/hook-timeout.js

@@ -35,8 +35,8 @@ exports.sessionStartHookTimeout = sessionStartHookTimeout;
 exports.toolHookTimeout = toolHookTimeout;
 const auth_js_1 = require("./auth.js");
 /**
- * Wall-clock budget for a session-start hook: the interactive login, plus the
- * agent DCR registration and delegation record that follow it.
+ * Wall-clock budget for a session-start hook: the interactive login, plus Talos
+ * credential loading or enrollment and the delegation record that follow it.
  *
  * Generous on purpose. It is an upper bound on a hook that is *waiting*, not a
  * latency target — nothing is spinning, and the login gives up on its own well

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, type RecordDelegationInput, type RecordDelegationResult, } from "./client.js";
-export { authenticatedRuntimeRequest, canonicalCredentialIdentity, canonicalProjectUrl, credentialAccount, configureSystemCaTrustForDefaultFetch, createOsTalosCredentialStore, enrollTalosChildRuntimeCredential, enrollTalosRuntimeCredential, resolveRuntimeCredential, runCredentialStoreCommand, talosRuntimeCredential, type CredentialStoreCommandOptions, type CredentialStoreCommandRunner, type ResolveRuntimeCredentialOptions, type EnrollTalosChildRuntimeCredentialOptions, type EnrollTalosRuntimeCredentialOptions, type EnrolledRuntimeCredential, type OsTalosCredentialStoreOptions, type NodeTlsCaProvider, type StoredTalosCredential, type TalosCredentialStore, type TalosCredentialIdentity, type RuntimeAuthenticatedRequest, type RuntimeAuthorizationHeader, type RuntimeCredential, type RuntimeCredentialKind, type RuntimeRequestAuthenticator, } from "./runtime-credential.js";
+export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, type RecordDelegationInput, type RecordDelegationResult, type RuntimeContext, } from "./client.js";
+export { authenticatedRuntimeRequest, canonicalCredentialIdentity, canonicalProjectUrl, credentialAccount, configureSystemCaTrustForDefaultFetch, createSpiffeFileRequestAuthenticator, createOsTalosCredentialStore, enrollTalosChildRuntimeCredential, enrollTalosRuntimeCredential, resolveRuntimeCredential, runCredentialStoreCommand, talosRuntimeCredential, type CredentialStoreCommandOptions, type CredentialStoreCommandRunner, type ResolveRuntimeCredentialOptions, type SpiffeFileRequestAuthenticatorOptions, type EnrollTalosChildRuntimeCredentialOptions, type EnrollTalosRuntimeCredentialOptions, type EnrolledRuntimeCredential, type OsTalosCredentialStoreOptions, type NodeTlsCaProvider, type StoredTalosCredential, type TalosCredentialStore, type TalosCredentialIdentity, type RuntimeAuthenticatedRequest, type RuntimeAuthorizationHeader, type RuntimeCredential, type RuntimeCredentialKind, type RuntimeRequestAuthenticator, } from "./runtime-credential.js";
 export { DebugLogger, ActiveActivity, redactLogData, formatLogEntry, withQuietStderr, type LogEntry, type LogLevel, type ActivityEntry, type ActivityStatus, type UnifiedLogEntry, type ActivityEnricher, type ActivitySink, } from "./logger.js";
 export { AgentSecurityEventReporter, SERVER_ACTIVITY_EVENTS, projectActivityEntry, type EventReporterOptions, type ServerActivityEvent, } from "./event-reporter.js";
 export { currentSessionContext, withSessionContext, setSessionContext, clearSessionContext, type SessionContext, } from "./context.js";
-export { loadConfig, saveConfig, resolveConfig, isSecurityConnected, describeSecurityGap, type SecurityConnection, mutateConfig, getConfigPath, getDataDir, getHarnessDataDir, listInstalledHarnesses, registerInstalledHarness, unregisterInstalledHarness, UNKNOWN_HARNESS_KEY, SESSIONLESS_KEY, type OryPluginConfig, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, type OryDelegationRecord, type PermissionMode, type PermissionModeCache, } from "./config.js";
+export { loadConfig, saveConfig, resolveConfig, isSecurityConnected, describeSecurityGap, readAgentRootDelegation, validateAgentRootDelegation, AGENT_ROOT_DELEGATION_ENV_VAR, type SecurityConnection, mutateConfig, mutateConfigAsync, getConfigPath, getDataDir, getHarnessDataDir, listInstalledHarnesses, registerInstalledHarness, unregisterInstalledHarness, UNKNOWN_HARNESS_KEY, SESSIONLESS_KEY, type OryPluginConfig, type AsyncConfigMutation, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, type OryDelegationRecord, type PermissionMode, type PermissionModeCache, } from "./config.js";
 export { resolvePermissionMode, warmPermissionModeCache, resetPermissionModeCache, type PermissionModeSource, type ResolvedPermissionMode, type ModeSubject, } from "./permission-mode.js";
 export { pkceLogin, refreshAccessToken, detectHeadless, generateCodeVerifier, sha256Base64Url, buildAuthorizeUrl, LOOPBACK_PORTS, DEFAULT_LOGIN_TIMEOUT_MS, type PkceLoginOptions, type PkceLoginOutcome, type PkceDeclineReason, } from "./auth.js";
 export { wantsHelp, shouldPrintHelp } from "./help-cli.js";
@@ -11,7 +11,7 @@ export { loadExternalRegistrations, recordExternalRegistration, clearExternalReg
 export { SESSION_START_HOOK_WINDOW_MS, TOOL_HOOK_WINDOW_MS, HOOK_TIMEOUT_MAX_MS, sessionStartHookTimeout, toolHookTimeout, type HookTimeoutUnit, } from "./hook-timeout.js";
 export { loadTokens, saveTokens, clearTokens, isExpired, refreshAndSave, tryAcquirePkceFlightLock, clearPkceFlightLock, waitForPeerTokens, waitForPeerTokensSync, TOKEN_EXPIRY_SKEW_SEC, type PkceFlightLock, } from "./auth-store.js";
 export { ensureUserAuthenticated, ensureAuthenticated, type UserLoginDecision, type UserLoginMode, type UserLoginOptions, } from "./user-login.js";
-export { resolveAgentCredentials, resolveRuntimeAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, loadAgentDynamicCredentialsByHarness, saveAgentDynamicCredentials, clearAgentDynamicCredentials, latestAgentRegistration, latestSubAgentSession, countAgentSessions, claimAgentDynamicCredentials, loadSubAgentDynamicCredentials, loadAllSubAgentDynamicCredentials, loadSubAgentDynamicCredentialsByHarness, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, clearSubAgentDynamicCredentialsForHarness, claimSubAgentDynamicCredentials, loadDelegationNodeId, saveDelegationNodeId, loadRetiredCredentials, clearRetiredCredentials, retireAgentSessions, sessionRetention, revokeAgentDynamicClient, AGENT_TOKEN_EXPIRY_SKEW_SEC, DEFAULT_SESSION_RETENTION, type AgentRegistrationClaim, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type ResolveRuntimeAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type DelegationInput, type RevokeAgentClientResult, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.js";
+export { resolveAgentCredentials, resolvePreprovisionedRuntimeContext, resolveRuntimeAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, loadAgentDynamicCredentialsByHarness, saveAgentDynamicCredentials, clearAgentDynamicCredentials, latestAgentRegistration, latestSubAgentSession, countAgentSessions, claimAgentDynamicCredentials, loadSubAgentDynamicCredentials, loadAllSubAgentDynamicCredentials, loadSubAgentDynamicCredentialsByHarness, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, clearSubAgentDynamicCredentialsForHarness, claimSubAgentDynamicCredentials, loadDelegationNodeId, resolvePreprovisionedRootDelegation, saveDelegationNodeId, loadRetiredCredentials, clearRetiredCredentials, retireAgentSessions, sessionRetention, revokeAgentDynamicClient, AGENT_TOKEN_EXPIRY_SKEW_SEC, DEFAULT_SESSION_RETENTION, type AgentRegistrationClaim, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type ResolveRuntimeAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type DelegationInput, type RevokeAgentClientResult, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.js";
 export { ensureReadCredential, resetReadCredentialBackoff, READ_CREDENTIAL_RETRY_MS, type EnsureReadCredentialOptions, type ReadCredentialOutcome, } from "./read-credential.js";
 export { clearCredentialsForUninstall, resolveInstalledHarnesses, type ClearCredentialsOptions, type ClearCredentialsResult, } from "./uninstall.js";
 export { type SessionInfo, type OAuth2TokenInfo, type PermissionCheck, type PermissionResult, type BatchPermissionResult, type OryError, type OryErrorCode, } from "./types.js";