@ory/argus 0.13.9 → 1.0.0

package/dist/status-data.js

@@ -0,0 +1,333 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probePermissionsCoverage = probePermissionsCoverage;
+exports.resolveDynamicName = resolveDynamicName;
+exports.collectStatusReport = collectStatusReport;
+/**
+ * Structured status data — the data-gathering half of the `status` command,
+ * shared by the text renderer ({@link file://./status-cli.ts}) and the local
+ * web dashboard. `collectStatusReport(harness)` returns a plain, serializable
+ * object mirroring every section `status` prints (configuration, user identity,
+ * agent identity, permissions coverage, recent activity), so the two surfaces
+ * never drift.
+ *
+ * The live permission-coverage probe ({@link probePermissionsCoverage}) lives
+ * here too and is imported back by `status-cli.ts`, so there is a single probe
+ * implementation.
+ */
+const config_js_1 = require("./config.js");
+const permission_mode_js_1 = require("./permission-mode.js");
+const permissions_js_1 = require("./permissions.js");
+const auth_store_js_1 = require("./auth-store.js");
+const agent_auth_js_1 = require("./agent-auth.js");
+const subject_js_1 = require("./subject.js");
+const client_js_1 = require("./client.js");
+const subject_js_2 = require("./subject.js");
+const branding_js_1 = require("./branding.js");
+const auth_js_1 = require("./auth.js");
+const node_os_1 = require("node:os");
+const tool_catalog_js_1 = require("./tool-catalog.js");
+const opl_js_1 = require("./opl.js");
+const fs = __importStar(require("node:fs"));
+// Additive dashboard section: core Ory service health (see status-system.ts).
+const status_system_js_1 = require("./status-system.js");
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTool";
+}
+/**
+ * Probe the harness's built-in tool catalog against Ory, returning how many
+ * tools the resolved user subject is allowed / denied / errored on, plus the
+ * live permission mode and the subject that was checked. Returns undefined when
+ * a probe can't run (no project URL, empty catalog, no user identity). Never
+ * throws.
+ *
+ * Checks route through {@link resolveCheckRelation}, i.e. the `access` permit —
+ * the same relation the runtime gate evaluates — so a tool carrying an explicit
+ * block is reported as denied here too, exactly as a tool call would be.
+ */
+async function probePermissionsCoverage(harness) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    if (!resolved.projectUrl)
+        return undefined;
+    const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    if (catalog.length === 0)
+        return undefined;
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    const subjectOverride = process.env.ORY_USER_SUBJECT_ID;
+    if (!subjectOverride && (!tokens || (0, auth_store_js_1.isExpired)(tokens))) {
+        return undefined;
+    }
+    const client = client_js_1.OryAgentClient.fromEnv(harness);
+    if (tokens && !(0, auth_store_js_1.isExpired)(tokens)) {
+        client.setUserPrincipal({ subject: tokens.subject, token: tokens.accessToken });
+    }
+    await (0, agent_auth_js_1.ensureAgentIdentity)(client, { projectUrl: resolved.projectUrl }).catch(() => {
+        /* best-effort; the probe still runs with whatever credentials we have */
+    });
+    const subject = (0, subject_js_2.resolveUserSubject)(client);
+    const subjectId = (0, subject_js_2.subjectLabel)(subject);
+    if (subjectId === "agent:unknown")
+        return undefined;
+    const agentSubject = (0, subject_js_2.resolveAgentSubject)(client);
+    const live = await (0, permission_mode_js_1.resolvePermissionMode)(client, subject, {
+        additionalSubjects: agentSubject ? [{ scope: "agent", subject: agentSubject }] : [],
+    });
+    const namespace = resolveNamespace();
+    const relation = (0, permissions_js_1.resolveCheckRelation)("users");
+    const result = {
+        total: catalog.length,
+        allowed: 0,
+        denied: 0,
+        errored: 0,
+        mode: live.mode,
+        modeSource: live.source,
+        subject: subjectId,
+    };
+    for (const tool of catalog) {
+        const check = { namespace, object: tool, relation, ...subject };
+        try {
+            const probe = await client.checkPermission(check, {
+                activityAttributes: { toolName: tool, source: "status_coverage" },
+            });
+            if (probe.allowed)
+                result.allowed++;
+            else
+                result.denied++;
+        }
+        catch (err) {
+            const ory = err;
+            result.errored++;
+            result.errorCode = result.errorCode ?? ory.code ?? "unknown";
+        }
+    }
+    return result;
+}
+function collectConfig(harness) {
+    const r = (0, config_js_1.resolveConfig)();
+    const configPath = (0, config_js_1.getConfigPath)();
+    return {
+        configPath,
+        configExists: fs.existsSync(configPath),
+        projectUrl: r.projectUrl,
+        projectUrlSource: r.projectUrlSource,
+        projectId: r.projectId,
+        projectIdSource: r.projectIdSource,
+        projectName: r.projectName,
+        workspaceName: r.workspaceName,
+        oauth2ClientId: r.oauth2ClientId,
+        oauth2ClientIdSource: r.oauth2ClientIdSource,
+        oauth2ClientName: (0, branding_js_1.isUserLoginClient)({ clientId: r.oauth2ClientId })
+            ? branding_js_1.USER_LOGIN_CLIENT_NAME
+            : undefined,
+        security: r.security,
+        permissionMode: r.permissionMode,
+        permissionModeSource: r.permissionModeSource,
+        userSubjectNamespace: r.userSubjectNamespace,
+        userSubjectNamespaceSource: r.userSubjectNamespaceSource,
+        namespace: resolveNamespace(),
+        principalNamespaces: [...opl_js_1.PRINCIPAL_NAMESPACES],
+        debugEnabled: process.env.ORY_AGENT_DEBUG === "true",
+    };
+}
+function collectUser() {
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    if (!tokens) {
+        return { tokenCache: "empty" };
+    }
+    const nowSec = Math.floor(Date.now() / 1000);
+    return {
+        tokenCache: (0, auth_store_js_1.isExpired)(tokens) ? "stale" : "present",
+        subject: tokens.subject,
+        displayName: tokens.displayName ?? (0, auth_js_1.displayNameFromIdToken)(tokens.idToken),
+        expiresInSeconds: tokens.expiresAt - nowSec,
+        clientId: tokens.clientId,
+    };
+}
+/**
+ * Human-readable name for a DCR agent / sub-agent credential: the persisted
+ * `client_name` when present, else a best-effort reconstruction from the
+ * harness and (for sub-agents) type. Reconstruction uses the current hostname,
+ * which may differ from the registration host for credentials saved before the
+ * name was persisted — acceptable for a display-only label.
+ */
+function resolveDynamicName(creds, subAgentType, harness) {
+    return (creds.clientName ??
+        (0, branding_js_1.agentClientName)({
+            harness: creds.harness ?? harness,
+            host: (0, node_os_1.hostname)() || "unknown-host",
+            subAgentType,
+        }));
+}
+function collectAgent(harness, sessionKey) {
+    if (process.env.ORY_AGENT_CLIENT_ID && process.env.ORY_AGENT_CLIENT_SECRET) {
+        return {
+            source: "static_client_credentials",
+            clientId: process.env.ORY_AGENT_CLIENT_ID,
+            subject: (0, subject_js_2.readAgentSubjectOverride)() ?? process.env.ORY_AGENT_CLIENT_ID,
+        };
+    }
+    const selected = sessionKey
+        ? (() => {
+            const credentials = (0, agent_auth_js_1.loadAgentDynamicCredentials)(harness, sessionKey);
+            return credentials ? { sessionKey, credentials } : undefined;
+        })()
+        : (0, agent_auth_js_1.latestAgentRegistration)(harness);
+    if (!selected)
+        return { source: "unregistered" };
+    const { sessionKey: credentialSession, credentials: persisted } = selected;
+    const resolved = (0, config_js_1.resolveConfig)();
+    const mismatch = resolved.projectUrl && persisted.projectUrl !== resolved.projectUrl
+        ? { registeredAgainst: persisted.projectUrl, current: resolved.projectUrl }
+        : undefined;
+    const subject = (0, subject_js_2.readAgentSubjectOverride)() ?? persisted.clientId;
+    return {
+        source: "dcr",
+        name: resolveDynamicName(persisted, undefined, harness),
+        sessionKey: credentialSession,
+        ...(credentialSession === config_js_1.SESSIONLESS_KEY
+            ? {}
+            : { sessionSubject: `${subject_js_1.AGENT_NAMESPACE}:${subject}|${credentialSession}` }),
+        clientId: persisted.clientId,
+        subject,
+        registeredAt: new Date(persisted.registeredAt * 1000).toISOString(),
+        projectUrlMismatch: mismatch,
+    };
+}
+function collectSubAgents(harness, requestedSession) {
+    const sessionKey = requestedSession
+        ?? (0, agent_auth_js_1.latestAgentRegistration)(harness)?.sessionKey
+        ?? (0, agent_auth_js_1.latestSubAgentSession)(harness);
+    const persisted = sessionKey ? (0, agent_auth_js_1.loadAllSubAgentDynamicCredentials)(harness, sessionKey) : {};
+    const resolved = (0, config_js_1.resolveConfig)();
+    return Object.entries(persisted)
+        .map(([subAgentType, creds]) => {
+        const mismatch = resolved.projectUrl && creds.projectUrl !== resolved.projectUrl
+            ? { registeredAgainst: creds.projectUrl, current: resolved.projectUrl }
+            : undefined;
+        return {
+            subAgentType,
+            name: resolveDynamicName(creds, subAgentType, harness),
+            clientId: creds.clientId,
+            subject: creds.clientId,
+            registeredAt: new Date(creds.registeredAt * 1000).toISOString(),
+            delegatedBy: creds.delegation?.delegatedBy,
+            projectUrlMismatch: mismatch,
+        };
+    })
+        .sort((a, b) => a.subAgentType.localeCompare(b.subAgentType));
+}
+async function collectPermissions(harness) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    const namespace = resolveNamespace();
+    const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    // Falls back to the last-known cached mode on every path that can't reach the
+    // project to read it live.
+    const base = {
+        mode: resolved.permissionMode,
+        modeSource: resolved.permissionModeSource,
+        namespace,
+    };
+    // One reason covers both missing values: with either absent no check can run.
+    if (!resolved.security.connected)
+        return { ...base, coverageStatus: "not_connected" };
+    if (catalog.length === 0) {
+        return { ...base, coverageStatus: "no_catalog", knownHarnesses: [...tool_catalog_js_1.KNOWN_HARNESSES] };
+    }
+    const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
+    if (!hasUser)
+        return { ...base, coverageStatus: "no_user" };
+    const coverage = await probePermissionsCoverage(harness);
+    if (!coverage)
+        return { ...base, coverageStatus: "no_user" };
+    // The probe read the mode live; prefer it over the cached config value.
+    const withMode = { ...base, mode: coverage.mode, modeSource: coverage.modeSource };
+    if (coverage.errored > 0 && coverage.allowed === 0 && coverage.denied === 0) {
+        return { ...withMode, coverageStatus: "probe_failed", coverage };
+    }
+    const status = coverage.allowed === coverage.total
+        ? "fully_granted"
+        : coverage.allowed === 0
+            ? "no_grants"
+            : "partial";
+    return { ...withMode, coverageStatus: status, coverage };
+}
+function isUserTokenUsable() {
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    return !!tokens && !(0, auth_store_js_1.isExpired)(tokens);
+}
+function readTail(file, limit) {
+    if (!file || !fs.existsSync(file))
+        return { file, count: 0, recent: [] };
+    const lines = fs.readFileSync(file, "utf-8").trim().split("\n").filter(Boolean);
+    const recent = lines.slice(-limit).map((raw) => {
+        try {
+            return { raw, parsed: JSON.parse(raw) };
+        }
+        catch {
+            return { raw };
+        }
+    });
+    return { file, count: lines.length, recent };
+}
+function collectActivity(harness) {
+    const log = readTail((0, client_js_1.resolveDebugLogPath)(harness), 10);
+    return {
+        logFile: log.file,
+        logCount: log.count,
+        recentEvents: log.recent,
+    };
+}
+/**
+ * Gather the full structured status report for a harness. The permissions
+ * section runs a live network probe when a project URL and user identity are
+ * available (same conditions as the text `status` command).
+ *
+ * `sessionKey` is the run being reported on, when the caller is inside one. The
+ * standalone CLI passes none, so the report selects the harness's newest stored
+ * session rather than inventing an ambient session.
+ */
+async function collectStatusReport(harness, sessionKey) {
+    return {
+        harness,
+        config: collectConfig(harness),
+        user: collectUser(),
+        agent: collectAgent(harness, sessionKey),
+        subAgents: collectSubAgents(harness, sessionKey),
+        permissions: await collectPermissions(harness),
+        activity: collectActivity(harness),
+        system: await (0, status_system_js_1.collectSystemServices)(),
+    };
+}

