@gavin-hu/my-pi-agent 0.13.1 → 0.15.0

package/lib/pdf.ts

@@ -0,0 +1,82 @@
+/**
+ * The optional `unpdf` seam: lazy load, module-shape handling, and text
+ * extraction, shared by `web-access` and `document`.
+ *
+ * `unpdf` bundles a server-friendly build of PDF.js, so it is imported lazily:
+ * an extension registers on every session, and a parser should load only when a
+ * read actually needs it. `web-access` treats the package as optional and
+ * reports {@link pdfGuidance} when it is absent; `document` ships it as a
+ * dependency. Both get the same loader, the same merged-pages call, and the same
+ * result unwrapping, so a PDF reads the same way through either surface.
+ *
+ * Value-only: no module state, and no import of `unpdf` until a caller asks.
+ */
+
+/** Install command for the optional PDF extractor package. */
+const UNPDF_INSTALL = "npm i unpdf";
+
+/** Model-facing guidance when the optional `unpdf` package is absent. */
+export function pdfGuidance(): string {
+	return `PDF extraction requires the optional 'unpdf' package (${UNPDF_INSTALL}).`;
+}
+
+/** Raised when `unpdf` is missing or does not expose `extractText`. */
+export class PdfUnavailableError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PdfUnavailableError";
+	}
+}
+
+/** Extract merged page text from PDF bytes. */
+export type PdfExtractor = (bytes: Uint8Array) => Promise<string>;
+
+/** Pull the merged text out of `unpdf`'s `{ totalPages, text }` result. Pure. */
+export function pdfTextFromResult(result: unknown): string {
+	if (typeof result === "string") return result;
+	const text = (result as { text?: unknown } | undefined)?.text;
+	return typeof text === "string" ? text : "";
+}
+
+/** The `extractText` function of an imported `unpdf` module, when it exposes one. */
+function extractTextOf(module: unknown): ((bytes: Uint8Array, options?: unknown) => Promise<unknown>) | undefined {
+	if (typeof module !== "object" || module === null) return undefined;
+	const named = (module as { extractText?: unknown }).extractText;
+	if (typeof named === "function") return named as (bytes: Uint8Array, options?: unknown) => Promise<unknown>;
+	const fallback = (module as { default?: unknown }).default;
+	if (typeof fallback !== "object" || fallback === null) return undefined;
+	const nested = (fallback as { extractText?: unknown }).extractText;
+	if (typeof nested !== "function") return undefined;
+	return nested as (bytes: Uint8Array, options?: unknown) => Promise<unknown>;
+}
+
+/**
+ * Build an extractor from an imported `unpdf` module.
+ *
+ * `unpdf` exports `extractText` directly; the default-export fallback tolerates
+ * a build that wraps it. Anything else is a broken install, reported with the
+ * same error the missing-package path uses.
+ */
+export function pdfExtractorFromModule(module: unknown): PdfExtractor {
+	const extractText = extractTextOf(module);
+	if (!extractText) throw new PdfUnavailableError("The installed 'unpdf' package does not export extractText.");
+	return async (bytes) => pdfTextFromResult(await extractText(bytes, { mergePages: true }));
+}
+
+/** Load `unpdf` lazily, or throw {@link PdfUnavailableError} with install guidance. */
+export async function loadPdfExtractor(): Promise<PdfExtractor> {
+	let module: unknown;
+	try {
+		module = await import("unpdf");
+	} catch {
+		throw new PdfUnavailableError(pdfGuidance());
+	}
+	return pdfExtractorFromModule(module);
+}
+
+/** Extract merged page text from PDF bytes, using `extractor` when given. */
+export async function extractPdfText(bytes: Uint8Array, extractor?: PdfExtractor): Promise<string> {
+	if (extractor) return extractor(bytes);
+	const loaded = await loadPdfExtractor();
+	return loaded(bytes);
+}

package/lib/plan-entry.ts

