@hicaru/pi-rlm 0.3.6 → 0.3.9

package/src/core/types.ts

@@ -15,9 +15,10 @@ export interface RlmConfig {
   readonly maxDepth: number;
   /** Max turns before the engine must finalize. */
   readonly maxIterations: number;
-  /** Per-`repl`-block wall-clock timeout inside the worker (seconds). */
+  /** Per-`repl`-block wall-clock timeout inside the worker (seconds).
+   *  v5 doctrine: content limits are the token budget's job — this is a HANG backstop only. */
   readonly execTimeoutS: number;
-  /** Parent-side watchdog per sandbox request (ms). */
+  /** Parent-side watchdog per sandbox request (ms). Hang backstop (see execTimeoutS). */
   readonly requestTimeoutMs: number;
   /** Concurrency pool for *_batched sub-calls. */
   readonly maxConcurrentSubcalls: number;
@@ -28,7 +29,10 @@ export interface RlmConfig {
   readonly maxPromptChars: number;
   /** Max wall-clock ms across the whole tree before the engine stops (undefined = no cap). */
   readonly maxTimeoutMs?: number;
-  /** Max total input+output tokens across the whole tree before the engine stops (undefined = no cap). */
+  /** Max total input+output tokens across the whole tree before the engine stops (undefined = no cap).
+ *  ⚠ HARD ABORT (audit H8): when set, exceeding this throws a LimitError mid-run and the run
+ *  ends with its best partial — NO wrap-up, NO continuation. The graceful path is the v5
+ *  token budget (`enableTokenBudget`); leave this unset unless a hard tree-wide stop is wanted. */
   readonly maxTokens?: number;
   /** Max consecutive error turns before the engine stops (undefined = no cap). */
   readonly maxErrors?: number;
@@ -61,6 +65,37 @@ export interface RlmConfig {
   readonly subSystemPrompt?: string;
   /** Sampling for sub-LLM (worker) calls. */
   readonly subSampling: Readonly<Sampling>;
+  /** v5 token budget: cap = budgetShare × contextWindow, clamped by budgetTaskCap. When on,
+   *  the budget is the PRIMARY run-length control (soft wrap-up → continuation chain). */
+  readonly enableTokenBudget: boolean;
+  /** Fraction of the model's context window that forms one run's token cap. */
+  readonly budgetShare: number;
+  /** Soft wrap-up fires at this fraction of the cap (one wrap-up turn). */
+  readonly budgetSoftFrac: number;
+  /** Absolute single-run ceiling; 0 = no clamp beyond the share. */
+  readonly budgetTaskCap: number;
+  /** Max continuation runs after a hard stop (chain ≤ 1 + this). */
+  readonly budgetMaxContinuations: number;
+  /** Char budget for the deterministic continuation handoff. */
+  readonly budgetHandoffChars: number;
+  /** v5 TaskLedger blackboard: claim coalescing + ancestor-echo reject + `[ledger]` injection. */
+  readonly enableLedger: boolean;
+  /** Real rlm spawns allowed before extra rlm_query demotes to llm_query (0 = never). */
+  readonly rlmBudget: number;
+  /** v5 durable memory: L1 episode replay + L2 BM25 notes under `<root>/.rlm/memory`. */
+  readonly enableMemory: boolean;
+  /** Char budget for the `[memory]` injection = tokens × 4. */
+  readonly injectNoteTokens: number;
+  /** Pending episodes per L2 consolidation batch (0 = never auto-consolidate). */
+  readonly evolveEvery: number;
+  /** Override the memory dir. `null` (default) = `<root>/.rlm/memory` — this field only
+ *  RELOCATES the store; the on/off switch is `enableMemory` (audit M3). */
+  readonly memoryDir: string | null;
+  /** v5: per-provider concurrent-request caps (e.g. `{ zai: 4 }`). Caps only lower limits. */
+  readonly providerMaxConcurrent?: Readonly<Record<string, number>>;
+  /** v5 doctrine: "delegation" = child engines get llm/memory/ledger only (no repo retrieval);
+   *  "legacy" keeps today's full child surface as a one-flip rollback. */
+  readonly childSurface: "delegation" | "legacy";
 }
 
 /** Input to a (headless) RLM run. */
@@ -75,6 +110,12 @@ export interface RlmInput {
   readonly parentNodeId?: string;
   /** Remaining timeout for this subtree (set by parent from its LimitGuard). */
   readonly remainingTimeoutMs?: number;
+  /** v5: budget for this run. Set only by the engine itself when chaining a continuation —
+   *  a fresh budget is resolved from config when omitted. */
+  readonly budget?: import("./budget.ts").TokenBudget;
+  /** v5: the shared TaskLedger blackboard. Children inherit the parent's instance —
+   *  set by childRun (the one child-RlmInput construction path); a fresh run gets a new one. */
+  readonly ledger?: import("./ledger.ts").TaskLedger;
 }
 
 /** Result of a completed RLM run. */

package/src/index.ts

@@ -4,6 +4,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Markdown } from "@earendil-works/pi-tui";
 import { registerRlmCommand } from "./commands/rlm.ts";
 import { registerRlmConfigCommand } from "./commands/rlm-config.ts";
+import { registerRlmLlmCommand } from "./commands/rlm-llm.ts";
+import { registerRlmRlmCommand } from "./commands/rlm-rlm.ts";
+import type { RlmConfig } from "./core/types.ts";
 import { createRlmTool } from "./tool/rlm-tool.ts";
 import { createReplTool } from "./tool/repl-tool.ts";
 import { loadSettings, mergeConfig, resolveModelId } from "./config/settings.ts";
@@ -11,10 +14,15 @@ import { RlmController } from "./mode/rlm-mode.ts";
 import { cheapestModel } from "./mode/llm-model.ts";
 import { postRlmGuide } from "./ui/intro.ts";
 import { setRlmModeStatus } from "./ui/status.ts";
+import { RunRegistry } from "./ui/panel/run-registry.ts";
+import { installTreePanel } from "./ui/panel/tree-panel.ts";
 import { markdownTheme } from "./ui/theme-adapter.ts";
+import { SANDBOX_WATCHDOG_HEARTBEAT_MS } from "./sandbox/sandbox.ts";
 import { SandboxManager } from "./sandbox/sandbox-manager.ts";
-import { createSubcallGates } from "./util/concurrency.ts";
+import { buildSessionGates, type SubcallGates } from "./util/concurrency.ts";
 import { BackgroundTasks } from "./tool/background-tasks.ts";
+import { MemoryStore } from "./core/memory.ts";
+import { modelComplete } from "./bridge/model.ts";
 import { resolve } from "node:path";
 import { resolveSource } from "./context/resolve.ts";
 import { formatContextListing } from "./context/listing.ts";
@@ -38,8 +46,6 @@ export {
   processRlmDepth,
 } from "./mode/subagent.ts";
 
-/** How often to keep the parent sandbox's request watchdog alive during detached work. */
-const WATCHDOG_HEARTBEAT_MS = 30_000;
 /** Soft token guard — cap bulk tool stdout; do NOT hard-block read/grep/bash readers. */
 const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls", "read", "grep"]));
 
@@ -62,7 +68,21 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
   const config = mergeConfig({});
-  const controller = new RlmController(config);
+  // v5 durable memory: one store per session under <cwd>/.rlm/memory (L1 replay + L2 notes).
+  // NOTE (audit M4): this store IS shared by both composition roots, but the TaskLedger is
+  // NOT — the native repl() session and each headless rlm run each keep their own blackboard
+  // (v5 parity: per-run ledger). Claims/coalescing reset at that boundary, by design.
+  // The consolidation LLM + real workspace root are attached in session_start (setLlm/setRoot).
+  const memory = new MemoryStore(
+    process.cwd(),
+    {
+      dir: config.memoryDir ?? undefined,
+      injectNoteTokens: config.injectNoteTokens,
+      evolveEvery: config.evolveEvery,
+    },
+    config.enableMemory,
+  );
+  const controller = new RlmController(config, memory);
   let onSandboxDiscardExtra: (() => void) | undefined;
   const sandboxManager = new SandboxManager({
     execTimeoutS: config.execTimeoutS,
@@ -75,20 +95,32 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     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, config.maxConcurrentChildren);
+  // v5: sub-call admission is built per session (see session_start) so provider concurrency
+  // caps resolve against the models actually in use.
   const background = new BackgroundTasks({
     maxTimeoutMs: config.maxTimeoutMs,
     maxTokens: config.maxTokens,
     maxErrors: config.maxErrors,
   });
+  // Session tree panel: every repl cell / rlm run / detached bg task registers here;
+  // the below-editor widget + agent modal read from it. Background is persistent
+  // and hides itself while idle.
+  const runRegistry = new RunRegistry();
+  runRegistry.register({
+    runId: "background",
+    label: "background tasks",
+    emitter: background.emitter,
+    subcalls: () => background.liveSubcalls(),
+    totals: () => background.liveTotals(),
+    hideWhenEmpty: true,
+  });
+  let treePanelInstalled = false;
   // 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);
+  }, SANDBOX_WATCHDOG_HEARTBEAT_MS);
   watchdogHeartbeat.unref();
 
   /** Memoised cwd seed — one resolveSource(pathPrefix:"") per session. */
