@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/dist/plugins/browser-session.js

@@ -2,9 +2,52 @@ import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 const requestTimeoutMs = 15_000;
+const maxTabListBytes = 1024 * 1024;
+const maxTabItems = 256;
+const maxCdpResponseBytes = 12 * 1024 * 1024;
+const maxScreenshotBytes = 8 * 1024 * 1024;
 const maxTextBytes = 128 * 1024;
+const maxEndpointLength = 2_048;
 const maxSelectorLength = 512;
+const maxTargetIdLength = 512;
+const maxNavigationUrlLength = 8_192;
+const maxTabTitleLength = 4_096;
+const maxTabTypeLength = 64;
+const maxDebuggerUrlLength = 2_048;
+const maxTabSummaryBytes = 128 * 1024;
+const maxPanelTabs = 20;
+const maxPanelTextChars = 12_000;
+const maxPanelErrorChars = 2_000;
+const noParameterNames = new Set();
+const targetParameterNames = new Set(["targetId"]);
+const navigationParameterNames = new Set(["targetId", "url"]);
+const clickParameterNames = new Set(["targetId", "selector"]);
+function inspectParameters(value, allowed) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Browser session parameters must be an object");
+    let descriptors;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new Error("Browser session parameters must be a plain object");
+        descriptors = Object.getOwnPropertyDescriptors(value);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "Browser session parameters must be a plain object")
+            throw error;
+        throw new Error("Browser session parameters must be an accessible plain object", { cause: error });
+    }
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !allowed.has(key)))
+        throw new Error("Browser session parameters contain an unknown property");
+    if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+        throw new Error("Browser session parameters must use data properties");
+    return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+}
 function endpointUrl(raw) {
+    if (typeof raw !== "string")
+        throw new Error("Browser session endpoint must be a string");
+    if (raw.length === 0 || raw.length > maxEndpointLength)
+        throw new Error(`Browser session endpoint must be between 1 and ${maxEndpointLength} characters`);
     let endpoint;
     try {
         endpoint = new URL(raw);
@@ -12,95 +55,276 @@ function endpointUrl(raw) {
     catch {
         throw new Error("Browser session endpoint is invalid");
     }
+    if (endpoint.username !== "" || endpoint.password !== "")
+        throw new Error("Browser session endpoint must not contain credentials");
     const host = endpoint.hostname.replace(/^\[|\]$/g, "").toLowerCase();
     if (endpoint.protocol !== "http:" || (host !== "localhost" && host !== "127.0.0.1" && host !== "::1"))
         throw new Error("Browser session endpoint must be a local http://localhost, 127.0.0.1, or ::1 address");
     endpoint.pathname = endpoint.pathname.replace(/\/$/, "");
     return endpoint;
 }
-async function tabs(endpoint) {
-    const response = await fetch(new URL("/json/list", endpoint));
-    if (!response.ok)
-        throw new Error(`Chrome DevTools returned HTTP ${response.status}`);
-    const payload = (await response.json());
+async function cancelResponseBody(response) {
+    try {
+        await response.body?.cancel?.();
+    }
+    catch {
+        // Response cleanup is best effort while preserving the original protocol error.
+    }
+}
+async function readTabList(response) {
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > maxTabListBytes) {
+        await cancelResponseBody(response);
+        throw new Error("Chrome DevTools tab list exceeded the 1 MiB limit");
+    }
+    if (response.body === null)
+        throw new Error("Chrome DevTools returned an empty tab list");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            bytes += next.value.byteLength;
+            if (bytes > maxTabListBytes) {
+                await reader.cancel();
+                throw new Error("Chrome DevTools tab list exceeded the 1 MiB limit");
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))));
+    }
+    catch (error) {
+        throw new Error("Chrome DevTools tab list must contain valid UTF-8", { cause: error });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Chrome DevTools returned an invalid tab list: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+function cancelledError(scope, reason) {
+    return new Error(`${scope} was cancelled`, { cause: reason });
+}
+function tabString(raw, index, field, maxLength, allowEmpty = true) {
+    if (typeof raw !== "string")
+        throw new Error(`Chrome DevTools tab ${index} ${field} must be a string`);
+    const minimum = allowEmpty ? 0 : 1;
+    if (raw.length < minimum || raw.length > maxLength)
+        throw new Error(`Chrome DevTools tab ${index} ${field} must be between ${minimum} and ${maxLength} characters`);
+    if (raw.includes("\0"))
+        throw new Error(`Chrome DevTools tab ${index} ${field} must not contain NUL characters`);
+    return raw;
+}
+function browserTab(raw, index) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error(`Chrome DevTools tab ${index} must be an object`);
+    const item = raw;
+    const webSocketDebuggerUrl = item.webSocketDebuggerUrl === undefined ? undefined : tabString(item.webSocketDebuggerUrl, index, "WebSocket URL", maxDebuggerUrlLength, false);
+    return {
+        targetId: tabString(item.id, index, "target ID", maxTargetIdLength, false),
+        title: tabString(item.title, index, "title", maxTabTitleLength),
+        url: tabString(item.url, index, "URL", maxNavigationUrlLength),
+        type: tabString(item.type, index, "type", maxTabTypeLength, false),
+        ...(webSocketDebuggerUrl === undefined ? {} : { webSocketDebuggerUrl }),
+    };
+}
+async function tabs(endpoint, signal) {
+    if (signal?.aborted === true)
+        throw cancelledError("Chrome DevTools discovery", signal.reason);
+    const controller = new AbortController();
+    let timedOut = false;
+    const abortFromCaller = () => controller.abort(signal?.reason);
+    signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, requestTimeoutMs);
+    timer.unref();
+    let payload;
+    try {
+        const response = await fetch(new URL("/json/list", endpoint), { signal: controller.signal, redirect: "error" });
+        if (!response.ok) {
+            await cancelResponseBody(response);
+            throw new Error(`Chrome DevTools returned HTTP ${response.status}`);
+        }
+        payload = await readTabList(response);
+    }
+    catch (error) {
+        if (timedOut)
+            throw new Error(`Chrome DevTools discovery timed out after ${requestTimeoutMs} ms`, { cause: error });
+        if (controller.signal.aborted)
+            throw cancelledError("Chrome DevTools discovery", error);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abortFromCaller);
+    }
     if (!Array.isArray(payload))
         throw new Error("Chrome DevTools returned an invalid tab list");