@@ -0,0 +1,71 @@
+/**
+ * Plan-mode entry, shared by the extension that owns the mode and the one that
+ * offers it as a phase of the goal.
+ *
+ * Plan mode has one owner: `plan` gates the tools, persists the flag, and draws
+ * the footer. A tool context can reach it through `ctx.executeTool`, but a
+ * command context cannot (`ExtensionCommandContext` has no `executeTool`), so the
+ * request travels on `pi.events` as an in-process request/response. The caller
+ * asks the user — with the consent sentence below — and `plan` enables without a
+ * second dialog, so the session never asks twice for one decision.
+ *
+ * The consent sentence and the read-only summary live here because two
+ * extensions show them: one copy each is how a trust guarantee drifts apart.
+ * Value-only, as `lib/` must be: the state is the caller's context and a closure,
+ * never a module variable.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isPlanModeEnabled } from "./plan-state.ts";
+import { PLAN_ENTER_TOOL } from "./tool-names.ts";
+
+/** EventBus channel on which a caller asks `plan` to enable plan mode. */
+export const PLAN_ENTER_REQUEST = "my-pi-agent/plan-mode/enter";
+
+/** One clause describing the read-only guarantee, reused across prompts. */
+export const READ_ONLY_SUMMARY =
+	"write and edit are disabled, bash is limited to read-only git commands, and other mutating tools are blocked; " +
+	"subagent delegation is forced read-only, and the only file write is write_plan (under .pi/plans, or the agent " +
+	"directory outside a repository)";
+
+/**
+ * The consent question, as the user sees it. Shown by `enter_plan_mode` and by
+ * any caller that offers plan mode itself, so both describe the same guarantee.
+ */
+export const PLAN_CONSENT =
+	`Plan mode is read-only exploration: ${READ_ONLY_SUMMARY}. ` +
+	"Enter plan mode to investigate and propose an approach before making changes?";
+
+/** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
+export interface PlanEnterRequest {
+	/** The caller's context; `plan` uses it for the footer status. */
+	ctx: ExtensionContext;
+	/** Called once, synchronously, with whether plan mode is on. */
+	respond(entered: boolean): void;
+}
+
+/**
+ * Ask `plan` to turn plan mode on, and report whether it is on afterwards.
+ *
+ * Resolves `true` without asking when the branch is already planning, and
+ * `false` when the `plan` tool is not registered — so `goal` loaded alone keeps
+ * working and nothing waits on a listener that is not there. The listener answers
+ * synchronously; the microtask is the fallback that guarantees resolution.
+ */
+export function requestPlanMode(
+	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
+	ctx: ExtensionContext,
+): Promise<boolean> {
+	if (isPlanModeEnabled(ctx.sessionManager.getBranch())) return Promise.resolve(true);
+	if (!pi.getAllTools().some((tool) => tool.name === PLAN_ENTER_TOOL)) return Promise.resolve(false);
+	return new Promise<boolean>((resolve) => {
+		let settled = false;
+		const respond = (entered: boolean): void => {
+			if (settled) return;
+			settled = true;
+			resolve(entered);
+		};
+		pi.events.emit(PLAN_ENTER_REQUEST, { ctx, respond } satisfies PlanEnterRequest);
+		queueMicrotask(() => respond(false));
+	});
+}

package/lib/plan-state.ts

@@ -0,0 +1,34 @@
+/**
+ * The plan-mode flag as the session branch carries it.
+ *
+ * Plan mode persists one custom entry (`plan-mode`) whose `enabled` field is the
+ * last word on the branch. `plan` writes it; `rewind` reads it through this
+ * module so `/review` cannot write while planning, without importing another
+ * extension's modules.
+ *
+ * Value-only: a constant and a pure replay over untrusted branch entries.
+ */
+
+/** Custom-entry type plan mode persists. */
+export const PLAN_MODE_ENTRY_TYPE = "plan-mode";
+
+/**
+ * Whether the branch's last valid plan-mode entry is enabled.
+ *
+ * Branch data is untrusted: an entry with the wrong type, a malformed `data`, or
+ * a non-boolean `enabled` is skipped rather than read as false. The last valid
+ * entry wins, so a later disable turns it off and a `/tree` restore follows the
+ * branch it lands on.
+ */
+export function isPlanModeEnabled(entries: readonly unknown[]): boolean {
+	let enabled = false;
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as { type?: unknown; customType?: unknown; data?: unknown };
+		if (entry.type !== "custom" || entry.customType !== PLAN_MODE_ENTRY_TYPE) continue;
+		if (!entry.data || typeof entry.data !== "object") continue;
+		const value = (entry.data as { enabled?: unknown }).enabled;
+		if (typeof value === "boolean") enabled = value;
+	}
+	return enabled;
+}

package/lib/report.ts

