@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/shared/chain-files.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CHAIN_RUNS_DIR } from "./types.ts";
+import { ensureSafeTempPath, ensureTempRoot } from "./temp-root.ts";
+const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const INITIAL_PROGRESS_CONTENT =
+  "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
+
+export function createChainDir(runId: string, baseDir?: string, cwd = process.cwd()): string {
+  const customBase = baseDir !== undefined && baseDir.length > 0;
+  if (!customBase) {
+    ensureTempRoot();
+  }
+  const chainDir = path.join(customBase ? path.resolve(cwd, baseDir) : CHAIN_RUNS_DIR, runId);
+  if (!customBase) {
+    ensureSafeTempPath(chainDir);
+  }
+  fs.mkdirSync(chainDir, { recursive: true });
+  return chainDir;
+}
+export function removeChainDir(chainDir: string): void {
+  try {
+    fs.rmSync(chainDir, { recursive: true });
+  } catch {
+    // Cleanup is best effort; another run may already have removed the directory.
+  }
+}
+async function cleanupOldDirectory(dir: string, now: number): Promise<void> {
+  try {
+    const dirPath = path.join(CHAIN_RUNS_DIR, dir);
+    const stat = await fs.promises.lstat(dirPath);
+    if (stat.isDirectory() && now - stat.mtimeMs > CHAIN_DIR_MAX_AGE_MS) {
+      await fs.promises.rm(dirPath, { recursive: true });
+    }
+  } catch {
+    // One unreadable directory must not prevent cleanup of the remaining runs.
+  }
+}
+export async function cleanupOldChainDirs(): Promise<void> {
+  ensureSafeTempPath(CHAIN_RUNS_DIR);
+  const now = Date.now();
+  let dirs: string[];
+  try {
+    dirs = await fs.promises.readdir(CHAIN_RUNS_DIR);
+  } catch {
+    // An unreadable scoped temp root must not fail extension startup.
+    return;
+  }
+  for (const dir of dirs) {
+    // Preserve the existing one-directory resource bound throughout startup pruning.
+    // oxlint-disable-next-line no-await-in-loop
+    await cleanupOldDirectory(dir, now);
+  }
+}
+export function writeInitialProgressFile(progressDir: string): void {
+  fs.mkdirSync(progressDir, { recursive: true });
+  try {
+    fs.writeFileSync(path.join(progressDir, "progress.md"), INITIAL_PROGRESS_CONTENT, {
+      encoding: "utf-8",
+      flag: "wx",
+    });
+  } catch (error) {
+    if (
+      typeof error !== "object" ||
+      error === null ||
+      !("code" in error) ||
+      error.code !== "EEXIST"
+    ) {
+      throw error;
+    }
+  }
+}

package/src/shared/concurrency.ts

@@ -0,0 +1,27 @@
+import type { ReadonlyInput } from "./types/inputs.ts";
+
+/** A bounded worker pool. Results retain input order even when workers finish out of order. */
+export async function mapConcurrent<T, R>(
+  items: readonly ReadonlyInput<T>[],
+  limit: number,
+  fn: (item: ReadonlyInput<T>, index: number) => Promise<R>,
+): Promise<R[]> {
+  const integralLimit = Math.floor(limit);
+  const safeLimit = Math.max(
+    1,
+    Number.isNaN(integralLimit) || integralLimit === 0 ? 1 : integralLimit,
+  );
+  const results: R[] = [];
+  results.length = items.length;
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (next < items.length) {
+      const index = next++;
+      // Each worker awaits its own task before claiming another, bounding active work.
+      // oxlint-disable-next-line no-await-in-loop
+      results[index] = await fn(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(safeLimit, items.length) }, () => worker()));
+  return results;
+}

package/src/shared/content-preview.ts

