@nexface/tools 0.1.1-alpha.0 → 0.1.1-alpha.10

package/dist/internal-types.d.ts

@@ -1,10 +1,19 @@
 import type { RuntimeAgentTool } from "./runtime.js";
+/**
+ * @experimental Status of an experimental execution notification.
+ * @beta
+ */
 export type AgentToolExecutionStatus = "running" | "success" | "error";
+/**
+ * @experimental Payload inferred by experimental execution listeners; not a named public export.
+ * @beta
+ */
 export interface AgentToolExecutionEvent {
     tool: RuntimeAgentTool<any, any>;
     cancelled?: boolean;
     progressLabel?: string;
     id: string;
+    operationId?: string;
     name: string;
     status: AgentToolExecutionStatus;
     startedAt: number;

package/dist/internal-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal-types.js","sourceRoot":"","sources":["../src/internal-types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"internal-types.js","sourceRoot":"","sources":["../src/internal-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { RuntimeAgentTool } from \"./runtime.js\";\n\n/**\n * @experimental Status of an experimental execution notification.\n * @beta\n */\nexport type AgentToolExecutionStatus = \"running\" | \"success\" | \"error\";\n\n/**\n * @experimental Payload inferred by experimental execution listeners; not a named public export.\n * @beta\n */\nexport interface AgentToolExecutionEvent {\n  tool: RuntimeAgentTool<any, any>;\n  cancelled?: boolean;\n  progressLabel?: string;\n  id: string;\n  operationId?: string;\n  name: string;\n  status: AgentToolExecutionStatus;\n  startedAt: number;\n  finishedAt?: number;\n  input: unknown;\n  result?: unknown;\n  error?: unknown;\n}\n"]}

package/dist/internal.d.ts

@@ -1,9 +1,10 @@
 export { AgentContextError, ToolRuntimeImplementation, ToolRuntimeImplementation as ToolRuntime, AgentToolError, createToolRuntime, getInternalToolRuntime, } from "./runtime.js";
-export type { ToolRuntime as PublicToolRuntime, ToolRuntimeOptions, InternalToolRuntime, } from "./runtime.js";
+export type { ToolRuntime as PublicToolRuntime, ToolRuntimeOptions, ToolOperation, InternalToolRuntime, } from "./runtime.js";
 export type { AgentToolExecutionEvent } from "./internal-types.js";
 export { defineSystemAgentTool } from "./definition.js";
 export { browserToolsAvailable, createBrowserToolset, executeCodeTool, getSnapshotTool, startPageTransitionTracker, } from "./browser/toolset.js";
 export { BROWSER_TOOLS_SKILL, serializeBrowserToolsSkill, } from "./browser/prompt.js";
-export type { BrowserToolHandler, BrowserToolsConfig, BrowserToolsOptions, BrowserToolset, PageTransitionSettleResult, PageTransitionTracker, } from "./browser/toolset.js";
+export type { BrowserToolHandler, PageAutomationOptions, BrowserToolset, PageTransitionSettleResult, PageTransitionTracker, } from "./browser/toolset.js";
 export type * from "./browser/types.js";
 export type { AgentContextRegistration } from "./types.js";
+export { assertAgentToolInputSchema, validateAgentToolInput } from "./schema.js";

package/dist/internal.js

