@ory/argus 0.13.9 → 1.0.0

package/dist/status-cli.js

@@ -2,13 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printUserIdentitySection = printUserIdentitySection;
 exports.printAgentIdentitySection = printAgentIdentitySection;
+exports.printSubAgentIdentitiesSection = printSubAgentIdentitiesSection;
 exports.printPermissionsSection = printPermissionsSection;
 exports.runStatusCommand = runStatusCommand;
 /**
  * Unified `status` CLI implementation. Each harness's `cli/main.ts` `status`
  * subcommand delegates here so onboarding readers see configuration, user
- * identity, agent identity, permissions, and the harness-specific plugin
- * registration block in a single pass.
+ * identity, agent identity, sub-agent identities, permissions, and the
+ * harness-specific plugin registration block in a single pass.
  *
  * The drill-down commands (`agent status`, `permissions status`) remain
  * unchanged — this composes their inputs without altering their output.
@@ -16,30 +17,16 @@ exports.runStatusCommand = runStatusCommand;
 const config_js_1 = require("./config.js");
 const auth_store_js_1 = require("./auth-store.js");
 const agent_auth_js_1 = require("./agent-auth.js");
-const client_js_1 = require("./client.js");
-const logger_js_1 = require("./logger.js");
-const agent_auth_js_2 = require("./agent-auth.js");
+const branding_js_1 = require("./branding.js");
 const subject_js_1 = require("./subject.js");
+const logger_js_1 = require("./logger.js");
+const auth_js_1 = require("./auth.js");
+const status_data_js_1 = require("./status-data.js");
 const tool_catalog_js_1 = require("./tool-catalog.js");
 const cli_js_1 = require("./cli.js");
 const cli_invocation_js_1 = require("./cli-invocation.js");
 function resolveNamespace() {
-    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
-}
-/**
- * Human-readable annotation for where the resolved user-login flag came
- * from, so `status` readers know whether to look at the env var or the
- * config file to change it.
- */
-function formatUserLoginSource(source) {
-    switch (source) {
-        case "env":
-            return " (ORY_USER_LOGIN env var)";
-        case "config":
-            return " (saved in config; change with: configure --user-login|--no-user-login)";
-        case "default":
-            return "";
-    }
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTool";
 }
 /**
  * Format a relative duration like "4h 32m" or "12s" for a future deadline.
@@ -61,27 +48,16 @@ function formatExpiresIn(expiresAtSec, nowMs = Date.now()) {
     return `${remaining}s`;
 }
 /**
- * Render the "User identity" block. Shows the `ORY_USER_LOGIN` state and,
- * when a PKCE token is cached, the resolved subject and expiry.
+ * Render the "User identity" block. The interactive PKCE login runs every
+ * session; this shows the cached token's subject and expiry, if any.
  */
 function printUserIdentitySection() {
-    const resolved = (0, config_js_1.resolveConfig)();
-    const loginOn = resolved.userLogin;
     const tokens = (0, auth_store_js_1.loadTokens)();
     console.log("");
     console.log("User identity (interactive PKCE login):");
-    const loginState = loginOn
-        ? `on${formatUserLoginSource(resolved.userLoginSource)}`
-        : "off (enable with: configure --user-login, or ORY_USER_LOGIN=true)";
-    console.log(`  Login:       ${loginState}`);
     if (!tokens) {
         console.log("  Token cache: empty");
-        if (loginOn) {
-            console.log("  Subject:     (will resolve at next session start)");
-        }
-        else {
-            console.log("  Subject:     (login disabled — no PKCE flow will run)");
-        }
+        console.log("  Subject:     (will resolve at next session start)");
         return;
     }
     const expired = (0, auth_store_js_1.isExpired)(tokens);
@@ -91,6 +67,10 @@ function printUserIdentitySection() {
     else {
         console.log(`  Token cache: present (expires in ${formatExpiresIn(tokens.expiresAt)})`);
     }
+    const displayName = tokens.displayName ?? (0, auth_js_1.displayNameFromIdToken)(tokens.idToken);
+    if (displayName) {
+        console.log(`  Name:        ${displayName}`);
+    }
     const subject = tokens.subject ? `user:${tokens.subject}` : "(no subject claim on cached token)";
     console.log(`  Subject:     ${subject}`);
     if (tokens.clientId) {
@@ -99,183 +79,182 @@ function printUserIdentitySection() {
 }
 /**
  * Render the "Agent identity" block. Summarizes the resolved machine
- * credential — static env override, persisted DCR, or unconfigured.
+ * credential — static env override, persisted DCR, or unconfigured. Each
+ * installed harness has its own agent registration, so the report is for
+ * `harness`'s identity only.
  */
-function printAgentIdentitySection() {
+function printAgentIdentitySection(harness) {
     console.log("");
     console.log("Agent identity (non-interactive):");
-    // Static overrides take precedence — surface them so the reader knows
+    // The one static override takes precedence — surface it so the reader knows
     // why DCR isn't running.
-    if (process.env.ORY_AGENT_API_KEY) {
-        console.log("  Source:      static API key (ORY_AGENT_API_KEY)");
-        if (process.env.ORY_AGENT_SUBJECT_ID) {
-            console.log(`  Subject:     ${process.env.ORY_AGENT_SUBJECT_ID}`);
-        }
-        return;
-    }
     if (process.env.ORY_AGENT_CLIENT_ID && process.env.ORY_AGENT_CLIENT_SECRET) {
         console.log("  Source:      static client_credentials (ORY_AGENT_CLIENT_ID/SECRET)");
         console.log(`  Client ID:   ${process.env.ORY_AGENT_CLIENT_ID}`);
-        const subject = process.env.ORY_AGENT_SUBJECT_ID ?? process.env.ORY_AGENT_CLIENT_ID;
+        const subject = (0, subject_js_1.readAgentSubjectOverride)() ?? process.env.ORY_AGENT_CLIENT_ID;
         console.log(`  Subject:     ${subject}`);
         return;
     }
-    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
-    if (!persisted) {
+    const latest = (0, agent_auth_js_1.latestAgentRegistration)(harness);
+    if (!latest) {
         console.log("  Source:      not registered yet");
         console.log("  Status:      first session start will register an OAuth2 client (RFC 7591)");
         return;
     }
+    const { sessionKey, credentials: persisted } = latest;
     const resolved = (0, config_js_1.resolveConfig)();
     const mismatched = resolved.projectUrl && persisted.projectUrl !== resolved.projectUrl;
     console.log("  Source:      OAuth2 Dynamic Client Registration (RFC 7591)");
     console.log(`  Status:      registered`);
+    console.log(`  Name:        ${(0, status_data_js_1.resolveDynamicName)(persisted)}`);
     console.log(`  Client ID:   ${persisted.clientId}`);
-    const subject = process.env.ORY_AGENT_SUBJECT_ID ?? persisted.clientId;
-    console.log(`  Subject:     ${subject}`);
+    const subject = (0, subject_js_1.readAgentSubjectOverride)() ?? persisted.clientId;
+    console.log(`  Subject:     ${subject_js_1.AGENT_NAMESPACE}:${subject}`);
     console.log(`  Registered:  ${new Date(persisted.registeredAt * 1000).toISOString()}`);
+    console.log(`  Session:     ${sessionKey}`);
+    console.log(`  Retained:    ${(0, agent_auth_js_1.countAgentSessions)(harness)} session(s)`);
+    if (sessionKey !== config_js_1.SESSIONLESS_KEY) {
+        console.log(`  Session ID:  ${subject_js_1.AGENT_NAMESPACE}:${subject}|${sessionKey}`);
+    }
     if (mismatched) {
         console.log(`  Warning:     registered against ${persisted.projectUrl}, but current project URL is ${resolved.projectUrl}`);
         console.log("               run `agent unregister` to clear stale credentials");
     }
 }
-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,
-        });
+/**
+ * Render the "Sub-agent identities" block — one entry per typed sub-agent
+ * (e.g. `Explore`, `general-purpose`) the agent has registered a distinct
+ * OAuth2 client for via DCR. All sub-agent identities are dynamic
+ * registrations. Scoped to `harness` — sub-agents belong to that harness's
+ * agent. A no-op when none exist yet.
+ */
+function printSubAgentIdentitiesSection(harness) {
+    const sessionKey = (0, agent_auth_js_1.latestAgentRegistration)(harness)?.sessionKey ?? (0, agent_auth_js_1.latestSubAgentSession)(harness);
+    const subAgents = sessionKey
+        ? (0, agent_auth_js_1.loadAllSubAgentDynamicCredentials)(harness, sessionKey)
+        : {};
+    const types = Object.keys(subAgents).sort((a, b) => a.localeCompare(b));
+    console.log("");
+    console.log(`Sub-agent identities${sessionKey ? ` (session ${(0, branding_js_1.shortSessionLabel)(sessionKey)})` : ""}:`);
+    if (types.length === 0) {
+        console.log("  None registered yet — one is registered the first time the agent");
+        console.log("  spawns a typed sub-agent (e.g. a Task / Explore sub-agent).");
+        return;
     }
-    await (0, agent_auth_js_2.ensureAgentIdentity)(client, { projectUrl: resolved.projectUrl }).catch(() => {
-        /* best-effort; the probe still runs with whatever credentials we have */
-    });
-    const subject = (0, subject_js_1.resolveUserSubject)(client);
-    const subjectId = (0, subject_js_1.subjectLabel)(subject);
-    if (subjectId === "agent:unknown")
-        return undefined;
-    const namespace = resolveNamespace();
-    const result = {
-        total: catalog.length,
-        allowed: 0,
-        denied: 0,
-        errored: 0,
-    };
-    for (const tool of catalog) {
-        const check = {
-            namespace,
-            object: tool,
-            relation: "use",
-            ...subject,
-        };
-        try {
-            const probe = await client.checkPermission(check, {
-                spanAttributes: { 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";
+    const resolved = (0, config_js_1.resolveConfig)();
+    types.forEach((type, i) => {
+        if (i > 0)
+            console.log("");
+        const creds = subAgents[type];
+        const subject = creds.delegation?.delegatedBy
+            ? `subagent:${creds.clientId} (delegated by ${creds.delegation.delegatedBy})`
+            : `subagent:${creds.clientId}`;
+        console.log(`  ${type}:`);
+        console.log(`    Name:       ${(0, status_data_js_1.resolveDynamicName)(creds, type)}`);
+        console.log(`    Client ID:  ${creds.clientId}`);
+        console.log(`    Subject:    ${subject}`);
+        console.log(`    Registered: ${new Date(creds.registeredAt * 1000).toISOString()}`);
+        if (resolved.projectUrl && creds.projectUrl !== resolved.projectUrl) {
+            console.log(`    Warning:    registered against ${creds.projectUrl}, but current project URL is ${resolved.projectUrl}`);
         }
-    }
-    return result;
+    });
 }
 /**
- * Render the "Permissions" block. Always prints the configured mode and
- * namespace; runs a network probe of the harness's built-in tool catalog
- * only when a project URL is configured *and* a user identity is
- * available (cached PKCE tokens or `ORY_USER_SUBJECT_ID`).
+ * Render the "Permissions" block: the deny posture, the namespace, and the
+ * coverage of the harness's built-in tool catalog.
+ *
+ * The network probe runs only when a project URL is configured *and* a user
+ * identity is available (cached PKCE tokens or `ORY_USER_SUBJECT_ID`). When it
+ * runs, the reported **Mode is read live from the project** in the same pass, so
+ * this line answers "what would a tool call do right now?" rather than echoing a
+ * cache that is only refreshed at session start. On every other path the last
+ * cached value is reported, annotated as such.
  */
 async function printPermissionsSection(binName, harness) {
     const resolved = (0, config_js_1.resolveConfig)();
     const namespace = resolveNamespace();
     const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    const cachedMode = `${resolved.permissionMode}${formatModeSuffix(resolved.permissionModeSource)}`;
     console.log("");
     console.log("Permissions:");
-    console.log(`  Mode:        ${resolved.permissionMode}${formatModeSuffix(resolved.permissionModeSource)}`);
-    console.log(`  Namespace:   ${namespace}`);
-    if (resolved.auditOnly) {
-        console.log("  Coverage:    n/a (audit-only mode — Ory checks disabled)");
-        return;
-    }
-    if (!resolved.projectUrl) {
-        console.log("  Coverage:    n/a (no project URL configured)");
-        return;
+    // Reasons the probe can't run. Each reports the cached mode, since there is no
+    // way to read the live one without reaching the project.
+    if (!resolved.security.connected) {
+        return printNoCoverage(cachedMode, namespace, `n/a (Agent Security not connected — ${(0, config_js_1.describeSecurityGap)(resolved.security)})`);
     }
     if (catalog.length === 0) {
-        console.log(`  Coverage:    n/a (no built-in catalog for harness "${harness}")`);
+        printNoCoverage(cachedMode, namespace, `n/a (no built-in catalog for harness "${harness}")`);
         console.log(`               known harnesses: ${tool_catalog_js_1.KNOWN_HARNESSES.join(", ")}`);
         return;
     }
-    const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
-    if (!hasUser) {
-        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=true once,`);
-        console.log(`               or set ORY_USER_SUBJECT_ID to probe a known subject)`);
+    if (!(process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable())) {
+        printNoCoverage(cachedMode, namespace, "n/a (no cached user identity — start a session once to sign in,");
+        console.log("               or set ORY_USER_SUBJECT_ID to probe a known subject)");
         return;
     }
-    process.stdout.write("  Coverage:    checking…\r");
-    const probe = await probePermissionsCoverage(harness);
-    // Clear the "checking…" line by overwriting it.
-    process.stdout.write(" ".repeat(40) + "\r");
+    // The probe reads the live mode in the same pass, so hold the Mode line until
+    // it returns rather than printing a cached value we are about to supersede.
+    //
+    // The progress line is carriage-return overwritten, which only renders as
+    // intended on a terminal — piped or redirected output would keep the literal
+    // \r and the spaces, so skip it entirely when stdout isn't a TTY.
+    const spinner = process.stdout.isTTY === true;
+    if (spinner)
+        process.stdout.write("  checking…\r");
+    const probe = await (0, status_data_js_1.probePermissionsCoverage)(harness);
+    if (spinner)
+        process.stdout.write(" ".repeat(40) + "\r");
     if (!probe) {
-        console.log("  Coverage:    unavailable (no user identity could be resolved)");
-        return;
+        return printNoCoverage(cachedMode, namespace, "unavailable (no user identity could be resolved)");
     }
     const { total, allowed, denied, errored } = probe;
+    console.log(`  Mode:        ${probe.mode}${formatModeSuffix(probe.modeSource)}`);
+    console.log(`  Namespace:   ${namespace}`);
+    console.log(`  Subject:     ${probe.subject}`);
     if (errored > 0 && allowed === 0 && denied === 0) {
         console.log(`  Coverage:    probe failed (${probe.errorCode ?? "unknown"})`);
         return;
     }
     const status = allowed === total
-        ? `bootstrapped (${allowed}/${total} built-in tools)`
+        ? `fully granted (${allowed}/${total} built-in tools)`
         : allowed === 0
-            ? `not bootstrapped (0/${total} built-in tools)`
+            ? `no grants (0/${total} built-in tools)`
             : `partial (${allowed}/${total} built-in tools allowed)`;
     console.log(`  Coverage:    ${status}`);
     if (denied > 0) {
-        console.log(`               run "${(0, cli_invocation_js_1.oryNpx)(binName)} permissions bootstrap" to grant the missing tools`);
+        console.log("               grant the missing tools in the Ory Console (Agent Security)");
     }
     else if (errored > 0) {
-        console.log(`               ${errored} probe error(s) — run "${(0, cli_invocation_js_1.oryNpx)(binName)} permissions status" for details`);
+        console.log(`               ${errored} probe error(s) — run "${(0, cli_invocation_js_1.oryNpx)(binName)} permissions" for details`);
     }
 }
+/** The Mode / Namespace / Coverage lines for every path that can't probe. */
+function printNoCoverage(mode, namespace, coverage) {
+    console.log(`  Mode:        ${mode}`);
+    console.log(`  Namespace:   ${namespace}`);
+    console.log(`  Coverage:    ${coverage}`);
+}
 function isUserTokenUsable() {
     const tokens = (0, auth_store_js_1.loadTokens)();
     return !!tokens && !(0, auth_store_js_1.isExpired)(tokens);
 }
 function formatModeSuffix(source) {
     switch (source) {
-        case "env":
-            return "  (from ORY_PERMISSION_MODE env)";
-        case "config":
-            return "  (from config — change with `permissions observe|enforce`)";
+        case "server":
+            return "  (read from the Ory project)";
+        case "cache":
+            return "  (cached — project unreachable)";
         case "default":
-            return "  (default)";
+            return "  (default — not yet read from the project)";
     }
 }
 /**
  * Compose the unified `status` output for a plugin CLI. Sections render
  * in this order: title → configuration → user identity → agent identity
- * → permissions → hooks & plugin → environment → recent activity
- * (traces + debug log).
+ * → sub-agent identities → permissions → hooks & plugin → environment →
+ * recent activity from the unified activity/debug log.
  *
- * Each section degrades gracefully — missing project URL, audit-only
+ * Each section degrades gracefully — Agent Security not connected
  * mode, and empty token caches all surface as inline "n/a" lines rather
  * than aborting the command.
  */
@@ -292,19 +271,20 @@ async function runStatusCommand(binName, harness, options) {
         console.log("");
         (0, cli_js_1.printOryConfig)();
         printUserIdentitySection();
-        printAgentIdentitySection();
+        printAgentIdentitySection(harness);
+        printSubAgentIdentitiesSection(harness);
         await printPermissionsSection(binName, harness);
         if (options.printPluginSection) {
             console.log("");
-            options.printPluginSection();
+            await options.printPluginSection();
         }
         (0, cli_js_1.printEnvironment)();
         console.log("");
         console.log("Recent activity:");
-        (0, cli_js_1.printTraceTail)(harness);
         (0, cli_js_1.printLogTail)(harness);
         console.log("");
-        console.log(`  Watch traces live:  ${(0, cli_invocation_js_1.oryNpx)(binName)} watch`);
+        console.log(`  Live activity/debug: ${(0, cli_invocation_js_1.oryNpx)(binName)} watch`);
+        console.log("  Include verbose diagnostics: set ORY_AGENT_DEBUG=true before starting the harness");
         console.log("");
         console.log(`Drill into any section with:`);
         console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} agent status`);

package/dist/status-data.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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.
+ */
+import { type PermissionMode, type SecurityConnection } from "./config.js";
+import { type PermissionModeSource } from "./permission-mode.js";
+import { type StatusSystemSection } from "./status-system.js";
+export interface PermissionsCoverage {
+    total: number;
+    allowed: number;
+    denied: number;
+    errored: number;
+    errorCode?: string;
+    /**
+     * The **live** deny posture, read from the project during the same probe.
+     * `status` reports this rather than the cached `config.permissionMode`: the
+     * two can disagree (the cache is only refreshed at session start), and the
+     * cached one is the misleading answer to "what would a tool call do now?".
+     */
+    mode: PermissionMode;
+    modeSource: PermissionModeSource;
+    /** The subject the probe actually checked as, e.g. `User:<id>`. */
+    subject: string;
+}
+/**
+ * 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.
+ */
+export declare function probePermissionsCoverage(harness: string): Promise<PermissionsCoverage | undefined>;
+export interface StatusConfigSection {
+    configPath: string;
+    /** Whether a config file actually exists at `configPath` (vs. where one would be written). */
+    configExists: boolean;
+    projectUrl?: string;
+    projectUrlSource: "env" | "config" | "none";
+    projectId?: string;
+    projectIdSource: "env" | "config" | "none";
+    /** Human-readable project / workspace names captured at install (display only). */
+    projectName?: string;
+    workspaceName?: string;
+    oauth2ClientId?: string;
+    oauth2ClientIdSource: "env" | "config" | "default";
+    /** Display name of the shared PKCE user-login client. Present only when the
+     *  configured client id *is* the reserved shared-login id — a project may
+     *  legitimately be pointed at some other public client (or at one provisioned
+     *  before the id was reserved), and labelling that one with the shared
+     *  client's name would claim an identity it does not have. */
+    oauth2ClientName?: string;
+    /** Whether Agent Security runs, derived from the project and broker URLs. */
+    security: SecurityConnection;
+    permissionMode: "observe" | "enforce";
+    permissionModeSource: "server" | "cache" | "default";
+    userSubjectNamespace?: string;
+    userSubjectNamespaceSource: "env" | "config" | "none";
+    /** The tool namespace tool-use checks are addressed under (`ORY_PERMISSION_NAMESPACE`
+     *  → default `AgentTool`). This is the namespace the `access` permit is checked in. */
+    namespace: string;
+    /** The principal namespaces the model addresses subjects under — `User`, `Agent`,
+     *  `SubAgent`, and the `Session` fallback. These are the subject namespaces the
+     *  checked `namespace` references; sourced from the canonical OPL constants so the
+     *  dashboard lists the whole model, not just the tool namespace. */
+    principalNamespaces: string[];
+    /** Whether debug logging is on (`ORY_AGENT_DEBUG=true`). Env-only, read at
+     *  process start by the logger — not persisted config, so it's shown read-only. */
+    debugEnabled: boolean;
+}
+export interface StatusUserSection {
+    tokenCache: "empty" | "present" | "stale";
+    subject?: string;
+    /**
+     * Human-readable name for the signed-in user (email / name /
+     * preferred_username), decoded from the persisted id_token. Present only
+     * when the id_token carries a profile claim — i.e. the login requested the
+     * `profile` / `email` scopes. Absent otherwise; callers fall back to the
+     * subject id.
+     */
+    displayName?: string;
+    expiresInSeconds?: number;
+    clientId?: string;
+}
+export type AgentIdentitySource = "static_client_credentials" | "dcr" | "unregistered";
+export interface StatusAgentSection {
+    source: AgentIdentitySource;
+    /** Human-readable OAuth2 client_name for a DCR agent, when known. */
+    name?: string;
+    clientId?: string;
+    subject?: string;
+    registeredAt?: string;
+    /**
+     * The session whose credential this report describes, if any. Sessionless SDK
+     * callers report the reserved `sessionless` key.
+     */
+    sessionKey?: string;
+    /**
+     * The narrower per-session subject for this run. Absent when there is no
+     * ambient session (an SDK integration with no session concept).
+     */
+    sessionSubject?: string;
+    projectUrlMismatch?: {
+        registeredAgainst: string;
+        current: string;
+    };
+}
+/**
+ * A typed sub-agent's persisted DCR identity — one row per sub-agent type
+ * (e.g. `Explore`, `general-purpose`) the agent has spawned and registered.
+ * All sub-agent identities are dynamic registrations, so this always mirrors
+ * an `agent.subAgents[<harness>][<session>][<type>]` entry in the shared config
+ * — the report covers the newest session of the harness it is run for, since a
+ * sub-agent belongs to one specific run of that harness's agent.
+ */
+export interface StatusSubAgentSection {
+    /** Sub-agent type key (the config map key), e.g. `"Explore"`. */
+    subAgentType: string;
+    /** Human-readable OAuth2 client_name for this sub-agent, when known. */
+    name?: string;
+    clientId: string;
+    subject: string;
+    registeredAt?: string;
+    /** The delegator recorded at registration (`agent:<sub>`), when known. */
+    delegatedBy?: string;
+    projectUrlMismatch?: {
+        registeredAgainst: string;
+        current: string;
+    };
+}
+export type PermissionsCoverageStatus = 
+/** Agent Security isn't connected — no project URL and/or OAuth2 client id. */
+"not_connected" | "no_catalog" | "no_user" | "fully_granted" | "partial" | "no_grants" | "probe_failed";
+export interface StatusPermissionsSection {
+    mode: "observe" | "enforce";
+    /** Where `mode` came from: a live project read, the local cache, or the default. */
+    modeSource: PermissionModeSource;
+    namespace: string;
+    coverageStatus: PermissionsCoverageStatus;
+    coverage?: PermissionsCoverage;
+    knownHarnesses?: string[];
+}
+export interface StatusActivityEntry {
+    raw: string;
+    parsed?: Record<string, unknown>;
+}
+export interface StatusActivitySection {
+    logFile?: string;
+    logCount: number;
+    recentEvents: StatusActivityEntry[];
+}
+export interface StatusReport {
+    harness: string;
+    config: StatusConfigSection;
+    user: StatusUserSection;
+    agent: StatusAgentSection;
+    /** Persisted per-type sub-agent DCR identities (may be empty). */
+    subAgents: StatusSubAgentSection[];
+    permissions: StatusPermissionsSection;
+    activity: StatusActivitySection;
+    /** Core Ory service health (Kratos, Hydra, Keto) — the dashboard's "System information". */
+    system: StatusSystemSection;
+}
+/**
+ * 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.
+ */
+export declare function resolveDynamicName(creds: {
+    clientName?: string;
+    harness?: string;
+}, subAgentType?: string, harness?: string): string;
+/**
+ * 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.
+ */
+export declare function collectStatusReport(harness: string, sessionKey?: string): Promise<StatusReport>;