@hicaru/pi-rlm 0.1.9 → 0.2.1

package/src/util/concurrency.ts

@@ -1,15 +1,89 @@
-/** Fixed-size concurrency pool: run `fn` over `items` with at most `limit` in flight, preserving order. */
-export async function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, idx: number) => Promise<R>): Promise<R[]> {
-  const out = new Array<R>(items.length);
-  let next = 0;
-  const worker = async (): Promise<void> => {
-    while (true) {
-      const index = next;
-      next += 1;
-      if (index >= items.length) return;
-      out[index] = await fn(items[index], index);
+/**
+ * Sub-call admission control.
+ *
+ * `spawn()` lets the sandbox put many requests on the wire at once, so a per-call pool no
+ * longer bounds anything: one `llm_query_chunked` over a large file posts every batch
+ * simultaneously, and each batch fans out again. The bound has to be session-wide, which is
+ * what `SubcallGates` is — constructed once at the composition root and shared by every
+ * handler.
+ */
+
+/**
+ * Counting semaphore: at most `limit` holders at once, FIFO.
+ *
+ * NOT re-entrant. A leaf completion takes exactly ONE slot, in `complete1`; wrapping a batch in
+ * a second acquisition of this same gate deadlocks as soon as the batch reaches `limit`
+ * prompts — the outer holders fill the gate and each waits for an inner slot nothing can free.
+ *
+ * FIFO means a large fan-out is not starved, but also that it is not preempted: a
+ * 500-prompt `llm_query_chunked` holds the queue until it drains, so an interactive
+ * `llm_query` issued behind it waits for the whole thing. Acceptable while sub-calls are
+ * uniform in priority; revisit if an interactive tier is ever added.
+ */
+export class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(private readonly limit: number) {}
+
+  /** Hold a slot for the duration of `fn`. */
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    // `while`, not `if`: a caller arriving between the decrement below and a woken waiter's
+    // resumption would otherwise slip past the limit.
+    while (this.active >= this.limit) {
+      await new Promise<void>((resolve) => { this.waiters.push(resolve); });
     }
-  };
-  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
-  return out;
+    this.active += 1;
+    try {
+      return await fn();
+    } finally {
+      this.active -= 1;
+      this.waiters.shift()?.();
+    }
+  }
+
+  /** In-flight holders. Exposed for tests asserting the bound. */
+  get inFlight(): number {
+    return this.active;
+  }
+}
+
+/**
+ * One semaphore per recursion depth.
+ *
+ * A single shared gate would deadlock: `limit` rlm_query children holding every slot, each
+ * blocked waiting for a grandchild that can never be admitted. Splitting by depth breaks the
+ * cycle — a holder at depth k only ever waits on depth k+1. Leaf LLM calls are terminal and
+ * never re-enter, so they safely share one process-wide gate.
+ */
+export class DepthGates {
+  private readonly gates = new Map<number, Semaphore>();
+
+  constructor(private readonly limit: number) {}
+
+  at(depth: number): Semaphore {
+    let gate = this.gates.get(depth);
+    if (gate === undefined) {
+      gate = new Semaphore(this.limit);
+      this.gates.set(depth, gate);
+    }
+    return gate;
+  }
+}
+
+/** Session-wide sub-call admission. Construct once; pass explicitly — never default one in. */
+export interface SubcallGates {
+  /** llm_query / llm_query_batched completions — terminal, so one shared gate. */
+  readonly leaf: Semaphore;
+  /** Recursive child engines — one gate per depth, see DepthGates. */
+  readonly rlm: DepthGates;
+}
+
+/**
+ * Worst case is `maxDepth × limit` concurrent child engines (each owning a Python
+ * subprocess) plus `limit` leaf completions, so keep `limit` modest — see
+ * DEFAULT_CONFIG.maxConcurrentSubcalls.
+ */
+export function createSubcallGates(limit: number): SubcallGates {
+  return Object.freeze({ leaf: new Semaphore(limit), rlm: new DepthGates(limit) });
 }

package/src/util/trace.ts

