@ory/argus 0.1.0

package/dist/cli.js

@@ -0,0 +1,484 @@
+"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.runConfigureCommand = runConfigureCommand;
+exports.printOryConfig = printOryConfig;
+exports.printEnvironment = printEnvironment;
+exports.printLogTail = printLogTail;
+exports.printEnvHelp = printEnvHelp;
+exports.printTraceTail = printTraceTail;
+exports.runWatchCommand = runWatchCommand;
+exports.isTtyAvailable = isTtyAvailable;
+exports.promptOnTty = promptOnTty;
+exports.promptForProjectUrl = promptForProjectUrl;
+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");
+/**
+ * Shared `configure` command implementation for all plugin CLIs.
+ *
+ * Parses --project-url and --api-key from args. If neither is provided,
+ * shows the current configuration. Otherwise saves the provided values.
+ */
+function runConfigureCommand(binName, args) {
+    let projectUrl;
+    let apiKey;
+    let auditOnly = false;
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case "--project-url":
+                projectUrl = args[++i];
+                break;
+            case "--api-key":
+                apiKey = args[++i];
+                break;
+            case "--audit-only":
+                auditOnly = true;
+                break;
+        }
+    }
+    if (!projectUrl && !apiKey && !auditOnly) {
+        const resolved = (0, config_js_1.resolveConfig)();
+        const configPath = (0, config_js_1.getConfigPath)();
+        console.log("Ory Plugin Configuration");
+        console.log("========================");
+        console.log("");
+        console.log(`Config file: ${configPath}`);
+        console.log(`Project URL: ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
+        console.log(`API Key:     ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
+        console.log(`Audit Only:  ${resolved.auditOnly ? "yes" : "no"}`);
+        console.log("");
+        console.log("To configure:");
+        console.log(`  npx ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log("");
+        console.log("To enable audit logging only (no auth or permission checks):");
+        console.log(`  npx ${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("  export ORY_API_KEY=ory_pat_...");
+        return;
+    }
+    if (auditOnly) {
+        // Audit-only mode: clear projectUrl/apiKey, set auditOnly flag
+        (0, config_js_1.saveConfig)({ auditOnly: true });
+        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)");
+        console.log("");
+        console.log("This configuration is shared across all Ory agent plugins.");
+        return;
+    }
+    const update = {};
+    if (projectUrl)
+        update.projectUrl = projectUrl;
+    if (apiKey)
+        update.apiKey = apiKey;
+    // Clear auditOnly when configuring with a project URL
+    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 (apiKey)
+        console.log(`  API Key: (set)`);
+    console.log("");
+    console.log("This configuration is shared across all Ory agent plugins.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_API_KEY) take precedence when set.");
+}
+/**
+ * Print the "Configuration:" block showing Ory project URL and API key status.
+ */
+function printOryConfig() {
+    const resolved = (0, config_js_1.resolveConfig)();
+    const configPath = (0, config_js_1.getConfigPath)();
+    console.log("Configuration:");
+    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(`  API Key:     ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
+}
+/**
+ * Print the "Environment:" block showing Ory-related environment variables.
+ */
+function printEnvironment() {
+    console.log("");
+    console.log("Environment:");
+    const vars = [
+        ["ORY_SESSION_TOKEN", process.env.ORY_SESSION_TOKEN ? "(set)" : undefined, false],
+        ["ORY_AGENT_SUBJECT_ID", process.env.ORY_AGENT_SUBJECT_ID, false],
+        ["ORY_AGENT_DEBUG", process.env.ORY_AGENT_DEBUG, false],
+        ["ORY_AGENT_LOG_FILE", process.env.ORY_AGENT_LOG_FILE, false],
+        ["ORY_AGENT_TRACE_FILE", process.env.ORY_AGENT_TRACE_FILE, false],
+    ];
+    for (const [name, value, required] of vars) {
+        const display = value ? `${value}` : required ? "NOT SET (required)" : "not set";
+        const icon = value ? "+" : required ? "!" : "-";
+        console.log(`  [${icon}] ${name}: ${display}`);
+    }
+}
+/**
+ * Print the last 5 debug log entries if ORY_AGENT_LOG_FILE is set and exists.
+ */
+function printLogTail() {
+    const logFile = process.env.ORY_AGENT_LOG_FILE;
+    if (logFile && fs.existsSync(logFile)) {
+        const lines = fs.readFileSync(logFile, "utf-8").trim().split("\n");
+        console.log("");
+        console.log(`Debug log: ${logFile} (${lines.length} events)`);
+        console.log("Last 5 events:");
+        for (const line of lines.slice(-5)) {
+            try {
+                const entry = JSON.parse(line);
+                console.log(`  ${entry.timestamp} [${entry.level}] ${entry.event}`);
+            }
+            catch {
+                console.log(`  ${line.slice(0, 120)}`);
+            }
+        }
+    }
+}
+/**
+ * Print the "Configure your Ory credentials" help text.
+ */
+function printEnvHelp(binName) {
+    console.log("");
+    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 --api-key ory_pat_...`);
+    console.log("");
+    console.log("  Option 2 — Set environment variables:");
+    console.log("    export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+    console.log("    export ORY_API_KEY=ory_pat_...");
+    console.log("");
+    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.
+ */
+function printTraceTail() {
+    const traceFile = process.env.ORY_AGENT_TRACE_FILE;
+    if (traceFile && fs.existsSync(traceFile)) {
+        const lines = fs.readFileSync(traceFile, "utf-8").trim().split("\n");
+        console.log("");
+        console.log(`Trace file: ${traceFile} (${lines.length} spans)`);
+        console.log("Last 5 spans:");
+        for (const line of lines.slice(-5)) {
+            try {
+                const span = JSON.parse(line);
+                console.log("  " + (0, tracer_js_1.formatSpan)(span));
+            }
+            catch {
+                console.log(`  ${line.slice(0, 120)}`);
+            }
+        }
+    }
+}
+/**
+ * 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 ?? "";
+    }
+    if (!traceFile) {
+        console.error("Usage: watch <trace-file>\n" +
+            "  Or set ORY_AGENT_TRACE_FILE environment variable.\n");
+        process.exit(1);
+    }
+    console.log(`Watching traces: ${traceFile}`);
+    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));
+    });
+    process.on("SIGINT", () => {
+        stop();
+        console.log("\nStopped watching.");
+        process.exit(0);
+    });
+}
+/**
+ * Returns true if `/dev/tty` can be opened for reading. Use this before
+ * attempting to prompt the user — the harness has already taken stdin so
+ * we cannot use `process.stdin`.
+ */
+function isTtyAvailable() {
+    try {
+        const fd = fs.openSync("/dev/tty", "r");
+        fs.closeSync(fd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Prompt the user to enter a value on /dev/tty. Returns the trimmed
+ * line, or null if no TTY is available. The prompt is written to stderr
+ * — never stdout.
+ */
+async function promptOnTty(prompt) {
+    let ttyFd;
+    try {
+        ttyFd = fs.openSync("/dev/tty", "r");
+    }
+    catch {
+        return null;
+    }
+    const ttyStream = fs.createReadStream("", { fd: ttyFd });
+    const rl = readline.createInterface({ input: ttyStream, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(prompt, resolve);
+        });
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+        ttyStream.destroy();
+    }
+}
+/**
+ * Inline prompt for the Ory project URL. Persists the entered URL to the
+ * shared config file and returns it. Returns null if the user cancels
+ * (empty input) or no TTY is available.
+ *
+ * This is the structured counterpart to {@link interactiveConfigPrompt},
+ * which only blocks until the user runs `configure` in another terminal.
+ */
+async function promptForProjectUrl(binName) {
+    if (!isTtyAvailable())
+        return null;
+    const message = [
+        "",
+        "--------------------------------------------",
+        "  Ory Agent Plugin — Project URL Required",
+        "--------------------------------------------",
+        "",
+        "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.`,
+        "",
+        "Example: https://your-project.projects.oryapis.com",
+        "",
+    ].join("\n");
+    process.stderr.write(message + "\n");
+    const answer = await promptOnTty("Project URL: ");
+    if (!answer) {
+        process.stderr.write("\nNo URL entered. Continuing without authentication.\n\n");
+        return null;
+    }
+    let url;
+    try {
+        const parsed = new URL(answer);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            process.stderr.write(`\nIgnoring invalid project URL "${answer}".\n\n`);
+            return null;
+        }
+        url = parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        process.stderr.write(`\nIgnoring invalid project URL "${answer}".\n\n`);
+        return null;
+    }
+    (0, config_js_1.saveConfig)({ projectUrl: url, auditOnly: false });
+    process.stderr.write(`\nSaved project URL to ${(0, config_js_1.getConfigPath)()}.\n\n`);
+    return url;
+}
+/**
+ * Display a friendly configuration prompt on stderr and block until the
+ * user presses Enter. After the user continues, re-checks config from
+ * disk and returns true if Ory is now configured.
+ *
+ * Falls back to non-interactive mode (returns false immediately) when
+ * no TTY is available (e.g. CI).
+ */
+async function interactiveConfigPrompt(binName) {
+    const configPath = (0, config_js_1.getConfigPath)();
+    const message = [
+        "",
+        "--------------------------------------------",
+        "  Ory Agent Plugin — Configuration Required",
+        "--------------------------------------------",
+        "",
+        "The Ory agent plugin is installed but not yet configured.",
+        "Run one of the following commands in another terminal:",
+        "",
+        "  Connect to Ory (enables auth & permission checks):",
+        `    npx ${binName} configure --project-url <URL> --api-key <KEY>`,
+        "",
+        "  Or, enable audit logging only (no auth or permission checks):",
+        `    npx ${binName} configure --audit-only`,
+        "",
+        `Config is saved to ${configPath}`,
+        "and shared across all agent plugins.",
+        "",
+        "You can also set environment variables (requires session restart):",
+        "  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com",
+        "  export ORY_API_KEY=ory_pat_...",
+        "",
+    ].join("\n");
+    process.stderr.write(message + "\n");
+    // Try to open the terminal for blocking user input.
+    // stdin is consumed by the harness JSON pipe, so we read /dev/tty directly.
+    let ttyFd;
+    try {
+        ttyFd = fs.openSync("/dev/tty", "r");
+    }
+    catch {
+        // No TTY (CI, piped environment) — can't block for input
+        process.stderr.write("No interactive terminal available. Configure Ory and restart the session.\n\n");
+        return false;
+    }
+    const ttyStream = fs.createReadStream("", { fd: ttyFd });
+    const rl = readline.createInterface({ input: ttyStream, output: process.stderr });
+    try {
+        await new Promise((resolve) => {
+            rl.question("Press Enter after configuring to continue... ", resolve);
+        });
+    }
+    finally {
+        rl.close();
+        ttyStream.destroy();
+    }
+    // Re-read config from disk (env vars set in another shell won't be visible)
+    const resolved = (0, config_js_1.resolveConfig)();
+    if (resolved.projectUrl || resolved.auditOnly) {
+        process.stderr.write("\nConfiguration detected! Continuing session.\n\n");
+        return true;
+    }
+    process.stderr.write("\nNo configuration detected. Session blocked.\n");
+    process.stderr.write("Run one of the configure commands above and start a new session.\n\n");
+    return false;
+}
+/**
+ * Run the `agent <subcommand>` family of CLI commands. These manage the
+ * agent's dynamic OAuth2 client registration (RFC 7591). Subcommands:
+ *
+ *   - `status`     — print the persisted DCR identity, if any.
+ *   - `unregister` — best-effort RFC 7592 DELETE on the registered
+ *                    client, then clear the persisted block.
+ *
+ * Returns the process exit code (0 on success, non-zero on usage error).
+ */
+async function runAgentCommand(binName, args) {
+    const sub = args[0];
+    if (!sub || sub === "--help" || sub === "-h") {
+        console.log(`Usage: ${binName} agent <subcommand>`);
+        console.log("");
+        console.log("Subcommands:");
+        console.log("  status      Show the registered agent OAuth2 client (if any)");
+        console.log("  unregister  Delete the registered agent client and clear local state");
+        return sub ? 0 : 1;
+    }
+    switch (sub) {
+        case "status":
+            runAgentStatus();
+            return 0;
+        case "unregister":
+            return await runAgentUnregister();
+        default:
+            console.error(`Unknown agent subcommand: ${sub}`);
+            console.error(`Run "${binName} agent --help" for usage.`);
+            return 1;
+    }
+}
+function runAgentStatus() {
+    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
+    console.log("Agent identity (Dynamic Client Registration)");
+    console.log("=============================================");
+    console.log("");
+    if (!persisted) {
+        console.log("  No registered agent client. The harness will register one on its");
+        console.log("  next session start using the user's bearer (or");
+        console.log("  ORY_AGENT_REGISTRATION_TOKEN) as the initial access token.");
+        return;
+    }
+    console.log(`  client_id:        ${persisted.clientId}`);
+    console.log(`  client_secret:    ${persisted.clientSecret ? "(set)" : "(not set — public client)"}`);
+    console.log(`  registered_at:    ${new Date(persisted.registeredAt * 1000).toISOString()}`);
+    console.log(`  project_url:      ${persisted.projectUrl}`);
+    if (persisted.harness)
+        console.log(`  harness:          ${persisted.harness}`);
+    if (persisted.registrationClientUri) {
+        console.log(`  management_uri:   ${persisted.registrationClientUri}`);
+    }
+    if (persisted.registrationAccessToken) {
+        console.log(`  registration_token: (set — used to manage/delete this client)`);
+    }
+}
+async function runAgentUnregister() {
+    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
+    if (!persisted) {
+        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 {
+        console.warn("Warning: no registration_access_token was persisted, so we cannot DELETE the server-side client. Clearing local state only.");
+    }
+    (0, agent_auth_js_1.clearAgentDynamicCredentials)();
+    console.log(`Unregistered agent client ${persisted.clientId}.`);
+    return 0;
+}

package/dist/client.d.ts

@@ -0,0 +1,158 @@
+import { DebugLogger } from "./logger.js";
+import { Tracer } from "./tracer.js";
+import type { SpanExporter } from "./otel/exporter.js";
+import type { SessionInfo, OAuth2TokenInfo, PermissionCheck, PermissionResult, BatchPermissionResult, OryError } from "./types.js";
+export interface OryAgentConfig {
+    /** Ory project URL, e.g. https://your-project.projects.oryapis.com */
+    projectUrl: string;
+    /** Ory API key for admin operations */
+    apiKey?: string;
+    /** Which harness this client is running in */
+    harness: string;
+    /** Optional log file path for debug output */
+    logFile?: string;
+    /** Optional NDJSON trace file path for structured span output */
+    traceFile?: string;
+    /**
+     * Session cache TTL in milliseconds.
+     * Set to 0 to disable caching. Default: 60_000 (1 minute).
+     */
+    sessionCacheTtlMs?: number;
+    /** Optional span exporter (OTLP, vendor SDK, …) attached to the tracer. */
+    exporter?: SpanExporter;
+}
+/**
+ * A principal known to the client. Either the human user (interactive
+ * PKCE login) or the agent (machine credentials).
+ */
+export interface PrincipalIdentity {
+    /** Subject (sub claim or `session:<id>`) — used in audit spans. */
+    subject?: string;
+    /** Bearer token. Agent's token authenticates outgoing API calls. */
+    token?: string;
+}
+export declare class OryAgentClient {
+    private frontend;
+    private oauth2;
+    private permission;
+    private relationship;
+    private config;
+    readonly logger: DebugLogger;
+    readonly tracer: Tracer;
+    private sessionCache;
+    private sessionCacheTtlMs;
+    /**
+     * The human user — the principal whose permissions we check.
+     * Populated by `ensureUserAuthenticated` on session start.
+     */
+    private _userPrincipal;
+    /**
+     * The AI agent process — the principal that authenticates outgoing
+     * Ory API calls. Populated by `ensureAgentIdentity`.
+     */
+    private _agentPrincipal;
+    constructor(config: OryAgentConfig);
+    /** Build a fresh set of Ory API instances using the current agent token. */
+    private buildApis;
+    /** Snapshot of the current user principal. */
+    get userPrincipal(): PrincipalIdentity;
+    /** Snapshot of the current agent principal. */
+    get agentPrincipal(): PrincipalIdentity;
+    /**
+     * Set or update the human user principal. The user is the subject of
+     * permission checks but does not authenticate outgoing API calls.
+     * Pass `{}` (or fields set to undefined) to clear.
+     */
+    setUserPrincipal(principal: PrincipalIdentity): void;
+    /**
+     * Set or update the AI agent principal. The agent's token (when
+     * present) is used in the Authorization header for all outgoing Ory
+     * API calls — so the audit log shows "agent X acting on behalf of
+     * user Y". Rebuilds the underlying Ory API instances when the token
+     * actually changes so subsequent calls pick it up; otherwise leaves
+     * the API instances alone (so test stubs survive a no-op update).
+     */
+    setAgentPrincipal(principal: PrincipalIdentity): void;
+    /**
+     * Verify an existing session token. Returns cached result if available.
+     */
+    verifySession(sessionToken: string): Promise<SessionInfo>;
+    /**
+     * Introspect an OAuth2 access token. Use this when agents authenticate
+     * via client credentials flow instead of session tokens.
+     */
+    introspectToken(token: string, scope?: string): Promise<OAuth2TokenInfo>;
+    /**
+     * Check if a subject has permission to perform an action.
+     *
+     * `options.spanAttributes` are merged into the `permission.check` trace
+     * span so callers can attach harness-side context (toolName, mcpServer,
+     * etc.) that the wire-level `PermissionCheck` shape doesn't carry.
+     */
+    checkPermission(check: PermissionCheck, options?: {
+        spanAttributes?: Record<string, unknown>;
+    }): Promise<PermissionResult>;
+    /**
+     * Check multiple permissions in a single request.
+     *
+     * `options.spanAttributes` are merged into the `permission.batch_check`
+     * span — same purpose as `checkPermission`'s spanAttributes.
+     */
+    batchCheckPermissions(checks: PermissionCheck[], options?: {
+        spanAttributes?: Record<string, unknown>;
+    }): Promise<BatchPermissionResult>;
+    /**
+     * Create a relation tuple in Keto. Idempotent: a 409 (tuple already
+     * exists) is swallowed and reported as success. All other errors are
+     * classified and re-thrown — callers wrap in fail-open semantics if
+     * the tuple is non-critical (e.g. audit-only delegation tracking).
+     *
+     * `options.spanAttributes` are merged into the `relationship.create`
+     * trace span so callers can attach context like `delegation: "user→agent"`.
+     */
+    createRelationship(check: PermissionCheck, options?: {
+        spanAttributes?: Record<string, unknown>;
+    }): Promise<{
+        created: boolean;
+        alreadyExisted: boolean;
+    }>;
+    /**
+     * Delete a relation tuple in Keto. Missing tuples (404) are treated as
+     * success so callers can call this idempotently when unwinding state.
+     */
+    deleteRelationship(check: PermissionCheck, options?: {
+        spanAttributes?: Record<string, unknown>;
+    }): Promise<{
+        deleted: boolean;
+        notFound: boolean;
+    }>;
+    /**
+     * Span attributes describing which principals were attached to the
+     * client when the span was started. Useful for correlating audit logs
+     * across the user/agent split.
+     */
+    private principalSpanAttributes;
+    /**
+     * Classify an error from any Ory API call into a structured OryError.
+     */
+    classifyError(err: unknown): OryError;
+    private isAxiosError;
+    /**
+     * Create a client from environment variables.
+     */
+    /**
+     * Create a client from environment variables, falling back to the
+     * shared config file at ~/.config/ory-agent-plugins/config.json.
+     *
+     * Resolution order for projectUrl and apiKey:
+     *   1. Environment variables (ORY_PROJECT_URL, ORY_API_KEY)
+     *   2. Config file (~/.config/ory-agent-plugins/config.json)
+     *   3. Placeholder (fail-open pass-through mode)
+     */
+    static fromEnv(harness: string): OryAgentClient;
+}
+/**
+ * Pull the Ory backend request ID from a response headers bag (axios returns
+ * lowercase header names). Returns undefined when not present.
+ */
+export declare function extractOryRequestId(headers: unknown): string | undefined;