@hicaru/pi-rlm 0.2.0 → 0.2.2

package/src/tool/background-tasks.ts

@@ -0,0 +1,95 @@
+/**
+ * Session-scoped home for detached `spawn()` work in native repl() mode.
+ *
+ * A spawned sub-call may settle after the repl() call that started it has returned, when
+ * that turn's RlmEmitter has been shut down and its LimitGuard discarded. Both live here for
+ * the whole session instead. The turn that awaits a task — or simply the next turn to run —
+ * adopts its settled subtree into its own ReplDetails, so background spend is reported even
+ * when the model never collects the result.
+ *
+ * The headless engine needs none of this: its emitter and guard already outlive every
+ * sub-call it services (see core/engine.ts).
+ */
+
+import { RlmEmitter } from "./rlm-events.ts";
+import { SubcallStore, type SubcallTotals } from "./subcall-store.ts";
+import type { RlmSubcall } from "./rlm-details.ts";
+import { LimitGuard, type Limits } from "../core/limits.ts";
+import type { Invocation } from "../bridge/subcall-handlers.ts";
+import { trace, traceEnabled } from "../util/trace.ts";
+
+/** What a drain hands to the turn that is reporting it. */
+export interface BackgroundDrain {
+  readonly subcalls: readonly RlmSubcall[];
+  readonly totals: SubcallTotals;
+}
+
+export class BackgroundTasks {
+  /** "bg" prefix so these IDs can never collide with a turn emitter's `s1, s2, …`. */
+  private readonly _emitter = new RlmEmitter("bg");
+  private readonly store = new SubcallStore(this._emitter);
+  private readonly limits: LimitGuard;
+  private active = 0;
+
+  constructor(limits: Limits) {
+    this.limits = new LimitGuard(limits);
+  }
+
+  /** Read-only access for the progressive tracer (scope "background"). */
+  get emitter(): RlmEmitter {
+    return this._emitter;
+  }
+
+  /** The Invocation detached sub-calls resolve to. Stable for the session. */
+  get invocation(): Invocation {
+    return {
+      emitter: this._emitter,
+      parentId: undefined,
+      depth: 0,
+      limits: this.limits,
+    };
+  }
+
+  /** Detached sub-calls still in flight. The single pending counter for the session. */
+  get pending(): number {
+    return this.active;
+  }
+
+  /** Live snapshot of detached sub-calls, settled or not — progressive rendering only. */
+  liveSubcalls(): readonly RlmSubcall[] {
+    return this.store.getSubcalls();
+  }
+
+  /** Live totals for that same snapshot. Accounting still flows through `drain()`. */
+  liveTotals(): SubcallTotals {
+    return this.store.getTotals();
+  }
+
+  /** Count `run` as in-flight detached work for its duration. */
+  async track<T>(run: () => Promise<T>): Promise<T> {
+    this.active += 1;
+    const startedAt = Date.now();
+    if (traceEnabled) trace("bg.start", { pending: this.active });
+    try {
+      return await run();
+    } finally {
+      this.active -= 1;
+      if (traceEnabled) trace("bg.settle", { pending: this.active, durationMs: Date.now() - startedAt });
+    }
+  }
+
+  /**
+   * Hand over every fully-settled subtree and forget it.
+   *
+   * Called at the end of every repl() call, not only when a task was awaited, so a spawn
+   * the model never collects still reaches the user's cost totals.
+   */
+  drain(): BackgroundDrain {
+    return this.store.takeSettledSubtrees();
+  }
+
+  dispose(): void {
+    this.store.dispose();
+    this._emitter.shutdown();
+  }
+}

package/src/tool/repl-details.ts

@@ -2,7 +2,7 @@
  * ReplDetails — structured payload for the repl() tool's AgentToolResult<T>.
  *
  * Mirrors RlmDetails but scoped to a single code execution. Sub-calls (llm_query,
- * rlm_query, todo, ask_user_question) triggered during sandbox execution are
+ * rlm_query, load_library) triggered during sandbox execution are
  * accumulated into the subcalls array for tree rendering.
  */
 
@@ -16,12 +16,14 @@ export interface ReplDetails {
   readonly stderr: string;
   /** Wall-clock execution time in milliseconds. */
   readonly executionTimeMs: number;
-  /** Sub-calls triggered during this execution (llm_query, rlm_query, todo, etc.). */
+  /** Sub-calls triggered during this execution (llm_query, rlm_query, etc.). */
   readonly subcalls: readonly RlmSubcall[];
   /** Running totals for this repl() call (cost + tokens from sub-LLM calls). */
   readonly totals: { readonly costUsd: number; readonly tokens: number };
   /** Final answer submitted through answer["ready"] without echoing it to the model. */
   readonly finalAnswer?: string;
+  /** Detached spawn() sub-calls still running when this call returned. Absent when none. */
+  readonly backgroundPending?: number;
   /** Advisory diagnostics — surfaced to the user, never a failure. */
   readonly warnings?: readonly string[];
 }

package/src/tool/repl-render.ts

