@hicaru/pi-rlm 0.1.0

package/src/tool/tool-utils.ts

@@ -0,0 +1,73 @@
+/** Shared helpers for Pi tool implementations. */
+
+import type { Static, TSchema } from "typebox";
+import { Value } from "typebox/value";
+import { err, ok, type Result } from "../util/errors.ts";
+
+export interface TextToolResponse<Details> {
+  readonly content: { readonly type: "text"; readonly text: string }[];
+  readonly details: Details;
+}
+
+export function validateToolParams<Schema extends TSchema, Details>(
+  schema: Schema,
+  rawParams: unknown,
+  toolName: string,
+  createErrorDetails: (errors: string) => Details,
+): Result<Static<Schema>, TextToolResponse<Details>> {
+  if (Value.Check(schema, rawParams)) return ok(rawParams as Static<Schema>);
+  const errors = [...Value.Errors(schema, rawParams)]
+    .map((error) => `${error.instancePath}: ${error.message}`)
+    .join("; ");
+  return err({
+    content: [{ type: "text", text: `Invalid ${toolName} parameters: ${errors}` }],
+    details: createErrorDetails(errors),
+  });
+}
+
+export type TextUpdateCallback<Details> = (update: TextToolResponse<Details>) => void;
+
+export interface ProgressNotifierOptions<Details> {
+  readonly onUpdate?: TextUpdateCallback<Details>;
+  readonly getDetails: () => Details;
+  readonly isRunning: (details: Details) => boolean;
+  readonly renderText: (details: Details) => string;
+  readonly intervalMs?: number;
+}
+
+export interface ProgressNotifier {
+  readonly notify: () => void;
+  readonly start: () => void;
+  readonly stop: () => void;
+}
+
+export function createProgressNotifier<Details>(opts: ProgressNotifierOptions<Details>): ProgressNotifier {
+  let handle: ReturnType<typeof setInterval> | undefined;
+
+  const stop = (): void => {
+    if (handle === undefined) return;
+    clearInterval(handle);
+    handle = undefined;
+  };
+
+  const notify = (): void => {
+    if (!opts.onUpdate) return;
+    const details = opts.getDetails();
+    opts.onUpdate({ content: [{ type: "text", text: opts.renderText(details) }], details });
+  };
+
+  const start = (): void => {
+    if (!opts.onUpdate || handle !== undefined) return;
+    notify();
+    handle = setInterval(() => {
+      const details = opts.getDetails();
+      if (!opts.isRunning(details)) {
+        stop();
+        return;
+      }
+      opts.onUpdate?.({ content: [{ type: "text", text: opts.renderText(details) }], details });
+    }, opts.intervalMs ?? 100);
+  };
+
+  return Object.freeze({ notify, start, stop });
+}

package/src/ui/config-panel.ts

