@ory/argus 0.13.7 → 0.13.9

package/dist/adapters.d.ts

@@ -43,6 +43,14 @@ export interface SessionStartOptions {
  * user gate still runs, refreshes tokens, and records the `user.auth` span.
  */
 export declare function sessionStart(client: OryAgentClient, opts: SessionStartOptions): Promise<SessionStartResult>;
+/**
+ * Write the `user → agent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that run
+ * their own session-start sequence (rather than {@link sessionStart}) share
+ * the same write-once semantics instead of re-issuing the write every
+ * session. No-op until both principals are populated.
+ */
+export declare function writeUserDelegatesAgent(client: OryAgentClient): Promise<void>;
 export interface RegisterSubagentOptions {
     harness: string;
     subAgentType: string;
@@ -50,6 +58,14 @@ export interface RegisterSubagentOptions {
     subAgentGate?: typeof ensureSubAgentIdentity;
 }
 export declare function registerSubagent(client: OryAgentClient, opts: RegisterSubagentOptions): Promise<void>;
+/**
+ * Write the `agent → subagent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that
+ * resolve the sub-agent identity through their own event plumbing (rather
+ * than {@link registerSubagent}) still share the write-once semantics.
+ * No-op until the agent principal is populated.
+ */
+export declare function writeAgentDelegatesSubagent(client: OryAgentClient, subAgentSubject: string, subAgentType: string): Promise<void>;
 export interface GateResult {
     /** False only when the tool was hard-denied in enforce mode. */
     proceed: boolean;

package/dist/adapters.js

@@ -21,7 +21,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveNamespace = resolveNamespace;
 exports.sessionStart = sessionStart;
+exports.writeUserDelegatesAgent = writeUserDelegatesAgent;
 exports.registerSubagent = registerSubagent;
+exports.writeAgentDelegatesSubagent = writeAgentDelegatesSubagent;
 exports.gate = gate;
 exports.complete = complete;
 exports.wrapTool = wrapTool;
@@ -52,7 +54,7 @@ async function sessionStart(client, opts) {
         projectUrl,
         harness: opts.harness,
     });
-    await recordUserDelegatesAgent(client);
+    await writeUserDelegatesAgent(client);
     return {
         proceed: decision.proceed,
         userMode: decision.mode,
@@ -60,25 +62,63 @@ async function sessionStart(client, opts) {
         agentKind: creds.kind,
     };
 }
-async function recordUserDelegatesAgent(client) {
-    const user = client.userPrincipal.subject;
-    const agent = client.agentPrincipal.subject;
-    if (!user || !agent)
-        return;
+/**
+ * Write a delegation tuple at most once. The tuple is stable for a given
+ * (namespace, object, subject), and Keto's create API is not idempotent, so
+ * this goes through {@link OryAgentClient.ensureRelationship}: it reads the
+ * exact tuple first and only writes when absent — no duplicate on repeated
+ * session starts, and self-healing if the tuple was deleted. If the existence
+ * probe fails we skip the write rather than risk a duplicate (delegation
+ * tuples are audit-only, so a missed write is harmless and retried next
+ * session). Best-effort: any failure is logged and swallowed.
+ */
+async function writeDelegationOnce(client, check, options) {
     try {
-        await client.createRelationship({
-            namespace: resolveNamespace(),
-            object: `agent:${agent}`,
-            relation: "delegate",
-            subjectId: `user:${user}`,
-        }, { spanAttributes: { delegation: "user-to-agent" } });
+        const res = await client.ensureRelationship(check, {
+            spanAttributes: options.spanAttributes,
+        });
+        if (res.probeError) {
+            client.logger.debug("delegation.probe_failed", {
+                ...options.failedContext,
+                message: res.probeError.message,
+            });
+        }
     }
     catch (err) {
-        client.logger.warn("delegation.user_to_agent.failed", {
+        client.logger.warn(options.failedEvent, {
+            ...options.failedContext,
             message: err instanceof Error ? err.message : String(err),
         });
     }
 }
+/**
+ * Write the `user → agent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that run
+ * their own session-start sequence (rather than {@link sessionStart}) share
+ * the same write-once semantics instead of re-issuing the write every
+ * session. No-op until both principals are populated.
+ */
+async function writeUserDelegatesAgent(client) {
+    const user = client.userPrincipal.subject;
+    const agent = client.agentPrincipal.subject;
+    if (!user || !agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "missing principal",
+            hasUser: !!user,
+            hasAgent: !!agent,
+        });
+        return;
+    }
+    await writeDelegationOnce(client, {
+        namespace: resolveNamespace(),
+        object: `agent:${agent}`,
+        relation: "delegate",
+        subjectId: `user:${user}`,
+    }, {
+        spanAttributes: { delegation: "user-to-agent" },
+        failedEvent: "delegation.user_to_agent.failed",
+    });
+}
 async function registerSubagent(client, opts) {
     const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
     const subAgentGate = opts.subAgentGate ?? agent_auth_js_1.ensureSubAgentIdentity;
@@ -99,23 +139,34 @@ async function registerSubagent(client, opts) {
     }
     if (identity.kind !== "dynamic" || !identity.subject)
         return;
+    await writeAgentDelegatesSubagent(client, identity.subject, opts.subAgentType);
+}
+/**
+ * Write the `agent → subagent` delegation tuple, at most once per install
+ * (see {@link writeDelegationOnce}). Exported so harness plugins that
+ * resolve the sub-agent identity through their own event plumbing (rather
+ * than {@link registerSubagent}) still share the write-once semantics.
+ * No-op until the agent principal is populated.
+ */
+async function writeAgentDelegatesSubagent(client, subAgentSubject, subAgentType) {
     const agent = client.agentPrincipal.subject;
-    if (!agent)
-        return;
-    try {
-        await client.createRelationship({
-            namespace: resolveNamespace(),
-            object: `subagent:${identity.subject}`,
-            relation: "delegate",
-            subjectId: `agent:${agent}`,
-        }, { spanAttributes: { delegation: "agent-to-subagent", subAgentType: opts.subAgentType } });
-    }
-    catch (err) {
-        client.logger.warn("delegation.agent_to_subagent.failed", {
-            subAgentType: opts.subAgentType,
-            message: err instanceof Error ? err.message : String(err),
+    if (!agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "agent principal not populated",
+            subAgentType,
         });
+        return;
     }
+    await writeDelegationOnce(client, {
+        namespace: resolveNamespace(),
+        object: `subagent:${subAgentSubject}`,
+        relation: "delegate",
+        subjectId: `agent:${agent}`,
+    }, {
+        spanAttributes: { delegation: "agent-to-subagent", subAgentType },
+        failedEvent: "delegation.agent_to_subagent.failed",
+        failedContext: { subAgentType },
+    });
 }
 /**
  * Authorize a tool call, record the spans, and return a normalized {@link GateResult}.

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "repo": "ory-agent-plugins",
-  "commit": "badfe6ff1166227b0eefaeb54018482631e0ce7b",
-  "commitShort": "badfe6f",
+  "commit": "f7663bf2a792378be5a94c7d6bb0d6671e1da6a9",
+  "commitShort": "f7663bf",
   "branch": "main",
-  "commitDate": "2026-07-15T11:49:39-07:00",
+  "commitDate": "2026-07-15T15:56:35-07:00",
   "dirty": false,
-  "builtAt": "2026-07-15T18:53:45.680Z"
+  "builtAt": "2026-07-15T23:00:39.070Z"
 }

package/dist/client.d.ts

@@ -159,6 +159,37 @@ export declare class OryAgentClient {
         created: boolean;
         alreadyExisted: boolean;
     }>;
+    /**
+     * True if the *exact* relation tuple already exists in Keto. Queries the
+     * relation-tuple listing API filtered by the tuple's own coordinates
+     * (namespace/object/relation + subject), so — unlike `checkPermission` —
+     * it does not follow subject-set expansion: it answers "is this literal
+     * tuple stored?", not "does this permission resolve?". Throws a classified
+     * {@link OryError} if the query itself fails.
+     */
+    relationshipExists(check: PermissionCheck): Promise<boolean>;
+    /**
+     * Idempotent relationship write. Keto's create API is **not** idempotent —
+     * `PUT /admin/relation-tuples` inserts a fresh row on every call (each with
+     * a new primary key) and never returns 409, so calling `createRelationship`
+     * on repeated bootstraps / session starts accumulates duplicate tuples.
+     * This reads the exact tuple first (via {@link relationshipExists}) and only
+     * writes when it is absent — which also self-heals if the tuple was deleted
+     * out of band.
+     *
+     * If the existence probe itself fails, the tuple is left untouched (we do
+     * not write blind, to avoid re-introducing duplicates when the read path is
+     * misbehaving) and the classified error is returned as `probeError`. Callers
+     * that must guarantee the grant exists (e.g. install-time bootstrap) can
+     * fall back to {@link createRelationship} when `probeError` is set.
+     */
+    ensureRelationship(check: PermissionCheck, options?: {
+        spanAttributes?: Record<string, unknown>;
+    }): Promise<{
+        created: boolean;
+        alreadyExisted: boolean;
+        probeError?: OryError;
+    }>;
     /**
      * Delete a relation tuple in Keto. Missing tuples (404) are treated as
      * success so callers can call this idempotently when unwinding state.

package/dist/client.js

@@ -551,6 +551,64 @@ class OryAgentClient {
             throw oryErr;
         }
     }
+    /**
+     * True if the *exact* relation tuple already exists in Keto. Queries the
+     * relation-tuple listing API filtered by the tuple's own coordinates
+     * (namespace/object/relation + subject), so — unlike `checkPermission` —
+     * it does not follow subject-set expansion: it answers "is this literal
+     * tuple stored?", not "does this permission resolve?". Throws a classified
+     * {@link OryError} if the query itself fails.
+     */
+    async relationshipExists(check) {
+        try {
+            const response = await this.relationship.getRelationships({
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                ...(check.subjectId ? { subjectId: check.subjectId } : {}),
+                ...(check.subjectSet
+                    ? {
+                        subjectSetNamespace: check.subjectSet.namespace,
+                        subjectSetObject: check.subjectSet.object,
+                        subjectSetRelation: check.subjectSet.relation,
+                    }
+                    : {}),
+                pageSize: 1,
+            });
+            const tuples = response.data?.relation_tuples ?? [];
+            return tuples.length > 0;
+        }
+        catch (err) {
+            throw this.classifyError(err);
+        }
+    }
+    /**
+     * Idempotent relationship write. Keto's create API is **not** idempotent —
+     * `PUT /admin/relation-tuples` inserts a fresh row on every call (each with
+     * a new primary key) and never returns 409, so calling `createRelationship`
+     * on repeated bootstraps / session starts accumulates duplicate tuples.
+     * This reads the exact tuple first (via {@link relationshipExists}) and only
+     * writes when it is absent — which also self-heals if the tuple was deleted
+     * out of band.
+     *
+     * If the existence probe itself fails, the tuple is left untouched (we do
+     * not write blind, to avoid re-introducing duplicates when the read path is
+     * misbehaving) and the classified error is returned as `probeError`. Callers
+     * that must guarantee the grant exists (e.g. install-time bootstrap) can
+     * fall back to {@link createRelationship} when `probeError` is set.
+     */
+    async ensureRelationship(check, options) {
+        let exists;
+        try {
+            exists = await this.relationshipExists(check);
+        }
+        catch (err) {
+            return { created: false, alreadyExisted: false, probeError: err };
+        }
+        if (exists)
+            return { created: false, alreadyExisted: true };
+        return this.createRelationship(check, options);
+    }
     /**
      * Delete a relation tuple in Keto. Missing tuples (404) are treated as
      * success so callers can call this idempotently when unwinding state.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, } from "./client.js";
-export { DebugLogger, redactLogData, type LogEntry, type LogLevel, } from "./logger.js";
+export { DebugLogger, redactLogData, withQuietStderr, 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, 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";
@@ -27,4 +27,4 @@ export { resolveUserSubject, runWithUserSubject, subjectLabel, type UserSubjectR
 export { formatDenialMessage, formatDenialSummary, formatAlertMessage, formatAlertSummary, alertAttributes, OryDenialError, type DenialContext, type AlertAttributes, } from "./denial.js";
 export { summarizeToolInput, summarizeToolOutput, type ToolInputSummary, type ToolOutputSummary, } from "./tool-metadata.js";
 export { OtlpExporter, otlpExporterFromEnv, parseKeyValueList, type SpanExporter, type OtlpExporterOptions, type OtlpProtocol, } from "./otel/index.js";
-export { resolveNamespace, sessionStart, gate, complete, registerSubagent, wrapTool, type SessionStartResult, type SessionStartOptions, type RegisterSubagentOptions, type GateResult, type GateOptions, type WrapToolOptions, } from "./adapters.js";
+export { resolveNamespace, sessionStart, gate, complete, registerSubagent, writeUserDelegatesAgent, writeAgentDelegatesSubagent, wrapTool, type SessionStartResult, type SessionStartOptions, type RegisterSubagentOptions, type GateResult, type GateOptions, type WrapToolOptions, } from "./adapters.js";

package/dist/index.js

@@ -1,14 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runConfigureCommand = exports.clearCredentialsForUninstall = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.revokeAgentDynamicClient = 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.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.emitDeferredNextSteps = exports.beginDeferNextSteps = exports.nextStepsSink = 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.resolveBuildInfo = exports.collectVersionInfo = exports.runVersionCommand = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.LOOPBACK_REDIRECT_URIS = exports.projectUrlFromSlug = exports.runPostInstall = exports.runInteractiveSetup = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.oryNpx = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = exports.printOryConfig = exports.runAgentCommand = void 0;
-exports.otlpExporterFromEnv = exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.runWithUserSubject = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.TOOL_EXECUTION_PHASES = exports.USER_FACING_PHASES = exports.HARNESS_LIFECYCLE_MAP = exports.isToolExecutionPhase = exports.isUserFacingPhase = exports.classifyLifecycle = exports.isInteractiveTool = exports.getInteractiveToolCatalog = exports.INTERACTIVE_TOOL_CATALOG = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.gateToolCall = exports.applyPermissionMode = exports.checkAndDecide = 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 = void 0;
-exports.wrapTool = exports.registerSubagent = exports.complete = exports.gate = exports.sessionStart = exports.resolveNamespace = exports.parseKeyValueList = void 0;
+exports.clearCredentialsForUninstall = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.revokeAgentDynamicClient = 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.withQuietStderr = exports.redactLogData = exports.DebugLogger = exports.OryAgentClient = void 0;
+exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.emitDeferredNextSteps = exports.beginDeferNextSteps = exports.nextStepsSink = 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.resolveBuildInfo = exports.collectVersionInfo = exports.runVersionCommand = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.LOOPBACK_REDIRECT_URIS = exports.projectUrlFromSlug = exports.runPostInstall = exports.runInteractiveSetup = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.oryNpx = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = exports.printOryConfig = exports.runAgentCommand = exports.runConfigureCommand = void 0;
+exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.runWithUserSubject = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.TOOL_EXECUTION_PHASES = exports.USER_FACING_PHASES = exports.HARNESS_LIFECYCLE_MAP = exports.isToolExecutionPhase = exports.isUserFacingPhase = exports.classifyLifecycle = exports.isInteractiveTool = exports.getInteractiveToolCatalog = exports.INTERACTIVE_TOOL_CATALOG = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.gateToolCall = exports.applyPermissionMode = exports.checkAndDecide = 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 = void 0;
+exports.wrapTool = exports.writeAgentDelegatesSubagent = exports.writeUserDelegatesAgent = exports.registerSubagent = exports.complete = exports.gate = exports.sessionStart = exports.resolveNamespace = exports.parseKeyValueList = exports.otlpExporterFromEnv = 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");
 Object.defineProperty(exports, "DebugLogger", { enumerable: true, get: function () { return logger_js_1.DebugLogger; } });
 Object.defineProperty(exports, "redactLogData", { enumerable: true, get: function () { return logger_js_1.redactLogData; } });
+Object.defineProperty(exports, "withQuietStderr", { enumerable: true, get: function () { return logger_js_1.withQuietStderr; } });
 var tracer_js_1 = require("./tracer.js");
 Object.defineProperty(exports, "Tracer", { enumerable: true, get: function () { return tracer_js_1.Tracer; } });
 Object.defineProperty(exports, "ActiveSpan", { enumerable: true, get: function () { return tracer_js_1.ActiveSpan; } });
@@ -189,4 +190,6 @@ Object.defineProperty(exports, "sessionStart", { enumerable: true, get: function
 Object.defineProperty(exports, "gate", { enumerable: true, get: function () { return adapters_js_1.gate; } });
 Object.defineProperty(exports, "complete", { enumerable: true, get: function () { return adapters_js_1.complete; } });
 Object.defineProperty(exports, "registerSubagent", { enumerable: true, get: function () { return adapters_js_1.registerSubagent; } });
+Object.defineProperty(exports, "writeUserDelegatesAgent", { enumerable: true, get: function () { return adapters_js_1.writeUserDelegatesAgent; } });
+Object.defineProperty(exports, "writeAgentDelegatesSubagent", { enumerable: true, get: function () { return adapters_js_1.writeAgentDelegatesSubagent; } });
 Object.defineProperty(exports, "wrapTool", { enumerable: true, get: function () { return adapters_js_1.wrapTool; } });

package/dist/interactive-setup.js

@@ -82,6 +82,7 @@ const cli_js_1 = require("./cli.js");
 const cli_invocation_js_1 = require("./cli-invocation.js");
 const auth_js_1 = require("./auth.js");
 const client_js_1 = require("./client.js");
+const logger_js_1 = require("./logger.js");
 const user_login_js_1 = require("./user-login.js");
 const agent_auth_js_1 = require("./agent-auth.js");
 const tool_catalog_js_1 = require("./tool-catalog.js");
@@ -261,8 +262,12 @@ async function runInteractiveSetup(binName, harness, args = [], deps = {}) {
             ttyPrompter = createTtyPrompter();
         }
     };
+    // Quiet the structured stderr firehose for the duration of the wizard so
+    // `[ory-agent] {...}` debug lines don't interleave with the human-facing UI
+    // when a session runs with ORY_AGENT_DEBUG=true (the dev launcher always
+    // sets it). Debug still lands in the log file.
     try {
-        return await runWizard(binName, harness, { runner, prompt, deps, runInteractive });
+        return await (0, logger_js_1.withQuietStderr)(() => runWizard(binName, harness, { runner, prompt, deps, runInteractive }));
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/logger.d.ts

@@ -12,6 +12,15 @@ export interface LogEntry {
  */
 export declare function redactLogData(value: unknown): unknown;
 export declare class DebugLogger {
+    /**
+     * Process-global switch to suppress the stderr firehose while still writing
+     * to the log file. The interactive installer sets this so structured debug
+     * JSON (`[ory-agent] {...}`) doesn't interleave with the wizard's
+     * human-facing UI when a session runs with `ORY_AGENT_DEBUG=true` (the dev
+     * launcher, for one, always sets it). File logging — the real observability
+     * channel — is unaffected.
+     */
+    static stderrSuppressed: boolean;
     enabled: boolean;
     harness: string;
     logFile: string | null;
@@ -27,3 +36,15 @@ export declare class DebugLogger {
     warn(event: string, data?: Record<string, unknown>): void;
     error(event: string, data?: Record<string, unknown>): void;
 }
+/**
+ * Run `fn` with the structured stderr firehose suppressed, restoring the
+ * previous state afterward (even on throw). File logging is unaffected.
+ *
+ * Human-facing CLI commands (the interactive installer, `status`,
+ * `permissions status`/`bootstrap`) spin up a client and emit debug/info
+ * events; when the process runs with `ORY_AGENT_DEBUG=true` (the dev launcher
+ * always sets it) those `[ory-agent] {...}` lines would interleave with the
+ * command's polished output. Wrapping the command body in this keeps the
+ * terminal clean while the log file still captures everything.
+ */
+export declare function withQuietStderr<T>(fn: () => Promise<T> | T): Promise<T>;

package/dist/logger.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DebugLogger = void 0;
 exports.redactLogData = redactLogData;
+exports.withQuietStderr = withQuietStderr;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 /**
@@ -82,6 +83,15 @@ function redactLogData(value) {
     return value;
 }
 class DebugLogger {
+    /**
+     * Process-global switch to suppress the stderr firehose while still writing
+     * to the log file. The interactive installer sets this so structured debug
+     * JSON (`[ory-agent] {...}`) doesn't interleave with the wizard's
+     * human-facing UI when a session runs with `ORY_AGENT_DEBUG=true` (the dev
+     * launcher, for one, always sets it). File logging — the real observability
+     * channel — is unaffected.
+     */
+    static stderrSuppressed = false;
     enabled;
     harness;
     logFile;
@@ -113,8 +123,13 @@ class DebugLogger {
             ...(safeData ? { data: safeData } : {}),
         };
         const line = JSON.stringify(entry);
-        // Always write to stderr so we don't interfere with hook stdout
-        process.stderr.write(`[ory-agent] ${line}\n`);
+        // Write to stderr (never stdout) so we don't interfere with hook stdout,
+        // unless the stderr firehose is globally suppressed (e.g. during the
+        // interactive installer, so it doesn't clutter the wizard UI). The log
+        // file below still captures everything.
+        if (!DebugLogger.stderrSuppressed) {
+            process.stderr.write(`[ory-agent] ${line}\n`);
+        }
         if (this.logFile) {
             const dir = path.dirname(this.logFile);
             if (!fs.existsSync(dir)) {
@@ -137,3 +152,24 @@ class DebugLogger {
     }
 }
 exports.DebugLogger = DebugLogger;
+/**
+ * Run `fn` with the structured stderr firehose suppressed, restoring the
+ * previous state afterward (even on throw). File logging is unaffected.
+ *
+ * Human-facing CLI commands (the interactive installer, `status`,
+ * `permissions status`/`bootstrap`) spin up a client and emit debug/info
+ * events; when the process runs with `ORY_AGENT_DEBUG=true` (the dev launcher
+ * always sets it) those `[ory-agent] {...}` lines would interleave with the
+ * command's polished output. Wrapping the command body in this keeps the
+ * terminal clean while the log file still captures everything.
+ */
+async function withQuietStderr(fn) {
+    const prev = DebugLogger.stderrSuppressed;
+    DebugLogger.stderrSuppressed = true;
+    try {
+        return await fn();
+    }
+    finally {
+        DebugLogger.stderrSuppressed = prev;
+    }
+}

package/dist/permissions-cli.js

@@ -61,6 +61,7 @@ exports.printPermissionsOnboardingHelp = printPermissionsOnboardingHelp;
 exports.maybeAutoBootstrap = maybeAutoBootstrap;
 const config_js_1 = require("./config.js");
 const client_js_1 = require("./client.js");
+const logger_js_1 = require("./logger.js");
 const agent_auth_js_1 = require("./agent-auth.js");
 const auth_store_js_1 = require("./auth-store.js");
 const tool_catalog_js_1 = require("./tool-catalog.js");
@@ -85,10 +86,14 @@ async function runPermissionsCommand(binName, harness, args) {
         return sub ? 0 : 1;
     }
     switch (sub) {
+        // `status` and `bootstrap` spin up a client and probe/grant per tool,
+        // emitting debug/info events. Quiet the stderr firehose so those don't
+        // interleave with the command's human-facing output under
+        // ORY_AGENT_DEBUG=true; the log file still captures everything.
         case "status":
-            return await runPermissionsStatus(binName, harness);
+            return await (0, logger_js_1.withQuietStderr)(() => runPermissionsStatus(binName, harness));
         case "bootstrap":
-            return await runPermissionsBootstrap(binName, harness, args.slice(1));
+            return await (0, logger_js_1.withQuietStderr)(() => runPermissionsBootstrap(binName, harness, args.slice(1)));
         case "observe":
             return runPermissionsSetMode(binName, "observe");
         case "enforce":
@@ -283,9 +288,17 @@ async function runPermissionsBootstrap(binName, harness, args) {
             continue;
         }
         try {
-            const res = await client.createRelationship(check, {
-                spanAttributes: { toolName: tool, source: "permissions_bootstrap" },
-            });
+            // Read-before-write: Keto's create API is not idempotent (every PUT
+            // inserts a new row and never 409s), so a plain createRelationship on
+            // re-install would duplicate the whole catalog. ensureRelationship
+            // probes for the exact tuple first and only writes when it is absent.
+            const spanAttributes = { toolName: tool, source: "permissions_bootstrap" };
+            let res = await client.ensureRelationship(check, { spanAttributes });
+            if (res.probeError) {
+                // Couldn't confirm existence — fall back to a direct write so a
+                // needed grant is still created (bootstrap's job is to guarantee it).
+                res = await client.createRelationship(check, { spanAttributes });
+            }
             if (res.alreadyExisted) {
                 existed++;
                 console.log(`  = ${tool}  (already exists)`);

package/dist/status-cli.js

@@ -17,6 +17,7 @@ const config_js_1 = require("./config.js");
 const auth_store_js_1 = require("./auth-store.js");
 const agent_auth_js_1 = require("./agent-auth.js");
 const client_js_1 = require("./client.js");
+const logger_js_1 = require("./logger.js");
 const agent_auth_js_2 = require("./agent-auth.js");
 const subject_js_1 = require("./subject.js");
 const tool_catalog_js_1 = require("./tool-catalog.js");
@@ -279,28 +280,35 @@ function formatModeSuffix(source) {
  * 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) {
+    // Quiet the structured stderr firehose for the duration of the report so
+    // `[ory-agent] {...}` debug lines (the permissions probe runs a client and
+    // per-tool checks) don't interleave with this human-facing output when the
+    // command runs with ORY_AGENT_DEBUG=true. Debug still lands in the log file,
+    // and the "Recent activity" section below surfaces its tail regardless.
+    await (0, logger_js_1.withQuietStderr)(async () => {
+        const heading = `Ory Agent Plugin Status (${options.title})`;
+        console.log(heading);
+        console.log("=".repeat(heading.length));
         console.log("");
-        options.printPluginSection();
-    }
-    (0, cli_js_1.printEnvironment)();
-    console.log("");
-    console.log("Recent activity:");
-    (0, cli_js_1.printTraceTail)(harness);
-    (0, cli_js_1.printLogTail)(harness);
-    console.log("");
-    console.log(`  Watch traces live:  ${(0, cli_invocation_js_1.oryNpx)(binName)} watch`);
-    console.log("");
-    console.log(`Drill into any section with:`);
-    console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} agent status`);
-    console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} permissions status`);
-    console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure`);
+        (0, cli_js_1.printOryConfig)();
+        printUserIdentitySection();
+        printAgentIdentitySection();
+        await printPermissionsSection(binName, harness);
+        if (options.printPluginSection) {
+            console.log("");
+            options.printPluginSection();
+        }
+        (0, cli_js_1.printEnvironment)();
+        console.log("");
+        console.log("Recent activity:");
+        (0, cli_js_1.printTraceTail)(harness);
+        (0, cli_js_1.printLogTail)(harness);
+        console.log("");
+        console.log(`  Watch traces live:  ${(0, cli_invocation_js_1.oryNpx)(binName)} watch`);
+        console.log("");
+        console.log(`Drill into any section with:`);
+        console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} agent status`);
+        console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} permissions status`);
+        console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure`);
+    });
 }

package/dist/testing.d.ts

@@ -14,6 +14,14 @@ export { runHarnessContractSuite, type HarnessContractAdapter, type ContractCont
  * Pass overrides to customize (e.g. a different harness name).
  */
 export declare function createMockClient(overrides?: Partial<ConstructorParameters<typeof OryAgentClient>[0]>): OryAgentClient;
+/**
+ * Control what the exact-tuple existence probe ({@link OryAgentClient.relationshipExists},
+ * used by `ensureRelationship`) reports. Pass `true` to model a tuple that is
+ * already stored (the write is then skipped), `false` for absent (the write
+ * proceeds). Returns the spy so callers can e.g. `.mockRejectedValue(...)` to
+ * model a failed probe.
+ */
+export declare function stubRelationshipExists(client: OryAgentClient, exists: boolean): import("vitest").Mock<(check: import("./types.js").PermissionCheck) => Promise<boolean>>;
 /**
  * Stub an internal API instance method on the client.
  * Returns a vi.fn mock so callers can assert on calls.

package/dist/testing.js

@@ -42,6 +42,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BATCH_SERVER_DENIED = exports.BATCH_SERVER_ALLOWED_TOOL_DENIED = exports.BATCH_BOTH_ALLOWED = exports.PERMISSION_DENIED = exports.PERMISSION_ALLOWED = exports.MOCK_INACTIVE_OAUTH2_RESPONSE = exports.MOCK_OAUTH2_RESPONSE = exports.MOCK_INACTIVE_SESSION_RESPONSE = exports.MOCK_SESSION_RESPONSE = exports.runHarnessContractSuite = void 0;
 exports.createMockClient = createMockClient;
+exports.stubRelationshipExists = stubRelationshipExists;
 exports.stubApi = stubApi;
 exports.makeAxiosError = makeAxiosError;
 exports.makeNetworkError = makeNetworkError;
@@ -85,13 +86,31 @@ Object.defineProperty(exports, "runHarnessContractSuite", { enumerable: true, ge
  * Pass overrides to customize (e.g. a different harness name).
  */
 function createMockClient(overrides) {
-    return new client_js_1.OryAgentClient({
+    const client = new client_js_1.OryAgentClient({
         projectUrl: "https://test.projects.oryapis.com",
         apiKey: "test-api-key",
         harness: "test",
         sessionCacheTtlMs: 0,
         ...overrides,
     });
+    // `ensureRelationship` probes for the exact tuple before writing. Default
+    // to "no tuple exists" so a plain createRelationship-asserting test sees the
+    // write proceed; tests that model an already-present tuple override this via
+    // `stubRelationshipExists`. We spy the public `relationshipExists` method
+    // (not the internal getRelationships API) because setAgentPrincipal rebuilds
+    // the Keto API instance and would discard an API-level stub.
+    vitest_1.vi.spyOn(client, "relationshipExists").mockResolvedValue(false);
+    return client;
+}
+/**
+ * Control what the exact-tuple existence probe ({@link OryAgentClient.relationshipExists},
+ * used by `ensureRelationship`) reports. Pass `true` to model a tuple that is
+ * already stored (the write is then skipped), `false` for absent (the write
+ * proceeds). Returns the spy so callers can e.g. `.mockRejectedValue(...)` to
+ * model a failed probe.
+ */
+function stubRelationshipExists(client, exists) {
+    return vitest_1.vi.spyOn(client, "relationshipExists").mockResolvedValue(exists);
 }
 /**
  * Stub an internal API instance method on the client.

package/package.json

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