@d3ara1n/pi-subagent 0.3.0 → 0.5.0

package/src/utils.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Unit tests for pi-subagent pure helpers.
+ *
+ * Zero-dependency: runs on node's built-in test runner.
+ *   node --test packages/pi-subagent/src/utils.test.ts
+ *
+ * These guard the bug fixes introduced during the improvement rounds:
+ * path-injection (sanitizeFilename), concurrency/abort/negative-active
+ * (AsyncSemaphore), provider-error word list (isProviderError), unknown-tool
+ * formatting (previewArgs), output truncation fallback (truncateOutput).
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import {
+	sanitizeFilename,
+	isProviderError,
+	AsyncSemaphore,
+	previewArgs,
+	truncateOutput,
+	formatTokens,
+	effectiveTimeout,
+	elapsedSeconds,
+} from "./utils.ts";
+import type { SubagentResult, SubagentRole } from "./types.ts";
+
+// ── sanitizeFilename: guards the path-injection fix ──
+describe("sanitizeFilename", () => {
+	test("never yields a path separator (no directory traversal)", () => {
+		// Core security contract: result contains no / or \, so it can't escape the dir via path.join.
+		for (const input of ["../../etc", "../passwd", "/etc/passwd", "a/b/c", "a\\b", "..", "///"]) {
+			const out = sanitizeFilename(input);
+			assert.ok(!out.includes("/"), `${input} -> "${out}" still contains /`);
+			assert.ok(!out.includes("\\"), `${input} -> "${out}" still contains \\`);
+		}
+	});
+	test("empty string falls back to unknown", () => {
+		assert.equal(sanitizeFilename(""), "unknown");
+	});
+	test("pure-dots collapses to unknown (leading dots stripped, rest empty)", () => {
+		assert.equal(sanitizeFilename(".."), "unknown");
+		assert.equal(sanitizeFilename("..."), "unknown");
+	});
+	test("special chars become underscores", () => {
+		assert.equal(sanitizeFilename("!!!"), "___");
+		assert.equal(sanitizeFilename("   "), "___");
+		assert.equal(sanitizeFilename("///"), "___");
+		assert.equal(sanitizeFilename("a/b/c"), "a_b_c");
+	});
+	test("keeps normal uuid/alnum/dots/dashes as-is", () => {
+		const id = "019eff4f-b603-7623-9eaa-17d32eb623d9";
+		assert.equal(sanitizeFilename(id), id);
+		assert.equal(sanitizeFilename("call_abc123.json"), "call_abc123.json");
+	});
+});
+
+// ── isProviderError: guards the #9 expanded word list ──
+describe("isProviderError", () => {
+	const mk = (stderr: string, errorMessage = ""): SubagentResult =>
+		({
+			stderr,
+			errorMessage,
+			role: "",
+			task: "",
+			exitCode: 0,
+			messages: [],
+			output: "",
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			activityLog: [],
+		}) as unknown as SubagentResult;
+
+	test("matches provider error keywords", () => {
+		const cases = [
+			"429 Too Many Requests",
+			"quota exceeded",
+			"rate limit exceeded",
+			"authentication error",
+			"request timeout",
+			"quota exhausted",
+			"service unavailable",
+			"503 Service Unavailable",
+			"internal server error",
+			"temporary failure",
+			"request declined",
+			"server overloaded",
+			"ECONNRESET",
+			"socket hang up",
+			"EPIPE",
+			"network error",
+			"connection refused",
+		];
+		for (const c of cases) {
+			assert.equal(isProviderError(mk(c)), true, `should match: ${c}`);
+		}
+	});
+	test("does not match business/programming errors", () => {
+		assert.equal(isProviderError(mk("TypeError: Cannot read properties of undefined")), false);
+		assert.equal(isProviderError(mk("Error: test failed, expected 5 got 3")), false);
+		assert.equal(isProviderError(mk("AssertionError: values differ")), false);
+		assert.equal(isProviderError(mk("")), false);
+	});
+	test("checks errorMessage too, not just stderr", () => {
+		assert.equal(isProviderError(mk("", "rate limited")), true);
+	});
+});
+
+// ── AsyncSemaphore: guards concurrency cap, negative-active, abort cleanup ──
+describe("AsyncSemaphore", () => {
+	test("never goes negative on extra release", async () => {
+		const s = new AsyncSemaphore(1);
+		await s.acquire();
+		s.release();
+		s.release();
+		s.release();
+		assert.equal((s as any).active, 0);
+	});
+	test("respects concurrency cap (queues beyond max)", async () => {
+		const s = new AsyncSemaphore(2);
+		await s.acquire();
+		await s.acquire();
+		let entered = false;
+		const p = s.acquire().then(() => {
+			entered = true;
+		});
+		await Promise.resolve();
+		await Promise.resolve();
+		assert.equal(entered, false); // still queued
+		s.release();
+		await p;
+		assert.equal(entered, true);
+	});
+	test("abort removes waiter from queue and rejects", async () => {
+		const s = new AsyncSemaphore(1);
+		await s.acquire();
+		const c = new AbortController();
+		const p = s.acquire(c.signal);
+		c.abort();
+		await assert.rejects(p);
+		assert.equal((s as any).waiters.length, 0);
+	});
+	test("releases queued waiters in FIFO order", async () => {
+		const s = new AsyncSemaphore(1);
+		await s.acquire();
+		const order: number[] = [];
+		const p1 = s.acquire().then(() => order.push(1));
+		const p2 = s.acquire().then(() => order.push(2));
+		const p3 = s.acquire().then(() => order.push(3));
+		s.release();
+		await p1;
+		s.release();
+		await p2;
+		s.release();
+		await p3;
+		assert.deepEqual(order, [1, 2, 3]);
+	});
+	test("acquires immediately when under cap", async () => {
+		const s = new AsyncSemaphore(3);
+		await s.acquire();
+		await s.acquire();
+		assert.equal((s as any).active, 2);
+	});
+});
+
+// ── previewArgs: guards the #10 shape-based formatting ──
+describe("previewArgs", () => {
+	test("command -> $ prefix", () => {
+		assert.equal(previewArgs({ command: "ls -la" }), "$ ls -la");
+	});
+	test("command truncated at 60 chars", () => {
+		const long = "x".repeat(70);
+		const r = previewArgs({ command: long });
+		assert.ok(r.startsWith("$ "));
+		assert.ok(r.endsWith("..."));
+		assert.ok(r.length < long.length);
+	});
+	test("file_path is shortened (home -> ~)", () => {
+		const r = previewArgs({ file_path: "/home/user/foo.ts" });
+		assert.ok(r.includes("foo.ts"));
+	});
+	test("url passthrough (truncated when long)", () => {
+		assert.equal(previewArgs({ url: "https://example.com" }), "https://example.com");
+		const longUrl = "https://" + "x".repeat(70);
+		assert.ok(previewArgs({ url: longUrl }).endsWith("..."));
+	});
+	test("query/pattern/regex/search -> /.../  form", () => {
+		assert.equal(previewArgs({ query: "foo" }), "/foo/");
+		assert.equal(previewArgs({ pattern: "bar" }), "/bar/");
+		assert.equal(previewArgs({ regex: "baz" }), "/baz/");
+		assert.equal(previewArgs({ search: "qux" }), "/qux/");
+	});
+	test("empty object falls back to JSON {}", () => {
+		assert.equal(previewArgs({}), "{}");
+	});
+});
+
+// ── effectiveTimeout: guards delegate-role auto-widening (seconds) ──
+describe("effectiveTimeout", () => {
+	const role = (tools: string[], timeout?: number): SubagentRole =>
+		({ role: "default", description: "", examples: [], decisionTrigger: "", tools, systemPrompt: "", timeout }) as unknown as SubagentRole;
+
+	test("non-delegate role uses base timeout", () => {
+		assert.equal(effectiveTimeout(role(["read", "grep"]), 600), 600);
+	});
+	test("delegate role doubles base when no explicit timeout", () => {
+		assert.equal(effectiveTimeout(role(["read", "delegate"]), 600), 1200);
+	});
+	test("explicit roleDef.timeout is always honored (no widening)", () => {
+		assert.equal(effectiveTimeout(role(["read", "delegate"], 300), 600), 300);
+	});
+	test("explicit timeout on non-delegate also honored", () => {
+		assert.equal(effectiveTimeout(role(["read"]), 600), 600);
+	});
+});
+
+// ── truncateOutput: guards the #2 head+tail fallback ──
+describe("truncateOutput", () => {
+	test("adds truncation header with original length", () => {
+		const big = "x".repeat(60000);
+		const r = truncateOutput(big);
+		assert.ok(r.startsWith("[Output truncated"));
+		assert.ok(r.includes("60000 chars total"));
+		assert.ok(r.includes("[truncated]"));
+	});
+	test("keeps head and tail, drops the middle", () => {
+		// 120000 chars: 40k H + 40k M + 40k T
+		const content = "H".repeat(40000) + "M".repeat(40000) + "T".repeat(40000);
+		const r = truncateOutput(content);
+		assert.ok(r.includes("H"), "head preserved");
+		assert.ok(r.includes("T"), "tail preserved");
+		assert.ok(!r.includes("M"), "middle dropped");
+	});
+});
+
+// ── formatTokens: boundary correctness ──
+describe("formatTokens", () => {
+	test("under 1000 stays raw", () => {
+		assert.equal(formatTokens(0), "0");
+		assert.equal(formatTokens(999), "999");
+	});
+	test("1000-9999 with one decimal place", () => {
+		assert.equal(formatTokens(1000), "1.0k");
+		assert.equal(formatTokens(9500), "9.5k");
+		// 9999/1000 = 9.999, toFixed(1) rounds up to 10.0
+		assert.equal(formatTokens(9999), "10.0k");
+	});
+	test("10000-999999 rounded to integer k", () => {
+		assert.equal(formatTokens(10000), "10k");
+		assert.equal(formatTokens(999999), "1000k");
+	});
+	test(">= 1000000 in M", () => {
+		assert.equal(formatTokens(1000000), "1.0M");
+	});
+});
+
+// ── elapsedSeconds: live/terminal time derivation ──
+describe("elapsedSeconds", () => {
+	test("terminal state: rounds elapsedMs to whole seconds", () => {
+		assert.equal(elapsedSeconds({ exitCode: 0, elapsedMs: 12345 }), 12);
+		assert.equal(elapsedSeconds({ exitCode: 0, elapsedMs: 400 }), 0);
+		assert.equal(elapsedSeconds({ exitCode: 1, elapsedMs: 59999 }), 60);
+	});
+	test("terminal state without elapsedMs -> undefined", () => {
+		assert.equal(elapsedSeconds({ exitCode: 0 }), undefined);
+	});
+	test("queued (running sentinel, no startTime) -> undefined", () => {
+		assert.equal(elapsedSeconds({ exitCode: -1 }), undefined);
+	});
+	test("running: live seconds from startTime (within ~1s drift)", () => {
+		const start = Date.now() - 3500;
+		const s = elapsedSeconds({ exitCode: -1, startTime: start });
+		assert.ok(s !== undefined, "should be defined while running");
+		assert.ok(s >= 3 && s <= 4, `expected ~3s, got ${s}`);
+	});
+	test("running: clamps negative drift (future startTime) to 0", () => {
+		const start = Date.now() + 10000; // 10s in the future
+		assert.equal(elapsedSeconds({ exitCode: -1, startTime: start }), 0);
+	});
+});

