@pasko70/pibo 1.13.0 → 1.15.0

package/dist/tools/codex-browser.js

@@ -0,0 +1,461 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { connectCdpTarget, listCdpTargets } from "./cdp-client.js";
+import { browserPoolPaths, releaseBrowserPoolLease } from "./browser-pool.js";
+import { browserUseLeaseEnvironment, findActiveBrowserUseLeaseForHolder } from "./browser-use-leases.js";
+import { ensureBrowserUseWrapper } from "./browser-use-wrapper.js";
+import { findCliToolEntry, getCliToolStatus } from "./registry.js";
+import { CodexBrowserNodeRepl, } from "./codex-browser-node-repl.js";
+export const BROWSER_USE_OPEN_TABS_TOOL_NAME = "browser_use_open_tabs";
+export const BROWSER_USE_TAKE_SCREENSHOT_TOOL_NAME = "browser_use_take_screenshot";
+export const BROWSER_USE_TOOL_NAME = "browser_use_browser_use";
+export const NODE_REPL_JS_TOOL_NAME = "node_repl_js";
+export const NODE_REPL_JS_RESET_TOOL_NAME = "node_repl_js_reset";
+export const CODEX_BROWSER_TOOL_NAMES = [
+    BROWSER_USE_OPEN_TABS_TOOL_NAME,
+    BROWSER_USE_TAKE_SCREENSHOT_TOOL_NAME,
+    BROWSER_USE_TOOL_NAME,
+    NODE_REPL_JS_TOOL_NAME,
+    NODE_REPL_JS_RESET_TOOL_NAME,
+];
+export class CodexBrowserSessionController {
+    options;
+    sessionName;
+    browserPoolLeaseId;
+    authLeaseId;
+    status;
+    wrapperPath;
+    env;
+    runCommand;
+    cdpUrl;
+    nodeRepl;
+    browserLeaseUsed = false;
+    constructor(options) {
+        this.options = options;
+        const entry = findCliToolEntry("browser-use");
+        if (!entry)
+            throw new Error("Pibo browser-use registry entry is unavailable");
+        this.status = options.status ?? getCliToolStatus(entry);
+        this.wrapperPath = this.status.installed
+            ? ensureBrowserUseWrapper(this.status) ?? this.status.executablePath
+            : this.status.executablePath;
+        const baseEnv = options.env ?? process.env;
+        const explicitAuthLease = baseEnv.PIBO_BROWSER_USE_LEASE_ID?.trim();
+        const sessionId = options.piboSessionId?.trim() || "local";
+        const registeredLease = explicitAuthLease ? undefined : findRegisteredLease(this.status, sessionId);
+        const registeredLeaseEnv = registeredLease ? browserUseLeaseEnvironment(this.status, registeredLease) : undefined;
+        this.sessionName = explicitAuthLease && baseEnv.PIBO_BROWSER_USE_SESSION
+            ? baseEnv.PIBO_BROWSER_USE_SESSION
+            : registeredLease?.sessionName ?? `pibo-${safeSessionName(sessionId)}`;
+        this.browserPoolLeaseId = explicitAuthLease && baseEnv.PIBO_BROWSER_POOL_LEASE_ID
+            ? baseEnv.PIBO_BROWSER_POOL_LEASE_ID
+            : registeredLease?.browserPoolLeaseId ?? `browser-use:${this.sessionName}`;
+        this.authLeaseId = explicitAuthLease || registeredLease?.id;
+        this.env = {
+            ...baseEnv,
+            ...(registeredLeaseEnv ?? {}),
+            BROWSER_USE_HOME: this.status.homeDir,
+            PIBO_BROWSER_USE_SESSION: this.sessionName,
+            PIBO_BROWSER_POOL_LEASE_ID: this.browserPoolLeaseId,
+            PIBO_BROWSER_POOL_HOLDER: `pibo-session:${sessionId}`,
+        };
+        if (!this.authLeaseId) {
+            delete this.env.PIBO_BROWSER_USE_LEASE_ID;
+            delete this.env.PIBO_BROWSER_USE_CHROME_USER_DATA_DIR;
+        }
+        this.runCommand = options.runCommand ?? runBrowserUseCommand;
+    }
+    async openTabs() {
+        const cdpUrl = await this.ensureChrome();
+        const targets = await listCdpTargets({ cdpUrl });
+        return pageTargets(targets).map(toBrowserUseTab);
+    }
+    async takeScreenshot(input = {}) {
+        const timeoutMs = input.timeoutMs ?? 15_000;
+        const cdpUrl = await this.ensureChrome(timeoutMs);
+        const targets = pageTargets(await listCdpTargets({ cdpUrl, timeoutMs }));
+        const target = selectTarget(targets, input.tabId);
+        if (!target)
+            throw new Error(input.tabId ? `Browser tab "${input.tabId}" was not found` : "No open browser tab was found");
+        const client = await connectCdpTarget(target, Math.min(timeoutMs, 5_000));
+        try {
+            const data = await captureScreenshot(client, input.fullPage === true, timeoutMs);
+            return {
+                status: "ok",
+                sessionName: this.sessionName,
+                browserPoolLeaseId: this.browserPoolLeaseId,
+                ...(this.authLeaseId ? { authLeaseId: this.authLeaseId } : {}),
+                tab: toBrowserUseTab(target, targets.indexOf(target)),
+                fullPage: input.fullPage === true,
+                mimeType: "image/png",
+                data,
+            };
+        }
+        finally {
+            client.close();
+        }
+    }
+    async use(input, signal) {
+        const command = browserUseCommand(input);
+        const response = await this.execute(command, input.timeoutMs ?? 30_000, signal);
+        if (response.exitCode !== 0) {
+            throw new Error(response.stderr.trim() || response.stdout.trim() || `browser-use exited with code ${response.exitCode ?? "unknown"}`);
+        }
+        return {
+            status: "ok",
+            sessionName: this.sessionName,
+            browserPoolLeaseId: this.browserPoolLeaseId,
+            ...(this.authLeaseId ? { authLeaseId: this.authLeaseId } : {}),
+            command,
+            output: parseJsonOrText(response.stdout),
+            ...(response.stderr.trim() ? { stderr: response.stderr.trim() } : {}),
+        };
+    }
+    async js(code, timeoutMs = 30_000) {
+        const repl = await this.getNodeRepl();
+        return repl.exec(code, timeoutMs);
+    }
+    async jsReset() {
+        if (!this.nodeRepl?.isAlive())
+            return { status: "ok", reset: true };
+        return this.nodeRepl.reset();
+    }
+    async dispose() {
+        this.nodeRepl?.dispose();
+        this.nodeRepl = undefined;
+        if (!this.browserLeaseUsed)
+            return;
+        const identity = {
+            workerId: this.env.PIBO_BROWSER_POOL_WORKER_ID || this.env.PIBO_COMPUTE_WORKER_ID || this.env.HOSTNAME || "local",
+            poolId: this.env.PIBO_BROWSER_POOL_ID || "default",
+            maxBrowserProcesses: positiveInteger(this.env.PIBO_BROWSER_POOL_MAX_PROCESSES, 1),
+        };
+        const rootDir = this.env.PIBO_BROWSER_POOL_ROOT || join(this.status.homeDir, "pibo-browser-pool");
+        try {
+            await releaseBrowserPoolLease(browserPoolPaths(rootDir, identity), identity, { leaseId: this.browserPoolLeaseId });
+        }
+        catch {
+            // Browser pool cleanup is best-effort during Pi session disposal.
+        }
+    }
+    async getNodeRepl() {
+        if (this.nodeRepl?.isAlive())
+            return this.nodeRepl;
+        this.nodeRepl = await CodexBrowserNodeRepl.start({
+            openTabs: () => this.openTabs(),
+            use: (input) => this.use(requireBrowserUseInput(input)),
+        }, this.options.cwd);
+        return this.nodeRepl;
+    }
+    async ensureChrome(timeoutMs = 15_000) {
+        if (this.cdpUrl) {
+            try {
+                await listCdpTargets({ cdpUrl: this.cdpUrl, timeoutMs: Math.min(timeoutMs, 1_000) });
+                return this.cdpUrl;
+            }
+            catch {
+                this.cdpUrl = undefined;
+            }
+        }
+        const response = await this.execute(["--pibo-ensure-chrome"], timeoutMs);
+        if (response.exitCode !== 0) {
+            throw new Error(response.stderr.trim() || response.stdout.trim() || "browser-use could not start Chrome");
+        }
+        const cdpUrl = response.stdout.split(/\r?\n/).map((line) => line.trim()).findLast((line) => /^https?:\/\//.test(line));
+        if (!cdpUrl)
+            throw new Error(`browser-use did not return a CDP URL: ${response.stdout.trim()}`);
+        this.cdpUrl = cdpUrl.replace(/\/+$/, "");
+        return this.cdpUrl;
+    }
+    execute(command, timeoutMs, signal) {
+        if (!this.status.installed) {
+            throw new Error("browser-use is not installed. Run `pibo tools install browser-use`.");
+        }
+        const args = ["--session", this.sessionName, ...(command[0]?.startsWith("--") ? [] : ["--json"]), ...command];
+        this.browserLeaseUsed = true;
+        return this.runCommand({
+            executable: this.wrapperPath,
+            args,
+            cwd: this.options.cwd,
+            env: this.env,
+            timeoutMs,
+            signal,
+        });
+    }
+}
+export function createCodexBrowserToolProfiles() {
+    const descriptions = {
+        [BROWSER_USE_OPEN_TABS_TOOL_NAME]: "List tabs in the persistent Browser Use session (Codex-compatible label: browser_use.open_tabs).",
+        [BROWSER_USE_TAKE_SCREENSHOT_TOOL_NAME]: "Capture a browser tab screenshot (Codex-compatible label: browser_use.take_screenshot).",
+        [BROWSER_USE_TOOL_NAME]: "Control the persistent Browser Use session through structured actions (Codex-compatible label: browser_use.browser_use).",
+        [NODE_REPL_JS_TOOL_NAME]: "Run JavaScript in a persistent browser-bound Node REPL (Codex-compatible label: node_repl.js).",
+        [NODE_REPL_JS_RESET_TOOL_NAME]: "Reset the persistent browser-bound Node REPL (Codex-compatible label: node_repl.js_reset).",
+    };
+    return CODEX_BROWSER_TOOL_NAMES.map((name) => ({
+        name,
+        description: descriptions[name],
+        yieldable: name === BROWSER_USE_TOOL_NAME,
+        builtInPiboTool: "codex_browser",
+    }));
+}
+export function createCodexBrowserToolDefinitions(controller, enabledNames = CODEX_BROWSER_TOOL_NAMES) {
+    const enabled = new Set(enabledNames);
+    const tools = [
+        [BROWSER_USE_OPEN_TABS_TOOL_NAME, defineTool({
+                name: BROWSER_USE_OPEN_TABS_TOOL_NAME,
+                label: "browser_use.open_tabs",
+                description: "List open tabs in the persistent Browser Use session. Returns stable target IDs, short tab IDs, titles, URLs, and tab indices.",
+                promptSnippet: "Use browser_use_open_tabs (browser_use.open_tabs) to discover tabs before targeting a screenshot or tab-specific action.",
+                executionMode: "parallel",
+                parameters: Type.Object({}),
+                async execute() {
+                    return toolResult(await controller.openTabs());
+                },
+            })],
+        [BROWSER_USE_TAKE_SCREENSHOT_TOOL_NAME, defineTool({
+                name: BROWSER_USE_TAKE_SCREENSHOT_TOOL_NAME,
+                label: "browser_use.take_screenshot",
+                description: "Take a PNG screenshot from the persistent Browser Use session. Omit tabId to capture the first attachable page tab.",
+                promptSnippet: "Use browser_use_take_screenshot (browser_use.take_screenshot) when visual page state matters.",
+                executionMode: "parallel",
+                parameters: Type.Object({
+                    tabId: Type.Optional(Type.String({ description: "Full target ID or short tab ID returned by browser_use_open_tabs." })),
+                    fullPage: Type.Optional(Type.Boolean({ description: "Capture the full scrollable page instead of only the viewport." })),
+                    timeoutMs: Type.Optional(Type.Number({ description: "Screenshot timeout in milliseconds." })),
+                }),
+                async execute(_toolCallId, params) {
+                    const result = await controller.takeScreenshot(params);
+                    const { data, ...details } = result;
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(details, null, 2) },
+                            { type: "image", data, mimeType: result.mimeType },
+                        ],
+                        details,
+                    };
+                },
+            })],
+        [BROWSER_USE_TOOL_NAME, defineTool({
+                name: BROWSER_USE_TOOL_NAME,
+                label: "browser_use.browser_use",
+                description: "Control one persistent Browser Use session with a structured action. State and element indices persist through the same Pibo session and managed browser-pool lease.",
+                promptSnippet: "Use browser_use_browser_use (browser_use.browser_use) for structured navigation and interaction; call state before index-based clicks or input.",
+                executionMode: "sequential",
+                parameters: Type.Object({
+                    action: StringEnum(["navigate", "state", "click", "input", "type", "scroll", "back", "switch_tab", "close_tab", "keys", "evaluate", "wait_selector", "wait_text"], { description: "Browser action." }),
+                    url: Type.Optional(Type.String({ description: "URL for navigate." })),
+                    index: Type.Optional(Type.Number({ description: "Interactive element index for click or input." })),
+                    coordinateX: Type.Optional(Type.Number({ description: "Viewport X coordinate for click; use with coordinateY." })),
+                    coordinateY: Type.Optional(Type.Number({ description: "Viewport Y coordinate for click; use with coordinateX." })),
+                    text: Type.Optional(Type.String({ description: "Text for input, type, or wait_text." })),
+                    direction: Type.Optional(StringEnum(["up", "down"], { description: "Scroll direction." })),
+                    amount: Type.Optional(Type.Number({ description: "Scroll amount in pixels." })),
+                    tab: Type.Optional(Type.Number({ description: "Browser Use tab index for switch_tab or close_tab." })),
+                    keys: Type.Optional(Type.String({ description: "Keys to send, such as Enter or Control+a." })),
+                    js: Type.Optional(Type.String({ description: "JavaScript for evaluate." })),
+                    selector: Type.Optional(Type.String({ description: "CSS selector for wait_selector." })),
+                    timeoutMs: Type.Optional(Type.Number({ description: "Action timeout in milliseconds." })),
+                }),
+                async execute(_toolCallId, params, signal) {
+                    return toolResult(await controller.use(params, signal));
+                },
+            })],
+        [NODE_REPL_JS_TOOL_NAME, defineTool({
+                name: NODE_REPL_JS_TOOL_NAME,
+                label: "node_repl.js",
+                description: "Execute JavaScript in a persistent, session-scoped Node REPL with top-level await. Top-level bindings persist. The sandbox omits require and process, and exposes browser.openTabs() plus browser.use(action, params) for the same Browser Use session.",
+                promptSnippet: "Use node_repl_js (node_repl.js) for persistent JavaScript state and browser-bound analysis. Top-level await and reusable top-level bindings are supported.",
+                executionMode: "sequential",
+                parameters: Type.Object({
+                    code: Type.String({ description: "JavaScript to execute. Top-level declarations persist across calls." }),
+                    timeoutMs: Type.Optional(Type.Number({ description: "Execution timeout in milliseconds." })),
+                }),
+                async execute(_toolCallId, params) {
+                    return nodeReplToolResult(await controller.js(params.code, params.timeoutMs));
+                },
+            })],
+        [NODE_REPL_JS_RESET_TOOL_NAME, defineTool({
+                name: NODE_REPL_JS_RESET_TOOL_NAME,
+                label: "node_repl.js_reset",
+                description: "Reset the persistent node_repl.js namespace for the current Pibo session.",
+                promptSnippet: "Use node_repl_js_reset (node_repl.js_reset) only when persistent JavaScript state should be discarded.",
+                executionMode: "sequential",
+                parameters: Type.Object({}),
+                async execute() {
+                    return nodeReplToolResult(await controller.jsReset());
+                },
+            })],
+    ];
+    return tools.filter(([name]) => enabled.has(name)).map(([, definition]) => definition);
+}
+function safeSessionName(value) {
+    return value.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 120) || "local";
+}
+function positiveInteger(value, fallback) {
+    const parsed = Number.parseInt(value ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function findRegisteredLease(status, piboSessionId) {
+    try {
+        return findActiveBrowserUseLeaseForHolder(status, piboSessionId);
+    }
+    catch {
+        return undefined;
+    }
+}
+function runBrowserUseCommand(request) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(request.executable, request.args, {
+            cwd: request.cwd,
+            env: request.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const abort = () => child.kill("SIGTERM");
+        request.signal?.addEventListener("abort", abort, { once: true });
+        const timer = setTimeout(() => child.kill("SIGTERM"), request.timeoutMs);
+        child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+        child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+        child.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            request.signal?.removeEventListener("abort", abort);
+            reject(error);
+        });
+        child.once("close", (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            request.signal?.removeEventListener("abort", abort);
+            resolve({ exitCode, stdout, stderr });
+        });
+    });
+}
+function browserUseCommand(input) {
+    switch (input.action) {
+        case "navigate":
+            return ["open", requireText(input.url, "url")];
+        case "state":
+            return ["state"];
+        case "click":
+            if (input.index !== undefined)
+                return ["click", integerText(input.index, "index")];
+            if (input.coordinateX !== undefined && input.coordinateY !== undefined) {
+                return ["click", integerText(input.coordinateX, "coordinateX"), integerText(input.coordinateY, "coordinateY")];
+            }
+            throw new Error("browser_use.browser_use click requires index or coordinateX and coordinateY");
+        case "input":
+            return ["input", integerText(input.index, "index"), requireText(input.text, "text")];
+        case "type":
+            return ["type", requireText(input.text, "text")];
+        case "scroll":
+            return ["scroll", input.direction ?? "down", ...(input.amount === undefined ? [] : ["--amount", integerText(input.amount, "amount")])];
+        case "back":
+            return ["back"];
+        case "switch_tab":
+            return ["switch", integerText(input.tab, "tab")];
+        case "close_tab":
+            return ["close-tab", ...(input.tab === undefined ? [] : [integerText(input.tab, "tab")])];
+        case "keys":
+            return ["keys", requireText(input.keys, "keys")];
+        case "evaluate":
+            return ["eval", requireText(input.js, "js")];
+        case "wait_selector":
+            return ["wait", "selector", requireText(input.selector, "selector")];
+        case "wait_text":
+            return ["wait", "text", requireText(input.text, "text")];
+    }
+}
+function requireBrowserUseInput(value) {
+    if (typeof value.action !== "string")
+        throw new Error("browser.use requires action");
+    return value;
+}
+function requireText(value, field) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`browser_use.browser_use ${field} must be a non-empty string`);
+    return value;
+}
+function integerText(value, field) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        throw new Error(`browser_use.browser_use ${field} must be an integer`);
+    return String(value);
+}
+function pageTargets(targets) {
+    return targets.filter((target) => target.type === "page" && Boolean(target.webSocketDebuggerUrl));
+}
+function toBrowserUseTab(target, index = 0) {
+    return {
+        index,
+        tabId: target.id.slice(-4),
+        targetId: target.id,
+        title: target.title,
+        url: target.url,
+        type: target.type,
+    };
+}
+function selectTarget(targets, tabId) {
+    if (!tabId)
+        return targets.find((target) => target.url !== "about:blank") ?? targets[0];
+    return targets.find((target) => target.id === tabId || target.id.endsWith(tabId));
+}
+async function captureScreenshot(client, fullPage, timeoutMs) {
+    await client.send("Page.enable", undefined, timeoutMs);
+    const params = { format: "png", fromSurface: true, captureBeyondViewport: fullPage };
+    if (fullPage) {
+        const metrics = await client.send("Page.getLayoutMetrics", undefined, timeoutMs);
+        const width = metrics.cssContentSize?.width;
+        const height = metrics.cssContentSize?.height;
+        if (typeof width === "number" && typeof height === "number") {
+            params.clip = { x: 0, y: 0, width, height, scale: 1 };
+        }
+    }
+    const response = await client.send("Page.captureScreenshot", params, timeoutMs);
+    if (typeof response.data !== "string" || response.data.length === 0)
+        throw new Error("CDP screenshot returned no image data");
+    return response.data;
+}
+function parseJsonOrText(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return "";
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function toolResult(result) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: result,
+    };
+}
+function nodeReplToolResult(result) {
+    const lines = [`status: ${result.status}`];
+    if ("executionCount" in result)
+        lines.push(`executionCount: ${result.executionCount}`, `durationMs: ${result.durationMs}`);
+    if ("reset" in result)
+        lines.push(`reset: ${result.reset}`);
+    if ("stdout" in result && result.stdout)
+        lines.push("", "stdout:", result.stdout);
+    if ("stderr" in result && result.stderr)
+        lines.push("", "stderr:", result.stderr);
+    if ("result" in result && result.result !== undefined && result.result !== null)
+        lines.push("", "result:", JSON.stringify(result.result, null, 2));
+    if (result.error)
+        lines.push("", "error:", JSON.stringify(result.error, null, 2));
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: result,
+        isError: result.status !== "ok",
+    };
+}