-    return payload
-        .filter((tab) => typeof tab === "object" && tab !== null && typeof tab.id === "string")
-        .map((tab) => {
-        const item = tab;
-        return {
-            targetId: String(item.id),
-            title: typeof item.title === "string" ? item.title : "",
-            url: typeof item.url === "string" ? item.url : "",
-            type: typeof item.type === "string" ? item.type : "",
-            ...(typeof item.webSocketDebuggerUrl === "string" ? { webSocketDebuggerUrl: item.webSocketDebuggerUrl } : {}),
-        };
-    });
+    if (payload.length > maxTabItems)
+        throw new Error(`Chrome DevTools tab inventory cannot exceed ${maxTabItems} items`);
+    return payload.map((tab, index) => browserTab(tab, index + 1));
 }
-async function target(endpoint, targetId) {
-    const tab = (await tabs(endpoint)).find((item) => item.targetId === targetId);
+function localDebuggerUrl(endpoint, raw) {
+    let debuggerUrl;
+    try {
+        debuggerUrl = new URL(raw);
+    }
+    catch {
+        throw new Error("Chrome DevTools returned an invalid WebSocket URL");
+    }
+    const host = debuggerUrl.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    const endpointPort = endpoint.port || "80";
+    const debuggerPort = debuggerUrl.port || "80";
+    if (debuggerUrl.protocol !== "ws:" ||
+        (host !== "localhost" && host !== "127.0.0.1" && host !== "::1") ||
+        debuggerPort !== endpointPort ||
+        debuggerUrl.username !== "" ||
+        debuggerUrl.password !== "")
+        throw new Error("Chrome DevTools WebSocket URL must stay on the configured local endpoint");
+    return debuggerUrl.toString();
+}
+async function target(endpoint, targetId, signal) {
+    const tab = (await tabs(endpoint, signal)).find((item) => item.targetId === targetId);
     if (tab === undefined)
         throw new Error(`Browser tab was not found: ${targetId}`);
     if (tab.webSocketDebuggerUrl === undefined)
         throw new Error(`Browser tab is not debuggable: ${targetId}`);
-    return tab;
+    return { ...tab, webSocketDebuggerUrl: localDebuggerUrl(endpoint, tab.webSocketDebuggerUrl) };
 }
-async function cdp(tab, method, params) {
+async function cdp(tab, method, params, signal) {
     if (tab.webSocketDebuggerUrl === undefined)
         throw new Error(`Browser tab is not debuggable: ${tab.targetId}`);
+    if (signal?.aborted === true)
+        throw cancelledError("Chrome DevTools request", signal.reason);
     const socket = new WebSocket(tab.webSocketDebuggerUrl);
     return new Promise((resolve, reject) => {
         const id = 1;
+        const closeSocket = () => {
+            try {
+                socket.close();
+            }
+            catch {
+                // Closing is best effort after the request has already failed.
+            }
+        };
         const timer = setTimeout(() => {
             cleanup();
-            socket.close();
+            closeSocket();
             reject(new Error(`Chrome DevTools request timed out: ${method}`));
         }, requestTimeoutMs);
+        timer.unref();
         const cleanup = () => {
             clearTimeout(timer);
             socket.removeEventListener("open", onOpen);
             socket.removeEventListener("message", onMessage);
             socket.removeEventListener("error", onError);
             socket.removeEventListener("close", onClose);
+            signal?.removeEventListener("abort", onAbort);
         };
         const onOpen = () => {
-            socket.send(JSON.stringify({ id, method, ...(params === undefined ? {} : { params }) }));
+            try {
+                socket.send(JSON.stringify({ id, method, ...(params === undefined ? {} : { params }) }));
+            }
+            catch (error) {
+                cleanup();
+                closeSocket();
+                reject(error instanceof Error ? error : new Error("Could not send the Chrome DevTools request", { cause: error }));
+            }
         };
         const onMessage = (event) => {
+            if (typeof event.data !== "string") {
+                cleanup();
+                closeSocket();
+                reject(new Error("Chrome DevTools returned a non-text response"));
+                return;
+            }
+            if (Buffer.byteLength(event.data, "utf8") > maxCdpResponseBytes) {
+                cleanup();
+                closeSocket();
+                reject(new Error("Chrome DevTools response exceeded the 12 MiB limit"));
+                return;
+            }
             let message;
             try {
-                message = JSON.parse(typeof event.data === "string" ? event.data : String(event.data));
+                message = JSON.parse(event.data);
             }
-            catch {
+            catch (error) {
+                cleanup();
+                closeSocket();
+                reject(new Error("Chrome DevTools returned invalid JSON", { cause: error }));
                 return;
             }
-            if (typeof message !== "object" || message === null || message.id !== id)
+            if (typeof message !== "object" || message === null || Array.isArray(message)) {
+                cleanup();
+                closeSocket();
+                reject(new Error("Chrome DevTools returned an invalid response envelope"));
                 return;
-            cleanup();
-            socket.close();
+            }
             const payload = message;
-            if (typeof payload.error === "object" && payload.error !== null) {
+            if (payload.id === undefined)
+                return;
+            if (payload.id !== id)
+                return;
+            cleanup();
+            closeSocket();
+            const hasResult = Object.prototype.hasOwnProperty.call(payload, "result");
+            const hasError = Object.prototype.hasOwnProperty.call(payload, "error");
+            if (hasResult === hasError) {
+                reject(new Error("Chrome DevTools returned an invalid response envelope"));
+                return;
+            }
+            if (hasError) {
+                if (typeof payload.error !== "object" || payload.error === null || Array.isArray(payload.error)) {
+                    reject(new Error("Chrome DevTools returned an invalid error response"));
+                    return;
+                }
                 const errorMessage = payload.error.message;
-                reject(new Error(typeof errorMessage === "string" ? errorMessage : "Chrome DevTools request failed"));
+                if (typeof errorMessage !== "string" || errorMessage.length === 0 || errorMessage.length > maxPanelErrorChars || errorMessage.includes("\0")) {
+                    reject(new Error("Chrome DevTools returned an invalid error response"));
+                    return;
+                }
+                reject(new Error(errorMessage));
+                return;
             }
-            else if (typeof payload.result === "object" && payload.result !== null)
-                resolve(payload.result);
-            else
-                reject(new Error("Chrome DevTools returned an invalid response"));
+            if (typeof payload.result !== "object" || payload.result === null || Array.isArray(payload.result)) {
+                reject(new Error("Chrome DevTools returned an invalid result response"));
+                return;
+            }
+            resolve(payload.result);
         };
         const onError = () => {
             cleanup();
+            closeSocket();
             reject(new Error("Could not connect to the Chrome DevTools tab"));
         };
         const onClose = () => {
             cleanup();
             reject(new Error("Chrome DevTools tab connection closed before responding"));
         };
+        const onAbort = () => {
+            cleanup();
+            closeSocket();
+            reject(cancelledError(`Chrome DevTools request ${method}`, signal?.reason));
+        };
         socket.addEventListener("open", onOpen);
         socket.addEventListener("message", onMessage);
         socket.addEventListener("error", onError);
         socket.addEventListener("close", onClose);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted === true)
+            onAbort();
     });
 }
 function resultValue(result) {
@@ -114,45 +338,115 @@ function resultValue(result) {
         throw new Error("Page evaluation returned no value");
     return value.value;
 }
-async function ready(endpoint, tab) {
+async function ready(tab, signal) {
     const deadline = Date.now() + requestTimeoutMs;
     while (Date.now() < deadline) {
         try {
-            const result = await cdp(tab, "Runtime.evaluate", { expression: "document.readyState", returnByValue: true });
+            const result = await cdp(tab, "Runtime.evaluate", { expression: "document.readyState", returnByValue: true }, signal);
             if (resultValue(result) === "complete" || resultValue(result) === "interactive")
                 return;
         }
-        catch {
+        catch (error) {
+            if (signal?.aborted === true)
+                throw cancelledError("Browser navigation", error);
             // The navigation may replace the target briefly; poll until it is ready or the deadline expires.
         }
         await new Promise((resolve) => setTimeout(resolve, 50));
     }
     throw new Error("Browser navigation did not become ready within 15 seconds");
 }
-async function evaluate(tab, expression) {
-    const result = await cdp(tab, "Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true });
+async function evaluate(tab, expression, signal) {
+    const result = await cdp(tab, "Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true }, signal);
     return resultValue(result);
 }
-export const Config = z.object({ endpoint: z.string().default("http://127.0.0.1:9222") });
+function browserTargetId(raw) {
+    if (typeof raw !== "string")
+        throw new Error("Browser target ID must be a string");
+    if (raw.length === 0 || raw.length > maxTargetIdLength)
+        throw new Error(`Browser target ID must be between 1 and ${maxTargetIdLength} characters`);
+    return raw;
+}
+function browserSelector(raw) {
+    if (typeof raw !== "string")
+        throw new Error("Browser selector must be a string");
+    if (raw.length === 0 || raw.length > maxSelectorLength)
+        throw new Error(`Browser selector must be between 1 and ${maxSelectorLength} characters`);
+    return raw;
+}
+function navigationUrl(raw) {
+    if (typeof raw !== "string")
+        throw new Error("Browser navigation URL must be a string");
+    if (raw.length === 0 || raw.length > maxNavigationUrlLength)
+        throw new Error(`Browser navigation URL must be between 1 and ${maxNavigationUrlLength} characters`);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("Browser navigation URL is invalid");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error("Browser navigation only supports http and https URLs");
+    if (url.username !== "" || url.password !== "")
+        throw new Error("Browser navigation URL must be HTTP or HTTPS without credentials");
+    return url;
+}
+function boundedUtf8(text, maxBytes) {
+    const encoded = Buffer.from(text, "utf8");
+    if (encoded.byteLength <= maxBytes)
+        return { text, truncated: false };
+    let end = maxBytes;
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end -= 1;
+    return { text: encoded.subarray(0, end).toString("utf8"), truncated: true };
+}
+function tabSummary(items) {
+    if (items.length === 0)
+        return "No browser pages are open.";
+    const summary = items.map((tab) => `${tab.targetId} ${tab.title} ${tab.url}`).join("\n");
+    const bounded = boundedUtf8(summary, maxTabSummaryBytes);
+    if (!bounded.truncated)
+        return bounded.text;
+    const notice = `\n… Browser tab summary truncated; ${items.length} tabs are available in details.`;
+    const availableBytes = maxTabSummaryBytes - Buffer.byteLength(notice, "utf8");
+    return boundedUtf8(summary, availableBytes).text + notice;
+}
+export const Config = z.object({ endpoint: z.string().min(1).max(maxEndpointLength).default("http://127.0.0.1:9222") });
 export default {
     name: "pi-browser-session",
     inject: ["piPluginUi", "piTools"],
     Config,
     apply(context, config) {
         const endpoint = endpointUrl(config.endpoint ?? "http://127.0.0.1:9222");
+        const lifecycle = new AbortController();
+        const executionSignal = (signal) => (signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]));
         let latest;
-        const listTabs = async () => tabs(endpoint);
-        const getTab = async (targetId) => target(endpoint, targetId);
+        const panelLatest = () => {
+            if (latest === undefined)
+                return null;
+            if (latest.text === undefined)
+                return structuredClone(latest);
+            return {
+                ...structuredClone(latest),
+                text: latest.text.slice(0, maxPanelTextChars),
+                previewTruncated: latest.text.length > maxPanelTextChars,
+            };
+        };
+        const panelLimits = { tabs: maxPanelTabs, textPreviewCharacters: maxPanelTextChars, errorCharacters: maxPanelErrorChars };
+        const listTabs = async (signal) => tabs(endpoint, signal);
+        const getTab = async (targetId, signal) => target(endpoint, targetId, signal);
         const unregisterTabs = context.piTools.register(defineTool({
             name: "browser_tabs",
             label: "Browser tabs",
             description: "List pages in an already-running local Chrome DevTools session.",
             promptSnippet: "list tabs in the connected local browser",
-            parameters: Type.Object({}),
-            async execute() {
-                const items = (await listTabs()).filter((tab) => tab.type === "page");
+            parameters: Type.Object({}, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                inspectParameters(params, noParameterNames);
+                const items = (await listTabs(executionSignal(signal))).filter((tab) => tab.type === "page");
                 return {
-                    content: [{ type: "text", text: items.map((tab) => `${tab.targetId} ${tab.title} ${tab.url}`).join("\n") || "No browser pages are open." }],
+                    content: [{ type: "text", text: tabSummary(items) }],
                     details: { tabs: items },
                 };
             },
@@ -162,17 +456,24 @@ export default {
             label: "Browser navigate",
             description: "Navigate a connected browser tab to an HTTP or HTTPS URL.",
             promptSnippet: "navigate the connected browser tab",
-            parameters: Type.Object({ targetId: Type.String(), url: Type.String() }),
-            async execute(_toolCallId, params) {
-                const url = new URL(params.url);
-                if (url.protocol !== "http:" && url.protocol !== "https:")
-                    throw new Error("Browser navigation only supports http and https URLs");
-                const tab = await getTab(params.targetId);
-                await cdp(tab, "Page.enable");
-                await cdp(tab, "Page.navigate", { url: url.toString() });
-                await ready(endpoint, { ...tab, url: url.toString() });
-                latest = { targetId: tab.targetId, url: url.toString(), title: tab.title };
-                return { content: [{ type: "text", text: `Navigated to ${url.toString()}` }], details: { ...latest, status: "navigated" } };
+            parameters: Type.Object({
+                targetId: Type.String({ minLength: 1, maxLength: maxTargetIdLength }),
+                url: Type.String({ minLength: 1, maxLength: maxNavigationUrlLength }),
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const actionSignal = executionSignal(signal);
+                const raw = inspectParameters(params, navigationParameterNames);
+                const targetId = browserTargetId(raw.targetId);
+                const url = navigationUrl(raw.url);
+                const tab = await getTab(targetId, actionSignal);
+                await cdp(tab, "Page.enable", undefined, actionSignal);
+                const navigation = await cdp(tab, "Page.navigate", { url: url.toString() }, actionSignal);
+                if (typeof navigation.errorText === "string" && navigation.errorText !== "")
+                    throw new Error(`Browser navigation failed: ${navigation.errorText}`);
+                await ready({ ...tab, url: url.toString() }, actionSignal);
+                latest = { targetId: tab.targetId, url: url.toString(), title: tab.title, status: "navigated" };
+                return { content: [{ type: "text", text: `Navigated to ${url.toString()}` }], details: structuredClone(latest) };
             },
         }));
         const unregisterRead = context.piTools.register(defineTool({
@@ -180,15 +481,18 @@ export default {
             label: "Browser read",
             description: "Read bounded visible text from a connected browser tab.",
             promptSnippet: "read visible text from the connected browser tab",
-            parameters: Type.Object({ targetId: Type.String() }),
-            async execute(_toolCallId, params) {
-                const tab = await getTab(params.targetId);
-                const value = await evaluate(tab, "document.body?.innerText ?? ''");
+            parameters: Type.Object({ targetId: Type.String({ minLength: 1, maxLength: maxTargetIdLength }) }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const actionSignal = executionSignal(signal);
+                const raw = inspectParameters(params, targetParameterNames);
+                const targetId = browserTargetId(raw.targetId);
+                const tab = await getTab(targetId, actionSignal);
+                const value = await evaluate(tab, "document.body?.innerText ?? ''", actionSignal);
                 const text = typeof value === "string" ? value : "";
-                const bytes = Buffer.byteLength(text, "utf8");
-                const bounded = Buffer.from(text, "utf8").subarray(0, maxTextBytes).toString("utf8");
-                latest = { targetId: tab.targetId, url: tab.url, title: tab.title, text: bounded };
-                return { content: [{ type: "text", text: bounded }], details: { ...latest, truncated: bytes > maxTextBytes } };
+                const bounded = boundedUtf8(text, maxTextBytes);
+                latest = { targetId: tab.targetId, url: tab.url, title: tab.title, status: "read", ...bounded };
+                return { content: [{ type: "text", text: bounded.text }], details: structuredClone(latest) };
             },
         }));
         const unregisterClick = context.piTools.register(defineTool({
@@ -196,17 +500,23 @@ export default {
             label: "Browser click",
             description: "Click one visible HTML element in a connected browser tab by CSS selector.",
             promptSnippet: "click a page element in the connected browser",
-            parameters: Type.Object({ targetId: Type.String(), selector: Type.String() }),
-            async execute(_toolCallId, params) {
-                if (params.selector.length === 0 || params.selector.length > maxSelectorLength)
-                    throw new Error("Browser selector must be between 1 and 512 characters");
-                const tab = await getTab(params.targetId);
-                const selector = JSON.stringify(params.selector);
-                const value = await evaluate(tab, `(() => { const element = document.querySelector(${selector}); if (!(element instanceof HTMLElement)) throw new Error('Element was not found'); element.click(); return true; })()`);
+            parameters: Type.Object({
+                targetId: Type.String({ minLength: 1, maxLength: maxTargetIdLength }),
+                selector: Type.String({ minLength: 1, maxLength: maxSelectorLength }),
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const actionSignal = executionSignal(signal);
+                const raw = inspectParameters(params, clickParameterNames);
+                const targetId = browserTargetId(raw.targetId);
+                const rawSelector = browserSelector(raw.selector);
+                const tab = await getTab(targetId, actionSignal);
+                const selector = JSON.stringify(rawSelector);
+                const value = await evaluate(tab, `(() => { const element = document.querySelector(${selector}); if (!(element instanceof HTMLElement)) throw new Error('Element was not found'); element.click(); return true; })()`, actionSignal);
                 if (value !== true)
                     throw new Error("Browser click did not complete");
                 latest = { targetId: tab.targetId, url: tab.url, title: tab.title, clicked: true };
-                return { content: [{ type: "text", text: `Clicked ${params.selector}` }], details: latest };
+                return { content: [{ type: "text", text: `Clicked ${rawSelector}` }], details: structuredClone(latest) };
             },
         }));
         const unregisterScreenshot = context.piTools.register(defineTool({
@@ -214,45 +524,74 @@ export default {
             label: "Browser screenshot",
             description: "Capture the visible viewport of a connected browser tab as PNG.",
             promptSnippet: "capture a screenshot of the connected browser tab",
-            parameters: Type.Object({ targetId: Type.String() }),
-            async execute(_toolCallId, params) {
-                const tab = await getTab(params.targetId);
-                const result = await cdp(tab, "Page.captureScreenshot", { format: "png" });
+            parameters: Type.Object({ targetId: Type.String({ minLength: 1, maxLength: maxTargetIdLength }) }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const actionSignal = executionSignal(signal);
+                const raw = inspectParameters(params, targetParameterNames);
+                const targetId = browserTargetId(raw.targetId);
+                const tab = await getTab(targetId, actionSignal);
+                const result = await cdp(tab, "Page.captureScreenshot", { format: "png" }, actionSignal);
                 const data = typeof result.data === "string" ? result.data : "";
                 if (data === "")
                     throw new Error("Chrome DevTools returned an empty screenshot");
-                latest = { targetId: tab.targetId, url: tab.url, title: tab.title, screenshot: { data, mimeType: "image/png" } };
-                return { content: [{ type: "image", data, mimeType: "image/png" }], details: latest };
+                const screenshotBytes = Buffer.byteLength(data, "base64");
+                if (screenshotBytes > maxScreenshotBytes)
+                    throw new Error("Chrome DevTools screenshot exceeded the 8 MiB limit");
+                if (data.length % 4 !== 0 || !/^[a-z0-9+/]*={0,2}$/iu.test(data))
+                    throw new Error("Chrome DevTools returned invalid base64 screenshot data");
+                latest = { targetId: tab.targetId, url: tab.url, title: tab.title, screenshot: { bytes: screenshotBytes, mimeType: "image/png" } };
+                return { content: [{ type: "image", data, mimeType: "image/png" }], details: structuredClone(latest) };
             },
         }));
-        const disposePanel = context.piPluginUi.register({
-            id: "browser-session-panel",
-            pluginId: "@pi-harness/core/plugins/browser-session",
-            title: "Browser Session",
-            description: "通过 Chrome DevTools Protocol 连接已启动的本地浏览器。",
-            icon: "◉",
-            read: async () => {
-                try {
-                    return {
-                        endpoint: endpoint.toString(),
-                        tabs: (await listTabs()).filter((tab) => tab.type === "page").map((tab) => ({ targetId: tab.targetId, title: tab.title, url: tab.url })),
-                        latest: latest ?? null,
-                        connected: true,
-                        error: null,
-                    };
-                }
-                catch (error) {
-                    return {
-                        endpoint: endpoint.toString(),
-                        tabs: [],
-                        latest: latest ?? null,
-                        connected: false,
-                        error: error instanceof Error ? error.message : String(error),
-                    };
-                }
-            },
-        });
+        let disposePanel = () => undefined;
+        try {
+            disposePanel = context.piPluginUi.register({
+                id: "browser-session-panel",
+                pluginId: "@pi-harness/core/plugins/browser-session",
+                title: "Browser Session",
+                description: "通过 Chrome DevTools Protocol 连接已启动的本地浏览器。",
+                icon: "◉",
+                read: async () => {
+                    try {
+                        const pages = (await listTabs(lifecycle.signal)).filter((tab) => tab.type === "page");
+                        const panelTabs = pages.slice(0, maxPanelTabs).map((tab) => ({ targetId: tab.targetId, title: tab.title, url: tab.url }));
+                        return {
+                            endpoint: endpoint.toString(),
+                            tabs: panelTabs,
+                            inventory: { total: pages.length, shown: panelTabs.length, truncated: pages.length > panelTabs.length },
+                            limits: panelLimits,
+                            latest: panelLatest(),
+                            connected: true,
+                            error: null,
+                        };
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return {
+                            endpoint: endpoint.toString(),
+                            tabs: [],
+                            inventory: { total: 0, shown: 0, truncated: false },
+                            limits: panelLimits,
+                            latest: panelLatest(),
+                            connected: false,
+                            error: message.slice(0, maxPanelErrorChars),
+                        };
+                    }
+                },
+            });
+        }
+        catch (error) {
+            unregisterTabs();
+            unregisterNavigate();
+            unregisterRead();
+            unregisterClick();
+            unregisterScreenshot();
+            lifecycle.abort(new Error("Browser session plugin registration failed"));
+            throw error;
+        }
         context.effect(() => () => {
+            lifecycle.abort(new Error("Browser session plugin disposed"));
             unregisterTabs();
             unregisterNavigate();
             unregisterRead();