@pi-unipi/unipi 2.5.0 → 2.6.0

package/packages/subagents/src/agent-manager.ts

@@ -13,6 +13,10 @@ import { resolveModel, type ModelRegistry } from "./model-resolver.js";
 import type { AgentRecord, AgentConfig, AgentType, ThinkingLevel, SubagentsConfig } from "./types.js";
 import { BUILTIN_CONFIGS } from "./types.js";
 import { loadCustomAgents } from "./custom-agents.js";
+
+function compareCodeUnits(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 import { FileLock } from "./file-lock.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
@@ -88,7 +92,7 @@ export class AgentManager {
       ...Object.keys(BUILTIN_CONFIGS).filter((type) => type !== "name-gen"),
       ...this.customAgents.keys(),
       ...Object.keys(this.typeSettings),
-    ])];
+    ])].sort(compareCodeUnits);
   }
 
   /** A type is enabled only when both JSON config and agent frontmatter allow it. */

package/packages/subagents/src/agent-runner.ts

@@ -19,8 +19,8 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_CONFIGS, type AgentConfig, type AgentType, type ThinkingLevel } from "./types.js";
 
-/** Tools excluded from subagents to prevent nesting. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_result"];
+/** Tools excluded from subagents to prevent nesting. Legacy names remain for older hosts. */
+const EXCLUDED_TOOL_NAMES = ["spawn_helper", "get_helper_result", "Agent", "get_result"];
 
 /** All known built-in tool names. */
 const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];

package/packages/subagents/src/core-compat.ts

@@ -1,4 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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 MODULES = { SUBAGENTS: "subagents" } as const;
 
@@ -24,6 +28,75 @@ export function emitEvent(
   }
 }
 
+export interface BoundedHelperOutput {
+  text: string;
+  truncated: boolean;
+  originalBytes: number;
+  artifactPath?: string;
+}
+
+/** Standalone-package twin of core's bounded-output policy. */
+const MAX_RAW_HELPER_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+export function boundHelperOutput(
+  text: string,
+  maxBytes = 64 * 1024,
+  existingArtifactPath?: string,
+): BoundedHelperOutput {
+  const originalBytes = Buffer.byteLength(text, "utf8");
+  if (originalBytes <= maxBytes) return { text, truncated: false, originalBytes };
+
+  let artifactPath = existingArtifactPath;
+  let artifactWarning: string | undefined;
+  if (!artifactPath && originalBytes <= MAX_RAW_HELPER_ARTIFACT_BYTES) {
+    try {
+      const dir = 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}`);
+      }
+      artifactPath = join(dir, `helper-${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 if (!artifactPath) {
+    artifactWarning = `Full output exceeded the ${MAX_RAW_HELPER_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 markerBytes = Buffer.byteLength(marker, "utf8");
+  const contentBudget = Math.max(1, maxBytes - markerBytes - 80);
+  const bytes = Buffer.from(text, "utf8");
+  const headBytes = Math.ceil(contentBudget * 0.75);
+  const tailBytes = Math.max(0, contentBudget - headBytes);
+  const head = bytes.subarray(0, headBytes).toString("utf8").replace(/\uFFFD+$/u, "");
+  const tail = bytes.subarray(originalBytes - tailBytes).toString("utf8").replace(/^\uFFFD+/u, "");
+  let bounded = `${head}\n… ${Math.max(0, originalBytes - contentBudget)} bytes omitted …\n${tail}${marker}`;
+  if (Buffer.byteLength(bounded, "utf8") > maxBytes) {
+    bounded = Buffer.from(bounded, "utf8").subarray(0, maxBytes).toString("utf8").replace(/\uFFFD+$/u, "");
+  }
+  return {
+    text: bounded,
+    truncated: true,
+    originalBytes,
+    artifactPath,
+  };
+}
+
 export async function withHerdrBlocked<T>(
   pi: Pick<ExtensionAPI, "events">,
   label: string,

package/packages/subagents/src/custom-agents.ts

@@ -12,6 +12,10 @@ import { homedir } from "node:os";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "./types.js";
 
+function compareCodeUnits(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
 /** Backup a corrupted file by renaming to .bak */
 function backupCorrupted(filePath: string): void {
   const backupPath = filePath + ".bak";
@@ -93,7 +97,9 @@ export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
   // Load global agents first
   const globalDir = getGlobalAgentsDir();
   if (existsSync(globalDir)) {
-    const files = readdirSync(globalDir).filter((f) => f.endsWith(".md"));
+    const files = readdirSync(globalDir)
+      .filter((f) => f.endsWith(".md"))
+      .sort(compareCodeUnits);
     for (const file of files) {
       const agent = loadAgentFromFile(join(globalDir, file), "global");
       if (agent) {
@@ -105,7 +111,9 @@ export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
   // Load project agents (overrides global)
   const projectDir = getProjectAgentsDir(cwd);
   if (existsSync(projectDir)) {
-    const files = readdirSync(projectDir).filter((f) => f.endsWith(".md"));
+    const files = readdirSync(projectDir)
+      .filter((f) => f.endsWith(".md"))
+      .sort(compareCodeUnits);
     for (const file of files) {
       const agent = loadAgentFromFile(join(projectDir, file), "project");
       if (agent) {

package/packages/subagents/src/index.ts

@@ -12,7 +12,7 @@ import { Type } from "typebox";
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { emitEvent, MODULES, UNIPI_EVENTS, withHerdrBlocked, type UnipiBadgeGenerateRequestEvent } from "./core-compat.js";
+import { boundHelperOutput, emitEvent, MODULES, UNIPI_EVENTS, withHerdrBlocked, type UnipiBadgeGenerateRequestEvent } from "./core-compat.js";
 import { AgentManager } from "./agent-manager.js";
 import { initConfig } from "./config.js";
 import { type AgentActivity, type NotificationDetails, BUILTIN_TYPES } from "./types.js";
@@ -756,9 +756,11 @@ Guidelines:
           });
         }
 
+        const output = boundHelperOutput(record.result?.trim() || "No output.");
+        record.resultArtifactPath = output.artifactPath;
         return textResult(
           `Agent completed in ${(durationMs / 1000).toFixed(1)}s (${record.toolUses} tool uses${tokenText ? `, ${tokenText} tokens` : ""}).\n\n` +
-            (record.result?.trim() || "No output."),
+            output.text,
           {
             status: "completed",
             toolUses: record.toolUses,
@@ -766,6 +768,9 @@ Guidelines:
             durationMs,
             turnCount: fgState.turnCount,
             maxTurns: fgState.maxTurns,
+            truncated: output.truncated,
+            originalBytes: output.originalBytes,
+            artifactPath: output.artifactPath,
           },
         );
       },
@@ -851,7 +856,13 @@ Guidelines:
         } else if (record.status === "error") {
           output += `Error: ${record.error}`;
         } else {
-          output += record.result?.trim() || "No output.";
+          const bounded = boundHelperOutput(
+            record.result?.trim() || "No output.",
+            64 * 1024,
+            record.resultArtifactPath,
+          );
+          record.resultArtifactPath = bounded.artifactPath;
+          output += bounded.text;
         }
 
         if (record.status !== "running" && record.status !== "queued") {

package/packages/subagents/src/types.ts

@@ -90,6 +90,8 @@ export interface AgentRecord {
   description: string;
   status: "queued" | "running" | "completed" | "aborted" | "stopped" | "error";
   result?: string;
+  /** Private artifact holding the complete result when model-visible output is bounded. */
+  resultArtifactPath?: string;
   error?: string;
   toolUses: number;
   startedAt: number;