firedrill-run 2.2.5 → 3.0.1

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

@@ -0,0 +1,580 @@
+/**
+ * Local access to started standalone tools (`firedrill tools access`).
+ *
+ * Root's terminal credential for a standalone instance lives at most 30 seconds
+ * and must stay in this process's memory, so an agent on this machine is given
+ * stable loopback URLs instead and this proxy fetches credentials lazily and
+ * forwards each call to the instance's isolated tool host:
+ *  - `POST /{cap}/{instance}/v1/invoke`: the Firedrill operation protocol
+ *    `{service_key?, operation, arguments, idempotency_key?}`;
+ *  - `POST /{cap}/{instance}/mcp`: JSON-response MCP (`initialize`, `ping`,
+ *    `tools/list`, `tools/call`); notifications are accepted locally. Every
+ *    `tools/call` carries an idempotency key in `_meta`, because a generic MCP
+ *    client cannot add one.
+ * The operations an agent can call are exactly what root's credential grants
+ * for the instance and mode (`read` grants read-only operations), as the tool
+ * host's tools/list shows; any other operation is refused here and never sent.
+ * On both routes an operation's declared idempotency argument carries the same
+ * key as the call's idempotency key.
+ *
+ * Guards (shared with the drill dependency proxy): loopback only, exact Host,
+ * no Origin, a random path capability compared in constant time, root's 1 MiB
+ * body limit. A call is retried at most once, with a fresh credential and the
+ * same idempotency key, so a committed write replays and never happens twice.
+ * The credential is never printed, logged or written anywhere.
+ *
+ * An isolated child of a tool setup is served on the same server with its own
+ * scoped connection (`isolated-access.ts`), passed through as root defines it:
+ *  - `POST|DELETE /{cap}/{instance}/mcp`: root's Streamable HTTP MCP (sessions,
+ *    event-stream answers); the MCP headers are passed on, never a cookie or Origin;
+ *  - `POST /{cap}/{instance}/operations/{service_key}/{operation_name}` with
+ *    `{"arguments": {...}}` and an `Idempotency-Key` UUID (one is made and
+ *    returned when absent); `GET /{cap}/{instance}/requests/{key}` reads it back.
+ * Nothing is retried there: root keys each call by its original request, so a
+ * lost answer is read back or resent with the same key, never a new one.
+ */
+import { randomBytes, randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { performance } from 'node:perf_hooks';
+import { CliError } from '../http.js';
+import { errorCode, isTransient, sleep } from './control-plane.js';
+import { BODY_MAX_BYTES, IDEMPOTENCY_META, gatewayCode, json, keyedCall, listedArguments, post, readBody, record, refuse, rpcReply, sameCap, validKey, } from './dependency-proxy.js';
+import { getStandaloneInstance, standaloneCredential, STANDALONE_ACTIVE } from './standalone-tools.js';
+import { CLEANUP_MS, ISOLATED_BODY_MAX_BYTES, MCP_REQUEST_HEADERS, MCP_RESPONSE_HEADERS, OPERATION_RESPONSE_HEADERS, forwardIsolated, isolatedGrantState, pickHeaders, readBounded, } from './isolated-access.js';
+const ROUTE = /^\/([A-Za-z0-9_-]{43})\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/(v1\/invoke|mcp|operations\/([a-z][a-z0-9_-]{0,79})\/([A-Za-z][A-Za-z0-9_.-]{0,127})|requests\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}))$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An isolated operation that got no answer: root keeps the original under its key. */
+const ISOLATED_UNANSWERED_TEXT = 'The tool did not answer this call, so it may or may not have taken effect. Read it back at the requests URL with the same idempotency key, or resend it with that same key. Never resend it under a new key.';
+/** An isolated MCP tools/call that got no answer: root keys it by the MCP session and the request id. */
+const ISOLATED_RPC_UNANSWERED_TEXT = 'The tool did not answer this call, so it may or may not have taken effect. Resend it with the same request id in the same MCP session; the tool returns the original result and never runs it twice. Never resend it with a new id.';
+const TOKEN_MARGIN_MS = 5_000;
+/** How long one call waits for a credential while root is briefly unavailable. */
+const TOKEN_WAIT_MS = 30_000;
+const INVOKE_KEYS = new Set(['service_key', 'operation', 'arguments', 'idempotency_key']);
+const RPC_KEYS = new Set(['jsonrpc', 'id', 'method', 'params']);
+const FORWARDED = new Set(['initialize', 'ping', 'tools/list', 'tools/call']);
+/** A call that may have reached the tool without an answer coming back (the tool host gives one code to every failure). */
+const UNANSWERED_TEXT = 'The tool 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.';
+export const STANDALONE_ACCESS_ERRORS = {
+    /** The instance is no longer active, or was reset to a new generation: start access again. */
+    ended: 'native_tool_access_ended',
+    /** Root's tool host for the instance changed between two credentials. */
+    changed: 'native_tool_access_changed',
+    /** An isolated tool's connection expired or was revoked. It is never renewed here: run access again for a new one. */
+    connectionEnded: 'tool_connection_ended',
+};
+/** The longest single timer Node accepts; a later expiry is checked again when it fires. */
+const TIMER_MAX_MS = 2_147_483_647;
+/** One grant check per isolated instance in this window, however many calls root refuses. */
+const CONFIRM_INTERVAL_MS = 30_000;
+export class StandaloneProxy {
+    #options;
+    #server;
+    #cap;
+    #instances;
+    #isolated;
+    #tokens = new Map();
+    #fetching = new Map();
+    #origins = new Map();
+    #ended = new Map();
+    #controller = new AbortController();
+    /** Per instance: each tool's declared idempotency argument (null: none), from root's tools/list metadata. */
+    #arguments = new Map();
+    #discovering = new Map();
+    /** Per isolated instance: the timer that ends it when its connection expires. */
+    #expiries = new Map();
+    /** Isolated instances whose grant is being checked after root refused a call, and when each was last checked. */
+    #confirming = new Set();
+    #confirmedAt = new Map();
+    #port = 0;
+    #closed = false;
+    constructor(options) {
+        this.#options = options;
+        this.#cap = randomBytes(32).toString('base64url');
+        this.#instances = new Map(options.instances.filter((one) => one.state === STANDALONE_ACTIVE).map((one) => [one.id, one]));
+        this.#isolated = new Map((options.isolated ?? []).filter((one) => !this.#instances.has(one.instance_id)).map((one) => [one.instance_id, one]));
+        for (const grant of this.#isolated.values())
+            this.#expireAt(grant);
+        this.#server = createServer({ requestTimeout: 90_000, headersTimeout: 10_000 }, (request, response) => { void this.#handle(request, response); });
+        this.#server.on('clientError', (_error, socket) => socket.destroy());
+    }
+    static async start(options) {
+        const proxy = new StandaloneProxy(options);
+        if (!proxy.serving.length)
+            throw new CliError('native_tool_access_unavailable', 'None of these tools is running, so there is nothing to connect to.', 2);
+        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;
+    }
+    /** The instances this proxy serves and has not ended. */
+    get serving() { return [...this.#instances.keys(), ...this.#isolated.keys()].filter((key) => !this.#ended.has(key)); }
+    /** Local URLs for one instance. They carry the path capability: they work only on this machine and only while the proxy runs. */
+    urls(instanceId) {
+        const prefix = `http://127.0.0.1:${this.#port}/${this.#cap}/${instanceId}`;
+        if (this.#instances.has(instanceId))
+            return { lane: 'pooled', mcp: `${prefix}/mcp`, invoke: `${prefix}/v1/invoke` };
+        if (this.#isolated.has(instanceId))
+            return { lane: 'isolated', mcp: `${prefix}/mcp`, operations: `${prefix}/operations`, requests: `${prefix}/requests` };
+        throw new CliError('native_tool_access_unavailable', 'That tool is not served here.');
+    }
+    /** Stop serving one instance (it ended at root). */
+    end(instanceId, code) {
+        if ((!this.#instances.has(instanceId) && !this.#isolated.has(instanceId)) || this.#ended.has(instanceId))
+            return;
+        this.#ended.set(instanceId, code);
+        this.#tokens.delete(instanceId);
+        clearTimeout(this.#expiries.get(instanceId));
+        this.#expiries.delete(instanceId);
+        this.#options.onEnded(instanceId, code);
+    }
+    /** An isolated entry stops being served when its connection expires; nothing renews it. */
+    #expireAt(grant) {
+        const left = Date.parse(grant.expires_at) - Date.now();
+        if (!(left > 0)) {
+            this.#ended.set(grant.instance_id, STANDALONE_ACCESS_ERRORS.connectionEnded);
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.#expiries.delete(grant.instance_id);
+            if (Date.parse(grant.expires_at) > Date.now())
+                this.#expireAt(grant);
+            else
+                this.end(grant.instance_id, STANDALONE_ACCESS_ERRORS.connectionEnded);
+        }, Math.min(left, TIMER_MAX_MS));
+        timer.unref();
+        this.#expiries.set(grant.instance_id, timer);
+    }
+    /** Root refused a call with this grant (401): end the entry only when root confirms the grant or instance is done. */
+    async #confirmIsolated(grant) {
+        if (this.#confirming.has(grant.instance_id) || this.#ended.has(grant.instance_id) || this.#closed
+            || Date.now() - (this.#confirmedAt.get(grant.instance_id) ?? 0) < CONFIRM_INTERVAL_MS)
+            return;
+        this.#confirming.add(grant.instance_id);
+        this.#confirmedAt.set(grant.instance_id, Date.now());
+        try {
+            const state = await isolatedGrantState(this.#options.scope, grant, AbortSignal.any([this.#controller.signal, AbortSignal.timeout(CLEANUP_MS)]));
+            if (state === 'connection_ended')
+                this.end(grant.instance_id, STANDALONE_ACCESS_ERRORS.connectionEnded);
+            else if (state === 'instance_ended')
+                this.end(grant.instance_id, STANDALONE_ACCESS_ERRORS.ended);
+        }
+        finally {
+            this.#confirming.delete(grant.instance_id);
+        }
+    }
+    /** Stop accepting calls, abort in-flight ones and forget every credential. Safe to call more than once. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#controller.abort();
+        this.#tokens.clear();
+        for (const timer of this.#expiries.values())
+            clearTimeout(timer);
+        this.#expiries.clear();
+        await new Promise((resolve) => { this.#server.close(() => resolve()); this.#server.closeAllConnections(); });
+    }
+    // -------------------------------------------------------------------------
+    // Inbound (the agent on this machine).
+    async #handle(request, response) {
+        try {
+            if (this.#closed)
+                return refuse(response, 503, 'tool_access_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 = ROUTE.exec(request.url ?? '');
+            if (!match || !sameCap(match[1], this.#cap))
+                return refuse(response, 404, 'not_found');
+            const isolated = this.#isolated.get(match[2]);
+            if (isolated) {
+                if (!(Date.parse(isolated.expires_at) > Date.now()))
+                    this.end(isolated.instance_id, STANDALONE_ACCESS_ERRORS.connectionEnded);
+                const ended = this.#ended.get(isolated.instance_id);
+                if (ended)
+                    return refuse(response, 410, ended);
+                return await this.#isolatedCall(isolated, match, request, response);
+            }
+            const instance = match[3] === 'mcp' || match[3] === 'v1/invoke' ? this.#instances.get(match[2]) : undefined;
+            if (!instance)
+                return refuse(response, 404, 'not_found');
+            if (request.method !== 'POST')
+                return refuse(response, 405, 'method_not_supported');
+            const ended = this.#ended.get(instance.id);
+            if (ended)
+                return refuse(response, 410, ended);
+            const declared = Number(request.headers['content-length']);
+            if (Number.isFinite(declared) && declared > BODY_MAX_BYTES)
+                return refuse(response, 413, 'request_too_large', undefined, true);
+            const body = await readBody(request);
+            if (body === null)
+                return refuse(response, 413, 'request_too_large', undefined, true);
+            let message;
+            try {
+                message = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                return refuse(response, 400, 'request_invalid');
+            }
+            if (match[3] === 'mcp')
+                await this.#mcp(instance, message, response);
+            else
+                await this.#invoke(instance, message, response);
+        }
+        catch {
+            if (!response.headersSent)
+                refuse(response, 502, 'tool_unavailable');
+            else
+                response.destroy();
+        }
+    }
+    /** One call for an isolated instance, passed through on its grant (never retried; see the module note). */
+    async #isolatedCall(grant, match, request, response) {
+        const route = match[3];
+        const declared = Number(request.headers['content-length']);
+        if (Number.isFinite(declared) && declared > ISOLATED_BODY_MAX_BYTES)
+            return refuse(response, 413, 'request_too_large', undefined, true);
+        const forward = async (url, method, headers, body, passBack, extra) => {
+            const sent = await forwardIsolated({ url, token: grant.token, method, headers, body, passBack, extra, response, signal: this.#controller.signal });
+            // Root's 401 is passed back as it is; whether the entry ends is decided by reading the grant, never by the 401 alone.
+            if (sent === 401)
+                void this.#confirmIsolated(grant).catch(() => undefined);
+            return sent;
+        };
+        if (route === 'mcp') {
+            // Root's MCP endpoint offers no server-initiated stream (GET), as it says itself.
+            if (request.method === 'GET') {
+                response.writeHead(405, { allow: 'POST, DELETE', 'cache-control': 'no-store', 'content-length': '0' });
+                response.end();
+                return;
+            }
+            if (request.method !== 'POST' && request.method !== 'DELETE')
+                return refuse(response, 405, 'method_not_supported');
+            const method = request.method === 'DELETE' ? 'DELETE' : 'POST';
+            const body = method === 'POST' ? await readBounded(request, ISOLATED_BODY_MAX_BYTES) : null;
+            if (method === 'POST' && body === null)
+                return refuse(response, 413, 'request_too_large', undefined, true);
+            const sent = await forward(grant.mcp_url, method, pickHeaders(request, MCP_REQUEST_HEADERS), body, MCP_RESPONSE_HEADERS);
+            if (sent !== 'unanswered')
+                return;
+            let rpc = null;
+            try {
+                rpc = body ? record(JSON.parse(body.toString('utf8'))) : null;
+            }
+            catch {
+                rpc = null;
+            }
+            const id = rpc && (typeof rpc.id === 'string' || Number.isSafeInteger(rpc.id)) ? rpc.id : undefined;
+            if (id === undefined)
+                return refuse(response, 502, 'tool_unavailable');
+            return rpcReply(response, id, { error: { code: -32603, message: rpc?.method === 'tools/call' ? ISOLATED_RPC_UNANSWERED_TEXT : 'The tool did not answer.' } });
+        }
+        if (route.startsWith('requests/')) {
+            if (request.method !== 'GET')
+                return refuse(response, 405, 'method_not_supported');
+            const sent = await forward(`${grant.requests_url}/${match[6]}`, 'GET', {}, null, OPERATION_RESPONSE_HEADERS);
+            if (sent === 'unanswered')
+                refuse(response, 502, 'tool_unavailable');
+            return;
+        }
+        // operations/{service_key}/{operation_name}
+        if (request.method !== 'POST')
+            return refuse(response, 405, 'method_not_supported');
+        if (!grant.operations.some((one) => one.service_key === match[4] && one.operation_name === match[5])) {
+            return json(response, 403, { error: 'operation_not_connected', message: 'This operation is not part of this connection (read-only unless writes were allowed). Nothing was sent.' }, true);
+        }
+        const given = request.headers['idempotency-key'];
+        if (given !== undefined && (typeof given !== 'string' || !UUID.test(given))) {
+            return json(response, 400, { error: 'request_invalid', message: 'Use a UUID as the Idempotency-Key, and reuse it to read or resend the same call.' });
+        }
+        const key = typeof given === 'string' ? given.toLowerCase() : randomUUID();
+        const body = await readBounded(request, ISOLATED_BODY_MAX_BYTES);
+        if (body === null)
+            return refuse(response, 413, 'request_too_large', undefined, true);
+        const sent = await forward(`${grant.operations_url}/${match[4]}/${match[5]}`, 'POST', { ...pickHeaders(request, ['content-type']), 'idempotency-key': key }, body, OPERATION_RESPONSE_HEADERS, { 'idempotency-key': key });
+        if (sent === 'unanswered')
+            json(response, 502, { error: 'tool_unavailable', idempotency_key: key, message: ISOLATED_UNANSWERED_TEXT });
+    }
+    async #invoke(instance, message, response) {
+        const call = record(message);
+        if (!call || !Object.keys(call).every((key) => INVOKE_KEYS.has(key)) || typeof call.operation !== 'string'
+            || (call.arguments !== undefined && !record(call.arguments))
+            || (call.service_key !== undefined && call.service_key !== instance.service_key)
+            || (call.idempotency_key !== undefined && !validKey(call.idempotency_key)))
+            return refuse(response, 400, 'request_invalid');
+        const tools = await this.#idempotencyArgument(instance);
+        if (tools === undefined) {
+            const ended = this.#ended.get(instance.id);
+            if (ended)
+                return refuse(response, 410, ended);
+            response.setHeader('retry-after', '1');
+            return json(response, 503, { error: 'tool_unavailable', message: 'The tool list could not be read, so nothing was sent. Try again.' });
+        }
+        // The tool host lists every granted operation: anything else would only be refused, so it is never sent.
+        if (!tools.has(call.operation))
+            return json(response, 403, { error: 'operation_not_connected', message: this.#notConnected() });
+        // The tool host refuses a write whose declared idempotency argument and idempotency_key differ, so both carry one key.
+        const argument = tools.get(call.operation) ?? null;
+        const keyed = keyedCall(record(call.arguments) ?? {}, typeof call.idempotency_key === 'string' ? { [IDEMPOTENCY_META]: call.idempotency_key } : {}, argument);
+        if (!keyed) {
+            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;
+        const upstream = await this.#forward(instance, 'invoke', { service_key: instance.service_key, operation: call.operation,
+            arguments: keyed.arguments, idempotency_key: key });
+        if (typeof upstream === 'string') {
+            return json(response, this.#ended.has(instance.id) ? 410 : 502, { error: upstream, idempotency_key: key, message: UNANSWERED_TEXT });
+        }
+        if (upstream.status === 409 && gatewayCode(upstream.body) === 'tool_access_unavailable') {
+            return json(response, 409, { error: 'tool_access_unavailable', idempotency_key: key, message: UNANSWERED_TEXT });
+        }
+        response.writeHead(upstream.status, { 'content-type': typeof upstream.headers['content-type'] === 'string' ? upstream.headers['content-type'] : 'application/octet-stream',
+            'content-length': String(upstream.body.length), 'cache-control': 'no-store' });
+        response.end(upstream.body);
+    }
+    async #mcp(instance, 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))) {
+            return refuse(response, 400, 'request_invalid');
+        }
+        // Notifications need no answer from the tool host.
+        if (rpc.id === undefined) {
+            response.writeHead(202, { 'cache-control': 'no-store', 'content-length': '0' });
+            response.end();
+            return;
+        }
+        const id = rpc.id;
+        if (id === null || (typeof id === 'string' && id.length > 200))
+            return rpcReply(response, id, { error: { code: -32600, message: 'Use a request id of up to 200 characters.' } });
+        if (!FORWARDED.has(rpc.method))
+            return rpcReply(response, id, { error: { code: -32601, message: 'Method not found' } });
+        const params = record(rpc.params) ?? {};
+        let forwarded;
+        let key = null;
+        if (rpc.method === 'tools/call') {
+            if (typeof params.name !== 'string' || (params.arguments !== undefined && !record(params.arguments))
+                || (params._meta !== undefined && !record(params._meta))) {
+                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(instance);
+            if (argument === undefined) {
+                return rpcReply(response, id, { error: { code: -32603, message: 'The tool list could not be read, so nothing was sent. Try again.' } });
+            }
+            // The tool host lists every granted operation: anything else would only be refused, so it is never sent.
+            if (!argument.has(params.name))
+                return rpcReply(response, id, { error: { code: -32602, message: this.#notConnected() } });
+            const meta = record(params._meta) ?? {};
+            const keyed = keyedCall(record(params.arguments) ?? {}, meta, argument.get(params.name) ?? null);
+            if (!keyed) {
+                return rpcReply(response, id, { error: { code: -32602,
+                        message: `The ${argument.get(params.name)} argument and _meta ${IDEMPOTENCY_META} name different keys, so nothing was sent. Use one key.` } });
+            }
+            key = keyed.key;
+            forwarded = { jsonrpc: '2.0', id, method: 'tools/call',
+                params: { name: params.name, arguments: keyed.arguments, _meta: { ...meta, [IDEMPOTENCY_META]: key } } };
+        }
+        else if (rpc.method === 'tools/list') {
+            // The tool host lists every granted tool at once and takes no cursor.
+            forwarded = { jsonrpc: '2.0', id, method: 'tools/list', params: record(params._meta) ? { _meta: params._meta } : {} };
+        }
+        else {
+            forwarded = { jsonrpc: '2.0', id, method: rpc.method, params };
+        }
+        const upstream = await this.#forward(instance, 'mcp', forwarded);
+        if (typeof upstream === 'string' || upstream.status !== 200) {
+            const ended = this.#ended.has(instance.id);
+            return rpcReply(response, id, { error: { code: -32603, message: ended
+                        ? 'This tool is no longer reachable through this connection. Run firedrill tools access again.'
+                        : key ? UNANSWERED_TEXT : 'The tool refused the call or did not answer.',
+                    ...(key ? { data: { 'firedrill/idempotency-key': key } } : {}) } });
+        }
+        let reply;
+        try {
+            reply = record(JSON.parse(upstream.body.toString('utf8')));
+        }
+        catch {
+            reply = null;
+        }
+        if (!reply || reply.jsonrpc !== '2.0')
+            return rpcReply(response, id, { error: { code: -32603, message: 'The tool answered malformed JSON.' } });
+        if (rpc.method === 'tools/list') {
+            const listed = listedArguments(reply.result);
+            if (listed)
+                this.#arguments.set(instance.id, listed.tools);
+        }
+        return json(response, 200, { ...reply, id });
+    }
+    /** Why a call to an operation this connection does not grant was refused before sending, with the next step for its mode. */
+    #notConnected() {
+        return this.#options.mode === 'read'
+            ? 'This operation is not part of this read-only connection, so nothing was sent. Use a tool from tools/list. '
+                + 'Writes need firedrill tools access <session-id> --allow-writes, only when the human asked for writes.'
+            : 'This operation is not part of this connection, so nothing was sent. Use a tool from tools/list.';
+    }
+    /**
+     * Each tool's declared idempotency argument for one instance (null: none),
+     * read once from the tool host's tools/list, single-flight. Undefined when the
+     * list could not be read: the call is not sent rather than sent unshaped.
+     */
+    async #idempotencyArgument(instance) {
+        const known = this.#arguments.get(instance.id);
+        if (known)
+            return known;
+        let pending = this.#discovering.get(instance.id);
+        if (!pending) {
+            pending = (async () => {
+                const upstream = await this.#forward(instance, 'mcp', { jsonrpc: '2.0', id: 'firedrill-discovery', method: 'tools/list', params: {} });
+                if (typeof upstream === 'string' || upstream.status !== 200)
+                    return undefined;
+                let reply;
+                try {
+                    reply = record(JSON.parse(upstream.body.toString('utf8')));
+                }
+                catch {
+                    reply = null;
+                }
+                const listed = reply?.jsonrpc === '2.0' ? listedArguments(reply.result) : null;
+                if (!listed)
+                    return undefined;
+                this.#arguments.set(instance.id, listed.tools);
+                return listed.tools;
+            })().finally(() => this.#discovering.delete(instance.id));
+            this.#discovering.set(instance.id, pending);
+        }
+        return pending;
+    }
+    // -------------------------------------------------------------------------
+    // Outbound (the instance's tool host).
+    /** One call with a credential, retried at most once with a fresh credential and the same body. */
+    async #forward(instance, kind, body) {
+        const bytes = Buffer.from(JSON.stringify(body), 'utf8');
+        let fresh = false;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            let credential;
+            try {
+                credential = await this.#credential(instance, fresh);
+            }
+            catch {
+                return this.#ended.get(instance.id) ?? 'tool_access_unavailable';
+            }
+            let upstream;
+            try {
+                upstream = await post(kind === 'invoke' ? credential.invoke_url : credential.mcp_url, credential.token, kind === 'mcp', bytes, this.#controller.signal);
+            }
+            catch {
+                // No complete answer: once more with a fresh credential; the same key makes a committed write replay.
+                if (attempt === 0 && !this.#closed) {
+                    fresh = true;
+                    continue;
+                }
+                return 'tool_unavailable';
+            }
+            // The tool host answers every refusal, an expired credential included, with this one code.
+            if (upstream.status === 409 && gatewayCode(upstream.body) === 'tool_access_unavailable' && attempt === 0 && !this.#closed) {
+                fresh = true;
+                continue;
+            }
+            return upstream;
+        }
+        return 'tool_unavailable';
+    }
+    /** A usable credential: cached while valid (a fresh one is used at least once), else fetched single-flight. */
+    async #credential(instance, fresh) {
+        const cached = this.#tokens.get(instance.id);
+        if (cached && !fresh && (performance.now() < cached.validUntil || !cached.used)) {
+            cached.used = true;
+            return cached.credential;
+        }
+        let pending = this.#fetching.get(instance.id);
+        if (!pending) {
+            pending = this.#fetch(instance).finally(() => this.#fetching.delete(instance.id));
+            this.#fetching.set(instance.id, pending);
+        }
+        const credential = await pending;
+        const entry = this.#tokens.get(instance.id);
+        if (entry?.credential === credential)
+            entry.used = true;
+        return credential;
+    }
+    async #fetch(instance) {
+        const deadline = performance.now() + TOKEN_WAIT_MS;
+        let checked = false;
+        for (let attempt = 0;; attempt++) {
+            if (this.#closed)
+                throw new CliError('tool_access_closed', 'Tool access stopped.');
+            const ended = this.#ended.get(instance.id);
+            if (ended)
+                throw new CliError(ended, 'This tool is no longer served here.');
+            let credential;
+            try {
+                credential = await standaloneCredential(this.#options.scope, { instance, mode: this.#options.mode, signal: this.#controller.signal });
+            }
+            catch (error) {
+                const status = error instanceof CliError ? error.httpStatus : null;
+                const code = errorCode(error);
+                // The terminal is signed out, its workspace changed, or no tool host is configured: nothing here can succeed.
+                if (status === 401 || code === 'native_workspace_changed' || (status === 503 && code === 'tool_access_unavailable')) {
+                    this.#options.onFatal(error);
+                    throw error;
+                }
+                // Root answers a stopped or expired instance with 410 tool_instance_ended: end access at once.
+                if (status === 410 && code === 'tool_instance_ended') {
+                    this.end(instance.id, STANDALONE_ACCESS_ERRORS.ended);
+                    throw error;
+                }
+                // An older root answered it with a generic 500, so read the instance once before waiting.
+                if (status === 500 && !checked && !this.#closed) {
+                    checked = true;
+                    if (await this.#gone(instance)) {
+                        this.end(instance.id, STANDALONE_ACCESS_ERRORS.ended);
+                        throw error;
+                    }
+                }
+                if (isTransient(error) && performance.now() < deadline && !this.#closed) {
+                    if (!await sleep(Math.min(4_000, 500 * 2 ** attempt), this.#controller.signal))
+                        throw error;
+                    continue;
+                }
+                // Answered: the instance was reset to a new generation (409 tool_access_changed), root refused
+                // access to it (409 tool_access_unavailable), or this mode is not allowed.
+                if (status !== null && status >= 400 && status < 500)
+                    this.end(instance.id, code === 'tool_access_changed' ? STANDALONE_ACCESS_ERRORS.ended : code ?? STANDALONE_ACCESS_ERRORS.ended);
+                throw error;
+            }
+            const origin = new URL(credential.invoke_url).origin;
+            const pinned = this.#origins.get(instance.id);
+            if (pinned && pinned !== origin) {
+                this.end(instance.id, STANDALONE_ACCESS_ERRORS.changed);
+                throw new CliError(STANDALONE_ACCESS_ERRORS.changed, 'The tool host changed while connected.');
+            }
+            this.#origins.set(instance.id, origin);
+            // Monotonic window from receipt time, so a wall-clock jump never extends a credential's use.
+            const lifetime = Math.min(30_000, credential.expires_at * 1_000 - Date.now()) - TOKEN_MARGIN_MS;
+            this.#tokens.set(instance.id, { credential, validUntil: performance.now() + lifetime, used: false });
+            return credential;
+        }
+    }
+    /** Whether root says the instance can no longer be served here: not active, reset to a new generation, or gone. */
+    async #gone(instance) {
+        try {
+            const current = await getStandaloneInstance(this.#options.scope, { instanceId: instance.id, signal: this.#controller.signal });
+            return current.state !== STANDALONE_ACTIVE || current.generation !== instance.generation;
+        }
+        catch (error) {
+            return error instanceof CliError && error.httpStatus === 404;
+        }
+    }
+}