@ory/argus 0.1.0

package/dist/dev.d.ts

@@ -0,0 +1,95 @@
+import { type SeedResult } from "./local/seed.js";
+export interface InstallContext {
+    /** Absolute path to the sandbox directory used as install/launch cwd. */
+    sandboxDir: string;
+    /**
+     * Run `npm install <package>` inside the sandbox against the local registry.
+     * Defaults the package name to `@ory/<harnessName>`.
+     */
+    npmInstall(packageName?: string): void;
+    /**
+     * Run `npx --package=<pkg> <bin> ...args` from the sandbox cwd against the
+     * local registry. Defaults the package to `@ory/<harnessName>`
+     * and the binary to the launcher's configured `binaryName` (or
+     * `ory-<harnessName>` if not set).
+     */
+    npxCli(args: string[], opts?: {
+        packageName?: string;
+        binaryName?: string;
+    }): void;
+}
+export interface DevLauncherConfig {
+    /** Harness identifier — used for sandbox dir name and default package name, e.g. "claude-code" */
+    harnessName: string;
+    /** CLI command to launch, e.g. "claude", "codex", "gemini", "opencode" */
+    command: string;
+    /** Absolute path to the plugin package root (used to locate the workspace root) */
+    packageRoot: string;
+    /**
+     * Default binary name for `npxCli` calls. Defaults to `ory-<harnessName>`.
+     * Override when the plugin's published binary doesn't match the harness
+     * directory name (e.g. claude-code exposes `ory-claude`, gemini-cli exposes
+     * `ory-gemini`).
+     */
+    binaryName?: string;
+    /**
+     * Run the harness's documented install flow (the README's `npx ory-<harness> install`
+     * commands) against the local registry. Each launcher invokes the install steps
+     * appropriate for its harness — the launcher itself never hand-writes config files.
+     */
+    install(ctx: InstallContext): void;
+    /** Extra tip lines to print before launch */
+    extraTips?: string[];
+}
+/**
+ * Parse the dev-launcher CLI args, splitting out launcher-only flags from the
+ * args that should be forwarded to the harness binary.
+ *
+ * Launcher-only flags:
+ *   --no-local   Opt out of the auto-managed local Ory stack (local Ory is
+ *                the default so multiple plugins can share one stack).
+ *   --fresh      Wipe runtime state before launching: stop and remove the
+ *                local Ory stack, Verdaccio registry, and Jaeger container
+ *                (including their volumes and on-disk state), remove this
+ *                harness's sandbox dir, and delete the shared user config
+ *                dir. Build artifacts and node_modules are not touched —
+ *                use `pnpm clean:all` followed by `pnpm install` for that.
+ */
+export declare function parseDevLauncherArgs(argv: readonly string[]): {
+    noLocalFlag: boolean;
+    freshFlag: boolean;
+    forwardedArgs: string[];
+};
+/**
+ * Decide whether the dev launcher should bring up a local Ory stack and seed
+ * it for the harness to authenticate against. Local Ory is the default so
+ * multiple harness plugins can share a single stack while developing — that
+ * mimics the production case of many harnesses sharing one Ory deployment.
+ *
+ * Returns `false` only when the run was explicitly opted out, either via the
+ * `--no-local` CLI flag or by setting `ORY_DEV_LOCAL` to a falsy value
+ * (`0`, `false`, `no`, `off`).
+ */
+export declare function isLocalOryEnabled(noLocalFlagPresent: boolean, envValue: string | undefined): boolean;
+/**
+ * Run a dev launcher with the given configuration.
+ *
+ * Auto-starts the local Verdaccio registry, publishes the harness plugin
+ * (with its workspace dependency closure) and `@ory/mcp-server`
+ * to it, then invokes each plugin's documented install commands (the same
+ * `npx ory-<harness> install` steps from the README) against the local
+ * registry. The launcher itself never hand-writes harness config — the
+ * plugin's own install logic is the source of truth.
+ */
+export declare function runDevLauncher(config: DevLauncherConfig): Promise<void>;
+/**
+ * Compose the harness env when local Ory is active. Wires up both
+ * principals' credentials so the user gate runs real PKCE against local
+ * Hydra and the agent gate runs RFC 7591 dynamic registration.
+ *
+ * The launcher always demonstrates the full UX — no opt-out into
+ * env-token short-circuits. The user gate is forced on and the browser
+ * flow fires every session against the seeded identity. Any pre-supplied
+ * tokens leaking from the parent shell are explicitly cleared.
+ */
+export declare function buildLocalOryEnv(gatewayUrl: string, seed: SeedResult): Record<string, string | undefined>;

