@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/bridge.py

@@ -0,0 +1,784 @@
+"""Bidirectional JSON-RPC bridge over stdin/stdout.
+
+Protocol writes use ``_original_stdout`` so that exec's stdout capture
+never corrupts the wire protocol.
+
+Requires Python 3.10+: the ``X | None`` annotations below are evaluated at
+definition time, so an older interpreter fails at import with a TypeError
+before this module can report anything. Do not soften them back to
+``Optional[...]`` — the host picks a qualifying interpreter (see
+``resolvePythonBin``) rather than making this tree run on an EOL Python.
+"""
+
+import ast
+import asyncio
+import builtins
+import contextvars
+import inspect
+import json
+import sys
+import traceback
+from io import StringIO
+from typing import Any
+
+from . import sandbox
+
+# Capture the real stdout before anything can redirect it.
+_original_stdout = sys.stdout
+_original_stderr = sys.stderr
+
+# req_id → (future, method). The method rides along purely so a failure can say
+# which call failed: the reader below sees only an id, and the traceback an
+# agent gets back is raised inside the reader, not at the await, so without this
+# the name of the operation is nowhere in the error.
+_pending: dict[int, tuple[asyncio.Future, str]] = {}
+_next_id = 1
+_exec_scope: dict[str, Any] = {}
+
+# Per-exec metadata from TypeScript (e.g. toolUseId). Each exec runs in its
+# own task, so the contextvar isolates concurrent execs from each other.
+exec_meta: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar("exec_meta", default={})
+
+# exec_id → the task running it, so a cancel arriving from TypeScript has
+# something to name. Without this the task from ensure_future is dropped on the
+# floor and a running exec cannot be reached by anything short of killing the
+# process — which serves the whole session and all its delegates.
+_running_execs: dict[str, asyncio.Task] = {}
+
+# Max bytes in a single protocol line. asyncio.StreamReader defaults to 64 KiB,
+# which a screenshot clears by an order of magnitude: the capture cap is 4 MB
+# (MAX_SCREENSHOT_BYTES in WidgeXactorWidget.ts) and base64 adds a third, so a
+# reply can reach ~5.3 MB. The default silently turned every screenshot into a
+# hung session. Sized well above that so the limit is a backstop against a
+# runaway writer, not something normal traffic can reach.
+_READ_LIMIT = 32 * 1024 * 1024
+
+
+def _dbg(msg: str) -> None:
+    """Write debug message to stderr (never contaminates JSON-RPC stdout)."""
+    _original_stderr.write(f"[xactor:bridge] {msg}\n")
+    _original_stderr.flush()
+
+
+def _emit(msg: dict) -> None:
+    """Write a JSON message + newline to the protocol stream and flush."""
+    _original_stdout.write(json.dumps(msg) + "\n")
+    _original_stdout.flush()
+
+
+def notify(method: str, **params: Any) -> None:
+    """Send a fire-and-forget message. No ``id``, so no response is expected.
+
+    Used for progress reporting, where blocking the API call on a UI round
+    trip would double every call's latency for no benefit.
+    """
+    _emit({"method": method, "params": params})
+
+
+def _fail_all_pending(reason: str) -> None:
+    """Reject every in-flight call. Used when a read fault loses a response.
+
+    Pending futures are the only record that anyone is waiting; if the reader
+    cannot say which call a lost frame belonged to, the choice is between
+    failing all of them and hanging all of them.
+    """
+    if not _pending:
+        return
+    _dbg(f"failing {len(_pending)} pending call(s): {reason}")
+    for req_id, (future, method) in list(_pending.items()):
+        _pending.pop(req_id, None)
+        if not future.done():
+            future.set_exception(RuntimeError(f"{method}: {reason}"))
+
+
+def _read_loop_stopped(task: "asyncio.Task") -> None:
+    """Done-callback for the read loop. Nothing reads stdin after this point.
+
+    A normal stop is EOF — TypeScript closed the pipe, the process is on its way
+    out, and there is nothing to say. Any other ending is a fault that would
+    otherwise show up only as an unretrieved-exception warning on stderr, long
+    after every call in flight had already hung.
+
+    Either way this process is finished, and says so by leaving. It used to
+    assume it was "on its way out" and go on running ``loop.run_forever()``
+    instead — true only when the host had sent SIGTERM, which is the one case
+    where the assumption did not matter. When the host died without it, the
+    daemon was reparented to launchd and stayed there with nothing to read and
+    no one to answer. They accumulated: one was found alive after seven days.
+    """
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is None:
+        _dbg("read loop stopped at EOF")
+    else:
+        _dbg(f"read loop died: {exc!r}\n{''.join(traceback.format_exception(exc))}")
+    _fail_all_pending("the bridge read loop stopped; no response can arrive")
+
+    # Stopping the loop returns control to `main`, which returns — so the
+    # interpreter shuts down normally, running whatever cleanup is registered,
+    # rather than being torn out from under itself by os._exit.
+    try:
+        asyncio.get_running_loop().stop()
+    except RuntimeError:
+        # No loop to stop, which means nothing is keeping us alive anyway.
+        pass
+
+
+async def call(method: str, **params: Any) -> Any:
+    """Send a JSON-RPC request and await the response."""
+    global _next_id
+    req_id = _next_id
+    _next_id += 1
+
+    future: asyncio.Future[Any] = asyncio.get_event_loop().create_future()
+    _pending[req_id] = (future, method)
+
+    _dbg(f"call → id={req_id} method={method} params_keys={list(params.keys())}")
+    _emit({"id": req_id, "method": method, "params": params})
+    result = await future
+    _dbg(f"call ← id={req_id} method={method} result_type={type(result).__name__}")
+    return result
+
+
+# Builtins withheld from agent code, mapped to what to use instead. The audit
+# hook denies the underlying operations too; this layer exists to fail early
+# with a message that names the replacement.
+#
+# `__import__` is not here: it is replaced rather than withheld, by
+# `sandbox.sandboxed_import`, which lets pure standard-library modules through.
+_DENIED_BUILTINS = {
+    "open": "use api.read_file() / api.write_file() / api.edit_file()",
+    "eval": "eval() is unavailable",
+    "exec": "exec() is unavailable",
+    "compile": "compile() is unavailable",
+    "input": "the shell is non-interactive",
+    "breakpoint": "the shell is non-interactive",
+}
+
+
+def _restricted_builtins() -> dict[str, Any]:
+    """A builtins mapping with the direct-OS escape hatches removed."""
+    safe = {k: v for k, v in vars(builtins).items() if k not in _DENIED_BUILTINS}
+
+    def _deny(name: str, hint: str) -> Any:
+        def denier(*_args: Any, **_kwargs: Any) -> Any:
+            raise PermissionError(f"Sandbox: {name}() is not allowed from shell code — {hint}.")
+        denier.__name__ = name
+        return denier
+
+    for name, hint in _DENIED_BUILTINS.items():
+        safe[name] = _deny(name, hint)
+    safe["__import__"] = sandbox.sandboxed_import
+    return safe
+
+
+def set_exec_scope(scope: dict[str, Any], restrict_builtins: bool = False) -> None:
+    """Set the namespace that exec commands run in.
+
+    Args:
+        scope: Names made available to exec'd code.
+        restrict_builtins: Withhold the direct-OS builtins (stdlib backend).
+    """
+    global _exec_scope
+    _exec_scope = dict(scope)
+    if restrict_builtins:
+        _exec_scope["__builtins__"] = _restricted_builtins()
+
+
+def compile_exec(code: str):
+    """Compile agent code into an ``async def __exec__()`` without rewriting it.
+
+    The agent's code needs a function around it — `await` and `return` are both
+    legal in what it sends, and neither is legal at module level. The obvious
+    way to get one is to indent every line and prepend a header, and that is
+    what this did for a long time.
+
+    Indenting is a *textual* operation and a triple-quoted string is text, so
+    it edits the agent's data as readily as its code:
+
+        old = \"\"\"foo          becomes          'foo\\n    bar'
+        bar\"\"\"
+
+    Four spaces, on every line after the first, inside a value the agent
+    believes it copied verbatim. It never announces itself. What it produces is
+    `api.edit_file` reporting `old_string not found` for a block the agent just
+    read out of the file — four separate bug reports over eight days, each
+    filed against `edit_file` — and a bash heredoc whose terminator no longer
+    sits at column zero, so the shell swallows the rest of the script. Every
+    one of those looked like a bug in the call being made rather than in the
+    transport under it, which is why it survived so long.
+
+    Wrapping on the AST cannot have that failure: `ast.parse` has already
+    turned the literal into a value by the time the body is moved, so nothing
+    downstream is in a position to reinterpret its whitespace.
+
+    The `async def` is parsed from a template rather than built as an
+    `ast.AsyncFunctionDef` by hand. The node's field set is not stable across
+    the versions this runs on — 3.12 added `type_params` — and a constructor
+    call that names the fields would have to know which interpreter it is on.
+
+    Line numbers come out *better* than before, incidentally: the body keeps
+    its original `lineno`, where the old header shifted every traceback down by
+    one.
+
+    Being on the AST is also what lets three traps be closed here rather than
+    explained afterwards — see `_ExecRewriter`. None of them changes what a
+    correct program does.
+    """
+    body = ast.parse(code).body or [ast.Pass()]
+    module = ast.parse(_EXEC_TEMPLATE)
+    # Before the rewrite, which replaces the call nodes the lint looks for.
+    lint = _shell_literal_lint(code, body)
+    if lint:
+        module.body.insert(0, ast.parse(f"__xactor_lint__ = {lint!r}").body[0])
+    exec_def = module.body[-1]
+    exec_def.body = body
+    _ExecRewriter(_top_level_bindings(body)).visit(exec_def)
+    ast.fix_missing_locations(module)
+    return compile(module, "<xactor-exec>", "exec")
+
+
+_SHELL_CALLS = {"bash": ("command", "input"), "run": ("argv", "input"), "powershell": ("script",)}
+
+
+def _shell_literal_lint(code: str, body: list[ast.stmt]) -> dict[int, str]:
+    """Line → note, for shell calls handed a non-raw literal Python un-escaped.
+
+    By the time `api.bash` runs, the backslash is already gone: `'\\''` in a
+    normal string reaches bash as `'''`. Only the source still shows what was
+    written, so the comparison happens here, and the note waits in the module
+    for `caller_lint` to fetch if the command fails. It is never shown for a
+    command that worked: `"a\\\\|b"` for grep is a correct use of exactly this.
+
+    Follows a plain name one step back to its assignment, since `cmd = "…"`
+    then `api.bash(cmd)` is the commoner shape for anything long.
+    """
+    from . import shell_hints
+
+    assigned: dict[str, ast.AST] = {}
+    for node in ast.walk(ast.Module(body=body, type_ignores=[])):
+        if isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
+            assigned[node.targets[0].id] = node.value
+
+    def literals(node: ast.AST, depth: int = 0):
+        if isinstance(node, ast.Name) and depth == 0 and node.id in assigned:
+            yield from literals(assigned[node.id], 1)
+            return
+        if isinstance(node, ast.JoinedStr) or (isinstance(node, ast.Constant) and isinstance(node.value, str)):
+            yield node
+            return
+        for child in ast.iter_child_nodes(node):
+            yield from literals(child, depth)
+
+    lint: dict[int, str] = {}
+    for node in ast.walk(ast.Module(body=body, type_ignores=[])):
+        if not (_ExecRewriter._is_api_call(node) and node.func.attr in _SHELL_CALLS):
+            continue
+        call = node.func.attr
+        params = _SHELL_CALLS[call]
+        args = list(node.args[:len(params)]) + [k.value for k in node.keywords if k.arg in params]
+        for arg in args:
+            for lit in literals(arg):
+                segment = ast.get_source_segment(code, lit)
+                if not segment:
+                    continue
+                value = lit.value if isinstance(lit, ast.Constant) else None
+                note = shell_hints.literal_note(segment, value, lit.lineno, call)
+                if note:
+                    for line in range(node.lineno, (node.end_lineno or node.lineno) + 1):
+                        lint.setdefault(line, note)
+                    break
+    return lint
+
+
+# Notes the shell attaches to this exec's output, whatever the script printed.
+# A hint inside a result dict reaches nobody who printed only `r["stdout"]` —
+# which is most scripts — so they go where the agent always looks.
+_exec_notes: contextvars.ContextVar[list[str] | None] = contextvars.ContextVar("exec_notes", default=None)
+
+
+# When the host will cut this exec off, on the loop's clock. None when the host
+# did not say, which is every caller but the real one.
+_exec_deadline: contextvars.ContextVar[float | None] = contextvars.ContextVar("exec_deadline", default=None)
+
+# The longest an exec may be given — `timeout_seconds` is capped here on the
+# host side (see `terminalTimeoutMs`). Any per-call timeout above it cannot
+# have been meant as seconds.
+MAX_EXEC_SECONDS = 3900
+
+
+def seconds_left() -> float | None:
+    """Seconds until the host stops the running exec, or None if unknown."""
+    deadline = _exec_deadline.get()
+    if deadline is None:
+        return None
+    return max(0.0, deadline - asyncio.get_running_loop().time())
+
+
+def add_note(text: str) -> None:
+    """Attach one line to the running exec's output. Repeats are dropped."""
+    notes = _exec_notes.get()
+    if notes is not None and text not in notes:
+        notes.append(text)
+
+
+def caller_lint() -> str | None:
+    """The literal-lint note for the agent line that is running now, if any."""
+    frame = sys._getframe(1)
+    while frame is not None:
+        if frame.f_code.co_filename == "<xactor-exec>":
+            table = frame.f_globals.get("__xactor_lint__") or {}
+            return table.get(frame.f_lineno)
+        frame = frame.f_back
+    return None
+
+
+# The module every exec is compiled into. The helpers live *in* it rather than
+# in the scope the caller builds, so any scope that runs the code has them —
+# `_handle_exec`'s and a test's alike — and an exec's list of un-awaited calls
+# is per-exec by construction, because the scope dict is.
+#
+# `__xactor_await__` is a plain function on purpose: it hands back the very
+# awaitable it was given, so an exception from an api call carries no extra
+# frame between the agent's line and the call that raised.
+_EXEC_TEMPLATE = '''\
+__xactor_unawaited__ = []
+class __XactorReady__:
+    __slots__ = ("value",)
+    def __init__(self, value):
+        self.value = value
+    def __await__(self):
+        return self.value
+        yield
+def __xactor_await__(value):
+    if hasattr(type(value), "__await__"):
+        return value
+    code = getattr(value, "gi_code", None)
+    if code is not None and code.co_flags & 0x100:
+        return value  # a generator-based coroutine (@types.coroutine)
+    return __XactorReady__(value)
+def __xactor_track__(value, name, line):
+    if type(value).__name__ == "coroutine":
+        __xactor_unawaited__.append((value, name, line))
+    return value
+async def __exec__():
+    pass
+'''
+
+
+def _top_level_bindings(body: list[ast.stmt]) -> set[str]:
+    """Names the exec body binds in its own scope — i.e. `__exec__`'s locals.
+
+    Descends through blocks (`if`, `for`, `try`, `with`) but not into nested
+    functions, lambdas, classes or comprehensions, whose bindings are their own.
+    Names the body itself declares `global` are excluded: those really do live
+    in the scope dict.
+    """
+    bound: set[str] = set()
+    declared_global: set[str] = set()
+
+    def walk(node: ast.AST) -> None:
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                bound.add(child.name)
+                continue
+            if isinstance(child, (ast.Lambda, ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+                continue
+            if isinstance(child, ast.Global):
+                declared_global.update(child.names)
+            elif isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store):
+                bound.add(child.id)
+            elif isinstance(child, ast.alias):
+                bound.add((child.asname or child.name).split(".")[0])
+            elif isinstance(child, ast.ExceptHandler) and child.name:
+                bound.add(child.name)
+            walk(child)
+
+    walk(ast.Module(body=body, type_ignores=[]))
+    return bound - declared_global
+
+
+class _ExecRewriter(ast.NodeTransformer):
+    """Three traps the `async def` wrapper set, closed where they were set.
+
+    **An un-awaited api call ran nothing and said nothing.** `api.bash`,
+    `api.man`, `api.write_file` and `api.todo_write` are coroutines; the page
+    verbs are not. A bare `api.todo_write([...])` was dropped without a word,
+    `print(api.man(x))` printed `<coroutine object …>`, and `api.bash(c)["stdout"]`
+    raised "'coroutine' object is not subscriptable" — about forty times, and
+    three of three rebase children made it on their first call. Each api call
+    that is not the operand of an `await` is now passed through
+    `__xactor_track__`, which records it if it is a coroutine; `_handle_exec`
+    fails the exec, by name and line, for any that never ran.
+
+    **`await` on a page verb raised.** `await api.find(...)` gave "object
+    FindSpec can't be used in 'await' expression". The tool description's rule
+    is "use await for all calls", so the rule is now true: `await x` on
+    something that is not awaitable is `x`.
+
+    **`global` in a nested function could not see the exec's own names.** Those
+    names are locals of `__exec__`, not globals, so `global inp` found nothing
+    and the NameError that followed was explained as the per-exec scope — the
+    wrong cause. In a nested function, `global n` for a name the body binds is
+    rewritten to `nonlocal n`, which is what the agent meant.
+    """
+
+    def __init__(self, top_level: set[str]) -> None:
+        self._top_level = top_level
+        self._scopes: list[set[str]] = []  # locals of each enclosing function, __exec__ first
+
+    # ── await ──
+    def visit_Await(self, node: ast.Await) -> ast.AST:
+        operand = node.value
+        # The operand itself is awaited, so it is not tracked — only what is
+        # inside it is visited.
+        if self._is_api_call(operand):
+            self.generic_visit(operand)
+        else:
+            node.value = self.visit(operand)
+        node.value = ast.copy_location(
+            ast.Call(func=ast.Name("__xactor_await__", ast.Load()), args=[node.value], keywords=[]),
+            node.value,
+        )
+        return node
+
+    # ── bare api calls ──
+    def visit_Call(self, node: ast.Call) -> ast.AST:
+        self.generic_visit(node)
+        if not self._is_api_call(node):
+            return node
+        return ast.copy_location(
+            ast.Call(
+                func=ast.Name("__xactor_track__", ast.Load()),
+                args=[node, ast.Constant(node.func.attr), ast.Constant(node.lineno)],
+                keywords=[],
+            ),
+            node,
+        )
+
+    @staticmethod
+    def _is_api_call(node: ast.AST) -> bool:
+        return (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "api"
+        )
+
+    # ── global in nested functions ──
+    def _visit_function(self, node: ast.AST) -> ast.AST:
+        # Each function's own locals, so `visit_Global` can tell whether a
+        # function between it and the exec binds the same name — in which case
+        # `nonlocal` would reach *that* one, and `global` was never about the
+        # exec's name at all.
+        own = _top_level_bindings(node.body) | {
+            a.arg for a in (*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs)
+        } | {a.arg for a in (node.args.vararg, node.args.kwarg) if a is not None}
+        self._scopes.append(own)
+        try:
+            self.generic_visit(node)
+        finally:
+            self._scopes.pop()
+        return node
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.AST:
+        return self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> ast.AST:
+        # The outermost one is `__exec__` itself; its own `global` statements
+        # mean what they say.
+        return self._visit_function(node)
+
+    def visit_Global(self, node: ast.Global) -> ast.AST | list[ast.stmt]:
+        if len(self._scopes) < 2:
+            return node
+        # Functions strictly between `__exec__` (first) and this one (last).
+        between = set().union(*self._scopes[1:-1]) if len(self._scopes) > 2 else set()
+        local = [n for n in node.names if n in self._top_level and n not in between]
+        if not local:
+            return node
+        rest = [n for n in node.names if n not in local]
+        out: list[ast.stmt] = [ast.copy_location(ast.Nonlocal(names=local), node)]
+        if rest:
+            out.append(ast.copy_location(ast.Global(names=rest), node))
+        return out
+
+
+async def unawaited_report(scope: dict[str, Any]) -> str:
+    """Name every api call in this exec that was created and never ran.
+
+    A coroutine some task holds is not reported: it was handed to
+    `create_task` and will run. Nor is one a task will reach in a moment —
+    `create_task(go(api.bash(x)))` holds `go`, not the bash call, and `go`
+    has not started yet when the exec returns — so the loop is given two turns
+    first, which is enough for such a task to reach its `await`.
+
+    Nothing is closed. Closing would silence Python's own "never awaited"
+    warning, but a report that is wrong — something will await it after all —
+    would then break the task that does, rather than merely being wrong.
+    """
+    pending = scope.get("__xactor_unawaited__") or []
+    if not pending:
+        return ""
+    for _ in range(2):
+        await asyncio.sleep(0)
+    try:
+        held = {id(t.get_coro()) for t in asyncio.all_tasks()}
+    except RuntimeError:
+        held = set()
+    lines = []
+    for coro, name, line in pending:
+        if id(coro) in held or inspect.getcoroutinestate(coro) != inspect.CORO_CREATED:
+            continue
+        lines.append(f"api.{name}(...) on line {line} was never awaited, so it did not run")
+    if not lines:
+        return ""
+    return (
+        "\n".join(lines)
+        + ".\nWrite `await api.<name>(...)`. Every api call that touches files, "
+        "commands, sessions or the IDE is async; awaiting one that is not is "
+        "harmless, so when in doubt, await.\n"
+    )
+
+
+def hermetic_hint(err: BaseException, trace: str) -> str:
+    """Explain a NameError that is really the scope boundary between execs.
+
+    Every exec gets a fresh `dict(_exec_scope)` and the agent's code is wrapped
+    in an `async def`, so a name it bound last call is gone twice over: the
+    assignment was a function local that never reached the scope dict, and the
+    dict itself was rebuilt. `globals()["x"] = ...` does not survive either,
+    which is the part that costs people a second round trip after the first one
+    taught them the wrong lesson.
+
+    That isolation is deliberate and should stay. A delegate runs its execs
+    through its *parent's* shell, so a scope that persisted would let a subagent
+    read and overwrite the variables of the session that called it.
+
+    What was not deliberate is that it is invisible. A bare `NameError: name 'r'
+    is not defined` reads as a typo, so the next thing anybody does is send the
+    same code again. Observed four times in one session, including once by an
+    agent that then reasoned its way to `globals()` — a fix that cannot work,
+    because the traceback shows the wrapper but not the rebuilt dict.
+
+    Every NameError gets it, and a narrower guard was tried first. Checking for
+    `<xactor-exec>` in the traceback looks like it would spare an unrelated
+    NameError raised inside `api` internals — and it discriminates nothing,
+    because the agent's frame is the entry point and is therefore in the chain
+    of every traceback it can see. A condition that is always true is worse
+    than none: it reads as a safeguard.
+    """
+    del trace  # kept in the signature; see above for why it cannot help
+    if not isinstance(err, NameError):
+        return ""
+    return (
+        "\n"
+        "Each exec runs in its own scope. Nothing you assign survives to the next "
+        "call — not a plain name, and not globals()[...] either, because the scope "
+        "is rebuilt every time. It is deliberate: a subagent shares its parent's "
+        "shell, and persisting would let the two read each other's variables.\n"
+        "So make the call self-contained — do the whole chain in one exec — or put "
+        "what you need on disk and read it back.\n"
+    )
+
+
+def escape_hint(err: BaseException) -> str:
+    """Explain the SyntaxError a Windows path in a normal string produces.
+
+    `"C:\\Users\\x"` does not compile: `\\U` begins an eight-digit unicode
+    escape, and the error says so in codec vocabulary — "truncated
+    \\UXXXXXXXX escape" — that names neither the path nor the fix. On Windows,
+    where every home directory starts `C:\\Users`, it is among the first
+    things an agent writes.
+    """
+    if not isinstance(err, SyntaxError) or "unicodeescape" not in str(err):
+        return ""
+    return (
+        "\nA backslash in a normal string starts an escape, and `\\U`, `\\N` and "
+        "`\\x` must be followed by a code — so a Windows path like \"C:\\Users\" "
+        "does not compile. Write r\"C:\\Users\" or \"C:/Users\"; every api call "
+        "accepts forward slashes.\n"
+    )
+
+
+async def _handle_exec(
+    code: str,
+    exec_id: str,
+    meta: dict[str, Any] | None = None,
+    timeout_ms: float | None = None,
+) -> None:
+    """Execute Python code sent from TypeScript, capturing stdout."""
+    exec_meta.set(meta or {})
+    _exec_deadline.set(
+        asyncio.get_running_loop().time() + timeout_ms / 1000
+        if isinstance(timeout_ms, (int, float)) and timeout_ms > 0 else None
+    )
+    notes: list[str] = []
+    _exec_notes.set(notes)
+
+    captured = StringIO()
+    old_stdout = sys.stdout
+    sys.stdout = captured
+
+    error_text: str | None = None
+    result_value: Any = None
+    cancelled = False
+    local_scope: dict[str, Any] = {}
+
+    try:
+        # Wrapped in an async def so that await works inside exec'd code — see
+        # compile_exec for why that wrapping happens on the AST and not on the
+        # source text.
+        local_scope = dict(_exec_scope)
+        exec(compile_exec(code), local_scope)
+        # Only the agent's own frames run under the strict scope — compiling
+        # the wrapper above and formatting the traceback below must not.
+        with sandbox.user_code_scope():
+            result_value = await local_scope["__exec__"]()
+    except asyncio.CancelledError:
+        # The user stopped this call. Caught ahead of `except Exception` and not
+        # re-raised, both deliberately: CancelledError derives from
+        # BaseException, so letting it past this frame would kill the task
+        # without ever emitting a response — and TypeScript would wait on a
+        # promise nobody is going to resolve. Swallowing it here means the task
+        # finishes normally, having reported what the agent got done first.
+        cancelled = True
+    except Exception as err:
+        error_text = traceback.format_exc()
+        # A scope-boundary NameError reads as a typo, so say what it really is.
+        error_text += hermetic_hint(err, error_text)
+        error_text += escape_hint(err)
+    finally:
+        sys.stdout = old_stdout
+        _running_execs.pop(exec_id, None)
+
+    # An api call that was never awaited did not run, whatever else happened.
+    # After a crash it is usually the cause ("'coroutine' object is not
+    # subscriptable"); after a clean finish it is a silent no-op — a todo list
+    # never written, a file never saved — and so it is an error either way.
+    if not cancelled:
+        dropped = await unawaited_report(local_scope)
+        if dropped:
+            error_text = (error_text + "\n" if error_text else "") + dropped
+
+    output = captured.getvalue()
+    if notes:
+        if output and not output.endswith("\n"):
+            output += "\n"
+        output += "".join(f"[shell] {n}\n" for n in notes)
+
+    response: dict[str, Any] = {"exec_id": exec_id, "output": output}
+    if cancelled:
+        response["cancelled"] = True
+    elif error_text is not None:
+        response["error"] = error_text
+    else:
+        # Serialize the result if it's JSON-friendly, else str()
+        try:
+            json.dumps(result_value)
+            response["result"] = result_value
+        except (TypeError, ValueError):
+            response["result"] = str(result_value)
+
+    _emit(response)
+
+
+async def _read_loop() -> None:
+    """Background task: read stdin and dispatch messages."""
+    loop = asyncio.get_event_loop()
+
+    if sys.platform == "win32":
+        import concurrent.futures
+
+        _stdin_executor = concurrent.futures.ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="stdin"
+        )
+
+        def _read_line() -> bytes:
+            return sys.stdin.buffer.readline()
+
+        async def _readline() -> bytes:
+            return await loop.run_in_executor(_stdin_executor, _read_line)
+    else:
+        reader = asyncio.StreamReader(limit=_READ_LIMIT)
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+
+        async def _readline() -> bytes:
+            return await reader.readline()
+
+    while True:
+        try:
+            raw = await _readline()
+        except ValueError as exc:
+            # A frame longer than the reader's limit. StreamReader raises rather
+            # than truncating, and this await sits outside the json try below —
+            # so before this except existed the exception ended the read loop
+            # outright, and with it every future the loop was going to resolve.
+            # The call that overflowed hung forever, and so did every call after
+            # it, because nothing was reading stdin any more.
+            #
+            # `continue` is the drain: readline() has already cleared what it
+            # buffered, so the next one picks up mid-line and raises again until
+            # it finally reaches the newline. The tail it returns then fails
+            # json.loads below and is skipped like any other malformed line.
+            #
+            # Failing every pending call is blunt — the id was inside the frame
+            # we could not parse, so there is no way to know which one overflowed.
+            # A caller told its call died is strictly better off than one waiting
+            # on a future nothing will ever resolve.
+            _dbg(f"read loop: oversized frame discarded: {exc}")
+            _fail_all_pending(
+                "a bridge response exceeded the read limit and was dropped"
+            )
+            continue
+        if not raw:
+            break  # EOF — TypeScript killed the process
+
+        line = raw.decode("utf-8", errors="replace").strip()
+        if not line:
+            continue
+
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        # API response (has id + result/error)
+        if "id" in msg and ("result" in msg or "error" in msg):
+            req_id = msg["id"]
+            future, method = _pending.pop(req_id, (None, "?"))
+            if future and not future.done():
+                if "error" in msg:
+                    _dbg(f"response id={req_id} ERROR: {msg['error']}")
+                    # Prefixed with the method. Still a RuntimeError, because
+                    # callers and tests catch that; the message is the only part
+                    # that changes.
+                    future.set_exception(RuntimeError(f"{method}: {msg['error']}"))
+                else:
+                    _dbg(f"response id={req_id} OK (result_type={type(msg['result']).__name__})")
+                    future.set_result(msg["result"])
+            else:
+                _dbg(f"response id={req_id} ORPHAN (no pending future)")
+            continue
+
+        # Exec command from TypeScript
+        if "exec" in msg and "exec_id" in msg:
+            _dbg(f"exec command received: exec_id={msg['exec_id']}, code_len={len(msg['exec'])}")
+            exec_id = msg["exec_id"]
+            _running_execs[exec_id] = asyncio.ensure_future(
+                _handle_exec(msg["exec"], exec_id, msg.get("meta"), msg.get("timeout_ms"))
+            )
+            continue
+
+        # Cancel an exec still running. An unknown or already-finished id is a
+        # no-op rather than an error: a cancel racing a result is normal, and
+        # there is nothing useful to say about losing that race.
+        if "cancel_exec_id" in msg:
+            exec_id = msg["cancel_exec_id"]
+            task = _running_execs.get(exec_id)
+            _dbg(f"cancel received: exec_id={exec_id}, running={task is not None}")
+            if task is not None and not task.done():
+                task.cancel()
+            continue