@peakflo/agent-harness 0.2.11-rc.2 → 0.2.11-rc.4

package/dist/runtime/mcp-auth-proxy.js

@@ -37,10 +37,205 @@
  * test suite asserts the bind address.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpAuthProxy = void 0;
+exports.McpAuthProxy = exports.BROWSER_HOLD_ATTEMPT_TIMEOUT_MS = exports.BROWSER_HOLD_MAX_FAILURES = exports.BROWSER_HOLD_MAX_BODY_BYTES = void 0;
+exports.listenLoopback = listenLoopback;
+exports.loopbackPortFromEnv = loopbackPortFromEnv;
+const node_crypto_1 = require("node:crypto");
 const node_http_1 = require("node:http");
 const node_https_1 = require("node:https");
-const node_crypto_1 = require("node:crypto");
+const browser_takeover_1 = require("./browser-takeover");
+const loopback_peer_1 = require("./loopback-peer");
+/** Largest agent request body the browser hold buffers to re-send. */
+exports.BROWSER_HOLD_MAX_BODY_BYTES = 1024 * 1024;
+/** Consecutive upstream failures (network/5xx) a hold tolerates. */
+exports.BROWSER_HOLD_MAX_FAILURES = 10;
+/** A takeover 409 faster than this was not held by the gateway: back off. */
+const BROWSER_HOLD_FAST_ANSWER_MS = 5_000;
+/**
+ * Longest a held re-send may wait for response headers before it counts as a
+ * transient upstream failure. The gateway holds one await-handback request
+ * for 20 s; after a handback it runs the call (a broker command is at most
+ * ~65 s), so this only fires for a gateway that has silently gone away — a
+ * hung socket would otherwise park Pi until its 24 h MCP timeout.
+ */
+exports.BROWSER_HOLD_ATTEMPT_TIMEOUT_MS = 180_000;
+/** Largest 409 takeover body read (it is a small JSON document). */
+const BROWSER_TAKEOVER_BODY_MAX_BYTES = 64 * 1024;
+/**
+ * Listen on 127.0.0.1:`port` (0 = ephemeral). When a FIXED port is taken the
+ * listener falls back to an ephemeral one and says so loudly, rather than
+ * failing the harness start: the per-uid `BrowserPeerGuard` still refuses a
+ * chat browser on any port, and the fixed number only feeds a defence-in-depth
+ * deny rule. Resolves with the bound port.
+ */
+function listenLoopback(server, port, logger, label) {
+    const attempt = (wanted) => new Promise((resolvePort, reject) => {
+        const onError = (error) => reject(error);
+        server.once('error', onError);
+        server.listen(wanted, '127.0.0.1', () => {
+            server.removeListener('error', onError);
+            const address = server.address();
+            if (typeof address === 'object' && address)
+                resolvePort(address.port);
+            else
+                reject(new Error(`${label} could not determine its address`));
+        });
+    });
+    if (!port)
+        return attempt(0);
+    return attempt(port).catch((error) => {
+        if (error && error.code === 'EADDRINUSE') {
+            logger.warn(`[${label}] fixed port ${port} is in use; falling back to an ephemeral port`);
+            return attempt(0);
+        }
+        throw error;
+    });
+}
+/** A fixed loopback port from the environment, or 0 (ephemeral) when unset or invalid. */
+function loopbackPortFromEnv(value) {
+    if (!value)
+        return 0;
+    const port = Number(value);
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : 0;
+}
+/* -------------------------------------------------------------------------- */
+/* Browser hold helpers                                                        */
+/* -------------------------------------------------------------------------- */
+function isTakeover(response) {
+    return (response.statusCode === browser_takeover_1.BROWSER_TAKEOVER_STATUS &&
+        response.headers[browser_takeover_1.BROWSER_TAKEOVER_HEADER] !== undefined);
+}
+/**
+ * Read a stream into a buffer. Over `limit`: null, or (with `truncate`) the
+ * first `limit` bytes. Never rejects; a broken stream yields what was read.
+ */
+function readBounded(stream, limit, truncate = false) {
+    return new Promise((resolveBody) => {
+        const chunks = [];
+        let size = 0;
+        let over = false;
+        stream.on('data', (chunk) => {
+            if (over)
+                return;
+            size += chunk.length;
+            if (size > limit) {
+                over = true;
+                if (truncate) {
+                    chunks.push(chunk.subarray(0, chunk.length - (size - limit)));
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        const done = () => resolveBody(over && !truncate ? null : Buffer.concat(chunks));
+        stream.once('end', done);
+        stream.once('error', done);
+        stream.once('close', done);
+    });
+}
+function parseJsonOrText(buffer) {
+    const text = buffer ? buffer.toString('utf8') : '';
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Stream an upstream response back unchanged (SSE flushed per chunk). */
+function pipeUpstreamResponse(proxyRes, res) {
+    if (res.destroyed) {
+        proxyRes.resume();
+        return;
+    }
+    const responseHeaders = { ...proxyRes.headers };
+    const contentType = String(proxyRes.headers['content-type'] || '');
+    const isSSE = contentType.includes('text/event-stream');
+    if (!isSSE)
+        delete responseHeaders['transfer-encoding'];
+    res.writeHead(proxyRes.statusCode || 502, responseHeaders);
+    if (isSSE) {
+        proxyRes.on('data', (chunk) => {
+            res.write(chunk);
+        });
+        proxyRes.on('end', () => res.end());
+    }
+    else {
+        proxyRes.pipe(res);
+    }
+    // An upstream reset mid-body (a Cloud Run instance going away) must not
+    // leave Pi waiting on a half-written answer: `pipe` never ends `res` then,
+    // and a clean `end()` would pass a truncated body off as complete.
+    proxyRes.once('close', () => {
+        if (!proxyRes.complete && !res.writableEnded)
+            res.destroy();
+    });
+    res.once('close', () => {
+        if (!proxyRes.complete)
+            proxyRes.destroy();
+    });
+}
+function writeJson(res, status, value) {
+    if (res.destroyed || res.headersSent) {
+        if (!res.writableEnded)
+            res.end();
+        return;
+    }
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(value));
+}
+/**
+ * Answer the agent's held call with a JSON-RPC error for ITS request id, so
+ * the tool call fails visibly instead of the turn hanging. A body without a
+ * single request id (batch, notification, unparsable) gets HTTP 502 JSON.
+ */
+function writeJsonRpcError(res, body, message) {
+    const request = parseJsonOrText(body);
+    const id = request && typeof request === 'object' && !Array.isArray(request)
+        ? request.id
+        : undefined;
+    if (typeof id === 'string' || typeof id === 'number') {
+        writeJson(res, 200, {
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32603, message }
+        });
+        return;
+    }
+    writeJson(res, 502, { error: message });
+}
+/** `promise`, or `onAbort` as soon as `signal` aborts (whichever is first). */
+function untilAborted(promise, signal, onAbort) {
+    if (signal.aborted)
+        return Promise.resolve(onAbort);
+    return new Promise((resolveValue, rejectValue) => {
+        const abort = () => resolveValue(onAbort);
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', abort);
+            resolveValue(value);
+        }, (error) => {
+            signal.removeEventListener('abort', abort);
+            rejectValue(error);
+        });
+    });
+}
+function delay(ms, signal) {
+    return new Promise((resolveDelay) => {
+        if (signal.aborted || ms <= 0) {
+            resolveDelay();
+            return;
+        }
+        const pending = {};
+        const done = () => {
+            clearTimeout(pending.timer);
+            signal.removeEventListener('abort', done);
+            resolveDelay();
+        };
+        pending.timer = setTimeout(done, ms);
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
 class McpAuthProxy {
     options;
     server = null;
@@ -51,9 +246,14 @@ class McpAuthProxy {
     /** One notification per integration per process, not one per failed call. */
     notifiedFailures = new Set();
     logger;
+    /** Browser calls held during a takeover. Cancelled on `stop()`. */
+    browserHolds = new Set();
+    /** Chat browsers run as their own uids; they get nothing from this proxy. */
+    peerGuard;
     constructor(options) {
         this.options = options;
         this.logger = options.logger ?? console;
+        this.peerGuard = new loopback_peer_1.BrowserPeerGuard(options.peerUid);
     }
     getPort() {
         return this.port;
@@ -106,24 +306,45 @@ class McpAuthProxy {
         }
         return new Promise((resolvePort, reject) => {
             const server = (0, node_http_1.createServer)((req, res) => {
+                if (this.peerGuard.refuse(req.socket, res)) {
+                    return;
+                }
                 void this.handleRequest(req, res);
             });
+            this.peerGuard.attach(server);
             this.server = server;
-            server.once('error', reject);
-            // LOOPBACK ONLY. Never 0.0.0.0, never a fixed port.
-            server.listen(0, '127.0.0.1', () => {
-                const address = server.address();
-                if (typeof address === 'object' && address) {
-                    this.port = address.port;
-                    resolvePort(address.port);
-                }
-                else {
-                    reject(new Error('MCP auth proxy could not determine its address'));
-                }
-            });
+            // LOOPBACK ONLY. Never 0.0.0.0. Ephemeral unless options.port pins it.
+            listenLoopback(server, this.options.port ?? 0, this.logger, 'McpAuthProxy')
+                .then((port) => {
+                this.port = port;
+                resolvePort(port);
+            })
+                .catch(reject);
         });
     }
+    /**
+     * Cancel every held browser call whose gateway URL starts with
+     * `targetUrlPrefix` (a full target URL, or `.../api/mcp/agent/<sessionId>/`
+     * for a whole session). Held calls are answered with a JSON-RPC error and
+     * the hook gets `end` / `cancelled`. Returns how many were cancelled.
+     */
+    cancelBrowserHolds(targetUrlPrefix) {
+        let count = 0;
+        for (const hold of this.browserHolds) {
+            if (hold.targetUrl.startsWith(targetUrlPrefix)) {
+                hold.controller.abort();
+                count += 1;
+            }
+        }
+        return count;
+    }
+    /** Number of browser calls currently held. For tests and diagnostics. */
+    activeBrowserHolds() {
+        return this.browserHolds.size;
+    }
     async stop() {
+        for (const hold of this.browserHolds)
+            hold.controller.abort();
         const server = this.server;
         this.server = null;
         this.port = null;
@@ -195,6 +416,10 @@ class McpAuthProxy {
                     targetUrl.pathname.replace(/\/$/, '') + '/' + subPath.join('/');
             }
             targetUrl.search = reqUrl.search;
+            if ((0, browser_takeover_1.isBrowserTargetUrl)(target.url)) {
+                await this.handleBrowserRequest(req, res, id, target, targetUrl);
+                return;
+            }
             let token;
             try {
                 token = await this.options.tokens.getToken(target.url);
@@ -288,6 +513,249 @@ class McpAuthProxy {
             }
         }
     }
+    /**
+     * THE BROWSER TAKEOVER HOLD (sandbox browser). Only for the built-in
+     * `pf-browser` gateway server; every other target takes the plain streaming
+     * path above, unchanged.
+     *
+     * While a person controls the chat browser, the gateway answers a waiting
+     * browser tool with 409 + `x-pf-browser-takeover`. That answer is NOT handed
+     * to Pi: the agent's call stays open (Pi's timeout for this server is 24 h)
+     * and the SAME body is re-sent with `x-pf-browser-await-handback: 1` — each
+     * with a fresh token — until the gateway answers anything else (it holds
+     * each such request up to 20 s and, after a handback, rewrites the call into
+     * a fresh snapshot). That answer is streamed back to Pi unchanged. The turn
+     * is never aborted; the SessionRunner counts the time as an intentional
+     * pause through `onBrowserPause`.
+     */
+    async handleBrowserRequest(req, res, id, target, targetUrl) {
+        const body = await readBounded(req, exports.BROWSER_HOLD_MAX_BODY_BYTES);
+        if (res.destroyed)
+            return;
+        if (body === null) {
+            res.writeHead(413, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Browser MCP request body too large' }));
+            return;
+        }
+        let token;
+        try {
+            token = await this.options.tokens.getToken(target.url);
+        }
+        catch (error) {
+            this.reportTokenFailure(id, target.label, error);
+            if (res.destroyed)
+                return;
+            res.writeHead(502, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: `Failed to obtain auth token for "${target.label}"`
+            }));
+            return;
+        }
+        if (res.destroyed)
+            return;
+        // One controller for the request's whole life: Pi closing it, a cancel,
+        // or `stop()` all abort the in-flight upstream request and the backoff.
+        const hold = {
+            targetUrl: target.url,
+            controller: new AbortController()
+        };
+        const signal = hold.controller.signal;
+        let clientClosed = false;
+        const onClose = () => {
+            if (!res.writableEnded) {
+                clientClosed = true;
+                hold.controller.abort();
+            }
+        };
+        res.once('close', onClose);
+        this.browserHolds.add(hold);
+        let holding = false;
+        const endHold = (reason) => {
+            if (!holding)
+                return;
+            holding = false;
+            this.callBrowserHook(target.url, { state: 'end', reason });
+        };
+        try {
+            let outcome = await this.sendBuffered(req, targetUrl, body, token, false, signal);
+            if (outcome.kind === 'error') {
+                if (signal.aborted)
+                    return;
+                this.logger.error(`[McpAuthProxy] Upstream error for "${target.label}": ${outcome.error.message}`);
+                writeJson(res, 502, {
+                    error: `Upstream error: ${outcome.error.message}`
+                });
+                return;
+            }
+            if (!isTakeover(outcome.response)) {
+                pipeUpstreamResponse(outcome.response, res);
+                return;
+            }
+            const takeoverText = await readBounded(outcome.response, BROWSER_TAKEOVER_BODY_MAX_BYTES, true);
+            if (signal.aborted)
+                return;
+            holding = true;
+            const accepted = this.callBrowserHook(target.url, {
+                state: 'start',
+                body: parseJsonOrText(takeoverText)
+            });
+            if (accepted === false) {
+                hold.controller.abort();
+            }
+            let attempt = 0;
+            let failures = 0;
+            while (!signal.aborted) {
+                attempt += 1;
+                const startedAt = Date.now();
+                try {
+                    // A FRESH token per attempt: a takeover can outlast the token. A
+                    // token lookup that hangs must not keep a cancelled hold alive.
+                    const attemptToken = await untilAborted(this.options.tokens.getToken(target.url), signal, null);
+                    outcome = signal.aborted
+                        ? { kind: 'error', error: new Error('aborted') }
+                        : await this.sendBuffered(req, targetUrl, body, attemptToken, true, signal, this.options.browserHoldAttemptTimeoutMs ??
+                            exports.BROWSER_HOLD_ATTEMPT_TIMEOUT_MS);
+                }
+                catch (error) {
+                    outcome = {
+                        kind: 'error',
+                        error: error instanceof Error ? error : new Error(String(error))
+                    };
+                }
+                if (signal.aborted) {
+                    if (outcome.kind === 'response')
+                        outcome.response.resume();
+                    break;
+                }
+                let transient = false;
+                if (outcome.kind === 'error') {
+                    transient = true;
+                }
+                else if (isTakeover(outcome.response)) {
+                    outcome.response.resume();
+                    failures = 0;
+                }
+                else if ((outcome.response.statusCode ?? 502) >= 500) {
+                    outcome.response.resume();
+                    transient = true;
+                }
+                else {
+                    endHold('resolved');
+                    pipeUpstreamResponse(outcome.response, res);
+                    return;
+                }
+                if (transient) {
+                    failures += 1;
+                    const reason = outcome.kind === 'error'
+                        ? outcome.error.message
+                        : `HTTP ${outcome.response.statusCode}`;
+                    this.logger.warn(`[McpAuthProxy] Browser hold for "${target.label}": upstream ` +
+                        `failure ${failures}/${exports.BROWSER_HOLD_MAX_FAILURES}: ${reason}`);
+                    if (failures >= exports.BROWSER_HOLD_MAX_FAILURES) {
+                        endHold('failed');
+                        writeJsonRpcError(res, body, `The browser call could not be completed: the gateway failed ` +
+                            `${failures} times in a row while a person controlled the ` +
+                            `browser (${reason}).`);
+                        return;
+                    }
+                }
+                const fast = Date.now() - startedAt < BROWSER_HOLD_FAST_ANSWER_MS;
+                if (transient || fast) {
+                    await delay(this.holdBackoffMs(attempt, failures), signal);
+                }
+            }
+            // Aborted: Pi closed, cancelled, or the proxy is stopping.
+            endHold(clientClosed ? 'client_closed' : 'cancelled');
+            if (!clientClosed) {
+                writeJsonRpcError(res, body, 'The browser call was cancelled while a person controlled the ' +
+                    'browser (the turn ended).');
+            }
+        }
+        finally {
+            endHold(clientClosed ? 'client_closed' : 'cancelled');
+            this.browserHolds.delete(hold);
+            res.off('close', onClose);
+        }
+    }
+    holdBackoffMs(attempt, failures) {
+        if (this.options.browserHoldBackoffMs) {
+            return this.options.browserHoldBackoffMs(attempt, failures);
+        }
+        if (failures > 0) {
+            const base = Math.min(500 * 2 ** (failures - 1), 10_000);
+            return base / 2 + Math.random() * (base / 2);
+        }
+        return 500 + Math.random() * 1500;
+    }
+    callBrowserHook(targetUrl, event) {
+        try {
+            return this.options.onBrowserPause?.(targetUrl, event);
+        }
+        catch (error) {
+            // A hook must never break the request path.
+            this.logger.warn(`[McpAuthProxy] browser pause hook failed: ${String(error)}`);
+            return undefined;
+        }
+    }
+    /**
+     * One upstream request with a buffered body and a fresh token. With
+     * `headersTimeoutMs`, no response headers by then is an error outcome.
+     */
+    sendBuffered(req, targetUrl, body, token, awaitHandback, signal, headersTimeoutMs) {
+        const headers = {};
+        for (const [key, value] of Object.entries(req.headers)) {
+            const lower = key.toLowerCase();
+            if (lower === 'host' ||
+                lower === 'connection' ||
+                lower === 'authorization' ||
+                lower === 'content-length' ||
+                lower === 'transfer-encoding' ||
+                lower === browser_takeover_1.BROWSER_AWAIT_HANDBACK_HEADER) {
+                continue;
+            }
+            headers[key] = value;
+        }
+        if (token !== null)
+            headers['authorization'] = `Bearer ${token}`;
+        headers['host'] = targetUrl.host;
+        if (body.length > 0 || (req.method !== 'GET' && req.method !== 'HEAD')) {
+            headers['content-length'] = String(body.length);
+        }
+        if (awaitHandback)
+            headers[browser_takeover_1.BROWSER_AWAIT_HANDBACK_HEADER] = '1';
+        const send = targetUrl.protocol === 'https:' ? node_https_1.request : node_http_1.request;
+        return new Promise((resolveOutcome) => {
+            let settled = false;
+            const settle = (outcome) => {
+                if (settled) {
+                    if (outcome.kind === 'response')
+                        outcome.response.resume();
+                    return;
+                }
+                settled = true;
+                resolveOutcome(outcome);
+            };
+            if (signal.aborted) {
+                settle({ kind: 'error', error: new Error('aborted') });
+                return;
+            }
+            const pending = {};
+            const upstreamReq = send(targetUrl.toString(), { method: req.method, headers, signal }, (response) => {
+                clearTimeout(pending.timer);
+                settle({ kind: 'response', response });
+            });
+            upstreamReq.on('error', (error) => {
+                clearTimeout(pending.timer);
+                settle({ kind: 'error', error });
+            });
+            if (headersTimeoutMs !== undefined && headersTimeoutMs > 0) {
+                pending.timer = setTimeout(() => {
+                    upstreamReq.destroy(new Error(`no upstream answer within ${headersTimeoutMs} ms`));
+                }, headersTimeoutMs);
+            }
+            upstreamReq.end(body);
+        });
+    }
     /**
      * One notification per TARGET per process — keyed on the target id, not on
      * the human-readable label.

package/dist/runtime/session-runner.d.ts

@@ -79,6 +79,14 @@ export interface SessionRunnerDeps {
      * Optional, so a runner constructed without one behaves exactly as before.
      */
     onApprovalStateChange?(sessionId: string, waiting: boolean): void;
+    /**
+     * Called when the turn starts or stops an intentional BROWSER pause: a
+     * person took control of the chat browser and the agent's browser call is
+     * held by the loopback MCP proxy until they hand back. Separate from
+     * `onApprovalStateChange` so an approval closing cannot relax polling while
+     * the browser is still held (and vice versa). Optional.
+     */
+    onBrowserPauseChange?(sessionId: string, paused: boolean): void;
     /**
      * Read the session's history from the CONTROL PLANE.
      *
@@ -379,12 +387,36 @@ export declare class SessionRunner {
      */
     private approvalWaitMs;
     private approvalWaitStartedAt;
+    /**
+     * Total wall-clock this turn has spent with its browser call HELD because a
+     * person controls the chat browser (takeover). Excluded from the idle guard
+     * and added back onto the hard ceiling exactly like approval time, but it
+     * never opens an approval and the approval timeout never applies: a takeover
+     * lasts as long as the person needs (owner decision), and the turn's abort
+     * and hard ceiling (minus the pause) still end it.
+     */
+    private browserPauseMs;
+    private browserPauseStartedAt;
+    /** When the last browser pause ended; the idle clock restarts from here. */
+    private browserPauseEndedAt;
     constructor(deps: SessionRunnerDeps);
     /**
      * True while a permission prompt is outstanding. Read by the harness to
      * decide how hard to poll the control plane for the answer.
      */
     isAwaitingApproval(): boolean;
+    /** True while a browser call is held because a person controls the browser. */
+    isBrowserPaused(): boolean;
+    /**
+     * Start or stop the browser-takeover pause clock. Called by the harness from
+     * the loopback MCP proxy's hold hook. Returns false when this runner has no
+     * live turn for `sessionId` — the caller should then cancel the hold rather
+     * than keep an agent call parked for a turn that is gone.
+     */
+    setBrowserPaused(sessionId: string, paused: boolean): boolean;
+    private closeBrowserPause;
+    /** Wall-clock spent in the browser pause we are in RIGHT NOW, if any. */
+    private liveBrowserPauseMs;
     /**
      * Run the leased turn to completion, or until `signal` aborts it.
      *