@hicaru/pi-rlm 0.3.0 → 0.3.2

package/README.md

@@ -110,15 +110,19 @@ These functions are injected into the model's Python namespace inside the REPL:
 | Function | Signature | Description |
 |---|---|---|
 | `context` | `list[dict]` | Loaded files as `[{"path","content","tokens"}, …]` — starts empty; cwd seeds on first `repl()` |
-| `llm_query` | `(prompt, model=None) -> str` | One-shot sub-LLM call (worker model) |
-| `llm_query_batched` | `(prompts, model=None) -> list[str]` | Concurrent sub-LLM calls (pool-bounded) |
-| `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | Split large text into cap-sized chunks and fan out via sub-LLMs |
-| `rlm_query` | `(prompt, model=None, paths=None) -> str` | Recursive child RLM with its own sandbox (depth-capped). Inherits your `context`; `paths` narrows it by prefix |
-| `rlm_query_batched` | `(prompts, model=None, paths=None) -> list[str]` | Concurrent recursive child RLMs, sharing one `paths` slice |
+| `llm_query` | `(prompt) -> Task` | Always spawn one sub-LLM; `await_task` → `str` |
+| `llm_batch` | `(prompts) -> Task` | Always spawn many sub-LLMs in parallel; `await_task` → `list[str]` |
+| `llm_query_chunked` | `(text, prompt) -> Task` | Always spawn; split large text into cap-sized chunks; `await_task` → `list[str]` |
+| `map_files` | `(files, prompt) -> Task` | Always spawn; ask `prompt` of many files; `await_task` → `dict[path, answer]` |
+| `rlm_query` | `(prompt, paths=None) -> Task` | Always spawn recursive child RLM; `await_task` → report `str` |
+| `rlm_batch` | `(prompts, paths=None) -> Task` | Always spawn many child RLMs; `await_task` → `list[str]` |
+| `await_task` | `(Task \| list[Task])` | Collect result(s) from always-spawn tools |
 | `add_context` | `(source) -> dict \| str` | Append a dir, file, document, or git URL into `context` under `ctx/<id>/` |
 | `SHOW_VARS` | `() -> str` | List currently defined variables & their types |
 | `answer` | `dict` | Set `answer["content"]=...; answer["ready"]=True` to finalize |
 
+Fan-out posts run **detached** (BG / ↯bg): fire several Tasks, do free `search`/`grep`, then `await_task([...])`.
+
 ### Adding context
 
 `context` starts empty. The working directory seeds automatically on the first `repl()` call
@@ -166,6 +170,49 @@ inherited by every child spawned afterwards.
 > each holds a full Python process and its own copy of the inherited context. Error and
 > wall-clock caps (above) still bound a runaway tree.
 
+## Prompt Architecture
+
+The system prompt is structured around a **contract / routing / examples / rules** pattern
+(api_v5, modeled on the best-performing arm from the RLM paper bake-off):
+
+| Section | Purpose |
+|---|---|
+| `<contract>` | Hard invariant: every heavy call returns a `Task`, never the answer. Only `await_task` returns content. |
+| `<routing>` | Decision tree: which tool for which job. Includes negative guidance ("NOT for") so the model knows when NOT to pick a tool. |
+| `<examples>` | Concrete E1–E7 patterns: good decompositions (rlm_batch for parallel studies, map_files for one-shot extracts) alongside anti-patterns with WHY each fails. |
+| `<rules>` | Standing orders: locate-then-delegate, memoize into `answers`, cap concurrent workers, author edits yourself. |
+
+Key design decisions (v0.3.2):
+
+- **Thinking rule:** the prompt tells the model *when* to plan out loud (complex decomposition,
+  uncertain targets) vs. when to jump straight to `repl()` (known paths, cheap lookups).
+- **Depth visibility:** child RLMs see `Recursion depth: N` in their system prompt and
+  calibrate ambition — they delegate only when their assigned task itself decomposes.
+- **Children are sandboxed:** the prompt explicitly states children cannot mutate the parent's
+  `answers`, `plan`, or REPL variables. Inheritance is one-way (read-only context).
+- **Root tasks wrapped in `<task>` XML tags** so the model cleanly separates user intent from
+  system instructions.
+- **`answer["ready"]` nudge:** runs that never finalize are wasted — the prompt reinforces
+  the contract with an explicit "You MUST flip" directive.
+
+## Subagents and environment
+
+RLM never confiscates native file tools (`read` / `grep` / bash readers) unless `repl` is in
+the **active** tool set — the paper's trade is all-or-nothing. Process-boundary subagents that
+spawn pi with a `--tools` allowlist without `repl` therefore keep ordinary file access.
+
+Optional env conventions (for packages that want an explicit full bypass):
+
+| Env | Meaning |
+|---|---|
+| `PI_SUBAGENT_CHILD=1` | Full RLM bypass in this process (no tools / hooks / flags). |
+| `PI_RLM_FORCE_IN_SUBAGENT=1` | Experimental: opt a child back into RLM. **Consumed on activate** (not inherited after). Refused when `PI_RLM_DEPTH >= maxDepth`. |
+| `PI_RLM_DEPTH` | Cross-process depth counter (default `0`). Bumped when force-in activates. |
+
+In-process recursion (`rlm_query`) still uses `maxDepth` from `/rlm-config` and is unrelated to
+these env vars. Set `RLM_TRACE_FILE` to a path for JSONL traces of bypass / force / block-skip
+decisions.
+
 ## Security
 
 - **Key isolation**: provider keys live only in TypeScript (`AuthStorage`); the sandbox

package/README.ru.md

@@ -104,11 +104,11 @@ rm -rf ~/.pi/agent/extensions/rlm
 | Функция | Сигнатура | Описание |
 |---|---|---|
 | `context` | `list[dict]` | Репозиторий, упакованный как `[{"path","content","tokens"}, ...]` — вся кодовая база |
-| `llm_query` | `(prompt, model=None) -> str` | Одноразовый вызов sub-LLM (worker-модель) |
-| `llm_query_batched` | `(prompts, model=None) -> list[str]` | Параллельные вызовы sub-LLM (с ограничением пула) |
-| `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | Дробит большой текст на части по лимиту и обрабатывает через sub-LLM |
-| `rlm_query` | `(prompt, model=None, paths=None) -> str` | Рекурсивный дочерний RLM со своей песочницей (с ограничением глубины). Наследует ваш `context`; `paths` сужает его по префиксу |
-| `rlm_query_batched` | `(prompts, model=None, paths=None) -> list[str]` | Параллельные рекурсивные дочерние RLM с общим срезом `paths` |
+| `llm_query` | `(prompt) -> str` | Одноразовый вызов sub-LLM (настроенная RLM LLM) |
+| `llm_query_batched` | `(prompts) -> list[str]` | Параллельные вызовы sub-LLM (с ограничением пула) |
+| `llm_query_chunked` | `(text, prompt) -> list[str]` | Дробит большой текст на части по лимиту и обрабатывает через sub-LLM |
+| `rlm_query` | `(prompt, paths=None) -> str` | Рекурсивный дочерний RLM со своей песочницей (с ограничением глубины). Наследует ваш `context`; `paths` сужает его по префиксу |
+| `rlm_query_batched` | `(prompts, paths=None) -> list[str]` | Параллельные рекурсивные дочерние RLM с общим срезом `paths` |
 | `ask_user_question` | `(questions) -> list[dict]` | Задать пользователю структурированные вопросы (только на глубине 0) |
 | `SHOW_VARS` | `() -> str` | Список текущих переменных и их типов |
 | `answer` | `dict` | Установите `answer["content"]=...; answer["ready"]=True` для завершения |