@@ -2,4 +2,5 @@ export { AgentContextError, ToolRuntimeImplementation, ToolRuntimeImplementation
 export { defineSystemAgentTool } from "./definition.js";
 export { browserToolsAvailable, createBrowserToolset, executeCodeTool, getSnapshotTool, startPageTransitionTracker, } from "./browser/toolset.js";
 export { BROWSER_TOOLS_SKILL, serializeBrowserToolsSkill, } from "./browser/prompt.js";
+export { assertAgentToolInputSchema, validateAgentToolInput } from "./schema.js";
 //# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,yBAAyB,IAAI,WAAW,EACxC,cAAc,EACd,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAOtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,yBAAyB,IAAI,WAAW,EACxC,cAAc,EACd,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAQtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAW7B,OAAO,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC","sourcesContent":["export {\n  AgentContextError,\n  ToolRuntimeImplementation,\n  ToolRuntimeImplementation as ToolRuntime,\n  AgentToolError,\n  createToolRuntime,\n  getInternalToolRuntime,\n} from \"./runtime.js\";\nexport type {\n  ToolRuntime as PublicToolRuntime,\n  ToolRuntimeOptions,\n  ToolOperation,\n  InternalToolRuntime,\n} from \"./runtime.js\";\nexport type { AgentToolExecutionEvent } from \"./internal-types.js\";\nexport { defineSystemAgentTool } from \"./definition.js\";\nexport {\n  browserToolsAvailable,\n  createBrowserToolset,\n  executeCodeTool,\n  getSnapshotTool,\n  startPageTransitionTracker,\n} from \"./browser/toolset.js\";\nexport {\n  BROWSER_TOOLS_SKILL,\n  serializeBrowserToolsSkill,\n} from \"./browser/prompt.js\";\nexport type {\n  BrowserToolHandler,\n  PageAutomationOptions,\n  BrowserToolset,\n  PageTransitionSettleResult,\n  PageTransitionTracker,\n} from \"./browser/toolset.js\";\nexport type * from \"./browser/types.js\";\nexport type { AgentContextRegistration } from \"./types.js\";\n\nexport { assertAgentToolInputSchema, validateAgentToolInput } from \"./schema.js\";\n"]}

package/dist/navigation.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../src/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA6BlD,MAAM,wBAAwB,GAAG,UAAU,CAAC;AA4B5C,MAAM,iBAAiB,GAAG,IAAI,OAAO,EAGlC,CAAC;AAEJ,MAAM,UAAU,qBAAqB,CAGnC,MAOC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACjE,MAAM,IAAI,GAAG,GAAG,wBAAwB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QACxD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW;YAClC,CAAC,CAAC,eAAe,CAAiC;gBAC9C,IAAI;gBACJ,MAAM,EAAE,UAAU;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC;YACJ,CAAC,CAAC,eAAe,CAAwB;gBACrC,IAAI;gBACJ,MAAM,EAAE,UAAU;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC,CAAC;QACP,IAAI,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,mCAAmC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,GAAG;YACH,UAAU;SACX,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAwC,CAAC;IAC5E,iBAAiB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,UAAgC;IAEhC,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../src/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA6BlD,MAAM,wBAAwB,GAAG,UAAU,CAAC;AA4B5C,MAAM,iBAAiB,GAAG,IAAI,OAAO,EAGlC,CAAC;AAEJ,MAAM,UAAU,qBAAqB,CAGnC,MAOC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACjE,MAAM,IAAI,GAAG,GAAG,wBAAwB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QACxD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW;YAClC,CAAC,CAAC,eAAe,CAAiC;gBAC9C,IAAI;gBACJ,MAAM,EAAE,UAAU;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC;YACJ,CAAC,CAAC,eAAe,CAAwB;gBACrC,IAAI;gBACJ,MAAM,EAAE,UAAU;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC,CAAC;QACP,IAAI,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,mCAAmC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,GAAG;YACH,UAAU;SACX,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAwC,CAAC;IAC5E,iBAAiB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,UAAgC;IAEhC,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import { defineAgentTool } from \"./definition.js\";\nimport type {\n  AgentToolDefinition,\n  AgentToolExecutionContext,\n  AgentToolInputSchema,\n  InferJsonSchema,\n} from \"./types.js\";\n\nexport interface AgentNavigationResult {\n  status: \"navigated\";\n}\n\ndeclare const agentNavigationBrand: unique symbol;\n\nexport interface AgentNavigationRouteConfig {\n  name: string;\n  description: string;\n  inputSchema?: AgentToolInputSchema;\n}\n\nexport interface AgentNavigation<\n  TRoutes extends Record<string, AgentNavigationRouteConfig> = Record<\n    string,\n    AgentNavigationRouteConfig\n  >,\n> {\n  readonly [agentNavigationBrand]: TRoutes;\n}\n\nconst navigationToolNamePrefix = \"nxf_nav_\";\n\nexport interface AgentNavigationConfig<\n  TRoutes extends Record<string, AgentNavigationRouteConfig>,\n> {\n  routes: TRoutes;\n}\n\nexport type AgentNavigationExecutors<\n  TNavigation extends AgentNavigation,\n> = TNavigation extends AgentNavigation<infer TRoutes>\n  ? {\n      [TKey in keyof TRoutes]: (\n        input: TRoutes[TKey] extends {\n          readonly inputSchema: infer TSchema extends AgentToolInputSchema;\n        }\n          ? InferJsonSchema<TSchema>\n          : Record<string, never>,\n        context: AgentToolExecutionContext,\n      ) => void | Promise<void>;\n    }\n  : never;\n\ninterface InternalAgentNavigationRoute {\n  key: string;\n  definition: AgentToolDefinition<any, AgentNavigationResult>;\n}\n\nconst navigationEntries = new WeakMap<\n  AgentNavigation<any>,\n  readonly InternalAgentNavigationRoute[]\n>();\n\nexport function defineAgentNavigation<\n  const TRoutes extends Record<string, AgentNavigationRouteConfig>,\n>(\n  config: AgentNavigationConfig<TRoutes> & {\n    routes: {\n      [TKey in keyof TRoutes]: Record<\n        Exclude<keyof TRoutes[TKey], keyof AgentNavigationRouteConfig>,\n        never\n      >;\n    };\n  },\n): AgentNavigation<TRoutes> {\n  const names = new Set<string>();\n  const entries = Object.entries(config.routes).map(([key, route]) => {\n    const name = `${navigationToolNamePrefix}${route.name}`;\n    const definition = route.inputSchema\n      ? defineAgentTool<unknown, AgentNavigationResult>({\n          name,\n          effect: \"navigate\",\n          description: route.description,\n          inputSchema: route.inputSchema,\n        })\n      : defineAgentTool<AgentNavigationResult>({\n          name,\n          effect: \"navigate\",\n          description: route.description,\n        });\n    if (names.has(definition.name)) {\n      throw new Error(`Duplicate navigation tool name: ${definition.name}.`);\n    }\n    names.add(definition.name);\n    return Object.freeze({\n      key,\n      definition,\n    });\n  });\n  const navigation = Object.freeze({}) as unknown as AgentNavigation<TRoutes>;\n  navigationEntries.set(navigation, Object.freeze(entries));\n  return navigation;\n}\n\nexport function getAgentNavigationEntries(\n  navigation: AgentNavigation<any>,\n): readonly InternalAgentNavigationRoute[] {\n  const entries = navigationEntries.get(navigation);\n  if (!entries) {\n    throw new Error(\"Navigation must be created by defineAgentNavigation().\");\n  }\n  return entries;\n}\n"]}