package/dist/dev.js

@@ -0,0 +1,514 @@
+"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.parseDevLauncherArgs = parseDevLauncherArgs;
+exports.isLocalOryEnabled = isLocalOryEnabled;
+exports.runDevLauncher = runDevLauncher;
+exports.buildLocalOryEnv = buildLocalOryEnv;
+const crypto = __importStar(require("node:crypto"));
+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("./registry/config.js");
+const manager_js_1 = require("./registry/manager.js");
+const jaeger_js_1 = require("./local/jaeger.js");
+const manager_js_2 = require("./local/manager.js");
+const configs_js_1 = require("./local/configs.js");
+const seed_js_1 = require("./local/seed.js");
+const auth_store_js_1 = require("./auth-store.js");
+const config_js_2 = require("./config.js");
+const tracer_js_1 = require("./tracer.js");
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function ensureSandboxManifest(sandboxDir, harnessName) {
+    const manifestPath = path.join(sandboxDir, "package.json");
+    if (fs.existsSync(manifestPath))
+        return;
+    fs.writeFileSync(manifestPath, JSON.stringify({ name: `ory-sandbox-${harnessName}`, private: true, version: "0.0.0" }, null, 2) + "\n");
+}
+function assertNpmAvailable() {
+    const result = (0, node_child_process_1.spawnSync)("npm", ["--version"], { stdio: "ignore" });
+    if (result.error || result.status !== 0) {
+        throw new Error("`npm` is not on PATH. The dev launcher uses npm/npx to run each plugin's documented install commands.");
+    }
+}
+function defaultBinaryName(harnessName) {
+    return `ory-${harnessName}`;
+}
+/**
+ * Parse the dev-launcher CLI args, splitting out launcher-only flags from the
+ * args that should be forwarded to the harness binary.
+ *
+ * Launcher-only flags:
+ *   --no-local   Opt out of the auto-managed local Ory stack (local Ory is
+ *                the default so multiple plugins can share one stack).
+ *   --fresh      Wipe runtime state before launching: stop and remove the
+ *                local Ory stack, Verdaccio registry, and Jaeger container
+ *                (including their volumes and on-disk state), remove this
+ *                harness's sandbox dir, and delete the shared user config
+ *                dir. Build artifacts and node_modules are not touched —
+ *                use `pnpm clean:all` followed by `pnpm install` for that.
+ */
+function parseDevLauncherArgs(argv) {
+    let noLocalFlag = false;
+    let freshFlag = false;
+    const forwardedArgs = [];
+    for (const arg of argv) {
+        if (arg === "--no-local") {
+            noLocalFlag = true;
+            continue;
+        }
+        if (arg === "--fresh") {
+            freshFlag = true;
+            continue;
+        }
+        forwardedArgs.push(arg);
+    }
+    return { noLocalFlag, freshFlag, forwardedArgs };
+}
+/**
+ * Decide whether the dev launcher should bring up a local Ory stack and seed
+ * it for the harness to authenticate against. Local Ory is the default so
+ * multiple harness plugins can share a single stack while developing — that
+ * mimics the production case of many harnesses sharing one Ory deployment.
+ *
+ * Returns `false` only when the run was explicitly opted out, either via the
+ * `--no-local` CLI flag or by setting `ORY_DEV_LOCAL` to a falsy value
+ * (`0`, `false`, `no`, `off`).
+ */
+function isLocalOryEnabled(noLocalFlagPresent, envValue) {
+    if (noLocalFlagPresent)
+        return false;
+    if (envValue === undefined)
+        return true;
+    const v = envValue.trim().toLowerCase();
+    if (v === "" || v === "0" || v === "false" || v === "no" || v === "off") {
+        return false;
+    }
+    return true;
+}
+function npmEnv() {
+    // Env shared by every install/runtime subprocess so npm/npx pulls from
+    // the local registry through an isolated pacote cache, with the user's
+    // supply-chain freshness gate disabled (otherwise just-published tarballs
+    // get filtered out as `ENOVERSIONS — No versions available`).
+    return {
+        ...process.env,
+        npm_config_registry: config_js_1.REGISTRY_URL,
+        npm_config_cache: (0, manager_js_1.getLocalRegistryNpmCacheDir)(),
+        npm_config_min_release_age: "0",
+    };
+}
+function buildInstallContext(harnessName, sandboxDir, binaryName) {
+    const defaultPackage = `@ory/${harnessName}`;
+    const defaultBin = binaryName ?? defaultBinaryName(harnessName);
+    return {
+        sandboxDir,
+        npmInstall(packageName = defaultPackage) {
+            // npm 11's arborist crashes (`Cannot read properties of null (reading
+            // 'matches')`) when running `npm install <pkg>` in a cwd that has no
+            // `package.json`, so seed a minimal manifest before installing.
+            ensureSandboxManifest(sandboxDir, harnessName);
+            console.log(`[ory-dev] npm install ${packageName} (sandbox: ${sandboxDir})`);
+            // `--min-release-age=0` must come from the CLI flag — config-file values
+            // can't override a user-level `min-release-age` setting in npm 11.
+            const result = (0, node_child_process_1.spawnSync)("npm", [
+                "install",
+                packageName,
+                "--no-audit",
+                "--no-fund",
+                "--loglevel=error",
+                "--min-release-age=0",
+                "--save=false",
+            ], { cwd: sandboxDir, stdio: "inherit", env: npmEnv() });
+            if (result.status !== 0) {
+                throw new Error(`npm install ${packageName} failed (exit ${result.status}).`);
+            }
+        },
+        npxCli(args, opts = {}) {
+            const packageName = opts.packageName ?? defaultPackage;
+            const binaryName = opts.binaryName ?? defaultBin;
+            console.log(`[ory-dev] npx --package=${packageName} ${binaryName} ${args.join(" ")}`);
+            const result = (0, node_child_process_1.spawnSync)("npx", [
+                "--yes",
+                `--package=${packageName}`,
+                binaryName,
+                ...args,
+            ], { cwd: sandboxDir, stdio: "inherit", env: npmEnv() });
+            if (result.status !== 0) {
+                throw new Error(`npx --package=${packageName} ${binaryName} ${args.join(" ")} failed (exit ${result.status}).`);
+            }
+        },
+    };
+}
+/**
+ * Wipe all runtime state the launcher can safely reset without breaking the
+ * running process: docker containers + volumes for the local Ory stack,
+ * Verdaccio registry, and Jaeger; the on-disk `.sandbox/<harness>` and
+ * `.ory-dev/` directories; and the shared user config dir. Build artifacts
+ * and node_modules are out of scope — those require a separate
+ * `pnpm clean:all && pnpm install`.
+ *
+ * Every step is best-effort: any failure is logged as a warning and the
+ * reset continues. The launcher then re-bootstraps everything from scratch.
+ */
+async function performFreshReset(sandbox) {
+    console.log("[ory-dev] --fresh: wiping runtime state...");
+    try {
+        await (0, manager_js_2.localReset)();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[ory-dev] --fresh: local Ory reset failed: ${msg}. Continuing.`);
+    }
+    try {
+        await (0, manager_js_1.registryClean)();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[ory-dev] --fresh: registry clean failed: ${msg}. Continuing.`);
+    }
+    const jaegerResult = (0, jaeger_js_1.stopDevJaeger)();
+    if (jaegerResult.status === "error") {
+        console.warn(`[ory-dev] --fresh: Jaeger stop failed: ${jaegerResult.detail ?? "unknown"}. Continuing.`);
+    }
+    if (fs.existsSync(sandbox)) {
+        fs.rmSync(sandbox, { recursive: true, force: true });
+        console.log(`[ory-dev] --fresh: removed ${sandbox}`);
+    }
+    const dataDir = (0, config_js_2.getDataDir)();
+    if (fs.existsSync(dataDir)) {
+        fs.rmSync(dataDir, { recursive: true, force: true });
+        console.log(`[ory-dev] --fresh: removed ${dataDir}`);
+    }
+    console.log("[ory-dev] --fresh: reset complete.");
+}
+/**
+ * Run a dev launcher with the given configuration.
+ *
+ * Auto-starts the local Verdaccio registry, publishes the harness plugin
+ * (with its workspace dependency closure) and `@ory/mcp-server`
+ * to it, then invokes each plugin's documented install commands (the same
+ * `npx ory-<harness> install` steps from the README) against the local
+ * registry. The launcher itself never hand-writes harness config — the
+ * plugin's own install logic is the source of truth.
+ */
+async function runDevLauncher(config) {
+    const workspaceRoot = path.resolve(config.packageRoot, "..", "..");
+    const sandbox = path.resolve(workspaceRoot, ".sandbox", config.harnessName);
+    const localOryDir = path.resolve(workspaceRoot, ".ory-dev", "ory");
+    const logFile = path.resolve(sandbox, "ory-agent-debug.log");
+    const traceFile = path.resolve(sandbox, "ory-agent-trace.ndjson");
+    const { noLocalFlag, freshFlag, forwardedArgs } = parseDevLauncherArgs(process.argv.slice(2));
+    const localEnabled = isLocalOryEnabled(noLocalFlag, process.env.ORY_DEV_LOCAL);
+    if (freshFlag) {
+        await performFreshReset(sandbox);
+    }
+    // Belt-and-suspenders: each dev launch is the sole owner of its
+    // session, so a stale pkce-flight lock from a previous run that died
+    // mid-flow (browser closed, harness crashed, login UI 404'd, etc.)
+    // would only block the next launch. Sweep it. The in-process gate's
+    // own staleness check would catch this within 5 minutes, but the
+    // explicit sweep makes the dev loop tight.
+    if ((0, auth_store_js_1.clearPkceFlightLock)()) {
+        console.log("[ory-dev] Cleared stale PKCE flight lock from a previous run.");
+    }
+    assertNpmAvailable();
+    console.log(`[ory-dev] Ensuring local npm registry is running...`);
+    await (0, manager_js_1.ensureRegistryRunning)();
+    console.log(`[ory-dev] Publishing @ory/${config.harnessName} (and mcp-server) to ${config_js_1.REGISTRY_URL}...`);
+    await (0, manager_js_1.publishHarnessToLocal)(config.harnessName);
+    ensureDir(sandbox);
+    console.log(`[ory-dev] Running install flow for @ory/${config.harnessName}...`);
+    const ctx = buildInstallContext(config.harnessName, sandbox, config.binaryName);
+    config.install(ctx);
+    // Each dev launch gets a fresh unique session subject so traces/permission
+    // checks are distinguishable across runs. Used as the harness's
+    // ORY_AGENT_SUBJECT_ID unless local-Ory mode supplies a real seeded session.
+    const sessionName = `ory-sandbox-${crypto.randomBytes(6).toString("hex")}`;
+    // When the user opts into local Ory, bring the docker stack up (or reuse
+    // it) and seed two identities (agent + user). The harness env is then
+    // wired so the user gate runs real browser PKCE against local Hydra and
+    // the agent gate runs RFC 7591 dynamic client registration.
+    const localOry = localEnabled
+        ? await bootstrapLocalOry(localOryDir)
+        : { active: false };
+    console.log(`[ory-dev] Launching ${config.harnessName} with Ory plugin...`);
+    console.log(`[ory-dev] Sandbox: ${sandbox}`);
+    if (localOry.active) {
+        const seed = localOry.seed;
+        console.log("");
+        console.log("[ory-dev] ──────────────────────────────────────────────────");
+        console.log(`[ory-dev]   Local Ory ready.`);
+        console.log(`[ory-dev]   API gateway: ${localOry.gatewayUrl}`);
+        console.log(`[ory-dev]   Console:     ${configs_js_1.CONSOLE_URL}`);
+        console.log(`[ory-dev]   Jaeger:      ${configs_js_1.JAEGER_UI_URL}`);
+        console.log(`[ory-dev]`);
+        console.log(`[ory-dev]   When the browser opens for login, sign in as:`);
+        console.log(`[ory-dev]     email:    ${seed.user.identity.email}`);
+        console.log(`[ory-dev]     password: ${seed.user.password}`);
+        console.log("[ory-dev] ──────────────────────────────────────────────────");
+        console.log("");
+    }
+    else {
+        console.log(`[ory-dev] Session: ${sessionName}`);
+    }
+    console.log(`[ory-dev] Debug log: ${logFile}`);
+    console.log(`[ory-dev] Trace file: ${traceFile}`);
+    console.log(`[ory-dev] npm registry: ${config_js_1.REGISTRY_URL} (local)`);
+    if (config.extraTips) {
+        for (const tip of config.extraTips) {
+            console.log(`[ory-dev] ${tip}`);
+        }
+    }
+    const otelEndpoint = await resolveOtelEndpoint();
+    if (otelEndpoint) {
+        console.log(`[ory-dev] OTLP endpoint: ${otelEndpoint}`);
+    }
+    console.log(`[ory-dev] Tip: tail -f ${logFile} | jq .  — live debug log`);
+    console.log(`[ory-dev] Tip: pnpm watch:traces ${config.harnessName}  — live trace stream\n`);
+    const env = {
+        ...npmEnv(),
+        ORY_AGENT_DEBUG: "true",
+        ORY_AGENT_LOG_FILE: logFile,
+        ORY_AGENT_TRACE_FILE: traceFile,
+        ...(localOry.active
+            ? buildLocalOryEnv(localOry.gatewayUrl, localOry.seed)
+            : { ORY_AGENT_SUBJECT_ID: sessionName }),
+        ...(otelEndpoint
+            ? {
+                OTEL_EXPORTER_OTLP_ENDPOINT: otelEndpoint,
+                // ORY-prefixed alias for harnesses (e.g. Claude Code) that
+                // filter the env passed to hook subprocesses and drop
+                // OTEL_*-prefixed vars. The OTLP exporter reads this as a
+                // fallback so traces still reach Jaeger when OTEL_* is stripped.
+                ORY_OTLP_ENDPOINT: otelEndpoint,
+                OTEL_SERVICE_NAME: process.env.OTEL_SERVICE_NAME ??
+                    `ory-agent-plugin-${config.harnessName}`,
+            }
+            : {}),
+    };
+    const result = (0, node_child_process_1.spawnSync)(config.command, forwardedArgs, {
+        cwd: sandbox,
+        stdio: "inherit",
+        env,
+    });
+    printTraceSummary(traceFile);
+    process.exit(result.status ?? 0);
+}
+function printTraceSummary(traceFile) {
+    if (!fs.existsSync(traceFile))
+        return;
+    const raw = fs.readFileSync(traceFile, "utf8").trim();
+    if (!raw)
+        return;
+    const lines = raw.split("\n").filter(Boolean);
+    const spans = [];
+    for (const line of lines) {
+        try {
+            spans.push(JSON.parse(line));
+        }
+        catch {
+            /* skip malformed lines */
+        }
+    }
+    if (spans.length === 0)
+        return;
+    console.log("");
+    console.log(`[ory-dev] Trace summary — ${spans.length} span(s) recorded`);
+    console.log(`[ory-dev] File: ${traceFile}`);
+    const counts = new Map();
+    const statusCounts = new Map();
+    for (const span of spans) {
+        const key = `${span.event}:${span.status}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+        statusCounts.set(span.status, (statusCounts.get(span.status) ?? 0) + 1);
+    }
+    console.log("[ory-dev] By status:");
+    for (const [status, n] of statusCounts) {
+        console.log(`           ${status.padEnd(8)} ${n}`);
+    }
+    console.log("[ory-dev] By event:");
+    const eventTotals = new Map();
+    for (const span of spans) {
+        eventTotals.set(span.event, (eventTotals.get(span.event) ?? 0) + 1);
+    }
+    const sortedEvents = [...eventTotals.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [event, n] of sortedEvents) {
+        console.log(`           ${event.padEnd(22)} ${n}`);
+    }
+    const tail = spans.slice(-10);
+    console.log(`[ory-dev] Last ${tail.length} span(s):`);
+    for (const span of tail) {
+        console.log("           " + (0, tracer_js_1.formatSpan)(span));
+    }
+}
+/**
+ * Compose the harness env when local Ory is active. Wires up both
+ * principals' credentials so the user gate runs real PKCE against local
+ * Hydra and the agent gate runs RFC 7591 dynamic registration.
+ *
+ * The launcher always demonstrates the full UX — no opt-out into
+ * env-token short-circuits. The user gate is forced on and the browser
+ * flow fires every session against the seeded identity. Any pre-supplied
+ * tokens leaking from the parent shell are explicitly cleared.
+ */
+function buildLocalOryEnv(gatewayUrl, seed) {
+    return {
+        ORY_PROJECT_URL: gatewayUrl,
+        ORY_PERMISSION_NAMESPACE: seed.permissions.namespace,
+        // User gate — always on in local dev so the launcher demonstrates
+        // the interactive PKCE login UX end-to-end every session.
+        ORY_AUTH_GATE: "1",
+        // Agent identity — the harness self-registers via DCR on first run
+        // using the user's bearer as the initial access token. No static
+        // client_credentials are seeded; explicitly clear them so a leaking
+        // shell env doesn't preempt the DCR path.
+        ORY_AGENT_CLIENT_ID: undefined,
+        ORY_AGENT_CLIENT_SECRET: undefined,
+        ORY_AGENT_API_KEY: undefined,
+        ORY_AGENT_REGISTRATION_TOKEN: undefined,
+        // User identity — the OAuth2 client used by the PKCE browser flow.
+        // Subject is the bare Kratos identity UUID; the User namespace pairs
+        // with it to form the SubjectSet `User:<id>` the seed writes.
+        ORY_OAUTH2_CLIENT_ID: seed.user.client.clientId,
+        ORY_USER_SUBJECT_NAMESPACE: "User",
+        ORY_USER_SUBJECT_ID: seed.user.identity.id,
+        // Pre-supplied tokens would short-circuit the gate. Always clear
+        // them so the launcher exercises the full PKCE flow.
+        ORY_USER_SESSION_TOKEN: undefined,
+        ORY_USER_OAUTH2_TOKEN: undefined,
+        ORY_API_KEY: undefined,
+        ORY_SESSION_TOKEN: undefined,
+        ORY_OAUTH2_TOKEN: undefined,
+    };
+}
+/**
+ * Bring up the local Ory docker stack (Kratos + Keto + Hydra + nginx) and
+ * seed a fresh test identity, returning the gateway URL and seed result so
+ * the launcher can wire ORY_PROJECT_URL + ORY_SESSION_TOKEN into the harness
+ * env.
+ *
+ * Fail-back-with-warning: any failure (Docker missing, compose error, gateway
+ * unhealthy, seed error) is logged and the launcher continues without local
+ * Ory. The harness still launches, and the plugin runs in pass-through mode.
+ */
+async function bootstrapLocalOry(localDir) {
+    console.log("[ory-dev] Local Ory: ensuring docker stack is up...");
+    let stack;
+    try {
+        stack = await (0, manager_js_2.ensureLocalOryStack)({ quiet: true, localDir });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[ory-dev] Local Ory bootstrap failed: ${msg}. Continuing without local Ory.`);
+        return { active: false };
+    }
+    switch (stack.status) {
+        case "already-running":
+            console.log(`[ory-dev] Local Ory: stack already running at ${stack.gatewayUrl} — reusing.`);
+            break;
+        case "started":
+            console.log(`[ory-dev] Local Ory: stack started at ${stack.gatewayUrl}.`);
+            break;
+        case "skipped:no-docker":
+            console.warn(`[ory-dev] Local Ory: ${stack.detail ?? "Docker unavailable."} ` +
+                `Continuing without local Ory.`);
+            return { active: false };
+        case "console-misconfigured":
+            console.warn(`[ory-dev] Local Ory: ${stack.detail ?? "console misconfigured."} ` +
+                `Continuing without local Ory.`);
+            return { active: false };
+        case "compose-failed":
+        case "gateway-unhealthy":
+            console.warn(`[ory-dev] Local Ory: ${stack.detail ?? stack.status}. ` +
+                `Inspect logs with: cd ${stack.localDir} && docker compose logs. ` +
+                `Continuing without local Ory.`);
+            return { active: false };
+    }
+    const gatewayUrl = stack.gatewayUrl ?? "http://localhost:4000";
+    const namespace = process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+    console.log("[ory-dev] Local Ory: seeding test identity + permissions...");
+    let seed;
+    try {
+        seed = await (0, seed_js_1.seedLocalEnvironment)(namespace);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[ory-dev] Local Ory: seed failed (${msg}). Continuing without local Ory.`);
+        return { active: false };
+    }
+    console.log(`[ory-dev] Local Ory: agent ${seed.agent.identity.email}, user ${seed.user.identity.email}, ` +
+        `${seed.permissions.tuples} permission tuples in '${namespace}' for ${seed.permissions.subject}.`);
+    return { active: true, gatewayUrl, seed };
+}
+/**
+ * Determine the OTLP endpoint for the dev launch:
+ *   1. Honor OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+ *      from the parent shell (Honeycomb, custom collector, etc.).
+ *   2. Otherwise auto-launch a local Jaeger container and use it. If Jaeger
+ *      is already reachable (from `local up` or a prior dev launch), reuse
+ *      it without spawning another container.
+ *   3. Otherwise return undefined (file-based traces only) — e.g. when
+ *      Docker is not available on this machine.
+ */
+async function resolveOtelEndpoint() {
+    const fromEnv = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ??
+        process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (fromEnv)
+        return fromEnv;
+    console.log("[ory-dev] Ensuring Jaeger is running for trace viewing...");
+    const result = await (0, jaeger_js_1.ensureDevJaeger)();
+    switch (result.status) {
+        case "already-running":
+            console.log(`[ory-dev] Jaeger reachable (UI: ${result.uiUrl}) — reusing existing container.`);
+            return result.endpoint;
+        case "started":
+            console.log(`[ory-dev] Jaeger started in Docker (UI: ${result.uiUrl}). Run 'pnpm jaeger:down' to stop it.`);
+            return result.endpoint;
+        case "skipped:no-docker":
+            console.log(`[ory-dev] ${result.detail ?? "Docker not available."} Falling back to NDJSON traces only.`);
+            return undefined;
+        case "skipped:probe-failed":
+            console.log(`[ory-dev] ${result.detail ?? "Jaeger did not become healthy in time."} Falling back to NDJSON traces only.`);
+            return undefined;
+        case "error":
+            console.log(`[ory-dev] Jaeger auto-start failed: ${result.detail ?? "unknown error"}. Falling back to NDJSON traces only.`);
+            return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, } from "./client.js";
+export { DebugLogger, redactLogData, type LogEntry, type LogLevel, } from "./logger.js";
+export { Tracer, ActiveSpan, deriveTraceId, formatSpan, watchTraceFile, type TraceEvent, type SpanStatus, type TraceSpan, type SpanOptions, type TracerOptions, type TracerContext, } from "./tracer.js";
+export { loadConfig, saveConfig, resolveConfig, mutateConfig, getConfigPath, getDataDir, getHarnessDataDir, type OryPluginConfig, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, } from "./config.js";
+export { pkceLogin, refreshAccessToken, detectHeadless, generateCodeVerifier, sha256Base64Url, buildAuthorizeUrl, LOOPBACK_PORTS, DEFAULT_LOGIN_TIMEOUT_MS, type PkceLoginOptions, type PkceLoginOutcome, type PkceDeclineReason, } from "./auth.js";
+export { loadTokens, saveTokens, clearTokens, isExpired, refreshAndSave, tryAcquirePkceFlightLock, clearPkceFlightLock, waitForPeerTokens, waitForPeerTokensSync, TOKEN_EXPIRY_SKEW_SEC, type PkceFlightLock, } from "./auth-store.js";
+export { ensureUserAuthenticated, ensureAuthenticated, type AuthGateDecision, type AuthGateMode, type AuthGateOptions, } from "./auth-gate.js";
+export { resolveAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, saveAgentDynamicCredentials, clearAgentDynamicCredentials, loadSubAgentDynamicCredentials, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, AGENT_TOKEN_EXPIRY_SKEW_SEC, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.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 { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, resolveHookCommand, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, resolveMcpServerCommand, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
+export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./dev.js";
+export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";
+export { runLocalCommand, ensureDevJaeger, stopDevJaeger, DEV_JAEGER_CONTAINER, type EnsureDevJaegerResult, type StopDevJaegerResult, } from "./local/index.js";
+export { runRegistryCommand } from "./registry/index.js";
+export { parseClaudeCodeMcpTool, parseGeminiMcpTool, parseMcpToolGeneric, checkMcpPermission, type McpToolIdentifier, type McpPermissionCheckOptions, type McpPermissionResult, } from "./mcp.js";
+export { resolveUserSubject, subjectLabel, type UserSubjectRef, } from "./subject.js";
+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 { OtlpHttpExporter, otlpExporterFromEnv, parseKeyValueList, type SpanExporter, type OtlpHttpExporterOptions, } from "./otel/index.js";