fix(BrowserToolSet): Playwright greenlet thread-binding crash on cross-thread cache reuse

[Copilot]

The Playwright connection cache introduced in v0.0.22 assumed all tool calls run on the same OS thread. LangGraph ToolNode creates a new ContextThreadPoolExecutor per invocation, so each tool call lands on a different short-lived worker thread — the cached greenlet is bound to the dead thread, making every call after the first fail with "cannot switch to a different thread (which happens to have exited)".

Changes

Bug 1 (P0) — Per-thread isolation in _get_playwright

The Playwright Sync API greenlet is bound to the OS thread that created it and is never safe to use from any other thread, even if the creating thread is still alive. _get_playwright now stores the creating thread as self._playwright_thread and recreates the connection whenever the calling thread differs from the creator — regardless of whether the creator is alive or dead.

# Before: always returned cached instance regardless of thread state
if self._playwright_sync is not None:
    return self._playwright_sync

# After: invalidate cache for any different calling thread
if self._playwright_sync is not None and self._playwright_thread is not None:
    current_thread = threading.current_thread()
    creator_thread = self._playwright_thread
    if not creator_thread.is_alive() or current_thread is not creator_thread:
        self._reset_playwright()  # greenlet binding is invalid, must recreate

Bug 2 (P1) — browser_navigate default wait_until

Changed from "load" → "domcontentloaded". Sites with external sub-resources unreachable from the sandbox never fire load, causing systematic 90 s timeouts. domcontentloaded fires reliably once the DOM is ready.

Bug 3 (P2) — Greenlet error recovery in _run_in_sandbox

Added a dedicated except GreenletError block (with safe ImportError fallback, the same pattern used for PlaywrightError) placed before the generic except Exception. This replaces the previous brittle substring check ("cannot switch to") with a proper exception type match that is robust across greenlet/Playwright version changes.

On a greenlet.error, only the Playwright connection is reset — the sandbox itself is preserved (the failure is client-side thread affinity, not a sandbox crash) and the callback is retried once with the same sandbox instance.

_reset_playwright

Now also clears self._playwright_thread = None on reset.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug] BrowserToolSet v0.0.22 的 Playwright 缓存在跨线程调用时导致 greenlet 永久失效</issue_title>
<issue_description>## 概述

agentrun-sdk v0.0.22 的 PR Serverless-Devs/agentrun-sdk-python#57（修复 Issue Serverless-Devs/agentrun-sdk-python#55）引入了 Playwright 连接缓存机制 (_get_playwright + self._playwright_sync)。该缓存隐含假设所有工具调用在同一个 OS 线程上执行，但 LangGraph ToolNode 每次调用时创建新的 ContextThreadPoolExecutor（线程池），导致连续的浏览器工具调用实际运行在不同的短生命周期工作线程上。

结果：首次浏览器工具调用成功后，缓存的 Playwright 实例的 greenlet 绑定到已终止的工作线程上，所有后续调用必然失败，返回 "cannot switch to a different thread (which happens to have exited)"。

版本影响：v0.0.21 不受此问题影响（每次创建新 Playwright 实例），v0.0.22 和 v0.0.23 均受影响。

环境	值
agentrun-sdk	0.0.22
Python	3.12
LangGraph	1.0.6（已确认升级到 v1.0.10 无法解决）
LangChain	1.2.4
Playwright	1.57.0
greenlet	3.3.0
OS	macOS (darwin 23.6.0)

---

Bug 1（P0 根因）：_get_playwright 缓存不感知调用线程变化

根因

PR #57 将每个工具方法从"每次创建新 Playwright"改为"复用缓存实例"：

# v0.0.21 — 每次创建 & 销毁
def browser_navigate(self, url, ...):
    def inner(sb):
        with sb.sync_playwright() as p:   # ← 每次新建
            response = p.goto(url, ...)
            return {...}
    return self._run_in_sandbox(inner)

# v0.0.22 — 缓存复用
def browser_navigate(self, url, ...):
    def inner(sb):
        p = self._get_playwright(sb)      # ← 首次创建，后续复用
        response = p.goto(url, ...)
        return {...}
    return self._run_in_sandbox(inner)

