@ory/argus 0.13.8 → 0.14.0

package/README.md

@@ -42,10 +42,11 @@ const client = OryAgentClient.fromEnv("my-harness");
 
 // 1. Session start: authenticate the human and the agent process.
 async function onSessionStart() {
+  // Runs every session and never blocks — it establishes the user identity
+  // for attribution; enforcement happens at the tool gate via permissionMode.
   await ensureUserAuthenticated(client, {
     binName: "my-harness",
     harness: "my-harness",
-    allowBlock: true,
   });
   await ensureAgentIdentity(client, {
     projectUrl: process.env.ORY_PROJECT_URL,

package/assets/commands/dashboard.md

@@ -0,0 +1,34 @@
+# Open the Ory Plugin Dashboard
+
+Open a live, browser-based control panel for the Ory agent plugin. It shows
+the health of the core Ory services the plugin uses (Kratos, Hydra, Keto) and
+the plugin's current configuration (project URL, permission mode, audit mode,
+user-login flag, namespaces, and the resolved user/agent identities),
+refreshing the health status live.
+
+Run:
+
+```bash
+{{NPX}} dashboard
+```
+
+This will:
+
+1. Start a small local web server bound to `127.0.0.1`
+2. Open your default browser at the dashboard
+3. Refresh the service health live
+
+The dashboard is the read-only status view of the Ory Agent web app — the same
+local React UI, loopback server, and styleguide that power the guided web
+installer. It never changes configuration. Stop it with `Ctrl-C` in the
+terminal (or the "Close" button in the page).
+
+When no browser is available (CI, SSH, headless), or with `--json`, it prints a
+machine-readable status report instead:
+
+```bash
+{{NPX}} dashboard --json
+```
+
+If the core services show as unreachable, start the local stack with
+{{REF_LOCAL_UP}} (or check state with `{{NPX}} local status`).

package/assets/skills/ory-build-agent/SKILL.md

@@ -86,16 +86,13 @@ import {
 const client = OryAgentClient.fromEnv("my-agent");
 const { projectUrl } = resolveConfig();
 
-// 1. User gate — interactive PKCE when ORY_USER_LOGIN=true, no-op otherwise.
-const userDecision = await ensureUserAuthenticated(client, {
+// 1. User gate — interactive PKCE; runs every session and never blocks.
+//    Establishes the user identity for attribution; a declined/skipped login
+//    is audited and the flow proceeds (enforcement is at the tool gate).
+await ensureUserAuthenticated(client, {
   binName: "my-agent",
   harness: "my-agent",
-  allowBlock: true, // flip to false if your agent can't refuse to start
 });
-if (userDecision.proceed === false) {
-  console.error(`Ory user login: ${userDecision.reason}`);
-  process.exit(2);
-}
 
 // 2. Agent gate — never blocks; resolves machine credentials (DCR by default).
 await ensureAgentIdentity(client, { projectUrl, harness: "my-agent" });
@@ -113,10 +110,11 @@ if (client.userPrincipal.subject && client.agentPrincipal.subject) {
 }
 ```
 
-Set `allowBlock: false` when the agent runs in-process inside a parent
-application and can't refuse to start. The gate still runs in advisory mode
-— it refreshes tokens, prompts on TTY, emits the `user.auth` span — but
-always returns `proceed: true`.
+The user gate runs on every session and is always non-blocking: it refreshes
+tokens, prompts on TTY, and emits the `user.auth` span, but always returns
+`proceed: true`. A missing or declined login never stops the agent — the
+consequence surfaces at the tool gate, where `permissionMode: enforce` denies
+and `observe` audits.
 
 ## Step 4 — The shared gate body
 
@@ -409,8 +407,8 @@ PKCE flow, permission tuples, and trace spans are all visible:
 1. {{REF_LOCAL_UP}} — brings up Kratos / Keto / Hydra on `localhost:4000`
    and seeds a demo user. The banner prints the email + password.
 2. Export the env vars the launcher writes (`ORY_PROJECT_URL`,
-   `ORY_USER_LOGIN=true`, `ORY_OAUTH2_CLIENT_ID`, optional
-   `ORY_AGENT_TRACE_FILE` for an NDJSON span log).
+   `ORY_OAUTH2_CLIENT_ID`, optional `ORY_AGENT_TRACE_FILE` for an NDJSON
+   span log). The user login runs every session.
 3. Start your agent. Confirm the browser opens for PKCE login.
 4. Invoke a gated tool and `tail -f $ORY_AGENT_TRACE_FILE | jq .` — you
    should see `user.auth` → `agent.auth` → `permission.check` →

package/assets/skills/ory-e2b-sandbox/SKILL.md

@@ -66,7 +66,6 @@ export const template = Template()
   // Sandbox runtime defaults. Per-tenant secrets (project URL, tokens, client
   // IDs) MUST be passed at Sandbox.create() time, never baked into the image.
   .setEnvs({
-    ORY_USER_LOGIN: "true",
     ORY_PERMISSION_MODE: "observe",
     ORY_PERMISSION_NAMESPACE: "AgentTools",
     ORY_AGENT_DEBUG: "true",

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

@@ -83,12 +83,10 @@ function bootstrap(): Promise<void> {
       await ensureUserAuthenticated(ory, {
         binName: "temporal-worker",
         harness: "temporal",
-        // Temporal's Activity entry point has no channel to carry a
-        // session-start block, so the user gate runs in advisory mode:
-        // it still refreshes tokens and emits the audit span, but the
-        // worker proceeds even if the user is unauthenticated. Hard
-        // enforcement happens at the per-Activity permission check.
-        allowBlock: false,
+        // The user gate runs every invocation and never blocks: it refreshes
+        // tokens and emits the audit span, but the worker proceeds even if the
+        // user is unauthenticated. Enforcement happens at the per-Activity
+        // permission check (permissionMode).
       });
       await ensureAgentIdentity(ory, {
         projectUrl: process.env.ORY_PROJECT_URL,
@@ -145,10 +143,10 @@ Key choices:
 
 - **Activities call Ory, Workflows don't.** Anything that needs a live decision
   goes in an Activity. Workflows only orchestrate.
-- **`allowBlock: false`.** The Activity boundary can't carry a session-start
-  block, so the user gate runs in advisory mode. Enforcement is at the
-  permission check, which throws on deny — Temporal will mark the Activity as
-  failed and surface the error via the Workflow result or retry policy.
+- **The user gate never blocks.** It runs every invocation to refresh the user
+  identity, but always proceeds. Enforcement is at the permission check, which
+  throws on deny — Temporal will mark the Activity as failed and surface the
+  error via the Workflow result or retry policy.
 - **`harness: "temporal"`.** Distinguishes worker-originated spans in the trace
   file from CLI plugin spans.
 - **Span attributes carry the Workflow + Activity IDs.** This is how operators

package/assets/skills/permissions-onboarding/SKILL.md

@@ -44,7 +44,7 @@ If any of those are wrong, fix them before continuing:
 {{NPX}} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]
 ```
 
-`--oauth2-client-id` is the public OAuth2 client registered in your Ory project (required when `ORY_USER_LOGIN=true`; see the *Register the user OAuth2 client* section of the plugin README).
+`--oauth2-client-id` is the public OAuth2 client registered in your Ory project (needed for the per-session user login to complete its PKCE browser flow; see the *Register the user OAuth2 client* section of the plugin README).
 
 ## Step 2: Look at the current permission posture
 
@@ -94,9 +94,9 @@ out-of-band as they come into scope.
 Two common failure modes:
 
 1. **No user identity cached.** Bootstrap needs to know which subject
-   to grant tuples to. If user login has never run (no PKCE login,
+   to grant tuples to. If the user login has never completed (no PKCE login,
    no `ORY_USER_SUBJECT_ID`), the command refuses. Run the harness once
-   with `ORY_USER_LOGIN=true` to cache a user token, or set
+   (the user login runs every session) to cache a user token, or set
    `ORY_USER_SUBJECT_ID=<id>` to target a known subject.
 2. **Credentials lack write scope on the permission namespace.** The
    command prints the full tuple list so you can apply them manually

package/dist/adapters.d.ts

@@ -30,7 +30,6 @@ export interface SessionStartResult {
 }
 export interface SessionStartOptions {
     harness: string;
-    allowBlock?: boolean;
     projectUrl?: string;
     binName?: string;
     /** Injectable gates (tests). */
@@ -38,11 +37,27 @@ export interface SessionStartOptions {
     agentGate?: typeof ensureAgentIdentity;
 }
 /**
- * Run both auth gates and write the user→agent delegation tuple. `allowBlock` is advisory
- * for in-process SDK integrations (the agent can't be prevented from constructing), but the
- * user gate still runs, refreshes tokens, and records the `user.auth` span.
+ * Run both auth gates and write the user→agent delegation tuple. The user gate
+ * runs every session to establish/refresh the user identity, records the
+ * `user.auth` span, and never blocks — enforcement is governed by
+ * `permissionMode` at tool-call time. `SessionStartResult.proceed` is therefore
+ * always `true`; it is retained only for a stable adapter shape.
  */
 export declare function sessionStart(client: OryAgentClient, opts: SessionStartOptions): Promise<SessionStartResult>;
+/**
+ * Write the `user → agent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that run
+ * their own session-start sequence (rather than {@link sessionStart}) share
+ * the same write-once semantics instead of re-issuing the write every
+ * session.
+ *
+ * The tuple is a *derived projection* of the delegation anchor stamped into
+ * the agent's OAuth2 client metadata at registration: the edge is resolved
+ * from the live principals when populated, otherwise rebuilt from the persisted
+ * anchor — so a tuple lost out of band can be self-healed from the identity
+ * layer. No-op only when neither source yields both ends.
+ */
+export declare function writeUserDelegatesAgent(client: OryAgentClient): Promise<void>;
 export interface RegisterSubagentOptions {
     harness: string;
     subAgentType: string;
@@ -50,6 +65,14 @@ export interface RegisterSubagentOptions {
     subAgentGate?: typeof ensureSubAgentIdentity;
 }
 export declare function registerSubagent(client: OryAgentClient, opts: RegisterSubagentOptions): Promise<void>;
+/**
+ * Write the `agent → subagent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that
+ * resolve the sub-agent identity through their own event plumbing (rather
+ * than {@link registerSubagent}) still share the write-once semantics.
+ * No-op until the agent principal is populated.
+ */
+export declare function writeAgentDelegatesSubagent(client: OryAgentClient, subAgentSubject: string, subAgentType: string): Promise<void>;
 export interface GateResult {
     /** False only when the tool was hard-denied in enforce mode. */
     proceed: boolean;

package/dist/adapters.js

@@ -21,7 +21,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveNamespace = resolveNamespace;
 exports.sessionStart = sessionStart;
+exports.writeUserDelegatesAgent = writeUserDelegatesAgent;
 exports.registerSubagent = registerSubagent;
+exports.writeAgentDelegatesSubagent = writeAgentDelegatesSubagent;
 exports.gate = gate;
 exports.complete = complete;
 exports.wrapTool = wrapTool;
@@ -35,9 +37,11 @@ function resolveNamespace() {
     return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
 }
 /**
- * Run both auth gates and write the user→agent delegation tuple. `allowBlock` is advisory
- * for in-process SDK integrations (the agent can't be prevented from constructing), but the
- * user gate still runs, refreshes tokens, and records the `user.auth` span.
+ * Run both auth gates and write the user→agent delegation tuple. The user gate
+ * runs every session to establish/refresh the user identity, records the
+ * `user.auth` span, and never blocks — enforcement is governed by
+ * `permissionMode` at tool-call time. `SessionStartResult.proceed` is therefore
+ * always `true`; it is retained only for a stable adapter shape.
  */
 async function sessionStart(client, opts) {
     const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
@@ -46,13 +50,12 @@ async function sessionStart(client, opts) {
     const decision = await userLogin(client, {
         binName: opts.binName ?? `ory-${opts.harness}`,
         harness: opts.harness,
-        allowBlock: opts.allowBlock ?? false,
     });
     const creds = await agentGate(client, {
         projectUrl,
         harness: opts.harness,
     });
-    await recordUserDelegatesAgent(client);
+    await writeUserDelegatesAgent(client);
     return {
         proceed: decision.proceed,
         userMode: decision.mode,
@@ -60,25 +63,104 @@ async function sessionStart(client, opts) {
         agentKind: creds.kind,
     };
 }
-async function recordUserDelegatesAgent(client) {
-    const user = client.userPrincipal.subject;
-    const agent = client.agentPrincipal.subject;
-    if (!user || !agent)
-        return;
+/**
+ * Write a delegation tuple at most once. The tuple is stable for a given
+ * (namespace, object, subject), and Keto's create API is not idempotent, so
+ * this goes through {@link OryAgentClient.ensureRelationship}: it reads the
+ * exact tuple first and only writes when absent — no duplicate on repeated
+ * session starts, and self-healing if the tuple was deleted. If the existence
+ * probe fails we skip the write rather than risk a duplicate (delegation
+ * tuples are audit-only, so a missed write is harmless and retried next
+ * session). Best-effort: any failure is logged and swallowed.
+ */
+async function writeDelegationOnce(client, check, options) {
     try {
-        await client.createRelationship({
-            namespace: resolveNamespace(),
-            object: `agent:${agent}`,
-            relation: "delegate",
-            subjectId: `user:${user}`,
-        }, { spanAttributes: { delegation: "user-to-agent" } });
+        const res = await client.ensureRelationship(check, {
+            spanAttributes: options.spanAttributes,
+        });
+        if (res.probeError) {
+            client.logger.debug("delegation.probe_failed", {
+                ...options.failedContext,
+                message: res.probeError.message,
+            });
+        }
     }
     catch (err) {
-        client.logger.warn("delegation.user_to_agent.failed", {
+        client.logger.warn(options.failedEvent, {
+            ...options.failedContext,
             message: err instanceof Error ? err.message : String(err),
         });
     }
 }
+/** Strip a `<ns>:` prefix from a namespaced subject, if present. */
+function unqualify(subject, ns) {
+    const prefix = `${ns}:`;
+    return subject.startsWith(prefix) ? subject.slice(prefix.length) : undefined;
+}
+/**
+ * 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 tuple be
+ * rebuilt 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.
+ */
+function reconcileEdgeEnd(client, principal, anchor, role) {
+    if (principal && anchor && principal !== anchor) {
+        client.logger.debug("delegation.anchor_mismatch", { role, principal, anchor });
+    }
+    return principal ?? anchor;
+}
+/**
+ * Write the `user → agent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that run
+ * their own session-start sequence (rather than {@link sessionStart}) share
+ * the same write-once semantics instead of re-issuing the write every
+ * session.
+ *
+ * The tuple is a *derived projection* of the delegation anchor stamped into
+ * the agent's OAuth2 client metadata at registration: the edge is resolved
+ * from the live principals when populated, otherwise rebuilt from the persisted
+ * anchor — so a tuple lost out of band can be self-healed from the identity
+ * layer. No-op only when neither source yields both ends.
+ */
+async function writeUserDelegatesAgent(client) {
+    // The anchor is the delegation *record* stamped into the agent client's
+    // metadata — not the mere existence of a persisted client. Only when a
+    // user-to-agent record is present do we know the delegator, so both ends of
+    // the edge are taken from the same record's client (agent = its clientId,
+    // user = its delegatedBy). Absent a record, fall back to live principals only.
+    const anchorCreds = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
+    const anchor = anchorCreds?.delegation;
+    const hasUserAgentAnchor = anchor?.delegationType === "user-to-agent";
+    const anchorUser = hasUserAgentAnchor ? unqualify(anchor.delegatedBy, "user") : undefined;
+    // The agent principal's subject is `ORY_AGENT_SUBJECT_ID ?? clientId` (see
+    // resolveClientCredentials). The anchor rebuild must apply the *same*
+    // precedence, or a no-principal session would write `agent:<clientId>` while
+    // a live session wrote `agent:<override>` — two divergent tuples for one edge.
+    const anchorAgent = hasUserAgentAnchor
+        ? (process.env.ORY_AGENT_SUBJECT_ID || anchorCreds.clientId)
+        : undefined;
+    const user = reconcileEdgeEnd(client, client.userPrincipal.subject, anchorUser, "user");
+    const agent = reconcileEdgeEnd(client, client.agentPrincipal.subject, anchorAgent, "agent");
+    if (!user || !agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "missing delegation edge (no principal and no anchor)",
+            hasUser: !!user,
+            hasAgent: !!agent,
+        });
+        return;
+    }
+    await writeDelegationOnce(client, {
+        namespace: resolveNamespace(),
+        object: `agent:${agent}`,
+        relation: "delegate",
+        subjectId: `user:${user}`,
+    }, {
+        spanAttributes: { delegation: "user-to-agent" },
+        failedEvent: "delegation.user_to_agent.failed",
+    });
+}
 async function registerSubagent(client, opts) {
     const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
     const subAgentGate = opts.subAgentGate ?? agent_auth_js_1.ensureSubAgentIdentity;
@@ -99,23 +181,41 @@ async function registerSubagent(client, opts) {
     }
     if (identity.kind !== "dynamic" || !identity.subject)
         return;
-    const agent = client.agentPrincipal.subject;
-    if (!agent)
-        return;
-    try {
-        await client.createRelationship({
-            namespace: resolveNamespace(),
-            object: `subagent:${identity.subject}`,
-            relation: "delegate",
-            subjectId: `agent:${agent}`,
-        }, { spanAttributes: { delegation: "agent-to-subagent", subAgentType: opts.subAgentType } });
-    }
-    catch (err) {
-        client.logger.warn("delegation.agent_to_subagent.failed", {
-            subAgentType: opts.subAgentType,
-            message: err instanceof Error ? err.message : String(err),
+    await writeAgentDelegatesSubagent(client, identity.subject, opts.subAgentType);
+}
+/**
+ * Write the `agent → subagent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that
+ * resolve the sub-agent identity through their own event plumbing (rather
+ * than {@link registerSubagent}) still share the write-once semantics.
+ * No-op until the agent principal is populated.
+ */
+async function writeAgentDelegatesSubagent(client, subAgentSubject, subAgentType) {
+    // The delegator (agent) is resolved from the live principal, falling back to
+    // the sub-agent client's persisted delegation anchor (`delegation.delegatedBy`
+    // = `agent:<agent>`) so the tuple can be rebuilt when no principal is present.
+    const anchor = (0, agent_auth_js_1.loadSubAgentDynamicCredentials)(subAgentType)?.delegation;
+    const anchorAgent = anchor?.delegationType === "agent-to-subagent"
+        ? unqualify(anchor.delegatedBy, "agent")
+        : undefined;
+    const agent = reconcileEdgeEnd(client, client.agentPrincipal.subject, anchorAgent, "agent");
+    if (!agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "no agent delegation edge (no principal and no anchor)",
+            subAgentType,
         });
+        return;
     }
+    await writeDelegationOnce(client, {
+        namespace: resolveNamespace(),
+        object: `subagent:${subAgentSubject}`,
+        relation: "delegate",
+        subjectId: `agent:${agent}`,
+    }, {
+        spanAttributes: { delegation: "agent-to-subagent", subAgentType },
+        failedEvent: "delegation.agent_to_subagent.failed",
+        failedContext: { subAgentType },
+    });
 }
 /**
  * Authorize a tool call, record the spans, and return a normalized {@link GateResult}.

package/dist/agent-auth.d.ts

@@ -26,8 +26,19 @@
  * the user with an `act` claim showing the agent — is intentionally
  * deferred.
  */
-import { type OryAgentDynamicCredentials } from "./config.js";
+import { type OryAgentDynamicCredentials, type OryDelegationRecord } from "./config.js";
 import { OryAgentClient } from "./client.js";
+/**
+ * Delegation context handed to {@link registerAgentClient} so the freshly
+ * minted OAuth2 client is stamped with its delegator at the identity layer.
+ * `delegatedAt` is stamped by the registrar, not the caller.
+ */
+export interface DelegationInput {
+    /** The delegator, namespaced: `user:<sub>` or `agent:<sub>`. */
+    delegatedBy: string;
+    delegationType: OryDelegationRecord["delegationType"];
+    subAgentType?: string;
+}
 export type AgentCredentialKind = "api_key" | "client_credentials" | "dynamic" | "none";
 export interface AgentCredentials {
     kind: AgentCredentialKind;
@@ -64,6 +75,13 @@ export interface ResolveAgentCredentialsOptions {
     env?: NodeJS.ProcessEnv;
     /** User's bearer token; preferred IAT for dynamic registration. */
     userToken?: string;
+    /**
+     * User's subject. When present, a fresh DCR stamps `metadata.delegatedBy`
+     * = `user:<userSubject>` on the agent client so the user→agent delegation
+     * has an identity-layer anchor. Absent ⇒ the client registers without a
+     * delegation anchor (no delegator known).
+     */
+    userSubject?: string;
     /** Harness identifier — baked into the registered client_name. */
     harness?: string;
     /** Inject the client_credentials token-grant function for tests. */
@@ -125,8 +143,21 @@ export interface RegisterAgentClientArgs {
     auth: string;
     /** Harness identifier baked into the client_name for audit. */
     harness?: string;
+    /** When set, names the client as a sub-agent of the given type. */
+    subAgentType?: string;
+    /**
+     * Delegation edge recorded for this client. When present, the issued
+     * credentials carry a durable record of who delegated to the agent — the
+     * integrity anchor from which the Keto delegation tuple can be rebuilt.
+     * Persisted in local config only; Ory's public DCR endpoint rejects a
+     * `metadata` field, so it is not stored server-side. Omitted when the
+     * delegator isn't known at registration time.
+     */
+    delegation?: DelegationInput;
     /** Override hostname for testing. */
     hostnameFn?: () => string;
+    /** Inject the wall clock for deterministic `delegatedAt` in tests. */
+    nowFn?: () => Date;
 }
 /**
  * Register a new OAuth2 client via RFC 7591. Authorization is carried
@@ -224,8 +255,8 @@ export interface EnsureSubAgentIdentityOptions {
  * Resolve a sub-agent identity via OAuth2 Dynamic Client Registration.
  *
  * Reuses persisted credentials when the `(projectUrl, subAgentType)`
- * pair matches; otherwise registers a fresh client with
- * `client_name = ory-subagent-<type>@<host>` and persists the result.
+ * pair matches; otherwise registers a fresh client named
+ * `Ory Agent Security · sub-agent · <harness>/<type> @ <host>` and persists the result.
  * Never throws and never blocks — on any failure the identity collapses
  * to `kind: "none"` and the plugin continues without it. Emits exactly
  * one `agent.auth` span so the audit trail records each sub-agent

package/dist/agent-auth.js

@@ -45,6 +45,7 @@ exports.ensureSubAgentIdentity = ensureSubAgentIdentity;
 const node_os_1 = require("node:os");
 const client_1 = require("@ory/client");
 const config_js_1 = require("./config.js");
+const branding_js_1 = require("./branding.js");
 /**
  * Skew window before nominal expiry at which a cached client_credentials
  * token is considered stale. Matches the user-token skew in auth-store.
@@ -162,9 +163,26 @@ async function revokeAgentDynamicClient(creds) {
  */
 async function registerAgentClient(args) {
     const host = (args.hostnameFn ?? node_os_1.hostname)() || "unknown-host";
-    const clientName = args.harness
-        ? `ory-agent-${args.harness}@${host}`
-        : `ory-agent@${host}`;
+    const clientName = (0, branding_js_1.agentClientName)({
+        harness: args.harness,
+        host,
+        subAgentType: args.subAgentType,
+    });
+    // Build the delegation anchor (if a delegator is known) and mirror it into the
+    // persisted credentials. This is the integrity anchor the Keto tuple is derived
+    // from. It is NOT sent to Ory: the public DCR endpoint rejects a `metadata`
+    // field (see the request body below), so the anchor lives only in local config.
+    const delegation = args.delegation
+        ? {
+            delegatedBy: args.delegation.delegatedBy,
+            delegationType: args.delegation.delegationType,
+            ...(args.harness ? { harness: args.harness } : {}),
+            ...(args.delegation.subAgentType
+                ? { subAgentType: args.delegation.subAgentType }
+                : {}),
+            delegatedAt: (args.nowFn ?? (() => new Date()))().toISOString(),
+        }
+        : undefined;
     const oidc = new client_1.OidcApi(new client_1.Configuration({
         basePath: args.projectUrl,
         accessToken: args.auth,
@@ -178,6 +196,14 @@ async function registerAgentClient(args) {
                 response_types: ["token"],
                 scope: "openid offline_access",
                 token_endpoint_auth_method: "client_secret_post",
+                // NB: the delegation record is deliberately NOT sent as `metadata`.
+                // Ory Network / Hydra reject a `metadata` field on the public DCR
+                // endpoints — both RFC 7591 create and RFC 7592 update return
+                // `400 invalid_client_metadata: 'metadata' cannot be set for dynamic
+                // client registration` (metadata is admin-API-only). Sending it made
+                // every fresh registration fail, so the agent never got credentials.
+                // The delegation anchor is persisted locally instead (see the return
+                // value) and is never read back from the server side.
             },
         }, 
         // The generated SDK declares no security scheme for the public DCR create
@@ -206,6 +232,7 @@ async function registerAgentClient(args) {
         registeredAt: Math.floor(Date.now() / 1000),
         projectUrl: args.projectUrl,
         harness: args.harness,
+        ...(delegation ? { delegation } : {}),
     };
 }
 /**
@@ -300,6 +327,14 @@ async function resolveAgentCredentials(options = {}) {
                 projectUrl: options.projectUrl,
                 auth: iat,
                 harness: options.harness,
+                ...(options.userSubject
+                    ? {
+                        delegation: {
+                            delegatedBy: `user:${options.userSubject}`,
+                            delegationType: "user-to-agent",
+                        },
+                    }
+                    : {}),
             });
             if (!registered.clientSecret) {
                 warnings.push("Dynamic registration returned no client_secret; cannot run client_credentials grant.");
@@ -341,7 +376,7 @@ async function resolveAgentCredentials(options = {}) {
     }
     return {
         kind: "none",
-        reason: "No agent credentials configured. Run with a user session (ORY_USER_LOGIN=true) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
+        reason: "No agent credentials configured. Run with a user session (the interactive user login runs every session) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
         warnings,
     };
 }
@@ -473,9 +508,11 @@ async function ensureAgentIdentity(client, options = {}) {
         creds = await resolveFn({
             projectUrl: options.projectUrl,
             env: options.env,
-            // The user gate populates userPrincipal.token on successful login;
-            // we hand it to the resolver so DCR can use it as the IAT.
+            // The user gate populates userPrincipal on successful login; we hand the
+            // token to the resolver so DCR can use it as the IAT, and the subject so
+            // the fresh client is stamped with its delegator (metadata.delegatedBy).
             userToken: client.userPrincipal.token,
+            userSubject: client.userPrincipal.subject,
             harness: options.harness,
         });
     }
@@ -512,8 +549,8 @@ async function ensureAgentIdentity(client, options = {}) {
  * Resolve a sub-agent identity via OAuth2 Dynamic Client Registration.
  *
  * Reuses persisted credentials when the `(projectUrl, subAgentType)`
- * pair matches; otherwise registers a fresh client with
- * `client_name = ory-subagent-<type>@<host>` and persists the result.
+ * pair matches; otherwise registers a fresh client named
+ * `Ory Agent Security · sub-agent · <harness>/<type> @ <host>` and persists the result.
  * Never throws and never blocks — on any failure the identity collapses
  * to `kind: "none"` and the plugin continues without it. Emits exactly
  * one `agent.auth` span so the audit trail records each sub-agent
@@ -550,6 +587,10 @@ async function ensureSubAgentIdentity(client, options) {
             subAgentType: options.subAgentType,
             projectUrl: options.projectUrl,
             harness: options.harness,
+            // The delegator for a sub-agent is the parent agent. When its subject is
+            // populated, stamp `metadata.delegatedBy` = `agent:<agent>` on the
+            // sub-agent client so the agent→subagent edge is anchored to the identity.
+            delegatorSubject: client.agentPrincipal.subject,
             iat: options.iat
                 ?? client.agentPrincipal.token
                 ?? client.userPrincipal.token
@@ -633,6 +674,15 @@ async function resolveSubAgentIdentity(args) {
             projectUrl: args.projectUrl,
             auth: args.iat,
             harness: subHarness,
+            ...(args.delegatorSubject
+                ? {
+                    delegation: {
+                        delegatedBy: `agent:${args.delegatorSubject}`,
+                        delegationType: "agent-to-subagent",
+                        subAgentType: args.subAgentType,
+                    },
+                }
+                : {}),
         });
         args.saveFn(args.subAgentType, registered);
         return {

package/dist/auth.d.ts

@@ -91,3 +91,10 @@ export declare function refreshAccessToken(args: {
     clientId: string;
     refreshToken: string;
 }): Promise<OryOAuth2Tokens>;
+/**
+ * Best-effort human-readable name for the signed-in user, pulled from the
+ * id_token's identity claims — `email`, then `name`, then `preferred_username`.
+ * Returns undefined when the token carries none of them (e.g. an `openid`-only
+ * token), so callers fall back to the opaque subject id.
+ */
+export declare function displayNameFromIdToken(idToken: string | undefined): string | undefined;