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

package/dist/adapters/pi-adapter.js

@@ -22,6 +22,7 @@ const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const model_gateway_1 = require("./model-gateway");
 const vendor_environment_1 = require("./vendor-environment");
+const browser_takeover_1 = require("../runtime/browser-takeover");
 const cold_start_steps_1 = require("../runtime/cold-start-steps");
 const dev_server_guard_1 = require("../runtime/dev-server-guard");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
@@ -167,7 +168,13 @@ function buildPiMcpConfigDocument(servers, onRename) {
                 // The managed integrations gateway can wait for a cold pfMCP
                 // instance. Its own upstream deadline is 270 seconds, so Pi must
                 // wait long enough to receive the gateway's result or clear error.
-                ...(name === 'integrations' ? { requestTimeoutMs: 300_000 } : {})
+                ...(name === 'integrations' ? { requestTimeoutMs: 300_000 } : {}),
+                // A browser call is HELD by the loopback proxy while a person
+                // controls the chat browser, for as long as they need. Pi's
+                // default 60 s timeout would fail the call mid-takeover.
+                ...(name === browser_takeover_1.BROWSER_SERVER_NAME
+                    ? { requestTimeoutMs: browser_takeover_1.BROWSER_MCP_TIMEOUT_MS }
+                    : {})
             }
         ];
     }));

package/dist/capabilities.d.ts

@@ -30,8 +30,11 @@ import { RunnerCapabilities } from './types';
  *
  * - `spaceFiles`: syncs `space-files/` (read-only) and serves
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
+ * - `browserTakeover`: holds a `browser` MCP call while a person controls the
+ *   chat browser (409 + `x-pf-browser-takeover`) and gives Pi a 24 h timeout
+ *   for that server. The API leases the `browser` server only with this.
  */
-export declare const HARNESS_FEATURES: readonly ["spaceFiles"];
+export declare const HARNESS_FEATURES: readonly ["spaceFiles", "browserTakeover"];
 /** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
 export declare function supportsPiSteering(version: string | null): boolean;
 export interface ProbeResult {

package/dist/capabilities.js

@@ -33,6 +33,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const browser_takeover_1 = require("./runtime/browser-takeover");
 const version_1 = require("./version");
 const PROBE_TIMEOUT_MS = 10_000;
 /**
@@ -41,8 +42,14 @@ const PROBE_TIMEOUT_MS = 10_000;
  *
  * - `spaceFiles`: syncs `space-files/` (read-only) and serves
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
+ * - `browserTakeover`: holds a `browser` MCP call while a person controls the
+ *   chat browser (409 + `x-pf-browser-takeover`) and gives Pi a 24 h timeout
+ *   for that server. The API leases the `browser` server only with this.
  */
