@ory/argus 0.2.1 → 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/client.js

@@ -38,6 +38,11 @@ class OryAgentClient {
             traceFile: config.traceFile,
             ...(config.exporter ? { exporter: config.exporter } : {}),
         });
+        // 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)

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

@@ -1,6 +1,6 @@
 export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, } from "./client.js";
 export { DebugLogger, redactLogData, type LogEntry, type LogLevel, } from "./logger.js";
-export { Tracer, ActiveSpan, deriveTraceId, formatSpan, watchTraceFile, type TraceEvent, type SpanStatus, type TraceSpan, type SpanOptions, type TracerOptions, type TracerContext, } from "./tracer.js";
+export { Tracer, ActiveSpan, deriveTraceId, formatSpan, watchTraceFile, type TraceEvent, type SpanStatus, type TraceSpan, type SpanOptions, type TracerOptions, type TracerContext, type SpanAttributeEnricher, } from "./tracer.js";
 export { loadConfig, saveConfig, resolveConfig, mutateConfig, getConfigPath, getDataDir, getHarnessDataDir, type OryPluginConfig, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, type PermissionMode, } from "./config.js";
 export { pkceLogin, refreshAccessToken, detectHeadless, generateCodeVerifier, sha256Base64Url, buildAuthorizeUrl, LOOPBACK_PORTS, DEFAULT_LOGIN_TIMEOUT_MS, type PkceLoginOptions, type PkceLoginOutcome, type PkceDeclineReason, } from "./auth.js";
 export { loadTokens, saveTokens, clearTokens, isExpired, refreshAndSave, tryAcquirePkceFlightLock, clearPkceFlightLock, waitForPeerTokens, waitForPeerTokensSync, TOKEN_EXPIRY_SKEW_SEC, type PkceFlightLock, } from "./auth-store.js";
@@ -9,12 +9,13 @@ 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";
 export { runLocalCommand, ensureDevJaeger, stopDevJaeger, DEV_JAEGER_CONTAINER, type EnsureDevJaegerResult, type StopDevJaegerResult, } from "./local/index.js";
 export { runRegistryCommand } from "./registry/index.js";
-export { checkAndDecide, applyPermissionMode, type PermissionDecision, type ModeDecision, type CheckAndDecideOptions, type ApplyPermissionModeContext, } from "./permissions.js";
+export { checkAndDecide, applyPermissionMode, type PermissionDecision, type ModeDecision, type DecisionSpanAttributes, type CheckAndDecideOptions, type ApplyPermissionModeContext, } from "./permissions.js";
 export { HARNESS_TOOL_CATALOG, KNOWN_HARNESSES, ALL_TOOLS, getToolCatalog, type KnownHarness, } from "./tool-catalog.js";
 export { parseClaudeCodeMcpTool, parseGeminiMcpTool, parseMcpToolGeneric, checkMcpPermission, type McpToolIdentifier, type McpPermissionCheckOptions, type McpPermissionResult, } from "./mcp.js";
 export { resolveUserSubject, subjectLabel, type UserSubjectRef, } from "./subject.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/permissions.d.ts

@@ -23,22 +23,40 @@
 import type { OryAgentClient } from "./client.js";
 import { type PermissionMode } from "./config.js";
 import type { OryError, PermissionCheck, PermissionResult } from "./types.js";
+/**
+ * Attributes describing *what was checked* and *under which posture*.
+ * Plugins spread this onto their `tool.invoke` / `tool.block` spans so
+ * the audit trail makes the observe-vs-enforce posture and the checked
+ * subject visible at a glance — without that, a span with `allowed=false`
+ * status=ok is ambiguous (observe pass-through? fail-open? bug?).
+ */
+export interface DecisionSpanAttributes {
+    permissionMode: PermissionMode;
+    /** Direct subject ID when the check used `subjectId`. */
+    subjectId?: string;
+    /** SubjectSet rendered as `<namespace>:<object>#<relation>` when used. */
+    subjectSet?: string;
+}
 export type PermissionDecision = {
     kind: "allow";
     result: PermissionResult;
     mode: PermissionMode;
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "deny";
     result: PermissionResult;
     mode: "enforce";
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "observe";
     result: PermissionResult;
     mode: "observe";
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "fail_open";
     error: OryError;
     mode: PermissionMode;
+    spanAttributes: DecisionSpanAttributes;
 };
 /**
  * The "what should the caller do?" half of a decision, independent of
@@ -49,12 +67,15 @@ export type PermissionDecision = {
 export type ModeDecision = {
     kind: "allow";
     mode: PermissionMode;
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "deny";
     mode: "enforce";
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "observe";
     mode: "observe";
+    spanAttributes: DecisionSpanAttributes;
 };
 export interface CheckAndDecideOptions {
     /**
@@ -81,6 +102,8 @@ export interface ApplyPermissionModeContext {
     relation?: string;
     /** Subject ID for the observe-deny log line, if available. */
     subjectId?: string;