package/dist/operation-lock.d.ts

@@ -0,0 +1,3 @@
+export declare function isOperationSurfaceLocked(surface: HTMLElement): boolean;
+/** Block user input inside the surface without hiding DOM from page tools. */
+export declare function lockOperationSurface(surface: HTMLElement, redirectFocus?: () => void): () => void;

package/dist/operation-lock.js

@@ -0,0 +1,46 @@
+import { isAgentFocus } from "./browser/focus.js";
+const lockedSurfaces = new WeakSet();
+export function isOperationSurfaceLocked(surface) {
+    return lockedSurfaces.has(surface);
+}
+/** Block user input inside the surface without hiding DOM from page tools. */
+export function lockOperationSurface(surface, redirectFocus) {
+    const previousBusy = surface.getAttribute("aria-busy");
+    const block = (event) => {
+        if (!event.isTrusted)
+            return;
+        if (event.type === "focus" || event.type === "focusin") {
+            if (isAgentFocus())
+                return;
+            event.stopImmediatePropagation();
+            if (event.target instanceof HTMLElement)
+                event.target.blur();
+            redirectFocus?.();
+            return;
+        }
+        if (event.type === "keydown" && event.key === "Tab") {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            redirectFocus?.();
+            return;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+    };
+    // Wheel and touch defaults are blocked here: React delegates them passively.
+    const events = ["focus", "focusin", "mouseenter", "mouseleave", "pointerenter", "pointerleave", "pointerdown", "pointerup", "pointermove", "pointerover", "pointerout", "mousedown", "mouseup", "mousemove", "mouseover", "mouseout", "click", "dblclick", "auxclick", "contextmenu", "keydown", "keyup", "beforeinput", "paste", "cut", "drop", "dragstart", "touchstart", "touchmove", "touchend", "touchcancel", "wheel", "submit", "reset"];
+    lockedSurfaces.add(surface);
+    surface.setAttribute("aria-busy", "true");
+    for (const name of events)
+        surface.addEventListener(name, block, { capture: true, passive: false });
+    return () => {
+        lockedSurfaces.delete(surface);
+        for (const name of events)
+            surface.removeEventListener(name, block, true);
+        if (previousBusy === null)
+            surface.removeAttribute("aria-busy");
+        else
+            surface.setAttribute("aria-busy", previousBusy);
+    };
+}
+//# sourceMappingURL=operation-lock.js.map

package/dist/operation-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.js","sourceRoot":"","sources":["../src/operation-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,cAAc,GAAG,IAAI,OAAO,EAAe,CAAC;AAElD,MAAM,UAAU,wBAAwB,CAAC,OAAoB;IAC3D,OAAO,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAAC,OAAoB,EAAE,aAA0B;IACnF,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,CAAC,KAAY,EAAE,EAAE;QAC7B,IAAI,CAAC,KAAK,CAAC,SAAS;YAAE,OAAO;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACvD,IAAI,YAAY,EAAE;gBAAE,OAAO;YAC3B,KAAK,CAAC,wBAAwB,EAAE,CAAC;YACjC,IAAI,KAAK,CAAC,MAAM,YAAY,WAAW;gBAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC7D,aAAa,EAAE,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAK,KAAuB,CAAC,GAAG,KAAK,KAAK,EAAE,CAAC;YACvE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,KAAK,CAAC,wBAAwB,EAAE,CAAC;YACjC,aAAa,EAAE,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QACD,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,KAAK,CAAC,wBAAwB,EAAE,CAAC;IACnC,CAAC,CAAC;IACF,6EAA6E;IAC7E,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChb,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,MAAM;QAAE,OAAO,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACpG,OAAO,GAAG,EAAE;QACV,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,MAAM;YAAE,OAAO,CAAC,mBAAmB,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1E,IAAI,YAAY,KAAK,IAAI;YAAE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;;YAC3D,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACvD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { isAgentFocus } from \"./browser/focus.js\";\n\nconst lockedSurfaces = new WeakSet<HTMLElement>();\n\nexport function isOperationSurfaceLocked(surface: HTMLElement): boolean {\n  return lockedSurfaces.has(surface);\n}\n\n/** Block user input inside the surface without hiding DOM from page tools. */\nexport function lockOperationSurface(surface: HTMLElement, redirectFocus?: () => void): () => void {\n  const previousBusy = surface.getAttribute(\"aria-busy\");\n  const block = (event: Event) => {\n    if (!event.isTrusted) return;\n    if (event.type === \"focus\" || event.type === \"focusin\") {\n      if (isAgentFocus()) return;\n      event.stopImmediatePropagation();\n      if (event.target instanceof HTMLElement) event.target.blur();\n      redirectFocus?.();\n      return;\n    }\n    if (event.type === \"keydown\" && (event as KeyboardEvent).key === \"Tab\") {\n      event.preventDefault();\n      event.stopImmediatePropagation();\n      redirectFocus?.();\n      return;\n    }\n    event.preventDefault();\n    event.stopImmediatePropagation();\n  };\n  // Wheel and touch defaults are blocked here: React delegates them passively.\n  const events = [\"focus\", \"focusin\", \"mouseenter\", \"mouseleave\", \"pointerenter\", \"pointerleave\", \"pointerdown\", \"pointerup\", \"pointermove\", \"pointerover\", \"pointerout\", \"mousedown\", \"mouseup\", \"mousemove\", \"mouseover\", \"mouseout\", \"click\", \"dblclick\", \"auxclick\", \"contextmenu\", \"keydown\", \"keyup\", \"beforeinput\", \"paste\", \"cut\", \"drop\", \"dragstart\", \"touchstart\", \"touchmove\", \"touchend\", \"touchcancel\", \"wheel\", \"submit\", \"reset\"];\n  lockedSurfaces.add(surface);\n  surface.setAttribute(\"aria-busy\", \"true\");\n  for (const name of events) surface.addEventListener(name, block, { capture: true, passive: false });\n  return () => {\n    lockedSurfaces.delete(surface);\n    for (const name of events) surface.removeEventListener(name, block, true);\n    if (previousBusy === null) surface.removeAttribute(\"aria-busy\");\n    else surface.setAttribute(\"aria-busy\", previousBusy);\n  };\n}\n"]}