@@ -0,0 +1,99 @@
+/**
+ * The pending-report coordinator: how a live feature tells the model what
+ * happened without interrupting it.
+ *
+ * A watcher match and a finished job follow one rule — report at the next turn,
+ * and raise at most one triggered turn when the work opted into `wake`. The two
+ * traps are subtle enough to have been re-derived once per extension:
+ *
+ * - a wake is only safe while the agent is idle, so an outcome that arrives
+ *   mid-turn must be queued rather than sent;
+ * - between the triggered send and the `agent_start` it causes, the agent still
+ *   looks idle, so a second outcome in that window must not trigger a second
+ *   turn. `waking` closes that window.
+ *
+ * Delivery is one shared transcript notice per burst, and a burst is marked
+ * reported only after the send succeeded, so a throw leaves it for the next
+ * turn. Value-only: every flag lives in the returned closure, never in a module
+ * variable, because each extension gets its own module instance.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { pruneStaleNotices, type NoticeMessage } from "./notice.ts";
+
+export interface PendingReporterOptions<T> {
+	/** Send a notice and ask the host to start one turn for it. */
+	wake(notice: NoticeMessage): void;
+	/** The outcomes not yet reported, oldest first. Does not mark them. */
+	pending(): T[];
+	/** Mark outcomes as reported, once the send has succeeded. */
+	markReported(items: T[]): void;
+	/** Build the notice for one burst: model text plus renderer details. */
+	buildNotice(items: T[]): NoticeMessage;
+	/** The notice's source, so only its own stale entries are pruned. */
+	source: string;
+	/** Runs after a wake turn was successfully requested, for an extra announcement. */
+	onWoke?(items: T[]): void;
+}
+
+/** The handlers an extension wires into its lifecycle hooks. */
+export interface PendingReporter {
+	/** An outcome arrived: wake a turn if the agent is idle, else leave it queued. */
+	report(): void;
+	/** A new session starts idle. */
+	sessionStart(): void;
+	/** A turn began: outcomes queue up, and none of them triggers a turn. */
+	agentStart(): void;
+	/** The turn settled: a later outcome may wake again. */
+	agentSettled(): void;
+	/** Report what is queued at the start of a turn, without triggering one. */
+	beforeAgentStart(): { message: NoticeMessage } | undefined;
+	/** Drop this source's older notices from the outgoing context. */
+	filterContext(messages: readonly AgentMessage[]): { messages: AgentMessage[] } | undefined;
+}
+
+export function createPendingReporter<T>(options: PendingReporterOptions<T>): PendingReporter {
+	const { wake, pending, markReported, buildNotice, source, onWoke } = options;
+	let busy = false;
+	let waking = false;
+
+	return {
+		report: () => {
+			if (busy || waking) return;
+			const items = pending();
+			if (items.length === 0) return;
+			try {
+				wake(buildNotice(items));
+			} catch {
+				// Reporting is best-effort; the next turn reports the same items.
+				return;
+			}
+			// Mark only after the send succeeded, so a throw changes nothing.
+			markReported(items);
+			waking = true;
+			onWoke?.(items);
+		},
+		sessionStart: () => {
+			busy = false;
+			waking = false;
+		},
+		agentStart: () => {
+			busy = true;
+		},
+		agentSettled: () => {
+			busy = false;
+			waking = false;
+		},
+		beforeAgentStart: () => {
+			const items = pending();
+			if (items.length === 0) return undefined;
+			const notice = buildNotice(items);
+			markReported(items);
+			return { message: notice };
+		},
+		filterContext: (messages) => {
+			const pruned = pruneStaleNotices(messages, source);
+			return pruned ? { messages: pruned } : undefined;
+		},
+	};
+}

package/lib/requirements.ts

@@ -17,6 +17,7 @@
 import { join } from "node:path";
 import { configSection, configValueAt, type JsonReadResult, SHARED_CONFIG_FILE } from "./config.ts";
 import type { WebSearchProviderEvent } from "./events.ts";
+import { pdfGuidance } from "./pdf.ts";
 import { getPiInvocation, type PiInvocation } from "./pi-invocation.ts";
 
 /** How a check came out. Only `missing` is worth interrupting a session for. */
@@ -167,19 +168,6 @@ export interface ExtensionReport {
 	findings: Finding[];
 }
 
