gsd-pi 2.33.1-dev.235d83a → 2.33.1-dev.29a8268

package/dist/resources/extensions/bg-shell/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Background Shell Extension v2
+ *
+ * A next-generation background process manager designed for agentic workflows.
+ * Provides intelligent process lifecycle management, structured output digests,
+ * event-driven readiness detection, and context-efficient communication.
+ *
+ * Key capabilities:
+ * - Multi-tier output: digest (30 tokens) → highlights → raw (full context)
+ * - Readiness detection: port probing, pattern matching, auto-classification
+ * - Process lifecycle events: starting → ready → error → exited
+ * - Output diffing & dedup: detect novel errors vs. repeated noise
+ * - Process groups: manage related processes as a unit
+ * - Cross-session persistence: survive context resets
+ * - Expect-style interactions: send_and_wait for interactive CLIs
+ * - Context injection: proactive alerts for crashes and state changes
+ *
+ * Tools:
+ *   bg_shell — start, output, digest, wait_for_ready, send, send_and_wait, run,
+ *              signal, list, kill, restart, group_status
+ *
+ * Commands:
+ *   /bg — interactive process manager overlay
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { registerBgShellTool } from "./bg-shell-tool.js";
+import { registerBgShellCommand } from "./bg-shell-command.js";
+import { registerBgShellLifecycle } from "./bg-shell-lifecycle.js";
+
+// ── Re-exports for consumers ───────────────────────────────────────────────
+
+export type { ProcessStatus, ProcessType, BgProcess, BgProcessInfo, OutputDigest, OutputLine, ProcessEvent } from "./types.js";
+export { processes, startProcess, killProcess, restartProcess, cleanupAll, cleanupSessionProcesses } from "./process-manager.js";
+export { generateDigest, getHighlights, getOutput, formatDigestText } from "./output-formatter.js";
+export { waitForReady, probePort } from "./readiness-detector.js";
+export { sendAndWait, runOnSession, queryShellEnv } from "./interaction.js";
+export { BgManagerOverlay } from "./overlay.js";
+
+// ── Shared State ────────────────────────────────────────────────────────────
+
+export interface BgShellSharedState {
+	latestCtx: ExtensionContext | null;
+	refreshWidget: () => void;
+}
+
+// ── Extension Entry Point ──────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	const state: BgShellSharedState = {
+		latestCtx: null,
+		refreshWidget: () => {},
+	};
+
+	registerBgShellLifecycle(pi, state);
+	registerBgShellTool(pi, state);
+	registerBgShellCommand(pi, state);
+}

package/dist/resources/extensions/bg-shell/interaction.ts