package/dist/operation-runtime.d.ts

@@ -0,0 +1,44 @@
+import type { AgentToolExecutionEvent } from "./internal-types.js";
+import type { ToolOperation } from "./runtime.js";
+export type TaskProgress = {
+    readonly phase: "processing";
+} | {
+    readonly phase: "tool";
+    readonly toolCallId: string;
+    readonly progressLabel?: string;
+};
+export interface OperationSnapshot {
+    readonly taskProgress?: TaskProgress;
+    readonly id: string;
+    readonly source: "host" | "webmcp";
+    readonly status: "running" | "waiting" | "cancelling" | "ending";
+    readonly hasExecuted: boolean;
+    readonly hasStartedTool: boolean;
+    readonly outcome?: "completed" | "failed" | "cancelled";
+    readonly reason?: "bridge_disposed";
+    readonly canCancel: boolean;
+}
+export interface RuntimeActivitySnapshot {
+    readonly operation: OperationSnapshot | null;
+    readonly executions: readonly AgentToolExecutionEvent[];
+}
+export declare class OperationTracker {
+    #private;
+    getSnapshot: () => RuntimeActivitySnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    begin(options?: {
+        signal?: AbortSignal;
+        onCancel?: () => void;
+        source?: "host" | "webmcp";
+        replaceWaiting?: ToolOperation;
+        taskProgress?: TaskProgress;
+    }): ToolOperation;
+    setTaskProgress(handle: ToolOperation, progress: TaskProgress): void;
+    disposeBridge(handle: ToolOperation): Promise<void>;
+    requestCancel(id: string): void;
+    admit(): {
+        operationId?: string;
+        release(): void;
+    };
+    observe(event: AgentToolExecutionEvent): void;
+}

package/dist/operation-runtime.js