package/src/utils.ts

@@ -0,0 +1,286 @@
+/**
+ * Pure helpers for pi-subagent: formatting, sanitization, formatting helpers,
+ * and the concurrency semaphore. No pi-API or I/O dependencies — safe to unit-test.
+ *
+ * Extracted from index.ts so these can be exercised directly. index.ts imports
+ * them; behavior is unchanged.
+ */
+
+import * as os from "node:os";
+import type { ActivityEntry, SubagentRole, SubagentResult, ToolStatus } from "./types.ts";
+
+/** Max output chars fed to the main model and the expanded TUI. Larger outputs are compressed (or truncated) to fit. */
+export const MAX_OUTPUT_CHARS = 50_000;
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}
+
+export function formatUsageStats(usage: SubagentResult["usage"], model?: string): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`\u2191${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`\u2193${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+/**
+ * 计算用于展示的运行耗时（秒）。
+ * - 运行中（exitCode === -1 且有 startTime）：基于墙钟实时计算；
+ * - 终态（exitCode !== -1 且有 elapsedMs）：冻结值；
+ * - queued 或字段缺失：undefined（调用方应跳过耗时展示）。
+ *
+ * 用结构子集而非 SubagentResult，便于在无需引入完整类型的纯工具上下文中复用与测试。
+ */
+export function elapsedSeconds(r: {
+	exitCode: number;
+	startTime?: number;
+	elapsedMs?: number;
+}): number | undefined {
+	if (r.exitCode === -1 && typeof r.startTime === "number") {
+		return Math.max(0, Math.round((Date.now() - r.startTime) / 1000));
+	}
+	if (r.exitCode !== -1 && typeof r.elapsedMs === "number") {
+		return Math.round(r.elapsedMs / 1000);
+	}
+	return undefined;
+}
+
+export type DisplayItem =
+	| { type: "toolCall"; name: string; args: Record<string, any>; status?: ToolStatus }
+	| { type: "thinking"; status?: ToolStatus };
+
+/** Map the real-time activity log into renderable display items (in order). */
+export function buildDisplayItems(activityLog: ActivityEntry[]): DisplayItem[] {
+	return activityLog.map((a) =>
+		a.kind === "thinking"
+			? { type: "thinking", status: a.status }
+			: { type: "toolCall", name: a.toolName ?? "?", args: a.args ?? {}, status: a.status },
+	);
+}
+
+export function shortenPath(p: string): string {
+	const home = os.homedir();
+	if (process.platform === "win32") {
+		return p.toLowerCase().startsWith(home.toLowerCase()) ? `~${p.slice(home.length)}` : p;
+	}
+	return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
+export function formatToolCall(
+	toolName: string,
+	args: Record<string, unknown>,
+	fg: (color: string, text: string) => string,
+): string {
+	switch (toolName) {
+		case "delegate": {
+			const subRole = args.role as string | undefined;
+			return fg("muted", "delegate ") + fg("accent", subRole ?? "...");
+		}
+		case "bash": {
+			const command = (args.command as string) || "...";
+			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+			return fg("muted", "$ ") + fg("toolOutput", preview);
+		}
+		case "read": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			const filePath = shortenPath(rawPath);
+			const offset = args.offset as number | undefined;
+			const limit = args.limit as number | undefined;
+			let text = fg("accent", filePath);
+			if (offset !== undefined || limit !== undefined) {
+				const startLine = offset ?? 1;
+				const endLine = limit !== undefined ? startLine + limit - 1 : "";
+				text += fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			}
+			return fg("muted", "read ") + text;
+		}
+		case "write": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			const content = (args.content || "") as string;
+			const lines = content.split("\n").length;
+			let text = fg("muted", "write ") + fg("accent", shortenPath(rawPath));
+			if (lines > 1) text += fg("dim", ` (${lines} lines)`);
+			return text;
+		}
+		case "edit": {
+			const rawPath = (args.file_path || args.path || "...") as string;
+			return fg("muted", "edit ") + fg("accent", shortenPath(rawPath));
+		}
+		case "grep": {
+			const pattern = (args.pattern || "") as string;
+			const rawPath = (args.path || ".") as string;
+			return fg("muted", "grep ") + fg("accent", `/${pattern}/`) + fg("dim", ` in ${shortenPath(rawPath)}`);
+		}
+		case "find": {
+			const pattern = (args.pattern || "*") as string;
+			return fg("muted", "find ") + fg("accent", pattern);
+		}
+		case "glob": {
+			const pattern = (args.pattern || "*") as string;
+			return fg("muted", "glob ") + fg("accent", pattern);
+		}
+		default: {
+			const preview = previewArgs(args);
+			return fg("accent", toolName) + (preview ? fg("dim", ` ${preview}`) : "");
+		}
+	}
+}
+
+/** Per-tool-call visual styling: prefix glyph + color function keyed by status. */
+export function statusStyle(
+	status: ToolStatus | undefined,
+	fg: (color: string, text: string) => string,
+): { prefix: string; color: (c: string, text: string) => string } {
+	switch (status) {
+		case "running":
+			return { prefix: fg("accent", "\u2192 "), color: fg };
+		case "failed":
+			return { prefix: fg("error", "\u2717 "), color: (_c, text) => fg("error", text) };
+		case "done":
+		default:
+			return { prefix: fg("dim", "\u2022 "), color: (_c, text) => fg("dim", text) };
+	}
+}
+
+/** Render a thinking-block row: diamond glyph + label, colored by status.
+ * Running = hollow diamond (unformed thought); done = solid diamond (settled). */
+export function formatThinking(
+	status: ToolStatus | undefined,
+	fg: (color: string, text: string) => string,
+): string {
+	if (status === "running") {
+		return fg("accent", "\u25C7 thinking");
+	}
+	// done (or unknown) — dim past tense, solid diamond
+	return fg("dim", "\u25C6 thought");
+}
+
+export function renderDisplayItems(
+	items: DisplayItem[],
+	limit: number | undefined,
+	fg: (color: string, text: string) => string,
+): string {
+	const toShow = limit ? items.slice(-limit) : items;
+	const skipped = limit && items.length > limit ? items.length - limit : 0;
+	let text = "";
+	if (skipped > 0) text += fg("muted", `... ${skipped} earlier items\n`);
+	for (const item of toShow) {
+		if (item.type === "thinking") {
+			text += `${formatThinking(item.status, fg)}\n`;
+		} else {
+			const { prefix, color } = statusStyle(item.status, fg);
+			text += `${prefix}${formatToolCall(item.name, item.args, color)}\n`;
+		}
+	}
+	return text.trimEnd();
+}
+
+export function isFailedResult(r: SubagentResult): boolean {
+	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted" || r.stopReason === "timeout";
+}
+
+/** Heuristic: does this result look like a provider-side failure worth retrying on the fallback role? */
+export function isProviderError(result: SubagentResult): boolean {
+	const haystack = `${result.stderr || ""}\n${result.errorMessage || ""}`;
+	return /429|quota|rate.?limit|auth|timeout|exhausted|unavailable|503|server error|temporary|declined|overloaded|econnreset|socket hang up|epipe|network|connection/i.test(haystack);
+}
+
+/** Shape-based preview for tools we don't have a dedicated formatter for. */
+export function previewArgs(args: Record<string, unknown>): string {
+	const command = args.command as string | undefined;
+	if (command) return `$ ${command.length > 60 ? command.slice(0, 60) + "..." : command}`;
+	const fp = (args.file_path || args.path) as string | undefined;
+	if (fp) return shortenPath(fp);
+	const url = args.url as string | undefined;
+	if (url) return url.length > 60 ? url.slice(0, 60) + "..." : url;
+	const query = (args.query || args.pattern || args.regex || args.search) as string | undefined;
+	if (query) return `/${query.length > 60 ? query.slice(0, 60) + "..." : query}/`;
+	const argsStr = JSON.stringify(args);
+	return argsStr.length > 50 ? argsStr.slice(0, 50) + "..." : argsStr;
+}
+
+// ── Concurrency gate ───────────────────────────────────────────────
+
+/**
+ * Promise-based semaphore capping concurrent subagent spawns.
+ * acquire() resolves immediately while under the limit, otherwise queues.
+ * Pass an AbortSignal to cancel while waiting (rejects and removes the waiter).
+ */
+export class AsyncSemaphore {
+	private active = 0;
+	private waiters: Array<() => void> = [];
+	private max: number;
+	constructor(max: number) {
+		this.max = max;
+	}
+	async acquire(signal?: AbortSignal): Promise<void> {
+		if (this.active < this.max) {
+			this.active++;
+			return;
+		}
+		return new Promise<void>((resolve, reject) => {
+			const wakeup = () => {
+				signal?.removeEventListener("abort", onAbort);
+				this.active++;
+				resolve();
+			};
+			const onAbort = () => {
+				signal?.removeEventListener("abort", onAbort);
+				const idx = this.waiters.indexOf(wakeup);
+				if (idx >= 0) this.waiters.splice(idx, 1);
+				reject(new Error("aborted while waiting for concurrency slot"));
+			};
+			this.waiters.push(wakeup);
+			if (signal) {
+				if (signal.aborted) {
+					onAbort();
+					return;
+				}
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+		});
+	}
+	release(): void {
+		this.active = Math.max(0, this.active - 1);
+		const next = this.waiters.shift();
+		if (next) next();
+	}
+}
+
+// ── Timeout policy ────────────────────────────────────────
+
+/**
+ * Effective per-role timeout. Roles that can `delegate` need headroom for
+ * nested runs to complete, so when no explicit per-role timeout is set we
+ * double the base. An explicit roleDef.timeout (seconds) is always honored as-is.
+ * All inputs/outputs are in SECONDS — convert to ms at the spawn boundary.
+ */
+export function effectiveTimeout(roleDef: SubagentRole, baseTimeoutSec: number): number {
+	const canDelegate = (roleDef.tools ?? []).includes("delegate");
+	if (canDelegate && roleDef.timeout == null) {
+		return baseTimeoutSec * 2;
+	}
+	return roleDef.timeout ?? baseTimeoutSec;
+}
+
+// ── Output truncation ────────────────────────────────────────
+
+/** Strip path separators / traversal so sessionId/toolCallId can't escape the history dir. */
+export function sanitizeFilename(s: string): string {
+	return s.replace(/[^\w.-]/g, "_").replace(/^[.]+/, "") || "unknown";
+}
+
+/** Mechanical fallback: keep head (findings) + tail (summary), drop the middle. */
+export function truncateOutput(t: string): string {
+	const head = t.slice(0, 30_000);
+	const tail = t.slice(-(MAX_OUTPUT_CHARS - 30_050));
+	return `[Output truncated — ${t.length} chars total]\n\n${head}\n\n... [truncated] ...\n\n${tail}`;
+}