@nexface/tools 0.1.13-alpha.3 → 0.1.13-alpha.5

package/dist/operation-view.js

@@ -1,13 +1,19 @@
 import { CursorIcon as Cursor } from "@phosphor-icons/react/Cursor";
 import { SparkleIcon as Sparkle } from "@phosphor-icons/react/Sparkle";
 import * as React from "react";
-import { useCallback, useLayoutEffect, useEffect, useRef, useState } from "react";
+import { useCallback, useLayoutEffect, useEffect, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
 import { PageCommandError } from "./browser/locator.js";
 import { lockOperationSurface } from "./operation-lock.js";
-const center = (rect) => ({ left: rect.left + rect.width / 2, top: rect.top + rect.height / 2 });
+const center = (rect) => ({
+    left: rect.left + rect.width / 2,
+    top: rect.top + rect.height / 2,
+});
 const distance = (a, b) => Math.hypot(a.left - b.left, a.top - b.top);
-const interrupted = () => new PageCommandError({ code: "EXECUTION_CANCELLED", message: "Page action presentation was interrupted." });
+const interrupted = () => new PageCommandError({
+    code: "EXECUTION_CANCELLED",
+    message: "Page action presentation was interrupted.",
+});
 function presentPointer(pointer, target, presentation) {
     let finished = false;
     const finish = (error) => {
@@ -19,45 +25,57 @@ function presentPointer(pointer, target, presentation) {
         presentation.signal?.removeEventListener("abort", onAbort);
         presentation.finish(error);
     };
-    const reached = () => pointer.isConnected && target.isConnected && distance(pointer.getBoundingClientRect(), center(target.getBoundingClientRect())) < 2;
+    const reached = () => pointer.isConnected &&
+        target.isConnected &&
+        distance(pointer.getBoundingClientRect(), center(target.getBoundingClientRect())) < 2;
     const onTransition = (event) => {
         if (event.target === pointer && event.propertyName === "transform" && reached())
             finish();
     };
     const onAbort = () => finish(interrupted());
-    const timer = setTimeout(() => reached() ? finish() : finish(new PageCommandError({
-        code: "ACTION_TIMEOUT", message: "Page action pointer did not reach its target in time.",
-    })), 750);
+    const timer = setTimeout(() => reached()
+        ? finish()
+        : finish(new PageCommandError({
+            code: "ACTION_TIMEOUT",
+            message: "Page action pointer did not reach its target in time.",
+        })), 750);
     pointer.addEventListener("transitionend", onTransition);
     presentation.signal?.addEventListener("abort", onAbort, { once: true });
-    queueMicrotask(() => { if (presentation.signal?.aborted)
-        onAbort();
-    else if (reached())
-        finish(); });
+    queueMicrotask(() => {
+        if (presentation.signal?.aborted)
+            onAbort();
+        else if (reached())
+            finish();
+    });
     return () => finish(interrupted());
 }
 function FeedbackLabel({ feedback }) {
-    return React.createElement("span", { className: "agent-operation__pointer-label", "data-browser-tool": feedback.centered ? "true" : undefined, "data-operation-effect": feedback.effect, title: feedback.label },
-        feedback.effect === "processing" ? React.createElement("span", { className: "agent-operation__pointer-processing" }) : null,
-        feedback.effect === "read" ? React.createElement("span", { className: "agent-operation__pointer-read-scan" },
+    return (React.createElement("span", { className: "agent-operation__pointer-label", "data-browser-tool": feedback.centered ? "true" : undefined, "data-operation-effect": feedback.effect, title: feedback.label },
+        feedback.effect === "processing" ? (React.createElement("span", { className: "agent-operation__pointer-processing" })) : null,
+        feedback.effect === "read" ? (React.createElement("span", { className: "agent-operation__pointer-read-scan" },
             React.createElement("i", null),
             React.createElement("i", null),
             React.createElement("i", null),
             React.createElement("i", null),
-            React.createElement("i", null)) : null,
-        feedback.effect === "navigate" ? React.createElement("span", { className: "agent-operation__pointer-navigation-trail" }) : null,
-        React.createElement("span", { className: "agent-operation__pointer-label-text" }, feedback.label));
+            React.createElement("i", null))) : null,
+        feedback.effect === "navigate" ? (React.createElement("span", { className: "agent-operation__pointer-navigation-trail" })) : null,
+        React.createElement("span", { className: "agent-operation__pointer-label-text" }, feedback.label)));
 }
-function FeedbackIndicator({ feedback, position }) {
+function FeedbackIndicator({ feedback, position, }) {
     const [lastPosition, setLastPosition] = useState(position ?? feedback.position);
-    useLayoutEffect(() => { if (position)
-        setLastPosition(position); }, [position?.left, position?.top]);
+    useLayoutEffect(() => {
+        if (position)
+            setLastPosition(position);
+    }, [position?.left, position?.top]);
     const current = position ?? lastPosition;
-    return current ? React.createElement("div", { "aria-hidden": true, className: "agent-operation__pointer-effect", "data-active": "true", "data-operation-effect": feedback.effect, style: { "--agent-operation-pointer-duration": "0ms", "--agent-operation-pointer-x": `${current.left}px`,
-            "--agent-operation-pointer-y": `${current.top}px` } },
-        React.createElement(FeedbackLabel, { feedback: feedback })) : null;
+    return current ? (React.createElement("div", { "aria-hidden": true, className: "agent-operation__pointer-effect", "data-active": "true", "data-operation-effect": feedback.effect, style: {
+            "--agent-operation-pointer-duration": "0ms",
+            "--agent-operation-pointer-x": `${current.left}px`,
+            "--agent-operation-pointer-y": `${current.top}px`,
+        } },
+        React.createElement(FeedbackLabel, { feedback: feedback }))) : null;
 }
-function AgentPointer({ active, feedback, targetPosition, surfaceCenter }) {
+function AgentPointer({ active, feedback, targetPosition, surfaceCenter, }) {
     const pointer = useRef(null);
     const [motion, setMotion] = useState();
     const action = feedback?.effect === "action" && (!feedback.requiresTarget || Boolean(targetPosition));
@@ -75,8 +93,11 @@ function AgentPointer({ active, feedback, targetPosition, surfaceCenter }) {
             return;
         }
         if (!motion) {
-            setMotion({ position: feedback?.persistentCursor && surfaceCenter ? surfaceCenter : targetPosition,
-                durationMs: 0, persistent: Boolean(feedback?.persistentCursor) });
+            setMotion({
+                position: feedback?.persistentCursor && surfaceCenter ? surfaceCenter : targetPosition,
+                durationMs: 0,
+                persistent: Boolean(feedback?.persistentCursor),
+            });
             return;
         }
         if (distance(motion.position, targetPosition) < 1) {
@@ -85,9 +106,14 @@ function AgentPointer({ active, feedback, targetPosition, surfaceCenter }) {
             return;
         }
         const from = pointer.current?.getBoundingClientRect() ?? motion.position;
-        const durationMs = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ? 0
+        const durationMs = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+            ? 0
             : Math.round(Math.min(360, Math.max(180, 180 + distance(from, targetPosition) * 0.18)));
-        setMotion({ position: targetPosition, durationMs, persistent: motion.persistent || Boolean(feedback?.persistentCursor) });
+        setMotion({
+            position: targetPosition,
+            durationMs,
+            persistent: motion.persistent || Boolean(feedback?.persistentCursor),
+        });
     }, [active, action, feedback?.id, targetPosition?.left, targetPosition?.top, motion]);
     const show = Boolean(active && motion && (motion.persistent || action));
     useLayoutEffect(() => {
@@ -100,18 +126,22 @@ function AgentPointer({ active, feedback, targetPosition, surfaceCenter }) {
         if (show && pointer.current)
             return presentPointer(pointer.current, feedback.target, feedback.presentation);
     }, [active, show, feedback?.presentation, feedback?.target, Boolean(targetPosition)]);
-    return show && motion ? React.createElement("div", { "aria-hidden": true, ref: pointer, className: "agent-operation__pointer-effect", "data-active": action, "data-operation-effect": action ? "action" : undefined, style: { "--agent-operation-pointer-duration": `${motion.durationMs}ms`,
-            "--agent-operation-pointer-x": `${motion.position.left}px`, "--agent-operation-pointer-y": `${motion.position.top}px` } },
+    return show && motion ? (React.createElement("div", { "aria-hidden": true, ref: pointer, className: "agent-operation__pointer-effect", "data-active": action, "data-operation-effect": action ? "action" : undefined, style: {
+            "--agent-operation-pointer-duration": `${motion.durationMs}ms`,
+            "--agent-operation-pointer-x": `${motion.position.left}px`,
+            "--agent-operation-pointer-y": `${motion.position.top}px`,
+        } },
         React.createElement("span", { className: "agent-operation__pointer-cursor" },
             React.createElement(Cursor, { className: "agent-operation__pointer", size: 24, weight: "fill" })),
-        action && feedback ? React.createElement(FeedbackLabel, { feedback: feedback }) : null) : null;
+        action && feedback ? React.createElement(FeedbackLabel, { feedback: feedback }) : null)) : null;
 }
-export function OperationOverlayView({ operation, feedback, progressHistory = [], running, humanHasControl = false, cancelling = false, onCancel: cancel, resolveSurface }) {
+export function OperationOverlayView({ operation, feedback, progressHistory = [], running, humanHasControl = false, cancelling = false, onCancel: cancel, resolveSurface, }) {
     const [, setGeometry] = useState("");
     const [historyOpen, setHistoryOpen] = useState(false);
     const [historyId] = useState(() => `nexface-operation-history-${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`}`);
     const cancelButtonRef = useRef(null);
-    const controllerShouldBeVisible = operation.status !== "cancelled" && (running || humanHasControl || operation.status === "failed");
+    const controllerShouldBeVisible = operation.status !== "cancelled" &&
+        (running || humanHasControl || operation.status === "failed");
     const [controllerVisibility, setControllerVisibility] = useState(controllerShouldBeVisible ? "visible" : undefined);
     useEffect(() => {
         if (controllerShouldBeVisible) {
@@ -119,12 +149,14 @@ export function OperationOverlayView({ operation, feedback, progressHistory = []
             return;
         }
         setHistoryOpen(false);
-        setControllerVisibility((current) => current ? "exiting" : undefined);
+        setControllerVisibility((current) => (current ? "exiting" : undefined));
         const timer = setTimeout(() => setControllerVisibility(undefined), 300);
         return () => clearTimeout(timer);
     }, [controllerShouldBeVisible]);
-    useEffect(() => { if (!progressHistory.length)
-        setHistoryOpen(false); }, [progressHistory.length]);
+    useEffect(() => {
+        if (!progressHistory.length)
+            setHistoryOpen(false);
+    }, [progressHistory.length]);
     useLayoutEffect(() => {
         const surface = resolveSurface?.();
         if (!surface || !running || humanHasControl)
@@ -144,17 +176,22 @@ export function OperationOverlayView({ operation, feedback, progressHistory = []
     useLayoutEffect(() => {
         const update = () => {
             const { surfaceRect, targetRect } = readGeometry();
-            const geometry = [surfaceRect, targetRect].map((rect) => {
+            const geometry = [surfaceRect, targetRect]
+                .map((rect) => {
                 if (!rect)
                     return "";
                 return [rect.left, rect.top, rect.width, rect.height].join(",");
-            }).join(";");
+            })
+                .join(";");
             setGeometry(geometry);
         };
         update();
         if (!running && !humanHasControl)
             return;
-        let frame = requestAnimationFrame(function track() { update(); frame = requestAnimationFrame(track); });
+        let frame = requestAnimationFrame(function track() {
+            update();
+            frame = requestAnimationFrame(track);
+        });
         return () => cancelAnimationFrame(frame);
     }, [readGeometry, operation, running, humanHasControl]);
     if (typeof document === "undefined")
@@ -170,29 +207,53 @@ export function OperationOverlayView({ operation, feedback, progressHistory = []
     const controllerExiting = controllerVisibility === "exiting";
     const controllerLabel = humanHasControl ? undefined : operation.progressLabel;
     const compactStatusLabel = humanHasControl ? "等待你完成操作" : operation.progressLabel;
-    const statusLabel = humanHasControl ? "等待你完成操作" : {
-        running: "Agent 正在控制", completed: running ? "工具已完成，任务继续中" : "操作已完成",
-        failed: running ? "Agent 正在处理错误" : "操作失败", cancelled: "任务已终止",
-    }[operation.status];
+    const statusLabel = humanHasControl
+        ? "等待你完成操作"
+        : {
+            running: "Agent 正在控制",
+            completed: running ? "工具已完成，任务继续中" : "操作已完成",
+            failed: running ? "Agent 正在处理错误" : "操作失败",
+            cancelled: "任务已终止",
+        }[operation.status];
     const targetPosition = rect ? center(rect) : undefined;
     return createPortal(React.createElement("div", { className: "agent-operation", "data-nexface-ignore": true, "data-feedback-active": operationFeedbackActive, "data-structured-target-lost": structuredTargetLost, "data-human-control": humanHasControl, "data-operation-effect": effect ?? "action", "data-run-active": running, "data-status": operation.status },
-        agentControlsSurface && surfaceRect ? React.createElement("div", { "aria-hidden": true, className: "agent-operation__surface", style: {
-                ...(highlightedRect ? { "--agent-operation-cutout-height": `${highlightedRect.height}px`,
-                    "--agent-operation-cutout-left": `${highlightedRect.left - surfaceRect.left}px`,
-                    "--agent-operation-cutout-top": `${highlightedRect.top - surfaceRect.top}px`, "--agent-operation-cutout-width": `${highlightedRect.width}px` } : {}),
-                height: surfaceRect.height, left: surfaceRect.left, top: surfaceRect.top, width: surfaceRect.width,
-            } }) : null,
-        activeFeedback && highlightedRect ? React.createElement("div", { "aria-hidden": true, className: "agent-operation__target", "data-operation-effect": effect, style: { height: highlightedRect.height, left: highlightedRect.left, top: highlightedRect.top, width: highlightedRect.width } }) : null,
+        agentControlsSurface && surfaceRect ? (React.createElement("div", { "aria-hidden": true, className: "agent-operation__surface", style: {
+                ...(highlightedRect
+                    ? {
+                        "--agent-operation-cutout-height": `${highlightedRect.height}px`,
+                        "--agent-operation-cutout-left": `${highlightedRect.left - surfaceRect.left}px`,
+                        "--agent-operation-cutout-top": `${highlightedRect.top - surfaceRect.top}px`,
+                        "--agent-operation-cutout-width": `${highlightedRect.width}px`,
+                    }
+                    : {}),
+                height: surfaceRect.height,
+                left: surfaceRect.left,
+                top: surfaceRect.top,
+                width: surfaceRect.width,
+            } })) : null,
+        activeFeedback && highlightedRect ? (React.createElement("div", { "aria-hidden": true, className: "agent-operation__target", "data-operation-effect": effect, style: {
+                height: highlightedRect.height,
+                left: highlightedRect.left,
+                top: highlightedRect.top,
+                width: highlightedRect.width,
+            } })) : null,
         React.createElement(AgentPointer, { active: agentControlsSurface && !cancelling, feedback: feedback?.presentation ? feedback : activeFeedback, targetPosition: targetPosition, surfaceCenter: surfaceRect ? center(surfaceRect) : undefined }),
-        activeFeedback && effect !== "action" && surfaceRect ? React.createElement(FeedbackIndicator, { key: activeFeedback.id, feedback: activeFeedback, position: activeFeedback.centered ? center(surfaceRect) : targetPosition }) : null,
-        controllerMounted ? React.createElement("section", { "aria-live": "polite", className: "agent-operation__controller", "data-visibility": controllerExiting ? "exiting" : "visible", style: surfaceRect ? { left: surfaceRect.left + surfaceRect.width / 2, right: "auto", "--agent-operation-controller-x": "-50%", maxWidth: Math.max(0, surfaceRect.width - 32) } : undefined },
-            historyOpen ? React.createElement("aside", { "aria-label": "\u672C\u6B21\u8FD0\u884C\u7684\u64CD\u4F5C\u8BB0\u5F55", className: "agent-operation__history", id: historyId },
+        activeFeedback && effect !== "action" && surfaceRect ? (React.createElement(FeedbackIndicator, { key: activeFeedback.id, feedback: activeFeedback, position: activeFeedback.centered ? center(surfaceRect) : targetPosition })) : null,
+        controllerMounted ? (React.createElement("section", { "aria-live": "polite", className: "agent-operation__controller", "data-visibility": controllerExiting ? "exiting" : "visible", style: surfaceRect
+                ? {
+                    left: surfaceRect.left + surfaceRect.width / 2,
+                    right: "auto",
+                    "--agent-operation-controller-x": "-50%",
+                    maxWidth: Math.max(0, surfaceRect.width - 32),
+                }
+                : undefined },
+            historyOpen ? (React.createElement("aside", { "aria-label": "\u672C\u6B21\u8FD0\u884C\u7684\u64CD\u4F5C\u8BB0\u5F55", className: "agent-operation__history", id: historyId },
                 React.createElement("header", null,
                     React.createElement("strong", null, "\u64CD\u4F5C\u8BB0\u5F55"),
                     React.createElement("span", null, progressHistory.length)),
-                React.createElement("ol", null, progressHistory.map(({ progressLabel: label, toolCallId }, index) => React.createElement("li", { key: toolCallId },
+                React.createElement("ol", null, progressHistory.map(({ progressLabel: label, toolCallId }, index) => (React.createElement("li", { key: toolCallId },
                     React.createElement("span", { "aria-hidden": true }, index + 1),
-                    React.createElement("p", null, label))))) : null,
+                    React.createElement("p", null, label))))))) : null,
             React.createElement("span", { "aria-hidden": true, className: "agent-operation__edge-flow" }),
             React.createElement("span", { "aria-hidden": true, className: "agent-operation__pause-mark" },
                 React.createElement("i", null),
@@ -204,8 +265,8 @@ export function OperationOverlayView({ operation, feedback, progressHistory = []
             React.createElement("div", null,
                 React.createElement("span", { className: "agent-operation__heading" },
                     React.createElement("strong", null, controllerLabel)),
-                statusLabel ? React.createElement("small", { className: "agent-operation__description" },
-                    React.createElement("span", { className: "agent-operation__status" }, statusLabel)) : null),
-            (running || humanHasControl) && operation.status !== "cancelled" ? React.createElement("span", { className: "agent-operation__compact-status", title: compactStatusLabel }, compactStatusLabel) : null,
-            cancel && (running || humanHasControl) && operation.status !== "cancelled" ? React.createElement("button", { ref: cancelButtonRef, className: "agent-operation__stop", type: "button", disabled: cancelling, onClick: cancel }, cancelling ? "正在终止" : "终止任务") : null) : null), document.body);
+                statusLabel ? (React.createElement("small", { className: "agent-operation__description" },
+                    React.createElement("span", { className: "agent-operation__status" }, statusLabel))) : null),
+            (running || humanHasControl) && operation.status !== "cancelled" ? (React.createElement("span", { className: "agent-operation__compact-status", title: compactStatusLabel }, compactStatusLabel)) : null,
+            cancel && (running || humanHasControl) && operation.status !== "cancelled" ? (React.createElement("button", { ref: cancelButtonRef, className: "agent-operation__stop", type: "button", disabled: cancelling, onClick: cancel }, cancelling ? "正在终止" : "终止任务")) : null)) : null), document.body);
 }

package/dist/react.js

@@ -3,7 +3,7 @@ import { Children, Fragment, cloneElement, useCallback, useEffect, useLayoutEffe
 import { defineAgentTool } from "./definition.js";
 import { getAgentNavigationEntries, } from "./navigation.js";
 import { AgentToolError, getInternalToolRuntime } from "./runtime.js";
-import { InternalToolRuntimeScope, useInternalToolRuntime, } from "./internal-react.js";
+import { InternalToolRuntimeScope, useInternalToolRuntime } from "./internal-react.js";
 import { connectToolRuntimeToWebMcp } from "./webmcp.js";
 const bindingInternals = new WeakMap();
 export function getAgentToolBindingInternals(binding) {
@@ -55,10 +55,10 @@ function createAgentToolBinding(toolName) {
 function useAgentBinding(definition, execute, options) {
     const runtime = useInternalToolRuntime();
     const confirmation = options.requiresConfirmation;
-    if (confirmation !== undefined
-        && (!confirmation
-            || typeof confirmation !== "object"
-            || (confirmation.mode !== "chat" && confirmation.mode !== "page"))) {
+    if (confirmation !== undefined &&
+        (!confirmation ||
+            typeof confirmation !== "object" ||
+            (confirmation.mode !== "chat" && confirmation.mode !== "page"))) {
         throw new Error("requiresConfirmation must explicitly use chat or page mode.");
     }
     const executeRef = useRef(execute);
@@ -82,9 +82,7 @@ export function useAgentTool(definition, execute, options = {}) {
     return useAgentBinding(definition, execute, options);
 }
 function getAgentNavigationExecutor(executors, key) {
-    if (!executors
-        || typeof executors !== "object"
-        || !Object.hasOwn(executors, key)) {
+    if (!executors || typeof executors !== "object" || !Object.hasOwn(executors, key)) {
         throw new Error(`Missing navigation executor: ${key}.`);
     }
     const executor = executors[key];

package/dist/registration.js

@@ -1,6 +1,8 @@
 import { assertAgentToolInputSchema } from "./shared/schema.js";
 export function registerAgentTool(definition, options) {
-    if (!definition || typeof definition.name !== "string" || typeof options?.execute !== "function") {
+    if (!definition ||
+        typeof definition.name !== "string" ||
+        typeof options?.execute !== "function") {
         throw new TypeError("registerAgentTool requires a definition and execute function.");
     }
     if ("requiresConfirmation" in options) {

package/dist/runtime.d.ts

@@ -14,7 +14,7 @@ export interface ToolRuntimeToolChangeEvent {
     readonly change: "registered" | "unregistered" | "visibility";
 }
 declare const CONTEXT_ERROR_CODES: readonly ["CONTEXT_DISPOSED", "CONTEXT_NAME_MISMATCH", "DUPLICATE_CONTEXT", "INVALID_CONTEXT"];
-type AgentContextErrorCode = typeof CONTEXT_ERROR_CODES[number];
+type AgentContextErrorCode = (typeof CONTEXT_ERROR_CODES)[number];
 export declare function isToolRuntimeError(error: unknown): error is {
     readonly type: "tool_runtime_error";
     readonly domain: "tool" | "context";

package/dist/runtime.js

@@ -2,13 +2,13 @@ import { searchNavigationTools, searchToolDefinition } from "./tool-search.js";
 import { pageDecisionSymbol } from "./shared/runtime-execution.js";
 import { PageCommandError } from "./browser/locator.js";
 import { measurePagePhase } from "./browser/diagnostics.js";
-import { runtimeControllerSymbol } from "./shared/runtime-controller.js";
+import { runtimeControllerSymbol, } from "./shared/runtime-controller.js";
 import { AgentToolError, TOOL_ERROR_CODES } from "./shared/errors.js";
 export { AgentToolError } from "./shared/errors.js";
 import { OperationTracker } from "./operation-runtime.js";
 import { isValidAgentContextName } from "./definition.js";
 import { assertAgentToolInputSchema, validateAgentToolInput } from "./shared/schema.js";
-import { createBrowserToolset, } from "./browser/toolset.js";
+import { createBrowserToolset } from "./browser/toolset.js";
 const CONTEXT_ERROR_CODES = [
     "CONTEXT_DISPOSED",
     "CONTEXT_NAME_MISMATCH",
@@ -21,9 +21,9 @@ export function isToolRuntimeError(error) {
     if (!error || typeof error !== "object")
         return false;
     const candidate = error;
-    if (candidate.type !== "tool_runtime_error"
-        || typeof candidate.message !== "string"
-        || typeof candidate.code !== "string") {
+    if (candidate.type !== "tool_runtime_error" ||
+        typeof candidate.message !== "string" ||
+        typeof candidate.code !== "string") {
         return false;
     }
     if (candidate.domain === "tool") {
@@ -44,9 +44,7 @@ function assertContextName(name) {
     }
 }
 function normalizeContextValue(value, path = "value", seen = new WeakSet()) {
-    if (value === null
-        || typeof value === "string"
-        || typeof value === "boolean") {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
         return value;
     }
     if (typeof value === "number") {
@@ -83,8 +81,8 @@ function normalizeContextValue(value, path = "value", seen = new WeakSet()) {
 }
 function normalizeContext(context) {
     assertContextName(context.name);
-    if (context.description !== undefined
-        && (typeof context.description !== "string" || !context.description.trim())) {
+    if (context.description !== undefined &&
+        (typeof context.description !== "string" || !context.description.trim())) {
         throw new AgentContextError("INVALID_CONTEXT", "Context description must be a non-empty string when provided.");
     }
     return {
@@ -139,16 +137,22 @@ export class ToolRuntimeImplementation extends EventTarget {
     beginInternalOperation(options = {}) {
         return this.#operations.begin(options);
     }
-    endBridgeOperation(handle) { return this.#operations.disposeBridge(handle); }
+    endBridgeOperation(handle) {
+        return this.#operations.disposeBridge(handle);
+    }
     setTaskProgress = (handle, progress) => this.#operations.setTaskProgress(handle, progress);
     setOperationWaiting = (handle, waiting) => this.#operations.setWaitingForUser(handle, waiting);
     getActivitySnapshot = () => this.#operations.getSnapshot();
     subscribeActivity = (listener) => this.#operations.subscribe(listener);
-    requestOperationCancel(id) { this.#operations.requestCancel(id); }
+    requestOperationCancel(id) {
+        this.#operations.requestCancel(id);
+    }
     setPageActionFeedback(listener) {
         this.#pageActionFeedback = listener;
-        return () => { if (this.#pageActionFeedback === listener)
-            this.#pageActionFeedback = undefined; };
+        return () => {
+            if (this.#pageActionFeedback === listener)
+                this.#pageActionFeedback = undefined;
+        };
     }
     #emitExecution(event) {
         this.#operations.observe(event);
@@ -156,8 +160,7 @@ export class ToolRuntimeImplementation extends EventTarget {
     }
     constructor(options = {}) {
         super();
-        if (options.pageAutomation !== undefined &&
-            typeof options.pageAutomation !== "boolean") {
+        if (options.pageAutomation !== undefined && typeof options.pageAutomation !== "boolean") {
             throw new AgentToolError("INVALID_INPUT", "pageAutomation must be a boolean.");
         }
         if (options.routeSearch !== undefined && typeof options.routeSearch !== "boolean") {
@@ -172,7 +175,9 @@ export class ToolRuntimeImplementation extends EventTarget {
                 if (searchQueries?.some((phrase) => typeof phrase !== "string" || !phrase.trim()))
                     throw new AgentToolError("INVALID_INPUT", "Search queries must contain nonblank strings.");
                 const navigation = this.getRegisteredTools().filter(({ definition }) => definition.effect === "navigate");
-                const candidates = searchQueries === undefined ? navigation : searchNavigationTools(navigation, searchQueries.map((phrase) => phrase.trim()));
+                const candidates = searchQueries === undefined
+                    ? navigation
+                    : searchNavigationTools(navigation, searchQueries.map((phrase) => phrase.trim()));
                 if (searchQueries !== undefined) {
                     const previous = this.#visibleNavigation;
                     this.#visibleNavigation = new Set(candidates);
@@ -185,7 +190,9 @@ export class ToolRuntimeImplementation extends EventTarget {
                         })));
                     }
                 }
-                return { tools: candidates.map(({ definition: { name, description } }) => ({ name, description })) };
+                return {
+                    tools: candidates.map(({ definition: { name, description } }) => ({ name, description })),
+                };
             });
         this.#browserToolset = options.pageAutomation ? createBrowserToolset() : undefined;
         runtimeInternals.set(this, this);
@@ -227,9 +234,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             definition,
             get confirmation() {
                 const confirmation = options.getConfirmation?.();
-                return confirmation === undefined
-                    ? undefined
-                    : Object.freeze({ ...confirmation });
+                return confirmation === undefined ? undefined : Object.freeze({ ...confirmation });
             },
             lifecycleSignal: lifecycleController.signal,
         });
@@ -238,9 +243,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             definition,
             runtimeTool,
             execute,
-            ...(options.getConfirmation
-                ? { getConfirmation: options.getConfirmation }
-                : {}),
+            ...(options.getConfirmation ? { getConfirmation: options.getConfirmation } : {}),
             lifecycleController,
         };
         this.#bindings.set(definition.name, binding);
@@ -378,7 +381,9 @@ export class ToolRuntimeImplementation extends EventTarget {
     getWebMcpTools() {
         return [...this.#bindings.values()]
             .map(({ runtimeTool }) => runtimeTool)
-            .filter((tool) => !this.#routeSearch || tool.definition.effect !== "navigate" || this.#visibleNavigation.has(tool))
+            .filter((tool) => !this.#routeSearch ||
+            tool.definition.effect !== "navigate" ||
+            this.#visibleNavigation.has(tool))
             .sort((left, right) => compareStrings(left.definition.name, right.definition.name));
     }
     isRegistered(name) {
@@ -386,10 +391,8 @@ export class ToolRuntimeImplementation extends EventTarget {
     }
     getTools() {
         const applicationTools = this.getWebMcpTools();
-        const browserTools = (this.#browserToolset?.definitions ?? [])
-            .map((definition) => this.#getBrowserRuntimeTool(definition));
-        return [...applicationTools, ...browserTools]
-            .sort((left, right) => compareStrings(left.definition.name, right.definition.name));
+        const browserTools = (this.#browserToolset?.definitions ?? []).map((definition) => this.#getBrowserRuntimeTool(definition));
+        return [...applicationTools, ...browserTools].sort((left, right) => compareStrings(left.definition.name, right.definition.name));
     }
     waitForTool(definition, options = {}) {
         const isTargetRegistered = () => this.#bindings.has(definition.name);
@@ -412,8 +415,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             };
             const onToolChange = (event) => {
                 const detail = event.detail;
-                if (detail?.toolName !== definition.name
-                    || detail.change !== "registered")
+                if (detail?.toolName !== definition.name || detail.change !== "registered")
                     return;
                 if (isTargetRegistered())
                     settle(resolve);
@@ -439,7 +441,11 @@ export class ToolRuntimeImplementation extends EventTarget {
     }
     execute(tool, input, options = {}) {
         const label = options.progressLabel?.trim().replace(/\s+/g, " ").slice(0, 48);
-        options = { ...(options.signal ? { signal: options.signal } : {}), ...(label ? { progressLabel: label } : {}), ...(options[pageDecisionSymbol] ? { [pageDecisionSymbol]: true } : {}) };
+        options = {
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(label ? { progressLabel: label } : {}),
+            ...(options[pageDecisionSymbol] ? { [pageDecisionSymbol]: true } : {}),
+        };
         const definition = tool.definition;
         const name = definition.name;
         const binding = this.#bindings.get(name);
@@ -455,8 +461,8 @@ export class ToolRuntimeImplementation extends EventTarget {
             if (!browserHandler) {
                 return Promise.reject(new AgentToolError("UNKNOWN_TOOL", `Unknown tool: ${name}.`));
             }
-            if (!browserToolset?.definitions.some((candidate) => candidate === definition)
-                || this.#getBrowserRuntimeTool(definition) !== tool) {
+            if (!browserToolset?.definitions.some((candidate) => candidate === definition) ||
+                this.#getBrowserRuntimeTool(definition) !== tool) {
                 return Promise.reject(new AgentToolError("CONTRACT_MISMATCH", `Tool "${name}" is registered with a different Definition.`));
             }
             return this.#enqueue((operationId) => this.#observeExecution(tool, input, options.signal, async (onFeedback, assertActive) => {
@@ -498,7 +504,9 @@ export class ToolRuntimeImplementation extends EventTarget {
         };
         // Reserve the tail before invoking executors or notifying synchronous listeners.
         let settleTail;
-        const tail = new Promise((resolve) => { settleTail = resolve; });
+        const tail = new Promise((resolve) => {
+            settleTail = resolve;
+        });
         this.#executionTail = tail;
         const queuedExecution = previous ? previous.then(start) : start();
         let execution = queuedExecution;
@@ -530,9 +538,13 @@ export class ToolRuntimeImplementation extends EventTarget {
             const target = binding.resolveTarget?.(input);
             return target?.isConnected ? target : undefined;
         }
-        if (this.#browserRuntimeTools.get(tool.definition) !== tool || !input || typeof input !== "object")
+        if (this.#browserRuntimeTools.get(tool.definition) !== tool ||
+            !input ||
+            typeof input !== "object")
             return undefined;
-        return this.#browserToolset?.handlers.get(tool.definition.name)?.resolveTarget?.(input);
+        return this.#browserToolset?.handlers
+            .get(tool.definition.name)
+            ?.resolveTarget?.(input);
     }
     async #observeExecution(tool, input, signal, execute, progressLabel, operationId) {
         const running = {
@@ -549,7 +561,10 @@ export class ToolRuntimeImplementation extends EventTarget {
         const assertActive = () => {
             signal?.throwIfAborted();
             if (presentation && this.#pageActionFeedback !== presentation) {
-                throw new PageCommandError({ code: "EXECUTION_CANCELLED", message: "Page action presentation was detached." });
+                throw new PageCommandError({
+                    code: "EXECUTION_CANCELLED",
+                    message: "Page action presentation was detached.",
+                });
             }
         };
         this.#emitExecution(running);
@@ -558,26 +573,33 @@ export class ToolRuntimeImplementation extends EventTarget {
             const result = await execute(async (feedback) => {
                 assertActive();
                 if (presentation)
-                    await measurePagePhase("presentation", async () => { await presentation(running, feedback, signal); });
+                    await measurePagePhase("presentation", async () => {
+                        await presentation(running, feedback, signal);
+                    });
                 assertActive();
             }, assertActive);
             signal?.throwIfAborted();
             this.#emitExecution({
-                ...running, status: "success", finishedAt: Date.now(), result,
+                ...running,
+                status: "success",
+                finishedAt: Date.now(),
+                result,
             });
             return result;
         }
         catch (error) {
             this.#emitExecution({
-                ...running, status: "error", cancelled: signal?.aborted === true,
-                finishedAt: Date.now(), error,
+                ...running,
+                status: "error",
+                cancelled: signal?.aborted === true,
+                finishedAt: Date.now(),
+                error,
             });
             throw error;
         }
     }
     async #executeApplication(name, input, options, binding, operationId) {
-        const id = globalThis.crypto?.randomUUID?.()
-            ?? `${Date.now()}-${Math.random()}`;
+        const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
         const startedAt = Date.now();
         const running = {
             ...(operationId ? { operationId } : {}),

package/dist/shared/errors.d.ts

@@ -1,5 +1,5 @@
 export declare const TOOL_ERROR_CODES: readonly ["EXECUTION_OUTCOME_UNKNOWN", "ACTION_IN_FLIGHT", "ACTION_NOT_HANDLED", "ACTION_TARGET_UNAVAILABLE", "BROWSER_EXECUTION_FAILED", "BROWSER_SNAPSHOT_REQUIRED", "BROWSER_TOOLS_UNAVAILABLE", "CONTRACT_MISMATCH", "DUPLICATE_BINDING", "INVALID_INPUT", "INVALID_TOOL_RUNTIME", "OPERATION_BUSY", "TOOL_CANCELLED", "TOOL_CONFIRMATION_INVALIDATED", "TOOL_CONFIRMATION_REJECTED", "TOOL_ERROR", "TOOL_REGISTRATION_TIMEOUT", "TOOL_SKIPPED", "TOOL_UNAVAILABLE", "UNKNOWN_TOOL"];
-type AgentToolErrorCode = typeof TOOL_ERROR_CODES[number];
+type AgentToolErrorCode = (typeof TOOL_ERROR_CODES)[number];
 export declare class AgentToolError extends Error {
     readonly code: AgentToolErrorCode;
     readonly details?: unknown | undefined;