@hicaru/pi-rlm 0.3.1 → 0.3.3

package/src/bridge/handlers/emitting.ts

@@ -0,0 +1,104 @@
+/**
+ * emitting() — the single emit-pattern helper for leaf sub-calls.
+ *
+ * AGENTS.md DRY #5: every leaf subcall follows create-node → execute → update.
+ * rlm_query childRun emits its own node; do not wrap childRun in emitting.
+ */
+
+import type { Usage } from "@earendil-works/pi-ai";
+import { isErrorText } from "../../util/errors.ts";
+import { previewText } from "../../text/preview.ts";
+import type { Invocation } from "./types.ts";
+
+export interface EmitOpts {
+  readonly kind: "llm" | "batch";
+  readonly label: string;
+  readonly args: string;
+  readonly model?: string;
+}
+
+export interface EmitSummary {
+  readonly preview: string;
+  readonly error?: string;
+  readonly failed?: number;
+  readonly total?: number;
+}
+
+/**
+ * Create a subcall node, run `fn`, then update the node with status/cost/preview.
+ * `fn` should not throw for soft failures (prefer Error: strings). Hard throws mark error.
+ */
+export async function emitting<T>(
+  inv: Invocation,
+  opts: EmitOpts,
+  fn: (track: (usage: Usage) => void) => Promise<T>,
+  summarize: (out: T) => EmitSummary,
+): Promise<T> {
+  const id = inv.emitter.emitSubcallCreated({
+    kind: opts.kind,
+    parentId: inv.parentId,
+    label: opts.label,
+    model: opts.model,
+    args: opts.args,
+    depth: inv.depth,
+  });
+
+  let costUsd = 0;
+  let tokens = 0;
+  const track = (u: Usage): void => {
+    costUsd += u.cost.total;
+    tokens += u.totalTokens;
+  };
+
+  try {
+    const out = await fn(track);
+    const summary = summarize(out);
+    inv.emitter.emitSubcallUpdated({
+      id,
+      status: summary.error !== undefined ? "error" : "done",
+      resultPreview: summary.preview,
+      costUsd,
+      tokens,
+      detail: summary.error,
+      failedCount: summary.failed,
+      totalCount: summary.total,
+    });
+    return out;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    inv.emitter.emitSubcallUpdated({
+      id,
+      status: "error",
+      resultPreview: msg,
+      costUsd,
+      tokens,
+      detail: msg,
+    });
+    throw err;
+  }
+}
+
+/** Summarize a batch result for the emitter. */
+export function summarizeBatch(out: readonly string[]): EmitSummary {
+  let failed = 0;
+  let firstError: string | undefined;
+  for (const s of out) {
+    if (isErrorText(s)) {
+      failed += 1;
+      firstError ??= s;
+    }
+  }
+  const first = previewText(out[0] ?? "");
+  const error =
+    failed === 0
+      ? undefined
+      : failed === out.length
+        ? `all ${out.length} sub-calls failed — reduce batch size or try llm_query individually`
+        : `${failed}/${out.length} sub-calls failed`;
+  return {
+    preview: out.length > 1 ? `${first}  (+${out.length - 1} more)` : first,
+    error: error ?? firstError,
+    failed,
+    total: out.length,
+  };
+}

package/src/bridge/handlers/finish.ts