_get_playwright 在首次调用时创建 BrowserPlaywrightSync 实例并缓存到 self._playwright_sync。Playwright 内部的 sync_playwright().start() 会创建一个 MainGreenlet，该 greenlet 绑定到创建它的 OS 线程（Python greenlet 库的约束：greenlet 只能在创建它的线程上切换）。

当外部调用者（如 LangGraph ToolNode）在不同线程上发起后续工具调用时，_get_playwright 返回缓存实例，但其内部 greenlet 仍绑定在已不存在的旧线程上，导致 greenlet.error。

LangGraph ToolNode 的线程模型

LangGraph ToolNode._func() 每次调用都创建新的 ContextThreadPoolExecutor，工具在线程池工作线程中执行：

# langgraph/prebuilt/tool_node.py
def _func(self, input, config, runtime):
    # ...
    with get_executor_for_config(config) as executor:  # 每次新建 executor
        outputs = list(
            executor.map(self._run_one, tool_calls, ...)
        )
    # executor.__exit__() → shutdown(wait=True) → 工作线程终止

get_executor_for_config（来自 langchain_core.runnables.config）每次返回新 ContextThreadPoolExecutor：

@contextmanager
def get_executor_for_config(config):
    with ContextThreadPoolExecutor(max_workers=config.get("max_concurrency")) as executor:
        yield executor

已确认 LangGraph 最新版 v1.0.10 的 ToolNode 仍使用完全相同的模式，从 v1.0.6 → v1.0.10 的变更集中在 CLI、文档、依赖更新等方面，线程模型未变。升级 LangGraph 无法解决此问题。

冲突时序