-// --- Install guidance -------------------------------------------------------
-//
-// Moved here from the extensions that raise it, so `doctor` and the tool error
-// say the same thing. Formatting only: no extension-specific logic.
-
-/** Install command for the optional PDF extractor package. */
-const UNPDF_INSTALL = "npm i unpdf";
-
-/** Model-facing guidance when the optional `unpdf` package is absent. */
-export function pdfGuidance(): string {
-	return `PDF extraction requires the optional 'unpdf' package (${UNPDF_INSTALL}).`;
-}
-
 // --- The table --------------------------------------------------------------
 
 /**
@@ -224,6 +212,9 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	todo: {},
 	goal: {},
+	check: {
+		notes: ["Runs the project's detected command through a shell; a stack with no detector needs `check.command`."],
+	},
 	plan: {
 		optional: [gitCheck("project-local `.pi/plans` (otherwise plans land in the agent directory)")],
 		notes: ["Needs an interactive UI to enter plan mode."],
@@ -769,19 +760,34 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 	return { extension, enabled, findings };
 }
 
+/** Probes in flight at once: enough to hide spawn latency, not a burst. */
+export const PROBE_CONCURRENCY = 4;
+
 /**
- * Probe every declared extension, or just `names`, in declaration order.
+ * Probe every declared extension, or just `names`, keeping declaration order.
  *
- * Sequential on purpose: the caller runs this on a session-start budget, and a
- * burst of parallel probes would trade a few milliseconds for a burst of child
- * processes.
+ * The caller is a user-facing report (`run_doctor`) or the panel's refresh, so
+ * the probes run a few at a time: a serial pass pays the sum of every spawn and
+ * read, while one `Promise.all` over the whole table starts a burst of child
+ * processes. The startup check does not come through here; it probes only the
+ * hard requirements, all at once (see `probeRequired`).
  */
 export async function probeAll(
 	seams: ProbeSeams,
 	names: readonly string[] = Object.keys(REQUIREMENTS),
 ): Promise<ExtensionReport[]> {
-	const reports: ExtensionReport[] = [];
-	for (const name of names) reports.push(await probeExtension(name, seams));
+	const reports = new Array<ExtensionReport>(names.length);
+	let cursor = 0;
+	/** Take the next name until the queue is empty; each worker keeps its slot. */
+	const drain = async (): Promise<void> => {
+		while (cursor < names.length) {
+			const index = cursor;
+			cursor += 1;
+			reports[index] = await probeExtension(names[index], seams);
+		}
+	};
+	const workers = Array.from({ length: Math.min(PROBE_CONCURRENCY, names.length) }, () => drain());
+	await Promise.all(workers);
 	return reports;
 }
 

package/lib/spawn.ts

