@pi-unipi/unipi 2.5.0 → 2.6.0

package/packages/core/bounded-output.ts

@@ -0,0 +1,106 @@
+import { chmodSync, lstatSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const DEFAULT_MODEL_OUTPUT_BYTES = 64 * 1024;
+export const MAX_RAW_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+export interface BoundedOutput {
+  text: string;
+  truncated: boolean;
+  originalBytes: number;
+  visibleBytes: number;
+  artifactPath?: string;
+}
+
+export interface BoundOutputOptions {
+  maxBytes?: number;
+  artifactPrefix?: string;
+  artifactDir?: string;
+}
+
+function byteSlice(text: string, start: number, end?: number): string {
+  return Buffer.from(text, "utf8").subarray(start, end).toString("utf8").replace(/\uFFFD+$/u, "");
+}
+
+function secureArtifactDir(customDir?: string): string {
+  const dir = customDir ?? join(homedir(), ".unipi", "tool-results");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  let stat = lstatSync(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`Refusing unsafe tool-result directory: ${dir}`);
+  }
+  if ((stat.mode & 0o077) !== 0) {
+    chmodSync(dir, 0o700);
+    stat = lstatSync(dir);
+    if ((stat.mode & 0o077) !== 0) {
+      throw new Error(`Refusing non-private tool-result directory: ${dir}`);
+    }
+  }
+  return dir;
+}
+
+function safePrefix(prefix: string): string {
+  const safe = prefix.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").slice(0, 48);
+  return safe || "tool-result";
+}
+
+/**
+ * Bound model-visible UTF-8 output and, up to the raw artifact safety cap,
+ * preserve the complete text in a private local artifact.
+ *
+ * Artifacts use random names and mode 0600 beneath a mode-0700 directory. The
+ * returned path is intentionally explicit so the agent can retrieve it with
+ * the ordinary read tool only when full output is actually needed.
+ */
+export function boundModelOutput(text: string, options: BoundOutputOptions = {}): BoundedOutput {
+  const maxBytes = Math.max(1024, Math.floor(options.maxBytes ?? DEFAULT_MODEL_OUTPUT_BYTES));
+  const originalBytes = Buffer.byteLength(text, "utf8");
+  if (originalBytes <= maxBytes) {
+    return { text, truncated: false, originalBytes, visibleBytes: originalBytes };
+  }
+
+  let artifactPath: string | undefined;
+  let artifactWarning: string | undefined;
+  if (originalBytes <= MAX_RAW_ARTIFACT_BYTES) {
+    try {
+      const dir = secureArtifactDir(options.artifactDir);
+      artifactPath = join(dir, `${safePrefix(options.artifactPrefix ?? "tool-result")}-${randomUUID()}.txt`);
+      writeFileSync(artifactPath, text, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    } catch (error) {
+      artifactWarning = `Full-output artifact unavailable: ${error instanceof Error ? error.message : String(error)}`;
+      artifactPath = undefined;
+    }
+  } else {
+    artifactWarning = `Full output exceeded the ${MAX_RAW_ARTIFACT_BYTES}-byte local artifact safety cap and was not retained.`;
+  }
+
+  const marker = [
+    "",
+    "--- output bounded by UniPi ---",
+    artifactPath ? `Full output: ${artifactPath}` : artifactWarning!,
+    `Original size: ${originalBytes} bytes; model-visible ceiling: ${maxBytes} bytes.`,
+    ...(artifactPath ? ["Use the read tool with offset/limit to inspect only the needed region."] : []),
+  ].join("\n");
+  const omissionReserve = 80;
+  const markerBytes = Buffer.byteLength(marker, "utf8");
+  const contentBudget = Math.max(1, maxBytes - markerBytes - omissionReserve);
+  const headBytes = Math.ceil(contentBudget * 0.75);
+  const tailBytes = Math.max(0, contentBudget - headBytes);
+  const head = byteSlice(text, 0, headBytes);
+  const tail = tailBytes > 0 ? byteSlice(text, originalBytes - tailBytes) : "";
+  const omission = `\n… ${Math.max(0, originalBytes - contentBudget)} bytes omitted …\n`;
+  let bounded = `${head}${omission}${tail}${marker}`;
+  if (Buffer.byteLength(bounded, "utf8") > maxBytes) {
+    bounded = byteSlice(bounded, 0, maxBytes);
+  }
+
+  return {
+    text: bounded,
+    truncated: true,
+    originalBytes,
+    visibleBytes: Buffer.byteLength(bounded, "utf8"),
+    artifactPath,
+  };
+}

package/packages/core/constants.ts

@@ -168,6 +168,7 @@ export const UTILITY_COMMANDS = {
   BADGE_TOGGLE: "badge-toggle",
   BADGE_SETTINGS: "badge-settings",
   UTIL_SETTINGS: "util-settings",
+  PREFIX_CACHE: "prefix-cache",
 } as const;
 
 /** Utility tool names */
@@ -232,6 +233,7 @@ export const MCP_DEFAULTS = {
   STARTUP_TIMEOUT_MS: 10000,
   MAX_SERVERS: 20,
   TOOL_NAME_SEPARATOR: "__",
+  MAX_MODEL_OUTPUT_BYTES: 64 * 1024,
 } as const;
 
 /** Compactor sentinel — when passed as customInstructions to ctx.compact(),

package/packages/core/index.ts

@@ -10,3 +10,4 @@ export * from "./sandbox.js";
 export * from "./utils.js";
 export * from "./model-cache.js";
 export * from "./tui-width.js";
+export * from "./bounded-output.js";

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Image generation and image recognition tools for the Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",

package/packages/info-screen/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/info-screen",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
   "type": "module",
   "main": "index.ts",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/input-shortcuts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/input-shortcuts",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Keyboard shortcuts for stash/restore, undo/redo, clipboard, and thinking toggle — chord-based overlay system",
   "type": "module",
   "main": "src/index.ts",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/kanboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Visualization layer for unipi workflow — HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
   "type": "module",
   "main": "index.ts",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/mcp/README.md

@@ -39,6 +39,10 @@ MCP input properties are cloned and recursively canonicalized before registratio
 
 Pi 0.80 cannot remove dynamically registered tools. Enabling, disabling, deleting, or changing MCP servers is therefore applied on the next Pi restart rather than mutating the tool list mid-session. This prevents stale schemas and makes the restart an explicit cache-epoch boundary.
 
+### Bounded Results
+
+MCP text results are model-visible up to a hard 64 KiB ceiling. A larger result keeps a bounded head/tail preview and, when the raw result is at most 16 MiB, writes the complete text to a private mode-0600 artifact under `~/.unipi/tool-results/`. Existing result directories are tightened to mode 0700. The returned result includes the path and directs the agent to use `read` with offset/limit. Results above the raw safety cap or filesystem write failures still return a bounded preview with an explicit non-retention warning. MCP image bytes are not written by this text bridge; image blocks remain represented by MIME metadata as before.
+
 Example tool calls:
 ```
 github__search_code({ query: "authentication middleware" })

package/packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/mcp",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "MCP server management extension for Pi coding agent — browse, add, configure, and use MCP servers",
   "type": "module",
   "main": "src/index.ts",
@@ -30,7 +30,7 @@
     "test": "npx tsx --test tests/**/*.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/mcp/src/bridge/translator.ts

@@ -5,7 +5,7 @@
  * Naming convention: {serverName}__{toolName}
  */
 
-import { MCP_DEFAULTS } from "@pi-unipi/core";
+import { MCP_DEFAULTS, boundModelOutput } from "@pi-unipi/core";
 import type { McpTool, McpToolResult } from "../types.js";
 import type { McpClient } from "./client.js";
 
@@ -170,21 +170,28 @@ export function translateMcpTool(
         }
       }
 