@@ -146,9 +178,11 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // ── Commands ──
   registerRlmCommand(pi, controller);
   registerRlmConfigCommand(pi, controller);
+  registerRlmLlmCommand(pi, controller);
+  registerRlmRlmCommand(pi, controller);
 
   // ── Tool registration ──
-  pi.registerTool(createRlmTool(controller));
+  pi.registerTool(createRlmTool(controller, runRegistry));
   let guidePosted = false;
 
   pi.on("session_start", async (_event, ctx) => {
@@ -157,6 +191,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const persisted = await loadSettings();
     controller.config = mergeConfig(persisted.config);
     controller.savedLlmRef = persisted.llm ?? undefined;
+    controller.savedRlmRef = persisted.rlm ?? undefined;
 
     // An explicit --rlm flag wins over the persisted setting for this session.
     const flag = pi.getFlag("rlm");
@@ -173,6 +208,25 @@ export default function rlmExtension(pi: ExtensionAPI): void {
       console.warn(`[rlm] model registry refresh failed: ${errorMessage(err)}`);
     }
 
+    if (controller.savedRlmRef) {
+      const resolvedRlm = resolveModelId(ctx.modelRegistry, controller.savedRlmRef);
+      if (resolvedRlm) {
+        controller.rlmModel = resolvedRlm;
+      } else {
+        console.warn(
+          `[rlm] pinned rlm model ${controller.savedRlmRef} not in registry; following session model until it reappears`,
+        );
+        try {
+          ctx.ui.notify(
+            `RLM: pinned rlm=${controller.savedRlmRef} unavailable — following session model until it is`,
+            "warning",
+          );
+        } catch {
+          // Some hosts have no UI at session_start.
+        }
+      }
+    }
+
     if (controller.savedLlmRef) {
       const resolved = resolveModelId(ctx.modelRegistry, controller.savedLlmRef);
       if (resolved) {
@@ -198,6 +252,40 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const llmModel = controller.llmModel ?? cheapestModel(ctx.modelRegistry) ?? ctx.model;
     const model = ctx.model;
     if (llmModel && model) {
+      // Consolidation runs on the cheap worker model through the single completion entry point;
+      // the workspace root is only known once the session starts.
+      const consolidateModel = llmModel;
+      memory.setLlm((prompt) =>
+        modelComplete([{ role: "user", content: prompt }], { model: consolidateModel, registry: ctx.modelRegistry })
+          .then((r) => r.text));
+      memory.setRoot(ctx.cwd ?? process.cwd());
+      // v5 provider caps (audit C1/C6): ONE resolver shared by both composition roots — the
+      // repl() tool and RlmController.start admit through the same pool, each gate capped
+      // against the model that actually runs on it (leaves = worker, children = smart).
+      // Memoized on (config, providers) so /rlm-config changes apply without a restart.
+      let gatesMemo:
+        | { readonly config: RlmConfig; readonly smart: string; readonly worker: string; readonly gates: SubcallGates }
+        | undefined;
+      const resolveSessionGates = (): SubcallGates => {
+        const smart = model;
+        const worker = controller.llmModel ?? cheapestModel(ctx.modelRegistry) ?? model;
+        const workerProvider = worker.provider;
+        if (
+          gatesMemo === undefined ||
+          gatesMemo.config !== controller.config ||
+          gatesMemo.smart !== smart.provider ||
+          gatesMemo.worker !== workerProvider
+        ) {
+          gatesMemo = {
+            config: controller.config,
+            smart: smart.provider,
+            worker: workerProvider,
+            gates: buildSessionGates(controller.config, smart.provider, workerProvider),
+          };
+        }
+        return gatesMemo.gates;
+      };
+      controller.setSessionGates(resolveSessionGates);
       try {
         pi.registerTool(createReplTool({
           sandboxManager,
@@ -207,8 +295,11 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           getLlmModel: () => controller.resolveModels(ctx)?.llm,
           registry: ctx.modelRegistry,
           getConfig: () => controller.config,
-          gates,
+          gates: resolveSessionGates(),
+          resolveGates: resolveSessionGates,
           background,
+          runRegistry,
+          memory,
           registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
           registerContextBundle: (bundle) => {
             contextBundleRef = bundle;
@@ -231,7 +322,11 @@ export default function rlmExtension(pi: ExtensionAPI): void {
       }
     }
 
-    setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
+    setRlmModeStatus(ctx, controller, ctx.getContextUsage());
+    if (!treePanelInstalled) {
+      treePanelInstalled = true;
+      installTreePanel(ctx, runRegistry);
+    }
     if (!guidePosted && controller.enabled) {
       guidePosted = true;
       postRlmGuide(pi, controller);
@@ -240,7 +335,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
   // ── Keep the footer's context reading live (RLM exists to shrink this number) ──
   pi.on("turn_end", async (_event, ctx) => {
-    setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
+    setRlmModeStatus(ctx, controller, ctx.getContextUsage());
   });
 
   /** True when the native-mode trade holds: enabled AND repl is in the active tool set. */

package/src/mode/rlm-mode.ts

@@ -9,13 +9,16 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { modelRef, resolveModelId, saveSettings } from "../config/settings.ts";
-import { createEngine } from "../core/engine.ts";
+import { createEngine, type EngineDeps } from "../core/engine.ts";
 import { limitsFromConfig } from "../core/limits.ts";
 import type { RlmConfig, RlmResult } from "../core/types.ts";
 import { resolveSource } from "../context/resolve.ts";
 import { RlmEmitter } from "../tool/rlm-events.ts";
 import { formatError } from "../util/errors.ts";
 import { cheapestModel } from "./llm-model.ts";
+import type { MemoryStore } from "../core/memory.ts";
+import type { RunRlm } from "../core/types.ts";
+import type { SubcallGates } from "../util/concurrency.ts";
 
 export interface RunHandle {
   readonly abort: () => void;
@@ -32,9 +35,25 @@ export class RlmController {
   savedLlmRef: string | undefined;
   /** Set by applyLlmSelection when the user explicitly picks "cheapest (auto)". */
   explicitClearPin = false;
+  /** Pinned rlm root/worker model — when unset, child engines follow pi's session model. */
+  rlmModel: Model<Api> | undefined;
+  savedRlmRef: string | undefined;
+  /** Set by applyRlmSelection when the user explicitly picks "(follow session model)". */
+  explicitClearRlmPin = false;
   private active: AbortController | null = null;
-
-  constructor(public config: RlmConfig) {}
+  /** v5: session admission gates (provider-capped), shared with the repl() tool — set at
+   *  session_start so BOTH composition roots admit through one pool (audit C1). */
+  private sessionGates: (() => SubcallGates) | undefined;
+
+  constructor(
+    public config: RlmConfig,
+    /** v5 durable memory — shared with the repl tool so child runs replay/persist too. */
+    public readonly memory?: MemoryStore,
+  ) {}
+
+  setSessionGates(getGates: () => SubcallGates): void {
+    this.sessionGates = getGates;
+  }
 
   get enabled(): boolean {
     return this.config.enabled;
@@ -64,6 +83,9 @@ export class RlmController {
       llm: this.explicitClearPin
         ? null
         : (modelRef(this.llmModel) ?? this.savedLlmRef),
+      rlm: this.explicitClearRlmPin
+        ? null
+        : (modelRef(this.rlmModel) ?? this.savedRlmRef),
     });
   }
 
@@ -77,12 +99,41 @@ export class RlmController {
 
   resolveModels(ctx: ExtensionContext): { model: Model<Api>; llm: Model<Api> } | undefined {
     if (!this.llmModel && this.savedLlmRef) this.llmModel = resolveModelId(ctx.modelRegistry, this.savedLlmRef);
-    const model = ctx.model ?? cheapestModel(ctx.modelRegistry);
+    if (!this.rlmModel && this.savedRlmRef) this.rlmModel = resolveModelId(ctx.modelRegistry, this.savedRlmRef);
+    // The rlm pin wins over the session model; unset → follow pi's active model.
+    const model = this.rlmModel ?? ctx.model ?? cheapestModel(ctx.modelRegistry);
     if (!model) return undefined;
     const llm = this.llmModel ?? cheapestModel(ctx.modelRegistry) ?? model;
     return { model, llm };
   }
 
+  /** Test seam (audit R7): intercept the exact object `createEngine` receives. */
+  protected spawnEngine(deps: EngineDeps): RunRlm {
+    return createEngine(deps);
+  }
+
+  /** The ONE engine construction path for this controller (DRY #6 — a second path that
+   *  forgets to grow is exactly how issue #4 and audit C1 happened). Protected so tests can
+   *  subclass and assert the wiring without touching the network. */
+  protected buildEngine(args: {
+    readonly ctx: ExtensionContext;
+    readonly models: { readonly model: Model<Api>; readonly llm: Model<Api> };
+    readonly signal: AbortSignal;
+    readonly emitter: RlmEmitter;
+  }): RunRlm {
+    return this.spawnEngine({
+      model: args.models.model,
+      llmModel: args.models.llm,
+      registry: args.ctx.modelRegistry,
+      config: this.config,
+      signal: args.signal,
+      emitter: args.emitter,
+      limits: limitsFromConfig(this.config),
+      memory: this.memory,
+      gates: this.sessionGates?.(),
+    });
+  }
+
   start(ctx: ExtensionContext, input: StartInput, emitter?: RlmEmitter): RunHandle {
     const models = this.resolveModels(ctx);
     if (!models) throw new Error("no model with configured auth is available");
@@ -102,14 +153,11 @@ export class RlmController {
           ? result.value.payload
           : formatError(`failed to pack repository — ${result.error}`);
       }
-      const engine = createEngine({
-        model: models.model,
-        llmModel: models.llm,
-        registry: ctx.modelRegistry,
-        config: this.config,
+      const engine = this.buildEngine({
+        ctx,
+        models,
         signal: abortController.signal,
         emitter: emitter ?? new RlmEmitter(),
-        limits: limitsFromConfig(this.config),
       });
       return await engine({ rootPrompt: input.rootPrompt, context: contextValue, depth: 0 });
     })().finally(() => {