@@ -0,0 +1,42 @@
+/**
+ * RLM trace — one JSONL line per interesting event, for the E2E harness and for post-mortem of
+ * a hung run. Off unless RLM_TRACE_FILE is set; when off, every call costs one boolean check.
+ *
+ * Purely observational: it subscribes to the RlmEmitter that already exists and to the sandbox
+ * frames that already cross the pipe. No behaviour is duplicated here.
+ */
+import { appendFileSync } from "node:fs";
+import type { RlmEmitter } from "../tool/rlm-events.ts";
+
+const FILE = process.env.RLM_TRACE_FILE;
+
+/** Check this before building payloads on hot paths. */
+export const traceEnabled: boolean = typeof FILE === "string" && FILE.length > 0;
+
+const START = Date.now();
+
+/** Append one event. Fail-soft: tracing must never break a run (state/writes.ts convention). */
+export function trace(kind: string, data: Record<string, unknown> = {}): void {
+  if (!traceEnabled || FILE === undefined) return;
+  const now = Date.now();
+  try {
+    appendFileSync(FILE, `${JSON.stringify({ t: now, rel: now - START, pid: process.pid, kind, ...data })}\n`);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Mirror one emitter's sub-call lifecycle into the trace. Returns an unsubscribe fn. */
+export function attachTracer(emitter: RlmEmitter, scope: "turn" | "background"): () => void {
+  if (!traceEnabled) return () => {};
+  // Rename e.kind → subcallKind so it does not overwrite the outer event kind
+  // (`subcall.created` / `subcall.updated`) when `trace` spreads `data` after `kind`.
+  const offs = [
+    emitter.onSubcallCreated((e) => {
+      const { kind: subcallKind, ...rest } = e;
+      trace("subcall.created", { scope, subcallKind, ...rest });
+    }),
+    emitter.onSubcallUpdated((e) => trace("subcall.updated", { scope, ...e })),
+  ];
+  return () => { for (const off of offs) off(); };
+}

package/src/bridge/llm-query.ts

@@ -1,133 +0,0 @@
-/**
- * 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 { checkResourceLimits, type RemainingResources } from "../core/resource-limits.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;
-  /** Parent run's remaining budget/timeout; checked before every sub-call. */
-  readonly remainingBudget?: () => RemainingResources;
-  /** 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> {
-    const rem = opts.remainingBudget?.();
-    if (rem !== undefined) {
-      const limitError = checkResourceLimits(rem);
-      if (limitError !== undefined) return limitError;
-    }
-    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,
-        failedCount: failed, totalCount: out.length,
-      });
-      return out;
-    },
-  };
-}

package/src/bridge/rlm-query.ts

@@ -1,122 +0,0 @@
-/**
- * The `rlm_query` recursion bridge.
- *
- * A child RLM gets its own sandbox and iterates over the prompt as its context. At/over the
- * depth cap it degrades to a plain `llm_query` (ported from rlm/core/rlm.py `_subcall`). The
- * concurrency pool bounds parallel children for `rlm_query_batched`.
- *
- * `childRun` is the single spawn path shared by `rlmQuery` / `rlmQueryBatched`.
- */
-
-import type { RlmResult, RunRlm } from "../core/types.ts";
-import type { LlmBridge } from "./llm-query.ts";
-import type { RlmEmitter } from "../tool/rlm-events.ts";
-import { checkResourceLimits } from "../core/resource-limits.ts";
-import { formatError } from "../util/errors.ts";
-import { mapPool } from "../util/concurrency.ts";
-
-export interface ChildRunInput {
-  readonly rootPrompt: string;
-  readonly context: unknown;
-  readonly depth: number;
-  readonly label?: string;
-  readonly model?: string | null;
-}
-
-export interface RlmHandlers {
-  rlmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
-  rlmQueryBatched(prompts: string[], model: string | null, depth: number): Promise<string[]>;
-  /** Full child-run result (answer + usage) for recursive spawns. */
-  childRun(input: ChildRunInput): Promise<RlmResult>;
-}
-
-export interface RlmBridgeOptions {
-  readonly run: RunRlm;
-  readonly llm: LlmBridge;
-  /** Live RlmDetails reporting via onUpdate. Required — replaces SubcallObserver for recursive subcalls. */
-  readonly emitter: RlmEmitter;
-  readonly maxDepth: number;
-  readonly maxConcurrent: number;
-  /** Parent subcall ID that this run is attached under. */
-  readonly parentNodeId?: string;
-  /** Returns the parent's remaining budget/timeout for seeding child runs. */
-  readonly remainingBudget?: () => { readonly budgetUsd?: number; readonly timeoutMs?: number };
-  /** Called with a child run's total cost/tokens so the parent LimitGuard debits it. */
-  readonly onChildUsage?: (costUsd: number, inputTokens: number, outputTokens: number) => void;
-}
-
-function emptyResult(answer: string): RlmResult {
-  return {
-    answer,
-    iterations: 0,
-    costUsd: 0,
-    inputTokens: 0,
-    outputTokens: 0,
-    durationMs: 0,
-  };
-}
-
-export function createRlmHandlers(opts: RlmBridgeOptions): RlmHandlers {
-  async function childRun(input: ChildRunInput): Promise<RlmResult> {
-    const childDepth = input.depth;
-    // At the cap, a child RLM would just be an LM — short-circuit to a one-shot llm_query.
-    // (Callers pass the absolute child depth; rlmQuery wraps with depth+1.)
-    if (childDepth >= opts.maxDepth) {
-      const answer = await opts.llm.llmQuery(
-        input.rootPrompt || String(input.context),
-        input.model ?? null,
-        childDepth - 1,
-      );
-      return emptyResult(answer);
-    }
-    let subId: string | undefined;
-    try {
-      const rem = opts.remainingBudget?.() ?? {};
-      // Pre-spawn guard: refuse if the parent's budget or timeout is already exhausted
-      // (reference: _subcall checks remaining_budget/timeout before spawning).
-      const limitError = checkResourceLimits(rem);
-      if (limitError) return emptyResult(limitError);
-      const label = input.label ?? "rlm_query";
-      const detailSource = input.rootPrompt || String(input.context);
-      subId = opts.emitter.emitSubcallCreated({
-        kind: "rlm", parentId: opts.parentNodeId, label,
-        model: input.model ?? undefined, detail: detailSource.slice(0, 60),
-        depth: childDepth,
-      });
-      const res = await opts.run({
-        rootPrompt: input.rootPrompt,
-        context: input.context,
-        depth: childDepth,
-        parentNodeId: subId,
-        modelOverride: input.model ?? undefined,
-        remainingBudgetUsd: rem.budgetUsd,
-        remainingTimeoutMs: rem.timeoutMs,
-      });
-      opts.onChildUsage?.(res.costUsd, res.inputTokens, res.outputTokens);
-      opts.emitter.emitSubcallUpdated({ id: subId,
-        status: "done", resultPreview: res.answer.slice(0, 200),
-      });
-      return res;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (subId) opts.emitter.emitSubcallUpdated({ id: subId, status: "error", detail: msg });
-      return emptyResult(formatError(`child RLM failed - ${msg}`));
-    }
-  }
-
-  async function child(prompt: string, model: string | null, depth: number): Promise<string> {
-    const res = await childRun({
-      rootPrompt: "",
-      context: prompt,
-      depth: depth + 1,
-      model,
-    });
-    return res.answer;
-  }
-
-  return {
-    rlmQuery: (prompt, model, depth) => child(prompt, model, depth),
-    rlmQueryBatched: (prompts, model, depth) => mapPool(prompts, opts.maxConcurrent, (p) => child(p, model, depth)),
-    childRun,
-  };
-}

package/src/mode/input-router.ts

@@ -1,23 +0,0 @@
-import type { InputSource } from "@earendil-works/pi-coding-agent";
-
-export interface InputRouteState {
-  readonly enabled: boolean;
-  readonly busy: boolean;
-}
-
-export interface InputRouteEvent {
-  readonly source: InputSource;
-  readonly text: string;
-}
-
-export type InputRouteDecision = "continue" | "route" | "busy";
-
-export function decideRlmInputRoute(event: InputRouteEvent, state: InputRouteState): InputRouteDecision {
-  const eligible = state.enabled && event.source === "interactive" && !event.text.trimStart().startsWith("/");
-  if (!eligible) return "continue";
-  return state.busy ? "busy" : "route";
-}
-
-export function shouldRouteRlmInput(event: InputRouteEvent, state: InputRouteState): boolean {
-  return decideRlmInputRoute(event, state) === "route";
-}