@@ -0,0 +1,45 @@
+/**
+ * finish handler — contract boundary: the model signals completion.
+ *
+ * Soft policy (default): returns finished=true always. If tasks are still pending,
+ * includes `warning` listing unawaited task_ids — does **not** auto-drain results
+ * into the summary (that would hide model mistakes). Callers may refuse to stop
+ * when warning is set.
+ */
+
+import type { FinishResult, SubcallHandlerDeps } from "./types.ts";
+import type { SubcallOpts } from "../../sandbox/interrupts.ts";
+import type { AwaitDeps } from "./task-registry.ts";
+
+export function createFinishHandler(
+  deps: SubcallHandlerDeps,
+  ad?: AwaitDeps,
+) {
+  return async (
+    summary: string,
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<FinishResult & { readonly summary?: string; readonly warning?: string }> => {
+    const inv = deps.resolve(opts, depth);
+    const pending = ad?.unawaitedIds() ?? [];
+    const warning =
+      pending.length > 0
+        ? `finish called with unawaited tasks: ${pending.join(", ")}`
+        : undefined;
+
+    if (inv !== null) {
+      inv.emitter.emitSubcallUpdated?.({
+        id: inv.parentId ?? "root",
+        status: "done",
+        detail: warning ?? "finish called",
+      });
+    }
+
+    return {
+      ok: true,
+      finished: true,
+      summary: summary.length > 0 ? summary : undefined,
+      warning,
+    };
+  };
+}

package/src/bridge/handlers/index.ts

@@ -0,0 +1,48 @@
+/**
+ * createSubcallHandlers — assembles the complete async-by-default handler set.
+ *
+ * This is the ONE place where subcall handlers are wired together. The engine
+ * and repl() tool both call this with their own resolve + trackDetached.
+ *
+ * Task identity lives in TaskRegistry (one implementation). Pass an optional
+ * registry to share session state; otherwise a fresh registry is created.
+ */
+
+import { createLlmQueryHandler, createLlmBatchHandler } from "./llm-query.ts";
+import { createRlmQueryHandler, createRlmBatchHandler } from "./rlm-query.ts";
+import { createAwaitHandler } from "./await.ts";
+import { createFinishHandler } from "./finish.ts";
+import { createTaskRegistry, type TaskRegistry } from "./task-registry.ts";
+import type { SubcallHandlerDeps, SubcallHandlers } from "./types.ts";
+
+export function createSubcallHandlers(
+  deps: SubcallHandlerDeps,
+  registry: TaskRegistry = createTaskRegistry(),
+): SubcallHandlers {
+  // Do NOT call getLlmModel() here — recursion-only tests leave leaf models unwired
+  // and throw if resolved at construction. complete1 reads getLlmModel lazily per call.
+  return {
+    llmQuery: createLlmQueryHandler(deps, registry.spawnDeps),
+    llmBatch: createLlmBatchHandler(deps, registry.spawnDeps),
+    rlmQuery: createRlmQueryHandler(deps, registry.spawnDeps),
+    rlmBatch: createRlmBatchHandler(deps, registry.spawnDeps),
+    awaitTask: createAwaitHandler(deps, registry.awaitDeps),
+    finishTask: createFinishHandler(deps, registry.awaitDeps),
+  };
+}
+
+export type {
+  SubcallHandlerDeps,
+  SubcallHandlers,
+  SpawnResult,
+  AwaitResult,
+  FinishResult,
+  Invocation,
+  InvocationLimits,
+  SubcallConfig,
+} from "./types.ts";
+
+export { limitsFromRemaining } from "./types.ts";
+export { summarizeBatch } from "./emitting.ts";
+export { createTaskRegistry, SPAWN_HINT } from "./task-registry.ts";
+export type { TaskRegistry, SpawnDeps, AwaitDeps } from "./task-registry.ts";

package/src/bridge/handlers/llm-query.ts

@@ -0,0 +1,130 @@
+/**
+ * llm_query and llm_batch handlers — async-by-default spawn pattern.
+ */
+
+import type { Usage } from "@earendil-works/pi-ai";
+import { modelRef } from "../../config/settings.ts";
+import { complete1, type Complete1Deps } from "./completion.ts";
+import { emitting, summarizeBatch } from "./emitting.ts";
+import { formatError, isErrorText } from "../../util/errors.ts";
+import { previewText } from "../../text/preview.ts";
+import type { SpawnResult, SubcallHandlerDeps } from "./types.ts";
+import type { SubcallOpts } from "../../sandbox/interrupts.ts";
+import { SPAWN_HINT, spawnAndRun, type SpawnDeps } from "./task-registry.ts";
+
+const UNWIRED = formatError("RLM bridge not wired for this invocation");
+
+function completeDeps(deps: SubcallHandlerDeps): Complete1Deps {
+  return {
+    leafGate: deps.gates.leaf,
+    registry: deps.registry,
+    getLlmModel: deps.getLlmModel,
+    getConfig: deps.getConfig,
+    signal: deps.signal,
+    onUsage: deps.onUsage,
+  };
+}
+
+function displayModel(deps: SubcallHandlerDeps): string | undefined {
+  try {
+    const m = deps.getLlmModel();
+    return modelRef(m) ?? m.id;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createLlmQueryHandler(
+  deps: SubcallHandlerDeps,
+  sd: SpawnDeps,
+) {
+  return async (
+    prompt: string,
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<SpawnResult> => {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) {
+      return {
+        ok: false,
+        task_id: null,
+        kind: "llm",
+        n: 1,
+        status: "pending",
+        hint: SPAWN_HINT,
+        error: UNWIRED,
+      };
+    }
+
+    const cdeps = completeDeps(deps);
+    return spawnAndRun(
+      sd,
+      "llm",
+      1,
+      () =>
+        emitting(
+          inv,
+          {
+            kind: "llm",
+            label: "llm_query",
+            args: `prompt: ${previewText(prompt)}`,
+            model: displayModel(deps),
+          },
+          (track: (u: Usage) => void) => complete1(inv, prompt, track, cdeps),
+          (out) => ({
+            preview: previewText(out),
+            error: isErrorText(out) ? out : undefined,
+          }),
+        ),
+      deps.trackDetached,
+      opts.detached,
+    );
+  };
+}
+
+export function createLlmBatchHandler(
+  deps: SubcallHandlerDeps,
+  sd: SpawnDeps,
+) {
+  return async (
+    prompts: readonly string[],
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<SpawnResult> => {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) {
+      return {
+        ok: false,
+        task_id: null,
+        kind: "llm_batch",
+        n: prompts.length,
+        status: "pending",
+        hint: SPAWN_HINT,
+        error: UNWIRED,
+      };
+    }
+
+    const cdeps = completeDeps(deps);
+    return spawnAndRun(
+      sd,
+      "llm_batch",
+      prompts.length,
+      () =>
+        emitting(
+          inv,
+          {
+            kind: "batch",
+            label: `llm_batch ×${prompts.length}`,
+            args: `prompt: ${previewText(prompts[0] ?? "")}`,
+            model: displayModel(deps),
+          },
+          // NO outer gate — complete1 takes the single leaf slot per prompt.
+          (track: (u: Usage) => void) =>
+            Promise.all(prompts.map((p) => complete1(inv, p, track, cdeps))),
+          summarizeBatch,
+        ),
+      deps.trackDetached,
+      opts.detached,
+    );
+  };
+}

package/src/bridge/handlers/rlm-query.ts

@@ -0,0 +1,227 @@
+/**
+ * rlm_query and rlm_batch handlers — async-by-default spawn pattern.
+ *
+ * AGENTS.md DRY #2: childRun exists once, here.
+ */
+
+import { modelRef } from "../../config/settings.ts";
+import { errorMessage, formatError } from "../../util/errors.ts";
+import { filterContextByPaths } from "../../context/merge.ts";
+import { previewText } from "../../text/preview.ts";
+import type { RlmInput, RlmResult } from "../../core/types.ts";
+import { checkResourceLimits } from "../../core/resource-limits.ts";
+import type { Invocation, SpawnResult, SubcallHandlerDeps } from "./types.ts";
+import type { SubcallOpts } from "../../sandbox/interrupts.ts";
+import { SPAWN_HINT, spawnAndRun, type SpawnDeps } from "./task-registry.ts";
+import { complete1, type Complete1Deps } from "./completion.ts";
+
+const UNWIRED = formatError("RLM bridge not wired for this invocation");
+const NO_UNMATCHED: readonly string[] = Object.freeze([]);
+
+function emptyResult(answer: string): RlmResult {
+  return {
+    answer,
+    iterations: 0,
+    costUsd: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    durationMs: 0,
+  };
+}
+
+interface ChildContext {
+  readonly context: unknown;
+  readonly unmatched: readonly string[];
+}
+
+function childContextFor(
+  deps: SubcallHandlerDeps,
+  prompt: string,
+  paths: readonly string[] | undefined,
+): ChildContext {
+  const inherited = deps.getChildContext?.();
+  if (inherited === undefined || inherited === null) {
+    return Object.freeze({ context: prompt, unmatched: NO_UNMATCHED });
+  }
+  if (paths === undefined || paths.length === 0) {
+    return Object.freeze({ context: inherited, unmatched: NO_UNMATCHED });
+  }
+  const filtered = filterContextByPaths(inherited, paths);
+  return Object.freeze({
+    context: filtered.files.length > 0 ? filtered.files : inherited,
+    unmatched: filtered.unmatched,
+  });
+}
+
+function completeDeps(deps: SubcallHandlerDeps): Complete1Deps {
+  return {
+    leafGate: deps.gates.leaf,
+    registry: deps.registry,
+    getLlmModel: deps.getLlmModel,
+    getConfig: deps.getConfig,
+    signal: deps.signal,
+    onUsage: deps.onUsage,
+  };
+}
+
+/**
+ * One child RLM run: depth cap → resource guard → depth gate → spawn engine → debit parent.
+ * Emits its own subcall node (do not wrap in emitting()).
+ */
+async function childRun(
+  deps: SubcallHandlerDeps,
+  inv: Invocation,
+  prompt: string,
+  paths: readonly string[] | undefined,
+): Promise<RlmResult> {
+  const childDepth = inv.depth + 1;
+  const run = deps.runChild;
+  const maxDepth = deps.getConfig().maxDepth;
+
+  if (run === undefined || childDepth >= maxDepth) {
+    const degrade = deps.degrade;
+    const answer =
+      degrade !== undefined
+        ? await degrade(prompt, inv.depth)
+        : await complete1(inv, prompt, () => {}, completeDeps(deps));
+    return emptyResult(answer);
+  }
+
+  const remTimeout = inv.limits.remainingTimeoutMs();
+  const limitError = checkResourceLimits({ timeoutMs: remTimeout });
+  if (limitError !== undefined) return emptyResult(limitError);
+
+  const rootModel = deps.getModel?.();
+  const modelLabel =
+    rootModel === undefined ? undefined : (modelRef(rootModel) ?? rootModel.id);
+  const subId = inv.emitter.emitSubcallCreated({
+    kind: "rlm",
+    parentId: inv.parentId,
+    label: "rlm_query",
+    model: modelLabel,
+    detail: prompt.slice(0, 60),
+    depth: childDepth,
+  });
+
+  const child = childContextFor(deps, prompt, paths);
+  const rootPrompt =
+    child.unmatched.length === 0
+      ? prompt
+      : `${prompt}\n\n[rlm] paths=${child.unmatched.join(", ")} matched no files; you received the full context.`;
+
+  const input: RlmInput = {
+    rootPrompt,
+    context: child.context,
+    depth: childDepth,
+    parentNodeId: subId,
+    remainingTimeoutMs: remTimeout,
+  };
+
+  try {
+    const res = await deps.gates.rlm.at(childDepth).run(() => run(input, inv));
+    inv.limits.addRaw(res.costUsd, res.inputTokens, res.outputTokens);
+    deps.onChildUsage?.(res.costUsd, res.inputTokens, res.outputTokens);
+    inv.emitter.emitSubcallUpdated({
+      id: subId,
+      status: "done",
+      resultPreview: res.answer.slice(0, 200),
+    });
+    return res;
+  } catch (err: unknown) {
+    const msg = errorMessage(err);
+    inv.emitter.emitSubcallUpdated({ id: subId, status: "error", detail: msg });
+    return emptyResult(formatError(`child RLM failed - ${msg}`));
+  }
+}
+
+export function createRlmQueryHandler(deps: SubcallHandlerDeps, sd: SpawnDeps) {
+  return async (
+    task: string,
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<SpawnResult> => {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) {
+      return {
+        ok: false,
+        task_id: null,
+        kind: "rlm",
+        n: 1,
+        status: "pending",
+        hint: SPAWN_HINT,
+        error: UNWIRED,
+      };
+    }
+
+    const pathArg = opts.paths;
+
+    return spawnAndRun(
+      sd,
+      "rlm",
+      1,
+      async () => {
+        const r = await childRun(deps, inv, task, pathArg);
+        return r.answer;
+      },
+      deps.trackDetached,
+      opts.detached,
+    );
+  };
+}
+
+export function createRlmBatchHandler(deps: SubcallHandlerDeps, sd: SpawnDeps) {
+  return async (
+    tasks: readonly string[],
+    depth: number,
+    opts: SubcallOpts,
+  ): Promise<SpawnResult> => {
+    const inv = deps.resolve(opts, depth);
+    if (inv === null) {
+      return {
+        ok: false,
+        task_id: null,
+        kind: "rlm_batch",
+        n: tasks.length,
+        status: "pending",
+        hint: SPAWN_HINT,
+        error: UNWIRED,
+      };
+    }
+
+    const pathArg = opts.paths;
+    const id = inv.emitter.emitSubcallCreated({
+      kind: "batch",
+      parentId: inv.parentId,
+      label: `rlm_batch ×${tasks.length}`,
+      args: previewText(tasks[0] ?? ""),
+      depth: inv.depth,
+    });
+
+    return spawnAndRun(
+      sd,
+      "rlm_batch",
+      tasks.length,
+      async () => {
+        try {
+          const results = await Promise.all(
+            tasks.map((t) => childRun(deps, inv, t, pathArg)),
+          );
+          const answers = results.map((r) => r.answer);
+          inv.emitter.emitSubcallUpdated({
+            id,
+            status: "done",
+            resultPreview: previewText(answers[0] ?? ""),
+            totalCount: answers.length,
+          });
+          return answers;
+        } catch (err: unknown) {
+          const msg = errorMessage(err);
+          inv.emitter.emitSubcallUpdated({ id, status: "error", detail: msg });
+          throw err;
+        }
+      },
+      deps.trackDetached,
+      opts.detached,
+    );
+  };
+}