package/dist/status-system.d.ts

@@ -0,0 +1,24 @@
+export interface StatusSystemService {
+    /** Service name, e.g. "Kratos". */
+    name: string;
+    /** One-line role, e.g. "Identities & sessions". */
+    role: string;
+    /** Published host port. */
+    port: number;
+    /** Base URL for the service. */
+    url: string;
+    /** The endpoint probed to decide health. */
+    healthUrl: string;
+    /** true = healthy, false = unreachable/error, null = not probed. */
+    healthy: boolean | null;
+    /** Human-readable detail (HTTP status or error) when unhealthy. */
+    detail?: string;
+}
+export interface StatusSystemSection {
+    services: StatusSystemService[];
+}
+/**
+ * Probe the core Ory services' readiness endpoints and return their health.
+ * Never throws — an unreachable service is reported as `healthy: false`.
+ */
+export declare function collectSystemServices(): Promise<StatusSystemSection>;

package/dist/status-system.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSystemServices = collectSystemServices;
+/**
+ * System-information probe for the dashboard: the health of the core Ory
+ * backend services the plugin authenticates and authorizes against — Kratos
+ * (identities), Hydra (OAuth2), and Keto (permissions).
+ *
+ * This is additive to the shared {@link file://./status-data.ts} report: the
+ * dashboard renders it as a "System information" section, while the installer
+ * simply ignores it. Ports and health endpoints are the same constants the
+ * local-stack manager and `local status` use, so the surfaces never disagree.
+ */
+const configs_js_1 = require("./local/configs.js");
+/** The three core Ory services, in display order. */
+function systemServiceSpecs() {
+    return [
+        { name: "Kratos", role: "Identities & sessions", port: configs_js_1.KRATOS_PUBLIC_PORT, healthPath: "/health/ready" },
+        { name: "Hydra", role: "OAuth2 & OIDC", port: configs_js_1.HYDRA_PUBLIC_PORT, healthPath: "/health/ready" },
+        { name: "Keto", role: "Permissions (Zanzibar relation checks)", port: configs_js_1.KETO_READ_PORT, healthPath: "/health/ready" },
+    ];
+}
+async function probe(healthUrl) {
+    try {
+        const res = await fetch(healthUrl, { signal: AbortSignal.timeout(2500) });
+        if (res.ok)
+            return { healthy: true };
+        return { healthy: false, detail: `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { healthy: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Probe the core Ory services' readiness endpoints and return their health.
+ * Never throws — an unreachable service is reported as `healthy: false`.
+ */
+async function collectSystemServices() {
+    const specs = systemServiceSpecs();
+    const services = await Promise.all(specs.map(async (spec) => {
+        const url = `http://localhost:${spec.port}`;
+        const healthUrl = `${url}${spec.healthPath}`;
+        const { healthy, detail } = await probe(healthUrl);
+        const service = {
+            name: spec.name,
+            role: spec.role,
+            port: spec.port,
+            url,
+            healthUrl,
+            healthy,
+            detail,
+        };
+        return service;
+    }));
+    return { services };
+}