@@ -0,0 +1,153 @@
+import { AgentToolError } from "./errors.js";
+export class OperationTracker {
+    #operation;
+    #unscoped = 0;
+    #executions = new Map();
+    #listeners = new Set();
+    #snapshot = Object.freeze({ operation: null, executions: Object.freeze([]) });
+    getSnapshot = () => this.#snapshot;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    };
+    begin(options = {}) {
+        options.signal?.throwIfAborted();
+        const previous = this.#operation;
+        const replacing = previous && previous.handle === options.replaceWaiting
+            && previous.snapshot.status === "waiting" && previous.pending === 0;
+        if (this.#unscoped || (previous && !replacing)) {
+            throw new AgentToolError("OPERATION_BUSY", "The Runtime already has an operation or outstanding tool calls.");
+        }
+        if (replacing) {
+            previous.removeAbort();
+            previous.resolveEnd();
+        }
+        let resolveEnd;
+        const endPromise = new Promise((resolve) => { resolveEnd = resolve; });
+        const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
+        const operation = {
+            snapshot: Object.freeze({ id, source: options.source ?? "host", status: "running", hasExecuted: false, hasStartedTool: options.taskProgress?.phase === "tool", canCancel: Boolean(options.onCancel), ...(options.taskProgress ? { taskProgress: Object.freeze(options.taskProgress) } : {}) }),
+            handle: undefined, pending: 0, resolveEnd,
+            ...(options.onCancel ? { onCancel: options.onCancel } : {}),
+            removeAbort: () => options.signal?.removeEventListener("abort", onAbort),
+        };
+        const onAbort = () => {
+            if (this.#operation !== operation || operation.snapshot.status === "ending")
+                return;
+            this.#update(operation, { status: "cancelling" });
+        };
+        const handle = Object.freeze({
+            id,
+            setWaitingForUser: (waiting) => {
+                if (this.#operation !== operation || !["running", "waiting"].includes(operation.snapshot.status))
+                    return;
+                const status = waiting ? "waiting" : "running";
+                if (status !== operation.snapshot.status)
+                    this.#update(operation, { status });
+            },
+            end: (endOptions) => {
+                if (this.#operation !== operation || operation.snapshot.status === "ending")
+                    return endPromise;
+                operation.removeAbort();
+                operation.snapshot = Object.freeze({ ...operation.snapshot, status: "ending", outcome: endOptions?.outcome ?? "completed" });
+                this.#publish();
+                if (this.#finish(operation))
+                    this.#publish();
+                return endPromise;
+            },
+        });
+        operation.handle = handle;
+        this.#operation = operation;
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        this.#publish();
+        return handle;
+    }
+    setTaskProgress(handle, progress) {
+        const operation = this.#operation;
+        if (operation?.handle !== handle || operation.snapshot.status === "ending")
+            return;
+        this.#update(operation, {
+            taskProgress: Object.freeze(progress),
+            hasStartedTool: operation.snapshot.hasStartedTool || progress.phase === "tool",
+        });
+    }
+    disposeBridge(handle) {
+        const operation = this.#operation;
+        if (operation?.handle === handle)
+            operation.snapshot = Object.freeze({ ...operation.snapshot, reason: "bridge_disposed" });
+        return handle.end();
+    }
+    requestCancel(id) {
+        const operation = this.#operation;
+        if (!operation || operation.snapshot.id !== id || !operation.onCancel
+            || operation.snapshot.status === "ending" || operation.snapshot.status === "cancelling")
+            return;
+        const previous = operation.snapshot.status;
+        this.#update(operation, { status: "cancelling" });
+        try {
+            operation.onCancel();
+        }
+        catch (error) {
+            if (this.#operation === operation && this.#snapshot.operation?.status === "cancelling") {
+                this.#update(operation, { status: previous });
+            }
+            throw error;
+        }
+    }
+    // Admission is captured before execution and released exactly once, including queued aborts.
+    admit() {
+        const operation = this.#operation?.snapshot.status === "ending" ? undefined : this.#operation;
+        if (operation)
+            operation.pending += 1;
+        else
+            this.#unscoped += 1;
+        let released = false;
+        return {
+            ...(operation ? { operationId: operation.snapshot.id } : {}),
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                if (operation) {
+                    operation.pending -= 1;
+                    if (this.#finish(operation))
+                        this.#publish();
+                }
+                else
+                    this.#unscoped -= 1;
+            },
+        };
+    }
+    observe(event) {
+        if (event.status === "running") {
+            this.#executions.set(event.id, event);
+            const operation = this.#operation;
+            if (operation && event.operationId === operation.snapshot.id && !operation.snapshot.hasExecuted) {
+                operation.snapshot = Object.freeze({ ...operation.snapshot, hasExecuted: true });
+            }
+        }
+        else
+            this.#executions.delete(event.id);
+        this.#publish();
+    }
+    #finish(operation) {
+        if (operation.pending || operation.snapshot.status !== "ending" || this.#operation !== operation)
+            return false;
+        this.#operation = undefined;
+        operation.resolveEnd();
+        return true;
+    }
+    #update(operation, patch) {
+        operation.snapshot = Object.freeze({ ...operation.snapshot, ...patch });
+        this.#publish();
+    }
+    #publish() {
+        this.#snapshot = Object.freeze({
+            operation: this.#operation?.snapshot ?? null,
+            executions: Object.freeze([...this.#executions.values()]),
+        });
+        for (const listener of this.#listeners)
+            listener();
+    }
+}
+//# sourceMappingURL=operation-runtime.js.map

package/dist/operation-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-runtime.js","sourceRoot":"","sources":["../src/operation-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentToolExecutionEvent } from \"./internal-types.js\";\nimport { AgentToolError } from \"./errors.js\";\nimport type { ToolOperation } from \"./runtime.js\";\n\nexport type TaskProgress = { readonly phase: \"processing\" } | { readonly phase: \"tool\"; readonly toolCallId: string; readonly progressLabel?: string };\n\nexport interface OperationSnapshot {\n  readonly taskProgress?: TaskProgress;\n  readonly id: string;\n  readonly source: \"host\" | \"webmcp\";\n  readonly status: \"running\" | \"waiting\" | \"cancelling\" | \"ending\";\n  readonly hasExecuted: boolean;\n  readonly hasStartedTool: boolean;\n  readonly outcome?: \"completed\" | \"failed\" | \"cancelled\";\n  readonly reason?: \"bridge_disposed\";\n  readonly canCancel: boolean;\n}\n\nexport interface RuntimeActivitySnapshot {\n  readonly operation: OperationSnapshot | null;\n  readonly executions: readonly AgentToolExecutionEvent[];\n}\n\ntype Operation = {\n  snapshot: OperationSnapshot;\n  handle: ToolOperation;\n  pending: number;\n  onCancel?: () => void;\n  removeAbort(): void;\n  resolveEnd(): void;\n};\n\nexport class OperationTracker {\n  #operation: Operation | undefined;\n  #unscoped = 0;\n  #executions = new Map<string, AgentToolExecutionEvent>();\n  #listeners = new Set<() => void>();\n  #snapshot: RuntimeActivitySnapshot = Object.freeze({ operation: null, executions: Object.freeze([]) });\n\n  getSnapshot = (): RuntimeActivitySnapshot => this.#snapshot;\n  subscribe = (listener: () => void): (() => void) => {\n    this.#listeners.add(listener);\n    return () => { this.#listeners.delete(listener); };\n  };\n\n  begin(options: {\n    signal?: AbortSignal;\n    onCancel?: () => void;\n    source?: \"host\" | \"webmcp\";\n    replaceWaiting?: ToolOperation;\n    taskProgress?: TaskProgress;\n  } = {}): ToolOperation {\n    options.signal?.throwIfAborted();\n    const previous = this.#operation;\n    const replacing = previous && previous.handle === options.replaceWaiting\n      && previous.snapshot.status === \"waiting\" && previous.pending === 0;\n    if (this.#unscoped || (previous && !replacing)) {\n      throw new AgentToolError(\"OPERATION_BUSY\", \"The Runtime already has an operation or outstanding tool calls.\");\n    }\n    if (replacing) {\n      previous.removeAbort();\n      previous.resolveEnd();\n    }\n    let resolveEnd!: () => void;\n    const endPromise = new Promise<void>((resolve) => { resolveEnd = resolve; });\n    const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;\n    const operation: Operation = {\n      snapshot: Object.freeze({ id, source: options.source ?? \"host\", status: \"running\", hasExecuted: false, hasStartedTool: options.taskProgress?.phase === \"tool\", canCancel: Boolean(options.onCancel), ...(options.taskProgress ? { taskProgress: Object.freeze(options.taskProgress) } : {}) }),\n      handle: undefined!, pending: 0, resolveEnd,\n      ...(options.onCancel ? { onCancel: options.onCancel } : {}),\n      removeAbort: () => options.signal?.removeEventListener(\"abort\", onAbort),\n    };\n    const onAbort = () => {\n      if (this.#operation !== operation || operation.snapshot.status === \"ending\") return;\n      this.#update(operation, { status: \"cancelling\" });\n    };\n    const handle: ToolOperation = Object.freeze({\n      id,\n      setWaitingForUser: (waiting: boolean) => {\n        if (this.#operation !== operation || ![\"running\", \"waiting\"].includes(operation.snapshot.status)) return;\n        const status = waiting ? \"waiting\" : \"running\";\n        if (status !== operation.snapshot.status) this.#update(operation, { status });\n      },\n      end: (endOptions?: { outcome?: \"completed\" | \"failed\" | \"cancelled\" }) => {\n        if (this.#operation !== operation || operation.snapshot.status === \"ending\") return endPromise;\n        operation.removeAbort();\n        operation.snapshot = Object.freeze({ ...operation.snapshot, status: \"ending\", outcome: endOptions?.outcome ?? \"completed\" });\n        this.#publish();\n        if (this.#finish(operation)) this.#publish();\n        return endPromise;\n      },\n    });\n    operation.handle = handle;\n    this.#operation = operation;\n    options.signal?.addEventListener(\"abort\", onAbort, { once: true });\n    this.#publish();\n    return handle;\n  }\n\n  setTaskProgress(handle: ToolOperation, progress: TaskProgress): void {\n    const operation = this.#operation;\n    if (operation?.handle !== handle || operation.snapshot.status === \"ending\") return;\n    this.#update(operation, {\n      taskProgress: Object.freeze(progress),\n      hasStartedTool: operation.snapshot.hasStartedTool || progress.phase === \"tool\",\n    });\n  }\n\n  disposeBridge(handle: ToolOperation): Promise<void> {\n    const operation = this.#operation;\n    if (operation?.handle === handle) operation.snapshot = Object.freeze({ ...operation.snapshot, reason: \"bridge_disposed\" });\n    return handle.end();\n  }\n\n  requestCancel(id: string): void {\n    const operation = this.#operation;\n    if (!operation || operation.snapshot.id !== id || !operation.onCancel\n      || operation.snapshot.status === \"ending\" || operation.snapshot.status === \"cancelling\") return;\n    const previous = operation.snapshot.status;\n    this.#update(operation, { status: \"cancelling\" });\n    try {\n      operation.onCancel();\n    } catch (error) {\n      if (this.#operation === operation && this.#snapshot.operation?.status === \"cancelling\") {\n        this.#update(operation, { status: previous });\n      }\n      throw error;\n    }\n  }\n\n  // Admission is captured before execution and released exactly once, including queued aborts.\n  admit(): { operationId?: string; release(): void } {\n    const operation = this.#operation?.snapshot.status === \"ending\" ? undefined : this.#operation;\n    if (operation) operation.pending += 1;\n    else this.#unscoped += 1;\n    let released = false;\n    return {\n      ...(operation ? { operationId: operation.snapshot.id } : {}),\n      release: () => {\n        if (released) return;\n        released = true;\n        if (operation) {\n          operation.pending -= 1;\n          if (this.#finish(operation)) this.#publish();\n        } else this.#unscoped -= 1;\n      },\n    };\n  }\n\n  observe(event: AgentToolExecutionEvent): void {\n    if (event.status === \"running\") {\n      this.#executions.set(event.id, event);\n      const operation = this.#operation;\n      if (operation && event.operationId === operation.snapshot.id && !operation.snapshot.hasExecuted) {\n        operation.snapshot = Object.freeze({ ...operation.snapshot, hasExecuted: true });\n      }\n    } else this.#executions.delete(event.id);\n    this.#publish();\n  }\n\n  #finish(operation: Operation): boolean {\n    if (operation.pending || operation.snapshot.status !== \"ending\" || this.#operation !== operation) return false;\n    this.#operation = undefined;\n    operation.resolveEnd();\n    return true;\n  }\n\n  #update(operation: Operation, patch: Partial<OperationSnapshot>): void {\n    operation.snapshot = Object.freeze({ ...operation.snapshot, ...patch });\n    this.#publish();\n  }\n\n  #publish(): void {\n    this.#snapshot = Object.freeze({\n      operation: this.#operation?.snapshot ?? null,\n      executions: Object.freeze([...this.#executions.values()]),\n    });\n    for (const listener of this.#listeners) listener();\n  }\n}\n"]}