-      if (result.isError) {
-        const errorText = blocks.map((b) => b.text).join("\n") || "Unknown error";
-        return {
-          content: [{ type: "text", text: `MCP tool error from ${serverName}: ${errorText}` }],
-          details: { error: true, server: serverName, tool: mcpTool.name },
-        };
-      }
-
       if (blocks.length === 0) {
-        blocks.push({ type: "text", text: "(no output)" });
+        blocks.push({ type: "text", text: result.isError ? "Unknown error" : "(no output)" });
       }
 
+      const rawText = blocks.map((block) => block.text).join("\n");
+      const wrapper = result.isError ? `MCP tool error from ${serverName}: ` : "";
+      const output = boundModelOutput(rawText, {
+        maxBytes: Math.max(1024, MCP_DEFAULTS.MAX_MODEL_OUTPUT_BYTES - Buffer.byteLength(wrapper, "utf8")),
+        artifactPrefix: `mcp-${serverName}-${mcpTool.name}`,
+      });
+      const visibleText = `${wrapper}${output.text}`;
+
       return {
-        content: blocks,
-        details: { server: serverName, tool: mcpTool.name },
+        content: [{ type: "text", text: visibleText }],
+        details: {
+          error: result.isError || undefined,
+          server: serverName,
+          tool: mcpTool.name,
+          truncated: output.truncated,
+          originalBytes: output.originalBytes,
+          artifactPath: output.artifactPath,
+        },
       };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);

