dsh-py-codeact 0.3.2 → 0.3.4

package/lib/index.js

@@ -5,7 +5,7 @@
  *
  * So this is NOT a `CodeRuntime` backend — it could not conform. It is an ordinary tool plugin that owns its own kernel: one IPython process per conversation tree with a shell per agent, globals surviving between calls, the model's action space being Python code and its observation that cell's output.
  *
- * It still emits `tool/code-dispatch-start` / `tool/code-dispatch`, so bridged tool calls render as SUBTOOL rows in the existing trajectory UI with no client change.
+ * It emits the session format's PTC dispatch events, so bridged tool calls render as SUBTOOL rows in the existing trajectory UI with no client change.
  *
  * @module dsh-py-codeact
  */
@@ -23,6 +23,9 @@ const TOOLS_MODULE = '__dsh__.tools'
 
 const SDK_SECTION_ORDER = 150
 
+/** Behind the tool listing, because the listing is what says whether a delegation tool is even there to orchestrate. */
+const ORCHESTRATION_SECTION_ORDER = 160
+
 /**
  * Ahead of the tool-guidance band, for the reason Code Mode orders its own code-only rule there: the model should read WHICH tools it may call before it reads what each one is for. Behind it sit thousands of characters of per-tool guidance ("use the read tool, not cat") that still apply — but by a different route than the one they imply.
  */