@@ -0,0 +1,198 @@
+/**
+ * Expect-style interactions: send_and_wait, run on session, query shell environment.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { BgProcess } from "./types.js";
+
+// ── Query Shell Environment ────────────────────────────────────────────────
+
+export async function queryShellEnv(
+	bg: BgProcess,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<{ cwd: string; env: Record<string, string>; shell: string } | null> {
+	const sentinel = `__GSD_ENV_${randomUUID().slice(0, 8)}__`;
+	const startIndex = bg.output.length;
+
+	const cmd = [
+		`echo "${sentinel}_START"`,
+		`echo "CWD=$(pwd)"`,
+		`echo "SHELL=$SHELL"`,
+		`echo "PATH=$PATH"`,
+		`echo "VIRTUAL_ENV=$VIRTUAL_ENV"`,
+		`echo "NODE_ENV=$NODE_ENV"`,
+		`echo "HOME=$HOME"`,
+		`echo "USER=$USER"`,
+		`echo "NVM_DIR=$NVM_DIR"`,
+		`echo "GOPATH=$GOPATH"`,
+		`echo "CARGO_HOME=$CARGO_HOME"`,
+		`echo "PYTHONPATH=$PYTHONPATH"`,
+		`echo "${sentinel}_END"`,
+	].join(" && ");
+
+	bg.proc.stdin?.write(cmd + "\n");
+
+	const start = Date.now();
+	while (Date.now() - start < timeout) {
+		if (signal?.aborted) return null;
+		if (!bg.alive) return null;
+
+		const newEntries = bg.output.slice(startIndex);
+		const endIdx = newEntries.findIndex(e => e.line.includes(`${sentinel}_END`));
+		if (endIdx >= 0) {
+			const startIdx = newEntries.findIndex(e => e.line.includes(`${sentinel}_START`));
+			if (startIdx >= 0) {
+				const envLines = newEntries.slice(startIdx + 1, endIdx);
+				const env: Record<string, string> = {};
+				let cwd = "";
+				let shell = "";
+
+				for (const entry of envLines) {
+					const match = entry.line.match(/^([A-Z_]+)=(.*)$/);
+					if (match) {
+						const [, key, value] = match;
+						if (key === "CWD") {
+							cwd = value;
+						} else if (key === "SHELL") {
+							shell = value;
+						} else if (value) {
+							env[key] = value;
+						}
+					}
+				}
+
+				return { cwd, env, shell };
+			}
+		}
+
+		await new Promise(r => setTimeout(r, 100));
+	}
+
+	return null;
+}
+
+// ── Send and Wait ──────────────────────────────────────────────────────────
+
+export async function sendAndWait(
+	bg: BgProcess,
+	input: string,
+	waitPattern: string,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<{ matched: boolean; output: string }> {
+	// Snapshot the current position in the unified buffer before sending
+	const startIndex = bg.output.length;
+	bg.proc.stdin?.write(input + "\n");
+
+	let re: RegExp;
+	try {
+		re = new RegExp(waitPattern, "i");
+	} catch {
+		return { matched: false, output: "Invalid wait pattern regex" };
+	}
+
+	const start = Date.now();
+	while (Date.now() - start < timeout) {
+		if (signal?.aborted) {
+			const newEntries = bg.output.slice(startIndex);
+			return { matched: false, output: newEntries.map(e => e.line).join("\n") || "(cancelled)" };
+		}
+		const newEntries = bg.output.slice(startIndex);
+		for (const entry of newEntries) {
+			if (re.test(entry.line)) {
+				return { matched: true, output: newEntries.map(e => e.line).join("\n") };
+			}
+		}
+		await new Promise(r => setTimeout(r, 100));
+	}
+
+	const newEntries = bg.output.slice(startIndex);
+	return { matched: false, output: newEntries.map(e => e.line).join("\n") || "(no output)" };
+}
+
+// ── Run on Session ─────────────────────────────────────────────────────────
+
+export async function runOnSession(
+	bg: BgProcess,
+	command: string,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<{ exitCode: number; output: string; timedOut: boolean }> {
+	const sentinel = randomUUID().slice(0, 8);
+	const startMarker = `__GSD_SENTINEL_${sentinel}_START__`;
+	const endMarker = `__GSD_SENTINEL_${sentinel}_END__`;
+	const exitVar = `__GSD_EXIT_${sentinel}__`;
+
+	// Snapshot current output buffer position
+	const startIndex = bg.output.length;
+
+	// Write the sentinel-wrapped command to stdin
+	const wrappedCommand = [
+		`echo ${startMarker}`,
+		command,
+		`${exitVar}=$?`,
+		`echo ${endMarker} $${exitVar}`,
+	].join("\n");
+	bg.proc.stdin?.write(wrappedCommand + "\n");
+
+	const start = Date.now();
+	while (Date.now() - start < timeout) {
+		if (signal?.aborted) {
+			const newEntries = bg.output.slice(startIndex);
+			return { exitCode: -1, output: newEntries.map(e => e.line).join("\n") || "(cancelled)", timedOut: false };
+		}
+
+		// Process died while waiting
+		if (!bg.alive) {
+			const newEntries = bg.output.slice(startIndex);
+			const lines = newEntries.map(e => e.line);
+			return { exitCode: bg.proc.exitCode ?? -1, output: lines.join("\n") || "(process exited)", timedOut: false };
+		}
+
+		const newEntries = bg.output.slice(startIndex);
+		for (let i = 0; i < newEntries.length; i++) {
+			if (newEntries[i].line.includes(endMarker)) {
+				// Parse exit code from the END sentinel line
+				const endLine = newEntries[i].line;
+				const exitMatch = endLine.match(new RegExp(`${endMarker}\\s+(\\d+)`));
+				const exitCode = exitMatch ? parseInt(exitMatch[1], 10) : -1;
+
+				// Extract output between START and END sentinels
+				const outputLines: string[] = [];
+				let capturing = false;
+				for (let j = 0; j < newEntries.length; j++) {
+					if (newEntries[j].line.includes(startMarker)) {
+						capturing = true;
+						continue;
+					}
+					if (newEntries[j].line.includes(endMarker)) {
+						break;
+					}
+					if (capturing) {
+						outputLines.push(newEntries[j].line);
+					}
+				}
+
+				return { exitCode, output: outputLines.join("\n"), timedOut: false };
+			}
+		}
+
+		await new Promise(r => setTimeout(r, 100));
+	}
+
+	// Timed out
+	const newEntries = bg.output.slice(startIndex);
+	const outputLines: string[] = [];
+	let capturing = false;
+	for (const entry of newEntries) {
+		if (entry.line.includes(startMarker)) {
+			capturing = true;
+			continue;
+		}
+		if (capturing) {
+			outputLines.push(entry.line);
+		}
+	}
+	return { exitCode: -1, output: outputLines.join("\n") || "(no output)", timedOut: true };
+}

package/dist/resources/extensions/bg-shell/output-formatter.ts

@@ -0,0 +1,279 @@
+/**
+ * Output analysis, digest generation, highlights extraction, and output retrieval.
+ */
+
+import {
+	truncateHead,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+} from "@gsd/pi-coding-agent";
+import type { BgProcess, OutputDigest, OutputLine, GetOutputOptions } from "./types.js";
+import {
+	ERROR_PATTERNS,
+	ERROR_PATTERN_UNION,
+	WARNING_PATTERN_UNION,
+	READINESS_PATTERN_UNION,
+	BUILD_COMPLETE_PATTERN_UNION,
+	TEST_RESULT_PATTERN_UNION,
+	WARNING_PATTERNS,
+	URL_PATTERN,
+	PORT_PATTERN,
+	PORT_PATTERN_SOURCE,
+	READINESS_PATTERNS,
+	BUILD_COMPLETE_PATTERNS,
+	TEST_RESULT_PATTERNS,
+	LINE_DEDUP_MAX,
+} from "./types.js";
+import { addEvent, pushAlert } from "./process-manager.js";
+import { transitionToReady } from "./readiness-detector.js";
+import { formatUptime, formatTimeAgo } from "./utilities.js";
+
+// ── Output Analysis ────────────────────────────────────────────────────────
+
+export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "stderr"): void {
+	// Error detection — single union regex instead of .some(p => p.test(line))
+	if (ERROR_PATTERN_UNION.test(line)) {
+		bg.recentErrors.push(line.trim().slice(0, 200)); // Cap line length
+		if (bg.recentErrors.length > 50) bg.recentErrors.splice(0, bg.recentErrors.length - 50);
+
+		if (bg.status === "ready") {
+			bg.status = "error";
+			addEvent(bg, {
+				type: "error_detected",
+				detail: line.trim().slice(0, 200),
+				data: { errorCount: bg.recentErrors.length },
+			});
+			pushAlert(bg, `error_detected: ${line.trim().slice(0, 120)}`);
+		}
+	}
+
+	// Warning detection — single union regex
+	if (WARNING_PATTERN_UNION.test(line)) {
+		bg.recentWarnings.push(line.trim().slice(0, 200));
+		if (bg.recentWarnings.length > 50) bg.recentWarnings.splice(0, bg.recentWarnings.length - 50);
+	}
+
+	// URL extraction
+	const urlMatches = line.match(URL_PATTERN);
+	if (urlMatches) {
+		for (const url of urlMatches) {
+			if (!bg.urls.includes(url)) {
+				bg.urls.push(url);
+			}
+		}
+	}
+
+	// Port extraction — PORT_PATTERN has /g flag so must be re-created per call
+	// Use PORT_PATTERN_SOURCE (string) to avoid re-parsing the literal each time
+	const portRe = new RegExp(PORT_PATTERN_SOURCE, "gi");
+	let portMatch: RegExpExecArray | null;
+	while ((portMatch = portRe.exec(line)) !== null) {
+		const port = parseInt(portMatch[1], 10);
+		if (port > 0 && port <= 65535 && !bg.ports.includes(port)) {
+			bg.ports.push(port);
+			addEvent(bg, {
+				type: "port_open",
+				detail: `Port ${port} detected`,
+				data: { port },
+			});
+		}
+	}
+
+	// Readiness detection — single union regex
+	if (bg.status === "starting") {
+		// Check custom ready pattern first
+		if (bg.readyPattern) {
+			try {
+				if (new RegExp(bg.readyPattern, "i").test(line)) {
+					transitionToReady(bg, `Custom pattern matched: ${line.trim().slice(0, 100)}`);
+				}
+			} catch { /* invalid regex, skip */ }
+		}
+
+		// Check built-in readiness patterns
+		if (bg.status === "starting" && READINESS_PATTERN_UNION.test(line)) {
+			transitionToReady(bg, `Readiness pattern matched: ${line.trim().slice(0, 100)}`);
+		}
+	}
+
+	// Recovery detection: if we were in error and see a success pattern
+	if (bg.status === "error") {
+		if (READINESS_PATTERN_UNION.test(line) || BUILD_COMPLETE_PATTERN_UNION.test(line)) {
+			bg.status = "ready";
+			bg.recentErrors = [];
+			addEvent(bg, { type: "recovered", detail: "Process recovered from error state" });
+			pushAlert(bg, "recovered — errors cleared");
+		}
+	}
+
+	// Dedup tracking — evict oldest entry when map exceeds LINE_DEDUP_MAX (LRU via Map insertion order)
+	bg.totalRawLines++;
+	const lineHash = line.trim().slice(0, 100);
+	const existing = bg.lineDedup.get(lineHash);
+	if (existing !== undefined) {
+		// Re-insert to update insertion order (move to tail = most recent)
+		bg.lineDedup.delete(lineHash);
+		bg.lineDedup.set(lineHash, existing + 1);
+	} else {
+		if (bg.lineDedup.size >= LINE_DEDUP_MAX) {
+			// Evict oldest entry (Map iteration order = insertion order = LRU at head)
+			const oldest = bg.lineDedup.keys().next().value;
+			if (oldest !== undefined) bg.lineDedup.delete(oldest);
+		}
+		bg.lineDedup.set(lineHash, 1);
+	}
+}
+
+// ── Digest Generation ──────────────────────────────────────────────────────
+
+export function generateDigest(bg: BgProcess, mutate: boolean = false): OutputDigest {
+	// Change summary: what's different since last read
+	const newErrors = bg.recentErrors.length - bg.lastErrorCount;
+	const newWarnings = bg.recentWarnings.length - bg.lastWarningCount;
+	const newLines = bg.output.length - bg.lastReadIndex;
+
+	let changeSummary: string;
+	if (newLines === 0) {
+		changeSummary = "no new output";
+	} else {
+		const parts: string[] = [];
+		parts.push(`${newLines} new lines`);
+		if (newErrors > 0) parts.push(`${newErrors} new errors`);
+		if (newWarnings > 0) parts.push(`${newWarnings} new warnings`);
+		changeSummary = parts.join(", ");
+	}
+
+	// Only mutate snapshot counters when explicitly requested (e.g. from tool calls)
+	if (mutate) {
+		bg.lastErrorCount = bg.recentErrors.length;
+		bg.lastWarningCount = bg.recentWarnings.length;
+	}
+
+	return {
+		status: bg.status,
+		uptime: formatUptime(Date.now() - bg.startedAt),
+		errors: bg.recentErrors.slice(-5), // Last 5 errors
+		warnings: bg.recentWarnings.slice(-3), // Last 3 warnings
+		urls: bg.urls,
+		ports: bg.ports,
+		lastActivity: bg.events.length > 0
+			? formatTimeAgo(bg.events[bg.events.length - 1].timestamp)
+			: "none",
+		outputLines: bg.output.length,
+		changeSummary,
+	};
+}
+
+// ── Highlight Extraction ───────────────────────────────────────────────────
+
+export function getHighlights(bg: BgProcess, maxLines: number = 15): string[] {
+	const lines: string[] = [];
+
+	// Collect significant lines
+	const significant: { line: string; score: number; idx: number }[] = [];
+	for (let i = 0; i < bg.output.length; i++) {
+		const entry = bg.output[i];
+		let score = 0;
+		if (ERROR_PATTERN_UNION.test(entry.line)) score += 10;
+		if (WARNING_PATTERN_UNION.test(entry.line)) score += 5;
+		if (URL_PATTERN.test(entry.line)) score += 3;
+		if (READINESS_PATTERN_UNION.test(entry.line)) score += 8;
+		if (TEST_RESULT_PATTERN_UNION.test(entry.line)) score += 7;
+		if (BUILD_COMPLETE_PATTERN_UNION.test(entry.line)) score += 6;
+		// Boost recent lines so highlights favor fresh output over stale
+		if (i >= bg.output.length - 50) score += 2;
+		if (score > 0) {
+			significant.push({ line: entry.line.trim().slice(0, 300), score, idx: i });
+		}
+	}
+
+	// Sort by significance (tie-break by recency)
+	significant.sort((a, b) => b.score - a.score || b.idx - a.idx);
+	const top = significant.slice(0, maxLines);
+
+	if (top.length === 0) {
+		// If nothing significant, show last few lines
+		const tail = bg.output.slice(-5);
+		for (const l of tail) lines.push(l.line.trim().slice(0, 300));
+	} else {
+		for (const entry of top) lines.push(entry.line);
+	}
+
+	return lines;
+}
+
+// ── Output Retrieval (multi-tier) ──────────────────────────────────────────
+
+export function getOutput(bg: BgProcess, opts: GetOutputOptions): string {
+	const { stream, tail, filter, incremental } = opts;
+
+	// Get the relevant slice of the unified buffer (already in chronological order)
+	let entries: OutputLine[];
+	if (incremental) {
+		entries = bg.output.slice(bg.lastReadIndex);
+		bg.lastReadIndex = bg.output.length;
+	} else {
+		entries = [...bg.output];
+	}
+
+	// Filter by stream if requested
+	if (stream !== "both") {
+		entries = entries.filter(e => e.stream === stream);
+	}
+
+	// Apply regex filter
+	if (filter) {
+		try {
+			const re = new RegExp(filter, "i");
+			entries = entries.filter(e => re.test(e.line));
+		} catch { /* invalid regex */ }
+	}
+
+	// Tail
+	if (tail && tail > 0 && entries.length > tail) {
+		entries = entries.slice(-tail);
+	}
+
+	const lines = entries.map(e => e.line);
+	const raw = lines.join("\n");
+	const truncation = truncateHead(raw, {
+		maxLines: DEFAULT_MAX_LINES,
+		maxBytes: DEFAULT_MAX_BYTES,
+	});
+
+	let result = truncation.content;
+	if (truncation.truncated) {
+		result += `\n\n[Output truncated: showing ${truncation.outputLines}/${truncation.totalLines} lines]`;
+	}
+	return result;
+}
+
+// ── Format Digest for LLM ──────────────────────────────────────────────────
+
+export function formatDigestText(bg: BgProcess, digest: OutputDigest): string {
+	let text = `Process ${bg.id} (${bg.label}):\n`;
+	text += `  status: ${digest.status}\n`;
+	text += `  type: ${bg.processType}\n`;
+	text += `  uptime: ${digest.uptime}\n`;
+
+	if (digest.ports.length > 0) text += `  ports: ${digest.ports.join(", ")}\n`;
+	if (digest.urls.length > 0) text += `  urls: ${digest.urls.join(", ")}\n`;
+
+	text += `  output: ${digest.outputLines} lines\n`;
+	text += `  changes: ${digest.changeSummary}`;
+
+	if (digest.errors.length > 0) {
+		text += `\n  errors (${digest.errors.length}):`;
+		for (const err of digest.errors) {
+			text += `\n    - ${err}`;
+		}
+	}
+	if (digest.warnings.length > 0) {
+		text += `\n  warnings (${digest.warnings.length}):`;
+		for (const w of digest.warnings) {
+			text += `\n    - ${w}`;
+		}
+	}
+
+	return text;
+}