@ory/argus 0.13.9 → 1.0.0

package/dist/client.js

@@ -33,25 +33,56 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TRACE_FILENAME = exports.DEFAULT_DEBUG_LOG_FILENAME = exports.OryAgentClient = void 0;
+exports.DEFAULT_DEBUG_LOG_FILENAME = exports.OryAgentClient = void 0;
 exports.resolveDebugLogPath = resolveDebugLogPath;
-exports.resolveTraceFilePath = resolveTraceFilePath;
 exports.extractOryRequestId = extractOryRequestId;
 const client_1 = require("@ory/client");
 const path = __importStar(require("node:path"));
 const logger_js_1 = require("./logger.js");
-const tracer_js_1 = require("./tracer.js");
+const event_reporter_js_1 = require("./event-reporter.js");
+const agent_auth_js_1 = require("./agent-auth.js");
+const context_js_1 = require("./context.js");
 const config_js_1 = require("./config.js");
 const auth_store_js_1 = require("./auth-store.js");
-const otlp_js_1 = require("./otel/otlp.js");
+const runtime_credential_js_1 = require("./runtime-credential.js");
+const BROKER_PERMISSION_BATCH_SIZE = 10;
+function permissionCheckFromRequest(request) {
+    return {
+        namespace: request.namespace,
+        object: request.object,
+        relation: request.relation,
+        subjectId: request.subjectId,
+        subjectSet: request.subjectSetNamespace && request.subjectSetObject !== undefined
+            ? {
+                namespace: request.subjectSetNamespace,
+                object: request.subjectSetObject,
+                relation: request.subjectSetRelation ?? "",
+            }
+            : undefined,
+    };
+}
+function permissionCheckFromTuple(tuple) {
+    return {
+        namespace: tuple.namespace,
+        object: tuple.object,
+        relation: tuple.relation,
+        subjectId: tuple.subject_id,
+        subjectSet: tuple.subject_set,
+    };
+}
+function httpError(status, message) {
+    return Object.assign(new Error(message), { status });
+}
 class OryAgentClient {
     frontend;
     oauth2;
     permission;
-    relationship;
     config;
     logger;
-    tracer;
+    eventReporter;
+    _runtimeCredential;
+    _runtimeCredentialsBySession = new Map();
+    _runtimeCredentialsByPrincipalKey = new Map();
     sessionCache = new Map();
     sessionCacheTtlMs;
     /**
@@ -59,94 +90,383 @@ class OryAgentClient {
      * Populated by `ensureUserAuthenticated` on session start.
      */
     _userPrincipal = {};
+    _userPrincipalsBySession = new Map();
     /**
      * The AI agent process — the principal that authenticates outgoing
      * Ory API calls. Populated by `ensureAgentIdentity`.
      */
     _agentPrincipal = {};
-    /**
-     * Admin credential — an Ory Network **project API key** (`ory_pat_…`) —
-     * used to authenticate the Keto Permission and Relationship APIs.
-     *
-     * This is deliberately distinct from the agent principal's token. Ory
-     * Network's permission APIs authenticate with a project API key and
-     * **reject project-issued OAuth2 access tokens** (a DCR client-credentials
-     * token is answered with `401 "Access token is not active"`). So when the
-     * agent identity resolves to a DCR OAuth2 client — the default path — its
-     * token cannot authenticate permission checks. Holding the admin key here
-     * lets {@link buildApis} route Keto through it while the agent OAuth2 token
-     * still authenticates the OAuth2 / Frontend APIs and carries attribution.
-     *
-     * When unset, Keto calls fall back to the agent token (legacy
-     * single-credential behavior, unchanged for static-key deployments).
-     */
-    _adminApiKey;
+    _agentPrincipalsBySession = new Map();
+    _eventPrincipalsByKey = new Map();
     constructor(config) {
         this.config = config;
         this.sessionCacheTtlMs = config.sessionCacheTtlMs ?? 60_000;
         this.logger = new logger_js_1.DebugLogger(config.harness, {
             logFile: config.logFile,
         });
-        this.tracer = new tracer_js_1.Tracer({
-            harness: config.harness,
-            traceFile: config.traceFile,
-            ...(config.exporter ? { exporter: config.exporter } : {}),
+        this.logger.setActivityEnricher(() => this.principalActivityAttributes());
+        this._runtimeCredential = (0, runtime_credential_js_1.resolveRuntimeCredential)({
+            requestAuthenticator: config.runtimeRequestAuthenticator,
+            subject: config.runtimeSubject ?? process.env.ORY_AGENT_SUBJECT_ID?.trim(),
         });
-        // Every span — including direct `tracer.record(...)` calls from
-        // plugin handlers — gets userSubject / agentSubject merged in, so
-        // tool.invoke / tool.block / permission.observe_deny spans carry
-        // the same principal attribution as the API-call spans.
-        this.tracer.setAttributeEnricher(() => this.principalSpanAttributes());
-        // Seed agent principal from the constructor `apiKey` so existing
-        // call sites keep working until they migrate to ensureAgentIdentity.
-        if (config.apiKey)
-            this._agentPrincipal.token = config.apiKey;
-        // The `apiKey` is also the admin credential for the Keto Permission /
-        // Relationship APIs. Seed it separately so that when `ensureAgentIdentity`
-        // later replaces the agent token with a DCR OAuth2 token, permission
-        // checks keep authenticating with the project API key rather than the
-        // OAuth2 token Ory Network rejects. See {@link _adminApiKey}.
-        if (config.apiKey)
-            this._adminApiKey = config.apiKey;
-        const { frontend, oauth2, permission, relationship } = this.buildApis();
+        if (this._runtimeCredential?.subject) {
+            this._agentPrincipal = { subject: this._runtimeCredential.subject };
+        }
+        if (config.eventReporter) {
+            const reporterOptions = config.eventReporter === true ? {} : config.eventReporter;
+            this.eventReporter = new event_reporter_js_1.AgentSecurityEventReporter({
+                ...reporterOptions,
+                projectUrl: config.projectUrl,
+                agentSecurityUrl: this.agentSecurityUrl,
+                token: (sessionId, principalKey) => this.eventPrincipal(sessionId, principalKey).token,
+                request: (url, init, sessionId, principalKey) => {
+                    const credential = (principalKey ? this._runtimeCredentialsByPrincipalKey.get(principalKey) : undefined) ??
+                        (sessionId ? this._runtimeCredentialsBySession.get(sessionId) : undefined) ??
+                        this._runtimeCredential;
+                    if (!credential)
+                        return undefined;
+                    return (0, runtime_credential_js_1.authenticatedRuntimeRequest)(credential, {
+                        url,
+                        init,
+                        authorizationHeader: "authorization",
+                    });
+                },
+                onUnauthorized: (sessionId, principalKey, rejectedToken) => {
+                    const principal = this.eventPrincipal(sessionId, principalKey);
+                    if (principal.token === rejectedToken) {
+                        if (principalKey) {
+                            this._eventPrincipalsByKey.set(principalKey, { subject: principal.subject });
+                            if (this.agentPrincipalForSession(sessionId).subject
+                                && (0, event_reporter_js_1.eventPrincipalKey)(this.agentPrincipalForSession(sessionId).subject) === principalKey) {
+                                this.setAgentPrincipal({ subject: principal.subject }, sessionId);
+                            }
+                        }
+                        else {
+                            this.setAgentPrincipal({ subject: principal.subject }, sessionId);
+                        }
+                        (0, agent_auth_js_1.invalidateAgentAccessToken)(rejectedToken);
+                    }
+                },
+                logger: this.logger,
+            });
+            this.logger.setActivitySink((entry) => {
+                const enrichedSubject = entry.attributes?.agentSubject;
+                const principal = typeof enrichedSubject === "string"
+                    ? { subject: enrichedSubject }
+                    : this.agentPrincipalForSession(entry.sessionId);
+                this.eventReporter?.enqueue(entry, principal.subject ? (0, event_reporter_js_1.eventPrincipalKey)(principal.subject) : undefined);
+            });
+        }
+        // User OAuth APIs remain independent from the runtime credential used by
+        // Agent Security broker requests.
+        const { frontend, oauth2, permission } = this.buildApis();
         this.frontend = frontend;
         this.oauth2 = oauth2;
         this.permission = permission;
-        this.relationship = relationship;
     }
     /** Build a fresh set of Ory API instances using the current agent token. */
     buildApis() {
-        const accessToken = this._agentPrincipal.token;
+        const accessToken = this.agentPrincipal.token;
+        const auth = accessToken ? { accessToken } : {};
         const apiConfig = new client_1.Configuration({
             basePath: this.config.projectUrl,
-            ...(accessToken ? { accessToken } : {}),
+            ...auth,
         });
-        // Keto (Permission + Relationship) authenticates with the admin project
-        // API key when one is set; otherwise it reuses the agent token (legacy
-        // single-credential behavior). When the two credentials are identical we
-        // reuse the same Configuration object so a single-credential deployment —
-        // and tests that stub one Configuration — see exactly one.
-        const ketoToken = this._adminApiKey ?? accessToken;
-        const ketoConfig = ketoToken === accessToken
-            ? apiConfig
-            : new client_1.Configuration({
-                basePath: this.config.projectUrl,
-                ...(ketoToken ? { accessToken: ketoToken } : {}),
-            });
         return {
             frontend: new client_1.FrontendApi(apiConfig),
             oauth2: new client_1.OAuth2Api(apiConfig),
-            permission: new client_1.PermissionApi(ketoConfig),
-            relationship: new client_1.RelationshipApi(ketoConfig),
+            permission: this.buildBrokerPermissionTransport(),
         };
     }
+    /** Canonical broker origin, with the shipped project URL fallback applied. */
+    get agentSecurityUrl() {
+        return this.config.agentSecurityUrl ?? this.config.projectUrl;
+    }
+    buildBrokerPermissionTransport() {
+        return {
+            checkPermission: async (request) => {
+                const response = await this.postPermissionChecks([permissionCheckFromRequest(request)]);
+                return { data: response.data.results[0] ?? { allowed: false }, headers: response.headers };
+            },
+            batchCheckPermission: async ({ batchCheckPermissionBody }) => {
+                const checks = batchCheckPermissionBody.tuples.map(permissionCheckFromTuple);
+                return this.postPermissionChecks(checks);
+            },
+        };
+    }
+    async postPermissionChecks(checks) {
+        const credential = this.runtimeCredential;
+        if (!credential)
+            throw httpError(403, "Runtime credential is required for permission checks");
+        const results = [];
+        let headers;
+        for (let start = 0; start < checks.length; start += BROKER_PERMISSION_BATCH_SIZE) {
+            const chunk = checks.slice(start, start + BROKER_PERMISSION_BATCH_SIZE);
+            const body = {
+                project_url: this.config.projectUrl,
+                checks: chunk.map((check) => ({
+                    namespace: check.namespace,
+                    object: check.object,
+                    relation: check.relation,
+                    principal: this.permissionPrincipal(check),
+                })),
+            };
+            const response = await (0, runtime_credential_js_1.authenticatedRuntimeRequest)(credential, {
+                url: `${this.agentSecurityUrl.replace(/\/+$/, "")}/agent-security/v1/permissions:check`,
+                init: {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(30_000),
+                },
+                authorizationHeader: "authorization",
+            });
+            if (!response.ok)
+                throw httpError(response.status, `HTTP ${response.status}`);
+            const data = await response.json();
+            if (!Array.isArray(data.results)
+                || data.results.length !== chunk.length
+                || data.results.some((result) => typeof result !== "object"
+                    || result === null
+                    || typeof result.allowed !== "boolean"
+                    || (result.error !== undefined && typeof result.error !== "string"))) {
+                throw httpError(403, "Agent Security returned an invalid permission result");
+            }
+            results.push(...data.results);
+            headers = response.headers;
+        }
+        return { data: { results }, headers };
+    }
+    permissionPrincipal(check) {
+        if (check.subjectId) {
+            throw httpError(403, "Permission subject IDs are not accepted by Agent Security");
+        }
+        const subject = check.subjectSet;
+        if (!subject)
+            throw httpError(403, "Permission check has no representable principal");
+        const projectPrincipal = subject.object === "project" &&
+            subject.relation === "enforcedSubjects" &&
+            subject.namespace === "PermissionMode";
+        if (projectPrincipal &&
+            (check.relation === "blockedSubjects" || (check.namespace === "PermissionMode" &&
+                check.object === "mode" &&
+                check.relation === "enforcedSubjects"))) {
+            return { kind: "project" };
+        }
+        if (subject.relation) {
+            throw httpError(403, "Permission subject-set expansion is not accepted by Agent Security");
+        }
+        const ownerNamespace = process.env.ORY_USER_SUBJECT_NAMESPACE?.trim()
+            || this.config.userSubjectNamespace
+            || "User";
+        if (subject.namespace === ownerNamespace) {
+            if (subject.object === this.userPrincipal.subject) {
+                return { kind: "owner", namespace: subject.namespace };
+            }
+            throw httpError(403, "Permission owner does not match the authenticated user");
+        }
+        const parts = subject.object.split("|");
+        if (parts.some((part) => !part.trim())) {
+            throw httpError(403, "Permission principal contains an invalid subject separator");
+        }
+        if (subject.namespace === "Agent") {
+            if (parts[0] !== this.agentPrincipal.subject) {
+                throw httpError(403, "Permission agent does not match the authenticated agent");
+            }
+            if (parts.length === 1)
+                return { kind: "agent" };
+            if (parts.length === 2)
+                return { kind: "agent_session", session_id: parts[1] };
+        }
+        else if (subject.namespace === "SubAgent") {
+            if (parts.length === 1) {
+                const typeName = this.subAgentTypeForClient(parts[0]);
+                if (typeName)
+                    return { kind: "subagent", type_name: typeName };
+            }
+            if ((parts.length === 3 || parts.length === 4) && this.subAgentTypeForClient(parts[0]) === parts[2]) {
+                return {
+                    kind: "subagent_spawn",
+                    session_id: parts[1],
+                    type_name: parts[2],
+                    ...(parts[3] ? { per_spawn_id: parts[3] } : {}),
+                };
+            }
+        }
+        throw httpError(403, "Permission check principal cannot be represented safely");
+    }
+    subAgentTypeForClient(clientId) {
+        const bySession = (0, config_js_1.loadConfig)().agent?.subAgents?.[this.harness];
+        for (const byType of Object.values(bySession ?? {})) {
+            const match = Object.entries(byType).find(([, credentials]) => credentials.clientId === clientId);
+            if (match)
+                return match[0];
+        }
+        return undefined;
+    }
     /** Snapshot of the current user principal. */
     get userPrincipal() {
-        return { ...this._userPrincipal };
+        return this.userPrincipalForSession(this.sessionId);
+    }
+    /** Snapshot of the user principal bound to one session. */
+    userPrincipalForSession(sessionId) {
+        const session = sessionId?.trim();
+        const principal = session ? this._userPrincipalsBySession.get(session) : undefined;
+        return { ...(principal ?? this._userPrincipal) };
     }
     /** Snapshot of the current agent principal. */
     get agentPrincipal() {
-        return { ...this._agentPrincipal };
+        const runtimeSubject = (0, context_js_1.currentSessionContext)().runtimeCredential?.subject;
+        if (runtimeSubject)
+            return { subject: runtimeSubject };
+        return this.agentPrincipalForSession(this.sessionId);
+    }
+    /** Active noninteractive broker credential. It is process memory only. */
+    get runtimeCredential() {
+        const context = (0, context_js_1.currentSessionContext)();
+        if (context.runtimeCredential)
+            return context.runtimeCredential;
+        if (context.sessionId) {
+            const credential = this._runtimeCredentialsBySession.get(context.sessionId);
+            if (credential)
+                return credential;
+        }
+        if (this._runtimeCredential)
+            return this._runtimeCredential;
+        const principal = this.agentPrincipal;
+        return principal.token
+            ? (0, runtime_credential_js_1.talosRuntimeCredential)(principal.token, { subject: principal.subject })
+            : undefined;
+    }
+    get hasRuntimeCredential() {
+        return this.runtimeCredential !== undefined;
+    }
+    setRuntimeCredential(credential) {
+        const sessionId = this.sessionId?.trim();
+        if (sessionId) {
+            if (credential)
+                this._runtimeCredentialsBySession.set(sessionId, credential);
+            else
+                this._runtimeCredentialsBySession.delete(sessionId);
+        }
+        else {
+            this._runtimeCredential = credential;
+        }
+        if (credential)
+            this.rememberRuntimeCredential(credential);
+        if (credential?.subject)
+            this.setAgentPrincipal({ subject: credential.subject }, sessionId);
+    }
+    /** Retain an actor-scoped credential for deferred event delivery without activating it globally. */
+    rememberRuntimeCredential(credential) {
+        if (credential.subject) {
+            this._runtimeCredentialsByPrincipalKey.set((0, event_reporter_js_1.eventPrincipalKey)(credential.subject), credential);
+        }
+    }
+    /** Run one hook with session/credential state isolated from concurrent hooks. */
+    withRuntimeContext(context, work) {
+        if (context.runtimeCredential)
+            this.rememberRuntimeCredential(context.runtimeCredential);
+        return (0, context_js_1.withSessionContext)(context, work);
+    }
+    /** Snapshot of the agent principal bound to one session. */
+    agentPrincipalForSession(sessionId) {
+        const session = sessionId?.trim();
+        const principal = session ? this._agentPrincipalsBySession.get(session) : undefined;
+        return { ...(principal ?? this._agentPrincipal) };
+    }
+    eventPrincipal(sessionId, principalKey) {
+        if (principalKey) {
+            const principal = this._eventPrincipalsByKey.get(principalKey);
+            if (principal)
+                return { ...principal };
+            const sessionPrincipal = this.agentPrincipalForSession(sessionId);
+            if (sessionPrincipal.subject && (0, event_reporter_js_1.eventPrincipalKey)(sessionPrincipal.subject) === principalKey) {
+                return sessionPrincipal;
+            }
+            return {};
+        }
+        return this.agentPrincipalForSession(sessionId);
+    }
+    /**
+     * The harness this client runs in (`"claude-code"`, `"codex"`, …). Exposed
+     * because persisted agent / sub-agent credentials and delegation anchors are
+     * keyed first by harness and then by session.
+     */
+    get harness() {
+        return this.config.harness;
+    }
+    /**
+     * The harness session currently in scope, or `undefined` outside one.
+     *
+     * Read from standalone ambient session context, which every harness sets from its
+     * own session identifier at the top of a lifecycle invocation — so identity
+     * and delegation code can select the session's credential and node without
+     * each plugin threading the id through its own call chain.
+     */
+    get sessionId() {
+        return (0, context_js_1.currentSessionContext)().sessionId;
+    }
+    /** Best-effort bounded flush for short-lived hook subprocesses and tests. */
+    async flushEvents(timeoutMs = 1_000) {
+        if (!this.eventReporter || timeoutMs <= 0)
+            return;
+        const startedAt = Date.now();
+        const remaining = () => Math.max(0, timeoutMs - (Date.now() - startedAt));
+        // Deliver sessions that already have a bearer before historical credential
+        // recovery can consume the short-lived hook process's entire deadline.
+        await this.eventReporter.flush(remaining());
+        if (remaining() <= 0)
+            return;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), remaining());
+        timer.unref?.();
+        try {
+            for (const scope of this.eventReporter.pendingScopes) {
+                if (controller.signal.aborted)
+                    break;
+                if (this.eventPrincipal(scope.sessionId, scope.principalKey).token)
+                    continue;
+                try {
+                    const { loadAllSubAgentDynamicCredentials, ensureSubAgentIdentity } = await import("./agent-auth.js");
+                    const subAgent = scope.principalKey
+                        ? Object.entries(loadAllSubAgentDynamicCredentials(this.harness, scope.sessionId?.trim())).find(([, credentials]) => (0, event_reporter_js_1.eventPrincipalKey)(credentials.clientId) === scope.principalKey)
+                        : undefined;
+                    if (subAgent) {
+                        const [subAgentType] = subAgent;
+                        const identity = await (0, context_js_1.withSessionContext)({ sessionId: scope.sessionId }, () => ensureSubAgentIdentity(this, {
+                            subAgentType,
+                            harness: this.harness,
+                            sessionId: scope.sessionId,
+                            emitActivity: false,
+                            signal: controller.signal,
+                        }));
+                        if (identity.subject && identity.token) {
+                            this._eventPrincipalsByKey.set((0, event_reporter_js_1.eventPrincipalKey)(identity.subject), {
+                                subject: identity.subject,
+                                token: identity.token,
+                            });
+                        }
+                    }
+                    else {
+                        const { ensureReadCredential } = await import("./read-credential.js");
+                        await (0, context_js_1.withSessionContext)({ sessionId: scope.sessionId }, () => ensureReadCredential(this, {
+                            signal: controller.signal,
+                            allowRegistration: false,
+                        }));
+                    }
+                }
+                catch (error) {
+                    this.logger.debug("events.credential_resolution_failed", {
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        await this.eventReporter.flush(remaining());
     }
     /**
      * Configured user-subject namespace (from config, resolved at construction).
@@ -159,53 +479,44 @@ class OryAgentClient {
     }
     /**
      * Set or update the human user principal. The user is the subject of
-     * permission checks but does not authenticate outgoing API calls.
-     * Pass `{}` (or fields set to undefined) to clear.
-     */
-    setUserPrincipal(principal) {
-        this._userPrincipal = { ...principal };
-    }
-    /** Whether an admin API key is set for the Keto APIs (never exposes it). */
-    get hasAdminApiKey() {
-        return !!this._adminApiKey;
-    }
-    /**
-     * Set or update the admin API key (an Ory Network project API key) used to
-     * authenticate the Keto Permission / Relationship APIs. Rebuilds those API
-     * instances when the key changes; a no-op update leaves them alone so test
-     * stubs survive. See {@link _adminApiKey} for why Keto needs a credential
-     * distinct from the agent's OAuth2 token.
+     * permission checks. Its token does not authenticate agent-attributed calls
+     * (OAuth2 / Frontend / Relationship), but it *is* the fallback credential for
+     * Keto permission reads when no agent token is present (see `buildApis`) — so
+     * a change to the user token rebuilds the API instances, otherwise the
+     * rehydrated user token would never reach the Permission API in a fresh
+     * subprocess. Pass `{}` (or fields set to undefined) to clear.
      */
-    setAdminApiKey(apiKey) {
-        if (this._adminApiKey === apiKey)
-            return;
-        this._adminApiKey = apiKey;
-        const { frontend, oauth2, permission, relationship } = this.buildApis();
-        this.frontend = frontend;
-        this.oauth2 = oauth2;
-        this.permission = permission;
-        this.relationship = relationship;
+    setUserPrincipal(principal, sessionId = this.sessionId) {
+        const session = sessionId?.trim();
+        if (session)
+            this._userPrincipalsBySession.set(session, { ...principal });
+        else
+            this._userPrincipal = { ...principal };
     }
     /**
      * Set or update the AI agent principal. The agent's token (when present)
-     * authenticates outgoing calls to the OAuth2 / Frontend APIs and carries
-     * audit attribution ("agent X acting on behalf of user Y"). Note the Keto
-     * Permission / Relationship APIs authenticate with {@link _adminApiKey}
-     * instead when one is set — Ory Network rejects OAuth2 tokens there.
-     * Rebuilds the underlying Ory API instances when the token actually changes
-     * so subsequent calls pick it up; otherwise leaves the API instances alone
-     * (so test stubs survive a no-op update).
+     * authenticates *every* outgoing Ory call — OAuth2 / Frontend and Keto
+     * (Permission / Relationship) alike — and carries audit attribution ("agent X
+     * acting on behalf of user Y"). Rebuilds the underlying Ory API instances when
+     * the token actually changes so subsequent calls pick it up; otherwise leaves
+     * the API instances alone (so test stubs survive a no-op update).
      */
-    setAgentPrincipal(principal) {
-        const tokenChanged = this._agentPrincipal.token !== principal.token;
-        this._agentPrincipal = { ...principal };
+    setAgentPrincipal(principal, sessionId = this.sessionId) {
+        const tokenChanged = this.agentPrincipalForSession(sessionId).token !== principal.token;
+        const session = sessionId?.trim();
+        if (session)
+            this._agentPrincipalsBySession.set(session, { ...principal });
+        else
+            this._agentPrincipal = { ...principal };
+        if (principal.subject) {
+            this._eventPrincipalsByKey.set((0, event_reporter_js_1.eventPrincipalKey)(principal.subject), { ...principal });
+        }
         if (!tokenChanged)
             return;
-        const { frontend, oauth2, permission, relationship } = this.buildApis();
+        const { frontend, oauth2, permission } = this.buildApis();
         this.frontend = frontend;
         this.oauth2 = oauth2;
         this.permission = permission;
-        this.relationship = relationship;
     }
     // ─── Session (Ory Identities / Kratos) ──────────────────────────
     /**
@@ -221,7 +532,7 @@ class OryAgentClient {
             });
             return cached.info;
         }
-        const span = this.tracer.startSpan("session.verify");
+        const activity = this.logger.startActivity("session.verify");
         try {
             const response = await this.frontend.toSession({
                 xSessionToken: sessionToken,
@@ -254,7 +565,7 @@ class OryAgentClient {
                 active: info.active,
                 aal: info.authenticatorAssuranceLevel,
             });
-            span.end("ok", {
+            activity.end("ok", {
                 sessionId: info.sessionId,
                 identityId: info.identityId,
                 active: info.active,
@@ -269,7 +580,7 @@ class OryAgentClient {
                 status: oryErr.status,
                 message: oryErr.message,
             });
-            span.end("error", {
+            activity.end("error", {
                 error: oryErr.code,
                 ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
             });
@@ -283,7 +594,7 @@ class OryAgentClient {
      */
     async introspectToken(token, scope) {
         this.logger.debug("oauth2.introspect.start", { hasToken: !!token });
-        const span = this.tracer.startSpan("oauth2.introspect");
+        const activity = this.logger.startActivity("oauth2.introspect");
         try {
             const response = await this.oauth2.introspectOAuth2Token({
                 token,
@@ -307,7 +618,7 @@ class OryAgentClient {
                 clientId: info.clientId,
                 subject: info.subject,
             });
-            span.end("ok", {
+            activity.end("ok", {
                 active: info.active,
                 clientId: info.clientId,
                 subject: info.subject,
@@ -322,7 +633,7 @@ class OryAgentClient {
                 status: oryErr.status,
                 message: oryErr.message,
             });
-            span.end("error", {
+            activity.end("error", {
                 error: oryErr.code,
                 ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
             });
@@ -333,19 +644,23 @@ class OryAgentClient {
     /**
      * Check if a subject has permission to perform an action.
      *
-     * `options.spanAttributes` are merged into the `permission.check` trace
-     * span so callers can attach harness-side context (toolName, mcpServer,
+     * `options.activityAttributes` are merged into the `permission.check` activity
+     * event so callers can attach harness-side context (toolName, mcpServer,
      * etc.) that the wire-level `PermissionCheck` shape doesn't carry.
+     *
+     * `options.informational` marks a check whose `false` result is *not* a
+     * denial — e.g. the permission-mode probe, where "enforce not granted" simply
+     * selects `observe`. Such an event ends `ok` (the read succeeded) rather than
+     * `denied`, so a reader watching activity doesn't mistake a routine mode read
+     * for a blocked tool. The boolean is still recorded as the `allowed`
+     * attribute either way.
      */
     async checkPermission(check, options) {
         this.logger.debug("permission.check.start", { ...check });
-        const span = this.tracer.startSpan("permission.check", {
-            attributes: {
-                object: check.object,
-                relation: check.relation,
-                ...this.principalSpanAttributes(),
-                ...options?.spanAttributes,
-            },
+        const activity = this.logger.startActivity("permission.check", {
+            object: check.object,
+            relation: check.relation,
+            ...options?.activityAttributes,
         });
         try {
             const response = await this.permission.checkPermission({
@@ -372,7 +687,7 @@ class OryAgentClient {
                 subjectId: check.subjectId,
                 subjectSet: check.subjectSet,
             });
-            span.end(result.allowed ? "ok" : "denied", {
+            activity.end(options?.informational || result.allowed ? "ok" : "denied", {
                 allowed: result.allowed,
                 ...(oryRequestId ? { oryRequestId } : {}),
             });
@@ -380,14 +695,13 @@ class OryAgentClient {
         }
         catch (err) {
             const oryErr = this.classifyError(err);
-            this.warnIfKetoCredentialMismatch(oryErr);
             this.logger.error("permission.check.failed", {
                 code: oryErr.code,
                 status: oryErr.status,
                 message: oryErr.message,
                 ...check,
             });
-            span.end("error", {
+            activity.end("error", {
                 error: oryErr.code,
                 ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
             });
@@ -397,19 +711,16 @@ class OryAgentClient {
     /**
      * Check multiple permissions in a single request.
      *
-     * `options.spanAttributes` are merged into the `permission.batch_check`
-     * span — same purpose as `checkPermission`'s spanAttributes.
+     * `options.activityAttributes` are merged into the `permission.batch_check`
+     * activity event, for the same purpose as `checkPermission`'s attributes.
      */
     async batchCheckPermissions(checks, options) {
         this.logger.debug("permission.batch_check.start", {
             count: checks.length,
         });
-        const span = this.tracer.startSpan("permission.batch_check", {
-            attributes: {
-                count: checks.length,
-                ...this.principalSpanAttributes(),
-                ...options?.spanAttributes,
-            },
+        const activity = this.logger.startActivity("permission.batch_check", {
+            count: checks.length,
+            ...options?.activityAttributes,
         });
         try {
             const response = await this.permission.batchCheckPermission({
@@ -446,7 +757,7 @@ class OryAgentClient {
                 allowed,
                 denied,
             });
-            span.end("ok", {
+            activity.end("ok", {
                 allowed,
                 denied,
                 ...(oryRequestId ? { oryRequestId } : {}),
@@ -455,261 +766,177 @@ class OryAgentClient {
         }
         catch (err) {
             const oryErr = this.classifyError(err);
-            this.warnIfKetoCredentialMismatch(oryErr);
             this.logger.error("permission.batch_check.failed", {
                 code: oryErr.code,
                 status: oryErr.status,
                 message: oryErr.message,
             });
-            span.end("error", {
+            activity.end("error", {
                 error: oryErr.code,
                 ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
             });
             throw oryErr;
         }
     }
-    // ─── Relationships (Ory Permissions / Keto write API) ────────────
+    // ─── Delegation (agent-security broker) ──────────────────────────
     /**
-     * Create a relation tuple in Keto. Idempotent: a 409 (tuple already
-     * exists) is swallowed and reported as success. All other errors are
-     * classified and re-thrown — callers wrap in fail-open semantics if
-     * the tuple is non-critical (e.g. audit-only delegation tracking).
+     * Record a delegation edge through the Ory Agent Security broker
+     * (`POST <agentSecurityUrl>/agent-security/v1/delegations:record`), authenticated
+     * with the process runtime credential. The broker constructs and writes the Keto tuple — the plugin
+     * sends only the semantic inputs, so the join-key/tuple encoding stays
+     * server-side and cannot drift here. Returns the node id + chain the broker
+     * assigned. Throws a classified {@link OryError} on any non-2xx; callers wrap
+     * in fail-open semantics (delegation is audit-only).
      *
-     * `options.spanAttributes` are merged into the `relationship.create`
-     * trace span so callers can attach context like `delegation: "user→agent"`.
+     * The broker exists only on hosted Ory; against the local dev stack the call
+     * returns 404 and callers treat it as a best-effort no-op.
      */
-    async createRelationship(check, options) {
-        this.logger.debug("relationship.create.start", { ...check });
-        const span = this.tracer.startSpan("relationship.create", {
-            attributes: {
-                namespace: check.namespace,
-                object: check.object,
-                relation: check.relation,
-                ...this.principalSpanAttributes(),
-                ...options?.spanAttributes,
+    async recordDelegation(input, options) {
+        const kind = input.kind === "agent" ? "PRINCIPAL_KIND_AGENT" : "PRINCIPAL_KIND_SUBAGENT";
+        const sessionId = input.sessionId ?? this.sessionId;
+        // `session_id` and `per_spawn_id` belong on `principal` — that is where the
+        // broker's proto declares them. They were previously sent at the top level
+        // of the body, where `RecordDelegationBody` has no such fields; the
+        // gateway's protojson runs with `DiscardUnknown: true`, so every value was
+        // silently dropped and the server never saw a session at all.
+        const body = {
+            project_url: this.config.projectUrl,
+            ...(input.identityId ? { identity_id: input.identityId } : {}),
+            harness: this.config.harness,
+            principal: {
+                kind,
+                ...(input.host ? { host: input.host } : {}),
+                ...(input.subAgentType ? { type_name: input.subAgentType } : {}),
+                ...(sessionId ? { session_id: sessionId } : {}),
+                ...(input.perSpawnId ? { per_spawn_id: input.perSpawnId } : {}),
             },
-        });
+            ...(input.delegatedBy ? { delegated_by: input.delegatedBy } : {}),
+        };
+        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.
+        const userToken = this.userPrincipalForSession(sessionId).token;
+        const runtimeCredential = options?.runtimeCredential ?? (options?.agentToken
+            ? (0, runtime_credential_js_1.talosRuntimeCredential)(options.agentToken)
+            : this.runtimeCredential);
         try {
-            const response = await this.relationship.createRelationship({
-                createRelationshipBody: {
-                    namespace: check.namespace,
-                    object: check.object,
-                    relation: check.relation,
-                    subject_id: check.subjectId,
-                    ...(check.subjectSet
-                        ? {
-                            subject_set: {
-                                namespace: check.subjectSet.namespace,
-                                object: check.subjectSet.object,
-                                relation: check.subjectSet.relation,
-                            },
-                        }
-                        : {}),
+            if (!userToken || !runtimeCredential) {
+                throw httpError(403, "User token and runtime credential are required");
+            }
+            const res = await (0, runtime_credential_js_1.authenticatedRuntimeRequest)(runtimeCredential, {
+                url,
+                init: {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${userToken}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: options?.signal ?? AbortSignal.timeout(30_000),
                 },
+                authorizationHeader: "x-ory-agent-authorization",
+                fetch: options?.fetchImpl,
             });
-            const oryRequestId = extractOryRequestId(response.headers);
-            this.logger.info("relationship.create.result", {
-                namespace: check.namespace,
-                object: check.object,
-                relation: check.relation,
-                subjectId: check.subjectId,
-            });
-            span.end("ok", {
-                created: true,
-                ...(oryRequestId ? { oryRequestId } : {}),
-            });
-            return { created: true, alreadyExisted: false };
-        }
-        catch (err) {
-            const oryErr = this.classifyError(err);
-            // Keto returns 409 when the tuple already exists; treat as success
-            // so callers can call this on every session start without dedup.
-            if (oryErr.status === 409) {
-                this.logger.debug("relationship.create.exists", {
-                    namespace: check.namespace,
-                    object: check.object,
-                    relation: check.relation,
-                });
-                span.end("ok", {
-                    created: false,
-                    alreadyExisted: true,
-                    ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
-                });
-                return { created: false, alreadyExisted: true };
+            if (!res.ok) {
+                const err = new Error(`HTTP ${res.status}`);
+                err.status = res.status;
+                throw err;
             }
-            this.warnIfKetoCredentialMismatch(oryErr);
-            this.logger.error("relationship.create.failed", {
-                code: oryErr.code,
-                status: oryErr.status,
-                message: oryErr.message,
-                ...check,
-            });
-            span.end("error", {
-                error: oryErr.code,
-                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
-            });
-            throw oryErr;
-        }
-    }
-    /**
-     * True if the *exact* relation tuple already exists in Keto. Queries the
-     * relation-tuple listing API filtered by the tuple's own coordinates
-     * (namespace/object/relation + subject), so — unlike `checkPermission` —
-     * it does not follow subject-set expansion: it answers "is this literal
-     * tuple stored?", not "does this permission resolve?". Throws a classified
-     * {@link OryError} if the query itself fails.
-     */
-    async relationshipExists(check) {
-        try {
-            const response = await this.relationship.getRelationships({
-                namespace: check.namespace,
-                object: check.object,
-                relation: check.relation,
-                ...(check.subjectId ? { subjectId: check.subjectId } : {}),
-                ...(check.subjectSet
-                    ? {
-                        subjectSetNamespace: check.subjectSet.namespace,
-                        subjectSetObject: check.subjectSet.object,
-                        subjectSetRelation: check.subjectSet.relation,
-                    }
-                    : {}),
-                pageSize: 1,
-            });
-            const tuples = response.data?.relation_tuples ?? [];
-            return tuples.length > 0;
-        }
-        catch (err) {
-            throw this.classifyError(err);
-        }
-    }
-    /**
-     * Idempotent relationship write. Keto's create API is **not** idempotent —
-     * `PUT /admin/relation-tuples` inserts a fresh row on every call (each with
-     * a new primary key) and never returns 409, so calling `createRelationship`
-     * on repeated bootstraps / session starts accumulates duplicate tuples.
-     * This reads the exact tuple first (via {@link relationshipExists}) and only
-     * writes when it is absent — which also self-heals if the tuple was deleted
-     * out of band.
-     *
-     * If the existence probe itself fails, the tuple is left untouched (we do
-     * not write blind, to avoid re-introducing duplicates when the read path is
-     * misbehaving) and the classified error is returned as `probeError`. Callers
-     * that must guarantee the grant exists (e.g. install-time bootstrap) can
-     * fall back to {@link createRelationship} when `probeError` is set.
-     */
-    async ensureRelationship(check, options) {
-        let exists;
-        try {
-            exists = await this.relationshipExists(check);
-        }
-        catch (err) {
-            return { created: false, alreadyExisted: false, probeError: err };
-        }
-        if (exists)
-            return { created: false, alreadyExisted: true };
-        return this.createRelationship(check, options);
-    }
-    /**
-     * Delete a relation tuple in Keto. Missing tuples (404) are treated as
-     * success so callers can call this idempotently when unwinding state.
-     */
-    async deleteRelationship(check, options) {
-        this.logger.debug("relationship.delete.start", { ...check });
-        const span = this.tracer.startSpan("relationship.delete", {
-            attributes: {
-                namespace: check.namespace,
-                object: check.object,
-                relation: check.relation,
-                ...this.principalSpanAttributes(),
-                ...options?.spanAttributes,
-            },
-        });
-        try {
-            const response = await this.relationship.deleteRelationships({
-                namespace: check.namespace,
-                object: check.object,
-                relation: check.relation,
-                subjectId: check.subjectId,
-                ...(check.subjectSet
-                    ? {
-                        subjectSetNamespace: check.subjectSet.namespace,
-                        subjectSetObject: check.subjectSet.object,
-                        subjectSetRelation: check.subjectSet.relation,
-                    }
-                    : {}),
-            });
-            const oryRequestId = extractOryRequestId(response.headers);
-            span.end("ok", {
-                deleted: true,
-                ...(oryRequestId ? { oryRequestId } : {}),
-            });
-            return { deleted: true, notFound: false };
+            const json = (await res.json());
+            // Accept both spellings. The broker's OpenAPI document carries the proto
+            // field names (`node_id`), but grpc-gateway's default marshaler emits
+            // lowerCamelCase — reading only one silently yields "" on the other,
+            // which reads as "no node" and stops every sub-agent edge from being
+            // recorded. Tolerating both also lets the two repos deploy in any order.
+            const raw = json.node_id ?? json.nodeId;
+            const nodeId = typeof raw === "string" ? raw : "";
+            const chain = json.delegation_chain ?? json.delegationChain;
+            const delegationChain = Array.isArray(chain)
+                ? chain.filter((c) => typeof c === "string")
+                : [];
+            activity.end("ok", { nodeId });
+            this.logger.debug("delegation.record.result", { kind: input.kind, nodeId });
+            return { nodeId, delegationChain };
         }
         catch (err) {
             const oryErr = this.classifyError(err);
-            if (oryErr.code === "not_found") {
-                span.end("ok", {
-                    deleted: false,
-                    notFound: true,
-                    ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
-                });
-                return { deleted: false, notFound: true };
-            }
-            this.warnIfKetoCredentialMismatch(oryErr);
-            this.logger.error("relationship.delete.failed", {
+            activity.end("error", { error: oryErr.code });
+            this.logger.debug("delegation.record.failed", {
+                kind: input.kind,
                 code: oryErr.code,
                 status: oryErr.status,
                 message: oryErr.message,
-                ...check,
-            });
-            span.end("error", {
-                error: oryErr.code,
-                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
             });
             throw oryErr;
         }
     }
     /**
-     * Span attributes describing which principals were attached to the
-     * client when the span was started. Useful for correlating audit logs
+     * Activity attributes describing which principals are attached to the
+     * client. Useful for correlating audit logs
      * across the user/agent split.
      */
-    principalSpanAttributes() {
+    principalActivityAttributes() {
         const out = {};
-        if (this._userPrincipal.subject)
-            out.userSubject = this._userPrincipal.subject;
-        if (this._agentPrincipal.subject)
-            out.agentSubject = this._agentPrincipal.subject;
+        const user = this.userPrincipal;
+        const agent = this.agentPrincipal;
+        if (user.subject)
+            out.userSubject = user.subject;
+        if (agent.subject)
+            out.agentSubject = agent.subject;
         return out;
     }
-    /**
-     * When a Keto call is auth-rejected while it was authenticated by something
-     * other than an Ory Network project API key (`ory_pat_…`) — e.g. a DCR
-     * OAuth2 access token — the credential *type* is wrong, not merely expired.
-     * Ory Network's Permission / Relationship APIs only accept a project API
-     * key. Emit an actionable hint so the failure isn't misread as a stale
-     * session (the generic `session_inactive` classification of the raw 401).
-     */
-    warnIfKetoCredentialMismatch(oryErr) {
-        if (oryErr.code !== "session_inactive" && oryErr.code !== "forbidden")
-            return;
-        const ketoToken = this._adminApiKey ?? this._agentPrincipal.token;
-        // A real project API key is already in use — treat as a genuine auth error.
-        if (typeof ketoToken === "string" && ketoToken.startsWith("ory_pat_"))
-            return;
-        this.logger.warn("permission.credential_mismatch", {
-            code: oryErr.code,
-            message: "Ory Network's Permission/Relationship APIs require a project API key " +
-                "(ory_pat_…); the agent's OAuth2 access token is not accepted. Create a " +
-                "key in the Ory Console (Project settings → API keys) and set it with " +
-                "`configure --api-key <key>` or the ORY_AGENT_API_KEY env var.",
-        });
-    }
     // ─── Error Classification ────────────────────────────────────────
     /**
      * Classify an error from any Ory API call into a structured OryError.
      */
     classifyError(err) {
+        // ── Transport failures, before anything status-shaped ──────────────
+        //
+        // Ordering matters and was the whole bug in #218. An axios error carries
+        // `isAxiosError` whether or not a response arrived, so the status table below
+        // claimed *every* transport failure and — with `status === undefined` — fell
+        // through to `unknown`, which fails **open** in both modes. That silently
+        // downgraded an `enforce` project to `observe` on any certificate problem, and
+        // made breaking TLS sufficient to disable all tool gating.
+        //
+        // It also made the socket-code list further down dead code for every
+        // axios-based call: a plain `ECONNREFUSED` classified as `unknown` too, so
+        // `network_error` was effectively unreachable from a permission check.
+        //
+        // A response-less error is by definition a transport failure, so it is
+        // classified here, by cause, and never by HTTP status.
+        const tlsCode = findTlsErrorCode(err);
+        if (tlsCode) {
+            return {
+                code: "tls_error",
+                message: `TLS/certificate verification failed: ${tlsCode} — ${err.message}. ` +
+                    "The permission check could not be completed against a verified host. " +
+                    "For a local stack with a private CA, set NODE_EXTRA_CA_CERTS to its root certificate.",
+                cause: err,
+            };
+        }
+        const socketCode = findSocketErrorCode(err);
+        if (socketCode) {
+            return {
+                code: "network_error",
+                message: `Network error: ${socketCode} — ${err.message}`,
+                cause: err,
+            };
+        }
+        // A plain Error carrying a top-level numeric `status`. The `fetch`-based
+        // calls (the agent-security broker) raise this shape rather than an axios
+        // error, and without this branch every one of them classified as `unknown`
+        // with no status at all — so a broker 403 was indistinguishable in the audit
+        // trail from a parse failure. Normalized into the axios shape so there is
+        // exactly one status→code table below.
+        if (!this.isAxiosError(err) && typeof err?.status === "number") {
+            return this.classifyError({
+                isAxiosError: true,
+                message: err.message,
+                response: { status: err.status },
+            });
+        }
         // Axios errors have a `response` property with status + data
         if (this.isAxiosError(err)) {
             const status = err.response?.status;
@@ -782,29 +1009,29 @@ class OryAgentClient {
      * Create a client from environment variables, falling back to the
      * shared config file at ~/.config/ory-agent-plugins/config.json.
      *
-     * Resolution order for projectUrl and apiKey:
-     *   1. Environment variables (ORY_PROJECT_URL, ORY_API_KEY)
+     * Resolution order for projectUrl:
+     *   1. Environment variables (ORY_PROJECT_URL / ORY_SDK_URL)
      *   2. Config file (~/.config/ory-agent-plugins/config.json)
      *   3. Placeholder (fail-open pass-through mode)
      */
-    static fromEnv(harness) {
+    static fromEnv(harness, runtime = {}) {
         const resolved = (0, config_js_1.resolveConfig)();
         const projectUrl = resolved.projectUrl;
         const logFile = resolveDebugLogPath(harness);
-        const traceFile = resolveTraceFilePath(harness);
         if (!projectUrl) {
             // Use a placeholder URL so the client can be constructed.
             // API calls will fail with network_error which is handled as fail-open.
             const client = new OryAgentClient({
                 projectUrl: "http://localhost:0",
-                apiKey: resolved.apiKey,
+                agentSecurityUrl: resolved.agentSecurityUrl ?? "http://localhost:0",
                 harness,
                 logFile,
-                traceFile,
                 userSubjectNamespace: resolved.userSubjectNamespace,
                 sessionCacheTtlMs: process.env.ORY_SESSION_CACHE_TTL_MS
                     ? parseInt(process.env.ORY_SESSION_CACHE_TTL_MS, 10)
                     : undefined,
+                eventReporter: undefined,
+                ...runtime,
             });
             client.logger.warn("config.missing_project_url", {
                 message: "ORY_PROJECT_URL is not set and no config file found. " +
@@ -812,26 +1039,29 @@ class OryAgentClient {
                     "Set ORY_PROJECT_URL or run the plugin's configure command.",
             });
             rehydrateUserPrincipal(client);
-            attachOtlpExporterFromEnv(client, harness);
             return client;
         }
         const client = new OryAgentClient({
             projectUrl,
-            apiKey: resolved.apiKey,
+            agentSecurityUrl: resolved.agentSecurityUrl,
             harness,
             logFile,
-            traceFile,
             userSubjectNamespace: resolved.userSubjectNamespace,
             sessionCacheTtlMs: process.env.ORY_SESSION_CACHE_TTL_MS
                 ? parseInt(process.env.ORY_SESSION_CACHE_TTL_MS, 10)
                 : undefined,
+            eventReporter: resolved.security.connected
+                ? {
+                    outboxDir: path.join((0, config_js_1.getHarnessDataDir)(harness), "events-outbox", (0, event_reporter_js_1.eventOutboxProjectScope)(projectUrl)),
+                }
+                : undefined,
+            ...runtime,
         });
         client.logger.debug("config.resolved", {
             projectUrlSource: resolved.projectUrlSource,
-            apiKeySource: resolved.apiKeySource,
+            agentSecurityUrlSource: resolved.agentSecurityUrlSource,
         });
         rehydrateUserPrincipal(client);
-        attachOtlpExporterFromEnv(client, harness);
         return client;
     }
 }
@@ -855,13 +1085,39 @@ exports.OryAgentClient = OryAgentClient;
  * with fresh values when it runs at `SessionStart`.
  *
  * The subject is attached whenever it is known — even for an expired token,
- * since the subject is what permission checks resolve against and Keto
- * checks authenticate with the admin API key, not this token. The access
- * token itself is only carried forward while still valid, so nothing
- * authenticates with a stale bearer.
+ * since the subject is what permission checks resolve against. The access
+  * token itself is only carried forward while still valid, so delegation
+  * authentication never uses a stale bearer. Permission reads independently
+  * resolve the required agent credential.
+ *
+ * Two sources feed it, in the same order the login gate uses: a credential
+ * supplied through the environment (`ORY_USER_OAUTH2_TOKEN`) first, then the
+ * persisted tokens. The env branch exists because the gate's `env_token` short-circuit
+ * attaches that credential *in memory only* and runs only at `SessionStart`;
+ * reading it here is what makes a pre-supplied token apply on every lifecycle
+ * event rather than just the first one.
  */
 function rehydrateUserPrincipal(client) {
+    // An env-supplied credential wins, matching the login gate's own ordering
+    // (its `env_token` short-circuit is checked before persisted tokens). That
+    // gate only runs on `SessionStart`, and it attaches the credential in memory
+    // 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.
+    const env = (0, auth_store_js_1.readEnvUserCredential)();
     const tokens = (0, auth_store_js_1.loadTokens)();
+    if (env.token) {
+        client.setUserPrincipal({
+            // The operator-pinned subject wins; fall back to the persisted one so an
+            // env token supplied alongside a completed login keeps its identity.
+            ...(env.subject ?? tokens?.subject
+                ? { subject: env.subject ?? tokens?.subject }
+                : {}),
+            token: env.token,
+        });
+        return;
+    }
     if (!tokens?.subject)
         return;
     client.setUserPrincipal({
@@ -869,17 +1125,15 @@ function rehydrateUserPrincipal(client) {
         token: (0, auth_store_js_1.isExpired)(tokens) ? undefined : tokens.accessToken,
     });
 }
-/** Default debug-log path under the shared per-harness data dir. */
+/** Default unified activity/debug log path under the shared per-harness data dir. */
 exports.DEFAULT_DEBUG_LOG_FILENAME = "ory-agent-debug.log";
-/** Default trace (NDJSON) path under the shared per-harness data dir. */
-exports.DEFAULT_TRACE_FILENAME = "ory-agent-trace.ndjson";
 /**
  * Resolve a file path from an env var with a sensible default under the
  * per-harness data dir. Semantics:
  *   - unset          → the default path (so post-install runs are observable
  *                      without hand-setting env vars),
  *   - set to a path  → that path (operator / dev-launcher override),
- *   - set but empty  → `undefined` (explicit opt-out, e.g. `ORY_AGENT_TRACE_FILE=`).
+ *   - set but empty  → `undefined` (explicit opt-out, e.g. `ORY_AGENT_LOG_FILE=`).
  */
 function resolveFilePath(envValue, defaultPath) {
     if (envValue === undefined)
@@ -888,40 +1142,12 @@ function resolveFilePath(envValue, defaultPath) {
     return trimmed.length > 0 ? trimmed : undefined;
 }
 /**
- * Debug log path. Only written when `ORY_AGENT_DEBUG=true` (the logger gates
- * on that); defaulting the path just means an enabled debug session lands in a
- * file automatically — important for subprocess-hook harnesses whose stderr
- * the harness may swallow.
+ * Unified activity/debug log path. Activity is always appended; verbose
+ * debug/info/warn/error entries are appended only when `ORY_AGENT_DEBUG=true`.
  */
 function resolveDebugLogPath(harness) {
     return resolveFilePath(process.env.ORY_AGENT_LOG_FILE, path.join((0, config_js_1.getHarnessDataDir)(harness), exports.DEFAULT_DEBUG_LOG_FILENAME));
 }
-/** Trace (NDJSON) path. Written on every recorded span when set. */
-function resolveTraceFilePath(harness) {
-    return resolveFilePath(process.env.ORY_AGENT_TRACE_FILE, path.join((0, config_js_1.getHarnessDataDir)(harness), exports.DEFAULT_TRACE_FILENAME));
-}
-function attachOtlpExporterFromEnv(client, harness) {
-    const meta = client.tracer.processMetadata;
-    const exporter = (0, otlp_js_1.otlpExporterFromEnv)({
-        harness,
-        hostname: meta.hostname,
-        user: meta.user,
-        pluginVersion: meta.pluginVersion,
-        cwd: meta.cwd,
-        gitBranch: meta.gitBranch,
-        gitCommit: meta.gitCommit,
-        onError: (err) => client.logger.warn("otel.export.failed", {
-            message: err instanceof Error ? err.message : String(err),
-        }),
-    });
-    if (!exporter)
-        return;
-    client.tracer.setExporter(exporter);
-    client.logger.info("otel.export.enabled", {
-        endpoint: exporter.endpoint,
-        serviceName: exporter.resource.attributes["service.name"],
-    });
-}
 /**
  * Pull the Ory backend request ID from a response headers bag (axios returns
  * lowercase header names). Returns undefined when not present.
@@ -940,3 +1166,58 @@ function extractOryRequestId(headers) {
         return value[0];
     return undefined;
 }
+/**
+ * The TLS/certificate error code on `err`, walking `cause` because HTTP clients
+ * wrap the underlying socket error.
+ *
+ * Matched by *shape*, not an exhaustive list. OpenSSL codes are SCREAMING_SNAKE
+ * and name the artifact that failed (`CERT_HAS_EXPIRED`,
+ * `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `SELF_SIGNED_CERT_IN_CHAIN`,
+ * `DEPTH_ZERO_SELF_SIGNED_CERT`, …), and Node adds `ERR_TLS_*`. A missed code
+ * would fall through to `unknown`, which fails **open** — the bug this exists to
+ * prevent — so the predicate is deliberately broad. `ERR_TLS_CERT_ALTNAME_INVALID`
+ * (hostname mismatch) is included: it is a verification failure, not a transport
+ * one.
+ */
+function findTlsErrorCode(err, depth = 0) {
+    if (!err || typeof err !== "object" || depth > 4)
+        return undefined;
+    const code = err.code;
+    if (typeof code === "string") {
+        const isOpenSslCertCode = /^[A-Z0-9_]+$/.test(code) && /(CERT|SSL|_TLS|SIGNATURE)/.test(code);
+        const isNodeTlsCode = code.startsWith("ERR_TLS_") || code === "ERR_SSL_PROTOCOL_ERROR";
+        // `ERR_TLS_*` and OpenSSL cert codes only; plain socket codes (ECONNRESET…)
+        // deliberately do not match — those are transport failures and fail open.
+        if (isNodeTlsCode || (isOpenSslCertCode && !code.startsWith("E")))
+            return code;
+        if (isOpenSslCertCode && /(CERT|SIGNATURE)/.test(code))
+            return code;
+    }
+    return (findTlsErrorCode(err.cause, depth + 1) ??
+        findTlsErrorCode(err.response?.cause, depth + 1));
+}
+/** Socket-level codes meaning the request never reached a server. */
+const SOCKET_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "ECONNABORTED",
+]);
+/**
+ * The socket-level error code on `err`, walking `cause` the same way
+ * {@link findTlsErrorCode} does — an HTTP client wraps the underlying socket
+ * error, so the code is rarely on the outermost object.
+ */
+function findSocketErrorCode(err, depth = 0) {
+    if (!err || typeof err !== "object" || depth > 4)
+        return undefined;
+    const code = err.code;
+    if (typeof code === "string" && SOCKET_ERROR_CODES.has(code))
+        return code;
+    return findSocketErrorCode(err.cause, depth + 1);
+}