@hicaru/pi-rlm 0.3.16 → 0.3.18

package/src/core/root-context.ts

@@ -0,0 +1,184 @@
+/**
+ * Root Σ (WS-3) — per-LLM-call A_t assembly for the native Pi session, via the `context`
+ * event (which feeds Pi's transformContext → applied on EVERY provider call).
+ *
+ * Pi hands handlers a structuredClone of the outgoing messages; the LAST returned array
+ * wins and the disk transcript is never touched — context is the query channel, the
+ * session log stays the archive (LLM-memory-survey thesis). Both transforms mutate the
+ * clone in place (new message objects land in the same array slots; splice uses the same
+ * array) to honor the zero-extra-allocations rule.
+ *
+ * - `elideStalePayloads` — discard semantics (paper §5.3): tool payloads older than the
+ *   keep window become head+tail previews; the full bytes remain in the session log.
+ * - `spliceSigmaSnapshot` — the fresh Σ snapshot rides immediately before the last user
+ *   message, exactly one instance (previous ones are removed — idempotent per call).
+ *
+ * Both are pure with respect to the transcript and never throw on weird shapes.
+ */
+
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+import type { RunState } from "./run-state.ts";
+import { runStateRootBlock } from "./run-state.ts";
+import { ROOT_TURN_ELIDED_LINE } from "../prompts/glossary.ts";
+import { truncateOutput } from "../text/parsing.ts";
+import { textContentOf } from "../text/agent-text.ts";
+
+/** The message union Pi passes through the context event (indexed — host evolution safe). */
+export type RootMessage = ContextEvent["messages"][number];
+
+export interface ElideOptions {
+  readonly keepTurns: number;
+  readonly elideChars: number;
+}
+
+const ELIDE_MARK = "chars elided — full result in session log";
+
+/**
+ * WS-3a: elide stale turns. The newest `keepTurns` assistant turns and the final user message
+ * stay verbatim. Older turns collapse in two tiers (§5.3 discard semantics + R5/G4 honest
+ * strictness, and the only way the R6 acceptance bound — per-call ≤ Σ + window — can hold):
+ *   - recent stale ring (the last `max(keepTurns, 1)` stale turns): toolResult payloads over
+ *     `elideChars` become head+tail previews (same truncation shape as repl stdout); assistant
+ *     prose always collapses to the one-line stub.
+ *   - older still: EVERYTHING (payloads included) becomes the one-line session-log stub —
+ *     a stale preview per turn would itself accumulate linearly and re-create O(T).
+ * `role:"custom"` messages of the Σ/intro kinds are immune (WS-3b owns them). Mutates the
+ * array in place; returns the number of messages elided (telemetry), for zero-cost counters.
+ */
+export function elideStalePayloads(messages: RootMessage[], opts: ElideOptions): number {
+  const keepTurns = Math.max(0, Math.floor(opts.keepTurns));
+  if (messages.length === 0) return 0;
+  // Preview ring: stale turns recent enough to deserve the §5.3 head+tail preview. Scales with
+  // the window knob — one calibration, two tiers (preview ring, then stub) — and never zero,
+  // so keepTurns=0 still previews the single closest stale payload instead of stubbing blind.
+  const previewRing = Math.max(keepTurns, 1);
+  if (keepTurns === 0) {
+    // R5 strict-0: nothing inside the window — Σ + immune customs + the final user message
+    // are all that survive verbatim.
+    return elideRange(messages, 0, messages.length, opts, previewRing);
+  }
+
+  // Index of the assistant message that opens the keepTurns-th-from-last turn — everything
+  // from there on is the protected tail (same walk as core/compaction.ts elideOldToolPayloads).
+  let tailStart = -1;
+  let seen = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === "assistant") {
+      seen += 1;
+      if (seen >= keepTurns) {
+        tailStart = i;
+        break;
+      }
+    }
+  }
+  if (tailStart <= 0) return 0; // fewer turns than the window — nothing to elide
+  return elideRange(messages, 0, tailStart, opts, previewRing);
+}
+
+/** Custom messages the elision never touches — the Σ snapshot/observation and the intro. */
+const IMMUNE_CUSTOM_TYPES: ReadonlySet<string> = new Set(["rlm-sigma", "rlm-sigma-observation", "rlm-intro"]);
+
+function isImmuneCustom(m: RootMessage): boolean {
+  if (m.role !== "custom") return false;
+  const customType: unknown = (m as { customType?: unknown }).customType;
+  return typeof customType === "string" && IMMUNE_CUSTOM_TYPES.has(customType);
+}
+
+/** R5: elide [from, to) — stale assistant prose always becomes the one-line Σ stub; stale
+ *  toolResults get the §5.3 preview while `assistantsAfter < previewRing` and the stub beyond
+ *  (two-tier elision — previews must not accumulate linearly). Immune customs and the final
+ *  user message are never touched. Mutates in place; returns the elided count. */
+function elideRange(
+  messages: RootMessage[],
+  from: number,
+  to: number,
+  opts: ElideOptions,
+  previewRing: number,
+): number {
+  const lastUser = lastIndexOfRole(messages, "user");
+  // Pre-pass: stale assistant indices in [from, to) — a payload's recency is measured by the
+  // stale turns AFTER it (pre-allocated walk, no per-message allocation).
+  let staleAssistants = 0;
+  for (let i = from; i < to; i++) {
+    if (messages[i]?.role === "assistant") staleAssistants += 1;
+  }
+  let elided = 0;
+  for (let i = from; i < to; i++) {
+    const m = messages[i];
+    if (m === undefined || isImmuneCustom(m)) continue;
+    if (i === lastUser) continue; // paranoia: the final user message is never touched
+    if (m.role === "assistant") {
+      staleAssistants -= 1; // turns AFTER this one = count minus itself
+      messages[i] = { ...m, content: [{ type: "text", text: ROOT_TURN_ELIDED_LINE }] } as RootMessage;
+      elided += 1;
+      continue;
+    }
+    if (m.role !== "toolResult") continue;
+    if (staleAssistants >= previewRing) {
+      // Deep-stale payload: even the preview would accumulate — collapse to the stub.
+      messages[i] = { ...m, content: [{ type: "text", text: ROOT_TURN_ELIDED_LINE }] } as RootMessage;
+      elided += 1;
+      continue;
+    }
+    if (totalTextLength(m) <= opts.elideChars) continue;
+    messages[i] = {
+      ...m,
+      content: [{ type: "text", text: previewToolText(m, opts.elideChars) }],
+    } as RootMessage;
+    elided += 1;
+  }
+  return elided;
+}
+
+/** WS-3b: exactly one live Σ snapshot, immediately before the LAST user message.
+ *  R2 (G2): `withContract` makes the splice carry the fence contract (A.4 authoring mode) —
+ *  pass-through to runStateRootBlock; without it, the v1 observation-only block. */
+export function spliceSigmaSnapshot(
+  messages: RootMessage[],
+  state: RunState,
+  rectifyHint: string | undefined,
+  opts?: { readonly withContract?: boolean },
+): void {
+  const block = runStateRootBlock(state, opts);
+  const text = rectifyHint === undefined ? block : `${block}\n${rectifyHint}`;
+  // Remove any previous instance (only one lives at a time — idempotent across calls).
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (isSigmaSnapshot(m)) messages.splice(i, 1);
+  }
+  const at = lastIndexOfRole(messages, "user");
+  const sigma: RootMessage = {
+    role: "custom",
+    customType: "rlm-sigma",
+    content: text,
+    display: false,
+    details: { kind: "sigma-snapshot", updatedAt: state.updatedAt },
+    timestamp: Date.now(),
+  } as RootMessage;
+  if (at < 0) {
+    messages.push(sigma); // no user message (degenerate) — append; still exactly one
+  } else {
+    messages.splice(at, 0, sigma);
+  }
+}
+
+function isSigmaSnapshot(m: RootMessage | undefined): boolean {
+  return m !== undefined && m.role === "custom" && (m as { customType?: unknown }).customType === "rlm-sigma";
+}
+
+function lastIndexOfRole(messages: readonly RootMessage[], role: "user"): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === role) return i;
+  }
+  return -1;
+}
+
+function totalTextLength(message: RootMessage): number {
+  return textContentOf((message as { content?: unknown }).content).length;
+}
+
+function previewToolText(message: RootMessage, elideChars: number): string {
+  const text = textContentOf((message as { content?: unknown }).content);
+  // The preview REPLACES the payload, so `elideChars` budgets the WHOLE head+tail result.
+  return truncateOutput(text, Math.max(100, elideChars), ELIDE_MARK);
+}

