@nexface/tools 0.1.15-alpha.1 → 0.1.15-alpha.3

package/dist/operation-surface.js

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { flushSync } from "react-dom";
-import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import { useCallback, useLayoutEffect, useRef, useState, } from "react";
 import { useSyncExternalStore } from "use-sync-external-store/shim";
 import { PageCommandError } from "./browser/locator.js";
 import { getInternalToolRuntime } from "./runtime.js";
@@ -9,7 +9,8 @@ import { isAgentActivation } from "./browser/focus.js";
 import { OperationOverlayView } from "./operation-view.js";
 const BROWSER_TOOL_NAMES = new Set(["nxf_getSnapshot", "nxf_executeAction", "nxf_applyAction"]);
 const belongsToOperation = (event, operation) => !operation || event.operationId === operation.id;
-const canPresentInOperation = (event, operation) => belongsToOperation(event, operation) && (!operation || operation.status === "running" || operation.status === "ending");
+const canPresentInOperation = (event, operation) => belongsToOperation(event, operation) &&
+    (!operation || operation.status === "running" || operation.status === "ending");
 const surfaces = new WeakSet();
 export function AgentOperationSurface(props) {
     const element = useRef(null);
@@ -21,28 +22,34 @@ export function AgentOperationSurface(props) {
         if (surfaces.has(props.toolRuntime))
             throw new Error("Only one AgentOperationSurface is supported per Runtime.");
         surfaces.add(props.toolRuntime);
-        return () => { surfaces.delete(props.toolRuntime); };
+        return () => {
+            surfaces.delete(props.toolRuntime);
+        };
     }, [props.toolRuntime]);
     const blockUserInput = useCallback((event) => {
         if ((event.type === "submit" || event.type === "reset") && isAgentActivation())
             return;
-        if (!element.current || !isOperationSurfaceLocked(element.current) || !event.nativeEvent.isTrusted)
+        if (!element.current ||
+            !isOperationSurfaceLocked(element.current) ||
+            !event.nativeEvent.isTrusted)
             return;
         event.preventDefault();
         event.stopPropagation();
     }, []);
     const blockPassiveUserInput = useCallback((event) => {
-        if (!element.current || !isOperationSurfaceLocked(element.current) || !event.nativeEvent.isTrusted)
+        if (!element.current ||
+            !isOperationSurfaceLocked(element.current) ||
+            !event.nativeEvent.isTrusted)
             return;
         // Stop React's capture dispatch, but let the native event reach our non-passive
         // surface listener. React's passive root listener cannot prevent scrolling.
         event.isPropagationStopped = () => true;
     }, []);
-    return React.createElement(React.Fragment, null,
+    return (React.createElement(React.Fragment, null,
         React.createElement("div", { ref: element, className: "nexface-operation-surface", onClickCapture: blockUserInput, onDoubleClickCapture: blockUserInput, onAuxClickCapture: blockUserInput, onPointerDownCapture: blockUserInput, onPointerUpCapture: blockUserInput, onPointerMoveCapture: blockUserInput, onPointerOverCapture: blockUserInput, onPointerOutCapture: blockUserInput, onMouseDownCapture: blockUserInput, onMouseUpCapture: blockUserInput, onContextMenuCapture: blockUserInput, onMouseMoveCapture: blockUserInput, onMouseOverCapture: blockUserInput, onMouseOutCapture: blockUserInput, onWheelCapture: blockPassiveUserInput, onTouchStartCapture: blockPassiveUserInput, onTouchMoveCapture: blockPassiveUserInput, onTouchEndCapture: blockUserInput, onTouchCancelCapture: blockUserInput, onKeyDownCapture: blockUserInput, onKeyUpCapture: blockUserInput, onKeyPressCapture: blockUserInput, onBeforeInputCapture: blockUserInput, onPasteCapture: blockUserInput, onCutCapture: blockUserInput, onDropCapture: blockUserInput, onDragStartCapture: blockUserInput, onSubmitCapture: blockUserInput, onResetCapture: blockUserInput }, props.children),
-        React.createElement(OperationSurfaceContent, { ...props, element: element }));
+        React.createElement(OperationSurfaceContent, { ...props, element: element })));
 }