-exports.HARNESS_FEATURES = ['spaceFiles'];
+exports.HARNESS_FEATURES = [
+    'spaceFiles',
+    browser_takeover_1.BROWSER_HARNESS_FEATURE
+];
 /** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
 function supportsPiSteering(version) {
     if (!version)

package/dist/github-proxy.d.ts

@@ -1,7 +1,8 @@
-import { type Server } from 'node:http';
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { type RequestOptions as HttpsRequestOptions } from 'node:https';
 import { type Socket } from 'node:net';
 import type { GitHubProxyCertificates } from './github-proxy-certificates';
+import { type PeerUidResolver } from './runtime/loopback-peer';
 import type { LeasedGitHubCredential } from './types';
 export interface GitHubProxySession {
     sessionId: string;
@@ -15,6 +16,12 @@ export interface GitHubProxyOptions {
     logger?: Pick<Console, 'warn'>;
     connectDirect?: (hostname: string, port: number) => Socket;
     resolveUpstream?: (hostname: string) => Partial<HttpsRequestOptions>;
+    /**
+     * Injected in tests. Defaults to the /proc/net/tcp lookup. A chat browser
+     * uid gets its CONNECT socket closed at once, and a plain HTTP request 403
+     * (see `refuseBrowserPeer`). Unknown uids are unchanged (fail open).
+     */
+    peerUid?: PeerUidResolver;
 }
 export interface ReceivePackCommand {
     oldOid: string;
@@ -27,7 +34,19 @@ export declare class GitHubTlsProxy {
     private readonly listener;
     private readonly options;
     private readonly tunneled;
+    /**
+     * Chat browsers run as their own uids (20000-29999) with --no-sandbox; a
+     * compromised renderer must not get a GitHub tunnel carrying a session's
+     * credential. Looked up once per accepted connection.
+     */
+    private readonly peerGuard;
     constructor(listener: Server, options: GitHubProxyOptions);
+    /**
+     * For the listener's plain-HTTP handler (which the owner of the listener
+     * installs): answers a browser peer 403 `{"error":"forbidden"}` and returns
+     * true; otherwise returns false and the caller answers as before.
+     */
+    refuseBrowserPeer(request: IncomingMessage, response: ServerResponse): boolean;
     private refused;
     private logRefusal;
     private connect;

package/dist/github-proxy.js

@@ -9,6 +9,7 @@ const node_https_1 = require("node:https");
 const node_net_1 = require("node:net");
 const node_tls_1 = require("node:tls");
 const child_stream_guards_1 = require("./runtime/child-stream-guards");
+const loopback_peer_1 = require("./runtime/loopback-peer");
 const INTERCEPTED_HOSTS = new Set(['github.com', 'api.github.com']);
 const PASS_THROUGH_HOSTS = new Set([
     'objects.githubusercontent.com',
@@ -263,9 +264,17 @@ class GitHubTlsProxy {
     tunneled = (0, node_http_1.createServer)((request, response) => {
         void this.handle(request, response);
     });
+    /**
+     * Chat browsers run as their own uids (20000-29999) with --no-sandbox; a
+     * compromised renderer must not get a GitHub tunnel carrying a session's
+     * credential. Looked up once per accepted connection.
+     */
+    peerGuard;
     constructor(listener, options) {
         this.listener = listener;
         this.options = options;
+        this.peerGuard = new loopback_peer_1.BrowserPeerGuard(options.peerUid);
+        this.peerGuard.attach(listener);
         listener.on('connect', (request, socket, head) => {
             // A refused CONNECT commonly makes the client reset the TCP connection
             // after it receives our 403. Without an error listener Node promotes that
@@ -273,9 +282,22 @@ class GitHubTlsProxy {
             // harness. Install the guard before the first await/write in connect(),
             // including for targets outside the GitHub allowlist.
             (0, child_stream_guards_1.guardStream)(socket, 'GitHubProxy/connect');
+            if (this.peerGuard.isBrowser(socket)) {
+                // No response at all: nothing about the proxy is told to a browser.
+                socket.destroy();
+                return;
+            }
             void this.connect(request, socket, head);
         });
     }
+    /**
+     * For the listener's plain-HTTP handler (which the owner of the listener
+     * installs): answers a browser peer 403 `{"error":"forbidden"}` and returns
+     * true; otherwise returns false and the caller answers as before.
+     */
+    refuseBrowserPeer(request, response) {
+        return this.peerGuard.refuse(request.socket, response);
+    }
     refused(sessionId, kind, path, response, reason) {
         this.logRefusal(sessionId, kind, path);
         reply(response, 403, reason);

package/dist/github-workspace.d.ts

@@ -1,5 +1,6 @@
 import { type RequestListener, type Server } from 'node:http';
 import type { WorkspaceProvider, WorkspaceRequest } from './ports';
+import type { PeerUidResolver } from './runtime/loopback-peer';
 import type { LeasedGitHubCredential } from './types';
 export interface GitHubWorkspaceOptions {
     root: string;
@@ -7,6 +8,8 @@ export interface GitHubWorkspaceOptions {
     createServer?: (handler: RequestListener) => Server;
     logger?: Pick<Console, 'warn'>;
     directUrls?: string[];
+    /** Injected in tests: the proxy's peer-uid lookup. See `GitHubTlsProxy`. */
+    peerUid?: PeerUidResolver;
 }
 /** Bare clone plus one worktree per session, adapted from 20x. */
 export declare class GitHubWorkspaceProvider implements WorkspaceProvider {

package/dist/github-workspace.js

@@ -248,14 +248,19 @@ class GitHubWorkspaceProvider {
         }
     }
     async startServer() {
-        const server = (this.options.createServer ?? node_http_1.createServer)((_request, response) => {
+        // Assigned below, before the server listens, so every request sees it.
+        let tlsProxy = null;
+        const server = (this.options.createServer ?? node_http_1.createServer)((request, response) => {
+            if (tlsProxy?.refuseBrowserPeer(request, response))
+                return;
             response.writeHead(400, { 'content-type': 'text/plain' });
             response.end('This endpoint is an HTTPS CONNECT proxy.\n');
         });
         const certificates = await (0, github_proxy_certificates_1.createGitHubProxyCertificates)(this.options.root);
         this.caCertificatePath = certificates.caCertificatePath;
-        new github_proxy_1.GitHubTlsProxy(server, {
+        tlsProxy = new github_proxy_1.GitHubTlsProxy(server, {
             certificates,
+            peerUid: this.options.peerUid,
             logger: this.options.logger,
             isDirectHostAllowed: (hostname) => this.directHosts.has(hostname),
             findSession: (sentinel) => [...this.sessions.values()].find((entry) => entry.sentinel === sentinel)

package/dist/harness.d.ts

@@ -164,6 +164,11 @@ export declare class Harness {
     private readonly health;
     private readonly proxy;
     /** One loopback host for every session this process runs (P9 knowledge tools). */
+    /**
+     * PF_KNOWLEDGE_PORT / PF_MCP_PROXY_PORT: fixed loopback ports, set by
+     * pf-bootstrap in a sandbox so the chat browser's Landlock rule can deny
+     * them by number. Unset (desktop) = ephemeral, as before.
+     */
     private readonly knowledgeHost;
     private readonly store;
     /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
@@ -269,6 +274,14 @@ export declare class Harness {
     /** Same idea, for the INDEPENDENT sandbox-tools pin (gh, node deps, ...). */
     private pendingSandboxToolsVersion;
     constructor(options: HarnessOptions, deps?: HarnessDeps);
+    /**
+     * BROWSER TAKEOVER, proxy → runner. The loopback proxy is holding (or has
+     * stopped holding) a `browser` call because a person controls the chat
+     * browser. The gateway URL names the session; its runner counts the hold as
+     * an intentional pause. No live runner → refuse, so the call is not parked
+     * for a turn that is gone.
+     */
+    private onBrowserPause;
     /** The actual bound health port. Used by tests to prove the socket closed. */
     getHealthPort(): number | null;
     snapshot(): HealthReport;

package/dist/harness.js

@@ -17,6 +17,7 @@ const harness_discovery_1 = require("./harness-discovery");
 const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
+const browser_takeover_1 = require("./runtime/browser-takeover");
 const knowledge_tools_1 = require("./runtime/knowledge-tools");
 const lease_renewal_1 = require("./runtime/lease-renewal");
 const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
@@ -172,7 +173,15 @@ class Harness {
     health;
     proxy;
     /** One loopback host for every session this process runs (P9 knowledge tools). */
-    knowledgeHost = new knowledge_tools_1.KnowledgeToolHost({ logger: console });
+    /**
+     * PF_KNOWLEDGE_PORT / PF_MCP_PROXY_PORT: fixed loopback ports, set by
+     * pf-bootstrap in a sandbox so the chat browser's Landlock rule can deny
+     * them by number. Unset (desktop) = ephemeral, as before.
+     */
+    knowledgeHost = new knowledge_tools_1.KnowledgeToolHost({
+        logger: console,
+        port: (0, mcp_auth_proxy_1.loopbackPortFromEnv)(process.env.PF_KNOWLEDGE_PORT)
+    });
     store;
     /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
     conversation;
@@ -324,9 +333,31 @@ class Harness {
             deps.credentialStore ??
                 (0, credential_store_1.createCredentialStore)(options.runtime, options.workspaceRoot);
         this.proxy = new mcp_auth_proxy_1.McpAuthProxy({
+            port: (0, mcp_auth_proxy_1.loopbackPortFromEnv)(process.env.PF_MCP_PROXY_PORT),
             tokens: this.tokens,
-            notifier: this.notifier
+            notifier: this.notifier,
+            onBrowserPause: (targetUrl, event) => this.onBrowserPause(targetUrl, event)
+        });
+    }
+    /**
+     * BROWSER TAKEOVER, proxy → runner. The loopback proxy is holding (or has
+     * stopped holding) a `browser` call because a person controls the chat
+     * browser. The gateway URL names the session; its runner counts the hold as
+     * an intentional pause. No live runner → refuse, so the call is not parked
+     * for a turn that is gone.
+     */
+    onBrowserPause(targetUrl, event) {
+        const sessionId = (0, browser_takeover_1.sessionIdFromGatewayUrl)(targetUrl);
+        const runner = sessionId ? this.runners.get(sessionId) : undefined;
+        if (!sessionId || !runner)
+            return event.state !== 'start';
+        const accepted = runner.setBrowserPaused(sessionId, event.state === 'start');
+        log('Browser takeover hold', {
+            sessionId,
+            state: event.state,
+            ...(event.state === 'end' ? { reason: event.reason } : { accepted })
         });
+        return accepted;
     }
     /** The actual bound health port. Used by tests to prove the socket closed. */
     getHealthPort() {
@@ -1794,6 +1825,9 @@ class Harness {
          * passed for the wrong reason.
          */
         const modelGateway = new model_gateway_1.SessionModelGateway();
+        // Two independent reasons to renew urgently; neither may clear the other.
+        let approvalWaiting = false;
+        let browserPaused = false;
         const runner = new session_runner_1.SessionRunner({
             mcpCheckState: this.mcpCheckState,
             getAdapter: (backend) => {
@@ -1841,6 +1875,13 @@ class Harness {
              * hard to poll the control plane for the answer. Nothing else in the
              * process knows a permission is outstanding.
              */
+            onBrowserPauseChange: (id, paused) => {
+                // Same tight renewal cadence as an approval, so a handback command
+                // (or abort) rides back quickly. Lease renewal keeps running either way.
+                browserPaused = paused;
+                renewal.setUrgent(paused || approvalWaiting);
+                log('Browser pause changed', { sessionId: id, paused });
+            },
             onApprovalStateChange: (id, waiting) => {
                 /*
                  * NO SET IS KEPT HERE. An earlier version also maintained an
@@ -1852,7 +1893,8 @@ class Harness {
                 // Event-driven, not polled: the cadence changes at the instant the
                 // prompt opens, so the first tight renewal happens ~2s later rather
                 // than up to a minute later.
-                renewal.setUrgent(waiting);
+                approvalWaiting = waiting;
+                renewal.setUrgent(waiting || browserPaused);
                 log('Approval state changed', { sessionId: id, waiting });
             },
             ingest: (id, parts, turn, final, modelMessages) => this.client
@@ -1928,6 +1970,11 @@ class Harness {
             }
             // Revoke ONLY this session's tokens. A process-wide revoke here blanked
             // the credential of every concurrent turn still running.
+            // A browser call held for a person cannot outlive its turn.
+            for (const url of mcpTargetUrls) {
+                if ((0, browser_takeover_1.isBrowserTargetUrl)(url))
+                    this.proxy.cancelBrowserHolds(url);
+            }
             this.tokens.revokeTargets(mcpTargetUrls);
             modelGateway.revoke();
             githubWorkspace.clearCredential?.(sessionId);

package/dist/health.d.ts

@@ -1,3 +1,4 @@
+import type { Socket } from 'node:net';
 import { HealthReport } from './types';
 /**
  * Health check for pf-bootstrap and for the Daytona liveness probe.
@@ -6,6 +7,17 @@ import { HealthReport } from './types';
  * from outside the sandbox, and session users get no useful secret from it —
  * the report deliberately carries no token.
  *
+ * BROWSER USERS GET NOTHING. A chat's Chromium runs as its own uid (20000-
+ * 29999) with --no-sandbox and uses the sandbox network directly (no egress
+ * proxy, no firewall), so a page or a compromised renderer could connect here
+ * and learn the tenant id, runner id, versions and heartbeat errors. On Linux each
+ * request's peer uid is looked up in /proc/net/tcp{,6}; a browser uid gets a
+ * bare 403. The guard FAILS OPEN when the uid cannot be determined (non-Linux,
+ * /proc unreadable, no matching row): the probe and pf-bootstrap run as root
+ * or pfharness, the report holds no secret, and failing closed would turn a
+ * /proc hiccup into a dead liveness probe. Only a CONFIRMED browser uid is
+ * refused.
+ *
  * STOP MUST ACTUALLY CLOSE, and this is the reason `boundPort` and the socket
  * tracking below exist. `server.close()` stops ACCEPTING connections but leaves
  * any keep-alive connection open, and an open connection keeps the Node event
@@ -18,6 +30,8 @@ import { HealthReport } from './types';
 export declare class HealthServer {
     private readonly port;
     private readonly report;
+    /** Injected by tests; defaults to the /proc/net/tcp lookup. */
+    private readonly lookupPeerUid;
     private server;
     /**
      * The port the server actually bound to, RETAINED after `stop()`.
@@ -29,7 +43,9 @@ export declare class HealthServer {
     private bound;
     /** Live connections, tracked so `stop()` can destroy them. */
     private readonly sockets;
-    constructor(port: number, report: () => HealthReport);
+    constructor(port: number, report: () => HealthReport, 
+    /** Injected by tests; defaults to the /proc/net/tcp lookup. */
+    lookupPeerUid?: (socket: Socket) => number | null);
     /** The actual bound port, or null before `start()`. Survives `stop()`. */
     get boundPort(): number | null;
     start(): Promise<void>;
@@ -41,5 +57,7 @@ export declare class HealthServer {
      * process exits, without weakening enrolment or running two ready harnesses.
      */
     private listenOnce;
+    /** A lookup that throws counts as "unknown" — fail open, see the class doc. */
+    private safePeerUid;
     stop(): Promise<void>;
 }

package/dist/health.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HealthServer = void 0;
 const node_http_1 = require("node:http");
+const loopback_peer_1 = require("./runtime/loopback-peer");
 const BIND_RETRY_INTERVAL_MS = 100;
 const BIND_RETRY_TIMEOUT_MS = 10_000;
 /**
@@ -11,6 +12,17 @@ const BIND_RETRY_TIMEOUT_MS = 10_000;
  * from outside the sandbox, and session users get no useful secret from it —
  * the report deliberately carries no token.
  *
+ * BROWSER USERS GET NOTHING. A chat's Chromium runs as its own uid (20000-
+ * 29999) with --no-sandbox and uses the sandbox network directly (no egress
+ * proxy, no firewall), so a page or a compromised renderer could connect here
+ * and learn the tenant id, runner id, versions and heartbeat errors. On Linux each
+ * request's peer uid is looked up in /proc/net/tcp{,6}; a browser uid gets a
+ * bare 403. The guard FAILS OPEN when the uid cannot be determined (non-Linux,
+ * /proc unreadable, no matching row): the probe and pf-bootstrap run as root
+ * or pfharness, the report holds no secret, and failing closed would turn a
+ * /proc hiccup into a dead liveness probe. Only a CONFIRMED browser uid is
+ * refused.
+ *
  * STOP MUST ACTUALLY CLOSE, and this is the reason `boundPort` and the socket
  * tracking below exist. `server.close()` stops ACCEPTING connections but leaves
  * any keep-alive connection open, and an open connection keeps the Node event
@@ -23,6 +35,7 @@ const BIND_RETRY_TIMEOUT_MS = 10_000;
 class HealthServer {
     port;
     report;
+    lookupPeerUid;
     server = null;
     /**
      * The port the server actually bound to, RETAINED after `stop()`.
@@ -34,9 +47,12 @@ class HealthServer {
     bound = null;
     /** Live connections, tracked so `stop()` can destroy them. */
     sockets = new Set();
-    constructor(port, report) {
+    constructor(port, report, 
+    /** Injected by tests; defaults to the /proc/net/tcp lookup. */
+    lookupPeerUid = (socket) => (0, loopback_peer_1.peerUid)(socket)) {
         this.port = port;
         this.report = report;
+        this.lookupPeerUid = lookupPeerUid;
     }
     /** The actual bound port, or null before `start()`. Survives `stop()`. */
     get boundPort() {
@@ -73,6 +89,11 @@ class HealthServer {
                     res.end(JSON.stringify({ error: 'Not found' }));
                     return;
                 }
+                if ((0, loopback_peer_1.isBrowserUid)(this.safePeerUid(req.socket))) {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'forbidden' }));
+                    return;
+                }
                 const body = this.report();
                 // 'starting' is not yet healthy, so a probe waits rather than
                 // declaring the sandbox ready too early.
@@ -96,6 +117,15 @@ class HealthServer {
             });
         });
     }
+    /** A lookup that throws counts as "unknown" — fail open, see the class doc. */
+    safePeerUid(socket) {
+        try {
+            return this.lookupPeerUid(socket);
+        }
+        catch {
+            return null;
+        }
+    }
     async stop() {
         const server = this.server;
         if (!server) {

package/dist/runtime/browser-takeover.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/** Built-in gateway server id; the gateway URL ends with `/<this id>`. */
+export declare const BROWSER_BUILTIN_SERVER_ID = "pf-browser";
+/** The MCP server name the agent's backend sees. */
+export declare const BROWSER_SERVER_NAME = "browser";
+/** 409 + this header = a person holds the browser; hold the agent's call. */
+export declare const BROWSER_TAKEOVER_HEADER = "x-pf-browser-takeover";
+/** Sent on re-tries during a hold; the gateway then waits up to 20 s. */
+export declare const BROWSER_AWAIT_HANDBACK_HEADER = "x-pf-browser-await-handback";
+export declare const BROWSER_TAKEOVER_STATUS = 409;
+/** How long the gateway holds one await-handback request. */
+export declare const BROWSER_AWAIT_HANDBACK_HOLD_MS = 20000;
+/** Pi's MCP request timeout for the `browser` server (24 h). */
+export declare const BROWSER_MCP_TIMEOUT_MS: number;
+/** Advertised in `capabilities.features`; the API leases `browser` only then. */
+export declare const BROWSER_HARNESS_FEATURE = "browserTakeover";
+/** True for a gateway target URL of the built-in browser server. */
+export declare function isBrowserTargetUrl(targetUrl: string): boolean;
+/**
+ * The session id in a gateway URL `.../api/mcp/agent/<sessionId>/<serverId>`,
+ * or null when the URL has another shape.
+ */
+export declare function sessionIdFromGatewayUrl(targetUrl: string): string | null;

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);
                 });
             });
         }