@hicaru/pi-rlm 0.3.6 → 0.3.8

package/src/sandbox/py/worker.py

@@ -39,33 +39,15 @@ from guards import (
     _CONTEXT_NAME,
     _send,
     _stall_alarm,
-    _surfaced_error,
+    _stall_message,
+    _StallTimeout,
     RESERVED,
     REAL_STDERR as _REAL_STDERR,
     REAL_STDIN as _REAL_STDIN,
 )
 from hostio import read_host_payload
-from retrieval import (
-    _Bm25Index,
-    _chunk_text,
-    _context_entries,
-    _CHUNK_HEADER_OVERHEAD,
-    _MAX_CHUNK_BATCH,
-    _MAX_CHUNKS,
-    _NUDGE_CHARS,
-    grep_context as _grep_context_impl,
-    outline as _outline_impl,
-    search as _search_impl,
-)
-from tasks import (
-    _clean_paths,
-    _reduce_batch,
-    _reduce_chunked,
-    _reduce_map_files,
-    _reduce_one,
-    _spawnable,
-    Task,
-)
+from retrieval import _Bm25Index, _NUDGE_CHARS
+from tasks import Task
 
 class _AnswerDict(dict):
     """`answer` dict; flipping `ready` True captures the final answer for the parent."""
@@ -83,18 +65,25 @@ class _AnswerDict(dict):
 
 
 
-class Worker:
+from scaffold import WorkerScaffold
+
+
+class Worker(WorkerScaffold):
     def __init__(
         self,
         depth: int,
         exec_timeout_s: float,
         max_prompt_chars: int,
         await_timeout_s: float = 600.0,
+        surface: str = "root",
     ):
         self.depth = depth
         self.exec_timeout_s = exec_timeout_s
         self.max_prompt_chars = max_prompt_chars
         self.await_timeout_s = await_timeout_s
+        # v5 role separation: "child" installs the delegation-only scaffold (no retrieval —
+        # a child's world arrives as text via getChildContext; retrieval belongs to the root).
+        self.surface = surface
         self._rid = 0
         self._final_answer: str | None = None
         # Replies parked by rid until something awaits them. Unbounded by design: a task
@@ -103,6 +92,9 @@ class Worker:
         # await_task, which is strictly worse than the memory.
         self.inbox: dict[str, dict[str, Any]] = {}
         self._inflight: set[str] = set()
+        # Every Task this worker created. Survives the model deleting the bound name, so
+        # await_task() / list_tasks() can still collect a spawn the model forgot to store.
+        self._handles: list[Task] = []
         # Requests (exec/shutdown) that arrived mid-exec; main() replays them.
         self._deferred: list[Any] = []
         # Kept for spawn() compatibility; sub-LLM kinds always post detached=true so fan-out
@@ -135,18 +127,23 @@ class Worker:
         ns["spawn"] = self._spawn
         # One collect API: await_task(Task) or await_task([Task, ...])
         ns["await_task"] = self._await_task
+        ns["list_tasks"] = self._list_tasks
         ns["map_files"] = self._map_files
         ns["llm_map_reduce"] = self._llm_map_reduce
-        ns["search"] = self._search
-        ns["grep_context"] = self._grep_context
-        ns["outline"] = self._outline
-        # env_tips memo (paper App. C.3): "If a value isn't in `answers`, it doesn't exist."
+        if self.surface != "child":
+            ns["search"] = self._search
+            ns["grep_context"] = self._grep_context
+            ns["outline"] = self._outline
+        # env_tips memo: collected *results* live in `answers`; Task handles live in REPL vars.
         # Re-created only when deleted — contents must survive every turn.
         if not isinstance(ns.get("answers"), dict):
             ns["answers"] = {}
         if not isinstance(ns.get("plan"), dict):
             ns["plan"] = {}
-        ns["add_context"] = self._add_context
+        if self.surface != "child":
+            ns["add_context"] = self._add_context
+        ns["list_claims"] = self._list_claims
+        ns["memory"] = self._memory_api()
         ns["SHOW_VARS"] = self._show_vars
         if not isinstance(ns.get("answer"), _AnswerDict):
             cur = ns.get("answer")
@@ -180,7 +177,10 @@ class Worker:
         ]
 
     def _show_vars(self) -> str:
-        avail = {k: type(self.ns[k]).__name__ for k in self._user_var_names()}
+        avail: dict[str, str] = {}
+        for k in self._user_var_names():
+            v = self.ns[k]
+            avail[k] = repr(v) if isinstance(v, Task) else type(v).__name__
         return f"Available variables: {avail}" if avail else "No variables created yet."
 
     # ---- sub-LLM bridge over stdio --------------------------------------------------------
@@ -234,23 +234,29 @@ class Worker:
             return True
         if self.park_reply(msg):
             return True
+        if isinstance(msg, dict) and msg.get("type") == "heartbeat":
+            return True
         # A request (exec/shutdown) arriving mid-exec: main() replays it.
         self._deferred.append(msg)
         return True
 
-    def _drain_until(self, rids) -> None:
+    def _drain_until(self, rids) -> bool:
         """Block until every rid in `rids` has its reply parked in the inbox.
 
-        Bounded: a host that goes silent raises inside the ```repl``` block instead of hanging
-        the session forever.
+        Returns False if the host stayed silent for `await_timeout_s` — the Task is
+        not settled; a later await_task can collect it. A closed pipe still raises.
         """
         if all(r in self.inbox for r in rids):
-            return
-        with _stall_alarm(self.exec_timeout_s, self.await_timeout_s) as rearm:
-            while not all(r in self.inbox for r in rids):
-                if not self._pump():
-                    raise RuntimeError("parent closed the pipe during a sub-LLM request")
-                rearm()
+            return True
+        try:
+            with _stall_alarm(self.exec_timeout_s, self.await_timeout_s) as rearm:
+                while not all(r in self.inbox for r in rids):
+                    if not self._pump():
+                        raise RuntimeError("parent closed the pipe during a sub-LLM request")
+                    rearm()
+        except _StallTimeout:
+            return False
+        return True
 
     def _take(self, rids) -> list[dict[str, Any]]:
         return [self.inbox.pop(r) for r in rids]
@@ -258,475 +264,10 @@ class Worker:
     def _rpc(self, kind: str, payload: dict[str, Any]) -> dict[str, Any]:
         """Post one request and block for its reply — the synchronous single-shot path."""
         rid = self._post(kind, payload)
-        self._drain_until((rid,))
+        if not self._drain_until((rid,)):
+            return {"error": _stall_message(self.await_timeout_s)}
         return self._take((rid,))[0]
 