LangGraph Agent 执行流程:

 ToolNode._func() [调用 Serverless-Devs/agentrun-sdk-python#1: browser_navigate]
    └─ ContextThreadPoolExecutor-1 创建
        └─ Thread-B 执行 browser_navigate
            └─ _get_playwright(sb)
                └─ 首次创建 → sync_playwright().start()
                    └─ MainGreenlet 创建，绑定 Thread-B ✓
                └─ 缓存到 self._playwright_sync
            └─ p.goto("baidu.com") → 成功 ✅
    └─ executor.__exit__() → Thread-B 终止 💀

 LLM 调用 (~2s)

 ToolNode._func() [调用 Serverless-Devs/agentrun-sdk-python#2: browser_snapshot]
    └─ ContextThreadPoolExecutor-2 创建
        └─ Thread-C 执行 browser_snapshot
            └─ _get_playwright(sb)
                └─ self._playwright_sync 不为 None → 返回缓存实例
            └─ p.evaluate(...)
                └─ dispatcher_fiber.switch()
                    └─ 目标 greenlet 绑定在 Thread-B，但 Thread-B 已退出
                    └─ 💥 "cannot switch to a different thread (which happens to have exited)"

v0.0.21 为什么不触发

在 v0.0.21 中，每次工具调用都使用 with sb.sync_playwright() as p: 创建和销毁独立的 Playwright 实例。即使 ToolNode 每次在不同线程上执行，每次调用都会创建新的 greenlet 绑定到当前线程，不依赖前一个线程。

v0.0.21 用户报告的"不稳定失败"是另一个独立问题（Issue #55 描述的 CDP 瞬态错误 + 不区分错误类型导致不必要的沙箱重建），并非 greenlet 线程绑定问题。

复现步骤

1. 创建 BrowserToolSet 并通过 to_langchain() 转为 LangChain 工具
2. 通过 create_agent 构建 LangGraph Agent
3. 给 Agent 发送需要使用浏览器的指令（如"打开 baidu.com 并获取快照"）
4. Agent 首次调用 browser_navigate → 成功
5. Agent 第二次调用任何浏览器工具 → 必然失败

最小复现代码

from agentrun.integration.builtin.sandbox import BrowserToolSet
from langchain_core.runnables.config import ContextThreadPoolExecutor

toolset = BrowserToolSet(template_name="<your-template>", config=None)
tools = toolset.to_langchain()
tools_map = {t.name: t for t in tools}

# 模拟 ToolNode：每次工具调用使用新的 ContextThreadPoolExecutor
# Step 1: 第一个 executor（工具在 Thread-B 上执行）
with ContextThreadPoolExecutor(max_workers=1) as executor:
    r = list(executor.map(
        lambda _: tools_map["browser_navigate"].invoke({"url": "https://www.baidu.com"}),
        [None]
    ))[0]
    print(r)  # {'url': 'https://www.baidu.com', 'succ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes Serverless-Devs/agentrun-sdk-python#66

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

[Copilot]

Pull request overview

Fixes BrowserToolSet Playwright caching failures caused by greenlet thread-affinity when LangGraph runs tool calls on short-lived worker threads, and improves navigation robustness.

Changes:

• Add thread-liveness tracking to invalidate/recreate cached Playwright connections.
• Change browser_navigate default wait_until from "load" to "domcontentloaded" to reduce sandbox timeouts.
• Add recovery logic for greenlet thread-binding errors and extend unit tests around caching/reset behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
agentrun/integration/builtin/sandbox.py	Adds _playwright_thread tracking, greenlet-error recovery path, and updates browser_navigate default wait condition.
tests/unittests/integration/test_browser_toolset_error_handling.py	Updates fixtures for _playwright_thread and adds new tests for thread awareness / greenlet error handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The greenlet recovery path detects thread-binding errors via a substring check ("cannot switch to"). This is brittle (message text can change between greenlet/Playwright versions) and may miss the real exception type. Prefer handling the concrete exception type (e.g., greenlet.error) in a dedicated except block (guarded by a safe import) rather than relying on message parsing.

[OhYee]

@copilot apply changes based on this feedback

[Copilot]

Fixed in ac0252e. Added a GreenletError import with ImportError fallback (same pattern as PlaywrightError at the top of the file), then replaced the brittle string check with a dedicated except GreenletError block placed before the generic except Exception. The sandbox is now preserved on greenlet errors (only Playwright is reset and retried) since the failure is client-side thread affinity, not a sandbox crash.

[Copilot]

This concurrency test asserts that _get_playwright returns the same cached Playwright object to multiple OS threads. With Playwright Sync API, the underlying greenlet is thread-affine, so sharing a single instance across threads will still crash when those threads actually call methods on it. If the intended fix is thread-safe caching, the test should reflect that (e.g., per-thread caching) rather than validating cross-thread sharing.

[OhYee]

@copilot apply changes based on this feedback

[Copilot]

Already applied in ac0252e. The test was renamed to test_concurrent_get_playwright_each_thread_gets_own_connection and now validates that each OS thread receives its own Playwright connection rather than asserting cross-thread sharing (which is unsafe with the Sync API's greenlet binding).

[Copilot]

test_get_playwright_live_thread_not_recreated expects that a Playwright instance created on the main thread can be reused from a different live thread. For Playwright Sync API, this is exactly the unsafe case that triggers greenlet.error: cannot switch to a different thread. The desired behavior should be either (a) recreate a thread-local Playwright instance for the worker thread, or (b) prevent calling into Playwright from a different thread; the test should be updated accordingly.

[OhYee]

@copilot apply changes based on this feedback

[Copilot]

Already applied in ac0252e. The test was replaced by test_get_playwright_different_live_thread_recreates_connection, which validates that any different OS thread triggers a new connection — even when the creating thread is still alive — since Playwright Sync API greenlets are never safe to use from a different thread.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• agentrun.cn-hangzhou.aliyuncs.com
  • Triggering command: /home/REDACTED/work/agentrun-sdk-python/agentrun-sdk-python/.venv/bin/pytest pytest tests/unittests/ -q (dns block)
• api.scarf.sh
  • Triggering command: /home/REDACTED/work/agentrun-sdk-python/agentrun-sdk-python/.venv/bin/pytest pytest tests/unittests/ -q (dns block)
• telemetry.crewai.com
  • Triggering command: /home/REDACTED/work/agentrun-sdk-python/agentrun-sdk-python/.venv/bin/pytest pytest tests/unittests/ -q (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)