@hicaru/pi-rlm 0.1.0

package/src/tool/rlm-events.ts

@@ -0,0 +1,215 @@
+/**
+ * RlmEmitter — typed EventEmitter wrapper for RLM lifecycle events.
+ *
+ * Replaces RlmToolBridge mutation methods. The engine and bridges emit typed
+ * events instead of calling bridge.addSubcall/updateSubcall/etc. Listeners
+ * (RlmEventAggregator, TelemetrySink) subscribe to build derived state.
+ *
+ * Node.js EventEmitter is synchronous — listeners run in registration order
+ * during emit. No backpressure needed: engine events are sequential, one at
+ * a time during the turn loop.
+ */
+
+import { EventEmitter } from "node:events";
+import type { TelemetrySink } from "../telemetry/sink.ts";
+import type { SubcallKind, SubcallStatus, RlmRunStatus } from "./rlm-details.ts";
+import type { ProposedEdit } from "../sandbox/protocol.ts";
+
+// ── Event payloads ──
+
+/** Emitted when a sub-call is created. ID is auto-generated by the emitter. */
+export interface SubcallCreatedEvent {
+  readonly id: string;
+  readonly parentId?: string;
+  readonly kind: SubcallKind;
+  readonly label: string;
+  readonly model?: string;
+  readonly detail?: string;
+  readonly args?: string;
+  /** Recursion depth. Required — all 9 call sites pass this. */
+  readonly depth: number;
+}
+
+/** Emitted when a sub-call is updated. All fields are partial — only supplied fields are applied. */
+export interface SubcallUpdatedEvent {
+  readonly id: string;
+  readonly status?: SubcallStatus;
+  readonly detail?: string;
+  readonly args?: string;
+  readonly resultPreview?: string;
+  /** Delta — additive on both the subcall and running totals. */
+  readonly costUsd?: number;
+  /** Delta — additive on both the subcall and running totals. */
+  readonly tokens?: number;
+}
+
+export interface TurnEvent {
+  readonly current: number;
+  readonly max: number;
+}
+
+export interface RootUsageEvent {
+  readonly costUsd: number;
+  readonly tokens: number;
+}
+
+export interface AnswerEvent {
+  readonly text: string;
+}
+
+export interface EditsEvent {
+  readonly edits: readonly ProposedEdit[];
+}
+
+export interface StatusEvent {
+  readonly status: RlmRunStatus;
+}
+
+export interface RootPromptEvent {
+  readonly text: string;
+}
+
+// ── RlmEmitter ──
+
+/**
+ * Typed wrapper around a Node.js EventEmitter for RLM lifecycle events.
+ *
+ * Auto-generates monotonic subcall IDs (`s1`, `s2`, …) via `emitSubcallCreated()`.
+ * Provides typed `on*` methods that return unsubscribe functions.
+ * `attachSink()` wires all events to a TelemetrySink and returns a detach function.
+ */
+export class RlmEmitter {
+  private readonly ee = new EventEmitter();
+  private seq = 0;
+
+  // ── Emit ──
+
+  /** Create a new sub-call entry. Returns the auto-generated ID. */
+  emitSubcallCreated(init: Omit<SubcallCreatedEvent, "id">): string {
+    const id = `s${++this.seq}`;
+    const event: SubcallCreatedEvent = { id, ...init };
+    this.ee.emit("subcall:created", event);
+    return id;
+  }
+
+  /** Update an existing sub-call. All fields are partial. costUsd/tokens are additive. */
+  emitSubcallUpdated(event: SubcallUpdatedEvent): void {
+    this.ee.emit("subcall:updated", event);
+  }
+
+  /** Set turn progress (root-only). */
+  emitTurn(current: number, max: number): void {
+    this.ee.emit("turn", { current, max } satisfies TurnEvent);
+  }
+
+  /** Accumulate usage directly to root-level totals. */
+  emitRootUsage(costUsd: number, tokens: number): void {
+    this.ee.emit("root-usage", { costUsd, tokens } satisfies RootUsageEvent);
+  }
+
+  /** Set the final answer text (root-only). */
+  emitAnswer(text: string): void {
+    this.ee.emit("answer", { text } satisfies AnswerEvent);
+  }
+
+  /** Set proposed edits (root-only). */
+  emitEdits(edits: readonly ProposedEdit[]): void {
+    this.ee.emit("edits", { edits } satisfies EditsEvent);
+  }
+
+  /** Set the root run status (done/error/aborted). */
+  emitStatus(status: RlmRunStatus): void {
+    this.ee.emit("status", { status } satisfies StatusEvent);
+  }
+
+  /** Set the root prompt text. Called once before the engine starts. */
+  emitRootPrompt(text: string): void {
+    this.ee.emit("root-prompt", { text } satisfies RootPromptEvent);
+  }
+
+  // ── Subscribe (returns unsubscribe function) ──
+
+  onSubcallCreated(handler: (event: SubcallCreatedEvent) => void): () => void {
+    this.ee.on("subcall:created", handler);
+    return () => { this.ee.off("subcall:created", handler); };
+  }
+
+  onSubcallUpdated(handler: (event: SubcallUpdatedEvent) => void): () => void {
+    this.ee.on("subcall:updated", handler);
+    return () => { this.ee.off("subcall:updated", handler); };
+  }
+
+  onTurn(handler: (event: TurnEvent) => void): () => void {
+    this.ee.on("turn", handler);
+    return () => { this.ee.off("turn", handler); };
+  }
+
+  onRootUsage(handler: (event: RootUsageEvent) => void): () => void {
+    this.ee.on("root-usage", handler);
+    return () => { this.ee.off("root-usage", handler); };
+  }
+
+  onAnswer(handler: (event: AnswerEvent) => void): () => void {
+    this.ee.on("answer", handler);
+    return () => { this.ee.off("answer", handler); };
+  }
+
+  onEdits(handler: (event: EditsEvent) => void): () => void {
+    this.ee.on("edits", handler);
+    return () => { this.ee.off("edits", handler); };
+  }
+
+  onStatus(handler: (event: StatusEvent) => void): () => void {
+    this.ee.on("status", handler);
+    return () => { this.ee.off("status", handler); };
+  }
+
+  onRootPrompt(handler: (event: RootPromptEvent) => void): () => void {
+    this.ee.on("root-prompt", handler);
+    return () => { this.ee.off("root-prompt", handler); };
+  }
+
+  // ── Sink integration ──
+
+  /**
+   * Wire all lifecycle events to a TelemetrySink.
+   * Returns a detach function that unsubscribes all sink listeners.
+   * The caller is responsible for calling `sink.shutdown()` after detaching.
+   */
+  attachSink(sink: TelemetrySink): () => void {
+    const unsubs: (() => void)[] = [];
+
+    unsubs.push(this.onSubcallCreated((event) => {
+      sink.start(event.id, {
+        kind: event.kind,
+        depth: event.depth,
+        parentId: event.parentId,
+        model: event.model,
+        label: event.label,
+        detail: event.detail,
+        args: event.args,
+      });
+    }));
+
+    unsubs.push(this.onSubcallUpdated((event) => {
+      if (event.costUsd !== undefined || event.tokens !== undefined) {
+        sink.usage(event.id, event.costUsd ?? 0, event.tokens ?? 0);
+      }
+      if (event.status !== undefined && event.status !== "running") {
+        sink.end(event.id, {
+          error: event.status === "error" ? (event.detail ?? "error") : undefined,
+          resultPreview: event.resultPreview,
+        });
+      }
+    }));
+
+    return () => { unsubs.forEach((fn) => fn()); };
+  }
+
+  // ── Lifecycle ──
+
+  /** Remove all listeners. Call after the run completes to prevent leaks. */
+  shutdown(): void {
+    this.ee.removeAllListeners();
+  }
+}

