@hicaru/pi-rlm 0.3.5 → 0.3.8

package/src/sandbox/sandbox.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from "node:url";
 import {
   isInterrupt,
   isWorkerMessage,
+  parsePendingTasks,
   type ParentMessage,
   type ReplResult,
   type WorkerMessage,
@@ -29,6 +30,9 @@ export type { AddContextResult, SubcallOpts, SubLlmHandlers } from "./interrupts
 export interface SandboxOptions {
   /** Sandbox recursion depth label (passed to the worker, used in interrupt routing). */
   readonly depth?: number;
+  /** v5 role separation: "child" sandboxes install the delegation-only scaffold (no
+   *  search/grep_context/outline/add_context — retrieval belongs to the root). */
+  readonly surface?: "root" | "child";
   /** Per-`repl`-block wall-clock timeout inside the worker (seconds). */
   readonly execTimeoutS?: number;
   /** Parent-side watchdog per request (ms); on breach the worker is SIGKILLed. */
@@ -52,6 +56,8 @@ export interface SandboxOptions {
 
 const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), "py", "worker.py");
 const STDERR_TAIL_CHARS = 8_192;
+/** How often to refresh the parent request watchdog (and ping the worker) during silent host work. */
+export const SANDBOX_WATCHDOG_HEARTBEAT_MS = 30_000;
 /** How long dispose() waits for a clean worker exit before escalating to SIGKILL. */
 const SHUTDOWN_GRACE_MS = 50;
 
@@ -118,6 +124,7 @@ export class PythonSandbox {
       "-X", "utf8=1",
       "-u", WORKER_PATH,
       "--depth", String(opts.depth ?? 1),
+      "--surface", opts.surface === "child" ? "child" : "root",
       "--timeout", String(opts.execTimeoutS ?? 600),
     ];
     if (opts.maxPromptChars !== undefined) {
@@ -224,6 +231,7 @@ export class PythonSandbox {
       raised: res.raised ?? false,
       executionTimeMs: Math.round((res.execution_time ?? 0) * 1000),
       varNames: res.var_names ?? [],
+      pendingTasks: parsePendingTasks(res.pending_tasks),
     };
   }
 
@@ -312,12 +320,22 @@ export class PythonSandbox {
   }
 
   /**
-   * Refresh the parent-side request watchdog for every pending request.
-   * Used during long mid-exec work that does not
-   * produce additional worker interrupts on this sandbox.
+   * Refresh the parent-side request watchdog and ping the worker.
+   * Used during long mid-exec work that does not produce additional worker
+   * interrupts on this sandbox. The heartbeat rearms the worker's stall alarm
+   * so a healthy long sub-call is not reported as `_StallTimeout`.
    */
   refreshWatchdog(): void {
     this.touchPending();
+    if (this.hasPendingRequest()) this.send({ type: "heartbeat" });
+  }
+
+  /** True when an exec/load_context/shutdown (not the init handshake) is in flight. */
+  private hasPendingRequest(): boolean {
+    for (const id of this.pending.keys()) {
+      if (id !== "_init") return true;
+    }
+    return false;
   }
 
   private send(msg: ParentMessage): void {

package/src/text/repl-output.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared REPL output formatting used by headless history and native repl() tool results.
+ * Lives in text/ so tool/ does not import from core/.
+ */
+
+import { truncateOutput } from "./parsing.ts";
+
+/** Max stderr kept in model-visible REPL output (headless history and native tool_result). */
+export const STDERR_LIMIT = 8_000;
+
+/** Prefix stderr so the model can tell prints from exceptions. Empty when stderr is blank. */
+export function formatReplStderr(stderr: string, limit = STDERR_LIMIT): string {
+  const err = stderr.trim();
+  return err ? `\n[stderr]\n${truncateOutput(err, limit)}` : "";
+}

package/src/tool/repl-result.ts

@@ -5,7 +5,9 @@
  */
 
 import type { RlmSubcall } from "./rlm-details.ts";
+import type { PendingTaskInfo } from "../sandbox/protocol.ts";
 import { capReplResultText, replDelegationNudge } from "../mode/native-guards.ts";
+import { formatReplStderr } from "../text/repl-output.ts";
 
 /** Model-visible text assembled from a repl() result. */
 export interface ReplResultText {
@@ -30,23 +32,20 @@ export function buildReplResultText(
   subcalls: readonly RlmSubcall[],
   backgroundPending = 0,
   varNames: readonly string[] = [],
+  stderr = "",
+  raised = false,
+  pendingTasks: readonly PendingTaskInfo[] = [],
 ): ReplResultText {
   const answerSubmitted = finalAnswer !== undefined;
-  const noOutput = !answerSubmitted && !stdout;
-  const varsHint = noOutput && varNames.length > 0
-    ? ` — the block ran fine and these REPL vars are defined: ${varNames.join(", ")}. `
-      + "Do NOT re-run it; read them in the next block."
-    : "";
-  const rawText = answerSubmitted
-    ? `ANSWER_SUBMITTED (${finalAnswer.length} chars) — delivered to user. Do not restate it.`
-    : stdout || `(no output)${varsHint}`;
+  const stderrBlock = formatReplStderr(stderr);
+  const rawText = assembleReplBody(stdout, finalAnswer, varNames, stderrBlock, raised);
   // Model-visible text is capped; the caller keeps full stdout in `details` for the TUI.
   const cappedText = capReplResultText(rawText) ?? rawText;
   const delegated = subcalls.some((s) => s.kind === "llm" || s.kind === "batch" || s.kind === "rlm");
-  const nudge = answerSubmitted ? undefined : replDelegationNudge(rawText.length, delegated);
+  const nudge = answerSubmitted || raised ? undefined : replDelegationNudge(rawText.length, delegated);
   const failedBg = subcalls.filter((s) => s.id.startsWith("bg") && s.status === "error").length;
   const pendingLine = backgroundPending > 0
-    ? `\n\n[rlm] ${backgroundPending} background task(s) still running — await_task(tasks) to collect.`
+    ? `\n\n[rlm] ${backgroundPending} background task(s) still running — ${pendingCollectHint(pendingTasks)}.`
     : "";
   const failedLine = failedBg > 0
     ? `\n[rlm] ${failedBg} background sub-call(s) FAILED — their await_task value is an "Error: …" string, not data.`
@@ -54,6 +53,51 @@ export function buildReplResultText(
   return { text: cappedText + (nudge ?? "") + pendingLine + failedLine };
 }
 
+function assembleReplBody(
+  stdout: string,
+  finalAnswer: string | undefined,
+  varNames: readonly string[],
+  stderrBlock: string,
+  raised: boolean,
+): string {
+  if (finalAnswer !== undefined) {
+    return `ANSWER_SUBMITTED (${finalAnswer.length} chars) — delivered to user. Do not restate it.`;
+  }
+  if (raised) {
+    const body = [stdout.trimEnd(), stderrBlock.trimStart()].filter((s) => s.length > 0).join("\n");
+    return body.length > 0 ? body : "(raised — see [stderr])";
+  }
+  const noOutput = !stdout;
+  const varsHint = noOutput && varNames.length > 0
+    ? ` — the block ran fine and these REPL vars are defined: ${varNames.join(", ")}. `
+      + "Do NOT re-run it; read them in the next block."
+    : "";
+  return stdout || `(no output)${varsHint}`;
+}
+
+/** Name the Python handle when we know it; otherwise point at await_task() / list_tasks(). */
+function pendingCollectHint(pendingTasks: readonly PendingTaskInfo[]): string {
+  if (pendingTasks.length === 0) {
+    return "collect with await_task(<Task var>) or await_task(); answers[] is for results AFTER await_task";
+  }
+  const names = new Array<string>(pendingTasks.length);
+  for (let i = 0; i < pendingTasks.length; i++) {
+    const t = pendingTasks[i];
+    const kind = t?.kind ?? "task";
+    const label = t?.label ?? "";
+    names[i] = t?.var ?? `<${kind}${label.length > 0 ? ` ${label}` : ""}>`;
+  }
+  if (pendingTasks.length === 1) {
+    const only = names[0] ?? "";
+    const first = pendingTasks[0];
+    const detail = first !== undefined && first.label.length > 0 ? ` (${first.kind} ${first.label})` : "";
+    return only.startsWith("<")
+      ? `collect with await_task()${detail}; answers[] is for results AFTER await_task`
+      : `collect with await_task(${only})${detail}; answers[] is for results AFTER await_task`;
+  }
+  return `collect with await_task()  (${names.join(", ")}); answers[] is for results AFTER await_task`;
+}
+
 /** Advisory diagnostics derived from a completed invocation's sub-calls. */
 export function collectReplWarnings(subcalls: readonly RlmSubcall[]): readonly string[] | undefined {
   let failed = 0;

package/src/tool/repl-tool.ts

@@ -28,6 +28,8 @@ import type { RlmConfig, RlmInput, RlmResult } from "../core/types.ts";
 import { SandboxManager } from "../sandbox/sandbox-manager.ts";
 import type { SubcallOpts } from "../sandbox/sandbox.ts";
 import { createSubcallHandlers, type Invocation } from "../bridge/handlers/index.ts";
+import { TaskLedger } from "../core/ledger.ts";
+import type { MemoryStore } from "../core/memory.ts";
 import { BackgroundTasks } from "./background-tasks.ts";
 import type { ReplResult } from "../sandbox/protocol.ts";
 import { RlmEmitter } from "./rlm-events.ts";
@@ -110,8 +112,13 @@ export interface ReplToolDeps {
   readonly getConfig: () => RlmConfig;
   /** Session-wide sub-call admission, shared with every child engine this tool spawns. */
   readonly gates: SubcallGates;
+  /** v5: live re-resolution of the session gates (provider caps change via /rlm-config without
+   *  a restart). Falls back to `gates` when omitted. Read lazily per sub-call. */
+  readonly resolveGates?: () => SubcallGates;
   /** Session-scoped home for detached spawn() work. */
   readonly background: BackgroundTasks;
+  /** v5 durable memory (session-wide `.rlm` store); omitted → memory off for this tool. */
+  readonly memory?: MemoryStore;
   readonly signal?: AbortSignal;
   readonly onUsage?: (usage: Usage, role: "sub") => void;
   readonly ensureContext?: () => Promise<void>;
@@ -127,12 +134,17 @@ export interface ReplToolDeps {
 export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplToolParams, ReplDetails> {
   const { sandboxManager, llmModel, registry, getConfig, signal, onUsage, background } = deps;
   const bridgeState = new NativeBridgeState(background);
+  // v5: one session-wide blackboard for the native repl() path — the same claim/coalesce/
+  // demote logic the engine gets per run, shared by every turn and every child it spawns.
+  const sessionLedger = new TaskLedger();
 
   // Late-bound cwd — getOrCreate installs handlers only at spawn; never rebuild the closure.
   let sessionCwd = process.cwd();
 
   const getLlmModel = (): Model<Api> => deps.getLlmModel?.() ?? llmModel;
   const getModel = (): Model<Api> => deps.getModel?.() ?? deps.model;
+  // v5 (audit C6): resolve lazily per call so provider-cap edits via /rlm-config apply live.
+  const currentGates = (): SubcallGates => deps.resolveGates?.() ?? deps.gates;
 
   // Each rlm_query spawns a child RLM with its own sandbox and turn loop, not a flat
   // one-shot llm_query. The engine is created per call so the child's subcalls, turn
@@ -143,7 +155,8 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     registry,
     config: getConfig(),
     signal,
-    gates: deps.gates,
+    memory: deps.memory,
+    gates: currentGates(),
     // Same emitter the parent subcall node lives on — see SubcallHandlerDeps.runChild.
     emitter: inv.emitter,
     // Everything a child engine spends is sub-work from this tool's perspective, including
@@ -156,7 +169,10 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
   // per-invocation is reached through bridgeState.resolve, not captured here.
   const subcallHandlers = createSubcallHandlers({
     resolve: (opts) => bridgeState.resolve(opts),
-    gates: deps.gates,
+    // Getter, not a captured value: sub-call deps read gates lazily per call.
+    get gates(): SubcallGates {
+      return currentGates();
+    },
     registry,
     getLlmModel,
     getModel,
@@ -168,6 +184,8 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     // earlier repl() reaches a child spawned in a later one. Populated before any interrupt can
     // fire: execute() awaits ensureContext() before getOrCreate().
     getChildContext: () => sandboxManager.contextPayload ?? undefined,
+    ledger: sessionLedger,
+    memory: deps.memory,
     trackDetached: (task) => background.track(task),
   });
 
@@ -213,7 +231,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
       "repl: free search/outline; fire rlm_batch|map_files|llm_batch as Task (BG); await_task for results.",
     promptGuidelines: [
       "Multi-area analysis: rlm_batch([...]) or map_files(paths, q); free search; await_task — not serial native read.",
-      "Always-spawn tools return Task; only await_task has content. Fire-all independent work before await.",
+      "Always-spawn tools return Task; only await_task has content. Fire-all then await; await_task() collects every still-running Task.",
       "llm_query/llm_batch have no disk — never 'Read path/to/file.ts'; use map_files or rlm_* (see context).",
     ],
     parameters: ReplToolParams,
@@ -283,6 +301,8 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         await sandboxManager.getOrCreate({
           ...subcallHandlers,
           ...(contextBundle?.handlers ?? {}),
+          ledgerClaims: () => Promise.resolve(sessionLedger.listClaims()),
+          memoryOp: (op, args) => Promise.resolve(deps.memory?.serviceOp(op, args) ?? "memory off"),
         });
 
         // Detect queue contention AFTER sandbox init (initPromise settled, isExecuting now accurate)
@@ -299,12 +319,23 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         }
 
         const start = Date.now();
-        const result: ReplResult = await sandboxManager.execWithSetup(params.code, () => {
-          // Wire per-invocation mutable state only after the serialized exec slot
-          // is active. Swapping earlier would let queued repl() calls overwrite
-          // emitter/limits for the currently running REPL execution.
-          bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits });
-        }, execSignal);
+        // v5 blackboard (audit C3 / R1): ancestors are the rlm_query/rlm_batch task
+        // strings inside this cell, not the Python soup (`print`, `await_task`). A
+        // child restating the user's goal then echoes. Popped in finally: detached
+        // work spawned by this cell already claimed at spawn time, inside this window.
+        const ledgerActive = getConfig().enableLedger;
+        const ancestorN = ledgerActive ? sessionLedger.beginNativeCell(params.code) : 0;
+        let result: ReplResult;
+        try {
+          result = await sandboxManager.execWithSetup(params.code, () => {
+            // Wire per-invocation mutable state only after the serialized exec slot
+            // is active. Swapping earlier would let queued repl() calls overwrite
+            // emitter/limits for the currently running REPL execution.
+            bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits });
+          }, execSignal);
+        } finally {
+          if (ledgerActive) sessionLedger.endNativeCell(ancestorN);
+        }
         const elapsed = Date.now() - start;
         capturedStdout = result.stdout;
         capturedStderr = result.stderr;
@@ -349,6 +380,9 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
           subcalls,
           background.pending,
           result.varNames,
+          result.stderr,
+          result.raised,
+          result.pendingTasks,
         );
 
         const details: ReplDetails = {

package/src/ui/status.ts

@@ -17,7 +17,10 @@ export function formatRlmStateLine(controller: RlmController, contextUsage?: Con
   // `percent` is null right after a compaction, before the next assistant response reports usage.
   const percent = contextUsage?.percent;
   const ctxSuffix = percent === null || percent === undefined ? "" : ` · ctx ${Math.round(percent)}%`;
-  return `● RLM ON · llm=${llm}${llmSuffix}${ctxSuffix}`;
+  // v5 provider caps (set via rlm.json): keep the effective admission visible.
+  const caps = controller.config.providerMaxConcurrent;
+  const capsSuffix = caps === undefined ? "" : ` · caps ${Object.entries(caps).map(([p, n]) => `${p}=${n}`).join(",")}`;
+  return `● RLM ON · llm=${llm}${llmSuffix}${ctxSuffix}${capsSuffix}`;
 }
 
 export function setRlmModeStatus(ui: ExtensionUIContext, controller: RlmController, contextUsage?: ContextUsage): void {

package/src/util/concurrency.ts

@@ -91,3 +91,50 @@ export interface SubcallGates {
 export function createSubcallGates(leafLimit: number, childLimit: number = leafLimit): SubcallGates {
   return Object.freeze({ leaf: new Semaphore(leafLimit), rlm: new DepthGates(childLimit) });
 }
+
+/** Provider-capped config slice (RlmConfig satisfies this structurally). */
+export interface ProviderCapConfig {
+  readonly maxConcurrentSubcalls: number;
+  readonly maxConcurrentChildren: number;
+  /** v5: per-provider concurrent-request caps, e.g. { zai: 4 }. Caps only ever LOWER a limit. */
+  readonly providerMaxConcurrent?: Readonly<Record<string, number>>;
+}
+
+/** min(maxConcurrentSubcalls, every involved provider's cap) — unknown providers are ignored. */
+export function effectiveSubcallLimit(
+  config: ProviderCapConfig,
+  providersInUse: readonly string[],
+): number {
+  let limit = config.maxConcurrentSubcalls;
+  for (const p of providersInUse) {
+    const cap = config.providerMaxConcurrent?.[p];
+    if (cap !== undefined && cap > 0) limit = Math.min(limit, cap);
+  }
+  return limit;
+}
+
+/** Child engines are the heavy unit — cap them against their own model's provider. */
+export function effectiveChildLimit(
+  config: ProviderCapConfig,
+  childModelProvider: string,
+): number {
+  const cap = config.providerMaxConcurrent?.[childModelProvider];
+  return cap !== undefined && cap > 0
+    ? Math.min(config.maxConcurrentChildren, cap)
+    : config.maxConcurrentChildren;
+}
+
+/** v5 session gates, capping the RIGHT model per gate (audit C6): leaf completions run on the
+ *  WORKER model, recursive child engines run on the SMART model — a shared-pool fold of both
+ *  providers would clamp the wrong side (zai smart + openai worker must cap children, not leaves).
+ *  Pure + testable; the composition roots memoize it keyed on (config, providers). */
+export function buildSessionGates(
+  config: ProviderCapConfig,
+  smartProvider: string,
+  workerProvider: string,
+): SubcallGates {
+  return createSubcallGates(
+    effectiveSubcallLimit(config, [workerProvider]),
+    effectiveChildLimit(config, smartProvider),
+  );
+}