@ory/argus 0.2.0 → 0.3.0

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/dev.js

@@ -485,7 +485,7 @@ async function bootstrapLocalOry(localDir) {
         return { active: false };
     }
     console.log(`[ory-dev] Local Ory: agent ${seed.agent.identity.email}, user ${seed.user.identity.email}, ` +
-        `${seed.permissions.tuples} permission tuples in '${namespace}' for ${seed.permissions.subject}.`);
+        `${seed.permissions.tuples} permissions in '${namespace}' for ${seed.permissions.subject}.`);
     return { active: true, gatewayUrl, seed };
 }
 /**

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";
@@ -14,7 +14,7 @@ export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./
 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/local/cli.js

@@ -63,7 +63,7 @@ Commands:
   up [--no-seed]     Start local Ory services (Kratos, Keto, Hydra, gateway)
   down               Stop all local services (preserves data)
   status             Show service health and container states
-  seed               Create test identity, session, and permission tuples
+  seed               Create test identity, session, and permissions
   logs [service] [-f]  View service logs (optionally follow, optionally filter)
   reset              Stop services and remove all data
   env                Print environment variables for connecting to local services

package/dist/local/manager.js

@@ -642,7 +642,7 @@ function printSeedResult(result) {
     console.log(`  User password:  ${result.user.password}`);
     console.log(`  User OAuth2:    ${result.user.client.clientId} (PKCE)`);
     console.log("");
-    console.log(`  Permissions: ${result.permissions.tuples} tuples in '${result.permissions.namespace}' for ${result.permissions.subject}`);
+    console.log(`  Permissions: ${result.permissions.tuples} entries in '${result.permissions.namespace}' for ${result.permissions.subject}`);
     console.log("");
     console.log("To use with any Ory agent plugin, set these environment variables:");
     console.log("");

package/dist/local/seed.js

@@ -110,7 +110,7 @@ async function seedPermissions(userId, namespace) {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             if (!msg.includes("409")) {
-                process.stderr.write(`  Warning: failed to create tuple for ${tool}: ${msg}\n`);
+                process.stderr.write(`  Warning: failed to create permission for ${tool}: ${msg}\n`);
             }
             else {
                 created++;
@@ -185,9 +185,9 @@ async function seedLocalEnvironment(namespace = "AgentTools") {
     //    Subject is a SubjectSet `User:<id>` so the Console UI can rewrite
     //    the same tuple shape by hand during the runbook demo.
     const subjectLabel = `${exports.USER_SUBJECT_NAMESPACE}:${userIdentity.id}`;
-    process.stderr.write(`  Creating permission tuples for ${COMMON_TOOLS.length} tools...\n`);
+    process.stderr.write(`  Creating permissions for ${COMMON_TOOLS.length} tools...\n`);
     const tupleCount = await seedPermissions(userIdentity.id, namespace);
-    process.stderr.write(`  Permissions: ${tupleCount} tuples in '${namespace}' for ${subjectLabel}\n`);
+    process.stderr.write(`  Permissions: ${tupleCount} entries in '${namespace}' for ${subjectLabel}\n`);
     // 3. User OAuth2 client (PKCE) — pre-registered so the user gate's
     //    PKCE flow has somewhere to authenticate against. The agent's
     //    OAuth2 client is intentionally NOT pre-registered; the harness

package/dist/permissions-cli.js

@@ -84,7 +84,7 @@ function printPermissionsHelp(binName) {
     console.log("");
     console.log("Subcommands:");
     console.log("  status      Show permission mode and tool coverage for the current user");
-    console.log("  bootstrap   Write 'use' tuples for the harness's built-in tools (idempotent)");
+    console.log("  bootstrap   Grant the current user 'use' on every built-in tool (idempotent)");
     console.log("  observe     Switch to observe mode (denies log but don't block)");
     console.log("  enforce     Switch to enforce mode (denies block — production posture)");
     console.log("");
@@ -104,7 +104,7 @@ function runPermissionsSetMode(binName, mode) {
         console.log("Denies will be logged and recorded as `permission.observe_deny` spans,");
         console.log("but tools will be allowed through. Run");
         console.log(`  ${binName} permissions enforce`);
-        console.log("once your tuple set is correct.");
+        console.log("once your permission set is correct.");
     }
     else {
         console.log("Denies will block tool execution. The plugin is now enforcing.");
@@ -121,9 +121,10 @@ async function runPermissionsStatus(binName, harness) {
     console.log(`Permission status (${harness})`);
     console.log("==========================================");
     console.log("");
-    console.log(`Mode:           ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
+    console.log(`Mode:           ${resolved.permissionMode}${formatModeSource(resolved.permissionModeSource)}`);
+    console.log(`  (other modes: ${otherModes(resolved.permissionMode).join(", ")})`);
     console.log(`Namespace:      ${namespace}`);
-    console.log(`Project URL:    ${resolved.projectUrl ?? "(not set)"} [source: ${resolved.projectUrlSource}]`);
+    console.log(`Project URL:    ${resolved.projectUrl ?? "(not set)"}${formatSourceSuffix(resolved.projectUrlSource)}`);
     console.log(`Audit-only:     ${resolved.auditOnly ? "yes (Ory disabled)" : "no"}`);
     console.log("");
     if (resolved.auditOnly) {
@@ -132,7 +133,7 @@ async function runPermissionsStatus(binName, harness) {
         return 0;
     }
     if (!resolved.projectUrl) {
-        console.log("No project URL configured — cannot probe tuple coverage.");
+        console.log("No project URL configured — cannot probe permission coverage.");
         console.log(`Configure first: ${binName} configure --project-url <URL> --api-key <KEY>`);
         return 0;
     }
@@ -214,7 +215,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
         return 1;
     }
     if (!resolved.projectUrl) {
-        console.error("No ORY_PROJECT_URL configured — cannot write tuples.");
+        console.error("No ORY_PROJECT_URL configured — cannot write permissions.");
         console.error(`Configure first: ${binName} configure --project-url <URL> --api-key <KEY>`);
         return 1;
     }
@@ -231,14 +232,14 @@ async function runPermissionsBootstrap(binName, harness, args) {
     const subject = (0, subject_js_1.resolveUserSubject)(client);
     const subjectId = (0, subject_js_1.subjectLabel)(subject);
     if (subjectId === "agent:unknown") {
-        console.error("No user identity resolved — refusing to write tuples to an unknown subject.");
+        console.error("No user identity resolved — refusing to write permissions for an unknown subject.");
         console.error("");
         console.error("Either:");
         console.error("  - run the harness once with ORY_AUTH_GATE=1 so a user token is cached, or");
         console.error("  - set ORY_USER_SUBJECT_ID=<id> to target a known subject.");
         return 1;
     }
-    console.log(`Bootstrapping ${catalog.length} permission tuples for ${harness}`);
+    console.log(`Bootstrapping ${catalog.length} permissions for ${harness}`);
     console.log("==========================================");
     console.log("");
     console.log(`Namespace: ${namespace}`);
@@ -246,7 +247,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
     console.log(`Tools:     ${catalog.join(", ")}`);
     if (dryRun) {
         console.log("");
-        console.log("(--dry-run) No tuples will be written.");
+        console.log("(--dry-run) No permissions will be written.");
     }
     console.log("");
     let created = 0;
@@ -285,7 +286,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
     }
     console.log("");
     if (dryRun) {
-        console.log(`Dry run: ${catalog.length} tuples would be written.`);
+        console.log(`Dry run: ${catalog.length} permissions would be written.`);
         return 0;
     }
     console.log(`Created: ${created}    Already existed: ${existed}    Failed: ${failures.length}`);
@@ -296,7 +297,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
             console.log("");
             console.log("Some writes were rejected — your current credentials may lack");
             console.log("write scope on the permission namespace. You can apply the");
-            console.log("tuples manually using the snippet below (one tuple per line):");
+            console.log("permissions manually using the snippet below (one per line):");
             console.log("");
             for (const tool of catalog) {
                 console.log(`  ${namespace}:${tool}#use@${subjectId}`);
@@ -309,7 +310,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
         return failures.length === catalog.length ? 1 : 0;
     }
     console.log("");
-    console.log(`Permission tuples are in place. Promote to enforce mode when ready:`);
+    console.log(`Permissions are in place. Promote to enforce mode when ready:`);
     console.log(`  ${binName} permissions enforce`);
     return 0;
 }
@@ -342,21 +343,22 @@ function printPermissionsOnboardingHelp(binName, harness, opts = {}) {
     const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
     console.log("");
     console.log("Permissions:");
-    console.log(`  Mode: ${resolved.permissionMode}  [source: ${resolved.permissionModeSource}]`);
+    console.log(`  Mode: ${resolved.permissionMode}${formatModeSource(resolved.permissionModeSource)}`);
+    console.log(`  Other modes: ${otherModes(resolved.permissionMode).join(", ")}`);
     if (resolved.auditOnly) {
         console.log("  Ory is in audit-only mode (kill switch). Permission checks are disabled.");
         return;
     }
     if (resolved.permissionMode === "observe") {
         console.log("  Observe mode: permission denies are logged + traced, but tools still run.");
-        console.log("  This is the safe default — promote once your tuple set is correct.");
+        console.log("  This is the safe default — promote to 'enforce' once your permission set is correct.");
     }
     else {
         console.log("  Enforce mode: permission denies block tool execution.");
     }
     if (opts.bootstrappedAutomatically) {
         console.log("");
-        console.log(`  Tuples bootstrapped for ${catalog.length} built-in tools.`);
+        console.log(`  Permissions bootstrapped for ${catalog.length} built-in tools.`);
     }
     else if (catalog.length > 0) {
         console.log("");
@@ -364,12 +366,52 @@ function printPermissionsOnboardingHelp(binName, harness, opts = {}) {
         console.log(`    npx ${binName} permissions bootstrap`);
     }
     console.log("");
-    console.log("  Inspect tuple coverage:");
+    console.log("  Inspect permission coverage:");
     console.log(`    npx ${binName} permissions status`);
     console.log("");
     console.log("  Promote to enforcing once observe-mode logs look right:");
     console.log(`    npx ${binName} permissions enforce`);
 }
+/**
+ * Render the trailing source annotation on a Mode line. Stays silent
+ * when the mode came from the built-in default, since saying "default"
+ * just adds noise. When the mode was overridden by env or config, name
+ * the override so the reader knows where to look.
+ */
+function formatModeSource(source) {
+    switch (source) {
+        case "env":
+            return `  (set via ${ENV_PERMISSION_MODE} env var)`;
+        case "config":
+            return "  (saved in config; change with: permissions observe|enforce)";
+        case "default":
+            return "  (built-in default)";
+    }
+}
+/**
+ * Generic source-suffix helper for other config fields (project URL,
+ * API key). Source 'none' means the value is unset — don't add a suffix.
+ */
+function formatSourceSuffix(source) {
+    switch (source) {
+        case "env":
+            return "  (from env)";
+        case "config":
+            return "  (from config)";
+        case "none":
+            return "";
+    }
+}
+/**
+ * Lists the modes other than the active one, in stable order, so the
+ * banner can hint "Other modes: …" without re-listing the active one.
+ * Audit-only is a separate kill switch (config.auditOnly), but we still
+ * mention it here so first-time readers learn the full set.
+ */
+function otherModes(active) {
+    const all = ["observe", "enforce", "audit-only"];
+    return all.filter((m) => m !== active);
+}
 /**
  * If a user identity is already cached and the plugin is configured,
  * opportunistically run `permissions bootstrap` so the user lands in a
@@ -391,7 +433,7 @@ async function maybeAutoBootstrap(binName, harness) {
         return false;
     try {
         console.log("");
-        console.log("Bootstrapping permission tuples (cached user identity detected)...");
+        console.log("Bootstrapping permissions (cached user identity detected)...");
         const code = await runPermissionsCommand(binName, harness, ["bootstrap"]);
         return code === 0;
     }

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/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.0",
+  "version": "0.3.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",