package/src/tool/rlm-tool.ts

@@ -0,0 +1,199 @@
+/**
+ * RLM tool — registers the RLM engine as a Pi tool with inline rendering.
+ *
+ * Modeled after rpiv-mono's subagent tool.
+ * The tool's execute() wraps createEngine() with an RlmEmitter + RlmEventAggregator that feeds
+ * onUpdate(partialResult) for progressive TUI re-rendering.
+ */
+
+import { getMarkdownTheme, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text, type Component } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { createPiInteractiveDeps } from "../bridge/pi-interactive.ts";
+import type { RlmController, StartInput } from "../mode/rlm-mode.ts";
+import { createTelemetrySink } from "../telemetry/index.ts";
+import { formatCost, formatTokens, spinnerFrame } from "../ui/theme.ts";
+import { errorMessage } from "../util/errors.ts";
+import { type RlmDetails } from "./rlm-details.ts";
+import { RlmEmitter } from "./rlm-events.ts";
+import { RlmEventAggregator } from "./rlm-aggregator.ts";
+import {
+  headlineStatusGlyph,
+  renderCollapsedSubcallTree,
+  renderExpandedSubcallTree,
+} from "./subcall-render.ts";
+import { createProgressNotifier, validateToolParams } from "./tool-utils.ts";
+import { applyEdits } from "../patch/index.ts";
+import { tryExtractDiff } from "../core/answer.ts";
+
+// ── Parameter schema ──
+
+export const RlmToolParams = Object.freeze(Type.Object({
+  prompt: Type.String({ description: "The task or question for the RLM engine" }),
+  context: Type.Optional(Type.String({ description: "Optional context. If omitted, repo is auto-packed via repomix." })),
+}));
+
+// ── Rendering helpers ──
+
+function rootStats(details: RlmDetails, theme: Theme): string {
+  const parts: string[] = [];
+  parts.push(formatCost(details.totals.costUsd));
+  parts.push(`${formatTokens(details.totals.tokens)} tok`);
+  if (details.turns.current > 0) parts.push(`${details.turns.current} turn${details.turns.current > 1 ? "s" : ""}`);
+  return theme.fg("dim", parts.join(" · "));
+}
+
+// ── Tool definition ──
+
+export function createRlmTool(controller: RlmController): ToolDefinition<typeof RlmToolParams, RlmDetails> {
+  return {
+    name: "rlm",
+    label: "RLM",
+    description: "Run the Recursive Language Model engine to answer complex questions with code execution and recursive sub-agent calls.",
+    parameters: RlmToolParams,
+
+    async execute(_toolCallId, rawParams, signal, onUpdate, ctx) {
+      const validation = validateToolParams(RlmToolParams, rawParams, "RLM", (_errors): RlmDetails => ({
+        status: "error",
+        rootPrompt: "",
+        turns: { current: 0, max: 0 },
+        subcalls: [],
+        totals: { costUsd: 0, tokens: 0 },
+      }));
+      if (!validation.ok) return validation.error;
+      const params = validation.value;
+
+      const sink = await createTelemetrySink(controller.config.telemetry);
+      const emitter = new RlmEmitter();
+      const aggregator = new RlmEventAggregator(emitter, onUpdate ?? (() => {}));
+      let detachSink: (() => void) | undefined;
+      if (sink) detachSink = emitter.attachSink(sink);
+      emitter.emitRootPrompt(params.prompt);
+
+      // Wire abort signal to controller
+      if (signal) {
+        signal.addEventListener("abort", () => controller.abort(), { once: true });
+      }
+
+      // Animated spinner: cycle through braille frames while running
+      const progress = createProgressNotifier<RlmDetails>({
+        onUpdate,
+        getDetails: () => aggregator.getState(),
+        isRunning: (details) => details.status === "running",
+        renderText: () => `${spinnerFrame()} RLM running…`,
+      });
+      progress.start();
+
+      try {
+        const input: StartInput = {
+          kind: "fresh",
+          rootPrompt: params.prompt,
+          context: params.context ?? undefined,
+        };
+        const interactive = createPiInteractiveDeps(ctx);
+        const { done } = controller.start(ctx, input, emitter, {
+          onAskUserQuestion: controller.config.askUserQuestion ? interactive.onAskUserQuestion : undefined,
+          onTodo: controller.config.todo ? interactive.onTodo : undefined,
+        });
+        const result = await done;
+
+        emitter.emitAnswer(result.answer);
+        const proposedEdits = result.edits ?? [];
+        const proposedDiffs = result.diffs?.length ? result.diffs : tryExtractDiff(result.answer);
+        if (proposedEdits.length > 0) emitter.emitEdits(proposedEdits);
+        await applyEdits(proposedEdits, proposedDiffs, ctx);
+
+        return {
+          content: [{ type: "text", text: result.answer }],
+          details: aggregator.getState(),
+        };
+      } catch (e) {
+        emitter.emitStatus("error");
+        const msg = `RLM failed: ${errorMessage(e)}`;
+        return {
+          content: [{ type: "text", text: msg }],
+          details: aggregator.getState(),
+        };
+      } finally {
+        progress.stop();
+        detachSink?.();
+        aggregator.dispose();
+        emitter.shutdown();
+        try { await sink?.shutdown(); }
+        catch (err) { console.warn(`[rlm] telemetry shutdown failed: ${errorMessage(err)}`); }
+      }
+    },
+
+    renderCall(args, theme, _context) {
+      const preview = args.prompt.length > 80
+        ? `${args.prompt.slice(0, 80)}...`
+        : args.prompt;
+      return new Text(
+        theme.fg("toolTitle", theme.bold("rlm ")) +
+        theme.fg("dim", preview.replace(/\n/g, " ")),
+        0, 0,
+      );
+    },
+
+    renderResult(result, { expanded, isPartial: _isPartial }, theme, _context) {
+      const details = result.details as RlmDetails | undefined;
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+      }
+      if (expanded) {
+        return renderExpanded(details, theme);
+      }
+      return renderCollapsed(details, theme);
+    },
+  };
+}
+
+// ── Expanded view ──
+
+function renderExpanded(details: RlmDetails, theme: Theme): Component {
+  const container = new Container();
+
+  const glyph = headlineStatusGlyph(details.status, theme);
+  const header = `${glyph} ${theme.fg("toolTitle", theme.bold("RLM"))} · ${rootStats(details, theme)}`;
+  container.addChild(new Text(header, 0, 0));
+
+  if (details.subcalls.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", "─── Sub-calls ───"), 0, 0));
+    container.addChild(renderExpandedSubcallTree(details.subcalls, theme));
+  }
+
+  if (details.answer) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", "─── Answer ───"), 0, 0));
+    container.addChild(new Markdown(details.answer, 0, 0, getMarkdownTheme()));
+  }
+
+  if (details.edits && details.edits.length > 0) {
+    container.addChild(new Spacer(1));
+    const editFiles = new Set(details.edits.map(e => e.path));
+    container.addChild(new Text(
+      theme.fg("muted", "─── Edits ───") +
+      `\n  ${theme.fg("dim", `${details.edits.length} edit${details.edits.length > 1 ? "s" : ""} proposed across ${editFiles.size} file${editFiles.size > 1 ? "s" : ""}`)}`,
+      0, 0,
+    ));
+  }
+
+  return container;
+}
+
+// ── Collapsed view ──
+
+function renderCollapsed(details: RlmDetails, theme: Theme): Text {
+  const glyph = headlineStatusGlyph(details.status, theme);
+  const header = `${glyph} ${theme.fg("toolTitle", theme.bold("RLM"))} · ${rootStats(details, theme)}`;
+
+  let body = "";
+  if (details.subcalls.length > 0) {
+    body = `\n${renderCollapsedSubcallTree(details.subcalls, theme)}`;
+  }
+
+  const expandHint = details.status === "running" ? "" : `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+  return new Text(`${header}${body}${expandHint}`, 0, 0);
+}

package/src/tool/subcall-render.ts

@@ -0,0 +1,129 @@
+/**
+ * Shared sub-call tree rendering for RLM tools (rlm + repl).
+ *
+ * Both tools accumulate RlmSubcall[] arrays with parentId links. This module
+ * provides the collapsed ASCII tree and expanded Container-based tree rendering
+ * used by their renderResult() implementations.
+ */
+
+import { Container, Text, type Component } from "@earendil-works/pi-tui";
+import type { RlmSubcall, SubcallStatus } from "./rlm-details.ts";
+import { formatCost, formatDuration, formatTokens, spinnerFrame } from "../ui/theme.ts";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+// ── Glyphs ──
+
+export function subcallRunningGlyph(theme: Theme): string {
+  return theme.fg("warning", spinnerFrame());
+}
+
+export function subcallStatusGlyph(sc: Pick<RlmSubcall, "status">, theme: Theme): string {
+  if (sc.status === "running") return theme.fg("warning", "⏳");
+  if (sc.status === "error") return theme.fg("error", "✗");
+  return theme.fg("success", "✓");
+}
+
+export function headlineStatusGlyph(status: SubcallStatus | "aborted" | "done", theme: Theme): string {
+  switch (status) {
+    case "done": return theme.fg("success", "✓");
+    case "error": return theme.fg("error", "✗");
+    case "aborted": return theme.fg("warning", "◐");
+    default: return theme.fg("warning", spinnerFrame());
+  }
+}
+
+// ── Stats formatting ──
+
+export function subcallStatsLine(sc: Pick<RlmSubcall, "costUsd" | "tokens" | "endedAt" | "startedAt">): string {
+  const parts: string[] = [];
+  if (sc.costUsd > 0) parts.push(formatCost(sc.costUsd));
+  if (sc.tokens > 0) parts.push(`${formatTokens(sc.tokens)} tok`);
+  if (sc.endedAt && sc.startedAt) parts.push(formatDuration(sc.endedAt - sc.startedAt));
+  return parts.join(" · ");
+}
+
+// ── Tree building ──
+
+function buildParentMap(subcalls: readonly RlmSubcall[]): Map<string | undefined, RlmSubcall[]> {
+  const map = new Map<string | undefined, RlmSubcall[]>();
+  for (const sc of subcalls) {
+    const list = map.get(sc.parentId) ?? [];
+    list.push(sc);
+    map.set(sc.parentId, list);
+  }
+  return map;
+}
+
+// ── Collapsed tree (ASCII) ──
+
+export function renderCollapsedSubcallTree(
+  subcalls: readonly RlmSubcall[],
+  theme: Theme,
+): string {
+  if (subcalls.length === 0) return "";
+
+  const byParent = buildParentMap(subcalls);
+
+  function walk(parentId: string | undefined, prefix: string): string[] {
+    const lines: string[] = [];
+    const direct = byParent.get(parentId) ?? [];
+    for (let i = 0; i < direct.length; i++) {
+      const sc = direct[i];
+      if (!sc) continue;
+      const isLast = i === direct.length - 1;
+      const branch = isLast ? "└─" : "├─";
+      const gGlyph = subcallStatusGlyph(sc, theme);
+      const gStats = subcallStatsLine(sc);
+      lines.push(`${prefix}${branch} ${sc.label}  ${gGlyph}  ${gStats}`);
+      const childPrefix = prefix + (isLast ? "   " : "│  ");
+      lines.push(...walk(sc.id, childPrefix));
+    }
+    return lines;
+  }
+
+  return walk(undefined, "  ").join("\n");
+}
+
+// ── Expanded tree (Container) ──
+
+export function renderExpandedSubcallTree(
+  subcalls: readonly RlmSubcall[],
+  theme: Theme,
+): Component {
+  const container = new Container();
+  if (subcalls.length === 0) return container;
+
+  const byParent = buildParentMap(subcalls);
+
+  function renderNode(sc: RlmSubcall, indent: number): void {
+    const pad = "  ".repeat(indent);
+    const sGlyph = subcallStatusGlyph(sc, theme);
+    const sKind = theme.fg("muted", sc.label);
+    const sModel = sc.model ? theme.fg("dim", ` ${sc.model}`) : "";
+    const sStats = sc.endedAt ? `  ${theme.fg("dim", subcallStatsLine(sc))}` : "";
+    let line = `${pad}${sGlyph} ${sKind}${sModel}${sStats}`;
+
+    if (sc.args) {
+      const ap = sc.args.length > 80 ? `${sc.args.slice(0, 80)}...` : sc.args;
+      line += `\n${pad}  ${theme.fg("dim", ap)}`;
+    }
+    if (sc.status === "error" && sc.detail) {
+      line += `\n${pad}  ${theme.fg("error", `✗ ${sc.detail}`)}`;
+    } else if (sc.resultPreview) {
+      const rp = sc.resultPreview.length > 120 ? `${sc.resultPreview.slice(0, 120)}...` : sc.resultPreview;
+      line += `\n${pad}  ${theme.fg("toolOutput", rp)}`;
+    }
+
+    container.addChild(new Text(line, 0, 0));
+
+    for (const child of (byParent.get(sc.id) ?? [])) {
+      renderNode(child, indent + 1);
+    }
+  }
+
+  for (const sc of (byParent.get(undefined) ?? [])) {
+    renderNode(sc, 1);
+  }
+
+  return container;
+}

package/src/tool/subcall-store.ts

@@ -0,0 +1,90 @@
+/**
+ * SubcallStore — shared subcall state accumulator for RLM lifecycle events.
+ *
+ * Subscribes to RlmEmitter subcall:created / subcall:updated events and
+ * accumulates RlmSubcall[] state with O(1) running totals. Used by both
+ * RlmEventAggregator (rlm tool) and repl() tool to eliminate duplicated
+ * subcall accumulation logic.
+ */
+import type { RlmEmitter, SubcallCreatedEvent, SubcallUpdatedEvent } from "./rlm-events.ts";
+import type { RlmSubcall, SubcallStatus } from "./rlm-details.ts";
+import { EmitterListener } from "./emitter-listener.ts";
+
+type MutableSubcall = {
+  -readonly [Key in keyof RlmSubcall]: RlmSubcall[Key];
+};
+
+export class SubcallStore extends EmitterListener {
+  private readonly subcalls = new Map<string, MutableSubcall>();
+
+  private totalCostUsd = 0;
+  private totalTokens = 0;
+
+  constructor(emitter: RlmEmitter, private readonly onChange?: () => void) {
+    super();
+    this.trackAll([
+      emitter.onSubcallCreated((e) => { this.handleSubcallCreated(e); this.onChange?.(); }),
+      emitter.onSubcallUpdated((e) => { this.handleSubcallUpdated(e); this.onChange?.(); }),
+    ]);
+  }
+
+  // ── Event handlers ──
+
+  private handleSubcallCreated(event: SubcallCreatedEvent): void {
+    this.subcalls.set(event.id, {
+      id: event.id,
+      parentId: event.parentId,
+      depth: event.depth,
+      kind: event.kind,
+      label: event.label,
+      model: event.model,
+      status: "running",
+      detail: event.detail,
+      args: event.args,
+      startedAt: Date.now(),
+      costUsd: 0,
+      tokens: 0,
+    });
+  }
+
+  private handleSubcallUpdated(event: SubcallUpdatedEvent): void {
+    const sc = this.subcalls.get(event.id);
+    if (!sc) return;
+
+    if (event.status !== undefined) {
+      sc.status = event.status;
+      if (event.status !== "running") sc.endedAt = Date.now();
+    }
+    if (event.detail !== undefined) sc.detail = event.detail;
+    if (event.args !== undefined) sc.args = event.args;
+    if (event.resultPreview !== undefined) sc.resultPreview = event.resultPreview;
+    if (event.costUsd !== undefined) {
+      sc.costUsd += event.costUsd;
+      this.totalCostUsd += event.costUsd;
+    }
+    if (event.tokens !== undefined) {
+      sc.tokens += event.tokens;
+      this.totalTokens += event.tokens;
+    }
+  }
+
+  // ── Read ──
+
+  /** Snapshot subcall array. Allocates a new array from Map values. */
+  getSubcalls(): RlmSubcall[] {
+    return Array.from(this.subcalls.values(), (subcall) => Object.freeze({ ...subcall, status: subcall.status as SubcallStatus }));
+  }
+
+  /** Snapshot running totals. O(1). */
+  getTotals(): { readonly costUsd: number; readonly tokens: number } {
+    return { costUsd: this.totalCostUsd, tokens: this.totalTokens };
+  }
+
+  // ── Root usage (delegated from RlmEventAggregator) ──
+
+  /** Accumulate root-level usage into shared totals. Called by aggregator. */
+  addRootUsage(costUsd: number, tokens: number): void {
+    this.totalCostUsd += costUsd;
+    this.totalTokens += tokens;
+  }
+}