package/dist/subject.d.ts

@@ -1,24 +1,34 @@
 /**
  * User-subject resolution for permission checks.
  *
- * Permission checks need a subject reference that matches the form
- * stored in Keto. Two shapes are supported:
+ * Every principal — user, agent, sub-agent — is addressed as a **SubjectSet**
+ * `<namespace>:<object>` (e.g. `User:<UUID>`). This is the form the Ory Console's
+ * *Add relationship* dialog writes, the form the local-stack seed writes, and the
+ * Zanzibar-idiomatic composition point (grant `Role:developer` `use` on a tool and
+ * add principals to the role, rather than fanning out a tuple per subject). It is
+ * the only first-class subject form: Keto does no cross-form expansion, so a check
+ * must match the write shape exactly, and standardizing on one shape removes that
+ * silent-misfire footgun.
  *
- *   - **SubjectSet** — `<namespace>:<object>` (e.g. `User:<UUID>`). This
- *     is the form the Console's *Add relationship* dialog writes, so
- *     dev/demo flows that grant tuples through the UI use it.
- *
- *   - **Direct SubjectID** — opaque string (e.g. `user:<UUID>` or
- *     `session:<id>`). Backward-compatible default when no subject
- *     namespace is configured.
- *
- * The selection is driven by the user-subject namespace: `ORY_USER_SUBJECT_NAMESPACE`
- * takes precedence, then the client's configured `userSubjectNamespace` (persisted
- * in the shared config, e.g. by the local-stack install path). When a namespace is
- * present the resolver builds a SubjectSet using it; otherwise it falls back to the
- * direct SubjectID chain.
+ * The namespace is resolved by precedence: `ORY_USER_SUBJECT_NAMESPACE` (env) →
+ * the client's configured `userSubjectNamespace` (persisted in the shared config)
+ * → the {@link DEFAULT_USER_SUBJECT_NAMESPACE} (`User`). The env/config values now
+ * *override* the default namespace; they are no longer an opt-in switch that
+ * toggles between SubjectSet and a legacy direct SubjectID.
  */
 import type { OryAgentClient } from "./client.js";
