@ory/argus 0.14.0 → 1.0.1

package/dist/external-registrations-main.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * `deregister-external` — replay every recorded foreign-tool removal.
+ *
+ * Run by `pnpm clean:all` before it deletes the data dir, so wiping our own
+ * state never leaves another tool pointing at a directory that is gone (#206).
+ * Always exits 0: this is cleanup in front of a destructive step that is going
+ * to happen regardless.
+ */
+export {};

package/dist/external-registrations-main.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `deregister-external` — replay every recorded foreign-tool removal.
+ *
+ * Run by `pnpm clean:all` before it deletes the data dir, so wiping our own
+ * state never leaves another tool pointing at a directory that is gone (#206).
+ * Always exits 0: this is cleanup in front of a destructive step that is going
+ * to happen regardless.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const external_registrations_js_1 = require("./external-registrations.js");
+function main() {
+    const pending = (0, external_registrations_js_1.loadExternalRegistrations)();
+    if (pending.length === 0) {
+        console.log("[ory] No external registrations to remove.");
+        return;
+    }
+    for (const result of (0, external_registrations_js_1.deregisterExternalRegistrations)()) {
+        if (result.ok) {
+            console.log(`[ory] Deregistered ${result.registration.description}.`);
+        }
+        else {
+            console.warn(`[ory] Could not deregister ${result.registration.description}: ${result.detail}. ` +
+                `Remove it by hand with: ${[
+                    result.registration.remove.command,
+                    ...result.registration.remove.args,
+                ].join(" ")}`);
+        }
+    }
+}
+try {
+    main();
+}
+catch (err) {
+    console.warn(`[ory] External deregistration failed: ${err.message}`);
+}
+process.exit(0);

package/dist/external-registrations.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Registrations we have made in *another tool's* config that point back into
+ * our data dir.
+ *
+ * Two harnesses do this today: Codex and Claude Code both assemble a plugin
+ * marketplace under `<dataDir>/<harness>/` and hand that **path** to the
+ * harness CLI, which stores it and re-reads it on every run.
+ *
+ * That makes the data dir load-bearing for a foreign tool, and removing it
+ * without deregistering first leaves that tool pointing at a directory which no
+ * longer exists. For Codex the blast radius is the whole `codex plugin`
+ * surface, including plugins that have nothing to do with Ory:
+ *
+ * ```
+ * $ codex plugin list
+ * Error: failed to load configured marketplace snapshot(s):
+ * - `ory` at ~/.config/ory-agent-plugins/codex/marketplace: marketplace root
+ *   does not contain a supported manifest
+ * ```
+ *
+ * The ordinary `uninstall` path deregisters correctly. The problem is every
+ * path that removes the data dir *without* going through it — `pnpm clean:all`
+ * or a user clearing the directory by hand. Removing our own state should never
+ * leave someone else's tool broken (#206).
+ *
+ * So each plugin records how to undo its registration, and the destructive
+ * paths replay those removals **before** deleting anything. The record is
+ * deliberately a plain command rather than a callback: the code that could run
+ * it may itself be inside the directory about to be deleted.
+ */
+export interface ExternalRegistration {
+    /** The harness that made the registration. One record per harness. */
+    harness: string;
+    /** The foreign tool holding the reference (`codex`, `claude`). */
+    tool: string;
+    /** Human-readable summary, shown when the removal runs. */
+    description: string;
+    /** Path inside our data dir that the foreign tool points at. */
+    root: string;
+    /** Argv that removes the registration from the foreign tool. */
+    remove: {
+        command: string;
+        args: string[];
+    };
+}
+/** Every registration currently recorded. */
+export declare function loadExternalRegistrations(): ExternalRegistration[];
+/**
+ * Record (or refresh) the registration for a harness. Idempotent: re-running an
+ * install replaces the harness's entry rather than appending a duplicate.
+ */
+export declare function recordExternalRegistration(entry: ExternalRegistration): void;
+/** Forget a harness's registration, after it has been deregistered. */
+export declare function clearExternalRegistration(harness: string): void;
+export interface DeregisterResult {
+    registration: ExternalRegistration;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Replay every recorded removal. Call this **before** deleting the data dir.
+ *
+ * Entirely best-effort: a foreign tool that is no longer installed, or that
+ * fails the removal, must not stop the reset that is in progress. Results are
+ * returned so the caller can report what happened.
+ */
+export declare function deregisterExternalRegistrations(): DeregisterResult[];
+/** Drop the whole registry (the data dir is about to go anyway). */
+export declare function clearAllExternalRegistrations(): void;
+/**
+ * A registration whose target directory has gone missing — the foreign tool is
+ * pointing at nothing, which is the state that breaks it.
+ *
+ * `status` uses this to say what happened and how to fix it, instead of leaving
+ * the user to decode an error from a tool that never mentions Ory.
+ */
+export declare function findDanglingRegistration(harness: string): ExternalRegistration | undefined;
+/** One-line remediation for a dangling registration, for `status` output. */
+export declare function describeDanglingRegistration(registration: ExternalRegistration): string;

package/dist/external-registrations.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Registrations we have made in *another tool's* config that point back into
+ * our data dir.
+ *
+ * Two harnesses do this today: Codex and Claude Code both assemble a plugin
+ * marketplace under `<dataDir>/<harness>/` and hand that **path** to the
+ * harness CLI, which stores it and re-reads it on every run.
+ *
+ * That makes the data dir load-bearing for a foreign tool, and removing it
+ * without deregistering first leaves that tool pointing at a directory which no
+ * longer exists. For Codex the blast radius is the whole `codex plugin`
+ * surface, including plugins that have nothing to do with Ory:
+ *
+ * ```
+ * $ codex plugin list
+ * Error: failed to load configured marketplace snapshot(s):
+ * - `ory` at ~/.config/ory-agent-plugins/codex/marketplace: marketplace root
+ *   does not contain a supported manifest
+ * ```
+ *
+ * The ordinary `uninstall` path deregisters correctly. The problem is every
+ * path that removes the data dir *without* going through it — `pnpm clean:all`
+ * or a user clearing the directory by hand. Removing our own state should never
+ * leave someone else's tool broken (#206).
+ *
+ * So each plugin records how to undo its registration, and the destructive
+ * paths replay those removals **before** deleting anything. The record is
+ * deliberately a plain command rather than a callback: the code that could run
+ * it may itself be inside the directory about to be deleted.
+ */
+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.loadExternalRegistrations = loadExternalRegistrations;
+exports.recordExternalRegistration = recordExternalRegistration;
+exports.clearExternalRegistration = clearExternalRegistration;
+exports.deregisterExternalRegistrations = deregisterExternalRegistrations;
+exports.clearAllExternalRegistrations = clearAllExternalRegistrations;
+exports.findDanglingRegistration = findDanglingRegistration;
+exports.describeDanglingRegistration = describeDanglingRegistration;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const config_js_1 = require("./config.js");
+/** Where the registry lives. Sibling of `config.json`, under the data dir. */
+function registryPath() {
+    return path.join((0, config_js_1.getDataDir)(), "external-registrations.json");
+}
+function readAll() {
+    try {
+        const raw = fs.readFileSync(registryPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((r) => !!r &&
+            typeof r.harness === "string" &&
+            typeof r.root === "string" &&
+            !!r.remove);
+    }
+    catch {
+        // Absent or unreadable: nothing recorded is the safe reading. This registry
+        // only ever drives best-effort cleanup, so a parse failure must not throw
+        // into an install or a reset.
+        return [];
+    }
+}
+function writeAll(entries) {
+    const dir = (0, config_js_1.getDataDir)();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(registryPath(), JSON.stringify(entries, null, 2) + "\n");
+}
+/** Every registration currently recorded. */
+function loadExternalRegistrations() {
+    return readAll();
+}
+/**
+ * Record (or refresh) the registration for a harness. Idempotent: re-running an
+ * install replaces the harness's entry rather than appending a duplicate.
+ */
+function recordExternalRegistration(entry) {
+    const others = readAll().filter((r) => r.harness !== entry.harness);
+    writeAll([...others, entry]);
+}
+/** Forget a harness's registration, after it has been deregistered. */
+function clearExternalRegistration(harness) {
+    const remaining = readAll().filter((r) => r.harness !== harness);
+    if (remaining.length === 0) {
+        fs.rmSync(registryPath(), { force: true });
+        return;
+    }
+    writeAll(remaining);
+}
+/**
+ * Replay every recorded removal. Call this **before** deleting the data dir.
+ *
+ * Entirely best-effort: a foreign tool that is no longer installed, or that
+ * fails the removal, must not stop the reset that is in progress. Results are
+ * returned so the caller can report what happened.
+ */
+function deregisterExternalRegistrations() {
+    const entries = readAll();
+    const results = [];
+    for (const registration of entries) {
+        const { command, args } = registration.remove;
+        try {
+            const result = (0, node_child_process_1.spawnSync)(command, args, {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+                shell: process.platform === "win32",
+                timeout: 30_000,
+            });
+            if (result.status === 0) {
+                results.push({ registration, ok: true });
+            }
+            else {
+                const output = ((result.stdout ?? "") + (result.stderr ?? "")).trim();
+                results.push({
+                    registration,
+                    ok: false,
+                    detail: output || result.error?.message || `exit ${result.status}`,
+                });
+            }
+        }
+        catch (err) {
+            results.push({
+                registration,
+                ok: false,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (entries.length > 0)
+        clearAllExternalRegistrations();
+    return results;
+}
+/** Drop the whole registry (the data dir is about to go anyway). */
+function clearAllExternalRegistrations() {
+    fs.rmSync(registryPath(), { force: true });
+}
+/**
+ * A registration whose target directory has gone missing — the foreign tool is
+ * pointing at nothing, which is the state that breaks it.
+ *
+ * `status` uses this to say what happened and how to fix it, instead of leaving
+ * the user to decode an error from a tool that never mentions Ory.
+ */
+function findDanglingRegistration(harness) {
+    return readAll().find((r) => r.harness === harness && !fs.existsSync(r.root));
+}
+/** One-line remediation for a dangling registration, for `status` output. */
+function describeDanglingRegistration(registration) {
+    const cmd = [registration.remove.command, ...registration.remove.args].join(" ");
+    return (`${registration.description} points at ${registration.root}, which no longer exists — ` +
+        `every '${registration.tool} plugin' command will fail until this is repaired. ` +
+        `Re-run the install to restore it, or remove the stale entry with: ${cmd}`);
+}

package/dist/help-cli.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared `--help` handling for every plugin CLI.
+ *
+ * Each CLI dispatches on `argv[0]` with a `switch`, so `--help` was only ever
+ * recognized in the *subcommand position*. Once a subcommand matched, trailing
+ * flags it did not know were ignored — and `install --help` ran a real install,
+ * writing harness config, registering a marketplace, materializing a runtime,
+ * and connecting against whatever `ORY_PROJECT_URL` / `ORY_OAUTH2_CLIENT_ID`
+ * happened to be in the environment (#222/#221).
+ *
+ * `<cmd> --help` is universal muscle memory for "tell me about this, change
+ * nothing", so it must never carry a side effect.
+ */
+/**
+ * True when the user asked for usage anywhere in `args` rather than in the
+ * subcommand slot — e.g. `install --help`, `local up -h`.
+ *
+ * Deliberately scans the whole tail: the point is that a help request must be
+ * honored wherever it appears, not just where the dispatcher happens to look.
+ * `--` ends the scan so a flag being *passed through* to something else is not
+ * mistaken for a request to this CLI (`install -- --help`).
+ */
+export declare function wantsHelp(args: readonly string[]): boolean;
+/**
+ * Guard for the top of a CLI's `main()`, after `argv` is split.
+ *
+ * Returns true when the CLI should print usage and do nothing else. Call it
+ * *before* the dispatch switch:
+ *
+ * ```ts
+ * const [command, ...args] = process.argv.slice(2);
+ * if (shouldPrintHelp(command, args)) return help();
+ * ```
+ *
+ * A bare `--help` / `help` / no command at all is left to the existing `switch`
+ * arms, which already handle it; this only covers the case the dispatcher
+ * cannot see — a help flag *after* a matched subcommand.
+ */
+export declare function shouldPrintHelp(command: string | undefined, args: readonly string[]): boolean;

package/dist/help-cli.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Shared `--help` handling for every plugin CLI.
+ *
+ * Each CLI dispatches on `argv[0]` with a `switch`, so `--help` was only ever
+ * recognized in the *subcommand position*. Once a subcommand matched, trailing
+ * flags it did not know were ignored — and `install --help` ran a real install,
+ * writing harness config, registering a marketplace, materializing a runtime,
+ * and connecting against whatever `ORY_PROJECT_URL` / `ORY_OAUTH2_CLIENT_ID`
+ * happened to be in the environment (#222/#221).
+ *
+ * `<cmd> --help` is universal muscle memory for "tell me about this, change
+ * nothing", so it must never carry a side effect.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wantsHelp = wantsHelp;
+exports.shouldPrintHelp = shouldPrintHelp;
+/** The flags every CLI accepts as a request for usage. */
+const HELP_FLAGS = new Set(["--help", "-h", "help"]);
+/**
+ * True when the user asked for usage anywhere in `args` rather than in the
+ * subcommand slot — e.g. `install --help`, `local up -h`.
+ *
+ * Deliberately scans the whole tail: the point is that a help request must be
+ * honored wherever it appears, not just where the dispatcher happens to look.
+ * `--` ends the scan so a flag being *passed through* to something else is not
+ * mistaken for a request to this CLI (`install -- --help`).
+ */
+function wantsHelp(args) {
+    for (const arg of args) {
+        if (arg === "--")
+            return false;
+        if (HELP_FLAGS.has(arg))
+            return true;
+    }
+    return false;
+}
+/**
+ * Guard for the top of a CLI's `main()`, after `argv` is split.
+ *
+ * Returns true when the CLI should print usage and do nothing else. Call it
+ * *before* the dispatch switch:
+ *
+ * ```ts
+ * const [command, ...args] = process.argv.slice(2);
+ * if (shouldPrintHelp(command, args)) return help();
+ * ```
+ *
+ * A bare `--help` / `help` / no command at all is left to the existing `switch`
+ * arms, which already handle it; this only covers the case the dispatcher
+ * cannot see — a help flag *after* a matched subcommand.
+ */
+function shouldPrintHelp(command, args) {
+    return command !== undefined && wantsHelp(args);
+}

package/dist/hook-timeout.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hook-timeout windows a harness declares on the entries it installs.
+ *
+ * Every subprocess harness kills a hook that runs past its window. Session
+ * start is the one hook that can legitimately take minutes: it may run the
+ * interactive PKCE browser login, which waits on a human. The tool-lifecycle
+ * hooks only make permission checks.
+ *
+ * **The invariant these constants exist to hold** (asserted in
+ * `hook-timeout.test.ts`): every declared session-start window is strictly
+ * greater than {@link DEFAULT_LOGIN_TIMEOUT_MS}. The login must always
+ * terminate on its own terms and record a clean `timeout` outcome the user can
+ * act on — never be SIGKILLed mid-flow by the harness, which surfaces nothing
+ * and leaves the session with no user identity (and, under `enforce`, every
+ * subsequent tool denied for a reason nothing explains).
+ *
+ * **Units differ per harness and are not guessable** — each was verified
+ * against the harness's own binary, because getting one wrong is silent:
+ *
+ * | Harness      | Unit         | Evidence                                                          |
+ * |--------------|--------------|-------------------------------------------------------------------|
+ * | claude-code  | seconds      | `timeout: number().describe("Timeout in seconds")`, `timeout * 1000` |
+ * | codex        | seconds      | documented per-handler timeout                                     |
+ * | cursor       | seconds      | documented per-hook timeout                                        |
+ * | gemini-cli   | milliseconds | `DEFAULT_HOOK_TIMEOUT = 6e4`; `Hook timed out after ${timeout}ms`  |
+ * | antigravity  | seconds      | `timeout_seconds`; validated `"must be between 5 and 120 seconds"` |
+ *
+ * Antigravity additionally **validates** its range, so it caps what any harness
+ * can be given — which is why the login window has to fit inside 120s.
+ */
+/**
+ * Wall-clock budget for a session-start hook: the interactive login, plus the
+ * agent DCR registration and delegation record that follow it.
+ *
+ * Generous on purpose. It is an upper bound on a hook that is *waiting*, not a
+ * latency target — nothing is spinning, and the login gives up on its own well
+ * before this.
+ */
+export declare const SESSION_START_HOOK_WINDOW_MS = 300000;
+/**
+ * Budget for the tool-lifecycle hooks. A permission check, plus the batched
+ * per-word round trips shell decomposition can add.
+ */
+export declare const TOOL_HOOK_WINDOW_MS = 60000;
+/**
+ * Hard ceiling on a session-start window, per harness, where the harness
+ * validates or silently rejects the value. Antigravity refuses anything over
+ * 120 seconds; the others impose no documented maximum.
+ */
+export declare const HOOK_TIMEOUT_MAX_MS: Readonly<Record<string, number>>;
+/** The unit a harness's hook config expresses timeouts in. */
+export type HookTimeoutUnit = "seconds" | "milliseconds";
+/**
+ * The session-start hook timeout to declare for `harness`, in that harness's
+ * own unit, clamped to any ceiling the harness enforces.
+ *
+ * Throws if the clamped result would not outlast the login. That is a build-time
+ * failure on purpose: a harness whose maximum window is shorter than the login
+ * cannot host the login as it is configured, and shipping it would reintroduce
+ * exactly the silent mid-flow kill this module exists to prevent.
+ */
+export declare function sessionStartHookTimeout(harness: string, unit: HookTimeoutUnit): number;
+/** The tool-lifecycle hook timeout to declare for `harness`, in its own unit. */
+export declare function toolHookTimeout(harness: string, unit: HookTimeoutUnit): number;

package/dist/hook-timeout.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Hook-timeout windows a harness declares on the entries it installs.
+ *
+ * Every subprocess harness kills a hook that runs past its window. Session
+ * start is the one hook that can legitimately take minutes: it may run the
+ * interactive PKCE browser login, which waits on a human. The tool-lifecycle
+ * hooks only make permission checks.
+ *
+ * **The invariant these constants exist to hold** (asserted in
+ * `hook-timeout.test.ts`): every declared session-start window is strictly
+ * greater than {@link DEFAULT_LOGIN_TIMEOUT_MS}. The login must always
+ * terminate on its own terms and record a clean `timeout` outcome the user can
+ * act on — never be SIGKILLed mid-flow by the harness, which surfaces nothing
+ * and leaves the session with no user identity (and, under `enforce`, every
+ * subsequent tool denied for a reason nothing explains).
+ *
+ * **Units differ per harness and are not guessable** — each was verified
+ * against the harness's own binary, because getting one wrong is silent:
+ *
+ * | Harness      | Unit         | Evidence                                                          |
+ * |--------------|--------------|-------------------------------------------------------------------|
+ * | claude-code  | seconds      | `timeout: number().describe("Timeout in seconds")`, `timeout * 1000` |
+ * | codex        | seconds      | documented per-handler timeout                                     |
+ * | cursor       | seconds      | documented per-hook timeout                                        |
+ * | gemini-cli   | milliseconds | `DEFAULT_HOOK_TIMEOUT = 6e4`; `Hook timed out after ${timeout}ms`  |
+ * | antigravity  | seconds      | `timeout_seconds`; validated `"must be between 5 and 120 seconds"` |
+ *
+ * Antigravity additionally **validates** its range, so it caps what any harness
+ * can be given — which is why the login window has to fit inside 120s.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_TIMEOUT_MAX_MS = exports.TOOL_HOOK_WINDOW_MS = exports.SESSION_START_HOOK_WINDOW_MS = void 0;
+exports.sessionStartHookTimeout = sessionStartHookTimeout;
+exports.toolHookTimeout = toolHookTimeout;
+const auth_js_1 = require("./auth.js");
+/**
+ * Wall-clock budget for a session-start hook: the interactive login, plus the
+ * agent DCR registration and delegation record that follow it.
+ *
+ * Generous on purpose. It is an upper bound on a hook that is *waiting*, not a
+ * latency target — nothing is spinning, and the login gives up on its own well
+ * before this.
+ */
+exports.SESSION_START_HOOK_WINDOW_MS = 300_000;
+/**
+ * Budget for the tool-lifecycle hooks. A permission check, plus the batched
+ * per-word round trips shell decomposition can add.
+ */
+exports.TOOL_HOOK_WINDOW_MS = 60_000;
+/**
+ * Hard ceiling on a session-start window, per harness, where the harness
+ * validates or silently rejects the value. Antigravity refuses anything over
+ * 120 seconds; the others impose no documented maximum.
+ */
+exports.HOOK_TIMEOUT_MAX_MS = {
+    antigravity: 120_000,
+};
+function convert(ms, unit) {
+    return unit === "seconds" ? Math.round(ms / 1000) : ms;
+}
+/**
+ * The session-start hook timeout to declare for `harness`, in that harness's
+ * own unit, clamped to any ceiling the harness enforces.
+ *
+ * Throws if the clamped result would not outlast the login. That is a build-time
+ * failure on purpose: a harness whose maximum window is shorter than the login
+ * cannot host the login as it is configured, and shipping it would reintroduce
+ * exactly the silent mid-flow kill this module exists to prevent.
+ */
+function sessionStartHookTimeout(harness, unit) {
+    const ceiling = exports.HOOK_TIMEOUT_MAX_MS[harness];
+    const ms = ceiling
+        ? Math.min(exports.SESSION_START_HOOK_WINDOW_MS, ceiling)
+        : exports.SESSION_START_HOOK_WINDOW_MS;
+    if (ms <= auth_js_1.DEFAULT_LOGIN_TIMEOUT_MS) {
+        throw new Error(`Session-start hook window for "${harness}" (${ms}ms) does not outlast the ` +
+            `login timeout (${auth_js_1.DEFAULT_LOGIN_TIMEOUT_MS}ms). The login would be killed ` +
+            `mid-flow. Lower DEFAULT_LOGIN_TIMEOUT_MS or raise the harness ceiling.`);
+    }
+    return convert(ms, unit);
+}
+/** The tool-lifecycle hook timeout to declare for `harness`, in its own unit. */
+function toolHookTimeout(harness, unit) {
+    const ceiling = exports.HOOK_TIMEOUT_MAX_MS[harness];
+    const ms = ceiling ? Math.min(exports.TOOL_HOOK_WINDOW_MS, ceiling) : exports.TOOL_HOOK_WINDOW_MS;
+    return convert(ms, unit);
+}

package/dist/index.d.ts

@@ -1,37 +1,42 @@
-export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, } from "./client.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 OryDelegationRecord, type PermissionMode, } from "./config.js";
+export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, type RecordDelegationInput, type RecordDelegationResult, } from "./client.js";
+export { authenticatedRuntimeRequest, canonicalCredentialIdentity, canonicalProjectUrl, credentialAccount, configureSystemCaTrustForDefaultFetch, createOsTalosCredentialStore, enrollTalosChildRuntimeCredential, enrollTalosRuntimeCredential, resolveRuntimeCredential, runCredentialStoreCommand, talosRuntimeCredential, type CredentialStoreCommandOptions, type CredentialStoreCommandRunner, type ResolveRuntimeCredentialOptions, type EnrollTalosChildRuntimeCredentialOptions, type EnrollTalosRuntimeCredentialOptions, type EnrolledRuntimeCredential, type OsTalosCredentialStoreOptions, type NodeTlsCaProvider, type StoredTalosCredential, type TalosCredentialStore, type TalosCredentialIdentity, type RuntimeAuthenticatedRequest, type RuntimeAuthorizationHeader, type RuntimeCredential, type RuntimeCredentialKind, type RuntimeRequestAuthenticator, } from "./runtime-credential.js";
+export { DebugLogger, ActiveActivity, redactLogData, formatLogEntry, withQuietStderr, type LogEntry, type LogLevel, type ActivityEntry, type ActivityStatus, type UnifiedLogEntry, type ActivityEnricher, type ActivitySink, } from "./logger.js";
+export { AgentSecurityEventReporter, SERVER_ACTIVITY_EVENTS, projectActivityEntry, type EventReporterOptions, type ServerActivityEvent, } from "./event-reporter.js";
+export { currentSessionContext, withSessionContext, setSessionContext, clearSessionContext, type SessionContext, } from "./context.js";
+export { loadConfig, saveConfig, resolveConfig, isSecurityConnected, describeSecurityGap, type SecurityConnection, mutateConfig, getConfigPath, getDataDir, getHarnessDataDir, listInstalledHarnesses, registerInstalledHarness, unregisterInstalledHarness, UNKNOWN_HARNESS_KEY, SESSIONLESS_KEY, type OryPluginConfig, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, type OryDelegationRecord, type PermissionMode, type PermissionModeCache, } from "./config.js";
+export { resolvePermissionMode, warmPermissionModeCache, resetPermissionModeCache, type PermissionModeSource, type ResolvedPermissionMode, type ModeSubject, } from "./permission-mode.js";
 export { pkceLogin, refreshAccessToken, detectHeadless, generateCodeVerifier, sha256Base64Url, buildAuthorizeUrl, LOOPBACK_PORTS, DEFAULT_LOGIN_TIMEOUT_MS, type PkceLoginOptions, type PkceLoginOutcome, type PkceDeclineReason, } from "./auth.js";
+export { wantsHelp, shouldPrintHelp } from "./help-cli.js";
+export { loadExternalRegistrations, recordExternalRegistration, clearExternalRegistration, clearAllExternalRegistrations, deregisterExternalRegistrations, findDanglingRegistration, describeDanglingRegistration, type ExternalRegistration, type DeregisterResult, } from "./external-registrations.js";
+export { SESSION_START_HOOK_WINDOW_MS, TOOL_HOOK_WINDOW_MS, HOOK_TIMEOUT_MAX_MS, sessionStartHookTimeout, toolHookTimeout, type HookTimeoutUnit, } from "./hook-timeout.js";
 export { loadTokens, saveTokens, clearTokens, isExpired, refreshAndSave, tryAcquirePkceFlightLock, clearPkceFlightLock, waitForPeerTokens, waitForPeerTokensSync, TOKEN_EXPIRY_SKEW_SEC, type PkceFlightLock, } from "./auth-store.js";
 export { ensureUserAuthenticated, ensureAuthenticated, type UserLoginDecision, type UserLoginMode, type UserLoginOptions, } from "./user-login.js";
-export { resolveAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, saveAgentDynamicCredentials, clearAgentDynamicCredentials, loadSubAgentDynamicCredentials, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, revokeAgentDynamicClient, AGENT_TOKEN_EXPIRY_SKEW_SEC, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type DelegationInput, type RevokeAgentClientResult, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.js";
-export { clearCredentialsForUninstall, type ClearCredentialsOptions, type ClearCredentialsResult, } from "./uninstall.js";
+export { resolveAgentCredentials, resolveRuntimeAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, loadAgentDynamicCredentialsByHarness, saveAgentDynamicCredentials, clearAgentDynamicCredentials, latestAgentRegistration, latestSubAgentSession, countAgentSessions, claimAgentDynamicCredentials, loadSubAgentDynamicCredentials, loadAllSubAgentDynamicCredentials, loadSubAgentDynamicCredentialsByHarness, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, clearSubAgentDynamicCredentialsForHarness, claimSubAgentDynamicCredentials, loadDelegationNodeId, saveDelegationNodeId, loadRetiredCredentials, clearRetiredCredentials, retireAgentSessions, sessionRetention, revokeAgentDynamicClient, AGENT_TOKEN_EXPIRY_SKEW_SEC, DEFAULT_SESSION_RETENTION, type AgentRegistrationClaim, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type ResolveRuntimeAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type DelegationInput, type RevokeAgentClientResult, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.js";
+export { ensureReadCredential, resetReadCredentialBackoff, READ_CREDENTIAL_RETRY_MS, type EnsureReadCredentialOptions, type ReadCredentialOutcome, } from "./read-credential.js";
+export { clearCredentialsForUninstall, resolveInstalledHarnesses, type ClearCredentialsOptions, type ClearCredentialsResult, } from "./uninstall.js";
 export { type SessionInfo, type OAuth2TokenInfo, type PermissionCheck, type PermissionResult, type BatchPermissionResult, type OryError, type OryErrorCode, } from "./types.js";
-export { runConfigureCommand, runAgentCommand, printOryConfig, printEnvironment, printLogTail, printEnvHelp, printTraceTail, runWatchCommand, isTtyAvailable, promptOnTty, promptForProjectUrl, interactiveConfigPrompt, } from "./cli.js";
+export { runConfigureCommand, runAgentCommand, printOryConfig, printEnvironment, printLogTail, printEnvHelp, isTtyAvailable, promptOnTty, promptForProjectUrl, interactiveConfigPrompt, } from "./cli.js";
 export { oryNpx } from "./cli-invocation.js";
-export { runPermissionsCommand, isUserIdentityCached, maybeAutoBootstrap, printPermissionsOnboardingHelp, } from "./permissions-cli.js";
-export { runInteractiveSetup, runPostInstall, projectUrlFromSlug, LOOPBACK_REDIRECT_URIS, type OryCliRunner, type OryExecResult, type InteractiveSetupDeps, type InteractiveSetupOutcome, type InteractiveSetupResult, } from "./interactive-setup.js";
+export { runPermissionsCommand } from "./permissions-cli.js";
+export { runWatchCommand, type WatchCommandOptions } from "./watch-cli.js";
+export { runPostInstall } from "./post-install.js";
 export { runStatusCommand, printUserIdentitySection, printAgentIdentitySection, printPermissionsSection, type StatusCommandOptions, } from "./status-cli.js";
 export { collectStatusReport, probePermissionsCoverage, type StatusReport, type StatusConfigSection, type StatusUserSection, type StatusAgentSection, type StatusPermissionsSection, type StatusActivitySection, type PermissionsCoverage, } from "./status-data.js";
-export { ensureOryCli, isSignedIn, listWorkspaces, createWorkspace, createProject, resolveProjectUrl, getDcrState, enableDcrAction, provisionOAuth2Client, saveNetworkConfig, runFullSetup, inspectPermissions, provisionPermissions, grantToolPermissions, provisionProjectApiKey, configureAuditOnly, configureLocalStack, type SetupActionDeps, type LocalStackResult, type FullSetupResult, } from "./setup-actions.js";
-export { canLaunchBrowser, launchWebInstaller, launchWebDashboard, } from "./web/launch.js";
-export { startServer, type RunningServer } from "./web/server.js";
-export type { WebAppMode, BootstrapPayload } from "./web/types.js";
 export { runVersionCommand, collectVersionInfo, resolveBuildInfo, type BuildInfo, type VersionInfo, type VersionCommandOptions, } from "./version-cli.js";
-export { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, resolveHookCommand, pinHookToLocalRegistry, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, nextStepsSink, beginDeferNextSteps, emitDeferredNextSteps, resolveMcpServerCommand, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
-export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./dev.js";
+export { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, nextStepsSink, beginDeferNextSteps, emitDeferredNextSteps, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
+export { wireRuntime, resolveRuntimeForInstall, materializeRuntime, linkedRuntime, resolveRuntimeEntry, resolveMcpRuntimeEntry, writeHookShim, writeMcpShim, hookCommand, mcpCommand, isOryRuntimeCommand, requireHookCommand, moduleSpecifier, getRuntimeRoot, getRuntimeStoreDir, getShimDir, getHookShimPath, getMcpShimPath, readRuntimeManifest, recordRuntimeWiring, getRuntimeWiring, removeRuntimeWiring, pruneRuntimeStores, checkRuntimeHealth, describeRuntimeHealth, defaultNpmInstaller, MCP_SERVER_PACKAGE, type RuntimeTarget, type RuntimeWiring, type RuntimeManifest, type RuntimeHealth, type NpmInstaller, type PreparedRuntime, } from "./runtime.js";
+export { renderMirrorBootstrap, type MirrorBootstrapKind, type MirrorBootstrapOptions, } from "./mirror-bootstrap.js";
 export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";
-export { runLocalCommand, ensureDevJaeger, stopDevJaeger, DEV_JAEGER_CONTAINER, type EnsureDevJaegerResult, type StopDevJaegerResult, } from "./local/index.js";
+export { runLocalCommand, } from "./local/index.js";
 export { runRegistryCommand, REGISTRY_URL } from "./registry/index.js";
-export { checkAndDecide, applyPermissionMode, gateToolCall, type PermissionDecision, type ModeDecision, type DecisionSpanAttributes, type CheckAndDecideOptions, type ApplyPermissionModeContext, type GateToolCallArgs, type ToolGateOutcome, } from "./permissions.js";
-export { HARNESS_TOOL_CATALOG, KNOWN_HARNESSES, ALL_TOOLS, getToolCatalog, INTERACTIVE_TOOL_CATALOG, getInteractiveToolCatalog, isInteractiveTool, type KnownHarness, } from "./tool-catalog.js";
+export { checkAndDecide, applyPermissionMode, gateToolCall, decomposeAndCheck, resolveCheckRelation, type PermissionDecision, type ModeDecision, type DecisionActivityAttributes, type CheckAndDecideOptions, type ApplyPermissionModeContext, type GateToolCallArgs, type PrincipalBlockSubjects, type ToolGateOutcome, type BlockReason, } from "./permissions.js";
+export { extractShellCommands, extractBashCommandWords, type ParsedShell, type ShellCommand, type ShellRedirect, type ShellAssignment, type BashParseResult, } from "./bash-parser.js";
+export { buildAgentSecurityOpl, renderToolNamespaceClass, renderDelegationNamespaceClass, renderPermissionModeNamespaceClass, renderAgentRoleNamespaceClass, renderEnrollmentNamespaceClass, renderPrincipalClass, renderOplImport, OPL_IMPORT_MODULE, OPL_IMPORT_SYMBOLS, PRINCIPAL_NAMESPACES, NODE_REFERENCE_NAMESPACES, AGENT_NODE_NAMESPACE, SUBAGENT_NODE_NAMESPACE, RELATION_USERS, RELATION_BLOCKED_SUBJECTS, RELATION_DELEGATES, RELATION_CREDENTIALS, RELATION_ENFORCED_SUBJECTS, RELATION_MEMBERS, RELATION_OPTED_OUT_SUBJECTS, PERMISSION_MODE_OBJECT, AUTO_ENROLL_OBJECT, PROJECT_POSTURE_OBJECT, PERMISSION_MODE_NAMESPACE, DELEGATION_NAMESPACE, AGENT_ROLE_NAMESPACE, ENROLLMENT_NAMESPACE, PERMIT_USE, DEFAULT_NAMESPACE, DEFAULT_SHELL_NAMESPACE, } from "./opl.js";
+export { HARNESS_TOOL_CATALOG, KNOWN_HARNESSES, ALL_TOOLS, getToolCatalog, INTERACTIVE_TOOL_CATALOG, getInteractiveToolCatalog, isInteractiveTool, SHELL_TOOL_CATALOG, getShellToolCatalog, isShellTool, SHELL_COMMAND_CATALOG, getShellCommandCatalog, resolveShellCommandNamespace, extractShellCommand, type KnownHarness, } from "./tool-catalog.js";
 export { classifyLifecycle, isUserFacingPhase, isToolExecutionPhase, HARNESS_LIFECYCLE_MAP, USER_FACING_PHASES, TOOL_EXECUTION_PHASES, type LifecyclePhase, } from "./lifecycle.js";
 export { parseClaudeCodeMcpTool, parseGeminiMcpTool, parseMcpToolGeneric, checkMcpPermission, type McpToolIdentifier, type McpPermissionCheckOptions, type McpPermissionResult, } from "./mcp.js";
-export { resolveUserSubject, runWithUserSubject, subjectLabel, type UserSubjectRef, } from "./subject.js";
-export { formatDenialMessage, formatDenialSummary, formatAlertMessage, formatAlertSummary, alertAttributes, OryDenialError, type DenialContext, type AlertAttributes, } from "./denial.js";
+export { resolveUserSubject, runWithUserSubject, subjectLabel, resolveAgentSubject, resolveAgentSessionSubject, resolveSubAgentSubject, resolveSubAgentSpawnSubject, AGENT_NAMESPACE, SUBAGENT_NAMESPACE, SESSION_NAMESPACE, DEFAULT_USER_SUBJECT_NAMESPACE, type UserSubjectRef, } from "./subject.js";
+export { formatDenialMessage, formatDenialSummary, formatAlertMessage, formatAlertSummary, alertAttributes, shellDenialFields, 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, writeUserDelegatesAgent, writeAgentDelegatesSubagent, wrapTool, type SessionStartResult, type SessionStartOptions, type RegisterSubagentOptions, type GateResult, type GateOptions, type WrapToolOptions, } from "./adapters.js";
+export { resolveNamespace, sessionStart, createSessionStarter, withHookContext, decideTool, gate, complete, fail, registerSubagent, writeUserDelegatesAgent, writeAgentDelegatesSubagent, wrapTool, type SessionStartResult, type SessionStartOptions, type HookContextOptions, type RegisterSubagentOptions, type GateResult, type GateOptions, type WrapToolOptions, } from "./adapters.js";
 export { collectSystemServices, type StatusSystemSection, type StatusSystemService, } from "./status-system.js";
-export { runDashboardCommand } from "./dashboard-cli.js";