@@ -0,0 +1,58 @@
+/** repl() tool TUI views — collapsed one-liner card and the expanded output/sub-call tree. */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import type { ReplDetails } from "./repl-details.ts";
+import { cardHeader, cardStatsLine, renderCollapsedCard, renderExpandedSubcallTree } from "./subcall-render.ts";
+
+/** Chars of stdout/stderr shown in the expanded view. */
+const EXPANDED_STDOUT_CHARS = 2_000;
+const EXPANDED_STDERR_CHARS = 500;
+
+// ── Collapsed view ──
+
+export function replStats(details: ReplDetails, theme: Theme): string {
+  const elapsed = details.executionTimeMs > 0 ? `${details.executionTimeMs}ms` : undefined;
+  return cardStatsLine(details.totals, theme, elapsed, details.backgroundPending);
+}
+
+export function renderReplCollapsed(details: ReplDetails, theme: Theme): Text {
+  return renderCollapsedCard("REPL", details.status, replStats(details, theme), details.subcalls, theme);
+}
+
+// ── Expanded view ──
+
+export function renderReplExpanded(details: ReplDetails, theme: Theme): Container {
+  const container = new Container();
+
+  container.addChild(new Text(cardHeader("REPL", details.status, replStats(details, theme), theme), 0, 0));
+
+  // Output
+  if (details.output) {
+    container.addChild(new Spacer(1));
+    const out = details.output.length > EXPANDED_STDOUT_CHARS
+      ? `${details.output.slice(0, EXPANDED_STDOUT_CHARS)}…`
+      : details.output;
+    container.addChild(new Text(out, 0, 0));
+  }
+
+  if (details.warnings && details.warnings.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", details.warnings.join("\n")), 0, 0));
+  }
+
+  // Stderr
+  if (details.stderr) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("error", details.stderr.slice(0, EXPANDED_STDERR_CHARS)), 0, 0));
+  }
+
+  // Sub-call tree
+  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));
+  }
+
+  return container;
+}

package/src/tool/repl-result.ts

@@ -0,0 +1,70 @@
+/**
+ * Model-visible text assembly for a repl() result, plus the advisory diagnostics derived from
+ * its sub-calls. Split out of repl-tool.ts: this is pure string/array work with no sandbox,
+ * emitter, or TUI dependency, and both halves are asserted directly by test/phase-guards.ts.
+ */
+
+import type { RlmSubcall } from "./rlm-details.ts";
+import { capReplResultText, replDelegationNudge } from "../mode/native-guards.ts";
+
+/** Model-visible text assembled from a repl() result. */
+export interface ReplResultText {
+  readonly text: string;
+}
+
+/**
+ * Assemble the model-visible text for a repl() result: cap stdout, append a zero-subcall
+ * delegation nudge when a bulk read went undelegated, and report tasks still running.
+ *
+ * The pending line is the model's only signal that `spawn()`ed work is outstanding — without
+ * it a model that spawned and moved on has no way to know it should still collect.
+ *
+ * `varNames` covers the opposite failure: a block that stores its results in `answers` and
+ * prints nothing reads as a bare "(no output)", so the model concludes the block did nothing
+ * and re-runs it — paying twice for the same sub-calls. The headless engine already answers
+ * this with the same hint (core/answer.ts); native mode was the only path missing it.
+ */
+export function buildReplResultText(
+  stdout: string,
+  finalAnswer: string | undefined,
+  subcalls: readonly RlmSubcall[],
+  backgroundPending = 0,
+  varNames: readonly string[] = [],
+): ReplResultText {
+  const answerSubmitted = finalAnswer !== undefined;
+  const noOutput = !answerSubmitted && !stdout;
+  const varsHint = noOutput && varNames.length > 0
+    ? ` — the block ran fine and these REPL vars are defined: ${varNames.join(", ")}. `
+      + "Do NOT re-run it; read them in the next block."
+    : "";
+  const rawText = answerSubmitted
+    ? `ANSWER_SUBMITTED (${finalAnswer.length} chars) — delivered to user. Do not restate it.`
+    : stdout || `(no output)${varsHint}`;
+  // Model-visible text is capped; the caller keeps full stdout in `details` for the TUI.
+  const cappedText = capReplResultText(rawText) ?? rawText;
+  const delegated = subcalls.some((s) => s.kind === "llm" || s.kind === "batch" || s.kind === "rlm");
+  const nudge = answerSubmitted ? undefined : replDelegationNudge(rawText.length, delegated);
+  const failedBg = subcalls.filter((s) => s.id.startsWith("bg") && s.status === "error").length;
+  const pendingLine = backgroundPending > 0
+    ? `\n\n[rlm] ${backgroundPending} background task(s) still running — rlm_await_all(tasks) to collect.`
+    : "";
+  const failedLine = failedBg > 0
+    ? `\n[rlm] ${failedBg} background sub-call(s) FAILED — their rlm_await value is an "Error: …" string, not data.`
+    : "";
+  return { text: cappedText + (nudge ?? "") + pendingLine + failedLine };
+}
+
+/** Advisory diagnostics derived from a completed invocation's sub-calls. */
+export function collectReplWarnings(subcalls: readonly RlmSubcall[]): readonly string[] | undefined {
+  let failed = 0;
+  let total = 0;
+  for (let i = 0; i < subcalls.length; i++) {
+    const call = subcalls[i];
+    if (call.status !== "error") continue;
+    // A batch subcall stands for many prompts; a single call stands for one.
+    failed += call.failedCount ?? 1;
+    total += call.totalCount ?? 1;
+  }
+  if (failed === 0) return undefined;
+  return Object.freeze([`${failed}/${total} sub-call(s) failed — results may be incomplete`]);
+}