@ory/argus 1.2.4 → 1.3.0

package/assets/skills/ory-temporal-worker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ory-temporal-worker
-description: Scaffold a [Temporal](https://temporal.io) TypeScript worker where every Activity execution is gated by Ory — the user is authenticated, the worker's agent identity is resolved via DCR, each Activity invocation runs an Ory Permission check, and the full lifecycle emits structured activity events. Use when the user asks to "add Ory to my Temporal worker", "wire Ory permissions into Temporal activities", "create a Temporal worker with Ory auth", "build a Temporal TypeScript project with the Ory agent client", or any close variant. The skill scaffolds the project in the user's repo following <https://docs.temporal.io/develop/typescript/set-up-your-local-typescript> — it does not run the worker.
+description: Scaffold a [Temporal](https://temporal.io) TypeScript worker where every Activity execution is gated by Ory — the user is authenticated, the worker resolves an injected or Talos runtime identity, each Activity invocation runs an Ory Permission check, and the full lifecycle emits structured activity events. Use when the user asks to "add Ory to my Temporal worker", "wire Ory permissions into Temporal activities", "create a Temporal worker with Ory auth", "build a Temporal TypeScript project with the Ory agent client", or any close variant. The skill scaffolds the project in the user's repo following <https://docs.temporal.io/develop/typescript/set-up-your-local-typescript> — it does not run the worker.
 ---
 
 # Ory-authed Temporal TypeScript worker
@@ -262,9 +262,9 @@ Temporal Web UI.
 
 This skill stops at the local dev server. For production:
 
-- Pin a static agent identity with `ORY_AGENT_CLIENT_ID +
-  ORY_AGENT_CLIENT_SECRET` (client_credentials) so the worker doesn't
-  re-register on every cold start.
+- Inject a runtime request authenticator from the workload platform, or provide
+  `ORY_AGENT_API_KEY` through the deployment secret manager. Do not bake a
+  runtime credential into the worker image.
 - Set retention and access controls for the worker's unified activity log.
   Ory Agent Security owns service telemetry; the worker does not export traces.
 - Use Temporal Cloud or a self-hosted Temporal cluster instead of

package/dist/adapters.d.ts

@@ -21,7 +21,7 @@
  * Every primitive is best-effort and fail-open.
  */
 import type { OryAgentClient } from "./client.js";
-import { ensureAgentIdentity, ensureSubAgentIdentity } from "./agent-auth.js";
+import { ensureAgentIdentity, ensureSubAgentIdentity, type SubAgentIdentity } from "./agent-auth.js";
 import { ensureUserAuthenticated } from "./user-login.js";
 import { type ModeDecision, type PermissionDecision, type PrincipalBlockSubjects } from "./permissions.js";
 import { type DenialContext } from "./denial.js";
@@ -42,12 +42,18 @@ export interface SessionStartResult {
 }
 export interface SessionStartOptions {
     harness: string;
+    /** Root agent type supplied by the adapter/application. Defaults to `harness`. */
+    agentType?: string;
     sessionId?: string;
     projectUrl?: string;
     binName?: string;
+    /** Environment override used by headless deployment packages and tests. */
+    env?: NodeJS.ProcessEnv;
     /** Injectable gates (tests). */
     userLogin?: typeof ensureUserAuthenticated;
     agentGate?: typeof ensureAgentIdentity;
+    /** Injectable runtime-context transport (tests and custom runtimes). */
+    runtimeContextFetch?: typeof fetch;
     /** Small, privacy-safe session metadata supported by the activity API. */
     activityAttributes?: Record<string, unknown>;
 }
@@ -77,7 +83,7 @@ export declare function createSessionStarter(client: OryAgentClient, opts: Sessi
  * logged and swallowed. No-op when Agent Security isn't connected (there is no
  * broker to record against) and when no user identity resolves.
  */
-export declare function writeUserDelegatesAgent(client: OryAgentClient, harness?: string, sessionId?: string): Promise<void>;
+export declare function writeUserDelegatesAgent(client: OryAgentClient, harness?: string, sessionId?: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export interface RegisterSubagentOptions {
     harness: string;
     subAgentType: string;
@@ -92,8 +98,9 @@ export interface RegisterSubagentOptions {
     perSpawnId?: string;
     sessionId?: string;
     signal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
 }
-export declare function registerSubagent(client: OryAgentClient, opts: RegisterSubagentOptions): Promise<void>;
+export declare function registerSubagent(client: OryAgentClient, opts: RegisterSubagentOptions): Promise<SubAgentIdentity | undefined>;
 /**
  * Record the `agent → subagent` delegation edge through the agent-security
  * broker. Exported so harness plugins that resolve the sub-agent identity
@@ -115,6 +122,7 @@ export declare function writeAgentDelegatesSubagent(client: OryAgentClient, subA
     agentToken?: string;
     runtimeCredential?: RuntimeCredential;
     signal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
 }): Promise<void>;
 export interface GateResult {
     /** False only when the tool was hard-denied in enforce mode. */

package/dist/adapters.js

@@ -104,19 +104,51 @@ async function sessionStart(client, opts) {
     const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
     const userLogin = opts.userLogin ?? user_login_js_1.ensureUserAuthenticated;
     const agentGate = opts.agentGate ?? agent_auth_js_1.ensureAgentIdentity;
+    const env = opts.env ?? process.env;
+    const packageWarnings = [];
+    let rootDelegation = (0, agent_auth_js_1.resolvePreprovisionedRootDelegation)(env, packageWarnings, client.runtimeCredential);
+    for (const message of packageWarnings) {
+        client.logger.warn("agent.package.invalid", { message });
+    }
+    if (!rootDelegation) {
+        try {
+            const context = await (0, agent_auth_js_1.resolvePreprovisionedRuntimeContext)(client, {
+                projectUrl,
+                expectedAgentType: opts.agentType ?? opts.harness,
+                env,
+                fetchImpl: opts.runtimeContextFetch,
+            });
+            rootDelegation = context?.rootDelegation;
+        }
+        catch (err) {
+            client.logger.warn("agent.runtime_context.failed", describeThrown(err));
+        }
+    }
     let decision = {
         proceed: true,
         mode: "skipped",
         reason: "User authentication failed open",
     };
-    try {
-        decision = await userLogin(client, {
-            binName: opts.binName ?? `ory-${opts.harness}`,
-            harness: opts.harness,
+    if (rootDelegation) {
+        decision = {
+            proceed: true,
+            mode: "skipped",
+            reason: "Administrator-preprovisioned agent package does not require user login",
+        };
+        client.logger.activity("user.auth", "skipped", {
+            attributes: { mode: decision.mode, reason: decision.reason, proceed: true },
         });
     }
-    catch (err) {
-        client.logger.warn("session_start.user_auth.failed", describeThrown(err));
+    else {
+        try {
+            decision = await userLogin(client, {
+                binName: opts.binName ?? `ory-${opts.harness}`,
+                harness: opts.harness,
+            });
+        }
+        catch (err) {
+            client.logger.warn("session_start.user_auth.failed", describeThrown(err));
+        }
     }
     let creds = {
         kind: "none",
@@ -128,12 +160,13 @@ async function sessionStart(client, opts) {
             projectUrl,
             harness: opts.harness,
             sessionId: opts.sessionId ?? client.sessionId,
+            env,
         });
     }
     catch (err) {
         client.logger.warn("session_start.agent_auth.failed", describeThrown(err));
     }
-    await writeUserDelegatesAgent(client, opts.harness, opts.sessionId);
+    await writeUserDelegatesAgent(client, opts.harness, opts.sessionId, env);
     // Warm the permission-mode cache from the server once per session, so the
     // synchronous `resolveConfig().permissionMode` read (the MCP
     // `applyPermissionMode` path, display surfaces) reflects the current project
@@ -183,8 +216,7 @@ function unqualify(subject, ns) {
 }
 /**
  * Resolve one end of a delegation edge, preferring the live principal but
- * falling back to the persisted delegation anchor (`delegation.delegatedBy`
- * on the DCR credentials in local config). This is what lets the edge be
+ * falling back to the persisted non-secret delegation anchor. This lets the edge be
  * recorded from an authoritative source rather than from nothing when the
  * principal isn't populated for the session. A mismatch between the two is
  * logged for reconciliation visibility; the live principal wins.
@@ -211,9 +243,12 @@ function reconcileEdgeEnd(client, principal, anchor, role) {
  * logged and swallowed. No-op when Agent Security isn't connected (there is no
  * broker to record against) and when no user identity resolves.
  */
-async function writeUserDelegatesAgent(client, harness, sessionId) {
+async function writeUserDelegatesAgent(client, harness, sessionId, env = process.env) {
     if (!(0, config_js_1.isSecurityConnected)())
         return;
+    if (client.runtimeRootDelegation ||
+        (0, agent_auth_js_1.resolvePreprovisionedRootDelegation)(env, undefined, client.runtimeCredential))
+        return;
     // Resolve the delegating user (the anchor of the edge). Prefer the live
     // principal; fall back to the delegator persisted in the agent client's
     // delegation anchor so the edge can still be recorded in a session where the
@@ -264,6 +299,7 @@ async function registerSubagent(client, opts) {
             sessionId: opts.sessionId ?? client.sessionId,
             perSpawnId: opts.perSpawnId,
             signal: opts.signal,
+            env: opts.env,
         });
     }
     catch (err) {
@@ -271,10 +307,12 @@ async function registerSubagent(client, opts) {
             subAgentType: opts.subAgentType,
             ...describeThrown(err),
         });
-        return;
+        return undefined;
     }
     if (identity.kind !== "runtime" && identity.kind !== "dynamic")
-        return;
+        return identity;
+    if (identity.runtimeCredential)
+        client.rememberRuntimeCredential(identity.runtimeCredential);
     await writeAgentDelegatesSubagent(client, identity.subject ?? "", opts.subAgentType, {
         harness: opts.harness,
         sessionId: opts.sessionId,
@@ -282,7 +320,9 @@ async function registerSubagent(client, opts) {
         signal: opts.signal,
         runtimeCredential: identity.runtimeCredential,
         agentToken: identity.token,
+        env: opts.env,
     });
+    return identity;
 }
 /**
  * Record the `agent → subagent` delegation edge through the agent-security
@@ -307,7 +347,8 @@ async function writeAgentDelegatesSubagent(client, subAgentSubject, subAgentType
     // session*: the parent of this sub-agent is this run's session credential, so
     // the harness alone would not identify it.
     const sessionKey = (opts.sessionId ?? client.sessionId)?.trim() || config_js_1.SESSIONLESS_KEY;
-    const delegatedBy = (0, agent_auth_js_1.loadDelegationNodeId)(opts.harness ?? client.harness, sessionKey);
+    const preprovisionedRoot = client.runtimeRootDelegation ?? (0, agent_auth_js_1.resolvePreprovisionedRootDelegation)(opts.env, undefined, client.runtimeCredential);
+    const delegatedBy = client.runtimeRootDelegation ?? (0, agent_auth_js_1.loadDelegationNodeId)(opts.harness ?? client.harness, sessionKey, opts.env, client.runtimeCredential);
     if (!delegatedBy) {
         client.logger.debug("delegation.skip", {
             reason: "no persisted agent delegation node (user→agent edge not recorded yet)",
@@ -327,6 +368,7 @@ async function writeAgentDelegatesSubagent(client, subAgentSubject, subAgentType
             signal: opts.signal,
             agentToken: opts.agentToken,
             runtimeCredential: opts.runtimeCredential,
+            preprovisionedRoot: preprovisionedRoot !== undefined,
             activityAttributes: {
                 delegation: "agent-to-subagent",
                 subAgentType,

package/dist/agent-auth.d.ts

@@ -5,15 +5,26 @@
  * user. Unlike the user, the agent never authenticates interactively.
  * The normal path resolves a noninteractive runtime credential: an injected
  * request authenticator, `ORY_AGENT_API_KEY`, or a Talos key enrolled with the
- * already-authenticated user. Enrolled keys remain process-local.
+ * already-authenticated user and persisted in the native OS credential store.
  *
  * Legacy DCR and client-credentials helpers remain exported temporarily so the
  * monorepo and existing consumers compile, but the normal gates do not select
  * them.
  */
 import { type OryAgentDynamicCredentials, type OryDelegationRecord } from "./config.js";
-import { OryAgentClient } from "./client.js";
+import { OryAgentClient, type RuntimeContext } from "./client.js";
 import { enrollTalosChildRuntimeCredential, enrollTalosRuntimeCredential, type RuntimeCredential, type RuntimeRequestAuthenticator, type TalosCredentialStore } from "./runtime-credential.js";
+/** Resolve the complete administrator-provisioned headless package, if present. */
+export declare function resolvePreprovisionedRootDelegation(env?: NodeJS.ProcessEnv, warnings?: string[], runtimeCredential?: RuntimeCredential): string | undefined;
+export interface ResolvePreprovisionedRuntimeContextOptions {
+    projectUrl?: string;
+    expectedAgentType: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}
+/** Resolve missing headless deployment metadata using the existing runtime proof. */
+export declare function resolvePreprovisionedRuntimeContext(client: OryAgentClient, options: ResolvePreprovisionedRuntimeContextOptions): Promise<RuntimeContext | undefined>;
 /**
  * Delegation context handed to {@link registerAgentClient} so the freshly
  * minted OAuth2 client is stamped with its delegator at the identity layer.
@@ -174,7 +185,7 @@ export declare function countAgentSessions(harness: string): number;
  * sessions but the node is not, so a sub-agent must hang off *its own* run's
  * agent node.
  */
-export declare function loadDelegationNodeId(harness: string, sessionKey: string): string | undefined;
+export declare function loadDelegationNodeId(harness: string, sessionKey: string, env?: NodeJS.ProcessEnv, runtimeCredential?: RuntimeCredential): string | undefined;
 /**
  * Record the broker-assigned delegation node for `(harness, session)`, trimming
  * the map to the most recent {@link DELEGATION_NODE_HISTORY} entries.
@@ -317,7 +328,7 @@ export interface EnsureAgentIdentityOptions {
     /** Retained for source compatibility and activity attribution. */
     harness?: string;
     /**
-     * Session this identity acts in. Selects the persisted DCR slot and defaults
+     * Session this identity acts in. Selects the OS-store descriptor and defaults
      * to the client's ambient session.
      */
     sessionId?: string;
@@ -417,9 +428,9 @@ export interface EnsureSubAgentIdentityOptions {
     allowEnrollment?: boolean;
 }
 /**
- * Resolve a sub-agent against the process runtime credential. The broker's
- * `type_name` supplies sub-agent attribution; no separate OAuth identity is
- * registered, loaded, minted, or persisted.
+ * Resolve a sub-agent to a child Talos credential. Stored credentials are
+ * loaded by spawn descriptor; missing credentials may be enrolled through the
+ * authenticated parent runtime.
  */
 export declare function ensureSubAgentIdentity(client: OryAgentClient, options: EnsureSubAgentIdentityOptions): Promise<SubAgentIdentity>;
 export {};

package/dist/agent-auth.js

@@ -6,7 +6,7 @@
  * user. Unlike the user, the agent never authenticates interactively.
  * The normal path resolves a noninteractive runtime credential: an injected
  * request authenticator, `ORY_AGENT_API_KEY`, or a Talos key enrolled with the
- * already-authenticated user. Enrolled keys remain process-local.
+ * already-authenticated user and persisted in the native OS credential store.
  *
  * Legacy DCR and client-credentials helpers remain exported temporarily so the
  * monorepo and existing consumers compile, but the normal gates do not select
@@ -14,6 +14,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SESSION_RETENTION = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = void 0;
+exports.resolvePreprovisionedRootDelegation = resolvePreprovisionedRootDelegation;
+exports.resolvePreprovisionedRuntimeContext = resolvePreprovisionedRuntimeContext;
 exports.resolveRuntimeAgentCredentials = resolveRuntimeAgentCredentials;
 exports._resetAgentCredentialsCache = _resetAgentCredentialsCache;
 exports.invalidateAgentAccessToken = invalidateAgentAccessToken;
@@ -55,6 +57,102 @@ const subject_js_1 = require("./subject.js");
 const runtime_credential_js_1 = require("./runtime-credential.js");
 const ENROLLMENT_LOCK_STALE_MS = 120_000;
 const ENROLLMENT_LOCK_WAIT_MS = 35_000;
+const validatedRuntimeSubjects = new WeakSet();
+/** Resolve the complete administrator-provisioned headless package, if present. */
+function resolvePreprovisionedRootDelegation(env = process.env, warnings, runtimeCredential) {
+    const root = (0, config_js_1.readAgentRootDelegation)(env, warnings);
+    if (!root)
+        return undefined;
+    if (!env.ORY_AGENT_API_KEY?.trim() && runtimeCredential?.kind !== "injected") {
+        warnings?.push("ORY_AGENT_ROOT_DELEGATION requires ORY_AGENT_API_KEY or an injected runtime authenticator; ignoring it.");
+        return undefined;
+    }
+    if (!(0, subject_js_1.readAgentSubjectOverride)(env, warnings)) {
+        warnings?.push("ORY_AGENT_ROOT_DELEGATION requires a valid ORY_AGENT_SUBJECT_ID; ignoring it.");
+        return undefined;
+    }
+    return root;
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const RUNTIME_CONTEXT_KEYS = [
+    "agent_type",
+    "authenticated",
+    "deployment_id",
+    "root_delegation",
+    "subject_id",
+];
+function parseRuntimeContext(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Runtime context response is malformed");
+    }
+    const raw = value;
+    if (Object.keys(raw).sort().join("\0") !== RUNTIME_CONTEXT_KEYS.join("\0")) {
+        throw new Error("Runtime context response is malformed");
+    }
+    const subjectId = raw.subject_id;
+    const rootDelegation = raw.root_delegation;
+    const deploymentId = raw.deployment_id;
+    const agentType = raw.agent_type;
+    if (raw.authenticated !== true ||
+        typeof subjectId !== "string" ||
+        !subjectId.startsWith("agent:") ||
+        !UUID_PATTERN.test(subjectId.slice("agent:".length)) ||
+        typeof rootDelegation !== "string" ||
+        !rootDelegation.trim() ||
+        typeof deploymentId !== "string" ||
+        !UUID_PATTERN.test(deploymentId) ||
+        typeof agentType !== "string" ||
+        !agentType.trim()) {
+        throw new Error("Runtime context response is malformed");
+    }
+    return { authenticated: true, subjectId, rootDelegation, deploymentId, agentType };
+}
+/** Resolve missing headless deployment metadata using the existing runtime proof. */
+async function resolvePreprovisionedRuntimeContext(client, options) {
+    const env = options.env ?? process.env;
+    const credential = client.runtimeCredential ?? (0, runtime_credential_js_1.resolveRuntimeCredential)({
+        env,
+        fetch: options.fetchImpl,
+    });
+    if (!credential)
+        return undefined;
+    let response;
+    try {
+        response = await (0, runtime_credential_js_1.authenticatedRuntimeRequest)(credential, {
+            url: `${client.agentSecurityUrl.replace(/\/+$/, "")}/agent-security/v1/runtime:context`,
+            init: {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ project_url: options.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl }),
+                signal: options.signal ?? AbortSignal.timeout(30_000),
+            },
+            authorizationHeader: "authorization",
+            fetch: options.fetchImpl,
+        });
+    }
+    catch {
+        throw new Error("Runtime context request failed");
+    }
+    if (response.status !== 200) {
+        throw new Error(`Runtime context request failed (HTTP ${response.status})`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new Error("Runtime context response is malformed");
+    }
+    const context = parseRuntimeContext(payload);
+    if (context.agentType !== options.expectedAgentType) {
+        throw new Error("Runtime context agent type does not match the adapter type");
+    }
+    const contextualCredential = { ...credential, subject: context.subjectId };
+    validatedRuntimeSubjects.add(contextualCredential);
+    client.setRuntimeCredential(contextualCredential);
+    client.setRuntimeContext(context);
+    return context;
+}
 async function withEnrollmentLock(identity, work) {
     const lockRoot = (0, node_path_1.join)((0, config_js_1.getDataDir)(), "runtime-credential-locks");
     const lockPath = (0, node_path_1.join)(lockRoot, `${(0, runtime_credential_js_1.credentialAccount)(identity)}.lock`);
@@ -107,7 +205,17 @@ async function resolveRuntimeAgentCredentials(options = {}) {
             subject,
             fetch: options.fetchImpl,
         });
-    const configured = (0, runtime_credential_js_1.resolveRuntimeCredential)({ env, subject, fetch: options.fetchImpl });
+    let configured = (0, runtime_credential_js_1.resolveRuntimeCredential)({ env, subject, fetch: options.fetchImpl });
+    const current = options.runtimeCredential;
+    if (configured?.kind === "talos" &&
+        current?.kind === "talos" &&
+        current.subject &&
+        validatedRuntimeSubjects.has(current) &&
+        current.apiKeyFingerprint !== undefined &&
+        current.apiKeyFingerprint === configured.apiKeyFingerprint) {
+        configured = { ...configured, subject: current.subject };
+        validatedRuntimeSubjects.add(configured);
+    }
     const existing = injected ?? configured
         ?? (options.runtimeCredential?.kind === "talos" ? options.runtimeCredential : undefined);
     if (existing) {
@@ -342,7 +450,10 @@ function pruneAgentBlock(current, mutate) {
  * sessions but the node is not, so a sub-agent must hang off *its own* run's
  * agent node.
  */
-function loadDelegationNodeId(harness, sessionKey) {
+function loadDelegationNodeId(harness, sessionKey, env = process.env, runtimeCredential) {
+    const provisioned = resolvePreprovisionedRootDelegation(env, undefined, runtimeCredential);
+    if (provisioned)
+        return provisioned;
     const config = (0, config_js_1.loadConfig)();
     return config.delegationAnchors?.[harness]?.[sessionKey]
         // Read the old location during the cutover; every subsequent save writes
@@ -996,8 +1107,8 @@ async function fetchClientCredentialsToken(args) {
  */
 async function ensureAgentIdentity(client, options = {}) {
     const sessionId = options.sessionId ?? client.sessionId;
-    // Agent Security isn't connected — skip credential resolution entirely
-    // (no DCR, no token grant) and record the no-op, shaped like the user
+    // Agent Security isn't connected: skip runtime credential resolution and
+    // record the no-op, shaped like the user
     // gate's not_connected result.
     const resolvedConfig = (0, config_js_1.resolveConfig)();
     const security = resolvedConfig.security;
@@ -1193,13 +1304,12 @@ async function drainRetiredCredentials(client, opts) {
     });
 }
 /**
- * Resolve a sub-agent against the process runtime credential. The broker's
- * `type_name` supplies sub-agent attribution; no separate OAuth identity is
- * registered, loaded, minted, or persisted.
+ * Resolve a sub-agent to a child Talos credential. Stored credentials are
+ * loaded by spawn descriptor; missing credentials may be enrolled through the
+ * authenticated parent runtime.
  */
 async function ensureSubAgentIdentity(client, options) {
-    // Same no-op as ensureAgentIdentity — no sub-agent DCR while Agent
-    // Security is not connected.
+    // Same no-op as ensureAgentIdentity while Agent Security is disconnected.
     const resolvedConfig = (0, config_js_1.resolveConfig)();
     const subAgentSecurity = resolvedConfig.security;
     if (!subAgentSecurity.connected) {

package/dist/auth-store.d.ts

@@ -33,9 +33,9 @@ export interface EnvUserCredential {
  *
  * **`ORY_USER_OAUTH2_TOKEN` is the only accepted variable**, because an OAuth2
  * access token is the only thing the credential is ever used as. All three
- * consumers of `userPrincipal.token` demand one: broker delegation
- * authentication and the agent + sub-agent DCR bootstraps (which send it as a
- * bearer to `/oauth2/register`). Nothing calls `verifySession`, so a Kratos
+ * consumers of `userPrincipal.token` demand one: broker delegation ownership
+ * and root Talos enrollment (which sends it as the user bearer). Nothing calls
+ * `verifySession`, so a Kratos
  * session token is never consumed as a session token.
  *
  * Three variables used to be accepted alongside it and have been removed:

package/dist/auth-store.js

@@ -100,9 +100,9 @@ function clearTokens() {
  *
  * **`ORY_USER_OAUTH2_TOKEN` is the only accepted variable**, because an OAuth2
  * access token is the only thing the credential is ever used as. All three
- * consumers of `userPrincipal.token` demand one: broker delegation
- * authentication and the agent + sub-agent DCR bootstraps (which send it as a
- * bearer to `/oauth2/register`). Nothing calls `verifySession`, so a Kratos
+ * consumers of `userPrincipal.token` demand one: broker delegation ownership
+ * and root Talos enrollment (which sends it as the user bearer). Nothing calls
+ * `verifySession`, so a Kratos
  * session token is never consumed as a session token.
  *
  * Three variables used to be accepted alongside it and have been removed:
@@ -142,16 +142,60 @@ function isExpired(tokens, now = Date.now()) {
  * or if the refresh call fails.
  */
 async function refreshAndSave(args) {
-    if (!args.current.refreshToken) {
-        throw new Error("No refresh_token available; a fresh login is required.");
-    }
-    const next = await (0, auth_js_1.refreshAccessToken)({
-        projectUrl: args.projectUrl,
-        clientId: args.clientId,
-        refreshToken: args.current.refreshToken,
+    return (0, config_js_1.mutateConfigAsync)(async (config) => {
+        const persistedProjectOrigin = canonicalProjectOrigin(config.projectUrl);
+        const requestedProjectOrigin = canonicalProjectOrigin(args.projectUrl);
+        if (persistedProjectOrigin !== requestedProjectOrigin) {
+            throw new Error("Persisted user OAuth2 tokens are bound to the current config projectUrl; sign in again for the selected project.");
+        }
+        const persisted = config.user?.oauth2;
+        const persistedClientId = persisted?.clientId?.trim() ||
+            config.oauth2ClientId?.trim() ||
+            config_js_1.DEFAULT_OAUTH2_CLIENT_ID;
+        if (persistedClientId !== args.clientId.trim()) {
+            throw new Error("Persisted user OAuth2 tokens are bound to a different OAuth2 client ID; sign in again with the selected client.");
+        }
+        if (persisted && !isExpired(persisted)) {
+            return { value: persisted };
+        }
+        const current = persisted ?? args.current;
+        if (!current.refreshToken) {
+            throw new Error("No refresh_token available; a fresh login is required.");
+        }
+        const next = await (0, auth_js_1.refreshAccessToken)({
+            projectUrl: args.projectUrl,
+            clientId: args.clientId,
+            refreshToken: current.refreshToken,
+        });
+        return {
+            config: {
+                ...config,
+                user: { ...(config.user ?? {}), oauth2: next },
+            },
+            value: next,
+        };
     });
-    saveTokens(next);
-    return next;
+}
+function canonicalProjectOrigin(raw) {
+    if (!raw?.trim()) {
+        throw new Error("Persisted user OAuth2 tokens require projectUrl in the current config.");
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw.trim());
+    }
+    catch {
+        throw new Error("Persisted user OAuth2 tokens require a valid projectUrl origin.");
+    }
+    if ((parsed.protocol !== "https:" && parsed.protocol !== "http:") ||
+        parsed.username ||
+        parsed.password ||
+        (parsed.pathname !== "/" && parsed.pathname !== "") ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error("Persisted user OAuth2 tokens require a valid projectUrl origin.");
+    }
+    return parsed.origin;
 }
 /**
  * Try to acquire the pkce-flight lock. Returns the lock handle if this

package/dist/auth.d.ts

@@ -26,7 +26,7 @@ export declare const LOOPBACK_PORTS: readonly [47823, 47824, 47825, 47826];
  *
  * The binding constraint is Antigravity, which validates its hook timeout to
  * `5..120` seconds — so 120s is the ceiling, and this leaves headroom for the
- * agent DCR registration and delegation record that run after the login inside
+ * Talos enrollment and delegation recording that run after login inside
  * the same hook invocation. See `hook-timeout.ts`, which derives every
  * harness's declared window and asserts it outlasts this value.
  */

package/dist/auth.js

@@ -75,7 +75,7 @@ exports.LOOPBACK_PORTS = [47823, 47824, 47825, 47826];
  *
  * The binding constraint is Antigravity, which validates its hook timeout to
  * `5..120` seconds — so 120s is the ceiling, and this leaves headroom for the
- * agent DCR registration and delegation record that run after the login inside
+ * Talos enrollment and delegation recording that run after login inside
  * the same hook invocation. See `hook-timeout.ts`, which derives every
  * harness's declared window and asserts it outlasts this value.
  */

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "repo": "ory-agent-plugins",
-  "commit": "8e70fe38343bc8599c65c5e1bd4af54861f633be",
-  "commitShort": "8e70fe3",
+  "commit": "7f6431efd4116e683b164cf2c7300cb44d0c4dcb",
+  "commitShort": "7f6431e",
   "branch": "main",
-  "commitDate": "2026-09-14T08:17:01-07:00",
+  "commitDate": "2026-09-28T11:06:31-07:00",
   "dirty": false,
-  "builtAt": "2026-09-14T15:20:26.275Z"
+  "builtAt": "2026-09-28T18:10:11.171Z"
 }

package/dist/cli.js

@@ -300,6 +300,11 @@ function printEnvironment() {
         ],
         ["ORY_USER_SUBJECT_ID", process.env.ORY_USER_SUBJECT_ID, false],
         ["ORY_AGENT_SUBJECT_ID", process.env.ORY_AGENT_SUBJECT_ID, false],
+        [
+            "ORY_AGENT_ROOT_DELEGATION",
+            process.env.ORY_AGENT_ROOT_DELEGATION ? "(set)" : undefined,
+            false,
+        ],
         ["ORY_AGENT_DEBUG", process.env.ORY_AGENT_DEBUG, false],
         ["ORY_AGENT_LOG_FILE", process.env.ORY_AGENT_LOG_FILE, false],
     ];

package/dist/client.d.ts

@@ -93,6 +93,14 @@ export interface RecordDelegationResult {
     /** Root-first chain, e.g. `["User:<id>", "agent:<join>"]`. */
     delegationChain: string[];
 }
+/** Administrator-provisioned runtime metadata resolved from Agent Security. */
+export interface RuntimeContext {
+    authenticated: true;
+    subjectId: string;
+    rootDelegation: string;
+    deploymentId: string;
+    agentType: string;
+}
 /**
  * A principal known to the client. Either the human user (interactive
  * PKCE login) or the agent (machine credentials).
@@ -111,6 +119,7 @@ export declare class OryAgentClient {
     readonly logger: DebugLogger;
     private readonly eventReporter?;
     private _runtimeCredential?;
+    private _runtimeContext?;
     private readonly _runtimeCredentialsBySession;
     private readonly _runtimeCredentialsByPrincipalKey;
     private sessionCache;
@@ -146,6 +155,10 @@ export declare class OryAgentClient {
     /** Active noninteractive broker credential. It is process memory only. */
     get runtimeCredential(): RuntimeCredential | undefined;
     get hasRuntimeCredential(): boolean;
+    /** Process-local deployment context. It is never persisted or copied to the environment. */
+    get runtimeContext(): RuntimeContext | undefined;
+    get runtimeRootDelegation(): string | undefined;
+    setRuntimeContext(context: RuntimeContext): void;
     setRuntimeCredential(credential: RuntimeCredential | undefined): void;
     /** Retain an actor-scoped credential for deferred event delivery without activating it globally. */
     rememberRuntimeCredential(credential: RuntimeCredential): void;
@@ -251,6 +264,8 @@ export declare class OryAgentClient {
         agentToken?: string;
         runtimeCredential?: RuntimeCredential;
         signal?: AbortSignal;
+        /** Authenticate without a user bearer for a preprovisioned root lineage. */
+        preprovisionedRoot?: boolean;
     }): Promise<RecordDelegationResult>;
     /**
      * Activity attributes describing which principals are attached to the