feat: parallel tool execution with automatic mutation serialization

- Add lightweight async mutex (src/util/mutex.ts) for FIFO serialization
- Add serialized?: boolean to BrowserToolDefinition
- Wire mutex acquisition into registerBrowserTool execute wrapper
- Expose mutationMutex() on BrowserClient
- Mark all mutation tools (click, type, scroll, navigate, switch_tab, etc.) as serialized
- Leave observation tools (screenshot, page_info, execute_js, http_get, etc.) unguarded
- Update prompt and skill docs to reflect parallel-safe behavior
- Fix scroll tool: add Page.bringToFront, explicit button:none/buttons:0/pointerType:mouse
- Update .gitignore to ignore scripts/ and data/ folders

2 files changed, 66 insertions, 17 deletions

diff --git a/src/util/mutex.ts b/src/util/mutex.ts
new file mode 100644
index 0000000..08efe76
--- /dev/null
+++ b/src/util/mutex.ts
@@ -0,0 +1,25 @@
+/**
+ * Lightweight async mutex (~10 lines). Acquire returns a release function.
+ * When the mutex is free, acquire() resolves immediately. When held,
+ * callers are queued and execute serially in FIFO order.
+ */
+export type Mutex = {
+  acquire(): Promise<() => void>;
+};
+
+export const createMutex = (): Mutex => {
+  let queue = Promise.resolve<unknown>(undefined);
+
+  return {
+    async acquire(): Promise<() => void> {
+      let release = () => {};
+      const next = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const prev = queue;
+      queue = prev.then(() => next);
+      await prev;
+      return release;
+    },
+  };
+};
diff --git a/src/util/tool.ts b/src/util/tool.ts
index d269ba2..c2bb3f8 100644
--- a/src/util/tool.ts
+++ b/src/util/tool.ts
@@ -53,6 +53,10 @@ export type BrowserToolDefinition<S extends TSchema> = {
   readonly handler: ToolHandler<S>;
   readonly renderCall?: (args: Static<S>, theme: Theme) => Component;
   readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
+  /** If true, the tool acquires the client's mutation mutex before executing.
+   *  This ensures that two serialized tools never run concurrently,
+   *  preventing race conditions on shared CDP session/page state. */
+  readonly serialized?: boolean;
   readonly ensureAlive?: boolean;
 };
 
@@ -146,23 +150,43 @@ export const registerBrowserTool = (
           );
         }
       }
-      const result = await def.handler(args, {
-        client,
-        signal,
-        onUpdate: (u) => {
-          if (onUpdate) {
-            // AgentToolUpdateCallback expects AgentToolResult<TDetails>; we use unknown for TDetails.
-            const update: AgentToolResult<OkDetails> = {
-              content: [{ type: "text", text: u.text }],
-              details: { ok: true, ...(u.details ?? {}) },
-            };
-            // Cast needed: onUpdate is AgentToolUpdateCallback<unknown> (generic TDetails).
-            (onUpdate as AgentToolUpdateCallback<OkDetails>)(update);
-          }
-        },
-        extensionCtx,
-      });
-      return toToolResult(result, def.name);
+      // Serialized tools acquire the client's mutation mutex so that only one
+      // mutation tool runs at a time. Observation tools skip this and run freely
+      // in parallel. AbortSignal is checked after acquiring the lock so that a
+      // cancelled task doesn't hold the mutex forever.
+      let release: (() => void) | undefined;
+      if (def.serialized) {
+        const acquire = await client.mutationMutex().acquire();
+        release = acquire;
+        if (signal?.aborted) {
+          release();
+          return toToolResult(
+            { success: false, error: { kind: "invalid_state", message: "Tool execution aborted before entering serialized lane" } },
+            def.name,
+          );
+        }
+      }
+      try {
+        const result = await def.handler(args, {
+          client,
+          signal,
+          onUpdate: (u) => {
+            if (onUpdate) {
+              // AgentToolUpdateCallback expects AgentToolResult<TDetails>; we use unknown for TDetails.
+              const update: AgentToolResult<OkDetails> = {
+                content: [{ type: "text", text: u.text }],
+                details: { ok: true, ...(u.details ?? {}) },
+              };
+              // Cast needed: onUpdate is AgentToolUpdateCallback<unknown> (generic TDetails).
+              (onUpdate as AgentToolUpdateCallback<OkDetails>)(update);
+            }
+          },
+          extensionCtx,
+        });
+        return toToolResult(result, def.name);
+      } finally {
+        release?.();
+      }
     },
   };
   pi.registerTool(td);