@@ -0,0 +1,117 @@
+import { isRecord, isUnknownArray } from "./unknown.ts";
+
+function truncate(value: string, length: number): string {
+  return value.length > length ? `${value.slice(0, length - 3)}...` : value;
+}
+function scalar(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return undefined;
+}
+function array(value: unknown): string | undefined {
+  if (!isUnknownArray(value) || value.length === 0) {
+    return undefined;
+  }
+  const first = scalar(value[0]);
+  if (first === undefined || first === "") {
+    return undefined;
+  }
+  return `${first}${value.length > 1 ? ` (+${value.length - 1} more)` : ""}`;
+}
+function mcpPreview(args: Readonly<Record<string, unknown>>): string | undefined {
+  if (typeof args.tool === "string" && args.tool !== "") {
+    const server = typeof args.server === "string" && args.server !== "" ? `${args.server}/` : "";
+    const toolArgs =
+      typeof args.args === "string" && args.args !== "" ? ` ${args.args.slice(0, 40)}` : "";
+    return `${server}${args.tool}${toolArgs}`;
+  }
+  return undefined;
+}
+function primaryPreview(args: Readonly<Record<string, unknown>>): string | undefined {
+  const mcp = mcpPreview(args);
+  if (mcp !== undefined) {
+    return mcp;
+  }
+  const queries = array(args.queries);
+  if (queries !== undefined) {
+    return truncate(queries, 60);
+  }
+  if (typeof args.query === "string" && args.query.trim().length > 0) {
+    return truncate(args.query, 60);
+  }
+  if (typeof args.workflow === "string" && args.workflow.trim().length > 0) {
+    return `workflow=${truncate(args.workflow, 48)}`;
+  }
+  return undefined;
+}
+function secondaryPreview(args: Readonly<Record<string, unknown>>): string | undefined {
+  if (typeof args.url === "string" && args.url.trim().length > 0) {
+    return truncate(args.url, 60);
+  }
+  const urls = array(args.urls);
+  if (urls !== undefined) {
+    return truncate(urls, 60);
+  }
+  if (typeof args.prompt === "string" && args.prompt.trim().length > 0) {
+    return truncate(args.prompt, 60);
+  }
+  for (const key of [
+    "command",
+    "path",
+    "file_path",
+    "pattern",
+    "query",
+    "url",
+    "task",
+    "describe",
+    "search",
+  ]) {
+    const value = args[key];
+    if (typeof value === "string" && value !== "") {
+      return truncate(value, 60);
+    }
+  }
+  return undefined;
+}
+/** Ordered tool-specific previews, then the first printable unknown argument. */
+export function extractToolArgsPreview(args: Readonly<Record<string, unknown>>): string {
+  const selected = primaryPreview(args) ?? secondaryPreview(args);
+  if (selected !== undefined) {
+    return selected;
+  }
+  for (const [key, value] of Object.entries(args)) {
+    const preview = array(value);
+    if (preview !== undefined) {
+      return `${key}=${truncate(preview, 50)}`;
+    }
+    if (typeof value === "string" && value.length > 0) {
+      return `${key}=${truncate(value, 50)}`;
+    }
+  }
+  return "";
+}
+function partText(part: unknown): string {
+  if (!isRecord(part)) {
+    return "";
+  }
+  if (part.type === "tool_result") {
+    return extractTextFromContent(part.content);
+  }
+  return typeof part.text === "string" ? part.text : "";
+}
+/** External content is accepted only as strings or known text/content fields. */
+export function extractTextFromContent(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  return isUnknownArray(content)
+    ? content
+        .map(partText)
+        .filter((text) => text !== "")
+        .join("\n")
+    : "";
+}

package/src/shared/cooperative.ts

@@ -1,21 +1,25 @@
 import { setImmediate as yieldToInput } from "node:timers/promises";
 
 export function runSynchronously<T>(steps: Generator<void, T>): T {
-	let step = steps.next();
-	while (!step.done) step = steps.next();
-	return step.value;
+  let step = steps.next();
+  while (step.done !== true) {
+    step = steps.next();
+  }
+  return step.value;
 }
 
 /** Batched recovery and delivery leave room for input between records. */
 export async function runCooperatively<T>(steps: Generator<void, T>): Promise<T> {
-	let step = steps.next();
-	for (let count = 0; !step.done; step = steps.next()) {
-		// ponytail: one recovery record remains atomic; move a demonstrated
-		// single-record stall off-thread rather than increasing this batch size.
-		if (++count === 32) {
-			await yieldToInput();
-			count = 0;
-		}
-	}
-	return step.value;
+  let step = steps.next();
+  for (let count = 0; step.done !== true; step = steps.next()) {
+    // ponytail: one recovery record remains atomic; move a demonstrated
+    // single-record stall off-thread rather than increasing this batch size.
+    if (++count === 32) {
+      // Yield between ordered atomic recovery records; concurrency would reorder delivery.
+      // oxlint-disable-next-line no-await-in-loop
+      await yieldToInput();
+      count = 0;
+    }
+  }
+  return step.value;
 }

package/src/shared/execution-cwd.ts

@@ -1,14 +1,39 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { hasExecutionCwdOwner } from "../runs/shared/child-execution-cwd.ts";
+import type { ReadonlyInput } from "./types/inputs.ts";
 