@@ -0,0 +1,170 @@
+/**
+ * The process seam shared by the extensions that run a shell command.
+ *
+ * `job`, `watch`, and `check` all start a command in its own process group,
+ * stream or discard its output, and kill the whole tree — a signal to the POSIX
+ * group, or `taskkill /T` on Windows. Only the policy on top differs (durable
+ * jobs, a tailed watcher, a bounded check), so the seam lives here.
+ *
+ * IO is split from the decision: {@link spawnOptions} and {@link killPlan} are
+ * pure and testable on every platform, while {@link defaultSpawn} and
+ * {@link defaultKillTree} execute them. Value-only, like every `lib/` module:
+ * no module state, and each caller keeps its own children.
+ */
+
+import { spawn as nodeSpawn, spawnSync } from "node:child_process";
+import type { Readable } from "node:stream";
+
+/**
+ * The writable end of a child's stdin pipe.
+ *
+ * Only the operations a caller needs, so tests can hand the runtime a recording
+ * double instead of a real socket.
+ */
+export interface StdinSink {
+	write(chunk: string): boolean;
+	end(): void;
+	destroy?(): void;
+	on(event: "error" | "close", listener: (error?: Error) => void): unknown;
+}
+
+/** The subset of a spawned child the extensions use. */
+export interface SpawnedProcess {
+	pid?: number;
+	stdout: Readable | null;
+	stderr: Readable | null;
+	/** Present only when the child was spawned with `stdin: true`. */
+	stdin?: StdinSink | null;
+	on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+	on(event: "error", listener: (error: Error) => void): unknown;
+	kill(signal?: NodeJS.Signals): boolean;
+	/** Detach from the parent's event loop, so a child cannot hold Pi open. */
+	unref?(): void;
+}
+
+export interface SpawnOptions {
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+	/** Give the child a stdin pipe instead of a closed stdin (no immediate EOF). */
+	stdin?: boolean;
+	/** The command writes its own output to a log; keep no parent pipe. */
+	detachOutput?: boolean;
+}
+
+export type SpawnFn = (command: string, options: SpawnOptions) => SpawnedProcess;
+
+/** Send `signal` to a pid's process tree, escalating to SIGKILL when `force`. */
+export type KillTreeFn = (pid: number, signal: NodeJS.Signals, force?: boolean) => void;
+
+/** The `stdio` triple a spawn needs: stdin, stdout, stderr. */
+export type SpawnStdio = ["pipe" | "ignore", "pipe" | "ignore", "pipe" | "ignore"];
+
+/** The `child_process.spawn` options this seam produces. */
+export interface NodeSpawnOptions {
+	cwd: string;
+	shell: boolean;
+	detached: boolean;
+	stdio: SpawnStdio;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The spawn options for one command: a shell in its own process group, so a
+ * signal can reach the shell and its descendants together.
+ *
+ * Stdin stays closed unless asked for, because a closed stdin gives the child
+ * EOF — a `read` exits instead of blocking forever. `detachOutput` keeps no
+ * parent pipe, for a child that writes its own log file.
+ */
+export function spawnOptions(options: SpawnOptions, platform: NodeJS.Platform = process.platform): NodeSpawnOptions {
+	return {
+		cwd: options.cwd,
+		shell: true,
+		detached: platform !== "win32",
+		stdio: [
+			options.stdin ? "pipe" : "ignore",
+			options.detachOutput ? "ignore" : "pipe",
+			options.detachOutput ? "ignore" : "pipe",
+		],
+		env: options.env,
+	};
+}
+
+/** What killing a pid's tree means on this platform. */
+export interface KillPlan {
+	/** A program to run instead of signalling (Windows has no process group). */
+	command?: { file: string; args: string[] };
+	/**
+	 * Pids to signal in order: the process group first, then the pid itself for a
+	 * child that is not a group leader (a reattached pid, for example).
+	 */
+	targets: number[];
+}
+
+/** The kill plan for `pid`: `taskkill /T` on Windows, group-then-pid otherwise. */
+export function killPlan(pid: number, force: boolean, platform: NodeJS.Platform = process.platform): KillPlan {
+	if (platform === "win32") {
+		const args = ["/pid", String(pid), "/T", ...(force ? ["/F"] : [])];
+		return { command: { file: "taskkill", args }, targets: [] };
+	}
+	return { targets: [-pid, pid] };
+}
+
+/** A signal-0 probe; injectable so the EPERM branch is testable. */
+export type KillProbe = (pid: number, signal: number) => unknown;
+
+/** Whether a pid is alive on this host. EPERM means it exists but is not ours. */
+export function isPidAlive(pid: number, probe: KillProbe = process.kill): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		probe(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** The host seams {@link applyKillPlan} runs through. */
+export interface KillSeams {
+	/** Signal one pid; throws when the pid is gone or not ours. */
+	kill(pid: number, signal: NodeJS.Signals): unknown;
+	/** Run a program (the Windows `taskkill`). */
+	run(file: string, args: string[]): unknown;
+}
+
+/**
+ * Execute a {@link KillPlan}: run the command, or signal each target in order.
+ *
+ * The group attempt may answer `ESRCH` for a pid that is not a group leader, and
+ * the final attempt is the fallback, so its failure means "already gone" — a
+ * kill of a dead process is not an error a caller can act on.
+ */
+export function applyKillPlan(plan: KillPlan, signal: NodeJS.Signals, seams: KillSeams): void {
+	if (plan.command) {
+		seams.run(plan.command.file, plan.command.args);
+		return;
+	}
+	for (const [index, target] of plan.targets.entries()) {
+		const isFallback = index === plan.targets.length - 1;
+		try {
+			seams.kill(target, signal);
+			return;
+		} catch (error) {
+			if (!isFallback && (error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+		}
+	}
+}
+
+/** The real seams, so a caller needs no adapter. */
+const processSeams: KillSeams = {
+	kill: (pid, signal) => process.kill(pid, signal),
+	run: (file, args) => spawnSync(file, args, { stdio: "ignore" }),
+};
+
+/** Default spawn: a shell command in its own process group, output piped. */
+export const defaultSpawn: SpawnFn = (command, options) => nodeSpawn(command, spawnOptions(options));
+
+/** Default tree kill: process group on POSIX, `taskkill /T` on Windows. */
+export const defaultKillTree: KillTreeFn = (pid, signal, force = false) => {
+	applyKillPlan(killPlan(pid, force), signal, processSeams);
+};