+/**
+ * Default namespace a resolved user principal is addressed under. The
+ * local-stack seed, the Console *Add relationship* dialog, and the Network OPL
+ * provisioning all use `User`, so it is the out-of-the-box default.
+ */
+export declare const DEFAULT_USER_SUBJECT_NAMESPACE = "User";
+/** Namespace the agent principal is addressed under (delegation subjects). */
+export declare const AGENT_NAMESPACE = "Agent";
+/** Namespace a sub-agent principal is addressed under. */
+export declare const SUBAGENT_NAMESPACE = "SubAgent";
+/** Namespace the no-user-identity `session:<id>` fallback is addressed under. */
+export declare const SESSION_NAMESPACE = "Session";
 export type UserSubjectRef = {
     subjectId: string;
 } | {
@@ -33,7 +43,7 @@ export type UserSubjectRef = {
  * client's user principal and the env overrides in
  * {@link resolveUserSubject}. The override only applies within `fn`'s
  * async context, so concurrent calls cannot observe each other's subject.
- * `ORY_USER_SUBJECT_NAMESPACE` SubjectSet shaping still applies.
+ * SubjectSet shaping still applies.
  *
  * A missing/empty `subject` is a no-op: `fn` runs with the normal
  * resolution chain.
@@ -46,13 +56,109 @@ export declare function runWithUserSubject<T>(subject: string | undefined, fn: (
  * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
  *
- * Returns a SubjectSet when a user-subject namespace is configured (env or
- * client config) and a concrete subject is available; otherwise a direct
- * SubjectID.
+ * Always returns a SubjectSet. A resolved principal is addressed under the
+ * configured user namespace (`ORY_USER_SUBJECT_NAMESPACE` → client config →
+ * {@link DEFAULT_USER_SUBJECT_NAMESPACE}). A `session:`-prefixed fallback is
+ * addressed under {@link SESSION_NAMESPACE} (`Session:<id>`). Only when nothing
+ * resolves at all do we emit the direct `agent:unknown` sentinel — an error
+ * marker that must never match a stored tuple.
  */
 export declare function resolveUserSubject(client: OryAgentClient, fallback?: string): UserSubjectRef;
 /**
  * Printable label for a `UserSubjectRef`. Used in denial messages and
- * span attributes. SubjectSets render as `<namespace>:<object>`.
+ * activity attributes. SubjectSets render as `<namespace>:<object>`.
  */
 export declare function subjectLabel(ref: UserSubjectRef): string;
+/** Separator between the credential client id and narrower scoping axes. */
+export declare const SUBJECT_AXIS_SEPARATOR = "|";
+/** The env var that overrides the agent's subject. */
+export declare const AGENT_SUBJECT_ID_ENV_VAR = "ORY_AGENT_SUBJECT_ID";
+/**
+ * Validate a subject override (issue #241).
+ *
+ * `deriveSubject` above already refuses to produce a trailing separator,
+ * because a subject ending in `|` silently never matches a stored relation.
+ * The same care is owed to the *base* it joins onto, which arrives from an
+ * operator-settable env var and was previously used verbatim.
+ *
+ * A value containing the axis separator is rejected for two independent
+ * reasons:
+ *
+ * 1. **It collapses the identity grains.** The credential, session, and spawn
+ *    subjects are told apart only by separator position, so an override
+ *    containing one makes them ambiguous: `override="a|b"` in session `c` and
+ *    `override="a"` in session `b|c` produce the same string. A session-scoped
+ *    block written to stop one runaway run could then match the base credential, or a
+ *    different run — and all three grains are read together in one batched
+ *    check, so this is a live semantics break rather than a theoretical one.
+ * 2. **It forges a delegation-node reference** (#225). A join key is exactly
+ *    `<identity>|<harness>|<host>|<session>`, and the two string spaces stay
+ *    disjoint today only because a Hydra client id is a UUID and contains no
+ *    separator. This env var is the one supported knob that breaks that.
+ *
+ * Rejected rather than sanitized: silently stripping the separator would
+ * produce a *different* subject than the operator asked for, which fails just
+ * as confusingly and is harder to notice. Ignoring the value falls back to the
+ * client id — a real, working identity — and says so.
+ */
+export declare function validateSubjectOverride(raw: string | undefined, envVar?: string): {
+    value?: string;
+    warning?: string;
+};
+/**
+ * Read and validate `ORY_AGENT_SUBJECT_ID`. Returns `undefined` when unset or
+ * rejected, pushing an explanation onto `warnings` in the latter case.
+ *
+ * One reader for every site that consumes the override, so the rule cannot hold
+ * in the resolver and not in what `status` reports.
+ */
+export declare function readAgentSubjectOverride(env?: NodeJS.ProcessEnv, warnings?: string[]): string | undefined;
+/**
+ * The registered agent credential subject: `Agent:<clientId>`. For DCR this
+ * client belongs to one session; static credentials may be shared explicitly.
+ *
+ * `undefined` when no agent principal is populated — the agent gate never
+ * blocks, so a session with no resolved machine identity is normal and callers
+ * must treat a missing agent subject as "nothing to check", not as a deny.
+ */
+export declare function resolveAgentSubject(client: OryAgentClient): UserSubjectRef | undefined;
+/**
+ * The **session-level** agent subject: `Agent:<clientId>|<session>`, unique to
+ * one run. Used for a block that stops the session's narrower subject without
+ * blocking its base credential subject.
+ *
+ * `undefined` when there is no agent principal, and — deliberately — also when
+ * there is no session. A caller with no session concept (an SDK integration in
+ * a long-running service) has exactly one sessionless credential subject;
+ * inventing a placeholder session would either collapse every run onto
+ * one string or produce a subject no admin could have written.
+ */
+export declare function resolveAgentSessionSubject(client: OryAgentClient, sessionId?: string): UserSubjectRef | undefined;
+/**
+ * The registered sub-agent credential subject: `SubAgent:<clientId>` for one
+ * typed sub-agent in one session.
+ *
+ * `subAgentClientId` is the client id from {@link ensureSubAgentIdentity};
+ * `undefined` in, and `undefined` out, since a sub-agent whose identity did not
+ * resolve has nothing to check.
+ */
+export declare function resolveSubAgentSubject(subAgentClientId: string | undefined): UserSubjectRef | undefined;
+/**
+ * The **spawn-level** sub-agent subject:
+ * `SubAgent:<clientId>|<session>|<type>[|<spawn>]`, the finest grain available.
+ *
+ * `perSpawnId` distinguishes two *concurrent* same-type sub-agents and is only
+ * present on harnesses that expose one (Cursor's `subagent_id`, Claude Code's
+ * `agent_id`, OpenClaw's `childRunId`, …). Where the harness exposes none the
+ * subject stops at the type and concurrent spawns share it — a limit of the
+ * harness, not of this model.
+ *
+ * As with the agent session subject, a missing session yields `undefined`
+ * rather than a placeholder.
+ */
+export declare function resolveSubAgentSpawnSubject(client: OryAgentClient, args: {
+    subAgentClientId?: string;
+    subAgentType: string;
+    perSpawnId?: string;
+    sessionId?: string;
+}): UserSubjectRef | undefined;