@ory/argus 0.11.0 → 0.12.0

package/dist/cli.js

@@ -47,10 +47,11 @@ exports.interactiveConfigPrompt = interactiveConfigPrompt;
 exports.runAgentCommand = runAgentCommand;
 const fs = __importStar(require("node:fs"));
 const readline = __importStar(require("node:readline"));
-const client_1 = require("@ory/client");
 const config_js_1 = require("./config.js");
 const agent_auth_js_1 = require("./agent-auth.js");
 const tracer_js_1 = require("./tracer.js");
+const cli_invocation_js_1 = require("./cli-invocation.js");
+const client_js_1 = require("./client.js");
 /**
  * Shared `configure` command implementation for all plugin CLIs.
  *
@@ -67,14 +68,27 @@ const tracer_js_1 = require("./tracer.js");
  */
 function runConfigureCommand(binName, args) {
     let projectUrl;
+    let projectId;
     let apiKey;
     let oauth2ClientId;
     let auditOnly = false;
+    // `undefined` = not specified (leave the persisted value alone);
+    // true/false = explicit enable/disable of the interactive user login.
+    let userLogin;
+    // `undefined` = not specified; a string sets it; empty string ("") clears it
+    // (via --no-user-subject-namespace) to fall back to direct SubjectID.
+    let userSubjectNamespace;
     for (let i = 0; i < args.length; i++) {
         switch (args[i]) {
             case "--project-url":
+            // `--sdk-url` is the name the Ory Console "Get Started" uses; accept it
+            // as an alias so the value copied from there works verbatim.
+            case "--sdk-url":
                 projectUrl = args[++i];
                 break;
+            case "--project-id":
+                projectId = args[++i];
+                break;
             case "--api-key":
                 apiKey = args[++i];
                 break;
@@ -84,9 +98,27 @@ function runConfigureCommand(binName, args) {
             case "--audit-only":
                 auditOnly = true;
                 break;
+            case "--user-login":
+                userLogin = true;
+                break;
+            case "--no-user-login":
+                userLogin = false;
+                break;
+            case "--user-subject-namespace":
+                userSubjectNamespace = args[++i];
+                break;
+            case "--no-user-subject-namespace":
+                userSubjectNamespace = "";
+                break;
         }
     }
-    if (!projectUrl && !apiKey && !oauth2ClientId && !auditOnly) {
+    if (!projectUrl &&
+        !projectId &&
+        !apiKey &&
+        !oauth2ClientId &&
+        !auditOnly &&
+        userLogin === undefined &&
+        userSubjectNamespace === undefined) {
         const resolved = (0, config_js_1.resolveConfig)();
         const configPath = (0, config_js_1.getConfigPath)();
         console.log("Ory Plugin Configuration");
@@ -94,35 +126,54 @@ function runConfigureCommand(binName, args) {
         console.log("");
         console.log(`Config file:      ${configPath}`);
         console.log(`Project URL:      ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
+        console.log(`Project ID:       ${resolved.projectId ?? "(not set)"} [${resolved.projectIdSource}]`);
         console.log(`API Key:          ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
         console.log(`OAuth2 Client ID: ${resolved.oauth2ClientId ?? "(not set)"} [${resolved.oauth2ClientIdSource}]`);
         console.log(`Audit Only:       ${resolved.auditOnly ? "yes" : "no"}`);
+        console.log(`User Login:       ${resolved.userLogin ? "on" : "off"} [${resolved.userLoginSource}]`);
+        console.log(`User subject ns:  ${resolved.userSubjectNamespace ?? "(direct subject id)"} [${resolved.userSubjectNamespaceSource}]`);
         console.log("");
         console.log("To configure:");
-        console.log(`  npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
+        console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
+        console.log("");
+        console.log("To enable the interactive user login (PKCE browser flow at session start):");
+        console.log(`  npx ${binName} configure --user-login    (disable with --no-user-login)`);
+        console.log("");
+        console.log("To address the user as a SubjectSet in permission checks (must match your tuples):");
+        console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --user-subject-namespace User   (clear with --no-user-subject-namespace)`);
         console.log("");
         console.log("To enable audit logging only (no auth or permission checks):");
-        console.log(`  npx ${binName} configure --audit-only`);
+        console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --audit-only`);
         console.log("");
         console.log("Or set environment variables:");
         console.log("  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+        console.log("  # ORY_SDK_URL (the Ory Console 'Get Started' name) is accepted as an alias.");
+        console.log("  # ORY_PROJECT_ID=<project uuid> is stored for admin operations (not an SDK URL).");
         console.log("  export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
         console.log("  export ORY_AGENT_API_KEY=ory_pat_...");
+        console.log("  export ORY_USER_LOGIN=true");
         return;
     }
     if (auditOnly) {
-        // Audit-only mode: clear projectUrl/apiKey, set auditOnly flag
-        (0, config_js_1.saveConfig)({ auditOnly: true });
+        // Audit-only mode: set the kill switch. Persist an explicit user-login
+        // choice too if one was passed, so it takes effect once audit-only is
+        // later turned off; audit-only itself disables login regardless.
+        (0, config_js_1.saveConfig)({ auditOnly: true, ...(userLogin !== undefined ? { userLogin } : {}) });
         const configPath = (0, config_js_1.getConfigPath)();
         console.log(`Configuration saved to ${configPath}`);
         console.log("  Mode: audit-only (logging enabled, auth and permission checks disabled)");
+        if (userLogin !== undefined) {
+            console.log(`  User login: ${userLogin ? "on" : "off"} (takes effect when audit-only is disabled)`);
+        }
         console.log("");
         console.log("This configuration is shared across all Ory agent plugins.");
         return;
     }
-    // When --project-url is provided we need a usable OAuth2 client id for
-    // the user PKCE flow — block the configure with a clear error if none
-    // is reachable from the flag, env, or already-persisted config.
+    // When --project-url / --sdk-url is provided we need a usable OAuth2 client
+    // id for the user PKCE flow — block the configure with a clear error if none
+    // is reachable from the flag, env, or already-persisted config. A bare
+    // --project-id sets an admin identifier only (not an SDK URL), so it doesn't
+    // trigger this gate on its own.
     if (projectUrl) {
         const persisted = (0, config_js_1.loadConfig)().oauth2ClientId;
         const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
@@ -152,31 +203,67 @@ function runConfigureCommand(binName, args) {
                 "    --redirect-uri http://127.0.0.1:47826/callback\n" +
                 "\n" +
                 "If you only want audit logging (no auth or permission checks), use:\n" +
-                `  npx ${binName} configure --audit-only`);
+                `  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --audit-only`);
             process.exit(1);
         }
     }
+    // Enabling user login needs a project URL and a public OAuth2 client id
+    // to complete the PKCE flow. Warn (don't block) if either is missing —
+    // the operator may supply them separately or via env before running.
+    if (userLogin === true) {
+        // resolveConfig() already folds in the ORY_SDK_URL alias and the config
+        // file; OR in the URL being set on this same invocation.
+        const nextProjectUrl = projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
+        const nextClientId = oauth2ClientId ?? process.env.ORY_OAUTH2_CLIENT_ID ?? (0, config_js_1.loadConfig)().oauth2ClientId;
+        if (!nextProjectUrl || !nextClientId) {
+            const missing = [
+                !nextProjectUrl ? "a project URL (--project-url / --sdk-url / ORY_PROJECT_URL)" : null,
+                !nextClientId ? "an OAuth2 client id (--oauth2-client-id / ORY_OAUTH2_CLIENT_ID)" : null,
+            ].filter(Boolean);
+            console.warn(`Warning: user login is enabled but still missing ${missing.join(" and ")}.\n` +
+                "The PKCE browser flow can't complete until both are configured.");
+        }
+    }
     const update = {};
     if (projectUrl)
         update.projectUrl = projectUrl;
+    if (projectId)
+        update.projectId = projectId;
     if (apiKey)
         update.apiKey = apiKey;
     if (oauth2ClientId)
         update.oauth2ClientId = oauth2ClientId;
-    // Clear auditOnly when configuring with a project URL
-    update.auditOnly = false;
+    if (userLogin !== undefined)
+        update.userLogin = userLogin;
+    // A non-empty namespace sets the SubjectSet namespace; the empty string
+    // (from --no-user-subject-namespace) clears it (null ⇒ delete the key).
+    if (userSubjectNamespace !== undefined) {
+        update.userSubjectNamespace = userSubjectNamespace === "" ? null : userSubjectNamespace;
+    }
+    // Configuring an actual connection (a slug-based URL, api key, or client id)
+    // implies leaving audit-only mode. A bare project id is only an admin
+    // identifier — it doesn't connect anything on its own — so it doesn't flip
+    // the flag; nor does a standalone user-login toggle.
+    if (projectUrl || apiKey || oauth2ClientId)
+        update.auditOnly = false;
     (0, config_js_1.saveConfig)(update);
     const configPath = (0, config_js_1.getConfigPath)();
     console.log(`Configuration saved to ${configPath}`);
     if (projectUrl)
         console.log(`  Project URL: ${projectUrl}`);
+    if (projectId)
+        console.log(`  Project ID: ${projectId}`);
     if (apiKey)
         console.log(`  API Key: (set)`);
     if (oauth2ClientId)
         console.log(`  OAuth2 Client ID: ${oauth2ClientId}`);
+    if (userLogin !== undefined)
+        console.log(`  User Login: ${userLogin ? "on" : "off"}`);
+    if (userSubjectNamespace !== undefined)
+        console.log(`  User subject namespace: ${userSubjectNamespace === "" ? "(cleared — direct subject id)" : userSubjectNamespace}`);
     console.log("");
     console.log("This configuration is shared across all Ory agent plugins.");
-    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY, ORY_OAUTH2_CLIENT_ID) take precedence when set.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY, ORY_OAUTH2_CLIENT_ID, ORY_USER_LOGIN) take precedence when set.");
 }
 /**
  * Print the "Configuration:" block showing Ory project URL and API key status.
@@ -189,10 +276,13 @@ function printOryConfig() {
     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(`  Project ID:      ${resolved.projectId ?? "NOT SET"} [source: ${resolved.projectIdSource}]`);
     console.log(`  API Key:         ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
     console.log(`  OAuth2 Client:   ${resolved.oauth2ClientId ?? "NOT SET"} [source: ${resolved.oauth2ClientIdSource}]`);
     console.log(`  Permission mode: ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
+    console.log(`  User login:      ${resolved.userLogin ? "on" : "off"} [source: ${resolved.userLoginSource}]`);
     console.log(`  Namespace:       ${namespace}`);
+    console.log(`  User subject ns: ${resolved.userSubjectNamespace ?? "(direct subject id)"} [source: ${resolved.userSubjectNamespaceSource}]`);
 }
 /**
  * Print the "Environment:" block showing Ory-related environment variables.
@@ -201,6 +291,9 @@ function printEnvironment() {
     console.log("");
     console.log("Environment:");
     const vars = [
+        ["ORY_PROJECT_URL", process.env.ORY_PROJECT_URL, false],
+        ["ORY_SDK_URL", process.env.ORY_SDK_URL, false],
+        ["ORY_PROJECT_ID", process.env.ORY_PROJECT_ID, false],
         ["ORY_USER_LOGIN", process.env.ORY_USER_LOGIN, false],
         [
             "ORY_AGENT_API_KEY",
@@ -238,10 +331,17 @@ function printEnvironment() {
     }
 }
 /**
- * Print the last 5 debug log entries if ORY_AGENT_LOG_FILE is set and exists.
+ * Print the last 5 debug log entries. When `harness` is given the path is
+ * resolved the same way the plugin does at runtime — the default per-harness
+ * data-dir location when `ORY_AGENT_LOG_FILE` is unset — so `status` finds the
+ * log without the reader hand-setting env vars. The debug log only exists when
+ * a session ran with `ORY_AGENT_DEBUG=true`; when it doesn't, this prints a
+ * one-line pointer on how to turn it on rather than staying silent.
  */
-function printLogTail() {
-    const logFile = process.env.ORY_AGENT_LOG_FILE;
+function printLogTail(harness) {
+    const logFile = harness
+        ? (0, client_js_1.resolveDebugLogPath)(harness)
+        : process.env.ORY_AGENT_LOG_FILE;
     if (logFile && fs.existsSync(logFile)) {
         const lines = fs.readFileSync(logFile, "utf-8").trim().split("\n");
         console.log("");
@@ -257,6 +357,12 @@ function printLogTail() {
             }
         }
     }
+    else if (harness) {
+        console.log("");
+        console.log(logFile
+            ? `Debug log: none yet — run a session with ORY_AGENT_DEBUG=true to write ${logFile}`
+            : "Debug log: disabled (ORY_AGENT_LOG_FILE set empty)");
+    }
 }
 /**
  * Print the "Configure your Ory credentials" help text.
@@ -266,7 +372,7 @@ function printEnvHelp(binName) {
     console.log("Configure your Ory credentials (one of these methods):");
     console.log("");
     console.log("  Option 1 — Save to config file (persists across sessions):");
-    console.log(`    npx ${binName} configure --project-url https://your-project.projects.oryapis.com \\`);
+    console.log(`    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url https://your-project.projects.oryapis.com \\`);
     console.log("                              --oauth2-client-id <public OAuth2 client id> \\");
     console.log("                              --api-key ory_pat_...");
     console.log("");
@@ -278,10 +384,17 @@ function printEnvHelp(binName) {
     console.log("If neither is set when a session starts, the agent will prompt for configuration.");
 }
 /**
- * Print the last 5 trace entries if ORY_AGENT_TRACE_FILE is set and exists.
+ * Print the last 5 trace spans. When `harness` is given the path is resolved
+ * the same way the plugin does at runtime — the default per-harness data-dir
+ * location when `ORY_AGENT_TRACE_FILE` is unset — so `status` shows recent
+ * activity out of the box (traces are written on every recorded span). When no
+ * spans have been recorded yet, prints a one-line pointer at the trace file so
+ * the reader knows where to look (and how to watch it live).
  */
-function printTraceTail() {
-    const traceFile = process.env.ORY_AGENT_TRACE_FILE;
+function printTraceTail(harness) {
+    const traceFile = harness
+        ? (0, client_js_1.resolveTraceFilePath)(harness)
+        : process.env.ORY_AGENT_TRACE_FILE;
     if (traceFile && fs.existsSync(traceFile)) {
         const lines = fs.readFileSync(traceFile, "utf-8").trim().split("\n");
         console.log("");
@@ -297,22 +410,32 @@ function printTraceTail() {
             }
         }
     }
+    else if (harness) {
+        console.log("");
+        console.log(traceFile
+            ? `Trace file: none yet — spans land in ${traceFile} once a session runs a tool`
+            : "Trace file: disabled (ORY_AGENT_TRACE_FILE set empty)");
+    }
 }
 /**
  * Run the live trace watcher. Tails the NDJSON trace file and prints
  * formatted spans to stdout as they arrive. Blocks until interrupted.
  */
-function runWatchCommand(args) {
-    let traceFile = args[0];
-    if (!traceFile) {
-        traceFile = process.env.ORY_AGENT_TRACE_FILE ?? "";
-    }
+function runWatchCommand(harness, args) {
+    // Precedence: explicit arg → resolved default (honors ORY_AGENT_TRACE_FILE,
+    // falling back to the per-harness data-dir path). The resolver returns
+    // undefined only when tracing is explicitly disabled (ORY_AGENT_TRACE_FILE
+    // set empty), so that's the one case that dead-ends here.
+    const traceFile = args[0] || (0, client_js_1.resolveTraceFilePath)(harness);
     if (!traceFile) {
-        console.error("Usage: watch <trace-file>\n" +
-            "  Or set ORY_AGENT_TRACE_FILE environment variable.\n");
+        console.error("Trace file is disabled (ORY_AGENT_TRACE_FILE is set empty).\n" +
+            "Unset it, or pass a path: watch <trace-file>\n");
         process.exit(1);
     }
     console.log(`Watching traces: ${traceFile}`);
+    if (!fs.existsSync(traceFile)) {
+        console.log("(file doesn't exist yet — waiting for the first span…)");
+    }
     console.log("Press Ctrl+C to stop.\n");
     const stop = (0, tracer_js_1.watchTraceFile)(traceFile, (span) => {
         console.log((0, tracer_js_1.formatSpan)(span));
@@ -382,7 +505,7 @@ async function promptForProjectUrl(binName) {
         "--------------------------------------------",
         "",
         "No Ory project URL is configured for this session.",
-        `Enter your Ory project URL to continue, or press Enter to skip and run \`npx ${binName} configure\` later.`,
+        `Enter your Ory project URL to continue, or press Enter to skip and run \`${(0, cli_invocation_js_1.oryNpx)(binName)} configure\` later.`,
         "",
         "Example: https://your-project.projects.oryapis.com",
         "",
@@ -430,10 +553,10 @@ async function interactiveConfigPrompt(binName) {
         "Run one of the following commands in another terminal:",
         "",
         "  Connect to Ory (enables auth & permission checks):",
-        `    npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`,
+        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`,
         "",
         "  Or, enable audit logging only (no auth or permission checks):",
-        `    npx ${binName} configure --audit-only`,
+        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --audit-only`,
         "",
         `Config is saved to ${configPath}`,
         "and shared across all agent plugins.",
@@ -538,31 +661,16 @@ async function runAgentUnregister() {
         console.log("No registered agent client to unregister. Nothing to do.");
         return 0;
     }
-    if (persisted.registrationClientUri && persisted.registrationAccessToken) {
-        const oidc = new client_1.OidcApi(new client_1.Configuration({
-            basePath: persisted.projectUrl,
-            accessToken: persisted.registrationAccessToken,
-        }));
-        try {
-            await oidc.deleteOidcDynamicClient({ id: persisted.clientId });
-        }
-        catch (err) {
-            const status = err?.response?.status;
-            if (status === 404) {
-                // Already gone server-side; nothing to warn about.
-            }
-            else if (typeof status === "number") {
-                console.warn(`Warning: server-side DELETE returned HTTP ${status}. Local state will be cleared anyway.`);
-            }
-            else {
-                const msg = err instanceof Error ? err.message : String(err);
-                console.warn(`Warning: server-side DELETE failed (${msg}). Local state will be cleared anyway.`);
-            }
-        }
-    }
-    else {
+    const outcome = await (0, agent_auth_js_1.revokeAgentDynamicClient)(persisted);
+    if (outcome.status === "skipped") {
         console.warn("Warning: no registration_access_token was persisted, so we cannot DELETE the server-side client. Clearing local state only.");
     }
+    else if (outcome.status === "failed") {
+        const detail = typeof outcome.httpStatus === "number"
+            ? `returned HTTP ${outcome.httpStatus}`
+            : `failed (${outcome.message})`;
+        console.warn(`Warning: server-side DELETE ${detail}. Local state will be cleared anyway.`);
+    }
     (0, agent_auth_js_1.clearAgentDynamicCredentials)();
     console.log(`Unregistered agent client ${persisted.clientId}.`);
     return 0;

package/dist/client.d.ts

@@ -13,6 +13,13 @@ export interface OryAgentConfig {
     logFile?: string;
     /** Optional NDJSON trace file path for structured span output */
     traceFile?: string;
+    /**
+     * Permission-check subject namespace for the human user. When set, the
+     * user is addressed as a SubjectSet `<namespace>:<subject>` (matching how
+     * the tuples were written in Keto) rather than a direct SubjectID. Read by
+     * {@link resolveUserSubject}; `ORY_USER_SUBJECT_NAMESPACE` overrides it.
+     */
+    userSubjectNamespace?: string;
     /**
      * Session cache TTL in milliseconds.
      * Set to 0 to disable caching. Default: 60_000 (1 minute).
@@ -58,6 +65,13 @@ export declare class OryAgentClient {
     get userPrincipal(): PrincipalIdentity;
     /** Snapshot of the current agent principal. */
     get agentPrincipal(): PrincipalIdentity;
+    /**
+     * Configured user-subject namespace (from config, resolved at construction).
+     * `resolveUserSubject` uses this as the SubjectSet namespace when the
+     * `ORY_USER_SUBJECT_NAMESPACE` env var isn't set. Undefined ⇒ direct
+     * SubjectID resolution.
+     */
+    get userSubjectNamespace(): string | undefined;
     /**
      * Set or update the human user principal. The user is the subject of
      * permission checks but does not authenticate outgoing API calls.
@@ -151,6 +165,19 @@ export declare class OryAgentClient {
      */
     static fromEnv(harness: string): OryAgentClient;
 }
+/** Default debug-log path under the shared per-harness data dir. */
+export declare const DEFAULT_DEBUG_LOG_FILENAME = "ory-agent-debug.log";
+/** Default trace (NDJSON) path under the shared per-harness data dir. */
+export declare const DEFAULT_TRACE_FILENAME = "ory-agent-trace.ndjson";
+/**
+ * Debug log path. Only written when `ORY_AGENT_DEBUG=true` (the logger gates
+ * on that); defaulting the path just means an enabled debug session lands in a
+ * file automatically — important for subprocess-hook harnesses whose stderr
+ * the harness may swallow.
+ */
+export declare function resolveDebugLogPath(harness: string): string | undefined;
+/** Trace (NDJSON) path. Written on every recorded span when set. */
+export declare function resolveTraceFilePath(harness: string): string | undefined;
 /**
  * Pull the Ory backend request ID from a response headers bag (axios returns
  * lowercase header names). Returns undefined when not present.

package/dist/client.js

@@ -1,8 +1,44 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OryAgentClient = void 0;
+exports.DEFAULT_TRACE_FILENAME = exports.DEFAULT_DEBUG_LOG_FILENAME = exports.OryAgentClient = void 0;
+exports.resolveDebugLogPath = resolveDebugLogPath;
+exports.resolveTraceFilePath = resolveTraceFilePath;
 exports.extractOryRequestId = extractOryRequestId;
 const client_1 = require("@ory/client");
+const path = __importStar(require("node:path"));
 const logger_js_1 = require("./logger.js");
 const tracer_js_1 = require("./tracer.js");
 const config_js_1 = require("./config.js");
@@ -75,6 +111,15 @@ class OryAgentClient {
     get agentPrincipal() {
         return { ...this._agentPrincipal };
     }
+    /**
+     * Configured user-subject namespace (from config, resolved at construction).
+     * `resolveUserSubject` uses this as the SubjectSet namespace when the
+     * `ORY_USER_SUBJECT_NAMESPACE` env var isn't set. Undefined ⇒ direct
+     * SubjectID resolution.
+     */
+    get userSubjectNamespace() {
+        return this.config.userSubjectNamespace;
+    }
     /**
      * Set or update the human user principal. The user is the subject of
      * permission checks but does not authenticate outgoing API calls.
@@ -600,6 +645,8 @@ class OryAgentClient {
     static fromEnv(harness) {
         const resolved = (0, config_js_1.resolveConfig)();
         const projectUrl = resolved.projectUrl;
+        const logFile = resolveDebugLogPath(harness);
+        const traceFile = resolveTraceFilePath(harness);
         if (!projectUrl) {
             // Use a placeholder URL so the client can be constructed.
             // API calls will fail with network_error which is handled as fail-open.
@@ -607,8 +654,9 @@ class OryAgentClient {
                 projectUrl: "http://localhost:0",
                 apiKey: resolved.apiKey,
                 harness,
-                logFile: process.env.ORY_AGENT_LOG_FILE,
-                traceFile: process.env.ORY_AGENT_TRACE_FILE,
+                logFile,
+                traceFile,
+                userSubjectNamespace: resolved.userSubjectNamespace,
                 sessionCacheTtlMs: process.env.ORY_SESSION_CACHE_TTL_MS
                     ? parseInt(process.env.ORY_SESSION_CACHE_TTL_MS, 10)
                     : undefined,
@@ -625,8 +673,9 @@ class OryAgentClient {
             projectUrl,
             apiKey: resolved.apiKey,
             harness,
-            logFile: process.env.ORY_AGENT_LOG_FILE,
-            traceFile: process.env.ORY_AGENT_TRACE_FILE,
+            logFile,
+            traceFile,
+            userSubjectNamespace: resolved.userSubjectNamespace,
             sessionCacheTtlMs: process.env.ORY_SESSION_CACHE_TTL_MS
                 ? parseInt(process.env.ORY_SESSION_CACHE_TTL_MS, 10)
                 : undefined,
@@ -640,6 +689,37 @@ class OryAgentClient {
     }
 }
 exports.OryAgentClient = OryAgentClient;
+/** Default debug-log path under the shared per-harness data dir. */
+exports.DEFAULT_DEBUG_LOG_FILENAME = "ory-agent-debug.log";
+/** Default trace (NDJSON) path under the shared per-harness data dir. */
+exports.DEFAULT_TRACE_FILENAME = "ory-agent-trace.ndjson";
+/**
+ * Resolve a file path from an env var with a sensible default under the
+ * per-harness data dir. Semantics:
+ *   - unset          → the default path (so post-install runs are observable
+ *                      without hand-setting env vars),
+ *   - set to a path  → that path (operator / dev-launcher override),
+ *   - set but empty  → `undefined` (explicit opt-out, e.g. `ORY_AGENT_TRACE_FILE=`).
+ */
+function resolveFilePath(envValue, defaultPath) {
+    if (envValue === undefined)
+        return defaultPath;
+    const trimmed = envValue.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Debug log path. Only written when `ORY_AGENT_DEBUG=true` (the logger gates
+ * on that); defaulting the path just means an enabled debug session lands in a
+ * file automatically — important for subprocess-hook harnesses whose stderr
+ * the harness may swallow.
+ */
+function resolveDebugLogPath(harness) {
+    return resolveFilePath(process.env.ORY_AGENT_LOG_FILE, path.join((0, config_js_1.getHarnessDataDir)(harness), exports.DEFAULT_DEBUG_LOG_FILENAME));
+}
+/** Trace (NDJSON) path. Written on every recorded span when set. */
+function resolveTraceFilePath(harness) {
+    return resolveFilePath(process.env.ORY_AGENT_TRACE_FILE, path.join((0, config_js_1.getHarnessDataDir)(harness), exports.DEFAULT_TRACE_FILENAME));
+}
 function attachOtlpExporterFromEnv(client, harness) {
     const meta = client.tracer.processMetadata;
     const exporter = (0, otlp_js_1.otlpExporterFromEnv)({