package/dist/operation-surface.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
-import type { ToolRuntime } from "./runtime.js";
+import { type ToolRuntime } from "./runtime.js";
 export interface AgentOperationSurfaceProps {
     toolRuntime: ToolRuntime;
     children: ReactNode;
 }
-export declare function AgentOperationSurface({ toolRuntime, children }: AgentOperationSurfaceProps): import("react").JSX.Element;
+export declare function AgentOperationSurface(props: AgentOperationSurfaceProps): import("react").JSX.Element;

package/dist/operation-surface.js

@@ -1,82 +1,127 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useLayoutEffect, useRef, useState } from "react";
-import { useOperationHost } from "./operation-host.js";
+import { useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { getInternalToolRuntime } from "./runtime.js";
+import { isOperationSurfaceLocked } from "./operation-lock.js";
 import { OperationOverlayView } from "./operation-view.js";
-export function AgentOperationSurface({ toolRuntime, children }) {
-    const chat = useOperationHost();
-    if (chat.toolRuntime !== toolRuntime)
-        throw new Error("AgentOperationSurface requires the NexfaceProvider Runtime.");
+const surfaces = new WeakSet();
+export function AgentOperationSurface(props) {
     const element = useRef(null);
-    const owner = useRef({});
-    const [visual, setVisual] = useState();
-    const [history, setHistory] = useState([]);
-    const activeExecutions = useRef(new Set());
-    const turn = chat.turnId;
-    const running = chat.running;
-    const waiting = chat.waiting && !running;
-    useLayoutEffect(() => {
-        if (chat.operationSurface.current)
-            throw new Error("Only one AgentOperationSurface is supported per NexfaceProvider.");
-        chat.operationSurface.current = owner.current;
-        return () => { chat.operationSurface.current = null; };
-    }, [chat.operationSurface]);
+    const initial = useRef(props.toolRuntime);
+    if (initial.current !== props.toolRuntime) {
+        throw new Error("AgentOperationSurface requires a stable Runtime. Remount it to change Runtime.");
+    }
     useLayoutEffect(() => {
-        setVisual(undefined);
-        setHistory([]);
-        activeExecutions.current.clear();
-    }, [turn]);
-    useLayoutEffect(() => toolRuntime.on("toolexecution", (event) => {
-        if (event.status === "running")
-            activeExecutions.current.add(event.id);
-        else if (!activeExecutions.current.delete(event.id))
+        if (surfaces.has(props.toolRuntime))
+            throw new Error("Only one AgentOperationSurface is supported per Runtime.");
+        surfaces.add(props.toolRuntime);
+        return () => { surfaces.delete(props.toolRuntime); };
+    }, [props.toolRuntime]);
+    const blockUserInput = useCallback((event) => {
+        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)
             return;
-        if (event.status === "running") {
-            setVisual({ event, target: toolRuntime.resolveTarget(event.tool, event.input) });
-        }
-        else {
-            setVisual((current) => current?.event.id === event.id
-                ? event.status === "success" && !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ? { ...current, event: { ...current.event, ...event } } : undefined
-                : current);
-        }
-        setHistory((entries) => {
-            const entry = {
-                toolCallId: event.id,
-                progressLabel: `${event.progressLabel || "正在处理你的请求"} · ${event.cancelled ? "已取消" : event.status === "running" ? "执行中" : event.status === "success" ? "已完成" : "失败"}`,
-            };
-            return entries.some((item) => item.toolCallId === event.id)
-                ? entries.map((item) => item.toolCallId === event.id ? entry : item)
-                : [...entries, entry];
+        // 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 _jsxs(_Fragment, { children: [_jsx("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, children: props.children }), _jsx(OperationSurfaceContent, { ...props, element: element })] });
+}
+function OperationSurfaceContent({ toolRuntime, element }) {
+    const runtime = getInternalToolRuntime(toolRuntime);
+    const activity = useSyncExternalStore(runtime.subscribeActivity, runtime.getActivitySnapshot, runtime.getActivitySnapshot);
+    const cycle = activity.operation;
+    const [outcome, setOutcome] = useState();
+    useLayoutEffect(() => runtime.subscribeActivity(() => {
+        const current = runtime.getActivitySnapshot().operation;
+        // Task progress does not replace page feedback. Only lifecycle boundaries clear it.
+        setVisual((visual) => {
+            if (current)
+                return current.status === "running" && visual?.event.operationId === current.id ? visual : undefined;
+            return visual && runtime.getActivitySnapshot().executions.some((event) => event.id === visual.event.id) ? visual : undefined;
         });
-    }), [toolRuntime]);
+        if (current?.status === "ending" && current.outcome)
+            setOutcome({ id: current.id, status: current.outcome });
+    }), [runtime]);
+    const [visual, setVisual] = useState();
+    const [history, setHistory] = useState({ scope: "", entries: [] });
+    useLayoutEffect(() => {
+        const onExecution = (event) => {
+            const scope = event.operationId ?? event.id;
+            const operation = runtime.getActivitySnapshot().operation;
+            const canDisplay = !event.operationId || (operation?.id === event.operationId && operation.status === "running");
+            if (canDisplay && event.status === "running") {
+                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, target, 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
+                    ? { ...current, event: { ...current.event, ...event } }
+                    : current);
+            }
+            setHistory((current) => {
+                if ((operation && event.operationId !== operation.id) || (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 unsubscribe = toolRuntime.on("toolexecution", onExecution);
+        for (const event of runtime.getActivitySnapshot().executions)
+            onExecution(event);
+        return unsubscribe;
+    }, [runtime, toolRuntime, element]);
+    const activated = Boolean(cycle && (cycle.hasStartedTool || cycle.source === "webmcp" || cycle.hasExecuted));
+    const executing = activity.executions.length > 0;
+    const waiting = cycle?.status === "waiting" && !executing;
+    const running = executing || (activated && cycle?.status !== "waiting");
+    const stopping = cycle?.status === "cancelling" || cycle?.status === "ending";
     useLayoutEffect(() => {
-        if (!running) {
+        if (!running || waiting)
             setVisual(undefined);
-        }
     }, [running, waiting]);
-    const resolveSurface = useCallback(() => element.current ?? undefined, []);
+    const currentVisual = !stopping && !waiting && visual && (cycle
+        ? cycle.status === "running" && visual.event.operationId === cycle.id
+        : activity.executions.some((event) => event.id === visual.event.id)) ? visual : undefined;
+    const resolveSurface = useCallback(() => element.current ?? undefined, [element]);
     const resolveTarget = useCallback(() => {
-        if (!visual)
+        if (!currentVisual)
             return undefined;
-        const target = visual.target;
-        if (target?.isConnected && element.current?.contains(target) && toolRuntime.getTools().includes(visual.event.tool))
+        const target = currentVisual.target;
+        if (target.isConnected && element.current?.contains(target)
+            && (currentVisual.event.tool.definition.effect === "navigate" || toolRuntime.getTools().includes(currentVisual.event.tool)))
             return { element: target };
-        return visual.event.tool.definition.effect === "navigate" && element.current?.isConnected
-            ? { element: element.current }
-            : undefined;
-    }, [visual, toolRuntime]);
-    const operation = visual ? {
-        toolCallId: visual.event.id,
-        name: visual.event.name,
-        input: visual.event.input,
-        effect: visual.event.tool.definition.effect,
-        progressLabel: visual.event.progressLabel || "正在处理你的请求",
-        status: visual.event.status === "running" ? "running" : "completed",
+        return undefined;
+    }, [currentVisual, element, toolRuntime]);
+    const operation = currentVisual ? {
+        toolCallId: currentVisual.event.id,
+        name: currentVisual.event.name,
+        input: currentVisual.event.input,
+        effect: currentVisual.event.tool.definition.effect,
+        progressLabel: currentVisual.event.progressLabel || "正在处理你的请求",
+        status: currentVisual.event.status === "running" ? "running" : currentVisual.event.status === "success" ? "completed" : "failed",
     } : {
-        toolCallId: turn,
+        toolCallId: cycle?.taskProgress?.phase === "tool" ? cycle.taskProgress.toolCallId : cycle?.id ?? history.scope,
         name: "agent",
-        progressLabel: waiting ? "等待你完成操作" : chat.failed ? "任务失败" : "正在处理你的请求",
-        status: chat.failed ? "failed" : running || waiting ? "running" : "completed",
+        progressLabel: waiting ? "等待你完成操作" : cycle?.status === "cancelling" ? "正在终止" : cycle?.taskProgress?.phase === "tool" ? cycle.taskProgress.progressLabel || "正在执行工具" : cycle?.taskProgress ? "正在处理" : "正在处理你的请求",
+        status: running || waiting ? "running" : outcome?.id === history.scope ? outcome.status : "completed",
     };
-    return _jsxs(_Fragment, { children: [_jsx("div", { ref: element, className: "nexface-operation-surface", children: children }), _jsx(OperationOverlayView, { operation: operation, progressHistory: history, ...(chat.taskLabel ? { taskLabel: chat.taskLabel } : {}), running: running, feedbackActive: Boolean(visual) && running && !waiting, humanHasControl: waiting, onCancel: chat.cancel, resolveSurface: resolveSurface, resolveTarget: resolveTarget }, chat.sessionId)] });
+    const entries = !cycle || history.scope === cycle.id ? history.entries : [];
+    return activated || executing || entries.length ? _jsx(OperationOverlayView, { operation: operation, progressHistory: entries, running: running, feedbackActive: Boolean(currentVisual) && running && !waiting && !stopping, humanHasControl: waiting, ...(cycle?.canCancel ? { onCancel: () => runtime.requestOperationCancel(cycle.id) } : {}), cancelling: cycle?.status === "cancelling" || cycle?.status === "ending", ...(currentVisual ? { fallbackPosition: currentVisual.position } : {}), resolveSurface: resolveSurface, resolveTarget: resolveTarget }) : null;
 }
 //# sourceMappingURL=operation-surface.js.map