package/src/core/root-digest.ts

@@ -0,0 +1,213 @@
+/**
+ * Root Σ (WS-2) — deterministic root compaction for the Pi harness orchestrator.
+ *
+ * When the native session compacts, this replaces Pi's LLM prose summarizer with a
+ * structural digest: the same no-LLM distillation shape the engine proven-uses at its
+ * budget hard-state (core/budget.ts:distillTrajectory), adapted to host AgentMessages.
+ * Zero summary tokens; compaction becomes reproducible. Paper framing: the digest is a
+ * Σ-style sufficient statistic (§3.1) — sections are ordered by continuity value, and the
+ * verbatim tail after `firstKeptEntryId` stays byte-identical (§5.3 observation override:
+ * fresh tool results outrank the digest).
+ *
+ * Cut-point semantics: Pi's preparation already picked `firstKeptEntryId` via its
+ * keepRecentTokens walk. We only ever TIGHTEN (move the cut later, shrinking the verbatim
+ * tail toward `rootDigestKeepRecentChars`) — never extend — and fold every message the
+ * tighter cut displaces into the digest inputs, so nothing is dropped unaccounted. Cuts
+ * land on entry boundaries Pi itself treats as safe (the walk is char-budgeted over whole
+ * entries, mirroring pi-docs/compaction.md's accumulate-and-cut).
+ *
+ * Failure semantics: pure function, no model call, no throw paths — the index.ts handler
+ * still wraps it fail-soft (host contract: handlers must not throw) and returns undefined
+ * so Pi falls back to its own summarizer.
+ */
+
+import type { CompactionResult, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { RlmConfig } from "./types.ts";
+import { DEFAULT_NEXT_STEP, FINDINGS_MAX, FINDINGS_MIN_CHARS, NEXT_STEP_RE, STATE_MAX, truncateMid } from "./budget.ts";
+import { estimateMessageTokens } from "../text/tokens.ts";
+import { agentMessageText } from "../text/agent-text.ts";
+import { isRecord } from "../util/type-guards.ts";
+import { ROOT_DIGEST_HEADER, ROOT_DIGEST_SECTIONS } from "../prompts/glossary.ts";
+
+/** Marker persisted on the session's compaction entry — tests and soaks assert on it. */
+export interface RootDigestDetails {
+  readonly kind: "root-digest";
+  readonly version: 1;
+}
+
+/** Structural slice of SkillStore the digest needs — tests inject stand-ins without a store. */
+export interface DigestFactSource {
+  sliceForPrompt(query: string, budgetTokens: number, minScore: number): string;
+}
+
+/** `SessionBeforeCompactEvent["preparation"]` slice — indexed on the event shape upstream. */
+export interface RootDigestPreparation {
+  readonly firstKeptEntryId: string;
+  readonly messagesToSummarize: readonly unknown[];
+  readonly isSplitTurn: boolean;
+  readonly tokensBefore: number;
+}
+
+export interface RootDigestArgs {
+  readonly preparation: RootDigestPreparation;
+  /** Chronological session entries (event.branchEntries) — the tighten walk reads these. */
+  readonly branchEntries: readonly SessionEntry[];
+  readonly config: Pick<RlmConfig, "rootDigestKeepRecentChars" | "rootDigestMaxChars" | "skillStateMinScore">;
+  readonly store: DigestFactSource | undefined;
+}
+
+/** Section caps come from budget.ts (ONE source — N2); only digest-local shapes live here. */
+const BULLET_CHARS = 400;
+const TASK_FRACTION = 0.3;
+const FACTS_FRACTION = 4; // facts budget = maxChars / FACTS_FRACTION, tokens at 4 chars/token
+
+/** AgentMessage-shaped projection of one session entry (host sessionEntryToContextMessages shape). */
+function entryMessages(entry: SessionEntry): readonly unknown[] {
+  if (!isRecord(entry)) return [];
+  if (entry.type === "message" && isRecord(entry.message)) return [entry.message];
+  if (entry.type === "custom_message") return [{ role: "custom", content: entry.content }];
+  if (entry.type === "compaction" && typeof entry.summary === "string") {
+    return [{ role: "compactionSummary", summary: entry.summary }];
+  }
+  if (entry.type === "branch_summary" && typeof entry.summary === "string") {
+    return [{ role: "branchSummary", summary: entry.summary }];
+  }
+  return [];
+}
+
+function entryChars(entry: SessionEntry): number {
+  let total = 0;
+  for (const message of entryMessages(entry)) total += agentMessageText(message).length + 8;
+  return total;
+}
+/**
+ * The ONE tighten walk: index of the first entry kept verbatim (≥ piCut). Walks backward
+ * accumulating entry chars until the budget is met; when the whole tail fits under the
+ * budget, Pi's boundary stands — we never EXTEND the digest span past Pi's cut.
+ */
+function tightenedCut(entries: readonly SessionEntry[], piCut: number, keepChars: number): number {
+  let acc = 0;
+  for (let i = entries.length - 1; i >= piCut; i--) {
+    acc += entryChars(entries[i]);
+    if (acc >= keepChars) return i;
+  }
+  return piCut;
+}
+
+/** [Task] — the LAST user prompt in the span (the ask still in force when compaction hits). */
+function taskSection(messages: readonly unknown[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (isRecord(m) && m.role === "user") {
+      const text = agentMessageText(m).trim();
+      if (text !== "") return text;
+    }
+  }
+  return "";
+}
+
+/** [Findings] — newest-first substantive assistant blobs, capped, then chronological. */
+function findingsSection(messages: readonly unknown[]): readonly string[] {
+  const findings: string[] = [];
+  for (let i = messages.length - 1; i >= 0 && findings.length < FINDINGS_MAX; i--) {
+    const m = messages[i];
+    if (!isRecord(m) || m.role !== "assistant") continue;
+    const text = agentMessageText(m).trim();
+    if (text.length > FINDINGS_MIN_CHARS) findings.push(text);
+  }
+  findings.reverse();
+  return findings;
+}
+
+/** [State] — newest-first toolResult first-lines (the last observed machinery state). */
+function stateSection(messages: readonly unknown[]): readonly string[] {
+  const states: string[] = [];
+  for (let i = messages.length - 1; i >= 0 && states.length < STATE_MAX; i--) {
+    const m = messages[i];
+    if (!isRecord(m) || m.role !== "toolResult") continue;
+    const text = agentMessageText(m).trim();
+    if (text === "") continue;
+    const tool = typeof m.toolName === "string" ? m.toolName : "tool";
+    states.push(`${tool}: ${text.split("\n", 1)[0] ?? text}`);
+  }
+  states.reverse();
+  return states;
+}
+
+/**
+ * Build the digest compaction. Returns undefined when Pi should keep its own path:
+ * split turns (our flat summary would double-count the turn prefix) or an empty span.
+ *
+ * `tokensBeforeRecomputed` is our own estimateMessageTokens pass over the same span —
+ * V1 soak probe: the host consumes `compaction.tokensBefore` (Pi's own preparation number)
+ * as-is; one trace line carries both so the first real /compact confirms whether the host
+ * ever diverges (status-line truth check) without touching the persisted CompactionResult.
+ */
+export function buildRootDigestCompaction(
+  args: RootDigestArgs,
+): {
+  readonly compaction: CompactionResult<RootDigestDetails>;
+  readonly tokensBeforeRecomputed: number;
+} | undefined {
+  const prep = args.preparation;
+  if (prep.isSplitTurn) return undefined;
+
+  const piCut = args.branchEntries.findIndex((entry) => entry.id === prep.firstKeptEntryId);
+  const cut = piCut < 0 ? -1 : tightenedCut(args.branchEntries, piCut, args.config.rootDigestKeepRecentChars);
+
+  const messages: unknown[] = [...prep.messagesToSummarize];
+  if (cut > piCut && piCut >= 0) {
+    for (let i = piCut; i < cut; i++) messages.push(...entryMessages(args.branchEntries[i]));
+  }
+  if (messages.length === 0) return undefined;
+
+  const max = Math.max(200, args.config.rootDigestMaxChars);
+  const task = truncateMid(taskSection(messages), Math.floor(max * TASK_FRACTION));
+  const findings = findingsSection(messages).map((f) => truncateMid(f, BULLET_CHARS));
+  const states = stateSection(messages);
+  // Next-step probe mirrors distillTrajectory: newest-first scan, chronological render.
+  const next = findings.find((f) => NEXT_STEP_RE.test(f)) ?? DEFAULT_NEXT_STEP;
+  const facts = args.store === undefined
+    ? ""
+    : args.store.sliceForPrompt(
+        task,
+        Math.max(1, Math.floor(max / FACTS_FRACTION / 4)),
+        args.config.skillStateMinScore,
+      );
+
+  const render = (factsText: string, stateLines: readonly string[], findingLines: readonly string[]): string => {
+    const blocks: string[] = [ROOT_DIGEST_HEADER];
+    const section = (label: string, body: string): void => {
+      if (body.trim() !== "") blocks.push(`[${label}] ${body}`);
+    };
+    section(ROOT_DIGEST_SECTIONS.task, task);
+    section(ROOT_DIGEST_SECTIONS.findings, findingLines.map((f) => `- ${f}`).join("\n"));
+    section(ROOT_DIGEST_SECTIONS.state, stateLines.map((s) => `- ${s}`).join("\n"));
+    section(ROOT_DIGEST_SECTIONS.next, next);
+    section(ROOT_DIGEST_SECTIONS.facts, factsText);
+    return blocks.join("\n\n");
+  };
+
+  // Over-cap drop order: [Project facts] → [State] → [Findings]; [Task]/[Next] survive to a
+  // final truncate — task continuity beats trivia (paper §3.1 sufficient statistic).
+  let summary = render(facts, states, findings);
+  if (summary.length > max) summary = render("", states, findings);
+  if (summary.length > max) summary = render("", [], findings);
+  if (summary.length > max) {
+    summary = render("", [], findings.slice(0, Math.max(1, Math.floor(findings.length / 2))));
+  }
+  summary = truncateMid(summary, max);
+
+  const boundary = cut >= 0 ? args.branchEntries[cut] : undefined;
+  return {
+    compaction: {
+      summary,
+      firstKeptEntryId: (isRecord(boundary) && typeof boundary.id === "string" ? boundary.id : undefined)
+        ?? prep.firstKeptEntryId,
+      tokensBefore: prep.tokensBefore,
+      details: { kind: "root-digest", version: 1 },
+    },
+    // Same CHAR_PER_TOKEN=4 (+8/message) math as the engine budgets — comparable numbers.
+    tokensBeforeRecomputed: estimateMessageTokens(messages.map((m) => ({ content: agentMessageText(m) }))),
+  };
+}