@ory/argus 0.3.0 → 0.4.0

package/dist/cli.js

@@ -93,7 +93,7 @@ function runConfigureCommand(binName, args) {
         console.log("");
         console.log("Or set environment variables:");
         console.log("  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
-        console.log("  export ORY_API_KEY=ory_pat_...");
+        console.log("  export ORY_AGENT_API_KEY=ory_pat_...");
         return;
     }
     if (auditOnly) {
@@ -122,7 +122,7 @@ function runConfigureCommand(binName, args) {
         console.log(`  API Key: (set)`);
     console.log("");
     console.log("This configuration is shared across all Ory agent plugins.");
-    console.log("Environment variables (ORY_PROJECT_URL, ORY_API_KEY) take precedence when set.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY) take precedence when set.");
 }
 /**
  * Print the "Configuration:" block showing Ory project URL and API key status.
@@ -130,11 +130,14 @@ function runConfigureCommand(binName, args) {
 function printOryConfig() {
     const resolved = (0, config_js_1.resolveConfig)();
     const configPath = (0, config_js_1.getConfigPath)();
+    const namespace = process.env.ORY_PERMISSION_NAMESPACE || "AgentTools";
     console.log("Configuration:");
-    console.log(`  Config file: ${configPath}`);
-    console.log(`  Mode:        ${resolved.auditOnly ? "audit-only" : "full"}`);
-    console.log(`  Project URL: ${resolved.projectUrl ?? "NOT SET"} [source: ${resolved.projectUrlSource}]`);
-    console.log(`  API Key:     ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
+    console.log(`  Config file:     ${configPath}`);
+    console.log(`  Mode:            ${resolved.auditOnly ? "audit-only" : "full"}`);
+    console.log(`  Project URL:     ${resolved.projectUrl ?? "NOT SET"} [source: ${resolved.projectUrlSource}]`);
+    console.log(`  API Key:         ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
+    console.log(`  Permission mode: ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
+    console.log(`  Namespace:       ${namespace}`);
 }
 /**
  * Print the "Environment:" block showing Ory-related environment variables.
@@ -143,14 +146,37 @@ function printEnvironment() {
     console.log("");
     console.log("Environment:");
     const vars = [
-        ["ORY_SESSION_TOKEN", process.env.ORY_SESSION_TOKEN ? "(set)" : undefined, false],
+        ["ORY_AUTH_GATE", process.env.ORY_AUTH_GATE, false],
+        [
+            "ORY_AGENT_API_KEY",
+            process.env.ORY_AGENT_API_KEY ? "(set)" : undefined,
+            false,
+        ],
+        ["ORY_AGENT_CLIENT_ID", process.env.ORY_AGENT_CLIENT_ID, false],
+        [
+            "ORY_USER_SESSION_TOKEN",
+            process.env.ORY_USER_SESSION_TOKEN ? "(set)" : undefined,
+            false,
+        ],
+        ["ORY_USER_SUBJECT_ID", process.env.ORY_USER_SUBJECT_ID, false],
         ["ORY_AGENT_SUBJECT_ID", process.env.ORY_AGENT_SUBJECT_ID, false],
         ["ORY_AGENT_DEBUG", process.env.ORY_AGENT_DEBUG, false],
         ["ORY_AGENT_LOG_FILE", process.env.ORY_AGENT_LOG_FILE, false],
         ["ORY_AGENT_TRACE_FILE", process.env.ORY_AGENT_TRACE_FILE, false],
     ];
+    if (process.env.ORY_API_KEY && !process.env.ORY_AGENT_API_KEY) {
+        vars.splice(2, 0, [
+            "ORY_API_KEY",
+            "(set, DEPRECATED — use ORY_AGENT_API_KEY)",
+            false,
+        ]);
+    }
     for (const [name, value, required] of vars) {
-        const display = value ? `${value}` : required ? "NOT SET (required)" : "not set";
+        const display = value
+            ? value
+            : required
+                ? "NOT SET (required)"
+                : "not set";
         const icon = value ? "+" : required ? "!" : "-";
         console.log(`  [${icon}] ${name}: ${display}`);
     }
@@ -188,7 +214,7 @@ function printEnvHelp(binName) {
     console.log("");
     console.log("  Option 2 — Set environment variables:");
     console.log("    export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
-    console.log("    export ORY_API_KEY=ory_pat_...");
+    console.log("    export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
     console.log("If neither is set when a session starts, the agent will prompt for configuration.");
 }
@@ -355,7 +381,7 @@ async function interactiveConfigPrompt(binName) {
         "",
         "You can also set environment variables (requires session restart):",
         "  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com",
-        "  export ORY_API_KEY=ory_pat_...",
+        "  export ORY_AGENT_API_KEY=ory_pat_...",
         "",
     ].join("\n");
     process.stderr.write(message + "\n");

package/dist/config.js

@@ -323,7 +323,10 @@ function writeConfigAtomic(config) {
 function resolveConfig() {
     const file = loadConfig();
     const envProjectUrl = process.env.ORY_PROJECT_URL;
-    const envApiKey = process.env.ORY_API_KEY;
+    // ORY_AGENT_API_KEY is the documented name; ORY_API_KEY is the deprecated
+    // alias kept for back-compat (agent-auth emits a warning when only the
+    // legacy form is set).
+    const envApiKey = process.env.ORY_AGENT_API_KEY ?? process.env.ORY_API_KEY;
     const envMode = parsePermissionMode(process.env.ORY_PERMISSION_MODE);
     const permissionMode = envMode ?? file.permissionMode ?? "observe";
     const permissionModeSource = envMode

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { resolveAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, f
 export { type SessionInfo, type OAuth2TokenInfo, type PermissionCheck, type PermissionResult, type BatchPermissionResult, type OryError, type OryErrorCode, } from "./types.js";
 export { runConfigureCommand, runAgentCommand, printOryConfig, printEnvironment, printLogTail, printEnvHelp, printTraceTail, runWatchCommand, isTtyAvailable, promptOnTty, promptForProjectUrl, interactiveConfigPrompt, } from "./cli.js";
 export { runPermissionsCommand, isUserIdentityCached, maybeAutoBootstrap, printPermissionsOnboardingHelp, } from "./permissions-cli.js";
+export { runStatusCommand, printUserIdentitySection, printAgentIdentitySection, printPermissionsSection, type StatusCommandOptions, } from "./status-cli.js";
 export { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, resolveHookCommand, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, resolveMcpServerCommand, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
 export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./dev.js";
 export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printOryConfig = exports.runAgentCommand = exports.runConfigureCommand = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.clearSubAgentDynamicCredentials = exports.saveSubAgentDynamicCredentials = exports.loadSubAgentDynamicCredentials = exports.clearAgentDynamicCredentials = exports.saveAgentDynamicCredentials = exports.loadAgentDynamicCredentials = exports.registerAgentClient = exports.fetchClientCredentialsToken = exports.ensureSubAgentIdentity = exports.ensureAgentIdentity = exports.resolveAgentCredentials = exports.ensureAuthenticated = exports.ensureUserAuthenticated = exports.TOKEN_EXPIRY_SKEW_SEC = exports.waitForPeerTokensSync = exports.waitForPeerTokens = exports.clearPkceFlightLock = exports.tryAcquirePkceFlightLock = exports.refreshAndSave = exports.isExpired = exports.clearTokens = exports.saveTokens = exports.loadTokens = exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = exports.buildAuthorizeUrl = exports.sha256Base64Url = exports.generateCodeVerifier = exports.detectHeadless = exports.refreshAccessToken = exports.pkceLogin = exports.getHarnessDataDir = exports.getDataDir = exports.getConfigPath = exports.mutateConfig = exports.resolveConfig = exports.saveConfig = exports.loadConfig = exports.watchTraceFile = exports.formatSpan = exports.deriveTraceId = exports.ActiveSpan = exports.Tracer = exports.redactLogData = exports.DebugLogger = exports.OryAgentClient = void 0;
-exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = void 0;
-exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpHttpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.applyPermissionMode = exports.checkAndDecide = void 0;
+exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = void 0;
+exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpHttpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.applyPermissionMode = exports.checkAndDecide = exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return client_js_1.OryAgentClient; } });
 var logger_js_1 = require("./logger.js");
@@ -76,6 +76,11 @@ Object.defineProperty(exports, "runPermissionsCommand", { enumerable: true, get:
 Object.defineProperty(exports, "isUserIdentityCached", { enumerable: true, get: function () { return permissions_cli_js_1.isUserIdentityCached; } });
 Object.defineProperty(exports, "maybeAutoBootstrap", { enumerable: true, get: function () { return permissions_cli_js_1.maybeAutoBootstrap; } });
 Object.defineProperty(exports, "printPermissionsOnboardingHelp", { enumerable: true, get: function () { return permissions_cli_js_1.printPermissionsOnboardingHelp; } });
+var status_cli_js_1 = require("./status-cli.js");
+Object.defineProperty(exports, "runStatusCommand", { enumerable: true, get: function () { return status_cli_js_1.runStatusCommand; } });
+Object.defineProperty(exports, "printUserIdentitySection", { enumerable: true, get: function () { return status_cli_js_1.printUserIdentitySection; } });
+Object.defineProperty(exports, "printAgentIdentitySection", { enumerable: true, get: function () { return status_cli_js_1.printAgentIdentitySection; } });
+Object.defineProperty(exports, "printPermissionsSection", { enumerable: true, get: function () { return status_cli_js_1.printPermissionsSection; } });
 var setup_js_1 = require("./setup.js");
 Object.defineProperty(exports, "parseSetupArgs", { enumerable: true, get: function () { return setup_js_1.parseSetupArgs; } });
 Object.defineProperty(exports, "readJsonFile", { enumerable: true, get: function () { return setup_js_1.readJsonFile; } });

package/dist/setup.js

@@ -372,8 +372,10 @@ Options:
 
 Environment variables:
   ORY_PROJECT_URL       Your Ory project URL (required at runtime)
-  ORY_API_KEY           Ory API key (required at runtime)
-  ORY_SESSION_TOKEN     Session token for agent authentication
+  ORY_AGENT_API_KEY     Agent API key / OAuth2 bearer (preferred name;
+                        ORY_API_KEY is honored as a deprecated alias)
+  ORY_AUTH_GATE         Set to "1" to enable the interactive user login gate
+  ORY_PERMISSION_MODE   "observe" (default) or "enforce" — what to do on deny
   ORY_AGENT_DEBUG       Set to "true" for debug logging
   ORY_AGENT_LOG_FILE    Path to write debug logs
   ORY_AGENT_SUBJECT_ID  Override the subject ID for permission checks
@@ -387,12 +389,17 @@ function printNextSteps(harnessName, uninstallCmd) {
     console.log("Next steps:");
     console.log("  1. Set required environment variables:");
     console.log("     export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
-    console.log("     export ORY_API_KEY=ory_pat_...");
+    console.log("     export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
-    console.log("  2. Optionally enable debug logging:");
+    console.log("  2. Turn on the interactive user login gate (opt-in):");
+    console.log("     export ORY_AUTH_GATE=1");
+    console.log(`     Without this, ${harnessName} runs without a human Ory identity attached`);
+    console.log("     to the session and permission checks fall back to a session:<id> subject.");
+    console.log("");
+    console.log("  3. Optionally enable debug logging:");
     console.log("     export ORY_AGENT_DEBUG=true");
     console.log("");
-    console.log(`  3. Start ${harnessName} in your project directory.`);
+    console.log(`  4. Start ${harnessName} in your project directory.`);
     console.log("");
     console.log(`To uninstall: ${uninstallCmd}`);
 }

package/dist/status-cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Render the "User identity" block. Shows the `ORY_AUTH_GATE` state and,
+ * when a PKCE token is cached, the resolved subject and expiry.
+ */
+export declare function printUserIdentitySection(): void;
+/**
+ * Render the "Agent identity" block. Summarizes the resolved machine
+ * credential — static env override, persisted DCR, or unconfigured.
+ */
+export declare function printAgentIdentitySection(): void;
+/**
+ * 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`).
+ */
+export declare function printPermissionsSection(binName: string, harness: string): Promise<void>;
+export interface StatusCommandOptions {
+    /** Display title — typically the harness's human-friendly name, e.g. "Claude Code". */
+    title: string;
+    /**
+     * Optional renderer for the "Hooks & plugin" section. Each harness owns
+     * the layout for its plugin-specific registration data (extension dir,
+     * marketplace plugin ID, hook script path, etc.).
+     */
+    printPluginSection?: () => void;
+}
+/**
+ * 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 log tail.
+ *
+ * Each section degrades gracefully — missing project URL, audit-only
+ * mode, and empty token caches all surface as inline "n/a" lines rather
+ * than aborting the command.
+ */
+export declare function runStatusCommand(binName: string, harness: string, options: StatusCommandOptions): Promise<void>;

package/dist/status-cli.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printUserIdentitySection = printUserIdentitySection;
+exports.printAgentIdentitySection = printAgentIdentitySection;
+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.
+ *
+ * The drill-down commands (`agent status`, `permissions status`) remain
+ * unchanged — this composes their inputs without altering their output.
+ */
+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 agent_auth_js_2 = require("./agent-auth.js");
+const subject_js_1 = require("./subject.js");
+const tool_catalog_js_1 = require("./tool-catalog.js");
+const cli_js_1 = require("./cli.js");
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+const AUTH_GATE_ENABLED = new Set(["1", "true", "yes", "on"]);
+function isAuthGateOn() {
+    const v = process.env.ORY_AUTH_GATE?.toLowerCase();
+    return !!v && AUTH_GATE_ENABLED.has(v);
+}
+/**
+ * Format a relative duration like "4h 32m" or "12s" for a future deadline.
+ * Returns "expired" when the deadline has already passed.
+ */
+function formatExpiresIn(expiresAtSec, nowMs = Date.now()) {
+    const remaining = expiresAtSec - Math.floor(nowMs / 1000);
+    if (remaining <= 0)
+        return "expired";
+    const days = Math.floor(remaining / 86400);
+    const hours = Math.floor((remaining % 86400) / 3600);
+    const minutes = Math.floor((remaining % 3600) / 60);
+    if (days > 0)
+        return `${days}d ${hours}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return `${remaining}s`;
+}
+/**
+ * Render the "User identity" block. Shows the `ORY_AUTH_GATE` state and,
+ * when a PKCE token is cached, the resolved subject and expiry.
+ */
+function printUserIdentitySection() {
+    const gateOn = isAuthGateOn();
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    console.log("");
+    console.log("User identity (interactive PKCE login):");
+    console.log(`  Gate:        ${gateOn ? "on (ORY_AUTH_GATE)" : "off (set ORY_AUTH_GATE=1 to enable)"}`);
+    if (!tokens) {
+        console.log("  Token cache: empty");
+        if (gateOn) {
+            console.log("  Subject:     (will resolve at next session start)");
+        }
+        else {
+            console.log("  Subject:     (gate disabled — no PKCE login will run)");
+        }
+        return;
+    }
+    const expired = (0, auth_store_js_1.isExpired)(tokens);
+    if (expired) {
+        console.log(`  Token cache: stale (${formatExpiresIn(tokens.expiresAt)}) — will refresh on next session start`);
+    }
+    else {
+        console.log(`  Token cache: present (expires in ${formatExpiresIn(tokens.expiresAt)})`);
+    }
+    const subject = tokens.subject ? `user:${tokens.subject}` : "(no subject claim on cached token)";
+    console.log(`  Subject:     ${subject}`);
+    if (tokens.clientId) {
+        console.log(`  Client ID:   ${tokens.clientId}`);
+    }
+}
+/**
+ * Render the "Agent identity" block. Summarizes the resolved machine
+ * credential — static env override, persisted DCR, or unconfigured.
+ */
+function printAgentIdentitySection() {
+    console.log("");
+    console.log("Agent identity (non-interactive):");
+    // Static overrides take precedence — surface them 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;
+        console.log(`  Subject:     ${subject}`);
+        return;
+    }
+    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
+    if (!persisted) {
+        console.log("  Source:      not registered yet");
+        console.log("  Status:      first session start will register an OAuth2 client (RFC 7591)");
+        return;
+    }
+    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(`  Client ID:   ${persisted.clientId}`);
+    const subject = process.env.ORY_AGENT_SUBJECT_ID ?? persisted.clientId;
+    console.log(`  Subject:     ${subject}`);
+    console.log(`  Registered:  ${new Date(persisted.registeredAt * 1000).toISOString()}`);
+    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,
+        });
+    }
+    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";
+        }
+    }
+    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`).
+ */
+async function printPermissionsSection(binName, harness) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    const namespace = resolveNamespace();
+    const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    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;
+    }
+    if (catalog.length === 0) {
+        console.log(`  Coverage:    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_AUTH_GATE=1 once,`);
+        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");
+    if (!probe) {
+        console.log("  Coverage:    unavailable (no user identity could be resolved)");
+        return;
+    }
+    const { total, allowed, denied, errored } = probe;
+    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)`
+        : allowed === 0
+            ? `not bootstrapped (0/${total} built-in tools)`
+            : `partial (${allowed}/${total} built-in tools allowed)`;
+    console.log(`  Coverage:    ${status}`);
+    if (denied > 0) {
+        console.log(`               run "npx ${binName} permissions bootstrap" to grant the missing tools`);
+    }
+    else if (errored > 0) {
+        console.log(`               ${errored} probe error(s) — run "npx ${binName} permissions status" for details`);
+    }
+}
+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 "default":
+            return "  (default)";
+    }
+}
+/**
+ * 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 log tail.
+ *
+ * Each section degrades gracefully — missing project URL, audit-only
+ * mode, and empty token caches all surface as inline "n/a" lines rather
+ * than aborting the command.
+ */
+async function runStatusCommand(binName, harness, options) {
+    const heading = `Ory Agent Plugin Status (${options.title})`;
+    console.log(heading);
+    console.log("=".repeat(heading.length));
+    console.log("");
+    (0, cli_js_1.printOryConfig)();
+    printUserIdentitySection();
+    printAgentIdentitySection();
+    await printPermissionsSection(binName, harness);
+    if (options.printPluginSection) {
+        console.log("");
+        options.printPluginSection();
+    }
+    (0, cli_js_1.printEnvironment)();
+    (0, cli_js_1.printLogTail)();
+    console.log("");
+    console.log(`Drill into any section with:`);
+    console.log(`  npx ${binName} agent status`);
+    console.log(`  npx ${binName} permissions status`);
+    console.log(`  npx ${binName} configure`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -69,7 +69,7 @@
     "open": "^11.0.0"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc",