@hicaru/pi-rlm 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hicaru/pi-rlm",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Save 99% tokens, Recursive Language Model (RLM) for the Pi",
   "license": "MIT",

package/src/bridge/fallback-todo.ts

@@ -90,12 +90,22 @@ function withPatch(task: Task, params: TodoParams): Task {
   });
 }
 
+/** The actions `worker.py::_todo` documents. Anything else is a caller error, not a missing task. */
+const TODO_ACTIONS: ReadonlySet<string> = Object.freeze(new Set([
+  "create", "update", "list", "get", "delete", "clear",
+]));
+
 export function createTodoFallback(): (action: string, params: Record<string, unknown>) => Promise<string> {
   let nextId = 1;
   let tasks: readonly Task[] = Object.freeze([]);
   const fmt = (task: Task): string => taskLines(task)[0] ?? `#${task.id}`;
 
   const apply = (action: string, rawParams: Record<string, unknown>): string => {
+    // Validated BEFORE the id lookup below: an unknown action used to fall through to it and
+    // report "task #? not found", which reads as a missing task rather than a bad action.
+    if (!TODO_ACTIONS.has(action)) {
+      return formatError(`unknown todo action '${action}' — expected ${[...TODO_ACTIONS].join(", ")}`);
+    }
     const params = toTodoParams(rawParams);
     if (action === "clear") {
       const count = tasks.length;
@@ -131,7 +141,8 @@ export function createTodoFallback(): (action: string, params: Record<string, un
       tasks = Object.freeze(tasks.map((item) => item.id === task.id ? updated : item));
       return `Updated ${fmt(updated)}`;
     }
-    return formatError(`unknown todo action '${action}'`);
+    // Unreachable: every TODO_ACTIONS member is handled above. Kept as the exhaustiveness arm.
+    return formatError(`unhandled todo action '${action}'`);
   };
   return async (action, params) => apply(action, params);
 }

package/src/bridge/subcall-handlers.ts

@@ -0,0 +1,336 @@
+/**
+ * The single implementation of the sub-LLM handler set (llm_query, llm_query_batched,
+ * rlm_query, rlm_query_batched).
+ *
+ * Resolves AGENTS.md DRY #1–#5, which previously lived twice: once in `createLlmBridge` /
+ * `createRlmHandlers` for the headless engine, once in `NativeBridgeState` for the repl()
+ * tool. The two callers only ever differed in how they answer one question — "which emitter,
+ * limits and parent node does THIS interrupt belong to?" — so that is the only thing they
+ * still supply, as `resolve`. The engine binds one Invocation for a whole run; the repl()
+ * tool swaps one per turn and routes `spawn()`ed work to its session registry.
+ *
+ * Concurrency: every leaf completion passes through `gates.leaf`, every child engine through
+ * `gates.rlm.at(depth)`, so a sandbox that puts 25 batches on the wire at once is still
+ * bounded session-wide. See util/concurrency.ts for why the rlm gate is per-depth.
+ */
+
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { displayModelRef, modelRef, resolveModelId } from "../config/settings.ts";
+import { type ChatMsg, modelComplete } from "./model.ts";
+import { previewText } from "../text/preview.ts";
+import { checkResourceLimits } from "../core/resource-limits.ts";
+import type { RlmInput, RlmResult, Sampling } from "../core/types.ts";
+import type { SubcallGates } from "../util/concurrency.ts";
+import type { SubcallOpts, SubLlmHandlers } from "../sandbox/sandbox.ts";
+import type { RlmEmitter } from "../tool/rlm-events.ts";
+import { errorMessage, formatError, isErrorText } from "../util/errors.ts";
+
+/**
+ * The slice of LimitGuard these handlers need. Narrow on purpose: the headless bridge is
+ * constructed from a `remainingBudget()` callback rather than owning a guard, and both
+ * shapes satisfy this.
+ */
+export interface InvocationLimits {
+  remainingBudgetUsd(): number | undefined;
+  remainingTimeoutMs(): number | undefined;
+  addUsage(usage: Usage): void;
+  addRaw(costUsd: number, inputTokens: number, outputTokens: number): void;
+}
+
+/**
+ * Adapt a "how much is left?" callback to InvocationLimits.
+ *
+ * The headless engine owns the real LimitGuard and folds usage in through `onUsage` /
+ * `onChildUsage`, so the accounting methods here are deliberately inert.
+ */
+export function limitsFromRemaining(
+  remaining?: () => { readonly budgetUsd?: number; readonly timeoutMs?: number },
+): InvocationLimits {
+  return {
+    remainingBudgetUsd: () => remaining?.().budgetUsd,
+    remainingTimeoutMs: () => remaining?.().timeoutMs,
+    addUsage: () => {},
+    addRaw: () => {},
+  };
+}
+
+/**
+ * Where one interrupt's reporting and accounting go.
+ *
+ * Captured at interrupt entry and threaded down, never re-read: once handlers can outlive
+ * their exec, re-reading mutable tool state after an await would attribute a sub-call to
+ * whichever turn happens to be current when it resumes.
+ */
+export interface Invocation {
+  readonly emitter: RlmEmitter;
+  readonly parentId: string | undefined;
+  readonly depth: number;
+  readonly limits: InvocationLimits;
+}
+
+/**
+ * The config slice these handlers read. Structurally satisfied by `RlmConfig`, and re-read on
+ * every call so `/rlm-config` changes take effect without rebuilding the sandbox.
+ */
+export interface SubcallConfig {
+  readonly maxPromptChars: number;
+  readonly maxDepth: number;
+  readonly subSampling?: Sampling;
+  readonly subSystemPrompt?: string;
+}
+
+export interface SubcallHandlerDeps {
+  /**
+   * Pick the Invocation for this interrupt. `null` ⇒ the bridge is not wired yet.
+   *
+   * `depth` is the depth the sandbox reported. The headless engine trusts it (its handlers
+   * serve one sandbox per depth); the repl() tool overrides it with its own turn depth.
+   */
+  readonly resolve: (opts: SubcallOpts, depth: number) => Invocation | null;
+  /** Session-wide admission control. Required — a per-caller default would silently unbound it. */
+  readonly gates: SubcallGates;
+  readonly registry: ModelRegistry;
+  readonly getWorkerModel: () => Model<Api>;
+  /** Live accessor — `/rlm-config` replaces the config object, so never capture the value. */
+  readonly getConfig: () => SubcallConfig;
+  readonly signal?: AbortSignal;
+  readonly onUsage?: (usage: Usage, role: "sub") => void;
+
+  // ── recursion (omit all three to get llm-only handlers) ──
+  /**
+   * Spawns a child RLM for rlm_query.
+   *
+   * Receives the parent's Invocation so the child can report on the same emitter its
+   * parent subcall node lives on — a child of detached work must not emit to a turn
+   * emitter that will be shut down before it finishes, and keeping parent and child on
+   * one emitter is what lets the session registry drain the subtree intact.
+   */
+  readonly runChild?: (input: RlmInput, inv: Invocation) => Promise<RlmResult>;
+  readonly getModel?: () => Model<Api>;
+  /**
+   * What rlm_query degrades to at the depth cap. A child RLM there would just be an LM, so
+   * both callers hand in their own one-shot path rather than re-deriving one here.
+   */
+  readonly degrade?: (prompt: string, model: string | null, depth: number) => Promise<string>;
+  /** Called with a child run's totals so a caller-side guard can debit them too. */
+  readonly onChildUsage?: (costUsd: number, inputTokens: number, outputTokens: number) => void;
+  /** Wraps detached work so a session registry can count what is still in flight. */
+  readonly trackDetached?: <T>(run: () => Promise<T>) => Promise<T>;
+}
+
+/** DRY #4 — the batch failure summary, previously written out in both copies. */
+export function summarizeBatch(out: readonly string[]): { readonly failed: number; readonly error?: string } {
+  let failed = 0;
+  for (const item of out) if (isErrorText(item)) failed += 1;
+  if (failed === 0) return { failed: 0 };
+  const error = failed === out.length
+    ? `all ${out.length} sub-calls failed — reduce batch size or try llm_query individually`
+    : `${failed}/${out.length} sub-calls failed`;
+  return { failed, error };
+}
+
+export type SubcallHandlers = Pick<
+  SubLlmHandlers,
+  "llmQuery" | "llmQueryBatched" | "rlmQuery" | "rlmQueryBatched"
+>;
+
+const UNWIRED = formatError("RLM bridge not wired for this invocation");
+
+function emptyResult(answer: string): RlmResult {
+  return { answer, iterations: 0, costUsd: 0, inputTokens: 0, outputTokens: 0, durationMs: 0 };
+}
+
+export function createSubcallHandlers(deps: SubcallHandlerDeps): SubcallHandlers {
+  /** DRY #3 — the one display-model resolution. */
+  const displayModel = (model: string | null): string =>
+    displayModelRef(deps.registry, model, deps.getWorkerModel());
+
+  /** Detached work is counted by the session registry; attached work runs as-is. */
+  const detachable = <T>(opts: SubcallOpts, run: () => Promise<T>): Promise<T> =>
+    opts.detached && deps.trackDetached !== undefined ? deps.trackDetached(run) : run();
+
+  /** One leaf completion. Reports cost/tokens via `track`; never throws. */
+  async function complete1(
+    inv: Invocation,
+    prompt: string,
+    model: string | null,
+    track: (usage: Usage) => void,
+  ): Promise<string> {
+    const config = deps.getConfig();
+    const limitError = checkResourceLimits({
+      budgetUsd: inv.limits.remainingBudgetUsd(),
+      timeoutMs: inv.limits.remainingTimeoutMs(),
+    });
+    if (limitError !== undefined) return limitError;
+    if (prompt.length > config.maxPromptChars) {
+      return formatError(
+        `sub-LLM prompt exceeded the size limit (${prompt.length.toLocaleString()} chars > ` +
+        `${config.maxPromptChars.toLocaleString()}). Shorten or chunk the prompt before calling llm_query.`,
+      );
+    }
+    const resolved = model ? resolveModelId(deps.registry, model) : undefined;
+    if (model && !resolved) return formatError(`unknown model override '${model}'`);
+    try {
+      const messages: ChatMsg[] = [{ role: "user", content: prompt }];
+      const res = await deps.gates.leaf.run(() => modelComplete(messages, {
+        model: resolved ?? deps.getWorkerModel(),
+        registry: deps.registry,
+        system: config.subSystemPrompt,
+        maxTokens: config.subSampling?.maxTokens,
+        temperature: config.subSampling?.temperature,
+        reasoning: config.subSampling?.reasoning,
+        signal: deps.signal,
+      }));
+      inv.limits.addUsage(res.usage);
+      deps.onUsage?.(res.usage, "sub");
+      track(res.usage);
+      return res.text;
+    } catch (err) {
+      const msg = errorMessage(err);
+      const hint = /credit|402|payment|quota|rate.limit/i.test(msg)
+        ? " — try smaller batches or individual llm_query calls"
+        : "";
+      return formatError(`${msg}${hint}`);
+    }
+  }
+
+  /**
+   * DRY #5 — the create → execute → update emit pattern for leaf sub-calls, in one place.
+   * rlm_query does NOT use this: its node is created inside `childRun`, and a wrapper here
+   * would double-report it.
+   */
+  async function emitting<T>(
+    opts: SubcallOpts,
+    depth: number,
+    init: { kind: "llm" | "batch"; label: string; model: string | null; args: string },
+    run: (inv: Invocation, track: (usage: Usage) => void) => Promise<T>,
+    summarize: (out: T) => {
+      readonly preview: string;
+      readonly error?: string;
+      readonly failed?: number;
+      readonly total?: number;
+    },
+    unwired: () => T,
+  ): Promise<T> {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) return unwired();
+    const id = inv.emitter.emitSubcallCreated({
+      kind: init.kind, parentId: inv.parentId, label: init.label,
+      model: displayModel(init.model), args: init.args, depth: inv.depth,
+    });
+    let costUsd = 0;
+    let tokens = 0;
+    const track = (usage: Usage): void => { costUsd += usage.cost.total; tokens += usage.totalTokens; };
+    const out = await detachable(opts, () => run(inv, track));
+    const summary = summarize(out);
+    inv.emitter.emitSubcallUpdated({
+      id,
+      status: summary.error !== undefined ? "error" : "done",
+      costUsd, tokens,
+      resultPreview: summary.preview,
+      detail: summary.error,
+      failedCount: summary.failed,
+      totalCount: summary.total,
+    });
+    return out;
+  }
+
+  /**
+   * One child RLM run: depth cap → resource guard → spawn engine → debit parent.
+   * Emits its own subcall node, so callers must not wrap it in another.
+   */
+  async function childRun(inv: Invocation, prompt: string, model: string | null): Promise<RlmResult> {
+    const childDepth = inv.depth + 1;
+    const run = deps.runChild;
+    const maxDepth = deps.getConfig().maxDepth;
+
+    // At the cap a child RLM would just be an LM — short-circuit to the caller's one-shot path.
+    if (run === undefined || childDepth >= maxDepth) {
+      const degrade = deps.degrade;
+      const answer = degrade !== undefined
+        ? await degrade(prompt, model, inv.depth)
+        : await complete1(inv, prompt, model, () => {});
+      return emptyResult(answer);
+    }
+
+    const remBudget = inv.limits.remainingBudgetUsd();
+    const remTimeout = inv.limits.remainingTimeoutMs();
+    const limitError = checkResourceLimits({ budgetUsd: remBudget, timeoutMs: remTimeout });
+    if (limitError) return emptyResult(limitError);
+
+    const rootModel = deps.getModel?.();
+    const resolvedOverride = model ? resolveModelId(deps.registry, model) : undefined;
+    const modelLabel = model
+      ? (modelRef(resolvedOverride) ?? `unknown/${model}`)
+      : (rootModel === undefined ? undefined : (modelRef(rootModel) ?? rootModel.id));
+    const subId = inv.emitter.emitSubcallCreated({
+      kind: "rlm", parentId: inv.parentId, label: "rlm_query",
+      model: modelLabel, detail: prompt.slice(0, 60), depth: childDepth,
+    });
+    try {
+      const res = await deps.gates.rlm.at(childDepth).run(() => run({
+        rootPrompt: "",
+        context: prompt,
+        depth: childDepth,
+        parentNodeId: subId,
+        modelOverride: model ?? undefined,
+        remainingBudgetUsd: remBudget,
+        remainingTimeoutMs: remTimeout,
+      }, inv));
+      inv.limits.addRaw(res.costUsd, res.inputTokens, res.outputTokens);
+      deps.onChildUsage?.(res.costUsd, res.inputTokens, res.outputTokens);
+      // The child emits live usage deltas on the shared emitter, so no aggregate cost here
+      // — adding it would double-count against SubcallStore's running totals.
+      inv.emitter.emitSubcallUpdated({ id: subId, status: "done", resultPreview: res.answer.slice(0, 200) });
+      return res;
+    } catch (err) {
+      const msg = errorMessage(err);
+      inv.emitter.emitSubcallUpdated({ id: subId, status: "error", detail: msg });
+      return emptyResult(formatError(`child RLM failed - ${msg}`));
+    }
+  }
+
+  return {
+    llmQuery: (prompt, model, depth, opts) => emitting(
+      opts, depth,
+      { kind: "llm", label: "llm_query", model, args: `prompt: ${previewText(prompt)}` },
+      (inv, track) => complete1(inv, prompt, model, track),
+      (out) => ({ preview: previewText(out), error: isErrorText(out) ? out : undefined }),
+      () => UNWIRED,
+    ),
+
+    llmQueryBatched: (prompts, model, depth, opts) => emitting(
+      opts, depth,
+      { kind: "batch", label: `llm_query ×${prompts.length}`, model, args: `prompt: ${previewText(prompts[0] ?? "")}` },
+      // NO outer gate. `complete1` already takes the single `leaf` slot each prompt needs;
+      // an outer `gates.leaf.map` here deadlocked every batch of >= limit prompts.
+      (inv, track) => Promise.all(prompts.map((p) => complete1(inv, p, model, track))),
+      (out) => {
+        const { failed, error } = summarizeBatch(out);
+        const first = previewText(out[0] ?? "");
+        return {
+          preview: out.length > 1 ? `${first}  (+${out.length - 1} more)` : first,
+          error, failed, total: out.length,
+        };
+      },
+      () => prompts.map(() => UNWIRED),
+    ),
+
+    async rlmQuery(prompt, model, depth, opts) {
+      const inv = deps.resolve(opts, depth);
+      if (inv === null) return UNWIRED;
+      return detachable(opts, async () => (await childRun(inv, prompt, model)).answer);
+    },
+
+    async rlmQueryBatched(prompts, model, depth, opts) {
+      const inv = deps.resolve(opts, depth);
+      if (inv === null) return prompts.map(() => UNWIRED);
+      // Bounded by the per-depth rlm gate inside childRun, not by an outer pool.
+      return detachable(opts, async () => {
+        const results = await Promise.all(prompts.map((p) => childRun(inv, p, model)));
+        return results.map((r) => r.answer);
+      });
+    },
+  };
+}

package/src/config/defaults.ts

@@ -16,7 +16,10 @@ export const DEFAULT_CONFIG: Readonly<RlmConfig> = Object.freeze({
   maxIterations: 30,
   execTimeoutS: 120,
   requestTimeoutMs: 10 * 60_000,
-  maxConcurrentSubcalls: 4,
+  // Session-wide, not per-batch: spawn() puts many requests on the wire at once, so this is
+  // the only thing bounding fan-out. Worst case is maxDepth × this many child engines (each
+  // owning a Python subprocess) plus this many leaf completions — keep it modest.
+  maxConcurrentSubcalls: 6,
   maxPromptChars: 400_000,
   maxErrors: 5,
   orchestrator: true,

package/src/core/engine.ts

@@ -17,10 +17,12 @@ import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { buildInteractiveHandlers } from "../bridge/interactive.ts";
 import { buildLibraryHandler } from "../bridge/library.ts";
 import { mergeLibraryIntoContext } from "../context/library-context.ts";
-import { createLlmBridge } from "../bridge/llm-query.ts";
+import {
+  createSubcallHandlers,
+  type Invocation,
+} from "../bridge/subcall-handlers.ts";
 import { type ChatMsg, modelComplete } from "../bridge/model.ts";
-import { createRlmHandlers } from "../bridge/rlm-query.ts";
-import { displayModelRef, resolveModelId } from "../config/settings.ts";
+import { resolveModelId } from "../config/settings.ts";
 import { buildRlmSystemPrompt } from "../prompts/system.ts";
 import { buildTurnPrompt, FINALIZE_PROMPT } from "../prompts/user.ts";
 import { phaseGuidance } from "../prompts/phases.ts";
@@ -57,6 +59,14 @@ import { STATE_SCHEMA_VERSION } from "../state/rows.ts";
 import type { PhaseRow, RunHeader } from "../state/rows.ts";
 import { serializeForSandbox, type ContextBundle } from "../context/repomix-context.ts";
 import { formatError } from "../util/errors.ts";
+import { createSubcallGates, type SubcallGates } from "../util/concurrency.ts";
+
+/**
+ * Grace period for detached sub-calls to settle before the run disposes its sandbox.
+ * Past it the abort signal (or process exit) is what stops them; waiting longer would
+ * hold a finished run open on work whose result nobody can receive.
+ */
+const DETACHED_SETTLE_MS = 5_000;
 
 
 export interface EngineDeps extends InteractiveDeps {
@@ -65,6 +75,8 @@ export interface EngineDeps extends InteractiveDeps {
   readonly registry: ModelRegistry;
   readonly config: RlmConfig;
   readonly limits?: Limits;
+  /** Session-wide sub-call admission, shared with the repl() tool. Private one if omitted. */
+  readonly gates?: SubcallGates;
   readonly signal?: AbortSignal;
   /** Live RlmDetails reporting via onUpdate. Required — replaces SubcallObserver. */
   readonly emitter: RlmEmitter;
@@ -171,37 +183,58 @@ export function createEngine(deps: EngineDeps): RunRlm {
       maxErrors: deps.limits?.maxErrors,
       maxTokens: deps.limits?.maxTokens,
     }, input.resume?.usageSeed.durationMs ?? 0);
-    const remainingBudget = (): { readonly budgetUsd?: number; readonly timeoutMs?: number } => ({
-      budgetUsd: limits.remainingBudgetUsd(),
-      timeoutMs: limits.remainingTimeoutMs(),
-    });
 
-    const llm = createLlmBridge({
-      workerModel: () => deps.workerModel,
+    // One Invocation for the whole run: this engine owns exactly one sandbox at one depth,
+    // and its emitter and LimitGuard outlive every sub-call it services — including
+    // detached ones, which is why the headless path needs no session registry.
+    const invocation: Invocation = {
+      emitter,
+      parentId: selfReportId,
+      depth: input.depth,
+      limits: {
+        remainingBudgetUsd: () => limits.remainingBudgetUsd(),
+        remainingTimeoutMs: () => limits.remainingTimeoutMs(),
+        addUsage: (u) => {
+          limits.addUsage(u);
+          deps.onUsage?.(u, "sub");
+        },
+        addRaw: (costUsd, inputTokens, outputTokens) => {
+          limits.addRaw(costUsd, inputTokens, outputTokens);
+        },
+      },
+    };
+    // Detached work must not outlive the sandbox we dispose in `finally`: track it so the
+    // run can settle or abort it first (a child engine left running would keep spending).
+    let detachedInFlight = 0;
+    let detachedIdle: (() => void) | undefined;
+    const subcalls = createSubcallHandlers({
+      resolve: () => invocation,
+      gates: deps.gates ?? createSubcallGates(deps.config.maxConcurrentSubcalls),
       registry: deps.registry,
-      config: () => deps.config,
+      getWorkerModel: () => deps.workerModel,
+      getModel: () => model,
+      getConfig: () => deps.config,
       signal: deps.signal,
-      onUsage: (u) => {
-        limits.addUsage(u);
-        deps.onUsage?.(u, "sub");
-      },
-      emitter: () => emitter,
-      parentId: () => selfReportId,
-      depth: () => input.depth,
-      remainingBudget,
-    });
-    const rlm = createRlmHandlers({
-      run,
-      llm,
-      config: () => deps.config,
-      modelLabel: (override) => displayModelRef(deps.registry, override, model),
-      emitter: () => emitter,
-      parentNodeId: () => selfReportId,
-      remainingBudget,
-      onChildUsage: (costUsd, inputTokens, outputTokens) => {
-        limits.addRaw(costUsd, inputTokens, outputTokens);
+      runChild: run,
+      trackDetached: async (task) => {
+        detachedInFlight += 1;
+        try {
+          return await task();
+        } finally {
+          detachedInFlight -= 1;
+          if (detachedInFlight === 0) detachedIdle?.();
+        }
       },
     });
+    /** Wait (bounded) for detached work before the sandbox goes away. */
+    const settleDetached = async (): Promise<void> => {
+      if (detachedInFlight === 0) return;
+      await new Promise<void>((resolve) => {
+        detachedIdle = resolve;
+        setTimeout(resolve, DETACHED_SETTLE_MS).unref?.();
+      });
+      detachedIdle = undefined;
+    };
     let sandbox: PythonSandbox | undefined;
     let best = "";
     let lastAnswer = "";
@@ -352,9 +385,10 @@ export function createEngine(deps: EngineDeps): RunRlm {
         signal: deps.signal,
         initTimeoutMs: deps.config.sandboxInitTimeoutMs,
         maxPromptChars: deps.config.maxPromptChars,
+        awaitTimeoutS: Math.round(deps.config.requestTimeoutMs / 1000),
         // Pipeline at depth 0 is read-only: guard open() write modes in the worker.
         readOnly: pipelineOn,
-        handlers: { ...llm, ...rlm, ...phaseHandlers, ...interactiveHandlers, ...libraryHandlers },
+        handlers: { ...subcalls, ...phaseHandlers, ...interactiveHandlers, ...libraryHandlers },
       });
 
       let history: ChatMsg[] = input.resume ? input.resume.history : [{ role: "system", content: system }];
@@ -573,6 +607,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
         if (nodeStatus !== "error" && lastAnswer) emitter.emitAnswer(previewText(lastAnswer));
         emitter.emitStatus(nodeStatus === "error" ? "error" : "done");
       }
+      await settleDetached();
       await sandbox?.dispose();
     }
   };

package/src/index.ts

@@ -12,12 +12,16 @@ import { postRlmGuide } from "./ui/intro.ts";
 import { setRlmModeStatus } from "./ui/status.ts";
 import { markdownTheme } from "./ui/theme-adapter.ts";
 import { SandboxManager } from "./sandbox/sandbox-manager.ts";
+import { createSubcallGates } from "./util/concurrency.ts";
+import { BackgroundTasks } from "./tool/background-tasks.ts";
 import { packRepository, formatForLLM, serializeForSandbox } from "./context/repomix-context.ts";
 import { buildNativeSystemPrompt, NATIVE_TURN_REMINDER } from "./prompts/system.ts";
 import { bashCommandFromInput, isFileReadingCommand, capToolResultText, BASH_BLOCK_REASON } from "./mode/native-guards.ts";
 import { errorMessage } from "./util/errors.ts";
 
 const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep"]));
+/** How often to keep the parent sandbox's request watchdog alive during detached work. */
+const WATCHDOG_HEARTBEAT_MS = 30_000;
 const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls"]));
 
 export default function rlmExtension(pi: ExtensionAPI): void {
@@ -31,8 +35,28 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     python: config.python,
     sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
     maxPromptChars: config.maxPromptChars,
+    // Same wall budget as the parent request watchdog — a stalled sub-call should surface
+    // inside the cell rather than hang the session forever.
+    awaitTimeoutS: Math.round(config.requestTimeoutMs / 1000),
     onSandboxDiscarded: () => { onSandboxDiscardExtra?.(); },
   });
+  // One admission gate for the whole session: spawn() lets the sandbox put many requests on
+  // the wire at once, so nothing smaller than session scope actually bounds fan-out.
+  const gates = createSubcallGates(config.maxConcurrentSubcalls);
+  const background = new BackgroundTasks({
+    maxBudgetUsd: config.maxBudgetUsd,
+    maxTimeoutMs: config.maxTimeoutMs,
+    maxTokens: config.maxTokens,
+    maxErrors: config.maxErrors,
+  });
+  // A detached child works in its OWN sandbox, so this one sees no frames and its request
+  // watchdog would fire mid-await and SIGKILL a healthy worker, taking the REPL namespace
+  // with it. Keep it alive while detached work is genuinely in flight.
+  const watchdogHeartbeat = setInterval(() => {
+    if (background.pending > 0) sandboxManager.refreshWatchdog();
+  }, WATCHDOG_HEARTBEAT_MS);
+  watchdogHeartbeat.unref();
+
   let packedContextText: string | undefined;
   let contextPackPromise: Promise<string | undefined> | undefined;
   const ensureRepositoryContext = async (cwd: string): Promise<string | undefined> => {
@@ -114,6 +138,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           getWorkerModel: () => controller.resolveModels(ctx)?.worker,
           registry: ctx.modelRegistry,
           getConfig: () => controller.config,
+          gates,
+          background,
           registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
           ensureContext: async () => {
             const contextText = await ensureRepositoryContext(ctx.cwd ?? process.cwd());
@@ -224,6 +250,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // ── Session shutdown: cleanup ──
   pi.on("session_shutdown", async () => {
     controller.abort();
+    clearInterval(watchdogHeartbeat);
+    background.dispose();
     await sandboxManager.dispose();
     contextInjected = false;
     packedContextText = undefined;

package/src/prompts/system.ts

@@ -74,6 +74,23 @@ const CHUNKED_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "  you open()ed, an oversized sub-result, or several concatenated context files.",
 ]);
 
+/** Non-blocking fan-out: spawn now, collect later (headless glossary). */
+const SPAWN_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `spawn(fn, *args) -> Task`: start `llm_query`, `llm_query_batched`, `llm_query_chunked`,",
+  "  `map_files`, `rlm_query` or `rlm_query_batched` WITHOUT waiting. Returns immediately.",
+  "  (Not `llm_map_reduce` — its reduce step depends on its own map results.)",
+  "- `rlm_await(task)` / `rlm_await_all(tasks) -> list`: collect results; order matches input.",
+  "  Tasks survive across turns, so spawn the slow work first, keep doing useful things, and",
+  "  await only when you actually need the results. `task.done` tells you if it has landed.",
+  "",
+  "  ```python",
+  "  # start the slow sub-agents, then keep working while they run",
+  "  tasks = [spawn(rlm_query, f\"Audit {area} end to end\") for area in areas]",
+  "  hits = [f for f in context if \"TODO\" in f[\"content\"]]   # overlaps with the sub-agents",
+  "  reports = rlm_await_all(tasks)",
+  "  ```",
+]);
+
 /** Why a file the user mentioned may be missing from `context`. */
 const CONTEXT_EXCLUSION_NOTE =
   "  NOTE: files larger than 1MB and gitignored files are NOT in `context` — they exist only on disk.";
@@ -206,6 +223,7 @@ function replGlossary(
     "- `llm_query_batched(prompts: list[str], model=None) -> list[str]`: run several sub-LLM calls",
     "  concurrently; output order matches input order.",
     ...CHUNKED_GLOSSARY_LINES,
+    ...SPAWN_GLOSSARY_LINES,
     ...DELEGATION_GLOSSARY_LINES,
   );
   if (askUserQuestion) {
@@ -370,6 +388,7 @@ function nativeReplGlossary(): string {
     CHUNKED_GLOSSARY_LINE_NATIVE,
     "- `rlm_query(prompt, model=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning. Prefer llm_query — rlm_query is slower and costlier.",
     "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
+    "- `spawn(fn, *args) -> Task` / `rlm_await(t)` / `rlm_await_all(ts)` — start `llm_query`, `llm_query_batched`, `llm_query_chunked`, `map_files`, `rlm_query` or `rlm_query_batched` without waiting (NOT `llm_map_reduce`); collect later, order preserved. Tasks outlive the repl() call, so spawn slow work early and await when you need it.",
     "",
     "",
     "- `answers` / `plan` — dicts persisted across every repl() call and snapshot. Your memo.",
@@ -445,8 +464,10 @@ export function buildNativeSystemPrompt(): string {
 /** Soft cap on the static native prompt. Leaves headroom for per-turn context injection
  *  without bloating the root model's system prompt. Exceeded → phase-guards.ts fails.
  *  Raised from 6K when the retrieval glossary and the condensed decomposition doctrine
- *  landed; both buy far more than they cost (paper Table 2, Fig. 4a). */
-export const NATIVE_PROMPT_BUDGET = 7_500;
+ *  landed; both buy far more than they cost (paper Table 2, Fig. 4a), then again for
+ *  spawn/rlm_await: the async fan-out API is part of the model-visible contract, and
+ *  ~50 tokens is worth the model actually using it. */
+export const NATIVE_PROMPT_BUDGET = 7_700;
 
 /** Exported for tests — prompt length without context metadata (which is injected separately). */
 export const NATIVE_PROMPT_STATIC = buildNativeSystemPrompt();

package/src/sandbox/protocol.ts

@@ -88,6 +88,12 @@ export interface AskAnswer {
 interface InterruptBase {
   readonly rid: string;
   readonly depth: number;
+  /**
+   * Started via `spawn()`: the request may outlive the `exec` that issued it, so the host
+   * must not attach it to that invocation's emitter or LimitGuard. Absent on the
+   * synchronous path.
+   */
+  readonly detached?: boolean;
 }
 
 interface PromptInterrupt extends InterruptBase {