@@ -0,0 +1,92 @@
+/** Config panel TUI — toggle RLM run parameters with descriptions. */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui";
+import type { RlmConfig } from "../core/types.ts";
+
+const CHOICES = Object.freeze({
+  maxDepth: Object.freeze(["1", "2", "3", "4"]),
+  maxIterations: Object.freeze(["10", "20", "30", "50"]),
+  execTimeoutS: Object.freeze(["30", "60", "120", "300"]),
+  maxConcurrentSubcalls: Object.freeze(["2", "4", "8", "16"]),
+  maxBudgetUsd: Object.freeze(["none", "0.50", "1", "5"]),
+  maxTimeoutMs: Object.freeze(["none", "60", "120", "300"]),
+  maxTokens: Object.freeze(["none", "10000", "50000", "100000"]),
+  maxErrors: Object.freeze(["3", "5", "10", "none"]),
+  orchestrator: Object.freeze(["on", "off"]),
+  compaction: Object.freeze(["on", "off"]),
+  rootSamplingMaxTokens: Object.freeze(["4096", "8192", "16384", "32768"]),
+  sandboxInitTimeoutMs: Object.freeze(["10000", "30000", "60000", "120000"]),
+  askUserQuestion: Object.freeze(["on", "off"]),
+  todo: Object.freeze(["on", "off"]),
+});
+
+function item(id: string, label: string, currentValue: string, values: readonly string[], description: string): SettingItem {
+  return { id, label, currentValue, values: [...values], description };
+}
+
+export async function showConfigPanel(ctx: ExtensionContext, config: RlmConfig): Promise<void> {
+  if (ctx.mode !== "tui") return;
+  const items: SettingItem[] = [
+    item("maxDepth", "Max recursion depth", String(config.maxDepth), CHOICES.maxDepth, "rlm_query past this depth degrades to plain llm_query (1 = no recursion)."),
+    item("maxIterations", "Max iterations", String(config.maxIterations), CHOICES.maxIterations, "Maximum root REPL turns before RLM asks the model for a final answer."),
+    item("execTimeoutS", "REPL block timeout (s)", String(config.execTimeoutS), CHOICES.execTimeoutS, "Wall-clock limit for one model-authored Python REPL block."),
+    item("maxConcurrentSubcalls", "Max concurrent sub-calls", String(config.maxConcurrentSubcalls), CHOICES.maxConcurrentSubcalls, "Concurrency pool size for llm_query_batched and rlm_query_batched."),
+    item("maxBudgetUsd", "Budget ceiling (USD)", config.maxBudgetUsd != null ? String(config.maxBudgetUsd) : "none", CHOICES.maxBudgetUsd, "Total spend cap for the whole recursive tree; none disables the cap."),
+    item("maxTimeoutMs", "Wall-clock ceiling (min)", config.maxTimeoutMs != null ? String(Math.round(config.maxTimeoutMs / 60_000)) : "none", CHOICES.maxTimeoutMs, "Total runtime cap for the whole recursive tree; none disables the cap."),
+    item("maxTokens", "Token ceiling", config.maxTokens != null ? String(config.maxTokens) : "none", CHOICES.maxTokens, "Total input+output token cap for the whole recursive tree."),
+    item("maxErrors", "Max consecutive errors", config.maxErrors != null ? String(config.maxErrors) : "none", CHOICES.maxErrors, "Stop after this many consecutive failing turns; none disables the guard."),
+    item("orchestrator", "Orchestrator addendum", config.orchestrator ? "on" : "off", CHOICES.orchestrator, "Append extra divide-and-conquer guidance to the root model system prompt."),
+    item("compaction", "Trajectory compaction", config.compaction ? "on" : "off", CHOICES.compaction, "Summarize old turns when history approaches the model context window."),
+    item("rootSamplingMaxTokens", "Root model output cap (tok)", String(config.rootSampling?.maxTokens ?? 16384), CHOICES.rootSamplingMaxTokens, "Max output tokens per root-model turn. Lower values keep each turn lean."),
+    item("sandboxInitTimeoutMs", "Sandbox init timeout", String(config.sandboxInitTimeoutMs), CHOICES.sandboxInitTimeoutMs, "How long to wait for the Python worker to start."),
+    item("askUserQuestion", "[Interactive] Ask user", config.askUserQuestion ? "on" : "off", CHOICES.askUserQuestion, "Allow root REPL code to present structured ask_user_question dialogs."),
+    item("todo", "[Interactive] Todo", config.todo ? "on" : "off", CHOICES.todo, "Allow REPL code to manage a visible todo task list."),
+    item("__save__", "Save & close", "↵", ["↵"], "Save these settings and close (Esc also saves)."),
+  ];
+
+  await ctx.ui.custom<void>((_tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new Text(theme.fg("accent", theme.bold("RLM settings")), 1, 1));
+    const list = new SettingsList(
+      items,
+      items.length + 2,
+      getSettingsListTheme(),
+      (id, value) => {
+        if (id === "__save__") {
+          done();
+          return;
+        }
+        applySetting(config, id, value);
+      },
+      () => done(),
+    );
+    container.addChild(list);
+    container.addChild(new Text(theme.fg("dim", "↑↓ move · enter change · esc save & close"), 1, 1));
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => list.handleInput?.(data),
+    };
+  });
+}
+
+function applySetting(config: RlmConfig, id: string, value: string): void {
+  switch (id) {
+    case "maxDepth": config.maxDepth = Number(value); break;
+    case "maxIterations": config.maxIterations = Number(value); break;
+    case "execTimeoutS": config.execTimeoutS = Number(value); break;
+    case "maxConcurrentSubcalls": config.maxConcurrentSubcalls = Number(value); break;
+    case "maxBudgetUsd": config.maxBudgetUsd = value === "none" ? undefined : Number(value); break;
+    case "maxTimeoutMs": config.maxTimeoutMs = value === "none" ? undefined : Number(value) * 60_000; break;
+    case "maxTokens": config.maxTokens = value === "none" ? undefined : Number(value); break;
+    case "maxErrors": config.maxErrors = value === "none" ? undefined : Number(value); break;
+    case "orchestrator": config.orchestrator = value === "on"; break;
+    case "compaction": config.compaction = value === "on"; break;
+    case "rootSamplingMaxTokens": config.rootSampling = Object.freeze({ ...config.rootSampling, maxTokens: Number(value) }); break;
+    case "sandboxInitTimeoutMs": config.sandboxInitTimeoutMs = Number(value); break;
+    case "askUserQuestion": config.askUserQuestion = value === "on"; break;
+    case "todo": config.todo = value === "on"; break;
+  }
+}

