@pi-unipi/core 2.5.0 → 2.6.1

package/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/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(),
@@ -295,6 +297,7 @@ export const NOTIFY_COMMANDS = {
   SET_NTFY: "notify-set-ntfy",
   TEST: "notify-test",
   RECAP_MODEL: "notify-recap-model",
+  NOTIFY_EVENT: "notify-event",
 } as const;
 
 /** Notify tool names */

package/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/model-cache.ts

@@ -9,14 +9,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-/** Path to the model cache directory */
-const CACHE_DIR = path.join(
-  process.env.HOME ?? process.env.USERPROFILE ?? "~",
-  ".unipi/config",
-);
+/** Resolve the model cache directory at call time (respects HOME changes). */
+function cacheDir(): string {
+  return path.join(
+    process.env.HOME ?? process.env.USERPROFILE ?? "~",
+    ".unipi/config",
+  );
+}
 
-/** Path to the model cache file */
-const CACHE_FILE = path.join(CACHE_DIR, "models-cache.json");
+/** Resolve the model cache file path at call time. */
+function cacheFile(): string {
+  return path.join(cacheDir(), "models-cache.json");
+}
 
 /** A single cached model entry */
 export interface CachedModel {
@@ -42,8 +46,9 @@ export interface ModelCache {
  */
 export function readModelCache(): CachedModel[] {
   try {
-    if (!fs.existsSync(CACHE_FILE)) return [];
-    const parsed = JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
+    const file = cacheFile();
+    if (!fs.existsSync(file)) return [];
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
     return Array.isArray(parsed.models) ? parsed.models : [];
   } catch {
     return [];
@@ -56,14 +61,15 @@ export function readModelCache(): CachedModel[] {
  */
 export function writeModelCache(models: CachedModel[]): void {
   try {
-    if (!fs.existsSync(CACHE_DIR)) {
-      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    const dir = cacheDir();
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
     }
     const cache: ModelCache = {
       updatedAt: new Date().toISOString(),
       models,
     };
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2) + "\n", "utf-8");
+    fs.writeFileSync(cacheFile(), JSON.stringify(cache, null, 2) + "\n", "utf-8");
   } catch {
     // Best effort — cache is optional
   }

package/package.json

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