+function validateDirectoryReply(
+  result: { readonly cwd?: string; readonly error?: string } | undefined,
+): void {
+  if (result?.error !== undefined && result.error !== "") {
+    throw new Error(result.error);
+  }
+  if (result && (result.cwd === undefined || result.cwd === "")) {
+    throw new Error("Working-directory owner did not return an execution directory.");
+  }
+}
 /** Capture the active directory owner once per invocation, before asynchronous preparation. */
-export function resolveExecutionCwd(pi: Pick<ExtensionAPI, "events"> & Partial<Pick<ExtensionAPI, "getAllTools" | "getCommands">>, ctx: ExtensionContext): string {
-	const request: { sessionManager: ExtensionContext["sessionManager"]; result?: { cwd?: string; error?: string } } = { sessionManager: ctx.sessionManager };
-	pi.events.emit("pi-change-working-dir:resolve-execution-cwd", request);
-	if (request.result?.error) throw new Error(request.result.error);
-	if (request.result && !request.result.cwd) throw new Error("Working-directory owner did not return an execution directory.");
-	if (!request.result && pi.getAllTools && pi.getCommands && hasExecutionCwdOwner({ getAllTools: pi.getAllTools, getCommands: pi.getCommands })) {
-		throw new Error("The loaded directory extension did not resolve the execution directory. Update pi-change-working-dir before delegating work.");
-	}
-	return request.result?.cwd ?? ctx.cwd;
+export function resolveExecutionCwd(
+  pi: ReadonlyInput<
+    Pick<ExtensionAPI, "events"> & Partial<Pick<ExtensionAPI, "getAllTools" | "getCommands">>
+  >,
+  ctx: ExtensionContext,
+): string {
+  const request: {
+    sessionManager: ExtensionContext["sessionManager"];
+    result?: { cwd?: string; error?: string };
+  } = { sessionManager: ctx.sessionManager };
+  pi.events.emit("pi-change-working-dir:resolve-execution-cwd", request);
+  validateDirectoryReply(request.result);
+  if (
+    !request.result &&
+    pi.getAllTools &&
+    pi.getCommands &&
+    hasExecutionCwdOwner({ getAllTools: pi.getAllTools, getCommands: pi.getCommands })
+  ) {
+    throw new Error(
+      "The loaded directory extension did not resolve the execution directory. Update pi-change-working-dir before delegating work.",
+    );
+  }
+  return request.result?.cwd ?? ctx.cwd;
 }

package/src/shared/file-coalescer.ts

@@ -1,29 +1,31 @@
 interface FileCoalescer {
-	schedule(file: string, delayMs?: number): boolean;
-	clear(): void;
+  readonly schedule: (file: string, delayMs?: number) => boolean;
+  readonly clear: () => void;
 }
 
 export function createFileCoalescer(
-	handler: (file: string) => void,
-	defaultDelayMs: number,
+  handler: (file: string) => void,
+  defaultDelayMs: number,
 ): FileCoalescer {
-	const pending = new Map<string, ReturnType<typeof setTimeout>>();
+  const pending = new Map<string, ReturnType<typeof setTimeout>>();
 
-	return {
-		schedule(file: string, delayMs = defaultDelayMs): boolean {
-			if (pending.has(file)) return false;
-			const timer = setTimeout(() => {
-				pending.delete(file);
-				handler(file);
-			}, delayMs);
-			pending.set(file, timer);
-			return true;
-		},
-		clear(): void {
-			for (const timer of pending.values()) {
-				clearTimeout(timer);
-			}
-			pending.clear();
-		},
-	};
+  return {
+    schedule(file: string, delayMs = defaultDelayMs): boolean {
+      if (pending.has(file)) {
+        return false;
+      }
+      const timer = setTimeout(() => {
+        pending.delete(file);
+        handler(file);
+      }, delayMs);
+      pending.set(file, timer);
+      return true;
+    },
+    clear(): void {
+      for (const timer of pending.values()) {
+        clearTimeout(timer);
+      }
+      pending.clear();
+    },
+  };
 }

package/src/shared/fork-context.ts

@@ -1,68 +1,72 @@
 import * as fs from "node:fs";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { requestChildExecutionCwd } from "../runs/shared/child-execution-cwd.ts";
+import { errorMessage } from "./unknown.ts";
 
 type SubagentExecutionContext = "fresh" | "fork";
 
 interface ForkableSessionManager {
-	getSessionFile(): string | undefined;
-	getLeafId(): string | null;
-	getSessionDir(): string;
+  readonly getSessionFile: () => string | undefined;
+  readonly getLeafId: () => string | null;
+  readonly getSessionDir: () => string;
 }
 
 interface ForkContextResolver {
-	sessionFileForIndex(index?: number): string | undefined;
+  readonly sessionFileForIndex: (index?: number) => string | undefined;
 }
 
-export function resolveSubagentContext(value: unknown): SubagentExecutionContext {
-	return value === "fork" ? "fork" : "fresh";
+export function resolveSubagentContext(value?: unknown): SubagentExecutionContext {
+  return value === "fork" ? "fork" : "fresh";
 }
 
 export function createForkContextResolver(
-	sessionManager: ForkableSessionManager,
-	requestedContext: unknown,
+  sessionManager: ForkableSessionManager,
 ): ForkContextResolver {
-	if (resolveSubagentContext(requestedContext) !== "fork") {
-		return {
-			sessionFileForIndex: () => undefined,
-		};
-	}
+  const parentSessionFile = sessionManager.getSessionFile();
+  if (parentSessionFile === undefined || parentSessionFile === "") {
+    throw new Error("Forked subagent context requires a persisted parent session.");
+  }
 
-	const parentSessionFile = sessionManager.getSessionFile();
-	if (!parentSessionFile) {
-		throw new Error("Forked subagent context requires a persisted parent session.");
-	}
+  const leafId = sessionManager.getLeafId();
+  if (leafId === null || leafId === "") {
+    throw new Error("Forked subagent context requires a current leaf to fork from.");
+  }
 
-	const leafId = sessionManager.getLeafId();
-	if (!leafId) {
-		throw new Error("Forked subagent context requires a current leaf to fork from.");
-	}
+  const sessionDir = sessionManager.getSessionDir();
+  const cachedSessionFiles = new Map<number, string>();
 
-	const sessionDir = sessionManager.getSessionDir();
-	const cachedSessionFiles = new Map<number, string>();
-
-	return {
-		sessionFileForIndex(index = 0): string | undefined {
-			const cached = cachedSessionFiles.get(index);
-			if (cached) return cached;
-			try {
-				if (!fs.existsSync(parentSessionFile)) {
-					throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
-				}
-				const sessionFile = SessionManager.open(parentSessionFile, sessionDir).createBranchedSession(leafId);
-				if (!sessionFile) {
-					throw new Error("Session manager did not return a forked session file.");
-				}
-				if (!fs.existsSync(sessionFile)) {
-					throw new Error(`Session manager returned a forked session file that does not exist: ${sessionFile}`);
-				}
-				requestChildExecutionCwd(sessionFile);
-				cachedSessionFiles.set(index, sessionFile);
-				return sessionFile;
-			} catch (error) {
-				const cause = error instanceof Error ? error : new Error(String(error));
-				throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
-			}
-		},
-	};
+  return {
+    sessionFileForIndex(index = 0): string | undefined {
+      const cached = cachedSessionFiles.get(index);
+      if (cached !== undefined && cached !== "") {
+        return cached;
+      }
+      try {
+        if (!fs.existsSync(parentSessionFile)) {
+          throw new Error(
+            `Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`,
+          );
+        }
+        const sessionFile = SessionManager.open(
+          parentSessionFile,
+          sessionDir,
+        ).createBranchedSession(leafId);
+        if (sessionFile === undefined || sessionFile === "") {
+          throw new Error("Session manager did not return a forked session file.");
+        }
+        if (!fs.existsSync(sessionFile)) {
+          throw new Error(
+            `Session manager returned a forked session file that does not exist: ${sessionFile}`,
+          );
+        }
+        requestChildExecutionCwd(sessionFile);
+        cachedSessionFiles.set(index, sessionFile);
+        return sessionFile;
+      } catch (error) {
+        throw new Error(`Failed to create forked subagent session: ${errorMessage(error)}`, {
+          cause: error,
+        });
+      }
+    },
+  };
 }

package/src/shared/formatters.ts

@@ -4,81 +4,122 @@
 
 import type { Usage } from "./types.ts";
 import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
+import type { ReadonlyDeep } from "type-fest";
 
 /**
  * Format token count with k suffix for large numbers
  */
 export function formatTokens(n: number): string {
-	return n < 1000 ? String(n) : n < 10000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
+  if (n < 1000) {
+    return String(n);
+  }
+  return n < 10000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
 }
 
 export function formatModelThinking(model?: string, thinking?: string): string {
-	const parsed = model ? splitKnownThinkingSuffix(model) : undefined;
-	const displayModel = parsed?.baseModel ?? model;
-	const explicitThinking = THINKING_LEVELS.find((level) => level === thinking?.trim());
-	const displayThinking = parsed?.thinkingSuffix ? parsed.thinkingSuffix.slice(1) : explicitThinking;
-	return [displayModel, displayThinking ? `thinking ${displayThinking}` : undefined].filter(Boolean).join(" · ");
+  const parsed = model !== undefined && model !== "" ? splitKnownThinkingSuffix(model) : undefined;
+  const displayModel = parsed?.baseModel ?? model;
+  const explicitThinking = THINKING_LEVELS.find((level) => level === thinking?.trim());
+  const displayThinking =
+    parsed?.thinkingSuffix !== undefined && parsed.thinkingSuffix !== ""
+      ? parsed.thinkingSuffix.slice(1)
+      : explicitThinking;
+  return [
+    displayModel,
+    displayThinking !== undefined && displayThinking !== ""
+      ? `thinking ${displayThinking}`
+      : undefined,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+function hasUsageValue(value: number): boolean {
+  return value !== 0 && !Number.isNaN(value);
 }
 
 /**
  * Format usage statistics into a compact string
  */
-export function formatUsage(u: Usage, model?: string): string {
-	const parts: string[] = [];
-	if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
-	if (u.input) parts.push(`in:${formatTokens(u.input)}`);
-	if (u.output) parts.push(`out:${formatTokens(u.output)}`);
-	if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
-	if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
-	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
-	if (model) parts.push(model);
-	return parts.join(" ");
+export function formatUsage(u: ReadonlyDeep<Usage>, model?: string): string {
+  const parts: string[] = [];
+  if (hasUsageValue(u.turns)) {
+    parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
+  }
+  if (hasUsageValue(u.input)) {
+    parts.push(`in:${formatTokens(u.input)}`);
+  }
+  if (hasUsageValue(u.output)) {
+    parts.push(`out:${formatTokens(u.output)}`);
+  }
+  if (hasUsageValue(u.cacheRead)) {
+    parts.push(`R${formatTokens(u.cacheRead)}`);
+  }
+  if (hasUsageValue(u.cacheWrite)) {
+    parts.push(`W${formatTokens(u.cacheWrite)}`);
+  }
+  if (hasUsageValue(u.cost)) {
+    parts.push(`$${u.cost.toFixed(4)}`);
+  }
+  if (model !== undefined && model !== "") {
+    parts.push(model);
+  }
+  return parts.join(" ");
 }
 
 /**
  * Format duration in human-readable form
  */
 export function formatDuration(ms: number): string {
-	if (ms < 1000) return `${ms}ms`;
-	if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-	return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  if (ms < 60000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  }
+  return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
 }
 
 /**
  * Format a tool call for display
  */
-export function formatToolCall(name: string, args: Record<string, unknown>, expanded = false): string {
-	switch (name) {
-		case "bash": {
-			const command = typeof args.command === "string" ? args.command : "";
-			const maxLength = expanded ? 240 : 60;
-			return `$ ${command.slice(0, maxLength)}${command.length > maxLength ? "..." : ""}`;
-		}
-		case "read":
-		case "write":
-		case "edit": {
-			const target = typeof args.path === "string"
-				? args.path
-				: typeof args.file_path === "string"
-					? args.file_path
-					: "";
-			return `${name} ${shortenPath(target)}`;
-		}
-		default: {
-			const s = JSON.stringify(args);
-			const maxLength = expanded ? 160 : 40;
-			return `${name} ${s.slice(0, maxLength)}${s.length > maxLength ? "..." : ""}`;
-		}
-	}
+export function formatToolCall(
+  name: string,
+  args: Readonly<Record<string, unknown>>,
+  expanded = false,
+): string {
+  switch (name) {
+    case "bash": {
+      const command = typeof args.command === "string" ? args.command : "";
+      const maxLength = expanded ? 240 : 60;
+      return `$ ${command.slice(0, maxLength)}${command.length > maxLength ? "..." : ""}`;
+    }
+    case "read":
+    case "write":
+    case "edit": {
+      let target = "";
+      if (typeof args.path === "string") {
+        target = args.path;
+      } else if (typeof args.file_path === "string") {
+        target = args.file_path;
+      }
+      return `${name} ${shortenPath(target)}`;
+    }
+    default: {
+      const s = JSON.stringify(args);
+      const maxLength = expanded ? 160 : 40;
+      return `${name} ${s.slice(0, maxLength)}${s.length > maxLength ? "..." : ""}`;
+    }
+  }
 }
 
 /**
  * Shorten a path by replacing home directory with ~
  */
 export function shortenPath(p: string): string {
-	const home = process.env.HOME;
-	if (home && p.startsWith(home)) {
-		return `~${p.slice(home.length)}`;
-	}
-	return p;
+  const home = process.env.HOME;
+  if (home !== undefined && home !== "" && p.startsWith(home)) {
+    return `~${p.slice(home.length)}`;
+  }
+  return p;
 }