package/src/ui/intro.ts

@@ -0,0 +1,23 @@
+/** Startup/help guide card for RLM mode. */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import { formatRlmStateLine } from "./status.ts";
+
+export const RLM_GUIDE = `# RLM mode
+
+{state}
+
+## Commands
+
+- \`/rlm\` — toggle RLM mode (shortcut: Ctrl+Shift+R). Turning it OFF also stops a running query.
+- \`/rlm-config\` — choose models, reasoning, and budget limits
+- \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)
+- \`/rlm-help\` — show this guide again
+
+When RLM mode is ON, plain messages route to RLM. The footer/status line shows the current state.`;
+
+export function postRlmGuide(pi: ExtensionAPI, controller: RlmController): void {
+  const content = RLM_GUIDE.replace("{state}", formatRlmStateLine(controller));
+  pi.sendMessage({ customType: "rlm-intro", content, display: true });
+}

package/src/ui/model-picker.ts

@@ -0,0 +1,139 @@
+/** Model picker TUI — choose a model and, when supported, a thinking level. */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
+import { Container, type Component, type SelectItem, SelectList, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { formatCost } from "./theme.ts";
+
+export interface ModelSelection {
+  readonly model: Model<Api>;
+  readonly thinkingLevel?: ThinkingLevel;
+}
+
+const LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+type SelectableThinkingLevel = (typeof LEVELS)[number];
+
+function items(models: Model<Api>[]): SelectItem[] {
+  return models.map((m) => ({
+    value: `${m.provider}/${m.id}`,
+    label: `${m.provider}/${m.id}`,
+    description: `in ${formatCost(m.cost.input)}/Mtok · out ${formatCost(m.cost.output)}/Mtok${m.reasoning ? " · reasoning" : ""}`,
+  }));
+}
+
+function supportedThinkingLevels(model: Model<Api>): SelectableThinkingLevel[] {
+  if (!model.reasoning) return [];
+  const map = model.thinkingLevelMap;
+  if (!map) return [...LEVELS];
+  return LEVELS.filter((level) => map[level] !== null);
+}
+
+async function selectThinkingLevel(
+  ctx: ExtensionContext,
+  model: Model<Api>,
+  current?: ThinkingLevel,
+): Promise<ThinkingLevel | undefined> {
+  const levels = supportedThinkingLevels(model);
+  if (levels.length === 0) return undefined;
+  if (ctx.mode !== "tui") {
+    const level = current ?? levels[0];
+    return level === "off" ? undefined : level;
+  }
+
+  const chosen = await ctx.ui.custom<SelectableThinkingLevel | null>((_tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold("Thinking level")), 1, 0));
+    const list = new SelectList(
+      levels.map((level) => ({ value: level, label: level, description: `Use ${level} reasoning for ${model.id}` })),
+      levels.length,
+      {
+        selectedPrefix: (t) => theme.fg("accent", t),
+        selectedText: (t) => theme.fg("accent", t),
+        description: (t) => theme.fg("muted", t),
+        scrollInfo: (t) => theme.fg("dim", t),
+        noMatch: (t) => theme.fg("warning", t),
+      },
+    );
+    const initial = levels.indexOf(current ?? "off");
+    if (initial >= 0) list.setSelectedIndex(initial);
+    list.onSelect = (item) => done(item.value as SelectableThinkingLevel);
+    list.onCancel = () => done(null);
+    container.addChild(list);
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc skip"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return { render: (w) => container.render(w), invalidate: () => container.invalidate(), handleInput: (data) => list.handleInput(data) };
+  });
+  return chosen === "off" ? undefined : (chosen ?? undefined);
+}
+
+/** Show a model selector; resolves to the chosen model plus optional thinking level. */
+export async function selectModel(
+  ctx: ExtensionContext,
+  title: string,
+  models: Model<Api>[],
+  current?: Model<Api>,
+  currentThinking?: ThinkingLevel,
+): Promise<ModelSelection | undefined> {
+  if (models.length === 0) {
+    ctx.ui.notify("RLM: no models with configured auth", "warning");
+    return undefined;
+  }
+  if (ctx.mode !== "tui") {
+    const fallback = models[0];
+    if (!fallback) return undefined;
+    const model = current ?? fallback;
+    return { model, thinkingLevel: await selectThinkingLevel(ctx, model, currentThinking) };
+  }
+
+  const chosen = await ctx.ui.custom<string | null>((_tui, theme, _kb, done) => {
+    let query = "";
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+    const filterLine: Component = {
+      render: (w) => [truncateToWidth(theme.fg("dim", `Filter: ${query || "type to filter…"}`), w)],
+      invalidate: () => {},
+    };
+    const list = new SelectList(items(models), Math.min(models.length, 12), {
+      selectedPrefix: (t) => theme.fg("accent", t),
+      selectedText: (t) => theme.fg("accent", t),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    });
+    const isFilterText = (s: string): boolean => {
+      const sanitized = s.replace(/ /g, "");
+      return sanitized.length > 0 && Array.from(sanitized).every((char) => char >= " " && char !== "\x7f");
+    };
+    const isBackspace = (s: string): boolean => s === "\x7f" || s === "\b";
+    list.onSelect = (item) => done(item.value);
+    list.onCancel = () => done(null);
+    container.addChild(filterLine);
+    container.addChild(list);
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate • type to filter • enter select • esc cancel"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => {
+        if (isFilterText(data)) {
+          query = `${query}${data.replace(/ /g, "")}`;
+          list.setFilter(query);
+          return;
+        }
+        if (isBackspace(data)) {
+          query = query.slice(0, -1);
+          list.setFilter(query);
+          return;
+        }
+        list.handleInput(data);
+      },
+    };
+  });
+
+  const model = chosen ? models.find((m) => `${m.provider}/${m.id}` === chosen) : undefined;
+  if (!model) return undefined;
+  return { model, thinkingLevel: await selectThinkingLevel(ctx, model, currentThinking) };
+}

