@nredd/pi-subagents 0.22.0-nredd.8 → 0.22.0-nredd.9

package/src/default-agents.ts

@@ -6,7 +6,17 @@
 
 import type { AgentConfig } from "./types.js";
 
-const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+/**
+ * Tool surface shared by Explore and Plan. `bash` is left out because a prompt cannot
+ * make an unrestricted shell read-only, and extensions are off because extension tools
+ * can run commands or write. A `.pi/agents/<Name>.md` override can opt back in with an
+ * explicit `extensions:` list.
+ */
+const READ_ONLY_SURFACE: Pick<AgentConfig, "builtinToolNames" | "extensions" | "skills"> = {
+  builtinToolNames: ["read", "grep", "find", "ls"],
+  extensions: false,
+  skills: true,
+};
 
 export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
   [
@@ -31,9 +41,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       name: "Explore",
       displayName: "Explore",
       description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.",
-      builtinToolNames: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
+      ...READ_ONLY_SURFACE,
       // Bind the role per machine, not to a provider or model generation.
       model: "@cheap",
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
@@ -49,13 +57,10 @@ You are STRICTLY PROHIBITED from:
 - Using redirect operators (>, >>, |) or heredocs to write to files
 - Running ANY commands that change system state
 
-Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
-
 # Tool Usage
-- Use the find tool for file pattern matching (NOT the bash find command)
-- Use the grep tool for content search (NOT bash grep/rg command)
-- Use the read tool for reading files (NOT bash cat/head/tail)
-- Use Bash ONLY for read-only operations
+- Use the find tool for file pattern matching
+- Use the grep tool for content search
+- Use the read tool for reading files
 - Make independent tool calls in parallel for efficiency
 - Adapt search approach based on thoroughness level specified
 
@@ -74,9 +79,7 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
       name: "Plan",
       displayName: "Plan",
       description: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
-      builtinToolNames: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
+      ...READ_ONLY_SURFACE,
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a software architect and planning specialist.
 Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
@@ -104,10 +107,9 @@ You are STRICTLY PROHIBITED from:
 - Follow existing patterns where appropriate
 
 # Tool Usage
-- Use the find tool for file pattern matching (NOT the bash find command)
-- Use the grep tool for content search (NOT bash grep/rg command)
-- Use the read tool for reading files (NOT bash cat/head/tail)
-- Use Bash ONLY for read-only operations
+- Use the find tool for file pattern matching
+- Use the grep tool for content search
+- Use the read tool for reading files
 
 # Output Format
 - Use absolute file paths

package/src/detached-results.ts

@@ -13,7 +13,9 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { AgentRecord } from "./types.js";
+import type { EvictedNote } from "./agent-manager.js";
+import type { NoticeParts } from "./notification-result.js";
+import type { AgentRecord, AgentTombstone } from "./types.js";
 import type { AgentActivity } from "./ui/agent-widget.js";
 
 /** One finished agent, in the shape `session_start` needs to re-announce it. */
@@ -25,6 +27,14 @@ export interface DetachedResult {
   details: unknown;
   /** History entry for a result that finished detached; absent if already appended. */
   record?: Record<string, unknown>;
+  /** The `subagents:completed`/`subagents:failed` event the live path would have emitted, replayed on delivery. */
+  lifecycle?: { channel: "subagents:completed" | "subagents:failed"; data: Record<string, unknown> };
+  /** What the reopened session keeps so these agents' ids still answer after their records are gone. */
+  evicted?: EvictedNote[];
+  /** Reopenable sessions among them, so a steer or resume of these ids continues the saved conversation. */
+  tombstones?: AgentTombstone[];
+  /** A full-result notice's parts, so delivery clips it against its batch's budget; `content` is the fallback. */
+  notice?: NoticeParts & { footer: string };
 }
 
 const SINK_KEY = Symbol.for("pi-subagents:detached-sink");
@@ -96,7 +106,8 @@ export function watchDetached(sessionFile: string, onSpooled: () => void): () =>
 export interface RunningDetached {
   record: AgentRecord;
   activity?: AgentActivity;
-  abort(): boolean;
+  /** `by` as for `AgentManager.abort`: `"parent"` for `stop_subagent`, omitted for a human. */
+  abort(by?: AgentRecord["stoppedBy"]): boolean;
   steer(message: string): boolean;
 }
 
@@ -127,6 +138,11 @@ export function unregisterRunningDetached(sessionFile: string, id: string): void
   if (byId?.size === 0) running().delete(sessionFile);
 }
 
+/** Every orphan still running in the process with the session file it is registered (and wakes) under. */
+export function listAllRunningDetached(): Array<{ sessionFile: string; agent: RunningDetached }> {
+  return [...running()].flatMap(([sessionFile, byId]) => [...byId.values()].map((agent) => ({ sessionFile, agent })));
+}
+
 /** Orphans still running for `sessionFile`, in registration order. */
 export function listRunningDetached(sessionFile: string | undefined): RunningDetached[] {
   if (sessionFile === undefined) return [];

package/src/enterprise-local.ts

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { errorMessage } from "./error-message.js";
 import { resolveAgentDir } from "./home-paths.js";
 
 const MANIFEST_VERSION = 1;
@@ -59,7 +60,7 @@ export function readEnterpriseLocalManifest(homeDir?: string): EnterpriseLocalMa
     }
     return manifest as unknown as EnterpriseLocalManifest;
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
+    const reason = errorMessage(error);
     console.warn(`[pi-subagents] Ignoring invalid ${path}: ${reason}`);
     return undefined;
   }