package/packages/memory/index.ts

@@ -35,6 +35,54 @@ import { isEmbeddingReady, hasModelChanged } from "./settings.js";
 /** Package version */
 const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
 
+interface MemoryReminderInput {
+  projectName: string;
+  memories: Array<{ title: string }>;
+  canSearch: boolean;
+  canStore: boolean;
+}
+
+/**
+ * Build the deterministic, model-visible first-turn memory reminder.
+ * Exported so provider-payload regressions can exercise the exact production
+ * content without initializing a storage backend.
+ */
+export function buildMemoryRecallReminder(input: MemoryReminderInput): string {
+  const lines = [
+    "## 🧠 Memory System Active",
+    "",
+    `You have ${input.memories.length} memories stored for project "${input.projectName}".`,
+  ];
+
+  if (input.canSearch && input.memories.length > 0) {
+    const titleList = input.memories.slice(0, 20).map((memory) => `- ${memory.title}`).join("\n");
+    const extra = input.memories.length > 20
+      ? `\n... and ${input.memories.length - 20} more`
+      : "";
+    lines.push(
+      "**BEFORE starting work**, call `memory_search` with relevant keywords to check for existing context.",
+      "",
+      "Available memories:",
+      titleList + extra,
+    );
+  }
+
+  if (input.canStore) {
+    lines.push(
+      "",
+      "**AFTER completing the task**, if you learned something non-obvious,",
+      "call `memory_store` to save it for future sessions.",
+    );
+  }
+
+  lines.push(
+    "",
+    "Guardrails: read max 10 memory results per search. Update existing memories instead of creating duplicates.",
+  );
+
+  return lines.join("\n");
+}
+
 /** Storage instance for current project */
 let projectStorage: MemoryStorage | null = null;
 
@@ -251,44 +299,18 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    const lines = [
-      "## 🧠 Memory System Active",
-      "",
-      `You have ${projectMemories.length} memories stored for project "${projectName}".`,
-    ];
-
-    if (canSearch && projectMemories.length > 0) {
-      const titleList = projectMemories.slice(0, 20).map(m => `- ${m.title}`).join("\n");
-      const extra = projectMemories.length > 20 ? `\n... and ${projectMemories.length - 20} more` : "";
-      lines.push(
-        "**BEFORE starting work**, call `memory_search` with relevant keywords to check for existing context.",
-        "",
-        "Available memories:",
-        titleList + extra,
-      );
-    } else {
-      recallDone = true;
-    }
-
-    if (canStore) {
-      lines.push(
-        "",
-        "**AFTER completing the task**, if you learned something non-obvious,",
-        "call `memory_store` to save it for future sessions.",
-      );
-    } else {
-      storeDone = true;
-    }
-
-    lines.push(
-      "",
-      "Guardrails: read max 10 memory results per search. Update existing memories instead of creating duplicates.",
-    );
+    if (!canSearch || projectMemories.length === 0) recallDone = true;
+    if (!canStore) storeDone = true;
 
     return {
       message: {
         customType: "unipi-memory-recall-reminder",
-        content: lines.join("\n"),
+        content: buildMemoryRecallReminder({
+          projectName,
+          memories: projectMemories,
+          canSearch,
+          canStore,
+        }),
         display: false,
       },
     };

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/memory",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Persistent cross-session memory with MemPalace backend (auto-installed) and SQLite fallback for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -43,8 +43,8 @@
     "better-sqlite3": "^12.9.0",
     "sqlite-vec": "^0.1.9",
     "js-yaml": "^4.1.0",
