firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/dependency-proxy.js

@@ -0,0 +1,1006 @@
+/**
+ * Per-drill loopback dependency proxy (Plan20 FIR-490, root
+ * `native-dependency-access.v1`).
+ *
+ * Root issues a dependency token only while the drill is ready or executing,
+ * for at most 30 seconds, and it must never reach env, files, evidence, logs or
+ * the target. So the target is given stable loopback URLs before it starts, and
+ * this companion-owned proxy fetches tokens lazily, keeps them in memory and
+ * forwards each call to root's tool gateway:
+ *  - `POST /{cap}/{alias}/v1/invoke`: the Firedrill operation protocol
+ *    `{service_key?, operation, arguments, idempotency_key?}`, limited to the
+ *    operations the descriptor declares for that dependency (root's token grants
+ *    the wider world set); an operation's declared idempotency argument carries
+ *    the same key as `idempotency_key`, exactly as over MCP;
+ *  - `POST /{cap}/{alias}/mcp`: stateless MCP. `initialize`, `ping` and
+ *    `notifications/initialized` are answered locally with root's exact
+ *    constants, so a target can connect its MCP client before the drill is
+ *    admitted; `tools/list` and `tools/call` are forwarded with the headers root
+ *    requires, and every call carries an idempotency key in `_meta` (a generic
+ *    MCP client cannot add one; root ignores it for reads).
+ *
+ * Guards: loopback only, exact Host, no Origin (browsers and DNS rebinding are
+ * refused), a random per-drill path capability compared in constant time, and
+ * root's 1 MiB body limit. A call is retried at most once, with a fresh token and
+ * the same idempotency key, so a committed write replays from root's journal and
+ * never happens twice. Upstream requests carry exactly one Authorization header,
+ * a Content-Length and no Origin, and never follow redirects. The proxy closes
+ * before the drill's close is recorded; tokens die with it.
+ *
+ * Isolated custom tools (root `runtime_support/native_isolated_broker.py`): the
+ * same access shape, but `invoke_url`/`mcp_url` may name a separate broker origin
+ * that tags each answer with `X-Firedrill-Outcome`. Only `observed` is a tool
+ * result. `pending` (HTTP 202, or JSON-RPC -32001 from `tools/call`) is waited on
+ * by reading the original operation at root's `recovery_path` on the same origin
+ * with a current token, never by resubmitting. `unknown` (409), `not_dispatched`
+ * (422) and a wait that ends while still pending reach the target as errors that
+ * carry the request id and a loopback `GET /{cap}/{alias}/v1/requests/{id}`
+ * recovery route, so a pending acceptance can never become the agent's answer.
+ */
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { performance } from 'node:perf_hooks';
+import { CliError } from '../http.js';
+import { SecretValue } from './contracts.js';
+import { filterEvidenceValue } from './evidence-filter.js';
+import { errorCode, isFenced, isRevocation, isTransient, sleep } from './control-plane.js';
+/** Root's gateway request body limit. */
+export const BODY_MAX_BYTES = 1_048_576;
+/** Root's tool response limit (16 MiB) plus framing. */
+const RESPONSE_MAX_BYTES = 16 * 1_048_576 + 65_536;
+const MCP_PROTOCOL_VERSION = '2025-06-18';
+/** Root's constant `initialize` result (the gateway does no version negotiation). */
+const MCP_INITIALIZE = { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: 'firedrill-tool', version: '1' } };
+const TOKEN_MARGIN_MS = 5_000;
+/** How long one call waits for root to issue a token (the drill may not be admitted yet). */
+const TOKEN_WAIT_MS = 30_000;
+/** Root's gateway socket timeout. */
+const UPSTREAM_TIMEOUT_MS = 30_000;
+/** The only tool headers root's gateway passes through. */
+const PASSED_HEADERS = ['retry-after', 'etag', 'idempotent-replayed'];
+const INVOKE_KEYS = new Set(['service_key', 'operation', 'arguments', 'idempotency_key']);
+const RPC_KEYS = new Set(['jsonrpc', 'id', 'method', 'params']);
+/** The isolated tool broker's outcome header (root's pooled gateway sends none). */
+const OUTCOME = 'x-firedrill-outcome';
+/** How long one call keeps reading an original operation the broker accepted without a result. */
+const PENDING_WAIT_MS = 45_000;
+/** The broker's JSON-RPC error for a `tools/call` without a confirmed result. */
+const NO_CONFIRMED_RESULT = -32001;
+/** Original operations remembered per dependency for the loopback recovery route. */
+const ORIGINALS_MAX = 10_000;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const UNSETTLED_TEXT = {
+    pending: 'The simulated tool accepted this operation but has no result yet. Read recovery_path, or resend it with the same idempotency key. Never resend it under a new key.',
+    unknown: 'The simulated tool cannot confirm whether this operation took effect. Read recovery_path before acting again. Never resend it under a new key.',
+    not_dispatched: 'The simulated tool did not run this operation.',
+};
+/** A call that may have reached the tool without an answer coming back. */
+const UNANSWERED_TEXT = 'The simulated dependency did not answer this call, so it may or may not have taken effect. Resend it with the same idempotency key. Never resend it under a new key.';
+/** The broker finished the operation but its MCP-shaped result could not be read back. */
+const UNDELIVERED_TEXT = 'The simulated tool finished this operation, but its result could not be delivered. Resend the same call with the same idempotency key to read it. Never resend it under a new key.';
+export const DEPENDENCY_ERRORS = {
+    /** Root's binding, service key or gateway URLs changed between two tokens of one drill. */
+    changed: 'native_dependency_changed',
+    /** Root's tool gateway is not configured for this deployment (permanent for the run). */
+    unavailable: 'native_dependency_unavailable',
+};
+const captures = new WeakMap();
+function captured(response, status, value, format) {
+    const callback = captures.get(response);
+    captures.delete(response);
+    if (!callback)
+        return;
+    let done = false;
+    const emit = (finished) => {
+        if (done)
+            return;
+        done = true;
+        try {
+            callback(finished ? status : null, finished ? value : null, finished ? format : 'unavailable');
+        }
+        catch { /* Evidence never changes the delivered result. */ }
+    };
+    if (response.writableFinished)
+        emit(true);
+    else if (response.destroyed)
+        emit(false);
+    else {
+        response.once('finish', () => emit(true));
+        response.once('close', () => emit(response.writableFinished));
+    }
+}
+function scrubExchange(value, secrets) {
+    let encoded = JSON.stringify(value), changed = false;
+    if (encoded === undefined || Buffer.byteLength(encoded) > 131072)
+        throw new Error('capture_size');
+    for (const secret of secrets.filter(Boolean)) {
+        const safe = encoded.split(JSON.stringify(secret).slice(1, -1)).join('[redacted]');
+        changed ||= safe !== encoded;
+        encoded = safe;
+    }
+    const safe = encoded.replace(/https?:\/\/[^"\\\s<>]+/gi, '[private link]');
+    changed ||= safe !== encoded;
+    const clean = JSON.parse(safe, (name, item) => {
+        if (['_meta', 'headers', 'cookies', 'authorization', 'idempotency_key', 'firedrill/idempotency-key', 'recovery_path'].includes(name)) {
+            changed = true;
+            return undefined;
+        }
+        return item;
+    });
+    return { value: clean, changed };
+}
+export class DependencyProxy {
+    #options;
+    #server;
+    #cap;
+    #operations;
+    #tokens = new Map();
+    #fetching = new Map();
+    #pinned = new Map();
+    #originals = new Map();
+    #captureContexts = new WeakMap();
+    #retainedCaptureBytes = 0;
+    /** Per dependency: each tool's declared idempotency argument (null: none), from root's tools/list metadata. */
+    #arguments = new Map();
+    /** Dependencies whose whole tool list this proxy has read. */
+    #discovered = new Set();
+    #discovering = new Map();
+    #controller = new AbortController();
+    #port = 0;
+    #closed = false;
+    /** The path capability, redacted wherever drill secrets are. */
+    secret;
+    constructor(options) {
+        this.#options = options;
+        this.#cap = randomBytes(32).toString('base64url');
+        this.secret = new SecretValue(this.#cap, 'dependency-proxy');
+        // Only synthetic dependencies are served: root issues tokens for simulated tools only.
+        this.#operations = new Map(options.descriptor.dependencies.filter((dependency) => dependency.mode === 'synthetic')
+            .map((dependency) => [dependency.alias, new Set(dependency.operations)]));
+        this.#server = createServer({ requestTimeout: UPSTREAM_TIMEOUT_MS * 3, headersTimeout: 10_000 }, (request, response) => { void this.#handle(request, response); });
+        this.#server.on('clientError', (_error, socket) => socket.destroy());
+    }
+    /** Start the proxy on an ephemeral loopback port. */
+    static async start(options) {
+        const proxy = new DependencyProxy(options);
+        await new Promise((resolve, reject) => {
+            proxy.#server.once('error', reject);
+            proxy.#server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => { proxy.#server.off('error', reject); resolve(); });
+        });
+        proxy.#port = proxy.#server.address().port;
+        if (options.signal.aborted)
+            await proxy.close();
+        else
+            options.signal.addEventListener('abort', () => { void proxy.close(); }, { once: true });
+        return proxy;
+    }
+    /** True when the descriptor declares this synthetic dependency. */
+    serves(alias) { return this.#operations.has(alias); }
+    /** The loopback URL the target uses for one dependency (it carries the path capability: treat it as secret). */
+    url(alias, kind) {
+        if (!this.#operations.has(alias))
+            throw new CliError('native_dependency_invalid', `Dependency "${alias}" is not a simulated dependency of this target.`);
+        return new SecretValue(`http://127.0.0.1:${this.#port}/${this.#cap}/${alias}${kind === 'invoke' ? '/v1/invoke' : '/mcp'}`, `dependency-url:${alias}`);
+    }
+    /** Stop accepting calls, abort in-flight ones and forget every token. Safe to call more than once. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#controller.abort();
+        this.#tokens.clear();
+        await new Promise((resolve) => { this.#server.close(() => resolve()); this.#server.closeAllConnections(); });
+    }
+    // -------------------------------------------------------------------------
+    // Inbound (the target).
+    async #handle(request, response) {
+        // Only callers holding this drill's loopback capability can affect its
+        // evidence accounting. Unauthenticated probes remain ordinary refusals.
+        let captureEligible = false;
+        try {
+            if (this.#closed)
+                return refuse(response, 503, 'dependency_proxy_closed');
+            if (request.headers.origin !== undefined)
+                return refuse(response, 403, 'origin_denied');
+            if (request.headers.host !== `127.0.0.1:${this.#port}`)
+                return refuse(response, 403, 'host_denied');
+            const match = /^\/([A-Za-z0-9_-]{43})\/([a-z][a-z0-9_-]{0,63})\/(v1\/invoke|mcp|v1\/requests\/([0-9a-f-]{36}))$/.exec(request.url ?? '');
+            if (!match || !sameCap(match[1], this.#cap) || !this.#operations.has(match[2]))
+                return refuse(response, 404, 'not_found');
+            if (match[4] !== undefined) {
+                if (request.method !== 'GET')
+                    return refuse(response, 405, 'method_not_supported');
+                request.resume();
+                return await this.#recover(match[2], match[4], response);
+            }
+            captureEligible = true;
+            if (request.method !== 'POST')
+                return refuse(response, 405, 'method_not_supported');
+            const declared = Number(request.headers['content-length']);
+            if (Number.isFinite(declared) && declared > BODY_MAX_BYTES) {
+                this.#captureUnavailable();
+                return refuse(response, 413, 'request_too_large', undefined, true);
+            }
+            const body = await readBody(request);
+            if (body === null) {
+                this.#captureUnavailable();
+                return refuse(response, 413, 'request_too_large', undefined, true);
+            }
+            let message;
+            try {
+                message = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                this.#captureUnavailable();
+                return refuse(response, 400, 'request_invalid');
+            }
+            if (match[3] === 'mcp')
+                captureEligible = record(message)?.method === 'tools/call';
+            if (match[3] === 'mcp')
+                await this.#mcp(match[2], message, response);
+            else
+                await this.#invoke(match[2], message, response);
+        }
+        catch {
+            if (captureEligible && !this.#captureContexts.has(response))
+                this.#captureUnavailable();
+            if (!response.headersSent)
+                refuse(response, 502, 'dependency_unavailable');
+            else
+                response.destroy();
+        }
+    }
+    async #invoke(alias, message, response) {
+        const call = record(message);
+        if (!call || !Object.keys(call).every((key) => INVOKE_KEYS.has(key)) || typeof call.operation !== 'string'
+            || !record(call.arguments) || (call.service_key !== undefined && typeof call.service_key !== 'string')
+            || (call.idempotency_key !== undefined && !validKey(call.idempotency_key))) {
+            this.#captureUnavailable();
+            return refuse(response, 400, 'request_invalid');
+        }
+        if (!this.#operations.get(alias)?.has(call.operation)) {
+            this.#captureUnavailable();
+            return refuse(response, 403, 'operation_not_declared');
+        }
+        // Root refuses a write whose declared idempotency argument and idempotency_key differ, so both carry one key, as over MCP.
+        const argument = await this.#idempotencyArgument(alias, call.operation);
+        if (argument === undefined) {
+            this.#captureUnavailable();
+            response.setHeader('retry-after', '1');
+            return json(response, 503, { error: 'dependency_not_ready',
+                message: 'The simulated dependency\'s tool list could not be read, so nothing was sent. Try again.' });
+        }
+        const keyed = keyedCall(call.arguments, typeof call.idempotency_key === 'string' ? { [IDEMPOTENCY_META]: call.idempotency_key } : {}, argument);
+        if (!keyed) {
+            this.#captureUnavailable();
+            return json(response, 400, { error: 'idempotency_key_conflict',
+                message: `The ${argument} argument and idempotency_key name different keys, so nothing was sent. Use one key.` });
+        }
+        // One key per inbound call, reused by the retry: a committed write replays instead of repeating.
+        const key = keyed.key;
+        this.#beginCapture(alias, call.operation, keyed.arguments, argument, 'http', key, response);
+        let upstream = await this.#forward(alias, (access) => post(access.invoke_url, access.token, false, Buffer.from(JSON.stringify({
+            service_key: access.service_key, operation: call.operation, arguments: keyed.arguments, idempotency_key: key,
+        }), 'utf8'), this.#controller.signal), call.service_key);
+        if (upstream === 'service_key_mismatch')
+            return refuse(response, 400, 'service_key_mismatch');
+        if (typeof upstream === 'string') {
+            // The call may have reached the tool before the answer was lost: the same key replays it, a new key could repeat it.
+            if (upstream === 'dependency_not_ready')
+                response.setHeader('retry-after', '1');
+            return json(response, upstream === 'dependency_not_ready' ? 503 : 502, { error: upstream, idempotency_key: key, message: UNANSWERED_TEXT });
+        }
+        if (upstream.status === 409 && gatewayCode(upstream.body) === 'tool_request_unavailable') {
+            // The gateway gives this one answer to every failure, including one after the operation was accepted.
+            return json(response, 409, { error: 'dependency_request_unavailable', idempotency_key: key, message: UNANSWERED_TEXT });
+        }
+        if (header(upstream.headers, OUTCOME) === 'pending') {
+            // Accepted, not answered: wait on the original operation; never submit it again.
+            const original = this.#original(alias, 'invoke', parsed(upstream.body), key, this.#captureContexts.get(response));
+            if (!original)
+                return json(response, 502, { error: 'dependency_unavailable', idempotency_key: key, message: UNANSWERED_TEXT });
+            const settled = await this.#settle(alias, original, Number(header(upstream.headers, 'retry-after')));
+            if (typeof settled === 'string')
+                return this.#unsettled(response, alias, 'pending', original);
+            upstream = settled;
+        }
+        return this.#relay(alias, upstream, response, key);
+    }
+    /** Loopback recovery: read one original operation this dependency's broker accepted earlier in the drill. */
+    async #recover(alias, requestId, response) {
+        const original = this.#originals.get(alias)?.get(requestId);
+        if (!original)
+            return refuse(response, 404, 'not_found');
+        if (original.capture)
+            this.#attachCapture({ ...original.capture, protocol: 'http' }, response);
+        else
+            this.#captureUnavailable();
+        const upstream = await this.#read(alias, original);
+        if (typeof upstream === 'string')
+            return refuse(response, upstream === 'dependency_not_ready' ? 503 : 502, upstream, 1);
+        return this.#relay(alias, upstream, response, original.key);
+    }
+    /**
+     * Relay an operation answer. Without an outcome header (root's pooled gateway)
+     * or with `observed`, it is the tool's answer. Any other outcome is relayed as
+     * an error with loopback recovery, and an unrecognized one as unavailable. A
+     * scenario outage the broker refused before dispatch is relayed as it is, as
+     * the pooled gateway answers the same outage.
+     */
+    #relay(alias, upstream, response, key) {
+        const outcome = header(upstream.headers, OUTCOME);
+        if (outcome === 'pending' || outcome === 'unknown' || outcome === 'not_dispatched') {
+            const original = this.#original(alias, 'invoke', parsed(upstream.body), key, this.#captureContexts.get(response));
+            if (original)
+                return this.#unsettled(response, alias, outcome, original);
+            // The broker's outage answer has no request id: nothing was run, so it is not an unanswered call.
+            const outage = outcome === 'not_dispatched' && upstream.status === 503 && gatewayCode(upstream.body) === 'dependency_unavailable';
+            if (!outage)
+                return refuse(response, 502, 'dependency_unavailable');
+        }
+        else if (outcome !== null && outcome !== 'observed')
+            return refuse(response, 502, 'dependency_unavailable');
+        const headers = {
+            'content-type': header(upstream.headers, 'content-type') ?? 'application/octet-stream',
+            'content-length': String(upstream.body.length), 'cache-control': 'no-store',
+        };
+        for (const name of PASSED_HEADERS) {
+            const value = header(upstream.headers, name);
+            if (value !== null)
+                headers[name] = value;
+        }
+        if (outcome === 'observed')
+            headers[OUTCOME] = 'observed';
+        response.writeHead(upstream.status, headers);
+        const contentType = headers['content-type'].split(';')[0].trim().toLowerCase();
+        if (upstream.body.length > 131072)
+            captured(response, upstream.status, null, 'unavailable');
+        else if (contentType === 'application/json' || contentType.endsWith('+json')) {
+            try {
+                captured(response, upstream.status, JSON.parse(upstream.body.toString('utf8')), 'json');
+            }
+            catch {
+                captured(response, upstream.status, null, 'unavailable');
+            }
+        }
+        else if (contentType.startsWith('text/'))
+            captured(response, upstream.status, upstream.body.toString('utf8'), 'text');
+        else
+            captured(response, upstream.status, null, 'unavailable');
+        response.end(upstream.body);
+    }
+    /** An operation without a confirmed result, as an error the target cannot mistake for an answer. */
+    #unsettled(response, alias, outcome, original) {
+        response.setHeader(OUTCOME, outcome);
+        if (outcome === 'pending')
+            response.setHeader('retry-after', '1');
+        json(response, outcome === 'not_dispatched' ? 422 : 409, {
+            error: outcome === 'pending' ? 'dependency_outcome_pending' : outcome === 'unknown' ? 'dependency_outcome_unknown' : 'dependency_not_dispatched',
+            outcome, request_id: original.request_id, recovery_path: this.#localPath(alias, original.request_id),
+            ...(original.key ? { idempotency_key: original.key } : {}), message: UNSETTLED_TEXT[outcome],
+        });
+    }
+    #localPath(alias, requestId) {
+        return `/${this.#cap}/${alias}/v1/requests/${requestId}`;
+    }
+    /**
+     * Root's recovery data for one accepted operation, kept only when its path is
+     * exactly this dependency's original-operation route (so the proxy never reads
+     * an arbitrary path with a token).
+     */
+    #original(alias, kind, value, key, capture) {
+        const data = record(value);
+        const pinned = this.#pinned.get(alias);
+        if (!data || !pinned || typeof data.request_id !== 'string' || !UUID_PATTERN.test(data.request_id))
+            return null;
+        const path = `/v1/requests/${encodeURIComponent(pinned.service_key)}/${data.request_id}`;
+        if (data.recovery_path !== path)
+            return null;
+        let seen = this.#originals.get(alias);
+        if (!seen) {
+            seen = new Map();
+            this.#originals.set(alias, seen);
+        }
+        const original = seen.get(data.request_id) ?? { request_id: data.request_id, path, kind, key };
+        if (capture && !original.capture) {
+            const size = Buffer.byteLength(JSON.stringify(capture.request)) + 1024;
+            // Evidence context is optional; it must not multiply the 10k original
+            // recovery index into an unbounded body cache. Never evict recovery IDs.
+            if (this.#retainedCaptureBytes + size <= 2 * 1048576) {
+                original.capture = capture;
+                this.#retainedCaptureBytes += size;
+            }
+        }
+        if (key && !original.key)
+            original.key = key;
+        seen.delete(original.request_id);
+        if (seen.size >= ORIGINALS_MAX)
+            seen.delete(seen.keys().next().value);
+        seen.set(original.request_id, original);
+        return original;
+    }
+    /** One read of an original operation: root's path, on the origin of the granted URL that accepted it, with a current token. */
+    #read(alias, original) {
+        return this.#forward(alias, (access) => get(new URL(original.path, original.kind === 'invoke' ? access.invoke_url : access.mcp_url).href, access.token, this.#controller.signal));
+    }
+    /**
+     * Read the original operation until it is no longer pending or the wait ends.
+     * Returns the last read (possibly still pending), or a refusal code when no read
+     * could be completed.
+     */
+    async #settle(alias, original, retryAfter) {
+        const deadline = performance.now() + PENDING_WAIT_MS;
+        let delay = Math.min(5, Math.max(1, retryAfter || 1));
+        for (;;) {
+            if (!await sleep(delay * 1_000, this.#controller.signal))
+                return 'dependency_unavailable';
+            const read = await this.#read(alias, original);
+            if (typeof read === 'string')
+                return read;
+            if (header(read.headers, OUTCOME) !== 'pending' || performance.now() + 1_000 >= deadline)
+                return read;
+            delay = Math.min(5, Math.max(1, Number(header(read.headers, 'retry-after')) || 1));
+        }
+    }
+    async #mcp(alias, message, response) {
+        const rpc = record(message);
+        if (!rpc || rpc.jsonrpc !== '2.0' || typeof rpc.method !== 'string' || !Object.keys(rpc).every((key) => RPC_KEYS.has(key))
+            || (rpc.params !== undefined && !record(rpc.params))
+            || (rpc.id !== undefined && rpc.id !== null && typeof rpc.id !== 'string' && !Number.isSafeInteger(rpc.id))) {
+            if (rpc?.method === 'tools/call')
+                this.#captureUnavailable();
+            return refuse(response, 400, 'request_invalid');
+        }
+        if (rpc.id === undefined) {
+            if (rpc.method === 'tools/call')
+                this.#captureUnavailable();
+            if (rpc.method !== 'notifications/initialized')
+                return refuse(response, 400, 'request_id_required');
+            response.writeHead(202, { 'cache-control': 'no-store', 'content-length': '0' });
+            response.end();
+            return;
+        }
+        const id = rpc.id;
+        const params = record(rpc.params) ?? {};
+        // Root's gateway answers these identically; answering here lets the target connect before admission.
+        if (rpc.method === 'initialize')
+            return rpcReply(response, id, { result: MCP_INITIALIZE });
+        if (rpc.method === 'ping')
+            return rpcReply(response, id, { result: {} });
+        const declared = this.#operations.get(alias);
+        let forwarded;
+        let key = null;
+        if (rpc.method === 'tools/call') {
+            if (typeof params.name !== 'string' || !declared.has(params.name)) {
+                this.#captureUnavailable();
+                return rpcReply(response, id, { error: { code: -32602, message: 'The tool is not declared for this target.' } });
+            }
+            if ((params.arguments !== undefined && !record(params.arguments)) || (params._meta !== undefined && !record(params._meta))) {
+                this.#captureUnavailable();
+                return rpcReply(response, id, { error: { code: -32602, message: 'Use a tool name and an arguments object.' } });
+            }
+            // The tool's declared idempotency argument (root's tools/list metadata) carries the same key as _meta.
+            const argument = await this.#idempotencyArgument(alias, params.name);
+            if (argument === undefined) {
+                this.#captureUnavailable();
+                return rpcReply(response, id, { error: { code: -32603, message: 'The simulated dependency\'s tool list could not be read, so nothing was sent. Try again.' } });
+            }
+            const meta = record(params._meta) ?? {};
+            const keyed = keyedCall(record(params.arguments) ?? {}, meta, argument);
+            if (!keyed) {
+                this.#captureUnavailable();
+                return rpcReply(response, id, { error: { code: -32602,
+                        message: `The ${argument} argument and _meta ${IDEMPOTENCY_META} name different keys, so nothing was sent. Use one key.` } });
+            }
+            key = keyed.key;
+            this.#beginCapture(alias, params.name, keyed.arguments, argument, 'mcp', key, response);
+            forwarded = { jsonrpc: '2.0', id, method: 'tools/call',
+                params: { ...params, arguments: keyed.arguments, _meta: { ...meta, [IDEMPOTENCY_META]: key } } };
+        }
+        else if (rpc.method === 'tools/list') {
+            forwarded = { jsonrpc: '2.0', id, method: 'tools/list', params };
+        }
+        else {
+            return rpcReply(response, id, { error: { code: -32601, message: 'Method not found' } });
+        }
+        const bytes = Buffer.from(JSON.stringify(forwarded), 'utf8');
+        const send = () => this.#forward(alias, (access) => post(access.mcp_url, access.token, true, bytes, this.#controller.signal));
+        const upstream = await send();
+        // A gateway refusal (root answers HTTP 409, not JSON-RPC) becomes a tool error, not a transport failure.
+        if (typeof upstream === 'string' || upstream.status !== 200) {
+            // A tools/call may have been accepted before the answer was lost: say so, and give the key that replays it.
+            if (key)
+                return rpcReply(response, id, { error: { code: -32603, message: UNANSWERED_TEXT, data: { 'firedrill/idempotency-key': key } } });
+            const text = upstream === 'dependency_not_ready' ? 'The simulated dependency is not ready yet.' : 'The simulated dependency refused the call.';
+            return rpcReply(response, id, { error: { code: -32603, message: text } });
+        }
+        let reply = record(parsed(upstream.body));
+        if (!reply || reply.jsonrpc !== '2.0')
+            return rpcReply(response, id, { error: { code: -32603, message: 'The simulated dependency answered malformed JSON.' } });
+        const failure = record(reply.error);
+        if (key && failure?.code === NO_CONFIRMED_RESULT)
+            return this.#mcpUnconfirmed(alias, id, key, record(failure.data), send, response);
+        if (rpc.method === 'tools/list' && record(reply.result)) {
+            this.#remember(alias, listedArguments(reply.result)?.tools);
+            // Least privilege: list only what the descriptor declares (root lists the whole grant).
+            const tools = Array.isArray(record(reply.result)?.tools) ? record(reply.result)?.tools : [];
+            reply = { ...reply, result: { ...record(reply.result), tools: tools.filter((tool) => {
+                        const name = record(tool)?.name;
+                        return typeof name === 'string' && declared.has(name);
+                    }) } };
+        }
+        return json(response, 200, { ...reply, id });
+    }
+    /**
+     * A broker `tools/call` without a confirmed result: wait on the original
+     * operation and, once it is observed, send the same call (same key) again. The
+     * broker then replays the original command as an MCP result, whatever the
+     * tool's own transport; the recovery read returns an HTTP-backed tool's raw
+     * answer, which is not an MCP result. Otherwise keep the JSON-RPC error with
+     * loopback recovery data and the key. Never a fabricated tool result.
+     */
+    async #mcpUnconfirmed(alias, id, key, data, send, response) {
+        const original = this.#original(alias, 'mcp', data, key, this.#captureContexts.get(response));
+        if (!original) {
+            return rpcReply(response, id, { error: { code: -32603, message: UNANSWERED_TEXT, data: { 'firedrill/idempotency-key': key } } });
+        }
+        const said = data?.outcome;
+        let outcome = said === 'pending' || said === 'not_dispatched' ? said : 'unknown';
+        if (outcome === 'pending') {
+            const settled = await this.#settle(alias, original, 1);
+            const now = typeof settled === 'string' ? null : header(settled.headers, OUTCOME);
+            if (now === 'observed' || now === 'unknown' || now === 'not_dispatched')
+                outcome = now;
+        }
+        if (outcome === 'observed') {
+            const replayed = await send();
+            const reply = typeof replayed === 'string' || replayed.status !== 200 ? null : record(parsed(replayed.body));
+            const result = reply?.jsonrpc === '2.0' ? record(reply.result) : null;
+            if (result && Array.isArray(result.content))
+                return rpcReply(response, id, { result });
+        }
+        return rpcReply(response, id, { error: { code: NO_CONFIRMED_RESULT, message: outcome === 'observed' ? UNDELIVERED_TEXT : UNSETTLED_TEXT[outcome],
+                data: { outcome, request_id: original.request_id, recovery_path: this.#localPath(alias, original.request_id), 'firedrill/idempotency-key': key } } });
+    }
+    #captureUnavailable() {
+        try {
+            this.#options.onExchange?.(null);
+        }
+        catch { /* Optional capture only. */ }
+    }
+    #beginCapture(alias, operation, args, argument, protocol, key, response) {
+        if (!this.#options.onExchange)
+            return;
+        try {
+            const business = { ...args };
+            for (const name of ['_meta', 'idempotency_key', 'firedrill/idempotency-key', ...(argument ? [argument] : [])])
+                delete business[name];
+            const scrubbed = scrubExchange(business, [this.#cap, key ?? '']);
+            const filtered = filterEvidenceValue(scrubbed.value, 1, 2048, 1024);
+            const bounded = record(filtered.value) ?? {};
+            const over = Buffer.byteLength(JSON.stringify(bounded)) > 32768;
+            this.#attachCapture({ alias, operation, protocol, key, request: over ? {} : bounded,
+                request_coverage: over || (filtered.stats.truncated ?? 0) > 0 ? 'truncated'
+                    : scrubbed.changed || filtered.stats.removed + filtered.stats.rewritten ? 'redacted' : 'captured' }, response);
+        }
+        catch {
+            this.#captureUnavailable();
+        }
+    }
+    #attachCapture(context, response) {
+        if (!this.#options.onExchange)
+            return;
+        this.#captureContexts.set(response, context);
+        captures.set(response, (status, observed, format) => {
+            try {
+                const binding = this.#pinned.get(context.alias);
+                if (!binding) {
+                    this.#captureUnavailable();
+                    return;
+                }
+                let value = observed, isError = null;
+                let outcome = status === null ? 'unknown' : 'returned';
+                const object = record(observed);
+                const error = record(object?.error);
+                const data = record(error?.data);
+                const said = data?.outcome ?? object?.outcome ?? header(response.getHeaders(), OUTCOME);
+                if (said === 'pending')
+                    outcome = 'pending';
+                else if (said === 'unknown')
+                    outcome = 'unknown';
+                else if (said === 'not_dispatched')
+                    outcome = 'refused';
+                if (context.protocol === 'mcp') {
+                    isError = format === 'unavailable' ? null : !!error || record(object?.result)?.isError === true;
+                    // Strip RPC envelope and all recovery/transport error data.
+                    value = error ? { code: error.code, message: error.message } : object?.result ?? null;
+                    // Internal transport/malformed replies do not prove the operation
+                    // was refused. In particular, an observed broker result whose MCP
+                    // replay was lost is still unknown at this device.
+                    if (error && outcome === 'returned')
+                        outcome = error.code === -32603 || error.code === NO_CONFIRMED_RESULT ? 'unknown' : 'refused';
+                }
+                else if (object && ('idempotency_key' in object || 'recovery_path' in object)) {
+                    value = null;
+                    format = 'unavailable';
+                    if (outcome === 'returned')
+                        outcome = 'unknown';
+                }
+                if (outcome === 'pending' || outcome === 'unknown') {
+                    value = null;
+                    format = 'unavailable';
+                }
+                const omissions = [];
+                if (context.request_coverage === 'redacted')
+                    omissions.push('privacy_filtered');
+                if (context.request_coverage === 'truncated')
+                    omissions.push('size_limit');
+                // Never retain a returned capability/key even if a tool echoes one.
+                const encoded = JSON.stringify(value);
+                let rewritten = false;
+                if (encoded === undefined) {
+                    value = null;
+                    format = 'unavailable';
+                }
+                else {
+                    if (Buffer.byteLength(encoded) > 131072) {
+                        value = null;
+                        format = 'unavailable';
+                        omissions.push('size_limit');
+                    }
+                    else {
+                        const scrubbed = scrubExchange(value, [this.#cap, context.key ?? '']);
+                        value = scrubbed.value;
+                        rewritten = scrubbed.changed;
+                    }
+                }
+                if (rewritten)
+                    omissions.push('privacy_filtered');
+                if (format === 'unavailable')
+                    omissions.push(status === null ? 'no_response' : 'unsupported_content');
+                this.#options.onExchange?.({ schema: 'firedrill.native-dependency-exchange.v1', exchange_id: randomUUID(),
+                    dependency_alias: context.alias, service_key: binding.service_key, operation: context.operation,
+                    binding_digest: binding.binding_digest, protocol: context.protocol, outcome, http_status: status, is_error: isError,
+                    request: context.request, response: value, response_format: format, request_coverage: context.request_coverage,
+                    response_coverage: format === 'unavailable' ? 'unavailable' : rewritten ? 'redacted' : 'captured',
+                    omission_reasons: [...new Set(omissions)] });
+            }
+            catch {
+                this.#captureUnavailable();
+            }
+        });
+        response.once('close', () => { if (captures.has(response))
+            captured(response, null, null, 'unavailable'); });
+    }
+    #remember(alias, tools) {
+        if (!tools)
+            return;
+        let known = this.#arguments.get(alias);
+        if (!known) {
+            known = new Map();
+            this.#arguments.set(alias, known);
+        }
+        for (const [name, argument] of tools)
+            known.set(name, argument);
+    }
+    /**
+     * A tool's declared idempotency argument (null when it declares none), read
+     * from root's tools/list once per dependency, single-flight. Undefined when the
+     * list could not be read: the call is not sent rather than sent unshaped.
+     */
+    async #idempotencyArgument(alias, tool) {
+        const known = this.#arguments.get(alias);
+        if (known?.has(tool))
+            return known.get(tool);
+        if (this.#discovered.has(alias))
+            return null;
+        let pending = this.#discovering.get(alias);
+        if (!pending) {
+            pending = this.#discover(alias).finally(() => this.#discovering.delete(alias));
+            this.#discovering.set(alias, pending);
+        }
+        if (!await pending)
+            return undefined;
+        return this.#arguments.get(alias)?.get(tool) ?? null;
+    }
+    async #discover(alias) {
+        let cursor = null;
+        for (let page = 0; page < DISCOVERY_PAGES; page++) {
+            const body = Buffer.from(JSON.stringify({ jsonrpc: '2.0', id: `firedrill-discovery-${page + 1}`, method: 'tools/list',
+                params: cursor === null ? {} : { cursor } }), 'utf8');
+            const upstream = await this.#forward(alias, (access) => post(access.mcp_url, access.token, true, body, this.#controller.signal));
+            if (typeof upstream === 'string' || upstream.status !== 200)
+                return false;
+            const reply = record(parsed(upstream.body));
+            const listed = reply?.jsonrpc === '2.0' ? listedArguments(reply.result) : null;
+            if (!listed)
+                return false;
+            this.#remember(alias, listed.tools);
+            if (listed.next === null)
+                break;
+            cursor = listed.next;
+        }
+        // A list longer than the pages read leaves the rest undeclared here; root's guards still refuse a mismatch.
+        this.#discovered.add(alias);
+        return true;
+    }
+    // -------------------------------------------------------------------------
+    // Outbound (root's tool gateway).
+    /**
+     * Send one call upstream with a token, retried at most once with a fresh token
+     * and the same request (same idempotency key; a read is safe to repeat). Returns
+     * the gateway's answer, or a short local refusal code when no answer can be relayed.
+     */
+    async #forward(alias, send, serviceKey) {
+        let fresh = false;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            let access;
+            try {
+                access = await this.#token(alias, fresh);
+            }
+            catch {
+                return this.#closed ? 'dependency_unavailable' : 'dependency_not_ready';
+            }
+            if (serviceKey !== undefined && serviceKey !== access.service_key)
+                return 'service_key_mismatch';
+            let upstream;
+            try {
+                upstream = await send(access);
+            }
+            catch {
+                // No complete answer: retry once with a fresh token; the same key makes a committed write replay.
+                if (attempt === 0 && !this.#closed) {
+                    fresh = true;
+                    continue;
+                }
+                return 'dependency_unavailable';
+            }
+            const code = gatewayCode(upstream.body);
+            const refused = upstream.status === 401 || (upstream.status === 409 && code === 'tool_request_unavailable');
+            const overloaded = upstream.status === 503 && code === 'tool_capacity_unavailable';
+            if ((refused || overloaded) && attempt === 0 && !this.#closed) {
+                if (overloaded) {
+                    const wait = Math.min(5, Math.max(1, Number(header(upstream.headers, 'retry-after')) || 1));
+                    if (!await sleep(wait * 1_000, this.#controller.signal))
+                        return 'dependency_unavailable';
+                }
+                fresh = refused;
+                continue;
+            }
+            return upstream;
+        }
+        return 'dependency_unavailable';
+    }
+    /** A usable token for one alias: cached while valid (a freshly issued one is used at least once), else fetched single-flight. */
+    async #token(alias, fresh) {
+        const cached = this.#tokens.get(alias);
+        if (cached && !fresh && (performance.now() < cached.validUntil || !cached.used)) {
+            cached.used = true;
+            return cached.access;
+        }
+        let pending = this.#fetching.get(alias);
+        if (!pending) {
+            pending = this.#fetch(alias).finally(() => this.#fetching.delete(alias));
+            this.#fetching.set(alias, pending);
+        }
+        const access = await pending;
+        const entry = this.#tokens.get(alias);
+        if (entry?.access === access)
+            entry.used = true;
+        return access;
+    }
+    async #fetch(alias) {
+        const deadline = performance.now() + TOKEN_WAIT_MS;
+        for (let attempt = 0;; attempt++) {
+            if (this.#closed)
+                throw new CliError('dependency_proxy_closed', 'The drill stopped.');
+            let access;
+            try {
+                access = await this.#options.controlPlane.dependencyAccess(this.#options.assignment, alias, this.#controller.signal);
+            }
+            catch (error) {
+                const code = errorCode(error);
+                const status = error instanceof CliError ? error.httpStatus : null;
+                // Fenced, revoked, closed, or no gateway configured: nothing later in this drill can succeed.
+                if (isRevocation(error) || isFenced(error) || code === 'native_execution_closed'
+                    || (code === DEPENDENCY_ERRORS.unavailable && status === 503)) {
+                    this.#options.onFatal(error);
+                    throw error;
+                }
+                // Not admitted yet (409) or briefly unavailable: wait within this call's bound.
+                const retryable = (code === DEPENDENCY_ERRORS.unavailable && status === 409) || isTransient(error);
+                if (!retryable || performance.now() >= deadline || this.#closed)
+                    throw error;
+                if (!await sleep(Math.min(4_000, 500 * 2 ** attempt), this.#controller.signal))
+                    throw error;
+                continue;
+            }
+            const pinned = this.#pinned.get(alias);
+            if (pinned && (pinned.binding_digest !== access.binding_digest || pinned.service_key !== access.service_key
+                || pinned.invoke_url !== access.invoke_url || pinned.mcp_url !== access.mcp_url)) {
+                const changed = new CliError(DEPENDENCY_ERRORS.changed, `Simulated dependency "${alias}" changed during the drill, so the drill was stopped.`);
+                this.#options.onFatal(changed);
+                throw changed;
+            }
+            if (!pinned) {
+                this.#pinned.set(alias, { binding_digest: access.binding_digest, service_key: access.service_key,
+                    invoke_url: access.invoke_url, mcp_url: access.mcp_url });
+            }
+            // Monotonic window from receipt time, so a wall-clock jump never extends a token's use.
+            const lifetime = Math.min(30_000, access.expires_at * 1_000 - Date.now()) - TOKEN_MARGIN_MS;
+            this.#tokens.set(alias, { access, validUntil: performance.now() + lifetime, used: false });
+            return access;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+/** One POST to root's gateway with exactly the headers it accepts; the body is fully read (bounded). */
+export function post(url, token, mcp, body, signal) {
+    const headers = { 'content-type': 'application/json', 'content-length': String(body.length) };
+    if (mcp) {
+        headers.accept = 'application/json, text/event-stream';
+        headers['mcp-protocol-version'] = MCP_PROTOCOL_VERSION;
+    }
+    return send('POST', url, token, headers, body, signal);
+}
+/** One GET of an original operation on the isolated tool broker: no body, no query, no Origin or cookie. */
+export function get(url, token, signal) {
+    return send('GET', url, token, {}, null, signal);
+}
+function send(method, url, token, extra, body, signal) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        if (target.protocol !== 'https:') {
+            reject(new Error('insecure gateway'));
+            return;
+        }
+        if (method === 'GET' && target.search !== '') {
+            reject(new Error('query not allowed'));
+            return;
+        }
+        const headers = { authorization: `Bearer ${token.reveal()}`, ...extra };
+        const request = httpsRequest(target, { method, headers, signal: AbortSignal.any([signal, AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)]) }, (response) => {
+            const chunks = [];
+            let size = 0;
+            response.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > RESPONSE_MAX_BYTES) {
+                    response.destroy(new Error('response too large'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.once('end', () => resolve({ status: response.statusCode ?? 0, headers: response.headers, body: Buffer.concat(chunks) }));
+            response.once('error', reject);
+            response.once('aborted', () => reject(new Error('response aborted')));
+        });
+        request.once('error', reject);
+        if (body === null)
+            request.end();
+        else
+            request.end(body);
+    });
+}
+/** A JSON body, or null. */
+function parsed(bytes) {
+    try {
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+export function header(headers, name) {
+    const value = headers[name];
+    return typeof value === 'string' ? value : Array.isArray(value) ? value[0] ?? null : null;
+}
+/** Root's idempotency key format: 1..255 visible ASCII. */
+export function validKey(value) {
+    return typeof value === 'string' && /^[\x21-\x7e]{1,255}$/.test(value);
+}
+/** Root's MCP request key in `tools/call` `_meta`. */
+export const IDEMPOTENCY_META = 'firedrill/idempotency-key';
+/** Root's `tools/list` `_meta` naming a tool's declared transport idempotency argument (pinned operation contract). */
+export const IDEMPOTENCY_ARGUMENT = 'firedrill/idempotency-argument';
+/** Pages one proxy reads to learn the declared idempotency arguments (the broker lists 50 tools per page). */
+export const DISCOVERY_PAGES = 20;
+/**
+ * Each listed tool's declared idempotency argument, or null when it declares
+ * none. Returns null for a malformed list.
+ */
+export function listedArguments(result) {
+    const value = result && typeof result === 'object' && !Array.isArray(result) ? result : null;
+    if (!value || !Array.isArray(value.tools))
+        return null;
+    const tools = new Map();
+    for (const tool of value.tools) {
+        const row = tool && typeof tool === 'object' && !Array.isArray(tool) ? tool : null;
+        if (!row || typeof row.name !== 'string')
+            continue;
+        const meta = row._meta && typeof row._meta === 'object' && !Array.isArray(row._meta) ? row._meta : {};
+        const argument = meta[IDEMPOTENCY_ARGUMENT];
+        tools.set(row.name, typeof argument === 'string' && argument.length > 0 ? argument : null);
+    }
+    return { tools, next: typeof value.nextCursor === 'string' && value.nextCursor.length > 0 ? value.nextCursor : null };
+}
+/**
+ * The request key and arguments for one `tools/call`, following root's
+ * declared idempotency argument:
+ *  - a valid key the caller put in that argument is the request key; a different
+ *    explicit `_meta` key is a conflict (null);
+ *  - when the argument is absent, only that field is filled, with the same key
+ *    as `_meta` (the caller's, or a new one);
+ *  - an argument value that is not a valid key is left as it is for root's guards;
+ *  - no other field is ever changed, and an existing value is never replaced.
+ */
+export function keyedCall(args, meta, argument) {
+    const given = validKey(meta[IDEMPOTENCY_META]) ? meta[IDEMPOTENCY_META] : null;
+    if (argument === null)
+        return { key: given ?? randomUUID(), arguments: args };
+    if (!Object.hasOwn(args, argument)) {
+        const key = given ?? randomUUID();
+        return { key, arguments: { ...args, [argument]: key } };
+    }
+    const explicit = args[argument];
+    if (!validKey(explicit))
+        return { key: given ?? randomUUID(), arguments: args };
+    if (given !== null && given !== explicit)
+        return null;
+    return { key: explicit, arguments: args };
+}
+export function sameCap(given, expected) {
+    const a = Buffer.from(given), b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** The gateway's error code: flat `{"error":"<code>"}` (pooled gateway) or `{"error":{"code"}}` (isolated tool broker). */
+export function gatewayCode(bytes) {
+    if (bytes.length > 4_096)
+        return null;
+    const value = record(parsed(bytes));
+    if (typeof value?.error === 'string')
+        return value.error;
+    const nested = record(value?.error);
+    return typeof nested?.code === 'string' ? nested.code : null;
+}
+/** The request body, or null once it exceeds root's limit (the rest is drained, not buffered). */
+export function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let over = false;
+        request.on('data', (chunk) => {
+            if (over)
+                return;
+            size += chunk.length;
+            if (size > BODY_MAX_BYTES) {
+                over = true;
+                chunks.length = 0;
+                resolve(null);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.once('end', () => { if (!over)
+            resolve(Buffer.concat(chunks)); });
+        request.once('error', reject);
+    });
+}
+export function json(response, status, value, close = false) {
+    const body = Buffer.from(JSON.stringify(value), 'utf8');
+    response.writeHead(status, { 'content-type': 'application/json', 'content-length': String(body.length), 'cache-control': 'no-store',
+        ...(close ? { connection: 'close' } : {}) });
+    captured(response, status, body.length <= 131072 ? value : null, body.length <= 131072 ? 'json' : 'unavailable');
+    response.end(body);
+}
+export function rpcReply(response, id, payload) {
+    json(response, 200, { jsonrpc: '2.0', id, ...payload });
+}
+export function refuse(response, status, code, retryAfter, close = false) {
+    if (retryAfter !== undefined)
+        response.setHeader('retry-after', String(retryAfter));
+    json(response, status, { error: code }, close);
+}