package/src/ui/status.ts

@@ -0,0 +1,26 @@
+/** Footer status line for RLM mode and active runs. */
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { RlmController } from "../mode/rlm-mode.ts";
+
+const KEY = "rlm";
+
+export function modelLabel(model: Model<Api> | undefined, fallback: string): string {
+  return model ? `${model.provider}/${model.id}` : fallback;
+}
+
+export function formatRlmStateLine(controller: RlmController): string {
+  if (!controller.enabled) return "○ RLM OFF";
+  const worker = modelLabel(controller.workerModel, controller.savedWorkerRef ?? "cheapest");
+  const workerSuffix = controller.config.subSampling.reasoning ? `:${controller.config.subSampling.reasoning}` : "";
+  return `● RLM ON · worker=${worker}${workerSuffix}`;
+}
+
+export function setRlmModeStatus(ui: ExtensionUIContext, controller: RlmController): void {
+  ui.setStatus(KEY, formatRlmStateLine(controller));
+}
+
+export function clearRlmStatus(ui: ExtensionUIContext): void {
+  ui.setStatus(KEY, undefined);
+}

package/src/ui/theme.ts

@@ -0,0 +1,47 @@
+/** Small presentation helpers shared by the RLM widgets (glyphs, spinner, formatting). */
+
+import type { SubcallKind, SubcallStatus } from "../tool/rlm-details.ts";
+
+export const SPINNER = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]);
+
+export function spinnerFrame(): string {
+  return SPINNER[Math.floor(Date.now() / 100) % SPINNER.length] ?? "⠋";
+}
+
+/** Glyph for a node's status. */
+export function statusGlyph(status: SubcallStatus): string {
+  if (status === "done") return "✓";
+  if (status === "error") return "✗";
+  return spinnerFrame();
+}
+
+/** Short role label for a node kind. */
+export function kindLabel(kind: SubcallKind): string {
+  switch (kind) {
+    case "root":
+      return "RLM ▸ root";
+    case "rlm":
+      return "rlm_query";
+    case "batch":
+      return "llm_query×";
+    case "tool":
+      return "tool";
+    default:
+      return "llm_query";
+  }
+}
+
+export function formatCost(usd: number): string {
+  return `$${usd.toFixed(usd < 1 ? 4 : 2)}`;
+}
+
+export function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+export function formatDuration(ms: number): string {
+  const s = ms / 1000;
+  return s < 60 ? `${s.toFixed(1)}s` : `${Math.floor(s / 60)}m${Math.round(s % 60)}s`;
+}

package/src/util/concurrency.ts

@@ -0,0 +1,15 @@
+/** Fixed-size concurrency pool: run `fn` over `items` with at most `limit` in flight, preserving order. */
+export async function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, idx: number) => Promise<R>): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) return;
+      out[index] = await fn(items[index], index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  return out;
+}

package/src/util/errors.ts

@@ -0,0 +1,27 @@
+/** Shared result and error-string helpers. */
+
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export function ok<T, E = never>(value: T): Result<T, E> {
+  return { ok: true, value };
+}
+
+export function err<T = never, E = string>(error: E): Result<T, E> {
+  return { ok: false, error };
+}
+
+export const ERROR_PREFIX = "Error:";
+
+export function formatError(message: string): string {
+  return `${ERROR_PREFIX} ${message}`;
+}
+
+export function isErrorText(text: string): boolean {
+  return text.startsWith(`${ERROR_PREFIX} `);
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}