package/dist/web/channel.js

@@ -6,6 +6,7 @@ import { PiboWebHttpError, nodeRequestToWebRequest, responseHtml, responseJson,
 export const DEFAULT_WEB_CHANNEL_HOST = "127.0.0.1";
 export const DEFAULT_WEB_CHANNEL_PORT = 4788;
 export const WEB_CHANNEL_NAME = "web-host";
+const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5_000;
 /**
  * Internal header that carries the TCP socket peer address from the web host
  * channel to the auth plugin. This is one of three independent safety layers
@@ -168,11 +169,44 @@ function createCanonicalRedirect(request, canonicalBaseURL) {
     }
     return redirect(new URL(`${url.pathname}${url.search}`, canonical.origin).toString());
 }
+function isEventStreamResponse(response) {
+    return response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream") === true;
+}
+async function waitForServerClose(closePromise, timeoutMs) {
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            settled = true;
+            resolve(false);
+        }, timeoutMs);
+        closePromise.then(() => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            resolve(true);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
 export function createWebHostChannel(options = {}) {
     const host = options.host ?? DEFAULT_WEB_CHANNEL_HOST;
     const port = options.port ?? DEFAULT_WEB_CHANNEL_PORT;
+    const shutdownDrainTimeoutMs = options.shutdownDrainTimeoutMs ?? DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
+    if (!Number.isFinite(shutdownDrainTimeoutMs) || shutdownDrainTimeoutMs < 0) {
+        throw new Error("Web channel shutdown drain timeout must be a non-negative finite number");
+    }
     let server;
     let context;
+    let stopPromise;
+    let shuttingDown = false;
+    const sockets = new Set();
+    const eventStreamControllers = new Map();
     const requireContext = () => {
         if (!context)
             throw new Error("Web channel is not started");
@@ -185,6 +219,20 @@ export function createWebHostChannel(options = {}) {
         }
         return auth.handleRequest(request);
     };
+    const sendResponse = async (nodeResponse, webResponse) => {
+        const eventStreamController = isEventStreamResponse(webResponse) ? new AbortController() : undefined;
+        if (eventStreamController)
+            eventStreamControllers.set(nodeResponse, eventStreamController);
+        try {
+            await sendWebResponse(nodeResponse, webResponse, { signal: eventStreamController?.signal });
+        }
+        finally {
+            if (eventStreamController)
+                eventStreamControllers.delete(nodeResponse);
+            if (shuttingDown)
+                server?.closeIdleConnections();
+        }
+    };
     const handleRequest = async (nodeRequest, nodeResponse) => {
         try {
             const baseURL = createRequestBaseURL(nodeRequest, host, port);
@@ -198,51 +246,51 @@ export function createWebHostChannel(options = {}) {
             const url = new URL(request.url);
             const canonicalRedirect = createCanonicalRedirect(request, options.canonicalBaseURL);
             if (canonicalRedirect) {
-                await sendWebResponse(nodeResponse, canonicalRedirect);
+                await sendResponse(nodeResponse, canonicalRedirect);
                 return;
             }
             if (url.pathname === "/health") {
-                await sendWebResponse(nodeResponse, responseJson({
+                await sendResponse(nodeResponse, responseJson({
                     status: "ok",
                     mode: process.env.PIBO_FALLBACK_MODE === "1" ? "fallback" : "main",
                 }));
                 return;
             }
             if (url.pathname === "/gateway/status") {
-                await sendWebResponse(nodeResponse, createGatewayStatusResponse(requireContext(), options));
+                await sendResponse(nodeResponse, createGatewayStatusResponse(requireContext(), options));
                 return;
             }
             if (url.pathname.startsWith("/api/auth/")) {
                 const authResponse = stripSocketPeerHeaderFromResponse(await handleAuthRequest(request));
-                await sendWebResponse(nodeResponse, authResponse);
+                await sendResponse(nodeResponse, authResponse);
                 return;
             }
             const ctx = requireContext();
             const simpleApiResponse = await handleSimpleAgentApiRequest(request, ctx);
             if (simpleApiResponse) {
-                await sendWebResponse(nodeResponse, simpleApiResponse);
+                await sendResponse(nodeResponse, simpleApiResponse);
                 return;
             }
             const apps = ctx.getWebApps();
             const app = apps.find((candidate) => matchPrefix(url.pathname, candidate.mountPath) || matchPrefix(url.pathname, candidate.apiPrefix));
             if (app) {
                 const response = await app.handleRequest(request, createAppContext(ctx));
-                await sendWebResponse(nodeResponse, response ?? notFound());
+                await sendResponse(nodeResponse, response ?? notFound());
                 return;
             }
             if (url.pathname === "/" && apps[0]) {
-                await sendWebResponse(nodeResponse, redirect(apps[0].mountPath));
+                await sendResponse(nodeResponse, redirect(apps[0].mountPath));
                 return;
             }
             if (url.pathname === "/") {
-                await sendWebResponse(nodeResponse, responseHtml("<!doctype html><title>Pibo</title><p>No web apps registered.</p>"));
+                await sendResponse(nodeResponse, responseHtml("<!doctype html><title>Pibo</title><p>No web apps registered.</p>"));
                 return;
             }
-            await sendWebResponse(nodeResponse, notFound());
+            await sendResponse(nodeResponse, notFound());
         }
         catch (error) {
             const status = error instanceof PiboAuthError || error instanceof PiboWebHttpError ? error.statusCode : 500;
-            await sendWebResponse(nodeResponse, responseJson({ error: error instanceof Error ? error.message : String(error) }, { status }));
+            await sendResponse(nodeResponse, responseJson({ error: error instanceof Error ? error.message : String(error) }, { status }));
         }
     };
     return {
@@ -251,12 +299,19 @@ export function createWebHostChannel(options = {}) {
         description: "Same-origin HTTP host for pibo web apps and auth routes.",
         auth: { mode: "required" },
         async start(channelContext) {
+            if (stopPromise)
+                await stopPromise;
             if (server)
                 return;
+            shuttingDown = false;
             context = channelContext;
             server = createServer((request, response) => {
                 void handleRequest(request, response);
             });
+            server.on("connection", (socket) => {
+                sockets.add(socket);
+                socket.once("close", () => sockets.delete(socket));
+            });
             await new Promise((resolve, reject) => {
                 server.once("error", reject);
                 server.listen(port, host, () => {
@@ -270,12 +325,46 @@ export function createWebHostChannel(options = {}) {
             }
         },
         async stop() {
-            context = undefined;
-            if (server) {
-                await new Promise((resolve, reject) => {
-                    server.close((error) => (error ? reject(error) : resolve()));
-                });
-                server = undefined;
+            if (stopPromise)
+                return await stopPromise;
+            if (!server) {
+                context = undefined;
+                return;
+            }
+            const closingServer = server;
+            shuttingDown = true;
+            stopPromise = (async () => {
+                try {
+                    const closePromise = new Promise((resolve, reject) => {
+                        closingServer.close((error) => (error ? reject(error) : resolve()));
+                    });
+                    const eventStreamCount = eventStreamControllers.size;
+                    for (const controller of eventStreamControllers.values())
+                        controller.abort();
+                    closingServer.closeIdleConnections();
+                    const drained = await waitForServerClose(closePromise, shutdownDrainTimeoutMs);
+                    if (!drained) {
+                        const connectionCount = sockets.size;
+                        console.warn(`[web-host] graceful shutdown timed out after ${shutdownDrainTimeoutMs} ms; force-closing ${connectionCount} active connection(s)`);
+                        for (const socket of sockets)
+                            socket.destroy();
+                        await closePromise;
+                    }
+                    else if (eventStreamCount > 0) {
+                        console.error(`[web-host] graceful shutdown closed ${eventStreamCount} active event stream(s)`);
+                    }
+                }
+                finally {
+                    server = undefined;
+                    context = undefined;
+                    shuttingDown = false;
+                }
+            })();
+            try {
+                await stopPromise;
+            }
+            finally {
+                stopPromise = undefined;
             }
         },
         getAddress() {