package/README.zh-CN.md

@@ -110,11 +110,11 @@ rm -rf ~/.pi/agent/extensions/rlm
 | 函数 | 签名 | 描述 |
 |---|---|---|
 | `context` | `list[dict]` | 打包为 `[{"path","content","tokens"}, ...]` 的仓库 —— 完整的代码库 |
-| `llm_query` | `(prompt, model=None) -> str` | 单次子 LLM 调用 (worker 模型) |
-| `llm_query_batched` | `(prompts, model=None) -> list[str]` | 并发子 LLM 调用 (池上限) |
-| `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | 将大文本拆分为不超过上限的块并通过子 LLM 处理 |
-| `rlm_query` | `(prompt, model=None, paths=None) -> str` | 具有自有沙箱的递归子 RLM (设有深度限制)。继承父级的 `context`；`paths` 按前缀缩小范围 |
-| `rlm_query_batched` | `(prompts, model=None, paths=None) -> list[str]` | 并发递归子 RLM，共享同一个 `paths` 切片 |
+| `llm_query` | `(prompt) -> str` | 单次子 LLM 调用（配置的 RLM LLM） |
+| `llm_query_batched` | `(prompts) -> list[str]` | 并发子 LLM 调用 (池上限) |
+| `llm_query_chunked` | `(text, prompt) -> list[str]` | 将大文本拆分为不超过上限的块并通过子 LLM 处理 |
+| `rlm_query` | `(prompt, paths=None) -> str` | 具有自有沙箱的递归子 RLM (设有深度限制)。继承父级的 `context`；`paths` 按前缀缩小范围 |
+| `rlm_query_batched` | `(prompts, paths=None) -> list[str]` | 并发递归子 RLM，共享同一个 `paths` 切片 |
 | `ask_user_question` | `(questions) -> list[dict]` | 向用户提出结构化问题 (仅限深度 0) |
 | `SHOW_VARS` | `() -> str` | 列出当前定义的变量及其类型 |
 | `answer` | `dict` | 设置 `answer["content"]=...; answer["ready"]=True` 以结束 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hicaru/pi-rlm",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "author": "hicaru",
   "repository": {
     "type": "git",

package/src/bridge/handlers/await.ts

@@ -0,0 +1,148 @@
+/**
+ * await handler — collect results from background tasks.
+ *
+ * Supports single-task await (await_task(task_id="...")) and multi-task await
+ * (await_task(task_ids=[...])). Returns AwaitResult with the collected result(s)
+ * in input order for batches.
+ */
+
+import { errorMessage, formatError } from "../../util/errors.ts";
+import type { AwaitResult, SubcallHandlerDeps, TaskEntry } from "./types.ts";
+import type { SubcallOpts } from "../../sandbox/interrupts.ts";
+import type { AwaitDeps } from "./task-registry.ts";
+
+export function createAwaitHandler(_deps: SubcallHandlerDeps, ad: AwaitDeps) {
+  return async (
+    taskId: string | undefined,
+    taskIds: readonly string[] | undefined,
+    timeoutS: number | undefined,
+    _depth: number,
+    _opts: SubcallOpts,
+  ): Promise<AwaitResult> => {
+    const timeoutMs = timeoutS !== undefined ? timeoutS * 1000 : undefined;
+
+    // Single task
+    if (taskId !== undefined && (taskIds === undefined || taskIds.length === 0)) {
+      const entry = ad.get(taskId);
+      if (entry === undefined) {
+        return {
+          ok: false,
+          task_id: taskId,
+          kind: "unknown",
+          status: "error",
+          error: `Task ${taskId} not found — was it already awaited or never spawned?`,
+        };
+      }
+
+      if (entry.status === "pending") {
+        try {
+          const resolved = await ad.wait(taskId, timeoutMs);
+          return toAwaitResult(resolved);
+        } catch (err: unknown) {
+          return {
+            ok: false,
+            task_id: taskId,
+            kind: entry.kind,
+            status: "error",
+            error: formatError(errorMessage(err)),
+          };
+        }
+      }
+
+      return toAwaitResult(entry);
+    }
+
+    // Multiple tasks
+    const ids = taskIds ?? (taskId !== undefined ? [taskId] : []);
+    if (ids.length === 0) {
+      return {
+        ok: false,
+        task_id: "",
+        kind: "unknown",
+        status: "error",
+        error: "No task_id or task_ids provided to await",
+      };
+    }
+
+    const entries = ids
+      .map((id) => ad.get(id))
+      .filter((e): e is TaskEntry => e !== undefined);
+
+    if (entries.length === 0) {
+      return {
+        ok: false,
+        task_id: ids[0] ?? "",
+        kind: "unknown",
+        status: "error",
+        error: "None of the requested task IDs were found",
+      };
+    }
+
+    const resolved = await Promise.all(
+      entries.map(async (e) => {
+        if (e.status === "pending") {
+          try {
+            return await ad.wait(e.taskId, timeoutMs);
+          } catch {
+            return e;
+          }
+        }
+        return e;
+      }),
+    );
+
+    const awaited = resolved.map(toAwaitResult);
+    const allDone = awaited.every((a) => a.status === "done");
+    const hasResults = awaited.some((a) => a.results !== undefined);
+    const firstError = awaited.find((a) => a.error)?.error;
+    const first = awaited[0];
+    const kind = first?.kind ?? "unknown";
+
+    if (hasResults) {
+      const allResults: string[] = [];
+      for (const a of awaited) {
+        if (a.results !== undefined) {
+          for (const r of a.results) allResults.push(r);
+        } else if (a.result !== undefined) {
+          allResults.push(a.result);
+        }
+      }
+      return {
+        ok: allDone,
+        task_id: ids.join(","),
+        kind,
+        status: allDone ? "done" : "error",
+        results: Object.freeze(allResults),
+        error: firstError,
+      };
+    }
+
+    if (awaited.length === 1 && first !== undefined) {
+      return first;
+    }
+
+    return {
+      ok: allDone,
+      task_id: ids.join(","),
+      kind,
+      status: allDone ? "done" : "error",
+      results: Object.freeze(awaited.map((a) => a.result ?? a.error ?? "")),
+      error: firstError,
+    };
+  };
+}
+
+function toAwaitResult(entry: TaskEntry): AwaitResult {
+  const status = entry.status === "pending" ? "error" : entry.status;
+  return {
+    ok: entry.status === "done",
+    task_id: entry.taskId,
+    kind: entry.kind,
+    status,
+    result: entry.result,
+    results: entry.results,
+    error:
+      entry.error ??
+      (entry.status === "pending" ? "Task still pending" : undefined),
+  };
+}

package/src/bridge/handlers/completion.ts

@@ -0,0 +1,72 @@
+/**
+ * Single LLM completion — the ONE place a sub-LLM call is made.
+ *
+ * Every leaf completion takes exactly ONE slot on `gates.leaf` here.
+ * Never wrap a whole batch in the leaf gate (deadlock); only complete1 acquires it.
+ *
+ * AGENTS.md DRY #1: complete1 exists once. Never inline another one.
+ */
+
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { type ChatMsg, modelComplete } from "../model.ts";
+import { checkResourceLimits } from "../../core/resource-limits.ts";
+import { errorMessage, formatError } from "../../util/errors.ts";
+import type { Semaphore } from "../../util/concurrency.ts";
+import type { Invocation, SubcallConfig } from "./types.ts";
+
+export interface Complete1Deps {
+  readonly leafGate: Semaphore;
+  readonly registry: ModelRegistry;
+  readonly getLlmModel: () => Model<Api>;
+  readonly getConfig: () => SubcallConfig;
+  readonly signal?: AbortSignal;
+  readonly onUsage?: (usage: Usage, role: "sub") => void;
+}
+
+/**
+ * Run one LLM completion inside the leaf gate.
+ * Never throws — returns formatError(...) strings on failure.
+ */
+export async function complete1(
+  inv: Invocation,
+  prompt: string,
+  track: (usage: Usage) => void,
+  deps: Complete1Deps,
+): Promise<string> {
+  const config = deps.getConfig();
+  const limitError = checkResourceLimits({
+    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.`,
+    );
+  }
+  try {
+    const messages: ChatMsg[] = [{ role: "user", content: prompt }];
+    const res = await deps.leafGate.run(() =>
+      modelComplete(messages, {
+        model: deps.getLlmModel(),
+        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: unknown) {
+    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}`);
+  }
+}

package/src/bridge/handlers/emitting.ts

@@ -0,0 +1,104 @@
+/**
+ * emitting() — the single emit-pattern helper for leaf sub-calls.
+ *
+ * AGENTS.md DRY #5: every leaf subcall follows create-node → execute → update.
+ * rlm_query childRun emits its own node; do not wrap childRun in emitting.
+ */
+
+import type { Usage } from "@earendil-works/pi-ai";
+import { isErrorText } from "../../util/errors.ts";
+import { previewText } from "../../text/preview.ts";
+import type { Invocation } from "./types.ts";
+
+export interface EmitOpts {
+  readonly kind: "llm" | "batch";
+  readonly label: string;
+  readonly args: string;
+  readonly model?: string;
+}
+
+export interface EmitSummary {
+  readonly preview: string;
+  readonly error?: string;
+  readonly failed?: number;
+  readonly total?: number;
+}
+
+/**
+ * Create a subcall node, run `fn`, then update the node with status/cost/preview.
+ * `fn` should not throw for soft failures (prefer Error: strings). Hard throws mark error.
+ */
+export async function emitting<T>(
+  inv: Invocation,
+  opts: EmitOpts,
+  fn: (track: (usage: Usage) => void) => Promise<T>,
+  summarize: (out: T) => EmitSummary,
+): Promise<T> {
+  const id = inv.emitter.emitSubcallCreated({
+    kind: opts.kind,
+    parentId: inv.parentId,
+    label: opts.label,
+    model: opts.model,
+    args: opts.args,
+    depth: inv.depth,
+  });
+
+  let costUsd = 0;
+  let tokens = 0;
+  const track = (u: Usage): void => {
+    costUsd += u.cost.total;
+    tokens += u.totalTokens;
+  };
+
+  try {
+    const out = await fn(track);
+    const summary = summarize(out);
+    inv.emitter.emitSubcallUpdated({
+      id,
+      status: summary.error !== undefined ? "error" : "done",
+      resultPreview: summary.preview,
+      costUsd,
+      tokens,
+      detail: summary.error,
+      failedCount: summary.failed,
+      totalCount: summary.total,
+    });
+    return out;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    inv.emitter.emitSubcallUpdated({
+      id,
+      status: "error",
+      resultPreview: msg,
+      costUsd,
+      tokens,
+      detail: msg,
+    });
+    throw err;
+  }
+}
+
+/** Summarize a batch result for the emitter. */
+export function summarizeBatch(out: readonly string[]): EmitSummary {
+  let failed = 0;
+  let firstError: string | undefined;
+  for (const s of out) {
+    if (isErrorText(s)) {
+      failed += 1;
+      firstError ??= s;
+    }
+  }
+  const first = previewText(out[0] ?? "");
+  const error =
+    failed === 0
+      ? undefined
+      : failed === out.length
+        ? `all ${out.length} sub-calls failed — reduce batch size or try llm_query individually`
+        : `${failed}/${out.length} sub-calls failed`;
+  return {
+    preview: out.length > 1 ? `${first}  (+${out.length - 1} more)` : first,
+    error: error ?? firstError,
+    failed,
+    total: out.length,
+  };
+}

package/src/bridge/handlers/finish.ts

@@ -0,0 +1,45 @@
+/**
+ * finish handler — contract boundary: the model signals completion.
+ *
+ * Soft policy (default): returns finished=true always. If tasks are still pending,
+ * includes `warning` listing unawaited task_ids — does **not** auto-drain results
+ * into the summary (that would hide model mistakes). Callers may refuse to stop
+ * when warning is set.
+ */
+
+import type { FinishResult, SubcallHandlerDeps } from "./types.ts";
+import type { SubcallOpts } from "../../sandbox/interrupts.ts";
+import type { AwaitDeps } from "./task-registry.ts";
+
+export function createFinishHandler(
+  deps: SubcallHandlerDeps,
+  ad?: AwaitDeps,
+) {
+  return async (
+    summary: string,
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<FinishResult & { readonly summary?: string; readonly warning?: string }> => {
+    const inv = deps.resolve(opts, depth);
+    const pending = ad?.unawaitedIds() ?? [];
+    const warning =
+      pending.length > 0
+        ? `finish called with unawaited tasks: ${pending.join(", ")}`
+        : undefined;
+
+    if (inv !== null) {
+      inv.emitter.emitSubcallUpdated?.({
+        id: inv.parentId ?? "root",
+        status: "done",
+        detail: warning ?? "finish called",
+      });
+    }
+
+    return {
+      ok: true,
+      finished: true,
+      summary: summary.length > 0 ? summary : undefined,
+      warning,
+    };
+  };
+}

package/src/bridge/handlers/index.ts

@@ -0,0 +1,48 @@
+/**
+ * createSubcallHandlers — assembles the complete async-by-default handler set.
+ *
+ * This is the ONE place where subcall handlers are wired together. The engine
+ * and repl() tool both call this with their own resolve + trackDetached.
+ *
+ * Task identity lives in TaskRegistry (one implementation). Pass an optional
+ * registry to share session state; otherwise a fresh registry is created.
+ */
+
+import { createLlmQueryHandler, createLlmBatchHandler } from "./llm-query.ts";
+import { createRlmQueryHandler, createRlmBatchHandler } from "./rlm-query.ts";
+import { createAwaitHandler } from "./await.ts";
+import { createFinishHandler } from "./finish.ts";
+import { createTaskRegistry, type TaskRegistry } from "./task-registry.ts";
+import type { SubcallHandlerDeps, SubcallHandlers } from "./types.ts";
+
+export function createSubcallHandlers(
+  deps: SubcallHandlerDeps,
+  registry: TaskRegistry = createTaskRegistry(),
+): SubcallHandlers {
+  // Do NOT call getLlmModel() here — recursion-only tests leave leaf models unwired
+  // and throw if resolved at construction. complete1 reads getLlmModel lazily per call.
+  return {
+    llmQuery: createLlmQueryHandler(deps, registry.spawnDeps),
+    llmBatch: createLlmBatchHandler(deps, registry.spawnDeps),
+    rlmQuery: createRlmQueryHandler(deps, registry.spawnDeps),
+    rlmBatch: createRlmBatchHandler(deps, registry.spawnDeps),
+    awaitTask: createAwaitHandler(deps, registry.awaitDeps),
+    finishTask: createFinishHandler(deps, registry.awaitDeps),
+  };
+}
+
+export type {
+  SubcallHandlerDeps,
+  SubcallHandlers,
+  SpawnResult,
+  AwaitResult,
+  FinishResult,
+  Invocation,
+  InvocationLimits,
+  SubcallConfig,
+} from "./types.ts";
+
+export { limitsFromRemaining } from "./types.ts";
+export { summarizeBatch } from "./emitting.ts";
+export { createTaskRegistry, SPAWN_HINT } from "./task-registry.ts";
+export type { TaskRegistry, SpawnDeps, AwaitDeps } from "./task-registry.ts";

package/src/bridge/handlers/llm-query.ts

@@ -0,0 +1,130 @@
+/**
+ * llm_query and llm_batch handlers — async-by-default spawn pattern.
+ */
+
+import type { Usage } from "@earendil-works/pi-ai";
+import { modelRef } from "../../config/settings.ts";
+import { complete1, type Complete1Deps } from "./completion.ts";
+import { emitting, summarizeBatch } from "./emitting.ts";
+import { formatError, isErrorText } from "../../util/errors.ts";
+import { previewText } from "../../text/preview.ts";
+import type { SpawnResult, SubcallHandlerDeps } from "./types.ts";
+import type { SubcallOpts } from "../../sandbox/interrupts.ts";
+import { SPAWN_HINT, spawnAndRun, type SpawnDeps } from "./task-registry.ts";
+
+const UNWIRED = formatError("RLM bridge not wired for this invocation");
+
+function completeDeps(deps: SubcallHandlerDeps): Complete1Deps {
+  return {
+    leafGate: deps.gates.leaf,
+    registry: deps.registry,
+    getLlmModel: deps.getLlmModel,
+    getConfig: deps.getConfig,
+    signal: deps.signal,
+    onUsage: deps.onUsage,
+  };
+}
+
+function displayModel(deps: SubcallHandlerDeps): string | undefined {
+  try {
+    const m = deps.getLlmModel();
+    return modelRef(m) ?? m.id;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createLlmQueryHandler(
+  deps: SubcallHandlerDeps,
+  sd: SpawnDeps,
+) {
+  return async (
+    prompt: string,
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<SpawnResult> => {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) {
+      return {
+        ok: false,
+        task_id: null,
+        kind: "llm",
+        n: 1,
+        status: "pending",
+        hint: SPAWN_HINT,
+        error: UNWIRED,
+      };
+    }
+
+    const cdeps = completeDeps(deps);
+    return spawnAndRun(
+      sd,
+      "llm",
+      1,
+      () =>
+        emitting(
+          inv,
+          {
+            kind: "llm",
+            label: "llm_query",
+            args: `prompt: ${previewText(prompt)}`,
+            model: displayModel(deps),
+          },
+          (track: (u: Usage) => void) => complete1(inv, prompt, track, cdeps),
+          (out) => ({
+            preview: previewText(out),
+            error: isErrorText(out) ? out : undefined,
+          }),
+        ),
+      deps.trackDetached,
+      opts.detached,
+    );
+  };
+}
+
+export function createLlmBatchHandler(
+  deps: SubcallHandlerDeps,
+  sd: SpawnDeps,
+) {
+  return async (
+    prompts: readonly string[],
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<SpawnResult> => {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) {
+      return {
+        ok: false,
+        task_id: null,
+        kind: "llm_batch",
+        n: prompts.length,
+        status: "pending",
+        hint: SPAWN_HINT,
+        error: UNWIRED,
+      };
+    }
+
+    const cdeps = completeDeps(deps);
+    return spawnAndRun(
+      sd,
+      "llm_batch",
+      prompts.length,
+      () =>
+        emitting(
+          inv,
+          {
+            kind: "batch",
+            label: `llm_batch ×${prompts.length}`,
+            args: `prompt: ${previewText(prompts[0] ?? "")}`,
+            model: displayModel(deps),
+          },
+          // NO outer gate — complete1 takes the single leaf slot per prompt.
+          (track: (u: Usage) => void) =>
+            Promise.all(prompts.map((p) => complete1(inv, p, track, cdeps))),
+          summarizeBatch,
+        ),
+      deps.trackDetached,
+      opts.detached,
+    );
+  };
+}