-    # ---- spawn / await ---------------------------------------------------------------------
-
-    def _start_prompt(self, kind: str, prompt, paths=None) -> Task:
-        text = str(prompt)
-        # A sub-LLM asked nothing answers something: the confabulation then sits in `answers`
-        # looking exactly like data. Refuse instead of spending a call on it.
-        if not text.strip():
-            return Task.resolved(self, kind, _surfaced_error(
-                f"{kind}() got an empty prompt — a sub-LLM would confabulate an answer to nothing"))
-        payload: dict[str, Any] = {"prompt": text}
-        clean = _clean_paths(paths)
-        if clean is not None:
-            payload["paths"] = clean
-        rid = self._post(kind, payload)
-        return Task(self, kind, (rid,), _reduce_one, text[:40])
-
-    def _start_prompts(self, kind: str, prompts, paths=None) -> Task:
-        prompts = [str(p) for p in prompts]
-        if not prompts:
-            return Task.resolved(self, kind, [])
-        # Only the all-blank case: one blank prompt among twenty is the caller's business.
-        if not any(p.strip() for p in prompts):
-            return Task.resolved(self, kind, [
-                _surfaced_error(f"{kind}() got only empty prompts")
-            ] * len(prompts))
-        payload: dict[str, Any] = {"prompts": prompts}
-        # One prefix set for the whole batch: a per-prompt aligned list is an API nobody uses
-        # correctly, and every prompt in a batch is asking about the same slice anyway.
-        clean = _clean_paths(paths)
-        if clean is not None:
-            payload["paths"] = clean
-        rid = self._post(kind, payload)
-        return Task(self, kind, (rid,), _reduce_batch(len(prompts)), f"×{len(prompts)}")
-
-    def _start_llm_query(self, prompt) -> Task:
-        return self._start_prompt("llm_query", prompt)
-
-    def _start_rlm_query(self, prompt, paths=None) -> Task:
-        return self._start_prompt("rlm_query", prompt, paths)
-
-    def _start_llm_batch(self, prompts) -> Task:
-        return self._start_prompts("llm_batch", prompts)
-
-    def _start_rlm_batch(self, prompts, paths=None) -> Task:
-        return self._start_prompts("rlm_batch", prompts, paths)
-
-    def _start_llm_query_chunked(self, text, prompt: str) -> Task:
-        """Split oversized text into cap-sized chunks and post EVERY batch at once.
-
-        One answer per chunk, order preserved. No exceptions escape: errors come back as
-        "Error: ..." strings per chunk (same contract as llm_batch). Because all
-        batches go on the wire together, a large input costs one round-trip of latency
-        rather than one per 20 chunks.
-
-        NOTE: budget uses Python code-point length (len) while the parent-side cap check counts
-        UTF-16 units (JS string.length); astral/emoji-heavy text may be marginally larger on the
-        parent and get per-chunk rejected. Acceptable trade-off for typical code/log/profile text.
-        """
-        text, prompt = str(text), str(prompt)
-        if not text:
-            return Task.resolved(self, "llm_query_chunked", [])
-        budget = self.max_prompt_chars - len(prompt) - _CHUNK_HEADER_OVERHEAD
-        if budget < 1_000:
-            return Task.resolved(self, "llm_query_chunked", [
-                f"Error: prompt leaves under 1,000 chars per chunk (cap {self.max_prompt_chars:,}) — shorten the instruction"
-            ])
-        chunks = _chunk_text(text, budget)
-        total = len(chunks)
-        if total > _MAX_CHUNKS:
-            return Task.resolved(self, "llm_query_chunked", [
-                f"Error: {total} chunks would be needed — filter/slice the text in Python first"
-            ])
-        rids: list[str] = []
-        sizes: list[int] = []
-        for i in range(0, total, _MAX_CHUNK_BATCH):
-            batch = [
-                f"{prompt}\n\n[chunk {i + j + 1}/{total} of the input]\n{c}"
-                for j, c in enumerate(chunks[i:i + _MAX_CHUNK_BATCH])
-            ]
-            rids.append(self._post("llm_batch", {"prompts": batch}))
-            sizes.append(len(batch))
-        return Task(self, "llm_query_chunked", tuple(rids), _reduce_chunked(sizes), f"{total} chunks")
-    def _builder_for(self, name: str):
-        # llm_map_reduce is deliberately absent: its reduce step is a SECOND sub-LLM call that
-        # depends on its own map results, so it cannot be one (rids, pure reduce) Task.
-        return {
-            "llm_query": self._start_llm_query,
-            "llm_batch": self._start_llm_batch,
-            "llm_query_chunked": self._start_llm_query_chunked,
-            "map_files": self._start_map_files,
-            "rlm_query": self._start_rlm_query,
-            "rlm_batch": self._start_rlm_batch,
-        }.get(name)
-
-    def _spawn(self, fn, *args, **kwargs) -> Task:
-        """Start a sub-call without waiting for it. `fn` is the scaffold function itself.
-
-        Returns a Task for await_task, possibly in a later ```repl``` block.
-        Misuse returns an already-resolved error Task rather than raising, matching the
-        "Error: ..." contract of the synchronous helpers.
-        """
-        name = getattr(fn, "_rlm_name", None)
-        builder = self._builder_for(name) if isinstance(name, str) else None
-        if builder is None:
-            return Task.resolved(self, "spawn", _surfaced_error(
-                "spawn() takes llm_query, llm_batch, llm_query_chunked, map_files, "
-                "rlm_query or rlm_batch — not llm_map_reduce, whose reduce step depends "
-                "on its own map results and so cannot be a single Task"))
-        # Sub-LLM kinds already post detached via _post; keep the flag for clarity / future kinds.
-        self._detached = True
-        try:
-            return builder(*args, **kwargs)
-        except TypeError as e:
-            return Task.resolved(self, "spawn", _surfaced_error(f"bad spawn arguments — {e}"))
-        finally:
-            self._detached = False
-
-    def _await_one(self, task: Task) -> Any:
-        """Block until one Task has its result. Idempotent — the value is memoized."""
-        if not task._settled:
-            self._drain_until(task._rids)
-            task._value = task._reduce(self._take(task._rids))
-            task._settled = True
-        return task._value
-
-    def _await_task(self, task_or_tasks) -> Any:
-        """Collect result(s). Accepts a single Task or a list/tuple of Tasks.
-
-        Canonical name for the model: await_task(...). (bare `await` is a Python keyword.)
-        """
-        if isinstance(task_or_tasks, Task):
-            return self._await_one(task_or_tasks)
-        if isinstance(task_or_tasks, (list, tuple)):
-            tasks = list(task_or_tasks)
-            union: list[str] = []
-            seen: set[str] = set()
-            for t in tasks:
-                if not isinstance(t, Task) or t._settled:
-                    continue
-                for rid in t._rids:
-                    if rid not in seen:
-                        seen.add(rid)
-                        union.append(rid)
-            if union:
-                self._drain_until(union)
-            out: list[Any] = []
-            for t in tasks:
-                if isinstance(t, Task):
-                    out.append(self._await_one(t))
-                else:
-                    out.append(
-                        _surfaced_error(
-                            f"await_task expects Task items, got {type(t).__name__}"
-                        )
-                    )
-            return out
-        return _surfaced_error(
-            f"await_task expects a Task or list of Tasks, got {type(task_or_tasks).__name__}"
-        )
-
-    # ---- deterministic retrieval (no sub-LLM calls, no root tokens) -----------------------
-
-    def _entries(self) -> list[tuple[str, str]]:
-        return _context_entries(self.ns.get("context"))
-
-    def _get_index(self) -> _Bm25Index:
-        """Build the BM25 index on first use; rebuild when `context` was replaced or resized.
-
-        Identity+length is a cheap stamp that catches the two ways context actually changes:
-        add_context() extending the list, and the model re-binding the name. In-place edits
-        that preserve length are not detected — documented, and rare in practice.
-        """
-        ctx = self.ns.get("context")
-        stamp = (id(ctx), len(ctx) if isinstance(ctx, (list, str)) else 0)
-        if self._index is None or self._index_stamp != stamp:
-            self._index = _Bm25Index(self._entries())
-            self._index_stamp = stamp
-        return self._index
-
-    def _search(self, query: str, k: int = 10, path_glob: str | None = None) -> list[dict[str, Any]]:
-        """Rank `context` windows against a natural-language query (BM25).
-
-        Returns [{path, line, score, snippet}] — pointers, not bodies.
-        """
-        return _search_impl(self._entries(), self._get_index(), query, k, path_glob)
-
-    def _grep_context(
-        self,
-        pattern: str,
-        k: int = 50,
-        path_glob: str | None = None,
-        before: int = 0,
-        after: int = 0,
-    ) -> dict[str, Any]:
-        """Regex over `context`, capped and shaped. See retrieval.grep_context."""
-        return _grep_context_impl(self._entries(), pattern, k, path_glob, before, after)
-
-    def _outline(self, path: str) -> str:
-        """Definition/heading skeleton of one context file. See retrieval.outline."""
-        return _outline_impl(self._entries(), path)
-
-    # ---- one-line delegation (structural: orchestrating must be easier than solving) -------
-
-    def _start_map_files(self, files: Any, prompt: str) -> Task:
-        """Post every batch map_files needs, WITHOUT waiting. Contract: see _map_files.
-
-        All batches go on the wire together, so a 100-file map costs one round-trip of latency
-        rather than one per 20 files.
-        """
-        prompt = str(prompt)
-        by_path: list[tuple[str, str]] = []
-        lookup: dict[str, str] | None = None
-        for item in files if isinstance(files, (list, tuple)) else [files]:
-            if isinstance(item, dict):
-                content = item.get("content", "")
-                by_path.append((str(item.get("path", "?")), content if isinstance(content, str) else str(content)))
-            elif isinstance(item, str):
-                if lookup is None:
-                    lookup = {p: c for p, c in self._entries()}
-                if item in lookup:
-                    by_path.append((item, lookup[item]))
-                else:
-                    by_path.append((item, ""))
-        if not by_path:
-            return Task.resolved(self, "map_files", {})
-
-        # Per-file prompt budget; anything larger is chunked and its answers concatenated.
-        budget = self.max_prompt_chars - len(prompt) - _CHUNK_HEADER_OVERHEAD - 256
-        if budget < 1_000:
-            return Task.resolved(self, "map_files", {
-                p: "Error: prompt too long to leave room for file content" for p, _ in by_path
-            })
-
-        requests: list[str] = []
-        spans: list[tuple[str, int]] = []  # (path, number of chunks contributed)
-        for path, content in by_path:
-            chunks = _chunk_text(content, budget) if len(content) > budget else [content]
-            spans.append((path, len(chunks)))
-            for j, chunk in enumerate(chunks):
-                header = f"[file {path}" + (f", part {j + 1}/{len(chunks)}]" if len(chunks) > 1 else "]")
-                requests.append(f"{prompt}\n\n{header}\n{chunk}")
-
-        rids: list[str] = []
-        sizes: list[int] = []
-        for i in range(0, len(requests), _MAX_CHUNK_BATCH):
-            batch = requests[i:i + _MAX_CHUNK_BATCH]
-            rids.append(self._post("llm_batch", {"prompts": batch}))
-            sizes.append(len(batch))
-        return Task(self, "map_files", tuple(rids),
-                    _reduce_map_files(sizes, spans), f"{len(by_path)} files")
-
-    @_spawnable("map_files")
-    def _map_files(self, files: Any, prompt: str) -> Task:
-        """Always spawn. Collect with await_task(t) → dict[path, answer].
-
-        `files` accepts context entries (dicts), paths (strings), or a mix — the whole
-        chunk/batch/collect loop the system prompt used to spell out, as one call.
-        Oversized files are split and their per-chunk answers joined.
-        Posts are detached (↯bg) so fan-out outlives the repl cell.
-        """
-        return self._start_map_files(files, prompt)
-
-    def _llm_map_reduce(
-        self,
-        items: Any,
-        map_prompt: str,
-        reduce_prompt: str,
-    ) -> str:
-        """Map `map_prompt` over `items` in one batch, then reduce the answers with one call.
-
-        The paper's canonical strategy ("query an LLM per chunk ... then query an LLM with all
-        the buffers") as a single call, so the root never hand-rolls the loop.
-        """
-        map_prompt, reduce_prompt = str(map_prompt), str(reduce_prompt)
-        seq = list(items) if isinstance(items, (list, tuple)) else [items]
-        if not seq:
-            return "Error: llm_map_reduce got no items"
-        texts = [
-            (str(it.get("content", "")) if isinstance(it, dict) else str(it))
-            for it in seq
-        ]
-        labels = [
-            (str(it.get("path", f"item {i + 1}")) if isinstance(it, dict) else f"item {i + 1}")
-            for i, it in enumerate(seq)
-        ]
-        mapped: list[str] = []
-        for i in range(0, len(texts), _MAX_CHUNK_BATCH):
-            batch = [
-                f"{map_prompt}\n\n[{labels[i + j]}]\n{t}"
-                for j, t in enumerate(texts[i:i + _MAX_CHUNK_BATCH])
-            ]
-            # Core tools always return Task — helpers must await explicitly.
-            part = self._await_task(self._start_llm_batch(batch))
-            mapped.extend(part if isinstance(part, list) else [str(part)])
-        joined = "\n\n".join(f"[{labels[i]}]\n{a}" for i, a in enumerate(mapped))
-        reduced = self._await_task(
-            self._start_llm_query(f"{reduce_prompt}\n\nPartial answers:\n{joined}")
-        )
-        return str(reduced)
-
-    # ---- Core tools: ALWAYS spawn (return Task). Collect with await_task only. ------------
-
-    @_spawnable("llm_query")
-    def _llm_query(self, prompt: str) -> Task:
-        """Always spawn. Collect with await_task(t). Never auto-awaits."""
-        return self._start_llm_query(prompt)
-
-    @_spawnable("llm_batch")
-    def _llm_batch(self, prompts) -> Task:
-        """Always spawn. Collect with await_task(t) → ordered list[str]."""
-        return self._start_llm_batch(prompts)
-
-    @_spawnable("llm_query_chunked")
-    def _llm_query_chunked(self, text, prompt: str) -> Task:
-        """Always spawn. Collect with await_task(t) → list[str] (one answer per chunk)."""
-        return self._start_llm_query_chunked(text, prompt)
-
-    @_spawnable("rlm_query")
-    def _rlm_query(self, prompt: str, paths=None) -> Task:
-        """Always spawn. Collect with await_task(t)."""
-        return self._start_rlm_query(prompt, paths)
-    def _add_context(self, source: str) -> dict[str, Any] | str:
-        """Pack an external dir/file/git-URL on the host and append it into `context`.
-
-        Paths are namespaced under ctx/<source_id>/ (host). Content is always in the
-        single `context` list — never a new context_N variable.
-        Host-side idempotency may return already_loaded without a payload path.
-        Documents (PDF/DOCX/…) are converted to Markdown on the host.
-        """
-        r = self._rpc("add_context", {"source": str(source)})
-        if r.get("error"):
-            return f"Error: {r['error']}"
-        if r.get("already_loaded"):
-            source_id = r.get("source_id") if isinstance(r.get("source_id"), str) else "ctx"
-            path_prefix = r.get("path_prefix") if isinstance(r.get("path_prefix"), str) else f"ctx/{source_id}/"
-            ctx = self.ns.get("context")
-            ctx_len = len(ctx) if isinstance(ctx, list) else 0
-            print(
-                f"[rlm] add_context: already loaded {source_id} "
-                f"(paths under {path_prefix}, context len={ctx_len})"
-            )
-            return {
-                "source": str(source),
-                "source_id": source_id,
-                "path_prefix": path_prefix,
-                "files": 0,
-                "chars": r.get("chars"),
-                "context_len": ctx_len,
-                "already_loaded": True,
-                "documents": 0,
-                "converted": 0,
-                "skipped": [],
-            }
-        path = r.get("path")
-        if not isinstance(path, str):
-            return "Error: malformed add_context reply (no path)"
-        try:
-            payload = read_host_payload(path, bool(r.get("json")))
-        finally:
-            try:
-                os.remove(path)  # worker owns temp-file cleanup (host does NOT unlink)
-            except OSError:
-                pass
-        return self._append_context(str(source), payload, r)
-
-    def _append_context(self, source: str, payload: Any, meta: dict[str, Any]) -> dict[str, Any] | str:
-        """Append host-packed files into `context` (idempotent by path prefix).
-
-        The two refusals below are pre-flighted host-side by LIST_CONTEXT_REQUIRED /
-        NO_FILES_PRODUCED in src/bridge/add-context.ts, so the host never commits a
-        loaded-prefix for an append that fails here. Reaching either one means host and worker
-        disagree about `context`; keep the wording identical to its twin.
-        """
-        ctx = self.ns.get("context")
-        if not isinstance(ctx, list):
-            kind = type(ctx).__name__ if ctx is not None else "None"
-            return f"Error: add_context requires list context (file bundle); got {kind}"
-
-        source_id = meta.get("source_id")
-        if not isinstance(source_id, str) or not source_id:
-            source_id = "ctx"
-        path_prefix = meta.get("path_prefix")
-        if not isinstance(path_prefix, str):
-            path_prefix = f"ctx/{source_id}/"
-        # Empty path_prefix is valid (cwd seed) but add_context always sends a non-empty ctx/ prefix.
-        # Guard startsWith on empty prefix: "anything".startswith("") is always True.
-        check_prefix = path_prefix if path_prefix != "" else None
-
-        # Idempotent: already present if any path uses this prefix.
-        if check_prefix is not None:
-            for item in ctx:
-                if isinstance(item, dict) and str(item.get("path", "")).startswith(check_prefix):
-                    print(
-                        f"[rlm] add_context: already loaded {source_id} "
-                        f"(paths under {path_prefix}, context len={len(ctx)})"
-                    )
-                    return {
-                        "source": source,
-                        "source_id": source_id,
-                        "path_prefix": path_prefix,
-                        "files": 0,
-                        "chars": meta.get("chars"),
-                        "context_len": len(ctx),
-                        "already_loaded": True,
-                        "documents": 0,
-                        "converted": 0,
-                        "skipped": [],
-                    }
-
-        files = self._context_file_entries(payload, path_prefix)
-        if not files:
-            return "Error: add_context produced no files"
-
-        ctx.extend(files)
-        # Keep restore payload in sync with the live list.
-        self._context_payload = ctx
-        self.ns["context"] = ctx
-
-        documents = meta.get("documents") if isinstance(meta.get("documents"), int) else 0
-        converted = meta.get("converted") if isinstance(meta.get("converted"), int) else 0
-        skipped = meta.get("skipped") if isinstance(meta.get("skipped"), list) else []
-        skip_n = len(skipped)
-        extra = ""
-        if documents or converted or skip_n:
-            extra = f"; documents={documents}, converted={converted}, skipped={skip_n}"
-        print(
-            f"[rlm] add_context: +{len(files)} files into context "
-            f"(len={len(ctx)}); paths under {path_prefix}{extra}"
-        )
-        return {
-            "source": source,
-            "source_id": source_id,
-            "path_prefix": path_prefix,
-            "files": len(files),
-            "chars": meta.get("chars"),
-            "context_len": len(ctx),
-            "already_loaded": False,
-            "documents": documents,
-            "converted": converted,
-            "skipped": skipped,
-        }
-
-    @staticmethod
-    def _context_file_entries(payload: Any, path_prefix: str) -> list[dict[str, Any]]:
-        """Normalize host payload to list[dict]. Host already namespaces; string is fallback."""
-        if isinstance(payload, str):
-            return [{
-                "path": f"{path_prefix}content" if path_prefix else "content",
-                "content": payload,
-                "tokens": max(1, (len(payload) + 3) // 4),
-            }]
-        if not isinstance(payload, list):
-            return []
-        out: list[dict[str, Any]] = []
-        for item in payload:
-            if isinstance(item, dict) and "path" in item and "content" in item:
-                out.append(item)
-        return out
-
-    @_spawnable("rlm_batch")
-    def _rlm_batch(self, prompts, paths=None) -> Task:
-        """Always spawn. Collect with await_task(t) → ordered list of reports."""
-        return self._start_rlm_batch(prompts, paths)
-
-    # ---- context + execution --------------------------------------------------------------
-
     def load_context(self, path: str, index: int | None = None, is_json: bool = False) -> int:
         """Load the packed world into the single REPL variable `context`.
 
@@ -821,6 +362,7 @@ class Worker:
             "raised": raised,
             "execution_time": time.perf_counter() - start,
             "var_names": self._user_var_names(),
+            "pending_tasks": self._pending_task_infos(),
         }
 
 
@@ -832,11 +374,14 @@ def main() -> None:
                     default=float(os.environ.get("RLM_AWAIT_TIMEOUT_S", "600")))
     ap.add_argument("--max-prompt-chars", type=int,
                     default=int(os.environ.get("RLM_MAX_PROMPT_CHARS", "400000")))
+    ap.add_argument("--surface", default=os.environ.get("RLM_SURFACE", "root"),
+                    choices=["root", "child"])
     args = ap.parse_args()
 
     worker = Worker(depth=args.depth, exec_timeout_s=args.timeout,
                     max_prompt_chars=args.max_prompt_chars,
-                    await_timeout_s=args.await_timeout)
+                    await_timeout_s=args.await_timeout,
+                    surface=args.surface)
     _send({"id": "_init", "ok": True})
 
     while True:
@@ -859,6 +404,8 @@ def main() -> None:
         # result would be lost.
         if worker.park_reply(req):
             continue
+        if isinstance(req, dict) and req.get("type") == "heartbeat":
+            continue
         if not isinstance(req, dict):
             _send({"id": "?", "ok": False, "error": f"expected an object, got {type(req).__name__}"})
             continue