@pi-unipi/unipi 2.4.2 → 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.4.1",
+  "version": "2.6.0",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/core/sandbox.ts

@@ -2,7 +2,8 @@
  * @unipi/core — Sandbox module
  *
  * Defines tool access levels for workflow commands.
- * Used with pi.setActiveTools() to enforce restrictions.
+ * Workflow enforces blocked names at tool_call time so provider tool schemas
+ * and ordering remain stable; filtering helpers remain available to other callers.
  */
 
 import { WORKFLOW_COMMANDS } from "./constants.js";
@@ -13,9 +14,9 @@ export type SandboxLevel = "read_only" | "brainstorm" | "write_unipi" | "review"
 /**
  * Built-in workflow tools used when no active tool list is supplied.
  *
- * Workflow commands should normally call filterToolsForLevel() with the current
- * active tool list. That keeps safe extension tools (memory, ask-user, web,
- * notify, etc.) available while removing only tools that violate the sandbox.
+ * Legacy fallback list used by callers that need an explicit filtered tool set.
+ * The workflow package itself keeps Pi's active tools unchanged and enforces
+ * BLOCKED_TOOLS at tool_call time.
  */
 const FALLBACK_TOOLS: Record<SandboxLevel, readonly string[]> = {
   /** Only read-only file tools — no bash, no write, no edit */
@@ -78,8 +79,8 @@ export function getSandboxLevel(commandName: string): SandboxLevel {
 /**
  * Get fallback tools for a sandbox level.
  *
- * Prefer filterToolsForLevel(level, activeTools) when applying a sandbox so
- * extension tools are preserved unless explicitly blocked.
+ * Prefer isToolAllowed() for cache-stable call-time enforcement. Filtering is
+ * retained for compatibility with callers that intentionally alter tool sets.
  */
 export function getToolsForLevel(level: SandboxLevel): readonly string[] {
   return FALLBACK_TOOLS[level];

package/packages/footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "2.4.1",
+  "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.4.1"
+    "@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.4.1",
+  "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.4.1"
+    "@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.4.1",
+  "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.4.1"
+    "@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.4.1",
+  "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.4.1"
+    "@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.4.1",
+  "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.4.1"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/mcp/README.md

@@ -12,6 +12,7 @@ The add command opens a split-pane overlay: server browser on the left, JSON con
 | `/unipi:mcp-settings` | Interactive settings with enable/disable/edit |
 | `/unipi:mcp-sync` | Force sync server catalog from GitHub |
 | `/unipi:mcp-status` | Text summary of all configured servers |
+| `/unipi:mcp-reload` | Remind you to restart Pi so tool schemas reload as a clean cache epoch |
 
 ### Setup Flow
 
@@ -30,6 +31,18 @@ MCP registers with the info-screen dashboard, showing server count, active serve
 
 MCP tools are registered dynamically based on configured servers. Once a server is added and Pi restarts, its tools become available to the agent.
 
+### Deterministic Definitions and Cache Behavior
+
+At session startup, enabled servers connect and discover tools in parallel. Registration waits for all discoveries to settle, then registers the successful combined tool set in canonical `{serverName}__{toolName}` order. Duplicate final names are rejected explicitly instead of allowing one definition to overwrite another.
+
+MCP input properties are cloned and recursively canonicalized before registration: schema object keys use locale-independent UTF-16 code-unit order, valid schema `required` string arrays are sorted and deduplicated, a missing top-level `required` becomes `[]`, and literal-value arrays keep their source order. Each tool also receives a stable label matching its final Pi name. These stable definitions and registration order prevent equivalent MCP configurations from changing the serialized tool list between runs, improving provider prompt-cache reuse. A server that fails discovery is excluded from the combined set; a registration error fails startup for that prepared set and is not reported as successful.
+
+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.4.1",
+  "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",
@@ -26,8 +26,11 @@
     "skills/**/*",
     "README.md"
   ],
+  "scripts": {
+    "test": "npx tsx --test tests/**/*.test.ts"
+  },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",