@peakflo/agent-harness 0.2.11-rc.3 → 0.2.11-rc.5

package/dist/runtime/browser-takeover.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * BROWSER TAKEOVER — the harness half of the sandbox-browser wire.
+ *
+ * COPIED, NOT IMPORTED. The source of truth is the core contract
+ * `packages/core/src/services/coding-agents/browser-protocol.ts`. This package
+ * is published to npm on its own and must not depend on `@pf-workflo/core`, so
+ * the few values the harness needs are repeated here.
+ * `__tests__/browser-takeover-contract.test.ts` reads the core source text and
+ * fails if any of them drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROWSER_HARNESS_FEATURE = exports.BROWSER_MCP_TIMEOUT_MS = exports.BROWSER_AWAIT_HANDBACK_HOLD_MS = exports.BROWSER_TAKEOVER_STATUS = exports.BROWSER_AWAIT_HANDBACK_HEADER = exports.BROWSER_TAKEOVER_HEADER = exports.BROWSER_SERVER_NAME = exports.BROWSER_BUILTIN_SERVER_ID = void 0;
+exports.isBrowserTargetUrl = isBrowserTargetUrl;
+exports.sessionIdFromGatewayUrl = sessionIdFromGatewayUrl;
+/** Built-in gateway server id; the gateway URL ends with `/<this id>`. */
+exports.BROWSER_BUILTIN_SERVER_ID = 'pf-browser';
+/** The MCP server name the agent's backend sees. */
+exports.BROWSER_SERVER_NAME = 'browser';
+/** 409 + this header = a person holds the browser; hold the agent's call. */
+exports.BROWSER_TAKEOVER_HEADER = 'x-pf-browser-takeover';
+/** Sent on re-tries during a hold; the gateway then waits up to 20 s. */
+exports.BROWSER_AWAIT_HANDBACK_HEADER = 'x-pf-browser-await-handback';
+exports.BROWSER_TAKEOVER_STATUS = 409;
+/** How long the gateway holds one await-handback request. */
+exports.BROWSER_AWAIT_HANDBACK_HOLD_MS = 20_000;
+/** Pi's MCP request timeout for the `browser` server (24 h). */
+exports.BROWSER_MCP_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+/** Advertised in `capabilities.features`; the API leases `browser` only then. */
+exports.BROWSER_HARNESS_FEATURE = 'browserTakeover';
+/** True for a gateway target URL of the built-in browser server. */
+function isBrowserTargetUrl(targetUrl) {
+    try {
+        const path = new URL(targetUrl).pathname.replace(/\/+$/, '');
+        return path.endsWith(`/${exports.BROWSER_BUILTIN_SERVER_ID}`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The session id in a gateway URL `.../api/mcp/agent/<sessionId>/<serverId>`,
+ * or null when the URL has another shape.
+ */
+function sessionIdFromGatewayUrl(targetUrl) {
+    try {
+        const parts = new URL(targetUrl).pathname.split('/').filter(Boolean);
+        const index = parts.lastIndexOf('agent');
+        if (index < 1 || parts[index - 1] !== 'mcp')
+            return null;
+        const sessionId = parts[index + 1];
+        return sessionId && parts.length > index + 2
+            ? decodeURIComponent(sessionId)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/runtime/knowledge-tools.d.ts

@@ -1,3 +1,4 @@
+import { type PeerUidResolver } from './loopback-peer';
 import type { KnowledgeDownloadResponse, KnowledgeFilesResponse } from '../types';
 /** The name the agent sees the server under. */
 export declare const KNOWLEDGE_SERVER_NAME = "pf-knowledge";
@@ -19,6 +20,13 @@ export interface KnowledgeToolHostOptions {
     fetchImpl?: typeof fetch;
     logger: Pick<Console, 'log' | 'warn' | 'error'>;
     downloadTimeoutMs?: number;
+    /**
+     * Injected in tests. Defaults to the /proc/net/tcp lookup; a chat browser
+     * uid gets 403 on every request of its connection. See `BrowserPeerGuard`.
+     */
+    peerUid?: PeerUidResolver;
+    /** Loopback port; 0 (default) is ephemeral. A sandbox pins it (PF_KNOWLEDGE_PORT). */
+    port?: number;
 }
 export declare class KnowledgeToolHost {
     private readonly options;
@@ -28,6 +36,8 @@ export declare class KnowledgeToolHost {
     private readonly tokenBySession;
     private readonly sessionByToken;
     private readonly turns;
+    /** Chat browsers run as their own uids; they get nothing from this host. */
+    private readonly peerGuard;
     constructor(options: KnowledgeToolHostOptions);
     /** The endpoint a session's agent is configured with. Starts the listener on first use. */
     endpointFor(sessionId: string): Promise<string>;

package/dist/runtime/knowledge-tools.js

@@ -36,6 +36,8 @@ const promises_1 = require("node:fs/promises");
 const node_http_1 = require("node:http");
 const node_path_1 = require("node:path");
 const control_plane_1 = require("../control-plane");
+const loopback_peer_1 = require("./loopback-peer");
+const mcp_auth_proxy_1 = require("./mcp-auth-proxy");
 const space_files_1 = require("./space-files");
 /** The name the agent sees the server under. */
 exports.KNOWLEDGE_SERVER_NAME = 'pf-knowledge';
@@ -166,8 +168,11 @@ class KnowledgeToolHost {
     tokenBySession = new Map();
     sessionByToken = new Map();
     turns = new Map();
+    /** Chat browsers run as their own uids; they get nothing from this host. */
+    peerGuard;
     constructor(options) {
         this.options = options;
+        this.peerGuard = new loopback_peer_1.BrowserPeerGuard(options.peerUid);
     }
     /** The endpoint a session's agent is configured with. Starts the listener on first use. */
     async endpointFor(sessionId) {
@@ -201,6 +206,8 @@ class KnowledgeToolHost {
         if (!this.starting) {
             this.starting = new Promise((resolve, reject) => {
                 const server = (0, node_http_1.createServer)((req, res) => {
+                    if (this.peerGuard.refuse(req.socket, res))
+                        return;
                     void this.handle(req, res).catch((error) => {
                         this.options.logger.error(`[knowledge] request failed: ${error instanceof Error ? error.message : String(error)}`);
                         if (!res.headersSent)
@@ -208,18 +215,17 @@ class KnowledgeToolHost {
                         res.end();
                     });
                 });
-                server.once('error', (error) => {
-                    this.starting = null;
-                    reject(error);
-                });
+                this.peerGuard.attach(server);
                 // Loopback only. Nothing outside this host can open this socket.
-                server.listen(0, '127.0.0.1', () => {
-                    const address = server.address();
-                    this.port = typeof address === 'object' && address ? address.port : 0;
+                (0, mcp_auth_proxy_1.listenLoopback)(server, this.options.port ?? 0, this.options.logger, 'knowledge').then((port) => {
+                    this.port = port;
                     this.server = server;
                     // Never keeps the process alive on its own: a one-shot run must still exit.
                     server.unref();
                     resolve();
+                }, (error) => {
+                    this.starting = null;
+                    reject(error);
                 });
             });
         }

package/dist/runtime/loopback-peer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Who is on the other end of a loopback TCP connection?
+ *
+ * Inside the sandbox every chat's Chromium runs as its own Unix user, and the
+ * uids are drawn from this range — keep it in step with UID_MIN / UID_MAX in
+ * packages/agentSandbox/browser-broker/os-users.mjs. Chromium runs with
+ * --no-sandbox and uses the sandbox network directly (no egress proxy, no
+ * firewall), so a page — or a COMPROMISED renderer — can open a socket to
+ * 127.0.0.1. The harness loopback services therefore refuse browser uids: a
+ * loopback server that should say nothing to a browser asks `peerUid()` and
+ * refuses uids in this range.
+ */
+export declare const BROWSER_UID_MIN = 20000;
+export declare const BROWSER_UID_MAX = 29999;
+export declare function isBrowserUid(uid: number | null): boolean;
+/** The parts of a `net.Socket` the lookup needs (server side of the connection). */
+export interface LoopbackSocket {
+    remoteAddress?: string;
+    remotePort?: number;
+    localPort?: number;
+}
+export interface PeerUidOptions {
+    /** Defaults to `process.platform`; anything but 'linux' answers null. */
+    platform?: NodeJS.Platform;
+    /** Defaults to a sync read; injected by tests with fake /proc content. */
+    readFile?: (path: string) => string;
+    /** Byte order of the /proc address words. Defaults to `os.endianness()`. */
+    endianness?: 'LE' | 'BE';
+}
+export interface ProcNetTcpEntry {
+    localAddress: string;
+    localPort: number;
+    remoteAddress: string;
+    remotePort: number;
+    uid: number;
+}
+/**
+ * One spelling per address: dotted IPv4 for IPv4 and IPv4-mapped IPv6
+ * ('::ffff:127.0.0.1' -> '127.0.0.1'), 32 lowercase hex digits otherwise.
+ * Null for anything unparseable.
+ */
+export declare function canonicalAddress(address: string): string | null;
+/**
+ * Parse /proc/net/tcp or /proc/net/tcp6. Addresses come back canonical (see
+ * `canonicalAddress`), so an IPv4-mapped IPv6 row compares equal to its IPv4
+ * form. Malformed rows are skipped.
+ */
+export declare function parseProcNetTcp(text: string, ipv6: boolean, order?: 'LE' | 'BE'): ProcNetTcpEntry[];
+/**
+ * The owner uid of the CLIENT socket of an accepted loopback connection, or
+ * null when it cannot be told (not Linux, /proc unreadable, no matching row).
+ *
+ * Both ends of a loopback connection live in the same network namespace, so
+ * /proc/net/tcp{,6} lists the client's socket too: the row whose LOCAL
+ * address:port is our peer's address:port and whose REMOTE port is our own
+ * port. Its `uid` column is the uid that created that socket. The server's own
+ * accepted socket is the mirror row (local port = our port) and never matches.
+ *
+ * Synchronous and cheap enough for low-rate endpoints: two small file reads.
+ */
+export declare function peerUid(socket: LoopbackSocket, options?: PeerUidOptions): number | null;
+/** Resolves a connection's peer uid; null when unknown. Injected by tests. */
+export type PeerUidResolver = (socket: LoopbackSocket) => number | null;
+/** The body every guarded server sends a browser peer: nothing else. */
+export declare const FORBIDDEN_BODY: string;
+/** The minimum a `BrowserPeerGuard` needs from an http/net server. */
+interface ConnectionEmitter {
+    on(event: 'connection', listener: (socket: LoopbackSocket) => void): unknown;
+}
+/** The minimum a `BrowserPeerGuard` needs from an http response. */
+interface ForbiddableResponse {
+    writeHead(status: number, headers: Record<string, string>): unknown;
+    end(body: string): unknown;
+}
+/**
+ * Per-CONNECTION browser-uid guard for a busier loopback server (the MCP auth
+ * proxy, the knowledge host): the /proc lookup runs once when a connection is
+ * accepted and is cached on that socket, so keep-alive and streaming traffic
+ * pays nothing per request. A confirmed browser uid gets a bare 403 on every
+ * request of the connection; an unknown uid (non-Linux, /proc unreadable, a
+ * resolver that throws) is let through, for the same reason as the health
+ * check: the legitimate callers run as pfharness or root, and failing closed
+ * would turn a /proc hiccup into broken MCP tools.
+ */
+export declare class BrowserPeerGuard {
+    private readonly resolve;
+    private readonly uids;
+    constructor(resolve?: PeerUidResolver);
+    /** Look up every new connection's peer uid as it is accepted. */
+    attach(server: ConnectionEmitter): void;
+    /** True for a CONFIRMED browser peer. Looks up lazily if `attach` missed it. */
+    isBrowser(socket: LoopbackSocket): boolean;
+    /** Answer a browser peer with 403 and return true; otherwise return false. */
+    refuse(socket: LoopbackSocket, res: ForbiddableResponse): boolean;
+    private lookup;
+}
+export {};

package/dist/runtime/loopback-peer.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserPeerGuard = exports.FORBIDDEN_BODY = exports.BROWSER_UID_MAX = exports.BROWSER_UID_MIN = void 0;
+exports.isBrowserUid = isBrowserUid;
+exports.canonicalAddress = canonicalAddress;
+exports.parseProcNetTcp = parseProcNetTcp;
+exports.peerUid = peerUid;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+/**
+ * Who is on the other end of a loopback TCP connection?
+ *
+ * Inside the sandbox every chat's Chromium runs as its own Unix user, and the
+ * uids are drawn from this range — keep it in step with UID_MIN / UID_MAX in
+ * packages/agentSandbox/browser-broker/os-users.mjs. Chromium runs with
+ * --no-sandbox and uses the sandbox network directly (no egress proxy, no
+ * firewall), so a page — or a COMPROMISED renderer — can open a socket to
+ * 127.0.0.1. The harness loopback services therefore refuse browser uids: a
+ * loopback server that should say nothing to a browser asks `peerUid()` and
+ * refuses uids in this range.
+ */
+exports.BROWSER_UID_MIN = 20000;
+exports.BROWSER_UID_MAX = 29999;
+function isBrowserUid(uid) {
+    return uid !== null && uid >= exports.BROWSER_UID_MIN && uid <= exports.BROWSER_UID_MAX;
+}
+const PROC_FILES = [
+    { path: '/proc/net/tcp', ipv6: false },
+    { path: '/proc/net/tcp6', ipv6: true }
+];
+function parseIpv4(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4) {
+        return null;
+    }
+    const bytes = parts.map((p) => (/^\d{1,3}$/.test(p) ? Number(p) : NaN));
+    return bytes.every((b) => b >= 0 && b <= 255) ? bytes : null;
+}
+function parseIpv6(address) {
+    let text = address.split('%')[0]; // drop a zone id
+    const groups = [];
+    // A trailing dotted quad ('::ffff:1.2.3.4') is two 16-bit groups.
+    const lastColon = text.lastIndexOf(':');
+    const tail = parseIpv4(text.slice(lastColon + 1));
+    if (tail) {
+        text = `${text.slice(0, lastColon + 1)}${((tail[0] << 8) | tail[1]).toString(16)}:${((tail[2] << 8) | tail[3]).toString(16)}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2) {
+        return null;
+    }
+    const parse = (part) => {
+        if (part === '') {
+            return [];
+        }
+        const out = [];
+        for (const g of part.split(':')) {
+            if (!/^[0-9A-Fa-f]{1,4}$/.test(g)) {
+                return null;
+            }
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    const head = parse(halves[0]);
+    const rest = halves.length === 2 ? parse(halves[1]) : [];
+    if (!head || !rest) {
+        return null;
+    }
+    const missing = 8 - head.length - rest.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0) {
+        return null;
+    }
+    groups.push(...head, ...new Array(missing).fill(0), ...rest);
+    const bytes = Buffer.alloc(16);
+    groups.forEach((g, i) => bytes.writeUInt16BE(g, i * 2));
+    return bytes;
+}
+function canonicalBytes(bytes) {
+    if (bytes.length === 4) {
+        return Array.from(bytes).join('.');
+    }
+    const mapped = bytes.subarray(0, 10).every((b) => b === 0) &&
+        bytes[10] === 0xff &&
+        bytes[11] === 0xff;
+    return mapped
+        ? Array.from(bytes.subarray(12)).join('.')
+        : bytes.toString('hex');
+}
+/**
+ * One spelling per address: dotted IPv4 for IPv4 and IPv4-mapped IPv6
+ * ('::ffff:127.0.0.1' -> '127.0.0.1'), 32 lowercase hex digits otherwise.
+ * Null for anything unparseable.
+ */
+function canonicalAddress(address) {
+    const v4 = parseIpv4(address);
+    if (v4) {
+        return v4.join('.');
+    }
+    const v6 = parseIpv6(address);
+    return v6 ? canonicalBytes(v6) : null;
+}
+/** "0100007F:1E61" -> { address: '127.0.0.1', port: 7777 } on little-endian. */
+function parseProcEndpoint(value, ipv6, order) {
+    const [hex, portHex] = value.split(':');
+    const width = ipv6 ? 32 : 8;
+    if (!hex ||
+        !portHex ||
+        hex.length !== width ||
+        !/^[0-9A-Fa-f]+$/.test(hex) ||
+        !/^[0-9A-Fa-f]{4}$/.test(portHex)) {
+        return null;
+    }
+    // The kernel prints each 32-bit word of the address in host byte order.
+    const bytes = Buffer.from(hex, 'hex');
+    if (order === 'LE') {
+        for (let i = 0; i < bytes.length; i += 4) {
+            bytes.subarray(i, i + 4).reverse();
+        }
+    }
+    return { address: canonicalBytes(bytes), port: parseInt(portHex, 16) };
+}
+/**
+ * Parse /proc/net/tcp or /proc/net/tcp6. Addresses come back canonical (see
+ * `canonicalAddress`), so an IPv4-mapped IPv6 row compares equal to its IPv4
+ * form. Malformed rows are skipped.
+ */
+function parseProcNetTcp(text, ipv6, order = (0, node_os_1.endianness)()) {
+    const entries = [];
+    for (const line of text.split('\n').slice(1)) {
+        // sl local_address rem_address st tx:rx tr:when retrnsmt uid ...
+        const cols = line.trim().split(/\s+/);
+        if (cols.length < 8) {
+            continue;
+        }
+        const local = parseProcEndpoint(cols[1], ipv6, order);
+        const remote = parseProcEndpoint(cols[2], ipv6, order);
+        const uid = Number(cols[7]);
+        if (!local || !remote || !Number.isInteger(uid)) {
+            continue;
+        }
+        entries.push({
+            localAddress: local.address,
+            localPort: local.port,
+            remoteAddress: remote.address,
+            remotePort: remote.port,
+            uid
+        });
+    }
+    return entries;
+}
+/**
+ * The owner uid of the CLIENT socket of an accepted loopback connection, or
+ * null when it cannot be told (not Linux, /proc unreadable, no matching row).
+ *
+ * Both ends of a loopback connection live in the same network namespace, so
+ * /proc/net/tcp{,6} lists the client's socket too: the row whose LOCAL
+ * address:port is our peer's address:port and whose REMOTE port is our own
+ * port. Its `uid` column is the uid that created that socket. The server's own
+ * accepted socket is the mirror row (local port = our port) and never matches.
+ *
+ * Synchronous and cheap enough for low-rate endpoints: two small file reads.
+ */
+function peerUid(socket, options = {}) {
+    if ((options.platform ?? process.platform) !== 'linux') {
+        return null;
+    }
+    const { remoteAddress, remotePort, localPort } = socket;
+    if (!remoteAddress || !remotePort || !localPort) {
+        return null;
+    }
+    const peer = canonicalAddress(remoteAddress);
+    if (!peer) {
+        return null;
+    }
+    const read = options.readFile ?? ((path) => (0, node_fs_1.readFileSync)(path, 'utf8'));
+    const order = options.endianness ?? (0, node_os_1.endianness)();
+    for (const file of PROC_FILES) {
+        let text;
+        try {
+            text = read(file.path);
+        }
+        catch {
+            continue; // e.g. no IPv6 in the kernel: the other file may still match
+        }
+        for (const entry of parseProcNetTcp(text, file.ipv6, order)) {
+            if (entry.localPort === remotePort &&
+                entry.remotePort === localPort &&
+                entry.localAddress === peer) {
+                return entry.uid;
+            }
+        }
+    }
+    return null;
+}
+/** The body every guarded server sends a browser peer: nothing else. */
+exports.FORBIDDEN_BODY = JSON.stringify({ error: 'forbidden' });
+/**
+ * Per-CONNECTION browser-uid guard for a busier loopback server (the MCP auth
+ * proxy, the knowledge host): the /proc lookup runs once when a connection is
+ * accepted and is cached on that socket, so keep-alive and streaming traffic
+ * pays nothing per request. A confirmed browser uid gets a bare 403 on every
+ * request of the connection; an unknown uid (non-Linux, /proc unreadable, a
+ * resolver that throws) is let through, for the same reason as the health
+ * check: the legitimate callers run as pfharness or root, and failing closed
+ * would turn a /proc hiccup into broken MCP tools.
+ */
+class BrowserPeerGuard {
+    resolve;
+    uids = new WeakMap();
+    constructor(resolve = (socket) => peerUid(socket)) {
+        this.resolve = resolve;
+    }
+    /** Look up every new connection's peer uid as it is accepted. */
+    attach(server) {
+        server.on('connection', (socket) => {
+            this.uids.set(socket, this.lookup(socket));
+        });
+    }
+    /** True for a CONFIRMED browser peer. Looks up lazily if `attach` missed it. */
+    isBrowser(socket) {
+        if (!this.uids.has(socket)) {
+            this.uids.set(socket, this.lookup(socket));
+        }
+        return isBrowserUid(this.uids.get(socket) ?? null);
+    }
+    /** Answer a browser peer with 403 and return true; otherwise return false. */
+    refuse(socket, res) {
+        if (!this.isBrowser(socket)) {
+            return false;
+        }
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(exports.FORBIDDEN_BODY);
+        return true;
+    }
+    lookup(socket) {
+        try {
+            return this.resolve(socket);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.BrowserPeerGuard = BrowserPeerGuard;

package/dist/runtime/mcp-auth-proxy.d.ts

@@ -35,13 +35,78 @@
  * from the network and does not weaken it. Binding 0.0.0.0 here WOULD, and the
  * test suite asserts the bind address.
  */
+import { type Server as HttpServer } from 'node:http';
 import { Notifier, TokenInjector } from '../ports';
+import { type PeerUidResolver } from './loopback-peer';
+/** Largest agent request body the browser hold buffers to re-send. */
+export declare const BROWSER_HOLD_MAX_BODY_BYTES: number;
+/** Consecutive upstream failures (network/5xx) a hold tolerates. */
+export declare const BROWSER_HOLD_MAX_FAILURES = 10;
+/**
+ * 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.
+ */
+export declare const BROWSER_HOLD_ATTEMPT_TIMEOUT_MS = 180000;
+export type BrowserPauseEndReason = 
+/** The gateway answered something other than a takeover 409. */
+'resolved'
+/** Pi closed the request. */
+ | 'client_closed'
+/** `cancelBrowserHolds`, `stop()`, or the start hook refused the hold. */
+ | 'cancelled'
+/** Too many consecutive upstream failures; Pi got a JSON-RPC error. */
+ | 'failed';
+export type BrowserPauseEvent = 
+/** `body` is the gateway's `BrowserTakeoverBody` (parsed JSON, or text). */
+{
+    state: 'start';
+    body: unknown;
+} | {
+    state: 'end';
+    reason: BrowserPauseEndReason;
+};
+/**
+ * Called once when a browser call starts being held and once when the hold
+ * ends. Returning `false` from the `start` event refuses the hold (no live
+ * turn for that session): the call is answered with a JSON-RPC error instead.
+ */
+export type BrowserPauseHook = (targetUrl: string, event: BrowserPauseEvent) => boolean | void;
 export interface McpAuthProxyOptions {
     tokens: TokenInjector;
     notifier?: Notifier;
     /** Injected in tests. Defaults to console. */
     logger?: Pick<Console, 'warn' | 'error' | 'log'>;
+    /** Browser takeover hold start/end. See `handleBrowserRequest`. */
+    onBrowserPause?: BrowserPauseHook;
+    /** Injected in tests: delay between hold attempts. Defaults to jittered. */
+    browserHoldBackoffMs?: (attempt: number, failures: number) => number;
+    /** Injected in tests. Defaults to `BROWSER_HOLD_ATTEMPT_TIMEOUT_MS`. */
+    browserHoldAttemptTimeoutMs?: number;
+    /**
+     * Injected in tests. Defaults to the /proc/net/tcp lookup; a chat browser
+     * uid gets 403 on every request of its connection. See `BrowserPeerGuard`.
+     */
+    peerUid?: PeerUidResolver;
+    /**
+     * Loopback port to listen on. 0 (the default, desktop) is ephemeral. A
+     * sandbox pins it (PF_MCP_PROXY_PORT) so the chat browser's Landlock rule
+     * can deny it by number. See `listenLoopback`.
+     */
+    port?: number;
 }
+/**
+ * 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.
+ */
+export declare function listenLoopback(server: HttpServer, port: number, logger: Pick<Console, 'warn'>, label: string): Promise<number>;
+/** A fixed loopback port from the environment, or 0 (ephemeral) when unset or invalid. */
+export declare function loopbackPortFromEnv(value: string | undefined): number;
 export declare class McpAuthProxy {
     private readonly options;
     private server;
@@ -52,6 +117,10 @@ export declare class McpAuthProxy {
     /** One notification per integration per process, not one per failed call. */
     private readonly notifiedFailures;
     private readonly logger;
+    /** Browser calls held during a takeover. Cancelled on `stop()`. */
+    private readonly browserHolds;
+    /** Chat browsers run as their own uids; they get nothing from this proxy. */
+    private readonly peerGuard;
     constructor(options: McpAuthProxyOptions);
     getPort(): number | null;
     /**
@@ -67,8 +136,40 @@ export declare class McpAuthProxy {
     registerTarget(targetUrl: string, label?: string): string | null;
     unregisterTarget(proxyUrl: string): void;
     start(): Promise<number>;
+    /**
+     * 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: string): number;
+    /** Number of browser calls currently held. For tests and diagnostics. */
+    activeBrowserHolds(): number;
     stop(): Promise<void>;
     private handleRequest;
+    /**
+     * 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`.
+     */
+    private handleBrowserRequest;
+    private holdBackoffMs;
+    private callBrowserHook;
+    /**
+     * One upstream request with a buffered body and a fresh token. With
+     * `headersTimeoutMs`, no response headers by then is an error outcome.
+     */
+    private sendBuffered;
     /**
      * One notification per TARGET per process — keyed on the target id, not on
      * the human-readable label.