@hicaru/pi-rlm 0.3.16 → 0.3.18

package/src/context/source-dir.ts

@@ -29,7 +29,7 @@ import { applyPathPrefix, contextSourceId, pathPrefixFor } from "./namespace.ts"
 /** Conversions are libuv-threadpool bound (default pool 4); 8 keeps the pool busy without thrash. */
 const CONVERT_CONCURRENCY = 8;
 
-export interface PackDirResult {
+interface PackDirResult {
   readonly files: readonly ContextFile[];
   readonly chars: number;
   readonly documents: number;
@@ -37,6 +37,25 @@ export interface PackDirResult {
   readonly skipped: readonly SkippedFile[];
 }
 
+/** DRY: the ONE PackDirResult → SourceResult flattening — shared by the local-dir source and
+ *  the git-clone source (which wraps it in Result). Never inline a second copy. */
+export function packToSourceResult(
+  packed: PackDirResult,
+  sourceId: string,
+  pathPrefix: string,
+): SourceResult {
+  return Object.freeze({
+    payload: packed.files,
+    files: packed.files.length,
+    chars: packed.chars,
+    sourceId,
+    pathPrefix,
+    documents: packed.documents,
+    converted: packed.converted,
+    skipped: packed.skipped,
+  });
+}
+
 /**
  * Walk `dir` and produce ContextFiles. Resolves the anydoc handle once per source
  * (not per file) and threads it into the per-file router.
@@ -153,14 +172,5 @@ export async function sourceDir(
   // Explicit pathPrefix (including "") wins; otherwise derive ctx/<id>/.
   const pathPrefix = opts.pathPrefix !== undefined ? opts.pathPrefix : pathPrefixFor(sourceId);
   const packed = await packDirectory(dir, pathPrefix, opts.signal);
-  return Object.freeze({
-    payload: packed.files,
-    files: packed.files.length,
-    chars: packed.chars,
-    sourceId,
-    pathPrefix,
-    documents: packed.documents,
-    converted: packed.converted,
-    skipped: packed.skipped,
-  });
+  return packToSourceResult(packed, sourceId, pathPrefix);
 }

package/src/context/source-doc.ts

@@ -16,7 +16,7 @@ import {
   type SkippedFile,
 } from "./types.ts";
 
-export type DocFileResult =
+type DocFileResult =
   | { readonly ok: true; readonly value: ContextFile; /** true only for a real anydoc conversion */ readonly converted: boolean }
   | { readonly ok: false; readonly skipped: SkippedFile };
 

package/src/context/source-git.ts

@@ -2,18 +2,15 @@
  * Shallow-clone a git URL, then pack with source-dir.
  */
 
-import { execFile } from "node:child_process";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { promisify } from "node:util";
 import { errorMessage, type Result } from "../util/errors.ts";
+import { execFileP } from "./walk.ts";
 import { contextSourceId, pathPrefixFor } from "./namespace.ts";
-import { packDirectory } from "./source-dir.ts";
+import { packDirectory, packToSourceResult } from "./source-dir.ts";
 import type { ResolveOpts, SourceResult } from "./types.ts";
 
-const execFileP = promisify(execFile);
-
 /** Shallow-clone `url` into a temp dir, pack, then remove the clone. */
 export async function sourceGit(
   url: string,
@@ -32,16 +29,7 @@ export async function sourceGit(
     const packed = await packDirectory(dir, pathPrefix, opts.signal);
     return {
       ok: true,
-      value: Object.freeze({
-        payload: packed.files,
-        files: packed.files.length,
-        chars: packed.chars,
-        sourceId,
-        pathPrefix,
-        documents: packed.documents,
-        converted: packed.converted,
-        skipped: packed.skipped,
-      }),
+      value: packToSourceResult(packed, sourceId, pathPrefix),
     };
   } catch (err: unknown) {
     return { ok: false, error: `git clone failed for ${url} — ${errorMessage(err)}` };

package/src/context/source-text.ts

@@ -9,7 +9,7 @@ import { applyPathPrefix } from "./namespace.ts";
 import { isBinary } from "./walk.ts";
 import { MAX_WALK_FILE_BYTES, type ContextFile, type SkippedFile } from "./types.ts";
 
-export type TextFileResult =
+type TextFileResult =
   | { readonly ok: true; readonly value: ContextFile }
   | { readonly ok: false; readonly skipped: SkippedFile };
 

package/src/context/walk.ts

@@ -13,12 +13,13 @@
 
 import { execFile } from "node:child_process";
 import type { Dirent } from "node:fs";
-import { lstat, open, readdir, realpath, stat } from "node:fs/promises";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import type { SkipReason } from "./types.ts";
 
-const execFileP = promisify(execFile);
+/** Shared promisified execFile (git listing) — source-git.ts reuses it (DRY). */
+export const execFileP = promisify(execFile);
 
 /** 8KB probe window for the NUL-byte binary check. */
 const BINARY_PROBE_BYTES = 8 * 1024;
@@ -94,7 +95,7 @@ function absKey(path: string): string {
 }
 
 /** True when `fileAbs` is `rootAbs` or a descendant (prefix + separator). */
-export function isInsideRoot(fileAbs: string, rootAbs: string): boolean {
+function isInsideRoot(fileAbs: string, rootAbs: string): boolean {
   const root = absKey(rootAbs);
   const file = absKey(fileAbs);
   if (file === root) return true;
@@ -102,7 +103,7 @@ export function isInsideRoot(fileAbs: string, rootAbs: string): boolean {
   return file.startsWith(prefix);
 }
 
-export type PathSafety =
+type PathSafety =
   | { readonly ok: true; readonly realAbs: string }
   | { readonly ok: false; readonly reason: Extract<SkipReason, "sensitive" | "symlink-escape" | "unreadable"> };
 
@@ -147,7 +148,7 @@ export async function checkPathSafety(absPath: string, packRoot: string): Promis
  * Paths are returned raw from git (forward-slashed). Sensitive paths are NOT filtered here —
  * packDirectory reports them as skipped: "sensitive" so the drop is visible.
  */
-export async function gitFiles(cwd: string, signal?: AbortSignal): Promise<readonly string[] | undefined> {
+async function gitFiles(cwd: string, signal?: AbortSignal): Promise<readonly string[] | undefined> {
   try {
     const { stdout } = await execFileP(
       "git",
@@ -239,12 +240,3 @@ export async function enumerateFiles(root: string, signal?: AbortSignal): Promis
   return await walkFs(root, signal);
 }
 
-/** True when a path exists and is a regular file (or symlink to one). */
-export async function isRegularFile(absPath: string): Promise<boolean> {
-  try {
-    const s = await stat(absPath);
-    return s.isFile();
-  } catch {
-    return false;
-  }
-}

package/src/core/budget.ts

@@ -14,28 +14,29 @@
 
 import type { ChatMsg } from "../bridge/model.ts";
 import type { RlmConfig } from "./types.ts";
+import type { RunState } from "./run-state.ts";
+import { compactJSON } from "./run-state.ts";
 
-export interface TokenBudgetOptions {
+interface TokenBudgetOptions {
   readonly softFrac?: number;
   readonly continuations?: number;
   readonly maxContinuations?: number;
 }
 
-export type BudgetState = "" | "soft" | "hard";
+type BudgetState = "" | "soft" | "hard";
 
 /** v5 verbatim: the soft wrap-up note prepended to the single turn after crossing soft. */
-export const WRAP_UP_BUDGET: string = Object.freeze(
+export const WRAP_UP_BUDGET: string =
   "[budget] ~80% of your token cap — ONE turn left. If the task is answerable NOW, finalize " +
     '(set answer["ready"] = True). Otherwise print a compact findings dump: what is confirmed, ' +
     "current file/line or search position, and the exact next step — a fresh continuation picks " +
-    "it up. Do not start new exploration.",
-);
+    "it up. Do not start new exploration.";
 
 export const DEFAULT_NEXT_STEP: string =
-  Object.freeze("continue the probing that was in flight, then finalize");
+  "continue the probing that was in flight, then finalize";
 
 /** v5 verbatim template (adapting the finalize spelling to this plugin's REPL). */
-const HANDOFF_TEMPLATE: string = Object.freeze(
+const HANDOFF_TEMPLATE: string =
   "A prior RLM run hit its token cap mid-task.\n" +
     "You are its continuation — pick up EXACTLY where it stopped.\n\n" +
     "ORIGINAL TASK:\n{query}\n\n" +
@@ -43,8 +44,7 @@ const HANDOFF_TEMPLATE: string = Object.freeze(
     "CURRENT STATE / LAST ACTIONS:\n{state}\n\n" +
     "NEXT STEP: {next}\n" +
     "Do not re-do confirmed work; continue from the NEXT STEP and finalize as\n" +
-    'soon as the task is answerable (answer["ready"] = True).',
-);
+    'soon as the task is answerable (answer["ready"] = True).';
 
 /** v5's elision marker, used whenever a handoff section is trimmed. */
 const ELISION_MARK = "\n…(+N chars elided [v5 handoff])…\n";
@@ -119,24 +119,26 @@ export class TokenBudget {
  */
 export const BUDGET_WINDOW_FLOOR = 250_000;
 
-/** An effective budget that can never trigger — the cascade "switched off" without changing
- *  any call-site types (budget: TokenBudget | undefined). */
-function unboundedBudget(config: RlmConfig): TokenBudget {
-  return new TokenBudget(Number.MAX_SAFE_INTEGER, {
+/** One TokenBudget construction shape — the cap varies, the policy knobs never do (DRY). */
+function makeBudget(config: RlmConfig, cap: number): TokenBudget {
+  return new TokenBudget(cap, {
     softFrac: config.budgetSoftFrac,
     maxContinuations: config.budgetMaxContinuations,
   });
 }
 
+/** An effective budget that can never trigger — the cascade "switched off" without changing
+ *  any call-site types (budget: TokenBudget | undefined). */
+function unboundedBudget(config: RlmConfig): TokenBudget {
+  return makeBudget(config, Number.MAX_SAFE_INTEGER);
+}
+
 export function resolveBudget(contextWindow: number | undefined, config: RlmConfig): TokenBudget {
   const ctx = contextWindow !== undefined && contextWindow > 0 ? contextWindow : 32_000;
   if (ctx < BUDGET_WINDOW_FLOOR) return unboundedBudget(config);
   const shareCap = Math.floor(ctx * config.budgetShare);
   const cap = config.budgetTaskCap > 0 ? Math.min(shareCap, config.budgetTaskCap) : shareCap;
-  return new TokenBudget(Math.max(cap, 1), {
-    softFrac: config.budgetSoftFrac,
-    maxContinuations: config.budgetMaxContinuations,
-  });
+  return makeBudget(config, Math.max(cap, 1));
 }
 
 /**
@@ -150,12 +152,15 @@ export function truncateMid(text: string, maxChars: number): string {
   return text.slice(0, half) + ELISION_MARK.replace("N", String(elided)) + text.slice(text.length - half);
 }
 
+/** Digest/handoff section caps — ONE source: budget.ts's handoff distillation and the root
+ *  digest (core/root-digest.ts) must never drift apart on the same trajectory heuristics. */
+export const FINDINGS_MAX = 6;
+export const FINDINGS_MIN_CHARS = 20;
+export const STATE_MAX = 8;
 const QUERY_CHARS = 800;
-const FINDINGS_MAX = 6;
-const FINDINGS_MIN_CHARS = 20;
-const STATE_MAX = 8;
 const STATE_NEEDLE = "REPL stdout";
-const NEXT_STEP_RE = /next|then|will |todo/i;
+/** Next-step probe shared by the engine handoff and the root digest (one wording source). */
+export const NEXT_STEP_RE = /next|then|will |todo/i;
 
 /**
  * Deterministic trajectory → handoff (v5 `distill_trajectory`). No LLM call: the model was
@@ -202,3 +207,84 @@ export function distillTrajectory(
 export function continuationPrompt(n: number, handoff: string): string {
   return `[continuation ${n}]\n${handoff}`;
 }
+
+// ── Workstream A: state-shaped hard-budget handoff ─────────────────────────────────
+
+/**
+ * With Σ active, the hard-budget handoff IS the execution state: compactJSON(Σ) replaces the
+ * prose walk — smaller and lossless where it matters (findings/verifiedFacts survive
+ * verbatim; the paper's exact-state > prose-summary result, Tables 1/5). Reuses the v5
+ * HANDOFF_TEMPLATE slots; `distillTrajectory` remains only for degraded runs.
+ */
+export function stateHandoff(state: RunState, query: string, handoffChars = 4_000): string {
+  const findingsBlock = state.findings.slice(-3).join("\n");
+  return HANDOFF_TEMPLATE.replace("{query}", truncateMid(query.slice(0, QUERY_CHARS), Math.floor(handoffChars * 0.3)))
+    .replace("{findings}", truncateMid(findingsBlock, Math.floor(handoffChars * 0.2)))
+    .replace("{state}", truncateMid(compactJSON(state), Math.floor(handoffChars * 0.35)))
+    .replace("{next}", state.nextStep !== "" ? state.nextStep : DEFAULT_NEXT_STEP);
+}
+
+// ── Workstream F: rectification at budget hard-state (MAS2 Eq. 5, local tier) ─────────
+
+/** One deterministic local fix for a continuation — discriminated union, no flags.
+ *  DOCTRINE: no arm ever switches models or providers — a failing model retries on itself
+ *  until the attempt budget is exhausted, then fails loudly. */
+export type RectifyAction =
+  | { readonly kind: "narrow-paths"; readonly paths: readonly string[] }
+  | { readonly kind: "reduce-concurrency"; readonly maxConcurrentSubcalls: number }
+  | { readonly kind: "none"; readonly reason: string };
+
+/** Compact telemetry label for a rectification (run-node detail line). */
+export function rectifyLabel(action: RectifyAction): string {
+  switch (action.kind) {
+    case "narrow-paths":
+      return `narrow-paths (${action.paths.length})`;
+    case "reduce-concurrency":
+      return `reduce-concurrency → ${action.maxConcurrentSubcalls}`;
+    case "none":
+      return "none";
+  }
+}
+
+/** Path-like tokens harvested from Σ — must contain a separator and an extension. */
+const STATE_PATH_TOKEN = /(?:[\w@.-]+\/+)+[\w@.-]+\.[A-Za-z]{1,6}/g;
+
+/** Top repeated paths from Σ, deterministic: frequency desc, then lexicographic; ≤4. */
+function topPathsFromState(state: RunState | undefined): readonly string[] {
+  if (state === undefined) return [];
+  const freq = new Map<string, number>();
+  const sources = [...state.verifiedFacts, ...state.findings];
+  for (const line of sources) {
+    for (const match of line.matchAll(STATE_PATH_TOKEN)) {
+      const path = match[0];
+      freq.set(path, (freq.get(path) ?? 0) + 1);
+    }
+  }
+  return [...freq.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, 4)
+    .map(([path]) => path);
+}
+
+/**
+ * MAS2 rectification (Eq. 5 adapted): at a budget hard-state, sample ONE local fix — no LLM.
+ * Deterministic priority: (1) narrow child paths from the run's top Σ paths, (2) halve leaf
+ * admission, (3) none. The model/provider pair is NEVER a rectification axis: a failing
+ * model retries until its attempt budget is exhausted and then the call fails loudly —
+ * no silent fallback, no swapping. The engine applies the choice to the continuation
+ * invocation and logs it on the run node.
+ */
+export function rectify(args: {
+  readonly state?: RunState;
+  readonly config: RlmConfig;
+}): RectifyAction {
+  const paths = topPathsFromState(args.state);
+  if (paths.length >= 2) return { kind: "narrow-paths", paths };
+  if (args.config.maxConcurrentSubcalls >= 4) {
+    return {
+      kind: "reduce-concurrency",
+      maxConcurrentSubcalls: Math.max(1, Math.floor(args.config.maxConcurrentSubcalls / 2)),
+    };
+  }
+  return { kind: "none", reason: "no local fix available" };
+}

package/src/core/compaction.ts

@@ -11,6 +11,8 @@ import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { type ChatMsg, modelComplete } from "../bridge/model.ts";
 import type { RetryPolicy } from "../util/retry.ts";
 import { estimateMessageTokens } from "../text/tokens.ts";
+import type { RunState } from "../core/run-state.ts";
+import { compactJSON } from "../core/run-state.ts";
 
 const DEFAULT_CONTEXT_WINDOW = 128_000;
 
@@ -19,7 +21,7 @@ const SUMMARY_REQUEST =
   "(2) any concrete intermediate results — numbers, values, variable names — preserved exactly; " +
   "(3) your next action. Be concise (1–3 paragraphs) but preserve all key results.";
 
-export interface CompactionDeps {
+interface CompactionDeps {
   readonly model: Model<Api>;
   readonly registry: ModelRegistry;
   readonly contextWindow?: number;
@@ -112,3 +114,44 @@ export async function compactHistory(
     },
   ];
 }
+
+/** Same protected-tail rule as elideOldToolPayloads: the working set survives verbatim. */
+const REBASE_KEEP_TURNS = 2;
+
+/**
+ * Workstream A: structural rebase — the SKILL.state replacement for the LLM summary path.
+ *
+ *   history := [ P , user("[Σ] …") , window(O) ]
+ *
+ * Everything older than the protected tail is superseded by the EXACT execution state — no
+ * model call is made at all (the summarizer LLM call disappears by design; the `compactions`
+ * counter still moves so telemetry stays comparable). Failure semantics: pure function, no
+ * fallible operations — the degraded path keeps `compactHistory` for as-built runs.
+ */
+export function rebaseWithState(history: ChatMsg[], state: RunState, count = 1): ChatMsg[] {
+  const system = history.find((m) => m.role === "system");
+  const head: ChatMsg[] = system ? [system] : [];
+  let tailStart = history.length;
+  let seen = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (history[i].role === "assistant") {
+      seen += 1;
+      if (seen >= REBASE_KEEP_TURNS) {
+        tailStart = i;
+        break;
+      }
+    }
+  }
+  const window: ChatMsg[] = tailStart < history.length ? history.slice(tailStart) : [];
+  return [
+    ...head,
+    {
+      role: "user",
+      content:
+        `Your conversation was structurally rebased ${count} time(s): older turns are superseded ` +
+        `by the exact execution state below — do NOT repeat completed work; fresh tool results ` +
+        `outrank Σ when they disagree.\n[Σ] ${compactJSON(state)}`,
+    },
+    ...window,
+  ];
+}