-    "@pi-unipi/core": "2.5.0",
-    "@pi-unipi/info-screen": "2.5.0"
+    "@pi-unipi/core": "2.6.0",
+    "@pi-unipi/info-screen": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/milestone/hooks.ts

@@ -51,7 +51,7 @@ function formatMilestoneContext(filePath: string): string | null {
 }
 
 /** Build an append-only snapshot that explicitly invalidates earlier snapshots. */
-function formatMilestoneSnapshot(workspace: string, context: string | null): string {
+export function formatMilestoneSnapshot(workspace: string, context: string | null): string {
   return [
     "# UniPi Milestone Snapshot",
     "This snapshot supersedes all prior UniPi milestone snapshots; use only this snapshot for milestone status.",

package/packages/milestone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/milestone",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Lifecycle layer for project-level goals — MILESTONES.md tracking, session hooks, auto-sync",
   "type": "module",
   "main": "index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/notify/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0",
+    "@pi-unipi/core": "2.6.0",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/packages/ralph/index.ts

@@ -30,6 +30,7 @@ const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
 /** Current loop manager instance (recreated on session reload) */
 let manager: RalphLoopManager | null = null;
 
+
 /**
  * Get or create the loop manager for the current context.
  */
@@ -42,9 +43,14 @@ function getManager(ctx: ExtensionContext, pi: ExtensionAPI): RalphLoopManager {
   return manager;
 }
 
+export { buildRalphLoopReminder } from "./reminder.js";
+import { buildRalphLoopReminder, latestRalphReminder, RALPH_REMINDER_TYPE } from "./reminder.js";
+
 export default function (pi: ExtensionAPI) {
-  // Register tools
-  // (Manager will be created lazily on first use)
+  // Register static tool definitions at extension load. Their executors resolve
+  // the session-scoped manager lazily, so schemas never arrive late or reorder
+  // the provider tool array during session_start.
+  registerRalphTools(pi, (ctx) => getManager(ctx, pi));
 
   // Register commands
   registerCommands(pi);
@@ -157,20 +163,13 @@ export default function (pi: ExtensionAPI) {
     const state = mgr.loadState(currentLoop);
     if (!state || state.status !== "active") return;
 
-    const iterStr = `${state.iteration}${state.maxIterations > 0 ? `/${state.maxIterations}` : ""}`;
-
-    let instructions = `You are in a Ralph loop working on: ${state.taskFile}\n`;
-    if (state.itemsPerIteration > 0) {
-      instructions += `- Work on ~${state.itemsPerIteration} items this iteration\n`;
-    }
-    instructions += `- Update the task file as you progress\n`;
-    instructions += `- When FULLY COMPLETE: ${RALPH_COMPLETE_MARKER}\n`;
-    instructions += `- Otherwise, call ralph_done tool to proceed to next iteration`;
+    const content = buildRalphLoopReminder(state);
+    if (latestRalphReminder(ctx) === content) return;
 
     return {
       message: {
-        customType: "unipi-ralph-loop-reminder",
-        content: `[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`,
+        customType: RALPH_REMINDER_TYPE,
+        content,
         display: false,
       },
     };
@@ -187,11 +186,6 @@ export default function (pi: ExtensionAPI) {
     manager = null;
   });
 
-  // Register tools after manager setup
-  pi.on("session_start", async (_event, ctx) => {
-    const mgr = getManager(ctx, pi);
-    registerRalphTools(pi, mgr);
-  });
 }
 
 /**

package/packages/ralph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ralph",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Long-running iterative development loops for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -26,9 +26,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "test": "npx tsx --test reminder.test.ts"
+  },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0",
-    "@pi-unipi/info-screen": "2.5.0"
+    "@pi-unipi/core": "2.6.0",
+    "@pi-unipi/info-screen": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",

package/packages/ralph/reminder.ts

@@ -0,0 +1,40 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { RALPH_COMPLETE_MARKER } from "@pi-unipi/core";
+
+export const RALPH_REMINDER_TYPE = "unipi-ralph-loop-reminder";
+
+export interface RalphReminderInput {
+  name: string;
+  iteration: number;
+  maxIterations: number;
+  taskFile: string;
+  itemsPerIteration: number;
+}
+
+/** Build the exact deterministic hidden reminder used by the live hook. */
+export function buildRalphLoopReminder(state: RalphReminderInput): string {
+  const iterStr = `${state.iteration}${state.maxIterations > 0 ? `/${state.maxIterations}` : ""}`;
+  let instructions = "This snapshot supersedes all earlier Ralph loop reminders.\n";
+  instructions += `You are in a Ralph loop working on: ${state.taskFile}\n`;
+  if (state.itemsPerIteration > 0) {
+    instructions += `- Work on ~${state.itemsPerIteration} items this iteration\n`;
+  }
+  instructions += "- Update the task file as you progress\n";
+  instructions += `- When FULLY COMPLETE: ${RALPH_COMPLETE_MARKER}\n`;
+  instructions += "- Otherwise, call ralph_done tool to proceed to next iteration";
+  return `[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`;
+}
+
+export function latestRalphReminder(ctx: Pick<ExtensionContext, "sessionManager">): string | null {
+  const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index];
+    if (entry.type === "custom_message" && entry.customType === RALPH_REMINDER_TYPE) {
+      return typeof entry.content === "string" ? entry.content : null;
+    }
+    // A compacted summary may contain the old reminder but no longer retains a
+    // dedicated custom entry. Inject the current snapshot once in the new epoch.
+    if (entry.type === "compaction") break;
+  }
+  return null;
+}

package/packages/ralph/tools.ts

@@ -9,10 +9,12 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { RALPH_COMPLETE_MARKER, RALPH_DEFAULTS, RALPH_TOOLS } from "@pi-unipi/core";
 import { RalphLoopManager, DEFAULT_REFLECT_INSTRUCTIONS } from "./ralph-loop.js";
 
+type ManagerProvider = (ctx: ExtensionContext) => RalphLoopManager;
+
 /**
  * Register ralph_start and ralph_done tools.
  */
-export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager): void {
+export function registerRalphTools(pi: ExtensionAPI, getManager: ManagerProvider): void {
   // --- ralph_start tool ---
   pi.registerTool({
     name: RALPH_TOOLS.START,
@@ -44,6 +46,7 @@ export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager):
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const manager = getManager(ctx);
       const taskFile = `.unipi/ralph/${params.name.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`;
 
       if (manager.loadState(params.name)?.status === "active") {
@@ -92,6 +95,7 @@ export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager):
     ],
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const manager = getManager(ctx);
       if (!manager.getCurrentLoop()) {
         return {
           content: [{ type: "text", text: "No active Ralph loop." }],

package/packages/subagents/README.md

@@ -69,6 +69,8 @@ spawn_helper(
 get_helper_result(agent_id: "helper_abc123")
 ```
 
+Foreground and retrieved background results have a hard 64 KiB model-visible ceiling. For raw results up to 16 MiB, larger output includes a bounded head/tail preview and a path to the complete private mode-0600 artifact under a mode-0700 `~/.unipi/tool-results/` directory. Use `read` with offset/limit to inspect only the needed region. Repeated retrieval reuses the same artifact. Results above the safety cap or artifact-write failures still return a preview with an explicit non-retention warning.
+
 ## Custom Agent Types
 
 Create markdown files defining agent behavior:

package/packages/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/subagents",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Subagents for UniPi — parallel execution, file locking, workflow integration",
   "type": "module",
   "main": "dist/index.js",