+    /** SubjectSet for the observe-deny log line, if available. */
+    subjectSet?: PermissionCheck["subjectSet"];
     /** Attributes merged into the `permission.observe_deny` span. */
     spanAttributes?: Record<string, unknown>;
     /** Override the resolved mode (tests). */

package/dist/permissions.js

@@ -25,6 +25,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyPermissionMode = applyPermissionMode;
 exports.checkAndDecide = checkAndDecide;
 const config_js_1 = require("./config.js");
+function formatSubjectSet(set) {
+    if (!set)
+        return undefined;
+    return `${set.namespace}:${set.object}#${set.relation}`;
+}
+function buildDecisionAttributes(mode, subjectId, subjectSet) {
+    const set = formatSubjectSet(subjectSet);
+    // SubjectSet supersedes subjectId in the span (the printable label is
+    // derivable from it); avoid emitting both so consumers don't need to
+    // dedupe.
+    if (set)
+        return { permissionMode: mode, subjectSet: set };
+    if (subjectId)
+        return { permissionMode: mode, subjectId };
+    return { permissionMode: mode };
+}
 /**
  * Map an `allowed` boolean from any permission check (plain or MCP)
  * onto a {@link ModeDecision}. When `allowed === false` and the mode
@@ -34,14 +50,16 @@ const config_js_1 = require("./config.js");
  */
 function applyPermissionMode(client, allowed, context = {}) {
     const mode = context.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
+    const spanAttributes = buildDecisionAttributes(mode, context.subjectId, context.subjectSet);
     if (allowed)
-        return { kind: "allow", mode };
+        return { kind: "allow", mode, spanAttributes };
     if (mode === "observe") {
         client.logger.warn("permission.observe_deny", {
             namespace: context.namespace,
             object: context.object,
             relation: context.relation,
             subjectId: context.subjectId,
+            subjectSet: spanAttributes.subjectSet,
             note: "denied by Ory; allowed by plugin in observe mode",
         });
         client.tracer.record("permission.observe_deny", "denied", {
@@ -49,13 +67,13 @@ function applyPermissionMode(client, allowed, context = {}) {
                 namespace: context.namespace,
                 object: context.object,
                 relation: context.relation,
-                mode,
+                ...spanAttributes,
                 ...context.spanAttributes,
             },
         });
-        return { kind: "observe", mode: "observe" };
+        return { kind: "observe", mode: "observe", spanAttributes };
     }
-    return { kind: "deny", mode: "enforce" };
+    return { kind: "deny", mode: "enforce", spanAttributes };
 }
 /**
  * Run a permission check and resolve the configured mode against the
@@ -64,6 +82,7 @@ function applyPermissionMode(client, allowed, context = {}) {
  */
 async function checkAndDecide(client, check, opts = {}) {
     const mode = opts.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
+    const spanAttributes = buildDecisionAttributes(mode, check.subjectId, check.subjectSet);
     let result;
     try {
         result = await client.checkPermission(check, {
@@ -71,19 +90,20 @@ async function checkAndDecide(client, check, opts = {}) {
         });
     }
     catch (err) {
-        return { kind: "fail_open", error: err, mode };
+        return { kind: "fail_open", error: err, mode, spanAttributes };
     }
     const inner = applyPermissionMode(client, result.allowed, {
         namespace: check.namespace,
         object: check.object,
         relation: check.relation,
         subjectId: check.subjectId,
+        subjectSet: check.subjectSet,
         spanAttributes: opts.spanAttributes,
         modeOverride: opts.modeOverride,
     });
     if (inner.kind === "allow")
-        return { kind: "allow", result, mode: inner.mode };
+        return { kind: "allow", result, mode: inner.mode, spanAttributes: inner.spanAttributes };
     if (inner.kind === "observe")
-        return { kind: "observe", result, mode: "observe" };
-    return { kind: "deny", result, mode: "enforce" };
+        return { kind: "observe", result, mode: "observe", spanAttributes: inner.spanAttributes };
+    return { kind: "deny", result, mode: "enforce", spanAttributes: inner.spanAttributes };
 }

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/dist/tracer.d.ts

@@ -99,6 +99,14 @@ export interface ProcessMetadata {
     gitBranch?: string;
     gitCommit?: string;
 }
+/**
+ * Returns a record of attributes to merge into every span's attribute
+ * bag at span-end. Used by `OryAgentClient` to inject the current
+ * `userSubject` / `agentSubject` onto every span without each handler
+ * having to remember to attach them. Must not throw and should be cheap;
+ * it is invoked on every span.
+ */
+export type SpanAttributeEnricher = () => Record<string, unknown> | undefined;
 export declare class Tracer extends EventEmitter {
     readonly harness: string;
     readonly processMetadata: ProcessMetadata;
@@ -106,6 +114,7 @@ export declare class Tracer extends EventEmitter {
     private readonly _spans;
     private _context;
     private _exporter;
+    private _enricher;
     constructor(opts: TracerOptions);
     /** Backwards-compatible accessors for the most common metadata fields. */
     get hostname(): string;
@@ -135,6 +144,15 @@ export declare class Tracer extends EventEmitter {
      */
     setExporter(exporter: SpanExporter | null): void;
     get exporter(): SpanExporter | null;
+    /**
+     * Install (or replace) an attribute enricher. The enricher is invoked
+     * on every span at end-time and its return value is merged into the
+     * span's attributes (with caller-supplied attributes taking precedence).
+     * Pass `null` to clear.
+     */
+    setAttributeEnricher(enricher: SpanAttributeEnricher | null): void;
+    /** @internal — invoked by `ActiveSpan.end()`. Never throws. */
+    _callEnricher(): Record<string, unknown> | undefined;
     /**
      * Flush any pending exports. Call before the host process exits so
      * the OTLP HTTP request has a chance to complete.

package/dist/tracer.js

@@ -98,8 +98,12 @@ class ActiveSpan {
         }
         this._ended = true;
         const durationMs = Math.round(performance.now() - this.startMs);
-        const merged = this.baseAttributes || attributes
-            ? { ...this.baseAttributes, ...attributes }
+        // Pull enricher attributes (e.g. userSubject / agentSubject from the
+        // client's principals) at span-end so every span gets them, including
+        // direct `tracer.record(...)` calls from plugin handlers.
+        const enriched = this.tracer._callEnricher();
+        const merged = enriched || this.baseAttributes || attributes
+            ? { ...enriched, ...this.baseAttributes, ...attributes }
             : undefined;
         const meta = this.tracer.processMetadata;
         const span = {
@@ -137,6 +141,7 @@ class Tracer extends node_events_1.EventEmitter {
     _spans = [];
     _context = {};
     _exporter;
+    _enricher = null;
     constructor(opts) {
         super();
         this.harness = opts.harness;
@@ -212,6 +217,30 @@ class Tracer extends node_events_1.EventEmitter {
     get exporter() {
         return this._exporter;
     }
+    /**
+     * Install (or replace) an attribute enricher. The enricher is invoked
+     * on every span at end-time and its return value is merged into the
+     * span's attributes (with caller-supplied attributes taking precedence).
+     * Pass `null` to clear.
+     */
+    setAttributeEnricher(enricher) {
+        this._enricher = enricher;
+    }
+    /** @internal — invoked by `ActiveSpan.end()`. Never throws. */
+    _callEnricher() {
+        if (!this._enricher)
+            return undefined;
+        try {
+            const out = this._enricher();
+            if (!out || Object.keys(out).length === 0)
+                return undefined;
+            return out;
+        }
+        catch {
+            // Enricher contract: never throw. Swallow defensively.
+            return undefined;
+        }
+    }
     /**
      * Flush any pending exports. Call before the host process exits so
      * the OTLP HTTP request has a chance to complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.2.1",
+  "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",