@hicaru/pi-rlm 0.3.6 → 0.3.8

package/src/prompts/system.ts

@@ -8,7 +8,7 @@ import type { ContextSizeStats } from "../text/tokens.ts";
 import {
   contextKindOf,
   DEFAULT_PROMPT_CAP,
-  ENV_TIPS,
+  envTips,
   howToRunCode,
   LARGE_FILE_RULE_LINES,
   promptCapTokensK,
@@ -33,23 +33,29 @@ export interface SystemPromptOptions {
   readonly child?: boolean;
   /** The recursion depth of this run (0 = root, 1 = first child, etc.). */
   readonly depth?: number;
+  /** v5 doctrine: the child sandbox has the delegation-only surface (no retrieval tools). */
+  readonly delegation?: boolean;
 }
 
-function orchestratorAddendum(maxPromptChars: number): string {
+function orchestratorAddendum(maxPromptChars: number, delegation: boolean): string {
   return [
     "As an RLM you are an **orchestrator, not a solver**. Probe `context`, plan decomposition, then",
     "fan out — do not solve multi-step module work yourself in a long chain of thought.",
     "",
     "<contract> llm_query / llm_batch / map_files / rlm_query / rlm_batch return Task (not the answer).",
-    "Only await_task returns content. Fire independent Tasks first, free search, then await_task.",
+    delegation
+      ? "Only await_task returns content. Fire independent Tasks first, slice your `context` meanwhile, then await_task."
+      : "Only await_task returns content. Fire independent Tasks first, free search, then await_task.",
     "Do not await after every independent spawn.</contract>",
     "",
     "<routing> one-shot facts → llm_query/llm_batch/map_files; one multi-step study → rlm_query;",
     "≥2 independent multi-step areas → rlm_batch (prefer over serial rlm_query). NEVER print file",
     "bodies into your own stream when a Task tool can read them.</routing>",
     "",
-    "Your own context window is small. Push long-context work into sub-calls. If free search/grep",
-    "already pins a tiny fact, use that. Aggregate small results in Python / `answers`.",
+    "Your own context window is small. Push long-context work into sub-calls.",
+    delegation
+      ? "If a slice of your `context` already pins a tiny fact, quote it — do not re-ask."
+      : "If free search/grep already pins a tiny fact, use that. Aggregate small results in Python / `answers`.",
     "",
     `Sub-call budget: (1) per-prompt < ${maxPromptChars.toLocaleString()} chars (≈${promptCapTokensK(maxPromptChars)}K tok);`,
     "(2) ~20 prompts per llm_batch. Fat prompts in small batches beat thousands of tiny prompts.",
@@ -78,13 +84,22 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
       `**Recursion depth: ${opts.depth}.** You are a sub-RLM — focus narrowly on your assigned`,
       "task. Delegate (rlm_query/rlm_batch) only if the task itself must decompose further.",
     );
+    if (opts.delegation ?? false) {
+      parts.push(
+        "",
+        "**REPL API (ONLY these):** llm_query / llm_batch / llm_query_chunked / map_files /",
+        "llm_map_reduce / rlm_query / rlm_batch / spawn / await_task / list_tasks / memory.* /",
+        "list_claims. There is no search/grep_context/outline here — your task arrived WITH its",
+        "world in `context`; slice it into llm prompts. rlm_query only for a disjoint path set.",
+      );
+    }
   }
   parts.push(
     "",
     howToRunCode(),
     "",
     replGlossary(
-      kind, recursion, opts.contextLoader ?? false, opts.child ?? false,
+      kind, recursion, opts.contextLoader ?? false, opts.child ?? false, opts.delegation ?? false,
     ),
     "",
     "REPL stdout over ~800 characters is truncated to a short excerpt — large results stay in your",
@@ -96,7 +111,7 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
   if (opts.orchestrator ?? true) {
     // Two counterweights, both required (paper App. B): the addendum bounds OVER-recursion
     // (batching/cost), ENV_TIPS bounds UNDER-recursion (solving it yourself).
-    parts.push("", orchestratorAddendum(maxPromptChars), "", ENV_TIPS);
+    parts.push("", orchestratorAddendum(maxPromptChars, opts.delegation ?? false), "", envTips(opts.delegation ?? false));
   }
   if (kind === "files") {
     parts.push("", LARGE_FILE_RULE_LINES.join("\n"));

package/src/prompts/user.ts

@@ -19,7 +19,10 @@ export function buildTurnPrompt(
   return `${prefix}${body}`;
 }
 
-/** Asked once when the engine runs out of turns without a submitted answer. */
+/** Asked once when the engine runs out of turns without a submitted answer. Same finalize
+ *  dialect as the budget wrap-up note (audit M6): answer-ready first, plain text only as an
+ *  explicit fallback the engine still accepts. */
 export const FINALIZE_PROMPT =
-  "You are out of turns. Provide your best final answer now based on everything you have gathered, " +
-  'by setting `answer["content"]` and `answer["ready"] = True` (fenced ```repl```), or as plain text.';
+  "You are out of turns. Finalize NOW: set `answer[\"content\"]` and `answer[\"ready\"] = True` " +
+    "(fenced ```repl```) with your best final answer from everything you have gathered. " +
+    "Only if the REPL is unavailable, answer as plain text.";

package/src/sandbox/interrupts.ts

@@ -51,6 +51,14 @@ export interface SubLlmHandlers {
   ): Promise<unknown>;
   finishTask(summary: string, depth: number, opts: SubcallOpts): Promise<unknown>;
   addContext(source: string, depth: number): Promise<AddContextResult>;
+  /** v5: the `[ledger]` claims table for the sandbox's `list_claims()` REPL call. */
+  ledgerClaims(): Promise<string>;
+  /** v5: durable memory surface for the sandbox's `memory.query/add/stats` object. */
+  memoryOp(
+    op: "query" | "add" | "stats",
+    args: { readonly query?: string; readonly k?: number; readonly content?: string; readonly paths?: readonly string[]; readonly tags?: readonly string[] },
+    depth: number,
+  ): Promise<string>;
 }
 
 function toStringArray(value: unknown): readonly string[] | undefined {
@@ -80,6 +88,8 @@ export const REJECT: SubLlmHandlers = Object.freeze({
   addContext: async () => {
     throw new Error("add_context not configured");
   },
+  ledgerClaims: async () => UNCONFIGURED,
+  memoryOp: async () => UNCONFIGURED,
 });
 
 export interface ReplyBody {
@@ -337,6 +347,20 @@ export async function serviceInterrupt(
         });
         return;
       }
+      case "ledger_claims": {
+        const table = await h.ledgerClaims();
+        reply(msg.rid, { response: table });
+        return;
+      }
+      case "memory": {
+        const out = await h.memoryOp(
+          msg.op,
+          { query: msg.query, k: msg.k, content: msg.content, paths: msg.paths, tags: msg.tags },
+          d,
+        );
+        reply(msg.rid, { response: out });
+        return;
+      }
       default: {
         const _exhaustive: never = msg;
         reply((_exhaustive as WorkerInterrupt).rid, {

package/src/sandbox/protocol.ts

@@ -2,7 +2,7 @@
  * Wire protocol for the RLM Python sandbox.
  *
  * Newline-delimited JSON over the worker's stdin/stdout — no sockets, no HTTP.
- * Parent -> worker: requests (exec/load_context/shutdown) and llm replies.
+ * Parent -> worker: requests (exec/load_context/shutdown), llm replies, and heartbeats.
  * Worker -> parent: request responses and mid-exec sub-LLM interrupts.
  *
  * Canonical api_v5 kinds only — no legacy `*_query_batched` wire names.
@@ -44,7 +44,12 @@ export interface LlmReply {
   readonly error?: string;
 }
 
-export type ParentMessage = WorkerRequest | LlmReply;
+/** Keep-alive while the host is working and has nothing else to write. */
+export interface Heartbeat {
+  readonly type: "heartbeat";
+}
+
+export type ParentMessage = WorkerRequest | LlmReply | Heartbeat;
 
 /** A normal response to a request (keyed by the request `id`). */
 export interface WorkerResponse {
@@ -60,11 +65,13 @@ export interface WorkerResponse {
   readonly execution_time?: number;
   // user-created variable names after this exec
   readonly var_names?: readonly string[];
+  /** Unsettled Task handles still in the worker (native pending-line / await-all). */
+  readonly pending_tasks?: readonly PendingTaskInfo[];
   // load_context:
   readonly index?: number;
 }
 
-/** Canonical interrupt kinds (api_v5). */
+/** Canonical interrupt kinds (api_v5 + v5 ledger + memory). */
 export type InterruptKind =
   | "llm_query"
   | "rlm_query"
@@ -72,7 +79,9 @@ export type InterruptKind =
   | "rlm_batch"
   | "await"
   | "finish"
-  | "add_context";
+  | "add_context"
+  | "ledger_claims"
+  | "memory";
 
 interface InterruptBase {
   readonly rid: string;
@@ -114,13 +123,31 @@ export interface AddContextInterrupt extends InterruptBase {
   readonly source?: string;
 }
 
+/** v5: sandbox asks the host for the TaskLedger claims table (`list_claims()`). */
+export interface LedgerClaimsInterrupt extends InterruptBase {
+  readonly type: "ledger_claims";
+}
+
+/** v5: sandbox reaches the durable MemoryStore (`memory.query/add/stats`). */
+export interface MemoryInterrupt extends InterruptBase {
+  readonly type: "memory";
+  readonly op: "query" | "add" | "stats";
+  readonly query?: string;
+  readonly k?: number;
+  readonly content?: string;
+  readonly paths?: readonly string[];
+  readonly tags?: readonly string[];
+}
+
 /** A mid-exec sub-LLM/tool request from the worker. */
 export type WorkerInterrupt =
   | PromptInterrupt
   | BatchInterrupt
   | AwaitInterrupt
   | FinishInterrupt
-  | AddContextInterrupt;
+  | AddContextInterrupt
+  | LedgerClaimsInterrupt
+  | MemoryInterrupt;
 
 export type WorkerMessage = WorkerResponse | WorkerInterrupt;
 
@@ -133,6 +160,8 @@ export const INTERRUPT_KINDS = Object.freeze(
     "await",
     "finish",
     "add_context",
+    "ledger_claims",
+    "memory",
   ]),
 );
 
@@ -158,6 +187,39 @@ export function isWorkerMessage(msg: unknown): msg is WorkerMessage {
   return isWorkerResponse(msg) || isInterrupt(msg);
 }
 
+/** Unsettled Task still in the worker, optionally bound to a REPL variable. */
+export interface PendingTaskInfo {
+  readonly var: string | null;
+  readonly kind: string;
+  readonly label: string;
+}
+
+const EMPTY_PENDING: readonly PendingTaskInfo[] = Object.freeze([]);
+
+function isPendingTaskInfo(value: unknown): value is PendingTaskInfo {
+  if (!isRecord(value)) return false;
+  const bound = value["var"];
+  return (typeof bound === "string" || bound === null)
+    && typeof value["kind"] === "string"
+    && typeof value["label"] === "string";
+}
+
+/** Narrow a worker `pending_tasks` payload; drop malformed entries. */
+export function parsePendingTasks(value: unknown): readonly PendingTaskInfo[] {
+  if (!Array.isArray(value)) return EMPTY_PENDING;
+  const out = new Array<PendingTaskInfo>(value.length);
+  let n = 0;
+  for (let i = 0; i < value.length; i++) {
+    const item: unknown = value[i];
+    if (isPendingTaskInfo(item)) {
+      out[n] = item;
+      n += 1;
+    }
+  }
+  out.length = n;
+  return n === 0 ? EMPTY_PENDING : Object.freeze(out);
+}
+
 /** Result of a single `repl` block execution, surfaced to the engine/tool. */
 export interface ReplResult {
   readonly stdout: string;
@@ -168,4 +230,6 @@ export interface ReplResult {
   readonly executionTimeMs: number;
   /** User-created variable names after this exec (builtins/context filtered out). */
   readonly varNames: readonly string[];
+  /** Unsettled Task handles still in the worker after this exec. */
+  readonly pendingTasks: readonly PendingTaskInfo[];
 }

package/src/sandbox/py/guards.py

@@ -91,12 +91,12 @@ RESERVED = frozenset(
         # Canonical api_v5
         "llm_query", "llm_batch",
         "rlm_query", "rlm_batch",
-        "await_task", "finish",
+        "await_task", "list_tasks", "finish",
         "spawn",
         # Helpers (not the old *_query_batched API)
         "llm_query_chunked", "map_files", "llm_map_reduce",
         "search", "grep_context", "outline",
-        "add_context",
+        "add_context", "list_claims", "memory",
         "SHOW_VARS", "answer", "context",
     }
 )
@@ -114,6 +114,14 @@ class _StallTimeout(Exception):
     """No frame from the host while a sub-call was pending."""
 
 
+def _stall_message(stall_timeout_s: float) -> str:
+    """Contract text for a stall — raised internally, returned as Error: … to the model."""
+    return (
+        f"sub-call still running — no reply from the host for {stall_timeout_s:g}s; "
+        "await_task it again in a later block"
+    )
+
+
 @contextmanager
 def _stall_alarm(exec_timeout_s: float, stall_timeout_s: float):
     """Swap the per-cell alarm for a stall alarm while blocked on the parent.
@@ -127,10 +135,7 @@ def _stall_alarm(exec_timeout_s: float, stall_timeout_s: float):
     remaining = signal.getitimer(signal.ITIMER_REAL)[0] if (use and exec_timeout_s > 0) else 0.0
 
     def _fire(signum, frame):  # noqa: ARG001
-        raise _StallTimeout(
-            f"sub-call stalled — no reply from the host for {stall_timeout_s:g}s "
-            "(the task may still be running; await_task it again in a later block)"
-        )
+        raise _StallTimeout(_stall_message(stall_timeout_s))
 
     old = signal.signal(signal.SIGALRM, _fire) if use else None