@hicaru/pi-rlm 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,224 @@
+<div align="center">
+
+<img src="../../assets/hero.png" alt="pi-rlm">
+
+</div>
+
+<div align="center">
+
+<sub>
+<a href="README.md">English</a> &nbsp;·&nbsp; **中文** &nbsp;·&nbsp; <a href="README.ru.md">Русский</a>
+</sub>
+
+</div>
+
+---
+
+# pi-rlm — 为 [Pi](https://github.com/earendil-works) 编程代理提供的递归语言模型 (Recursive Language Models)
+
+<div align="center">
+
+**递归语言模型 (RLMs)** 作为 Pi 扩展原生实现 ——
+无需额外服务器，无需 Docker，无需 socket。
+
+</div>
+
+---
+
+**递归语言模型 (RLM)** 是一种与任务无关的推理范式，其中根语言模型通过对输入进行*编程式*的检查、分解并**递归调用自身**，从而在近乎无限的上下文中进行编排。RLM 将典型的 `llm.completion(prompt, model)` 调用替换为 `rlm.completion(prompt, model)` 调用：提示词/上下文作为 REPL 环境中的一个变量进行卸载，模型与其进行交互，并且模型可以将子 LLM 和子 RLM 调用作为代码中的普通函数启动。
+
+这是对 [CodeAct](https://arxiv.org/abs/2402.01030) 风格框架的一种尝试 —— 每个语言模型都能访问代码环境，子 (R)LM 调用是函数，而上下文/提示词是代码中的对象 —— 从而脱离了 JSON 工具调用 (tool-calling) 标准。以此方式构建的系统*本身*就是一个依赖于递归子 LLM 调用的语言模型，因此得名。
+
+`pi-rlm` 将该范式**原生引入 Pi**：
+
+- **根编排器**模型逐轮驱动一个**持久化的 Python REPL**。
+- 长上下文工作通过 `llm_query` / `llm_query_batched` **委派**给廉价的工作模型。
+- 困难的子问题通过 `rlm_query` **递归**到子 RLM 中（设有深度限制）。
+- 所有内容均**在进程内**运行 —— 唯一的外部进程是一个本地的 `python3` worker。
+
+> 这是 RLM 方法的 Pi 插件重新实现（参见 [RLM 论文](https://arxiv.org/abs/2512.24601)
+> 和 [Python `rlm` 库](https://github.com/alexzhang13/rlm-minimal)）。它**不是**那个 Python 库。
+
+## 工作原理
+
+```
+pi 进程 (TypeScript)
+ ├─ /rlm  ──► 引擎逐轮驱动 SMART (根) 模型 (编写 ```repl``` Python)
+ │             │  每轮：解析 repl 块 ──► 在沙箱中运行 ──► 将 stdout 反馈回去
+ │             ▼
+ ├─ bridge ── llm_query / llm_query_batched ──► WORKER 模型 (serverless, 进程内)
+ │            rlm_query ──► 递归子 RLM (自有沙箱), 设有深度限制
+ ├─ AgentTree ──► 编辑器上方的实时 agent/subagent 树 (角色, 深度, 成本, token)
+ └─ PythonSandbox ── `python3 worker.py` ──[基于 stdio 的 JSONL, 双向]── 持久化 REPL
+```
+
+- **无需服务器，无需 socket，无需 Docker。** 唯一的外部进程是一个本地 `python3` 沙箱。
+  当沙箱代码调用 `llm_query` 时，worker 在 stdout 上写入请求并在 stdin 上阻塞；
+  Pi 在进程内提供服务并将回复写回。**供应商 API 密钥绝不会进入沙箱。**
+- 沙箱公开了 `context`, `llm_query`, `llm_query_batched`, `rlm_query`,
+  `rlm_query_batched`, `SHOW_VARS()`, `todo()`, `ask_user_question()` 以及一个 `answer` 字典。
+  模型通过设置 `answer["ready"] = True` 来提交最终结果。
+
+## 安装
+
+`pi-rlm` 是一个 Pi 包。Pi 提供了 `@earendil-works/pi-*` 和 `typebox` peer
+依赖；请**不要**在该包中安装它们的独立副本。要求 `PATH` 中有 `python3` (仅限标准库)。
+
+开发时的推荐本地安装方式：
+
+```bash
+pi install /path/to/this-repo/pi-plugin/rlm
+```
+
+已发布的 npm 包安装方式：
+
+```bash
+npm publish                       # 例如 as @<you>/pi-rlm
+pi install npm:@<you>/pi-rlm
+```
+
+> **Git 安装**要求包清单位于安装的仓库根目录下。
+> 对于像这样一个 monorepo 子目录，请优先使用上述的本地路径或 npm 流程。
+
+如果您之前直接复制了扩展文件夹，请将其删除，以免遮蔽 (shadow) 该包：
+
+```bash
+rm -rf ~/.pi/agent/extensions/rlm
+```
+
+然后运行 `/reload` 或重启 Pi。使用 `pi list` 验证该包是否出现在
+`settings.packages` 中，并检查 `/rlm`, `/rlm-config` 和 `/rlm-stop` 是否出现在 **[Extensions]** 下。
+
+## 命令
+
+| 命令 | 快捷键 | 描述 |
+|---|---|---|
+| `/rlm` | `Ctrl+Shift+R` | 切换持久化 RLM 模式 (通过 RLM 引擎路由普通提示词) |
+| `/rlm-stop` | | 终止正在运行的任务 |
+| `/rlm-config` | | 选择 smart + worker 模型并调整运行设置 |
+| `/rlm-resume` | | 恢复被中断的任务 (默认 `@latest`) |
+| `/rlm-runs` | | 列出最近的任务 |
+| `/rlm-help` | | 显示启动指南和速查表 |
+
+在任务激活期间，一个**实时树**会显示根编排器和每个子 LLM /
+递归子节点的状态、模型、成本、token 和持续时间。最终答案将以 markdown 形式发布
+到聊天中；任何代码修改将作为 diff 收集并通过弹出窗口进行审核 (除非开启了 `yolo`)。
+
+## 沙箱 API
+
+这些函数被注入到 REPL 内部模型的 Python 命名空间中：
+
+| 函数 | 签名 | 描述 |
+|---|---|---|
+| `context` | `list[dict]` | 打包为 `[{"path","content","tokens"}, ...]` 的仓库 —— 完整的代码库 |
+| `llm_query` | `(prompt, model=None) -> str` | 单次子 LLM 调用 (worker 模型) |
+| `llm_query_batched` | `(prompts, model=None) -> list[str]` | 并发子 LLM 调用 (池上限) |
+| `rlm_query` | `(prompt, model=None) -> str` | 具有自有沙箱的递归子 RLM (设有深度限制) |
+| `rlm_query_batched` | `(prompts, model=None) -> list[str]` | 并发递归子 RLM |
+| `todo` | `(action, **kwargs) -> str` | 任务列表：`create`/`update`/`list`/`get`/`delete`/`clear` |
+| `ask_user_question` | `(questions) -> list[dict]` | 向用户提出结构化问题 (仅限深度 0) |
+| `SHOW_VARS` | `() -> str` | 列出当前定义的变量及其类型 |
+| `answer` | `dict` | 设置 `answer["content"]=...; answer["ready"]=True` 以结束 |
+
+## 设置 (`/rlm-config`)
+
+| 设置 | 默认值 | 含义 |
+|---|---|---|
+| Smart model | Pi 的当前活动模型 | 根编排器 |
+| Worker model | 最便宜的可用模型 | 响应 `llm_query` |
+| Max recursion depth | `4` | 超过此深度的 `rlm_query` 将回退到 `llm_query` |
+| Max iterations | `30` | 引擎完成前的最大轮数 |
+| Budget ceiling | none | 当美元支出超过此值时停止整个树 |
+| Max consecutive errors | `5` | 在 N 轮连续错误后停止 |
+| REPL block timeout | `120s` | 每个 `repl` 块的墙上时钟时间 (worker 中的 SIGALRM) |
+| Max concurrent sub-calls | `4` | `*_batched` 的池大小 |
+| Orchestrator addendum | on | “委派，而非自行解决”的引导 |
+| Trajectory compaction | on (0.85) | 当历史记录接近上下文窗口时进行总结 |
+| `yolo` | off | 立即应用建议的修改，跳过审核弹出窗 |
+| `askUserQuestion` | on | 向模型公开 `ask_user_question()` |
+| `todo` | on | 向模型公开 `todo()` |
+
+> **并发注意：** 每个 `rlm_query` 子节点都会启动自己的 `python3` worker (冷启动约 50–150 毫秒)。
+> 最坏情况下的并发解释器数量 ≈ `maxConcurrentSubcalls`^(depth−1)；在
+> 默认设置下 (深度 4, 并发 4)，极端情况下为 4³ = 64。预算和错误
+> 上限 (见上文) 无论扇出 (fan-out) 如何都会限制总支出。
+
+## 遥测与运行日志
+
+- **运行日志** (`runLog`)：默认始终开启。每次运行将 JSONL 轨迹写入 `.rlm/runs/`
+  (默认)，上限为 `maxRuns` (50)。支持通过 `/rlm-resume` 进行**快照** (`sandbox.pkl`) 和**恢复**
+  被中断的任务。快照受每个会话的 `nonce` 保护，以防止跨会话重放。
+- **MLflow 追踪** (`telemetry`)：可选。设置 `MLFLOW_TRACKING_URI` 或在
+  `/rlm-config` 中配置 `trackingUri` / `experimentId`。根运行被标记为 MLflow span
+  以便在恢复时进行追踪关联。Bearer 令牌来自 `MLFLOW_TRACKING_TOKEN`
+  环境变量，且**绝不会**持久化到 `rlm.json`。
+
+## 安全性
+
+- **密钥隔离**：供应商密钥仅存在于 TypeScript (`AuthStorage`) 中；沙箱
+  接收提示词并返回文本 —— 绝不接触密钥。
+- **环境清理**：在 worker 启动前会剥离敏感环境变量 (API 密钥, token)。
+  worker 无法从 `os.environ` 读取供应商凭据。
+- **并非安全沙箱**：Python worker 公开了 `__import__` 和 `open`。模型编写的
+  代码可以导入网络模块、读写本地文件，并向 stdout 写入符合协议格式的 JSON。
+  此层级信任根模型的代码；stdio 协议隔离的是供应商密钥和
+  进程生命周期，**而非**对抗性代码的隔离。以后可以在不改变协议的情况下，
+  通过设置添加更强的沙箱 (Docker, seccomp)。
+- **限制内置函数**：禁用 `eval`/`exec`/`compile`/`input`/`globals`/`locals`；每块
+  SIGALRM 超时 + 父进程监视器 (挂起时 SIGKILL)；预算 / token / 超时 /
+  连续错误上限。
+- **信任**：本地安装需要 Pi 项目信任。
+
+## 项目布局
+
+```
+src/
+  sandbox/    worker.py + JSONL stdio driver (PythonSandbox) · protocol.ts · sandbox-manager.ts
+  bridge/     model.ts (one-shot completion) · llm-query.ts · rlm-query.ts (recursion)
+  core/       engine.ts (the loop) · iteration · limits · answer · compaction · pipeline · types
+  prompts/    system + per-turn prompts (ported from the Python reference)
+  text/       parsing (repl blocks) · tokens · preview · edits
+  state/      agent-tree · events · reads/writes · resume · paths · rows
+  tool/       repl-tool · rlm-events · aggregator · propose-edits · emitter-listener
+  config/     defaults · settings (rlm.json persistence + validation)
+  context/    repomix-based repository packing + caching
+  telemetry/  MLflow sink · dispatcher · mlflow-config
+  ui/         tree-widget · status · model-picker · config-panel · intro · theme
+  commands/   rlm · rlm-config
+  mode/       rlm-mode (controller) · input-router
+  patch/      apply · popup · index
+  util/       errors · concurrency
+test/         phase1–phase9 · native-smoke · native-mode · helpers
+```
+
+## 测试
+
+运行时为 **Bun** (`bun install`, `bun run …` —— 绝不要使用 npm/pnpm/yarn)。
+
+```bash
+bun run test/phase1.ts                   # 沙箱：执行, 持久化, 密钥隔离, 超时终止
+bun run test/phase4.ts                   # 递归深度限制逻辑 (不消耗 token)
+bun run test/phase5.ts                   # 实时 agent 树渲染 (不消耗 token)
+RLM_TEST_LIVE=1 bun run test/phase2.ts   # 通过沙箱进行真实的 llm_query
+RLM_TEST_LIVE=1 bun run test/phase3.ts   # 在文件上下文中进行真实的端到端 /rlm 运行
+RLM_TEST_LIVE=1 bun run test/phase4.ts   # 引擎解决 20 个文档的“大海捞针”测试
+```
+
+## 背景
+
+基于 Python 参考实现 [`rlm`](https://github.com/alexzhang13/rlm-minimal) 和
+[RLM 论文](https://arxiv.org/abs/2512.24601) 中的方法，为 Pi 原生重新实现。
+
+如果您在研究中使用此项目，请引用原始 RLM 工作：
+
+```bibtex
+@misc{zhang2026recursivelanguagemodels,
+      title={Recursive Language Models},
+      author={Alex L. Zhang and Tim Kraska and Omar Khattab},
+      year={2026},
+      eprint={2512.24601},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2512.24601},
+}
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hicaru/pi-rlm",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Recursive Language Model (RLM) for the Pi coding agent — native, server-less.",
+  "license": "MIT",
+  "author": "hicaru",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hicaru/rlm.pi.git"
+  },
+  "homepage": "https://github.com/hicaru/rlm.pi",
+  "bugs": {
+    "url": "https://github.com/hicaru/rlm.pi/issues"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run check"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.79.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.0",
+    "@earendil-works/pi-tui": ">=0.79.0",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "@mlflow/core": "~0.2.0",
+    "diff": "^9.0.0",
+    "repomix": "^1.15.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/bridge/fallback-todo.ts

@@ -0,0 +1,137 @@
+import { formatError } from "../util/errors.ts";
+
+type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+
+interface Task {
+  readonly id: number;
+  readonly subject: string;
+  readonly description?: string;
+  readonly status: TaskStatus;
+  readonly activeForm?: string;
+  readonly blockedBy?: readonly number[];
+  readonly owner?: string;
+}
+
+interface TodoParams {
+  readonly id?: number;
+  readonly subject?: string;
+  readonly description?: string;
+  readonly status?: TaskStatus;
+  readonly activeForm?: string;
+  readonly blockedBy?: readonly number[];
+  readonly addBlockedBy?: readonly number[];
+  readonly removeBlockedBy?: readonly number[];
+  readonly owner?: string;
+  readonly filterStatus?: string;
+  readonly includeDeleted?: boolean;
+}
+
+const TODO_STATUSES = Object.freeze(new Set<unknown>(["pending", "in_progress", "completed", "deleted"]));
+
+function isTaskStatus(value: unknown): value is TaskStatus {
+  return TODO_STATUSES.has(value);
+}
+
+function numericArray(value: unknown): readonly number[] | undefined {
+  return Array.isArray(value) ? Object.freeze(value.filter((n): n is number => typeof n === "number")) : undefined;
+}
+
+function toTodoParams(raw: Record<string, unknown>): TodoParams {
+  const blockedBy = numericArray(raw.blockedBy);
+  const addBlockedBy = numericArray(raw.addBlockedBy);
+  const removeBlockedBy = numericArray(raw.removeBlockedBy);
+  return Object.freeze({
+    ...(typeof raw.id === "number" ? { id: raw.id } : {}),
+    ...(typeof raw.subject === "string" ? { subject: raw.subject } : {}),
+    ...(typeof raw.description === "string" ? { description: raw.description } : {}),
+    ...(isTaskStatus(raw.status) ? { status: raw.status } : {}),
+    ...(typeof raw.activeForm === "string" ? { activeForm: raw.activeForm } : {}),
+    ...(blockedBy ? { blockedBy } : {}),
+    ...(addBlockedBy ? { addBlockedBy } : {}),
+    ...(removeBlockedBy ? { removeBlockedBy } : {}),
+    ...(typeof raw.owner === "string" ? { owner: raw.owner } : {}),
+    ...(typeof raw.filterStatus === "string" ? { filterStatus: raw.filterStatus } : {}),
+    ...(raw.includeDeleted === true ? { includeDeleted: true } : {}),
+  });
+}
+
+function patchedBlockedBy(task: Task, params: TodoParams): readonly number[] | undefined {
+  if (params.blockedBy) return params.blockedBy;
+
+  let next = task.blockedBy ?? Object.freeze([] as readonly number[]);
+  if (params.addBlockedBy) next = Object.freeze([...next, ...params.addBlockedBy]);
+
+  if (params.removeBlockedBy) {
+    const removeSet = new Set(params.removeBlockedBy);
+    next = Object.freeze(next.filter((n) => !removeSet.has(n)));
+  }
+  return next.length ? next : undefined;
+}
+
+function taskLines(task: Task): readonly string[] {
+  const lines: string[] = [`#${task.id} [${task.status}] ${task.subject}`];
+  if (task.description) lines.push(`  description: ${task.description}`);
+  if (task.activeForm) lines.push(`  activeForm: ${task.activeForm}`);
+  if (task.blockedBy?.length) lines.push(`  blockedBy: ${task.blockedBy.map((n) => `#${n}`).join(", ")}`);
+  if (task.owner) lines.push(`  owner: ${task.owner}`);
+  return lines;
+}
+
+function withPatch(task: Task, params: TodoParams): Task {
+  const blockedBy = patchedBlockedBy(task, params);
+  return Object.freeze({
+    ...task,
+    ...(params.subject !== undefined ? { subject: params.subject } : {}),
+    ...(params.description !== undefined ? { description: params.description } : {}),
+    ...(params.status !== undefined ? { status: params.status } : {}),
+    ...(params.activeForm !== undefined ? { activeForm: params.activeForm } : {}),
+    ...(blockedBy ? { blockedBy } : {}),
+    ...(params.owner !== undefined ? { owner: params.owner } : {}),
+  });
+}
+
+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 => {
+    const params = toTodoParams(rawParams);
+    if (action === "clear") {
+      const count = tasks.length;
+      tasks = Object.freeze([]);
+      nextId = 1;
+      return `Cleared ${count} task(s).`;
+    }
+    if (action === "create") {
+      const subject = typeof params.subject === "string" && params.subject.trim() ? params.subject.trim() : undefined;
+      if (!subject) return formatError("create requires subject");
+      const task = withPatch(Object.freeze({ id: nextId, subject, status: "pending" }), params);
+      nextId += 1;
+      tasks = Object.freeze([...tasks, task]);
+      return `Created ${fmt(task)}`;
+    }
+    if (action === "list") {
+      const filter = params.filterStatus ?? params.status;
+      const includeDeleted = params.includeDeleted === true;
+      const rows = tasks.filter((task) => (includeDeleted || task.status !== "deleted") && (!filter || task.status === filter)).map(fmt);
+      return rows.length ? rows.join("\n") : "No tasks.";
+    }
+    const id = params.id;
+    const task = id !== undefined ? tasks.find((item) => item.id === id) : undefined;
+    if (!task) return formatError(`task #${id ?? "?"} not found`);
+    if (action === "get") return taskLines(task).join("\n");
+    if (action === "delete") {
+      const deleted = Object.freeze({ ...task, status: "deleted" as const });
+      tasks = Object.freeze(tasks.map((item) => item.id === task.id ? deleted : item));
+      return `Deleted ${fmt(deleted)}`;
+    }
+    if (action === "update") {
+      const updated = withPatch(task, params);
+      tasks = Object.freeze(tasks.map((item) => item.id === task.id ? updated : item));
+      return `Updated ${fmt(updated)}`;
+    }
+    return formatError(`unknown todo action '${action}'`);
+  };
+  return async (action, params) => apply(action, params);
+}

package/src/bridge/interactive.ts

@@ -0,0 +1,65 @@
+import type { AskAnswer, AskQuestion } from "../sandbox/protocol.ts";
+import type { SubLlmHandlers } from "../sandbox/sandbox.ts";
+import type { RlmEmitter } from "../tool/rlm-events.ts";
+import { formatError } from "../util/errors.ts";
+
+export interface InteractiveBridgeOpts {
+  readonly onAskUserQuestion?: (questions: readonly AskQuestion[]) => Promise<AskAnswer[]>;
+  readonly onTodo?: (action: string, params: Record<string, unknown>) => Promise<string>;
+  readonly onTodoRow?: (action: string, params: Record<string, unknown>, result: string) => void | Promise<void>;
+  readonly emitter?: RlmEmitter;
+  readonly depth: number;
+  readonly parentId?: string;
+}
+
+export function buildInteractiveHandlers(opts: InteractiveBridgeOpts): {
+  askUserQuestion: SubLlmHandlers["askUserQuestion"];
+  todo: SubLlmHandlers["todo"];
+} {
+  return {
+    async askUserQuestion(questions, depth) {
+      if (depth > 0) return questions.map((q) => ({
+        question: q.question,
+        selected: [],
+        custom: formatError("ask_user_question not available inside rlm_query sub-calls"),
+      }));
+
+      const id = opts.emitter?.emitSubcallCreated({
+        kind: "tool", parentId: opts.parentId,
+        label: "ask_user_question",
+        args: `${questions.length} question(s)`,
+        depth,
+      });
+      try {
+        const cb = opts.onAskUserQuestion;
+        if (!cb) throw new Error("ask_user_question not configured (no onAskUserQuestion callback)");
+        const answers = await cb(questions);
+        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "done" });
+        return answers;
+      } catch (err) {
+        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "error", detail: String(err) });
+        throw err;
+      }
+    },
+
+    async todo(action, params, depth) {
+      const id = opts.emitter?.emitSubcallCreated({
+        kind: "tool", parentId: opts.parentId,
+        label: `todo:${action}`,
+        args: params.subject ? String(params.subject) : String(params.id ?? ""),
+        depth,
+      });
+      try {
+        const cb = opts.onTodo;
+        if (!cb) throw new Error("todo not configured (no onTodo callback)");
+        const result = await cb(action, params);
+        await opts.onTodoRow?.(action, params, result);
+        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "done", resultPreview: result.slice(0, 80) });
+        return result;
+      } catch (err) {
+        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "error", detail: String(err) });
+        throw err;
+      }
+    },
+  };
+}