@@ -67,6 +70,72 @@ Your action space is Python. Each call runs one cell in a **persistent IPython s
 
 The available tools:`
 
+/**
+ * Orchestration is the one thing this loop can express that a tool-calling loop cannot: a fan-out whose shape is decided in code rather than by the model emitting N calls and reading N results back into its context. Worth its own section for the reason Code Mode's own guidance is separate from its tool listing — the listing says what exists, this says what to build out of it.
+ *
+ * Deliberately names no tool: the delegation tool's name is configurable (`dsh-tool-subagent` defaults to `subagent`) and it may not be mounted at all, so the text points at the listing above instead of asserting a binding that might not be there.
+ */
+const ORCHESTRATION = `## Orchestrating delegations
+
+The delegation tool is an awaitable — Python IS the orchestration. \`asyncio.gather\` fans out, \`while\` decides how many rounds, \`if\` decides what survives.
+
+Its result is a union keyed by \`kind\`, and by default it settles in the background and hands back an id (\`continuable: true\`). Pass \`run_in_background=False\` when this cell needs the answer; the text sits in \`"output"\`, a list of content blocks:
+
+\`\`\`python
+from __dsh__.tools import <delegation-tool> as delegate
+import asyncio, json
+
+LIMIT = asyncio.Semaphore(4)   # a dozen children racing for one upstream finish later than a few at a time
+
+async def ask(desc, prompt, timeout=600):
+    async with LIMIT:   # a gather waits out its slowest member forever, so give every child a deadline
+        r = await asyncio.wait_for(delegate(description=desc, prompt=prompt, run_in_background=False), timeout)
+    return "".join(b.get("text", "") for b in r["output"] if isinstance(b, dict))
+
+def as_json(text):   # the child tends to wrap its JSON in a sentence
+    return json.loads(text[text.index("{"):text.rindex("}") + 1])
+\`\`\`
+
+**Carry each item through its own chain instead of stage by stage.** Gather the chains, not the stages, so one item is being verified while another is still being found:
+
+\`\`\`python
+SCHEMA = '{"refuted": true, "reason": "why"}'   # example VALUES: a child handed {"refuted": bool} copies that literally, and the parse dies rather than the work
+
+async def survives(claim):
+    verdict = await ask("refute", f"Refute this, and default to refuted when unsure: {claim}. Reply as JSON: {SCHEMA}")
+    return not as_json(verdict)["refuted"]
+
+async def chain(dim):
+    claims = as_json(await ask(f"review {dim}", PROMPTS[dim]))["findings"]
+    votes = await asyncio.gather(*(survives(c) for c in claims))
+    return [c for c, ok in zip(claims, votes) if ok]
+
+rows = await asyncio.gather(*(chain(d) for d in DIMENSIONS), return_exceptions=True)
+kept = [c for row in rows if not isinstance(row, BaseException) for c in row]
+\`\`\`
+
+Wall-clock is then the slowest single chain rather than the sum of the slowest per stage. Reach for a barrier only where the next step needs the whole previous one at once — dedup, an early exit, ranking candidates against each other.
+
+Isolate every child's failure, the way \`return_exceptions=True\` does above: one that dies on its token limit or answers unparseably otherwise takes the whole batch with it, and the siblings that did finish are worth more than the round.
+
+Keep each prompt to what only that child could be told — point it at a path and let it read the file, since it shares this filesystem. Pasting a file into a prompt is what walks a child into that limit.
+
+The shape need not be settled before the first call either: keep running rounds while one still turns up something new, deduping against everything SEEN rather than against what survived — dedup against the survivors and every rejected claim comes back next round.
+`
+
+/**
+ * Whether any visible tool delegates to a subagent, detected by the SHAPE of its declared output rather than by name: `toolName` is configurable (`dsh-tool-subagent` defaults to `subagent`), so a name test would miss a renamed mount, and the three-branch union below is one no other tool in a stock catalogue declares.
+ *
+ * The branches are a static literal in `dsh-tool-subagent` — `background` and `continuable` stay in the schema even where config cannot reach them — so this holds regardless of how that plugin is configured.
+ */
+function hasDelegationTool(schemas) {
+  return schemas.some((schema) => {
+    const branches = schema.output?.oneOf
+    if (!Array.isArray(branches)) return false
+    return ['foreground', 'background', 'continuable'].every((expected) => branches.some((b) => b?.properties?.kind?.const === expected))
+  })
+}
+
 /**
  * The wrapper dsh's MCP client puts around every result: `{ content, structuredContent? }`, with
  * `content` the protocol's block array and `structuredContent` the server's own payload. Detected
@@ -564,6 +633,21 @@ function renderCell(result) {
   return sections.join('\n') || '[[ execution successful, no output ]]'
 }
 
+/**
+ * The hand-written prose that reaches `ctx.systemPrompt.section({text})` verbatim.
+ *
+ * dsh-system-prompt reads `{{` in section text as a variable reference, and a malformed one throws during ASSEMBLY — which takes down every session on the preset rather than degrading one prompt. The per-tool prose inside the sdk section is escaped by `escapePromptGroups` on its way through the renderer; these literals have no such pass, so they are asserted brace-free at mount instead, keeping the text the one thing a reader of the source can trust.
+ *
+ * `ORCHESTRATION` and `INSTRUCTIONS` are the ones carrying Python that shows JSON shapes, where an f-string's doubled literal brace is the easy mistake. `RESTART_NOTICE` is deliberately absent: it is injected as a transcript message, which never passes through `interpolate`.
+ *
+ * Exported so the suite can put each one through the real renderer, rather than restating the check.
+ */
+export const HAND_WRITTEN_PROSE = [
+  { label: 'code-only', text: EXCLUSIVE_RULE },
+  { label: 'sdk', text: INSTRUCTIONS },
+  { label: 'orchestration', text: ORCHESTRATION },
+]
+
 export const name = PLUGIN_NAME
 export const inject = ['tools', 'systemPrompt']
 
@@ -615,6 +699,18 @@ export function apply(ctx, config = {}) {
     text: (assembly) => renderToolsSection(visibleSchemas(assembly.scope)),
   })
 