package/src/error-message.ts

@@ -0,0 +1,11 @@
+/**
+ * error-message.ts — the text a caught value reports.
+ *
+ * `catch` binds `unknown`: an `Error` gives its message, and anything else a
+ * caller threw (a string, a rejected non-Error) is stringified as-is.
+ */
+
+/** The message of `error` when it is an `Error`, else `String(error)`. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/git-path.ts

@@ -0,0 +1,66 @@
+/**
+ * git-path.ts -- decode the C-style quoted paths git prints without `-z`.
+ *
+ * `pi.exec` decodes each stdout chunk as UTF-8 on its own, so a multibyte
+ * character split across two chunks becomes U+FFFD. With `core.quotePath=true`
+ * git escapes every non-ASCII byte (and control characters, `"` and `\`) as
+ * `"..."` with octal escapes, so a listing read without `-z` is pure ASCII and
+ * survives any chunking; this module turns it back into the real path.
+ */
+
+const SIMPLE_ESCAPES: Record<string, number> = {
+  a: 0x07,
+  b: 0x08,
+  f: 0x0c,
+  n: 0x0a,
+  r: 0x0d,
+  t: 0x09,
+  v: 0x0b,
+  '"': 0x22,
+  "\\": 0x5c,
+};
+
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/** Args that make `git` quote every non-ASCII path byte; put them before the subcommand. */
+export const QUOTE_PATH_ARGS = ["-c", "core.quotePath=true"];
+
+/**
+ * Decode one path as git prints it: a plain name is returned as is, a `"..."` name is
+ * unescaped to bytes and decoded as UTF-8. Throws on anything that cannot name a file
+ * as a JS string: raw non-ASCII (the listing was not quoted, so it may be mis-decoded),
+ * a malformed escape, or bytes that are not valid UTF-8.
+ */
+export function unquoteGitPath(text: string): string {
+  const quoted = text.length >= 2 && text.startsWith('"') && text.endsWith('"');
+  const body = quoted ? text.slice(1, -1) : text;
+  for (let i = 0; i < body.length; i++) {
+    if (body.charCodeAt(i) > 0x7f) throw new Error(`git printed a non-ASCII path unquoted (${JSON.stringify(text)}); it may be mis-decoded`);
+  }
+  if (!quoted) return text;
+  const bytes: number[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const char = body.charAt(i);
+    if (char === '"') throw new Error(`malformed quoted git path ${JSON.stringify(text)}`);
+    if (char !== "\\") {
+      bytes.push(body.charCodeAt(i));
+      continue;
+    }
+    const next = body.charAt(i + 1);
+    const octal = /^[0-3][0-7]{2}$/.test(body.slice(i + 1, i + 4)) ? body.slice(i + 1, i + 4) : undefined;
+    if (octal) {
+      bytes.push(Number.parseInt(octal, 8));
+      i += 3;
+    } else if (next in SIMPLE_ESCAPES) {
+      bytes.push(SIMPLE_ESCAPES[next] as number);
+      i += 1;
+    } else {
+      throw new Error(`malformed escape in quoted git path ${JSON.stringify(text)}`);
+    }
+  }
+  try {
+    return UTF8.decode(Uint8Array.from(bytes));
+  } catch {
+    throw new Error(`git path ${JSON.stringify(text)} is not valid UTF-8 and cannot be inspected`);
+  }
+}

package/src/group-join.ts

@@ -15,7 +15,6 @@ interface AgentGroup {
   agentIds: Set<string>;
   completedRecords: Map<string, AgentRecord>;
   timeoutHandle?: ReturnType<typeof setTimeout>;
-  delivered: boolean;
   /** Shorter timeout for stragglers after a partial delivery. */
   isStraggler: boolean;
 }
@@ -40,7 +39,6 @@ export class GroupJoinManager {
       groupId,
       agentIds: new Set(agentIds),
       completedRecords: new Map(),
-      delivered: false,
       isStraggler: false,
     };
     this.groups.set(groupId, group);
@@ -61,7 +59,7 @@ export class GroupJoinManager {
     if (!groupId) return 'pass';
 
     const group = this.groups.get(groupId);
-    if (!group || group.delivered) return 'pass';
+    if (!group) return 'pass';
 
     group.completedRecords.set(record.id, record);
 
@@ -83,7 +81,6 @@ export class GroupJoinManager {
   }
 
   private onTimeout(group: AgentGroup): void {
-    if (group.delivered) return;
     group.timeoutHandle = undefined;
 
     // Partial delivery — some agents still running
@@ -112,18 +109,15 @@ export class GroupJoinManager {
       clearTimeout(group.timeoutHandle);
       group.timeoutHandle = undefined;
     }
-    group.delivered = true;
     this.deliverCb([...group.completedRecords.values()], partial);
-    this.cleanupGroup(group.groupId);
+    this.cleanupGroup(group);
   }
 
-  private cleanupGroup(groupId: string): void {
-    const group = this.groups.get(groupId);
-    if (!group) return;
+  private cleanupGroup(group: AgentGroup): void {
     for (const id of group.agentIds) {
       this.agentToGroup.delete(id);
     }
-    this.groups.delete(groupId);
+    this.groups.delete(group.groupId);
   }
 
   /** Check if an agent is in a group. */