-function OperationSurfaceContent({ toolRuntime, element }) {
+function OperationSurfaceContent({ toolRuntime, element, }) {
     const runtime = getInternalToolRuntime(toolRuntime);
     const activity = useSyncExternalStore(runtime.subscribeActivity, runtime.getActivitySnapshot, runtime.getActivitySnapshot);
     const cycle = activity.operation;
@@ -58,15 +65,24 @@ function OperationSurfaceContent({ toolRuntime, element }) {
     useLayoutEffect(() => runtime.setPageActionFeedback((event, feedback, signal) => {
         const operation = runtime.getActivitySnapshot().operation;
         if (signal?.aborted || !canPresentInOperation(event, operation))
-            throw new PageCommandError({ code: "EXECUTION_CANCELLED", message: "Page action presentation was interrupted." });
+            throw new PageCommandError({
+                code: "EXECUTION_CANCELLED",
+                message: "Page action presentation was interrupted.",
+            });
         const target = feedback.target;
-        if (!feedback.effect || (feedback.effect === "action" && (!target?.isConnected || !element.current?.contains(target)))) {
+        if (!feedback.effect ||
+            (feedback.effect === "action" &&
+                (!target?.isConnected || !element.current?.contains(target)))) {
             setVisual(undefined);
             return;
         }
         const next = {
-            id: crypto.randomUUID(), effect: feedback.effect, label: label(event),
-            centered: feedback.effect === "read", persistentCursor: true, requiresTarget: feedback.effect === "action",
+            id: crypto.randomUUID(),
+            effect: feedback.effect,
+            label: label(event),
+            centered: feedback.effect === "read",
+            persistentCursor: true,
+            requiresTarget: feedback.effect === "action",
             ...(target ? { target } : {}),
         };
         if (feedback.effect !== "action") {
@@ -98,32 +114,61 @@ function OperationSurfaceContent({ toolRuntime, element }) {
             const page = BROWSER_TOOL_NAMES.has(event.name);
             if (canDisplay && event.status === "running") {
                 if (page)
-                    setVisual(event.name === "nxf_getSnapshot" ? { event, feedback: {
-                            id: event.id, effect: "read", label: label(event), centered: true,
-                        } } : undefined);
+                    setVisual(event.name === "nxf_getSnapshot"
+                        ? {
+                            event,
+                            feedback: {
+                                id: event.id,
+                                effect: "read",
+                                label: label(event),
+                                centered: true,
+                            },
+                        }
+                        : undefined);
                 else {
-                    const target = event.tool.definition.effect === "navigate" ? element.current : runtime.resolveTarget(event.tool, event.input);
+                    const target = event.tool.definition.effect === "navigate"
+                        ? element.current
+                        : runtime.resolveTarget(event.tool, event.input);
                     if (target?.isConnected && element.current?.contains(target)) {
                         const rect = target.getBoundingClientRect();
-                        setVisual({ event, feedback: { id: event.id, effect: event.tool.definition.effect ?? "action", label: label(event),
-                                resolveTarget: () => event.tool.definition.effect === "navigate" ? element.current ?? undefined : runtime.resolveTarget(event.tool, event.input),
-                                position: { left: rect.left + rect.width / 2, top: rect.top + rect.height / 2 } } });
+                        setVisual({
+                            event,
+                            feedback: {
+                                id: event.id,
+                                effect: event.tool.definition.effect ?? "action",
+                                label: label(event),
+                                resolveTarget: () => event.tool.definition.effect === "navigate"
+                                    ? (element.current ?? undefined)
+                                    : runtime.resolveTarget(event.tool, event.input),
+                                position: { left: rect.left + rect.width / 2, top: rect.top + rect.height / 2 },
+                            },
+                        });
                     }
                 }
             }
             else if (canDisplay)
                 setVisual((current) => current?.event.id === event.id && current.event.operationId === event.operationId
-                    ? page ? undefined : { ...current, event } : current);
+                    ? page
+                        ? undefined
+                        : { ...current, event }
+                    : current);
             if (page && !operation && event.status === "error")
                 setOutcome({ id: scope, status: event.cancelled ? "cancelled" : "failed" });
             setHistory((current) => {
-                if (!belongsToOperation(event, operation) || (event.status !== "running" && current.scope !== scope))
+                if (!belongsToOperation(event, operation) ||
+                    (event.status !== "running" && current.scope !== scope))
                     return current;
                 const entries = current.scope === scope ? current.entries : [];
-                const entry = { toolCallId: event.id,
-                    progressLabel: `${event.progressLabel || "正在处理你的请求"} · ${event.cancelled ? "已取消" : event.status === "running" ? "执行中" : event.status === "success" ? "已完成" : "失败"}` };
-                return { scope, entries: entries.some((item) => item.toolCallId === event.id)
-                        ? entries.map((item) => item.toolCallId === event.id ? entry : item) : [...entries, entry] };
+                const entry = {
+                    toolCallId: event.id,
+                    progressLabel: `${event.progressLabel || "正在处理你的请求"} · ${event.cancelled ? "已取消" : event.status === "running" ? "执行中" : event.status === "success" ? "已完成" : "失败"}`,
+                };
+                return {
+                    scope,
+                    entries: entries.some((item) => item.toolCallId === event.id)
+                        ? entries.map((item) => (item.toolCallId === event.id ? entry : item))
+                        : [...entries, entry],
+                };
             });
         };
         const unsubscribe = toolRuntime.on("toolexecution", onExecution);
@@ -136,25 +181,57 @@ function OperationSurfaceContent({ toolRuntime, element }) {
     const waiting = cycle?.status === "waiting" && !executing;
     const running = executing || (activated && cycle?.status !== "waiting");
     const stopping = cycle?.status === "cancelling";
-    useLayoutEffect(() => { if (!running || waiting)
-        setVisual(undefined); }, [running, waiting]);
+    useLayoutEffect(() => {
+        if (!running || waiting)
+            setVisual(undefined);
+    }, [running, waiting]);
     const serverExecuting = cycle?.taskProgress?.phase === "tool";
     const visualExecuting = Boolean(visual && activity.executions.some((event) => event.id === visual.event.id));
-    const currentVisual = !stopping && !waiting && visual
-        && (!serverExecuting || (BROWSER_TOOL_NAMES.has(visual.event.name) && visualExecuting))
-        && canPresentInOperation(visual.event, cycle) && (cycle || visualExecuting) ? visual : undefined;
+    const currentVisual = !stopping &&
+        !waiting &&
+        visual &&
+        (!serverExecuting || (BROWSER_TOOL_NAMES.has(visual.event.name) && visualExecuting)) &&
+        canPresentInOperation(visual.event, cycle) &&
+        (cycle || visualExecuting)
+        ? visual
+        : undefined;
     const browserExecution = activity.executions.find((event) => BROWSER_TOOL_NAMES.has(event.name));
-    const progressLabel = currentVisual?.feedback.label ?? (waiting ? "等待你完成操作" : stopping ? "正在终止"
-        : browserExecution ? browserExecution.progressLabel || "正在浏览网页"
-            : cycle?.taskProgress?.phase === "tool" ? cycle.taskProgress.progressLabel || "正在执行工具"
-                : cycle?.taskProgress ? "正在处理" : "正在处理你的请求");
-    const operation = { progressLabel, status: currentVisual
-            ? currentVisual.event.status === "running" ? "running" : currentVisual.event.status === "success" ? "completed" : "failed"
-            : running || waiting ? "running" : outcome?.id === history.scope ? outcome.status : "completed" };
-    const feedback = currentVisual?.feedback ?? (serverExecuting && running && !waiting && !stopping
-        ? { id: cycle.taskProgress.toolCallId, effect: "read", label: progressLabel, centered: true } : undefined);
+    const progressLabel = currentVisual?.feedback.label ??
+        (waiting
+            ? "等待你完成操作"
+            : stopping
+                ? "正在终止"
+                : browserExecution
+                    ? browserExecution.progressLabel || "正在浏览网页"
+                    : cycle?.taskProgress?.phase === "tool"
+                        ? cycle.taskProgress.progressLabel || "正在执行工具"
+                        : cycle?.taskProgress
+                            ? "正在处理"
+                            : "正在处理你的请求");
+    const operation = {
+        progressLabel,
+        status: currentVisual
+            ? currentVisual.event.status === "running"
+                ? "running"
+                : currentVisual.event.status === "success"
+                    ? "completed"
+                    : "failed"
+            : running || waiting
+                ? "running"
+                : outcome?.id === history.scope
+                    ? outcome.status
+                    : "completed",
+    };
+    const feedback = currentVisual?.feedback ??
+        (serverExecuting && running && !waiting && !stopping
+            ? {
+                id: cycle.taskProgress.toolCallId,
+                effect: "read",
+                label: progressLabel,
+                centered: true,
+            }
+            : undefined);
     const resolveSurface = useCallback(() => element.current ?? undefined, [element]);
     const entries = !cycle || history.scope === cycle.id ? history.entries : [];
-    return activated || executing || entries.length ? React.createElement(OperationOverlayView, { key: cycle?.id ?? history.scope, operation: operation, progressHistory: entries, running: running, humanHasControl: waiting, cancelling: stopping, ...(feedback ? { feedback } : {}), ...(cycle?.canCancel ? { onCancel: () => runtime.requestOperationCancel(cycle.id) } : {}), resolveSurface: resolveSurface }) : null;
+    return activated || executing || entries.length ? (React.createElement(OperationOverlayView, { key: cycle?.id ?? history.scope, operation: operation, progressHistory: entries, running: running, humanHasControl: waiting, cancelling: stopping, ...(feedback ? { feedback } : {}), ...(cycle?.canCancel ? { onCancel: () => runtime.requestOperationCancel(cycle.id) } : {}), resolveSurface: resolveSurface })) : null;
 }
-//# sourceMappingURL=operation-surface.js.map

package/dist/operation-types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=operation-types.js.map

package/dist/operation-view.d.ts

@@ -10,4 +10,4 @@ export interface OperationOverlayViewProps {
     onCancel?(): void;
     resolveSurface?(): HTMLElement | undefined;
 }
-export declare function OperationOverlayView({ operation, feedback, progressHistory, running, humanHasControl, cancelling, onCancel: cancel, resolveSurface }: OperationOverlayViewProps): React.ReactPortal | null;
+export declare function OperationOverlayView({ operation, feedback, progressHistory, running, humanHasControl, cancelling, onCancel: cancel, resolveSurface, }: OperationOverlayViewProps): React.ReactPortal | null;

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,9 +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);
 }
-//# sourceMappingURL=operation-view.js.map

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];
@@ -203,9 +201,7 @@ function isHTMLElement(value) {
     return ElementConstructor !== undefined && value instanceof ElementConstructor;
 }
 function warnAgentUIAction(message) {
-    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
-        console.warn(message);
-    }
+    console.warn(message);
 }
 const eventAdapters = {
     click: {
@@ -286,8 +282,8 @@ export function AgentUIAction({ name, description, event = "click", children, })
             if (warnedChildRef.current !== warningType) {
                 warnedChildRef.current = warningType;
                 warnAgentUIAction(isFragment
-                    ? `AgentUIAction "${name}" does not support React.Fragment children.`
-                    : `AgentUIAction "${name}" needs a child with onClick.`);
+                    ? `AgentUIAction "${name}" does not support React.Fragment children; the Tool is not registered.`
+                    : `AgentUIAction "${name}" needs a child with onClick; the Tool is not registered.`);
             }
             return;
         }
@@ -365,4 +361,3 @@ export function AgentUIAction({ name, description, event = "click", children, })
         ref: mergedRef,
     });
 }
-//# sourceMappingURL=react.js.map

package/dist/registration.js

@@ -1,15 +1,16 @@
 import { assertAgentToolInputSchema } from "./shared/schema.js";
 export function registerAgentTool(definition, options) {
     assertAgentToolRegistration(definition, options);
-    assertAgentToolInputSchema(definition.inputSchema, `Tool "${definition.name}".inputSchema`);
+    assertAgentToolInputSchema(definition.inputSchema, `Tool "${definition.name}" was not registered: inputSchema`);
     return Object.freeze({ definition, execute: options.execute });
 }
 export function assertAgentToolRegistration(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) {
         throw new TypeError("Registered Agent tools do not support requiresConfirmation.");
     }
 }
-//# sourceMappingURL=registration.js.map