+  for (const { label, text } of HAND_WRITTEN_PROSE) {
+    const run = /\{{2,}/.exec(text)
+    if (run !== null) throw new Error(`dsh-py-codeact: the ${label} section contains "${run[0]}", which dsh-system-prompt parses as a variable reference`)
+  }
+
+  // Empty string where no delegation tool is mounted, the way `dsh-tool-subagent` blanks its own `tool:subagent` section: a section describing a fan-out the model has no way to perform is several hundred characters of standing misdirection.
+  ctx.systemPrompt.section({
+    name: 'py-codeact:orchestration',
+    order: ORCHESTRATION_SECTION_ORDER,
+    text: (assembly) => (hasDelegationTool(visibleSchemas(assembly.scope)) ? ORCHESTRATION : ''),
+  })
+
   // Injected at the seam rather than carried as a prompt section, because the position IS the information: everything above the notice ran in an interpreter that no longer exists, everything below runs in the new one. A section states the fact but cannot say where the boundary fell — and the model reads the transcript in order.
   ctx.on('agent/session-start', ({ agent }) => {
     // `session-start` also fires for `compact` and `clear`, where the interpreter is very much alive — and a resume inside the SAME process finds its kernel still running. Only an actually-absent interpreter means the bindings died.
@@ -660,7 +756,9 @@ export function apply(ctx, config = {}) {
       console.warn(`[dsh-py-codeact] no agent on execution ${exec.callId}: sub-calls will run but not appear as SUBTOOL rows`)
     }
     const trace = { rootCallId: exec.rootCallId, parentCallId: exec.callId, subCallId, name, arguments: args }
-    session?.append('tool/code-dispatch-start', trace)
+    // V3 rejects the old Code Mode tags even though their payload is unchanged. Older hosts in our peer range still require them.
+    const dispatchEvent = session?.header?.version >= 3 ? 'tool/ptc-dispatch' : 'tool/code-dispatch'
+    session?.append(`${dispatchEvent}-start`, trace)
 
     // Every outcome has to emit the terminal event, throws included: if `ctx.tools.execute` rejects rather than returning `{isError:true}` (an abort, a policy wrapper throwing), the Python side is still answered, but the SUBTOOL row would sit in the trajectory as "running" forever.
     try {
@@ -674,7 +772,7 @@ export function apply(ctx, config = {}) {
         signal: exec.signal,
       })
 
-      session?.append('tool/code-dispatch', { ...trace, isError: outcome.isError, content: outcome.content })
+      session?.append(dispatchEvent, { ...trace, isError: outcome.isError, content: outcome.content })
       // Pixels cannot travel through the bridge: `value` is JSON, so a `read_image` result reaches the cell as width/height/attachmentId and NOTHING to look at. Re-attach the blocks the way Code Mode does, and the image lands in the conversation right after this cell — the model sees it on its next step. Without this the model believes the call succeeded, gets metadata, and cannot tell why it still cannot see anything.
       if (!outcome.isError && contentHasImage(outcome.content ?? [])) {
         exec.deferContext(createUserMessage({ content: outcome.content, source: { kind: 'plugin', plugin: 'dsh-py-codeact' } }))
@@ -684,7 +782,7 @@ export function apply(ctx, config = {}) {
       // falling back to the wrapper there would hand the cell the one shape it was promised not to see.
       return toolCallReply(outcome, entry.envelopes.get(from)?.has(name))
     } catch (error) {
-      session?.append('tool/code-dispatch', { ...trace, isError: true, content: [{ type: 'text', text: String(error?.message ?? error) }] })
+      session?.append(dispatchEvent, { ...trace, isError: true, content: [{ type: 'text', text: String(error?.message ?? error) }] })
       throw error
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-py-codeact",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "CodeAct agent loop for the DeepSeek Harness: a persistent IPython session as the model's action space, with harness tools bridged in as a virtual `__dsh__.tools` module.",
   "license": "MIT",
   "repository": {

package/py/kernel.py

@@ -49,7 +49,6 @@ import inspect
 import io
 import json
 import keyword
-import select
 import sys
 import traceback
 import types
@@ -186,6 +185,7 @@ class Bridge:
         self._send = send
         self._pending: dict = {}
         self._next = 0
+        self._sends: set = set()  # hold fire-and-forget send tasks so the GC cannot drop a `call` frame mid-flight
 
     def call(self, name: str, args):
         self._next += 1
@@ -194,7 +194,21 @@ class Bridge:
         self._pending[call_id] = future
         # There is ONE Bridge for the whole process, so the frame has to say which shell is calling or the host cannot tell a parent's in-flight call from a subagent's. The ContextVar already routes stdout, the displayhook and `__dsh__.tools` the same way, and `create_task` snapshots it — so a task the model detached keeps naming the shell that created it.
         session = _current_session.get()
-        self._send({"t": "call", "id": call_id, "shell": None if session is None else session.shell_id, "name": name, "args": args})
+
+        # `_send` is async (it yields to the loop while the fd-3 buffer drains), but `call` stays sync so the binding can `return await bridge.call(...)` and hand the cell the Future itself to await — `await` on a coroutine that returned a Future would hand the cell a pending Future instead of its resolved value. A `call` frame is tiny, so fire it as a task: it runs immediately and only yields if the buffer is full, never blocking the caller. If `_send` itself raises (e.g. json.dumps hitting a raising __str__), fail the call instead of hanging the awaiter — the future's done callback then pops `_pending`.
+        async def _send_call():
+            try:
+                await self._send({"t": "call", "id": call_id, "shell": None if session is None else session.shell_id, "name": name, "args": args})
+            except Exception as exc:  # noqa: BLE001 - _send is host-provided; any failure must not leak the future
+                if not future.done():
+                    future.set_exception(exc)
+
+        send = asyncio.create_task(_send_call())
+        send.add_done_callback(self._sends.discard)
+        self._sends.add(send)
+
+        # One done callback for both jobs. Popping `_pending` is the leak safety net: if the host never replies, or `_send` raised and we failed the future ourselves, or a `wait_for` timeout cancelled it, the entry still leaves. Cancelling `send` is the side-effect one: a cancelled or timed-out call whose frame has not gone out yet must not reach the host at all, or the tool runs and its side effects land after the cell already reported the call as cancelled. A frame mid-write is past that point — `_send` holds the lock and shields the drain wait, so it finishes the line rather than splicing the next frame onto a stump.
+        future.add_done_callback(lambda _: (self._pending.pop(call_id, None), send.cancel()))
         return future
 
     def settle(self, call_id, ok, value, tool, message) -> None:
@@ -215,7 +229,8 @@ def _make_binding(bridge: Bridge, spec):
     renames = {p["name"]: p["raw"] for p in spec.get("params") or [] if p.get("raw")}
 
     async def call(**kwargs):
-        return await bridge.call(name, {renames.get(key, key): value for key, value in kwargs.items()} if renames else kwargs)
+        # A per-call timeout is the orphan-future safety net: if the host never sends a result for this `call_id`, the await raises `TimeoutError` instead of hanging forever, and the done callback registered in `Bridge.call` drops the entry from `_pending`. It must sit ABOVE the 600s delegation budget the prompt teaches (`ask(desc, prompt, timeout=600)`), or the kernel kills a legitimate in-flight subagent while the host is still running it — the side effects land, the late result is dropped, and the model retries and duplicates them.
+        return await asyncio.wait_for(bridge.call(name, {renames.get(key, key): value for key, value in kwargs.items()} if renames else kwargs), 660)
 
     call.__name__ = name if name.isidentifier() else "call"
     call.__qualname__ = f"__dsh__.tools.{name}"
@@ -260,10 +275,12 @@ class ToolsModule(types.ModuleType):
 
     `sys.modules` is process-global, so there is exactly ONE of these no matter how many shells are live — yet each agent sees a different catalogue (a subagent's `toolFilter` narrows it, and restrictions move tools in and out between cells). So the bindings live on the Session and every lookup routes through the ContextVar; putting them in `__dict__` would hand every shell the last writer's catalogue."""
 
+    # A class attribute, not an instance one: normal lookup finds it before `__getattr__` ever runs, and the `__setattr__` guard below cannot touch the class body. `ToolCallError` is a harness-provided exception type the model is told to catch, not a tool binding.
+    ToolCallError = ToolCallError
+
     def __init__(self) -> None:
         super().__init__("__dsh__.tools", "Harness tools, bridged into this session as awaitables.")
         self.__path__ = []  # a package, so `__dsh__.tools.mcp` resolves under it
-        self.ToolCallError = ToolCallError
 
     def __getattr__(self, name):  # only reached when the attribute is absent
         if name.startswith("__"):
@@ -276,6 +293,14 @@ class ToolsModule(types.ModuleType):
         available = ", ".join(sorted(listed_tools())) or "(none)"
         raise AttributeError(f"no such tool: {name!r}. Available: {available}")
 
+    def __setattr__(self, name, value):
+        # One ToolsModule per process, shared by every agent — a write here would shadow that name
+        # for all of them, permanently and invisibly to `dir()`, which keeps reporting the tool it
+        # no longer reaches. The old per-call `Namespace` made this a local mistake.
+        if not (name.startswith("__") and name.endswith("__")):
+            raise AttributeError("__dsh__.tools belongs to the harness and is shared by every agent in this process — bind your own name instead of writing to it")
+        super().__setattr__(name, value)
+
     def __dir__(self):
         return sorted(listed_tools())
 
@@ -400,8 +425,9 @@ def alias(members: dict) -> None:
     `setdefault`, so a name that already exists keeps its own value: a server exposing `a-b` beside
     `a_b` gets no alias for `a-b`, and both stay reachable under their own spellings.
     """
-    for raw in [name for name in members if spellable(name) is not None]:
-        members.setdefault(spellable(raw), members[raw])
+    for raw in list(members):  # a snapshot: `setdefault` below adds the folds mid-loop
+        if (fold := spellable(raw)) is not None:
+            members.setdefault(fold, members[raw])
 
 
 def canonical(server: str, servers: dict) -> str:
@@ -438,8 +464,12 @@ def mcp_members(module_name: str) -> dict:
 
     Deliberately not a method: a non-dunder attribute on the class would shadow a tool or a server
     of that name, and a raw MCP name is the server's to choose — `_private` is a legal one.
+
+    Reads the `mcp_servers` tree cached on the Session by `rebind`, so an attribute access does not
+    rebuild the whole tree (O(n)) when nothing has changed.
     """
-    servers = mcp_servers({name: call for name, call in bound_tools().items() if servable(name) is not None})
+    session = _current_session.get()
+    servers = session.mcp_tree if session is not None else {}  # no session → no bound tools → no tree
     if module_name == MCP_MODULE:
         # Keyed by the FOLDED name so a hyphenated server and its fold resolve to one module object,
         # not two: `listed` tells an alias from a real neighbour by identity, and two objects would
@@ -519,7 +549,7 @@ def mcp_server_module(server: str) -> McpModule:
     return module
 
 
-def install_mcp_modules(bindings: dict) -> None:
+def install_mcp_modules(servers: dict[str, dict]) -> None:
     """Register a module per visible MCP server.
 
     Eager, because the deep import form never reaches `mcp_members`: `from __dsh__.tools.mcp.x
@@ -529,19 +559,27 @@ def install_mcp_modules(bindings: dict) -> None:
     `sys.modules` only ever gains entries: a server another shell can see costs this one an unused
     module, while removing it would break an import that shell is mid-conversation with. What a
     shell can actually reach is decided by `mcp_members`, not by what is registered.
+
+    Takes the grouped tree from `build_bindings` so `rebind` does not rebuild it a second time.
     """
-    for server in mcp_servers(bindings):
+    for server in servers:
         mcp_server_module(server)
 
 
-def build_bindings(bridge: Bridge, specs) -> dict:
-    """Project one agent's visible tools into awaitables for its shell."""
+def build_bindings(bridge: Bridge, specs) -> tuple[dict, dict[str, dict]]:
+    """Project one agent's visible tools into awaitables for its shell.
+
+    Returns `(bindings, mcp_servers)` so `rebind` can hand the grouped tree to
+    `install_mcp_modules` and cache it for `mcp_members` without rebuilding it.
+    """
     # A tool named `ToolCallError` would be shadowed by the module's own attributes, and one named `_rebind` used to overwrite a bound method outright. dsh's own SDK renderer refuses `_`-leading tool names for exactly this collision class.
     # `mcp` joins them, and unconditionally: it used to be bound and then overwritten by the namespace, so the tool was uncallable anyway — but only when an MCP server happened to be mounted. A name that means the namespace in one catalogue and a tool in the next is worse than one that always means the same thing.
-    reserved = set(vars(ToolsModule)) | set(vars(types.ModuleType)) | {"ToolCallError", "mcp"}
+    reserved = set(vars(ToolsModule)) | set(vars(types.ModuleType)) | {"mcp"}
     flat = {spec["name"]: _make_binding(bridge, spec) for spec in specs if not spec["name"].startswith("_") and spec["name"] not in reserved}
     # `mcp` only when something is under it: an empty namespace in `dir()` reads as a broken mount.
-    return {**flat, "mcp": MCP_ROOT} if mcp_servers(flat) else flat
+    servers = mcp_servers(flat)
+    bindings = {**flat, "mcp": MCP_ROOT} if servers else flat
+    return bindings, servers
 
 
 def install_bridge_modules() -> ToolsModule:
@@ -611,7 +649,7 @@ class Capped(io.TextIOBase):
     """Byte-capped StringIO stand-in for one cell's stdout or stderr."""
 
     def __init__(self, limit: int) -> None:
-        self.parts: list = []
+        self.parts: list[bytes] = []
         self.size = 0
         self.limit = limit
         self.truncated = False
@@ -623,11 +661,11 @@ class Capped(io.TextIOBase):
                 room = self.limit - self.size
                 if room > 0:
                     # "ignore", not "replace": slicing encoded bytes at the cap can land mid-character, and "replace" would hand the model a U+FFFD. Dropping the partial character is honest.
-                    self.parts.append(chunk[:room].decode("utf-8", "ignore"))
+                    self.parts.append(chunk[:room])
                     self.size += room
                 self.truncated = True
             else:
-                self.parts.append(s)
+                self.parts.append(chunk)
                 self.size += len(chunk)
         return len(s)
 
@@ -635,7 +673,7 @@ class Capped(io.TextIOBase):
         return True
 
     def text(self) -> str:
-        body = "".join(self.parts)
+        body = b"".join(self.parts).decode("utf-8", "ignore")
         return f"{body}\n[dsh-py-codeact] output truncated at {self.limit} bytes" if self.truncated else body
 
 
@@ -651,6 +689,14 @@ class Session:
         history = Config()
         history.HistoryAccessor.hist_file = ":memory:"
         self.shell = InteractiveShell(user_ns=namespace, config=history)
+        # The specs last bound, so an identical catalogue (the common case — a restriction that
+        # did not change anything, or the same tools re-sent) skips `rebind` and its per-tool
+        # callable + signature rebuild. `None` means "nothing bound yet"; `==` on the parsed
+        # structures still catches a catalogue the host re-serialised, which identity would miss.
+        self._last_specs: list | None = None
+        # The grouped `mcp_servers` tree from the last `rebind`, cached so `mcp_members` reads it
+        # (O(1) lookup) instead of rebuilding it on every attribute access.
+        self.mcp_tree: dict[str, dict] = {}
         self.rebind(bridge, specs)
         self.sinks: list = [None, None]  # the Capped buffers of the cell in flight
         install_bridge_modules()
@@ -704,9 +750,23 @@ class Session:
         The one place the `sys.modules` registration lives, so `build_bindings` stays the pure
         projection its name promises and no caller can produce bindings the import machinery
         cannot follow.
+
+        Skipped when the specs equal the last bound set: `build_bindings` rebuilds
+        every tool callable + `inspect.Signature` per exec, and the common case is a catalogue that
+        never changed between cells. `==` on the parsed structures catches a catalogue the host
+        re-serialised, which object identity would miss.
         """
-        self.bindings = build_bindings(bridge, specs)
-        install_mcp_modules(self.bindings)
+        if specs == self._last_specs:
+            return
+        self.bindings, servers = build_bindings(bridge, specs)
+        install_mcp_modules(servers)
+        # `mcp_members` reads a servable-filtered tree: a true-dunder raw name (e.g. `__odd__`) is
+        # reachable via the flat name and the deep import, never via `mcp.<server>.<tool>`, so the
+        # server it sits under is absent from `dir(mcp)`. `install_mcp_modules` takes the unfiltered
+        # tree so the server module is still registered for the deep import form.
+        self.mcp_tree = mcp_servers({name: call for name, call in self.bindings.items() if servable(name) is not None})
+        # Recorded only once the build above has succeeded: a memo written before a raising spec would make a retry with the same specs early-return and silently serve the stale catalogue.
+        self._last_specs = specs
 
     def format_exc(self) -> str:
         """IPython's own traceback, rendered without ANSI colors."""
@@ -767,23 +827,48 @@ class Kernel:
     def __init__(self) -> None:
         self._out = os.fdopen(PROTOCOL_FD, "wb", buffering=0)
         self._bridge = Bridge(self._send)
+        # One frame at a time: `call` frames fire as tasks beside the `done`/`ready` frames this loop awaits, and a sender that yields mid-frame (buffer full) must not let another write into the gap — the host's `readline` would see two spliced frames and drop both.
+        self._send_lock = asyncio.Lock()
         # One Session per agent, one in-flight task per Session. Keyed by the shell id the host assigns; a fan-out of subagents lands here as N entries sharing this process, its event loop and its packages.
         self._sessions: dict = {}
         self._tasks: dict = {}
 
-    def _send(self, frame: dict) -> None:
+    async def _send(self, frame: dict) -> None:
         # fd 3 is NON-BLOCKING: `asyncio.connect_read_pipe` sets O_NONBLOCK on it, and Node's `stdio[3]: 'pipe'` is one duplex socketpair, so the read and write ends are the same descriptor. A raw `write()` therefore stops at the socket send buffer (8 KiB on macOS) and reports how far it got — ignoring that return value truncated the frame mid-JSON, silently, and the next frame was concatenated onto the stump. The host then dropped one unparsable blob and the session wedged for good. `default=str` so the natural CodeAct idiom just works: the model globs with `pathlib` and passes the `Path` straight into a tool. Coercing here beats making every call site write `str(p)` — and beats a `TypeError` raised mid-frame, which is what used to happen. Same for `datetime`, `Decimal`, `UUID`, numpy scalars.
         # `errors="replace"` is load-bearing, not tidiness: a lone surrogate — routine from `surrogateescape` decoding, or any `Path` on a non-UTF-8 filename — passes `json.dumps` and then raises `UnicodeEncodeError` here. This send is what answers an exec, so a raise means no `done` frame ever arrives and the turn hangs forever. A U+FFFD in one string beats a wedged session.
         payload = memoryview((json.dumps(frame, ensure_ascii=False, default=str) + "\n").encode("utf-8", errors="replace"))
-        while payload:
-            try:
-                written = self._out.write(payload)
-            except BlockingIOError:
-                written = None
-            if written is None:  # the buffer is full; wait for the host to drain it
-                select.select([], [PROTOCOL_FD], [])
-                continue
-            payload = payload[written:]
+        loop = asyncio.get_running_loop()
+        async with self._send_lock:
+            cancelled = False
+            while payload:
+                try:
+                    written = self._out.write(payload)
+                except BlockingIOError:
+                    written = None
+                if written is None:  # the buffer is full; wait for the host to drain it — a bare `sleep(0)` would hot-spin a core until it does
+                    drained = loop.create_future()
+                    loop.add_writer(PROTOCOL_FD, self._writable, drained)
+                    try:
+                        await asyncio.shield(drained)
+                    except asyncio.CancelledError:
+                        # A cancel must not abandon a half-written frame: the next send splices onto the stump, the host drops both lines, and the aborted exec's `done` never arrives — the 5s `hardInterruptMs` backstop then SIGKILLs the whole kernel. Finish this frame first, then let the cancel through; the host answers a `done` once, so the replacement frame `_exec` sends next is ignored, not fatal.
+                        cancelled = True
+                    finally:
+                        loop.remove_writer(PROTOCOL_FD)  # a no-op when the callback already removed it; cancels a queued-but-unrun one
+                    continue
+                payload = payload[written:]
+            if cancelled:
+                raise asyncio.CancelledError
+
+    @staticmethod
+    def _writable(drained) -> None:
+        # Remove INSIDE the callback: a level-triggered selector re-fires a still-registered writer on every poll, and the future's done callbacks are `call_soon`-scheduled — the sender's `finally` above runs two loop batches later, by which time a re-fire would `set_result` on the already-done future.
+        asyncio.get_running_loop().remove_writer(PROTOCOL_FD)
+        drained.set_result(None)
+
+    def _busy(self, shell) -> bool:
+        running = self._tasks.get(shell)
+        return running is not None and not running.done()
 
     def _session_for(self, shell, specs=None) -> Session:
         session = self._sessions.get(shell)
@@ -813,16 +898,15 @@ class Kernel:
                 "repr": None,
                 "note": None,
             }
-        self._send(frame)
+        await self._send(frame)
 
-    def _handle(self, frame: dict) -> None:
+    async def _handle(self, frame: dict) -> None:
         kind = frame.get("t")
         shell = frame.get("shell") or DEFAULT_SHELL
         if kind == "exec":
-            running = self._tasks.get(shell)
-            if running is not None and not running.done():
+            if self._busy(shell):
                 # Answer BEFORE rebinding: a rejected exec must not swap the tool table under the cell that is still running, or a binding it captured (`from __dsh__.tools import read`) can change identity — or vanish — between its start and its next await. The check is per shell: another agent's cell running is not a conflict.
-                self._send(
+                await self._send(
                     {"t": "done", "id": frame.get("id"), "shell": shell, "ok": False, "stdout": "", "stderr": "", "error": "kernel busy: a previous cell is still running", "repr": None, "note": None}
                 )
                 return
@@ -832,12 +916,15 @@ class Kernel:
         elif kind == "result":
             self._bridge.settle(frame.get("id"), bool(frame.get("ok")), frame.get("value"), frame.get("tool"), frame.get("message"))
         elif kind == "interrupt":
-            running = self._tasks.get(shell)
-            if running is not None and not running.done():
-                running.cancel()
+            # A synchronous CPU-bound cell (`while True: pass`) blocks the event loop inside `exec`, so this interrupt frame sits unread and `task.cancel()` can't fire until the next `await` yields back to the loop.
+            if self._busy(shell):
+                self._tasks[shell].cancel()
         elif kind == "init":
-            self._session_for(shell, frame.get("tools") or [])
-            self._send(
+            # Mirror the exec branch's two guards: a non-list `tools` would raise inside `build_bindings` (caught only by `serve`'s broad `except`, which swallows the `ready` frame and wedges the host), and a re-init while a cell is running must not rebind the tool table under it. `ready` is always sent — init is idempotent, so the existing bindings stay valid when we skip.
+            specs = frame.get("tools")
+            if isinstance(specs, list) and not self._busy(shell):
+                self._session_for(shell, specs)
+            await self._send(
                 {
                     "t": "ready",
                     "shell": shell,
@@ -851,8 +938,10 @@ class Kernel:
                 }
             )
         elif kind == "dispose":
-            # The agent is gone; drop its shell so its globals can be collected.
-            self._tasks.pop(shell, None)
+            # The agent is gone; cancel any in-flight cell, then drop its shell so its globals can be collected.
+            running = self._tasks.pop(shell, None)
+            if running is not None and not running.done():
+                running.cancel()
             self._sessions.pop(shell, None)
 
     async def serve(self) -> None:
@@ -864,7 +953,12 @@ class Kernel:
             os.fdopen(PROTOCOL_FD, "rb", buffering=0),
         )
         while True:
-            line = await reader.readline()
+            try:
+                line = await reader.readline()
+            except ValueError:
+                # a line over the 16 MiB limit overflows the buffer; it is already drained, so skipping is safe — but say so: the host's exec never gets its `done` and the turn hangs, and a silent drop hides why
+                print("[dsh-py-codeact] dropped a frame over the 16 MiB line limit", file=REAL_STDERR)
+                continue
             if not line:
                 return  # host closed fd 3
             try:
@@ -876,7 +970,7 @@ class Kernel:
             if frame.get("t") == "shutdown":
                 return
             try:
-                self._handle(frame)
+                await self._handle(frame)
             except Exception:  # noqa: BLE001 — one malformed frame must not take the interpreter down
                 # `_handle` runs directly in this loop: an exception here unwinds out of `asyncio.run` and takes the interpreter — and the whole session's state — with it. One malformed frame is not worth that; a `result` whose `id` is unhashable used to do exactly it.
                 print(f"[dsh-py-codeact] dropped a frame that raised: {traceback.format_exc()}", file=REAL_STDERR)