package/src/bridge/llm-query.ts

@@ -0,0 +1,124 @@
+/**
+ * The `llm_query` / `llm_query_batched` bridge: turns sandbox sub-LLM interrupts into
+ * real (serverless) completions on the configured *worker* model, reporting each call to the
+ * RlmEmitter for progressive TUI re-rendering.
+ *
+ * Caps enforce the divide-and-conquer budget from the RLM method: per-prompt size and batch
+ * fan-out are bounded, and batches run through a fixed-size concurrency pool.
+ */
+
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { RlmEmitter } from "../tool/rlm-events.ts";
+import { modelRef, resolveModelId } from "../config/settings.ts";
+import type { Sampling } from "../core/types.ts";
+import { type ChatMsg, modelComplete } from "./model.ts";
+import { previewText } from "../text/preview.ts";
+import { formatError, isErrorText } from "../util/errors.ts";
+import { mapPool } from "../util/concurrency.ts";
+
+export interface LlmBridgeOptions {
+  readonly workerModel: Model<Api>;
+  readonly registry: ModelRegistry;
+  readonly subSystem?: string;
+  readonly maxPromptChars?: number;
+  readonly maxConcurrent?: number;
+  readonly sampling?: Sampling;
+  readonly signal?: AbortSignal;
+  readonly onUsage?: (usage: Usage, model: Model<Api>) => void;
+  /** Live RlmDetails reporting via onUpdate. */
+  readonly emitter?: RlmEmitter;
+  readonly parentId?: string;
+  readonly depth?: number;
+}
+
+const DEFAULT_MAX_PROMPT_CHARS = 400_000;
+const DEFAULT_MAX_CONCURRENT = 4;
+
+export interface LlmBridge {
+  llmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
+  llmQueryBatched(prompts: string[], model: string | null, depth: number): Promise<string[]>;
+}
+
+export function createLlmBridge(opts: LlmBridgeOptions): LlmBridge {
+  const maxPromptChars = opts.maxPromptChars ?? DEFAULT_MAX_PROMPT_CHARS;
+  const maxConcurrent = opts.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+  const { emitter } = opts;
+  const displayModel = (model: string | null): string =>
+    modelRef(model ? (resolveModelId(opts.registry, model) ?? opts.workerModel) : opts.workerModel) ?? opts.workerModel.id;
+
+  // Run one completion; report cost/tokens via `track` (a per-call or per-batch accumulator).
+  async function complete1(prompt: string, model: string | null, track: (u: Usage) => void): Promise<string> {
+    if (prompt.length > maxPromptChars) {
+      return formatError(`sub-LLM prompt exceeded the size limit (${prompt.length.toLocaleString()} chars > ${maxPromptChars.toLocaleString()}). Shorten or chunk the prompt before calling llm_query.`);
+    }
+    const resolved = model ? resolveModelId(opts.registry, model) : undefined;
+    if (model && !resolved) return formatError(`unknown model override '${model}'`);
+    try {
+      const messages: ChatMsg[] = [{ role: "user", content: prompt }];
+      const res = await modelComplete(messages, {
+        model: resolved ?? opts.workerModel,
+        registry: opts.registry,
+        system: opts.subSystem,
+        maxTokens: opts.sampling?.maxTokens,
+        temperature: opts.sampling?.temperature,
+        reasoning: opts.sampling?.reasoning,
+        signal: opts.signal,
+      });
+      opts.onUsage?.(res.usage, resolved ?? opts.workerModel);
+      track(res.usage);
+      return res.text;
+    } catch (err) {
+      return formatError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  return {
+    async llmQuery(prompt, model) {
+      const id = emitter?.emitSubcallCreated({
+        kind: "llm", parentId: opts.parentId, label: "llm_query",
+        model: displayModel(model), args: `prompt: ${previewText(prompt)}`,
+        depth: opts.depth ?? 0,
+      });
+      let cost = 0;
+      let tokens = 0;
+      const out = await complete1(prompt, model, (u) => {
+        cost += u.cost.total;
+        tokens += u.totalTokens;
+      });
+      if (emitter && id !== undefined) emitter.emitSubcallUpdated({ id,
+        status: isErrorText(out) ? "error" : "done",
+        costUsd: cost, tokens, resultPreview: previewText(out),
+        detail: isErrorText(out) ? out : undefined,
+      });
+      return out;
+    },
+
+    async llmQueryBatched(prompts, model) {
+      const id = emitter?.emitSubcallCreated({
+        kind: "batch", parentId: opts.parentId, label: `llm_query ×${prompts.length}`,
+        model: displayModel(model), args: `prompt: ${previewText(prompts[0] ?? "")}`,
+        depth: opts.depth ?? 0,
+      });
+      let cost = 0;
+      let tokens = 0;
+      const out = await mapPool(prompts, maxConcurrent, (p) =>
+        complete1(p, model, (u) => {
+          cost += u.cost.total;
+          tokens += u.totalTokens;
+        }),
+      );
+      const failed = out.filter(isErrorText).length;
+      const error = failed === out.length && out.length > 0
+        ? `all ${out.length} sub-calls failed`
+        : failed > 0 ? `${failed}/${out.length} sub-calls failed` : undefined;
+      const firstPreview = previewText(out[0] ?? "");
+      const resultPreview = out.length > 1 ? `${firstPreview}  (+${out.length - 1} more)` : firstPreview;
+      if (emitter && id !== undefined) emitter.emitSubcallUpdated({ id,
+        status: error ? "error" : "done", costUsd: cost, tokens,
+        resultPreview, detail: error,
+      });
+      return out;
+    },
+  };
+}