@hicaru/pi-rlm 0.1.0

package/src/state/reads.ts

@@ -0,0 +1,96 @@
+/**
+ * Fail-soft JSONL readers for the RLM run-state module.
+ *
+ * `readRows` parses each line in its own try/catch so a truncated trailing
+ * line cannot erase prior rows. `listRunIds` sorts directories newest-first
+ * by the slug (ISO-like timestamps are self-sorting).
+ */
+
+import { open, readFile } from "node:fs/promises";
+import { runsDir, trailPath, contextPath } from "./paths.ts";
+import { isHeader, isRow, type RunHeader, type Row } from "./rows.ts";
+import { errorMessage, failSoft, listDirectoriesSorted, pathExists, warn } from "./internal.ts";
+
+/** Every well-formed row, in trail order. Malformed line → one warn, skipped. */
+export async function readRows(cwd: string, dir: string, runId: string): Promise<Row[]> {
+  const path = trailPath(cwd, dir, runId);
+  if (!await pathExists(path)) return [];
+  const content = await failSoft(
+    () => readFile(path, "utf-8"),
+    undefined as string | undefined,
+  );
+  const trimmed = content?.trim();
+  if (!trimmed) return [];
+
+  const rows: Row[] = [];
+  for (const line of trimmed.split("\n")) {
+    try {
+      const row = JSON.parse(line) as unknown;
+      if (isRow(row)) rows.push(row);
+      else warn("skipping invalid JSONL row shape");
+    } catch (e) {
+      warn(`skipping malformed JSONL row — ${errorMessage(e)}`);
+    }
+  }
+  return rows;
+}
+
+/** Read the first line of a trail file without reading the entire file (P1). */
+async function readFirstLine(path: string): Promise<string | undefined> {
+  return await failSoft(async () => {
+    const file = await open(path, "r");
+    try {
+      const stats = await file.stat();
+      const size = Math.min(stats.size, 65536);
+      if (size <= 0) return undefined;
+      const buffer = Buffer.alloc(size);
+      const { bytesRead } = await file.read(buffer, 0, size, 0);
+      const content = buffer.toString("utf-8", 0, bytesRead);
+      const nl = content.indexOf("\n");
+      return nl >= 0 ? content.slice(0, nl) : content.trim() || undefined;
+    } finally {
+      await file.close();
+    }
+  }, undefined as string | undefined, { warn: false });
+}
+
+/** First well-formed header row, or undefined. Bounded read — never reads the full trail (P1). */
+export async function readHeader(cwd: string, dir: string, runId: string): Promise<RunHeader | undefined> {
+  const line = await readFirstLine(trailPath(cwd, dir, runId));
+  if (!line) return undefined;
+  try {
+    const row = JSON.parse(line) as unknown;
+    return isHeader(row) ? row : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Reload context from a persistent sidecar file. */
+export async function readContextSidecar(cwd: string, dir: string, runId: string, json: boolean): Promise<unknown> {
+  const path = contextPath(cwd, dir, runId, json);
+  if (!await pathExists(path)) return undefined;
+  const content = await failSoft(
+    () => readFile(path, "utf-8"),
+    undefined as string | undefined,
+  );
+  if (content === undefined) return undefined;
+  try {
+    return json ? JSON.parse(content) as unknown : content;
+  } catch (e) {
+    warn(e);
+    return undefined;
+  }
+}
+
+/** Enumerate run-ids by directory listing; newest first (slug sorts chronologically). */
+export async function listRunIds(cwd: string, dir: string): Promise<string[]> {
+  return await failSoft(() => listDirectoriesSorted(runsDir(cwd, dir)), [], { warn: false });
+}
+
+/** `@latest` / explicit id resolution. */
+export async function resolveRunId(cwd: string, dir: string, ref: string): Promise<string | undefined> {
+  const ids = await listRunIds(cwd, dir);
+  if (ref === "@latest") return ids[0];
+  return ids.includes(ref) ? ref : undefined;
+}

package/src/state/resume.ts

@@ -0,0 +1,154 @@
+/**
+ * Resume fold — rebuilds engine state from a JSONL trail in one pass.
+ *
+ * The fold reuses the live engine's own prompt builders (`buildTurnPrompt`) so
+ * the rebuilt history is faithful — DRY: the fold and the live loop share the
+ * same message-construction helpers. Mid-file malformed rows fail; trailing
+ * garbage from a crash is tolerated.
+ */
+
+import { readFile } from "node:fs/promises";
+import { type ChatMsg } from "../bridge/model.ts";
+import { appendUserMessage } from "../core/history.ts";
+import { buildTurnPrompt } from "../prompts/user.ts";
+import type { ProposedEdit } from "../sandbox/protocol.ts";
+import { readHeader } from "./reads.ts";
+import {
+  isCompaction,
+  isHeader,
+  isPhase,
+  isRow,
+  isTerminal,
+  isTodo,
+  isTurn,
+  STATE_SCHEMA_VERSION,
+  type Row,
+  type RunHeader,
+} from "./rows.ts";
+import { trailPath, snapshotPath } from "./paths.ts";
+import { failSoft, pathExists } from "./internal.ts";
+
+export interface PhaseRecon {
+  readonly current: string;
+  readonly advancedAt: number;
+  readonly summary?: string;
+}
+
+export type ReconstructResult =
+  | {
+      readonly ok: true;
+      readonly header: RunHeader;
+      readonly history: ChatMsg[];
+      readonly pendingReplOutputs?: string;
+      readonly usageSeed: { readonly costUsd: number; readonly inputTokens: number; readonly outputTokens: number; readonly durationMs: number };
+      readonly best: string;
+      readonly editsAcc: ProposedEdit[];
+      readonly completedTurns: number;
+      readonly compactions: number;
+      /** R-C1: the latest turn whose per-turn snapshot file exists on disk (undefined ⇒ no restore). */
+      readonly snapshotTurn: number | undefined;
+      readonly todoRows: readonly { readonly action: string; readonly params: Record<string, unknown>; readonly result: string }[];
+      readonly terminated: boolean;
+      /** Reconstructed pipeline phase state. undefined ⇒ pre-v3 trail (treats as research). */
+      readonly phase?: PhaseRecon;
+    }
+  | { readonly ok: false; readonly reason: "no-header" | "version-mismatch" | "no-turns" | "mid-file-hole"; readonly detail: string };
+
+/** QB: single read + parse — detects mid-file holes without reading the trail twice. */
+async function readRowsStrict(cwd: string, dir: string, runId: string): Promise<{ readonly rows: Row[]; readonly hole: boolean }> {
+  const path = trailPath(cwd, dir, runId);
+  if (!await pathExists(path)) return { rows: [], hole: false };
+  const content = await failSoft(() => readFile(path, "utf-8"), undefined as string | undefined);
+  const trimmed = content?.trim();
+  if (!trimmed) return { rows: [], hole: false };
+
+  const rows: Row[] = [];
+  let sawBad = false;
+  for (const line of trimmed.split("\n")) {
+    try {
+      const row = JSON.parse(line) as unknown;
+      if (!isRow(row)) {
+        sawBad = true;
+        continue;
+      }
+      rows.push(row);
+      if (sawBad) return { rows, hole: true }; // good line after a bad one = mid-file hole
+    } catch {
+      sawBad = true; // trailing bad line tolerated; a subsequent good line means a hole
+    }
+  }
+  return { rows, hole: false };
+}
+
+export async function reconstructRlmState(
+  cwd: string,
+  dir: string,
+  runId: string,
+  systemPrompt: string,
+): Promise<ReconstructResult> {
+  const header = await readHeader(cwd, dir, runId);
+  if (!header) return { ok: false, reason: "no-header", detail: runId };
+  // QB: ??1 backward-compat — when bumping STATE_SCHEMA_VERSION, also bump this default
+  // so trails written without an explicit `v` field are rejected rather than silently passed.
+  if ((header.v ?? 1) !== STATE_SCHEMA_VERSION)
+    return { ok: false, reason: "version-mismatch", detail: `run ${runId} written under schema v${header.v}` };
+
+  const { rows, hole } = await readRowsStrict(cwd, dir, runId);
+  if (hole) return { ok: false, reason: "mid-file-hole", detail: runId };
+
+  let history: ChatMsg[] = [{ role: "system", content: systemPrompt }];
+  const usageSeed = { costUsd: 0, inputTokens: 0, outputTokens: 0, durationMs: 0 };
+  let best = "";
+  let editsAcc: ProposedEdit[] = [];
+  let completedTurns = 0;
+  let compactions = 0;
+  let snapshotTurn: number | undefined; // R-C1: latest turn with an existing snapshot file
+  let pendingReplOutputs: string | undefined;
+  const todoRows: { action: string; params: Record<string, unknown>; result: string }[] = [];
+  let terminated = false;
+  let phase: PhaseRecon | undefined;
+
+  for (const row of rows) {
+    if (isHeader(row)) continue;
+    if (isCompaction(row)) {
+      history = [...row.history];
+      compactions++;
+      usageSeed.costUsd += row.usage.costUsd;
+      usageSeed.inputTokens += row.usage.inputTokens;
+      usageSeed.outputTokens += row.usage.outputTokens;
+      pendingReplOutputs = undefined;
+      continue;
+    }
+    if (isTurn(row)) {
+      const i = row.turn - 1;
+      if (pendingReplOutputs) appendUserMessage(history, pendingReplOutputs);
+      appendUserMessage(history, buildTurnPrompt(i, header.meta.maxIterations));
+      history.push({ role: "assistant", content: row.response });
+      usageSeed.costUsd += row.usage.costUsd;
+      usageSeed.inputTokens += row.usage.inputTokens;
+      usageSeed.outputTokens += row.usage.outputTokens;
+      if (row.answerContent) best = row.answerContent;
+      else if (!best && row.response.trim()) best = row.response; // C3: mirror engine fallback
+      if (row.edits && row.edits.length > 0) editsAcc = [...row.edits];
+      completedTurns = row.turn;
+      // R-C1: verify the per-turn snapshot file exists — a crashed finalize leaves the row claiming snapshotOk:true with no pkl.
+      if (row.snapshotOk && await pathExists(snapshotPath(cwd, dir, runId, row.turn)))
+        snapshotTurn = row.turn;
+      usageSeed.durationMs = row.cumulativeDurationMs; // C2: seed wall-clock
+      pendingReplOutputs = row.replOutputs;
+      continue;
+    }
+    if (isPhase(row)) {
+      phase = { current: row.phase, advancedAt: row.turn - 1, summary: row.summary };
+      continue;
+    }
+    if (isTodo(row)) {
+      todoRows.push({ action: row.action, params: row.params, result: row.result });
+      continue;
+    }
+    if (isTerminal(row)) terminated = true;
+  }
+
+  if (completedTurns === 0 && !terminated) return { ok: false, reason: "no-turns", detail: runId };
+  return { ok: true, header, history, pendingReplOutputs, usageSeed, best, editsAcc, completedTurns, compactions, snapshotTurn, todoRows, terminated, phase };
+}

package/src/state/rows.ts

@@ -0,0 +1,117 @@
+/**
+ * Run-state row shapes for the RLM JSONL audit trail.
+ *
+ * REPLAY CONTRACT: every field below is part of the resume fold's reconstruction.
+ * If any field is added, removed, or its semantics change, bump STATE_SCHEMA_VERSION
+ * so older trails are rejected rather than mis-replayed.
+ *
+ * Guards accept `unknown` and narrow via `hasKind` — no `any`, no `!`.
+ */
+
+import type { ChatMsg } from "../bridge/model.ts";
+import type { ProposedEdit } from "../sandbox/protocol.ts";
+
+/** Bump when a row shape changes such that the resume fold cannot replay older files. */
+export const STATE_SCHEMA_VERSION = 5;
+
+export interface UsageRow {
+  readonly costUsd: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+/** Line 1 of every trail. Carries everything the fold needs to rebuild the system prompt + reload context. */
+export interface RunHeader {
+  readonly kind: "header";
+  readonly v: number;
+  readonly runId: string;
+  readonly ts: string;
+  readonly rootPrompt: string;
+  readonly context: { readonly type: string; readonly chars: number; readonly json: boolean };
+  readonly models: { readonly model: string; readonly worker: string };
+  /** Snapshot of the replay-affecting config (maxIterations, orchestrator, pipeline…). */
+  readonly meta: {
+    readonly maxIterations: number;
+    readonly maxDepth: number;
+    readonly orchestrator: boolean;
+    /** pipeline-enabled gate behaviour (always true from v4 on). */
+    readonly pipeline?: boolean;
+  };
+}
+
+/** One completed turn. `response`+`replOutputs` rebuild history; the rest restore scalars. */
+export interface TurnRow {
+  readonly kind: "turn";
+  readonly turn: number;            // 1-based (== engine `i + 1`)
+  readonly ts: string;
+  readonly response: string;        // assistant message
+  readonly replOutputs?: string;    // formatReplOutputs(results) → next user message
+  readonly answerContent?: string;  // restores `best`
+  readonly edits?: readonly ProposedEdit[]; // restores editsAcc (latest wins)
+  readonly error: boolean;          // turnHadError → limits.observe on resume
+  readonly usage: UsageRow;
+  readonly cumulativeDurationMs: number; // limits.usage().durationMs at turn-write time
+  readonly snapshotOk: boolean;     // whether sandbox.pkl reflects THIS turn
+}
+
+/** Emitted when compaction rewrites history; the fold replaces history wholesale. */
+export interface CompactionRow {
+  readonly kind: "compaction";
+  readonly turn: number;
+  readonly ts: string;
+  readonly history: readonly ChatMsg[]; // post-compaction array (small by design)
+  readonly usage: UsageRow;             // compaction model cost added to limits
+}
+
+export interface TodoRow {
+  readonly kind: "todo";
+  readonly turn: number;
+  readonly ts: string;
+  readonly action: string;
+  readonly params: Record<string, unknown>;
+  readonly result: string;
+}
+
+export interface TerminalRow {
+  readonly kind: "terminal";
+  readonly ts: string;
+  readonly status: "completed" | "finalized" | "aborted" | "stopped";
+  readonly answer: string;
+  readonly iterations: number;
+  readonly usage: UsageRow;
+}
+
+/** Emitted when the root RLM advances to a new pipeline phase. */
+export interface PhaseRow {
+  readonly kind: "phase";
+  readonly turn: number; // 1-based turn when advanced
+  readonly ts: string;
+  readonly phase: string;
+  readonly summary?: string;
+}
+
+export type Row = RunHeader | TurnRow | CompactionRow | TodoRow | TerminalRow | PhaseRow;
+
+const hasKind = (r: unknown, k: Row["kind"]): boolean =>
+  typeof r === "object" && r !== null && (r as { kind?: unknown }).kind === k;
+
+export const isHeader = (r: unknown): r is RunHeader =>
+  hasKind(r, "header") && typeof (r as RunHeader).runId === "string" && typeof (r as RunHeader).rootPrompt === "string"
+  && typeof (r as RunHeader).meta?.maxIterations === "number";
+
+export const isTurn = (r: unknown): r is TurnRow =>
+  hasKind(r, "turn") && typeof (r as TurnRow).turn === "number" && typeof (r as TurnRow).response === "string";
+
+export const isCompaction = (r: unknown): r is CompactionRow =>
+  hasKind(r, "compaction") && Array.isArray((r as CompactionRow).history);
+
+export const isTodo = (r: unknown): r is TodoRow =>
+  hasKind(r, "todo") && typeof (r as TodoRow).action === "string" && typeof (r as TodoRow).result === "string";
+
+export const isTerminal = (r: unknown): r is TerminalRow => hasKind(r, "terminal");
+
+export const isPhase = (r: unknown): r is PhaseRow =>
+  hasKind(r, "phase") && typeof (r as PhaseRow).phase === "string" && typeof (r as PhaseRow).turn === "number";
+
+export const isRow = (r: unknown): r is Row =>
+  isHeader(r) || isTurn(r) || isCompaction(r) || isTodo(r) || isTerminal(r) || isPhase(r);

package/src/state/writes.ts

@@ -0,0 +1,56 @@
+/**
+ * Fail-soft JSONL writes for the RLM run-state module.
+ *
+ * Every writer returns `boolean` and warns on failure — never throws into
+ * the engine loop. A failed `appendRow` disables persistence for the rest
+ * of the run without aborting the answer.
+ */
+
+import { appendFile, mkdir, open, rm, writeFile } from "node:fs/promises";
+import { contextPath, runDir, runsDir, trailPath } from "./paths.ts";
+import type { Row, TodoRow } from "./rows.ts";
+import { errorMessage, failSoft, listDirectoriesSorted, warn } from "./internal.ts";
+
+/** mkdir + append one JSON line. Returns true on success; warns + false on throw. Never throws. */
+export async function appendRow(cwd: string, dir: string, runId: string, row: Row): Promise<boolean> {
+  return await failSoft(async () => {
+    await mkdir(runDir(cwd, dir, runId), { recursive: true });
+    const path = trailPath(cwd, dir, runId);
+    await appendFile(path, `${JSON.stringify(row)}\n`, "utf-8");
+    // QC: fsync to flush kernel buffers — crash between write and sync would lose the last row
+    const file = await open(path, "r+");
+    try {
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    return true;
+  }, false);
+}
+
+export async function appendTodoRow(cwd: string, dir: string, runId: string, row: Omit<TodoRow, "kind">): Promise<boolean> {
+  return await appendRow(cwd, dir, runId, { kind: "todo", ...row });
+}
+
+/** Persist the original context ONCE at run start so resume can reload it. */
+export async function writeContextSidecar(cwd: string, dir: string, runId: string, context: unknown, json: boolean): Promise<boolean> {
+  return await failSoft(async () => {
+    await mkdir(runDir(cwd, dir, runId), { recursive: true });
+    await writeFile(contextPath(cwd, dir, runId, json), json ? JSON.stringify(context) : String(context), "utf-8");
+    return true;
+  }, false);
+}
+
+/** Prune oldest run directories beyond maxRuns. Best-effort; never throws. */
+export async function pruneRuns(cwd: string, dir: string, maxRuns: number): Promise<void> {
+  try {
+    const ids = await listDirectoriesSorted(runsDir(cwd, dir)); // newest first (slug sorts chronologically)
+    const pruned = ids.slice(maxRuns);
+    if (pruned.length > 0) console.log(`[rlm-state] pruning ${pruned.length} runs (maxRuns=${maxRuns})`);
+    for (const id of pruned) {
+      await rm(runDir(cwd, dir, id), { recursive: true, force: true });
+    }
+  } catch (e) {
+    warn(`pruneRuns failed: ${errorMessage(e)}`);
+  }
+}

package/src/telemetry/dispatcher.ts

@@ -0,0 +1,116 @@
+export interface DispatcherSink<E> {
+  readonly name: string;
+  handle(event: E): Promise<void>;
+  flush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export interface DispatcherOptions {
+  readonly maxQueueSize: number;
+}
+
+/** Bounded FIFO async dispatcher with drop-oldest backpressure. */
+export class Dispatcher<E> {
+  private readonly sinks: DispatcherSink<E>[] = [];
+  private queue: E[] = [];
+  private flushing = false;
+  private inFlight: Promise<void> = Promise.resolve();
+  private shuttingDown = false;
+  private backpressureActive = false;
+  private readonly failed = new Set<string>();
+
+  constructor(private readonly options: DispatcherOptions) {}
+
+  registerSink(sink: DispatcherSink<E>): () => void {
+    this.sinks.push(sink);
+    return () => {
+      const idx = this.sinks.indexOf(sink);
+      if (idx >= 0) this.sinks.splice(idx, 1);
+    };
+  }
+
+  dispatch(event: E): void {
+    if (this.shuttingDown || this.sinks.length === 0) return;
+    const cap = this.options.maxQueueSize;
+    if (this.queue.length >= cap) {
+      this.queue.shift();
+      if (!this.backpressureActive) {
+        this.backpressureActive = true;
+        console.warn(`[rlm-telemetry] backpressure: queue saturated at ${cap}; dropping oldest events`);
+      }
+    } else if (this.backpressureActive && this.queue.length < cap - 1) {
+      this.backpressureActive = false;
+      console.warn("[rlm-telemetry] backpressure recovered: queue back under capacity");
+    }
+    this.queue.push(event);
+    this.scheduleFlush();
+  }
+
+  async shutdown(): Promise<void> {
+    this.shuttingDown = true;
+    const remaining = this.queue;
+    this.queue = [];
+    this.flushing = false;
+
+    await this.inFlight;
+
+    for (const event of remaining) await this.broadcast(event);
+    const sinks = [...this.sinks];
+    await Promise.allSettled(sinks.map((sink) => sink.flush()));
+    await Promise.allSettled(sinks.map((sink) => sink.shutdown()));
+  }
+
+  reset(): void {
+    this.sinks.length = 0;
+    this.queue = [];
+    this.flushing = false;
+    this.inFlight = Promise.resolve();
+    this.shuttingDown = false;
+    this.backpressureActive = false;
+    this.failed.clear();
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushing) return;
+    this.flushing = true;
+    this.drain();
+  }
+
+  private drain(): void {
+    if (this.queue.length === 0) {
+      this.flushing = false;
+      return;
+    }
+    const batch = this.queue;
+    this.queue = [];
+
+    this.inFlight = this.inFlight.then(async () => {
+      for (const event of batch) await this.broadcast(event);
+      if (this.queue.length > 0) {
+        const handle = setImmediate(() => this.drain());
+        handle.unref?.();
+      } else {
+        this.flushing = false;
+      }
+    });
+  }
+
+  private async broadcast(event: E): Promise<void> {
+    const sinks = [...this.sinks];
+    const results = await Promise.allSettled(sinks.map((sink) => sink.handle(event)));
+    results.forEach((result, idx) => {
+      const name = sinks[idx]?.name;
+      if (!name) return;
+      if (result.status === "rejected") {
+        if (!this.failed.has(name)) {
+          this.failed.add(name);
+          const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+          console.warn(`[rlm-telemetry] sink ${name} rejected event: ${reason}`);
+        }
+      } else if (this.failed.has(name)) {
+        this.failed.delete(name);
+        console.warn(`[rlm-telemetry] sink ${name} recovered`);
+      }
+    });
+  }
+}

package/src/telemetry/index.ts

@@ -0,0 +1,14 @@
+import type { TelemetryConfig } from "../core/types.ts";
+import { resolveMlflowConfig } from "./mlflow-config.ts";
+import type { TelemetrySink } from "./sink.ts";
+
+export type { TelemetrySink };
+
+export async function createTelemetrySink(config: TelemetryConfig | undefined): Promise<TelemetrySink | undefined> {
+  if (!config) return undefined;
+  const resolved = resolveMlflowConfig({ trackingUri: config.trackingUri, experimentId: config.experimentId });
+  const enabled = config.enabled ?? Boolean(resolved.trackingUri);
+  if (!enabled || !resolved.trackingUri) return undefined;
+  const { MlflowSink } = await import("./mlflow-sink.ts");
+  return new MlflowSink(resolved, config.maxQueueSize);
+}

package/src/telemetry/mlflow-config.ts

@@ -0,0 +1,15 @@
+export interface MlflowConfig {
+  readonly trackingUri?: string;
+  readonly experimentId?: string;
+  readonly trackingToken?: string;
+}
+
+const readEnv = (key: string): string | undefined => process.env[key]?.trim() || undefined;
+
+export function resolveMlflowConfig(config: Pick<MlflowConfig, "trackingUri" | "experimentId">): MlflowConfig {
+  return {
+    trackingUri: readEnv("MLFLOW_TRACKING_URI") || config.trackingUri,
+    experimentId: readEnv("MLFLOW_EXPERIMENT_ID") || config.experimentId,
+    trackingToken: readEnv("MLFLOW_TRACKING_TOKEN"),
+  };
+}