gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.538325aea

package/packages/gsd-agent-core/src/artifact-manager.ts

@@ -0,0 +1,126 @@
+/**
+ * Session-scoped artifact storage for truncated tool outputs.
+ *
+ * Artifacts are stored in a directory alongside the session file,
+ * accessible via artifact:// URLs.
+ */
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Manages artifact storage for a session.
+ *
+ * Artifacts are stored with sequential IDs in the session's artifact directory.
+ * The directory is created lazily on first write.
+ */
+export class ArtifactManager {
+	#nextId = 0;
+	readonly #dir: string;
+	#dirCreated = false;
+	#initialized = false;
+
+	/**
+	 * @param sessionFile Path to the session .jsonl file
+	 */
+	constructor(sessionFile: string) {
+		// Artifact directory is session file path without .jsonl extension
+		this.#dir = sessionFile.slice(0, -6);
+	}
+
+	/**
+	 * Artifact directory path.
+	 * Directory may not exist until first artifact is saved.
+	 */
+	get dir(): string {
+		return this.#dir;
+	}
+
+	#ensureDir(): void {
+		if (!this.#dirCreated) {
+			mkdirSync(this.#dir, { recursive: true });
+			this.#dirCreated = true;
+		}
+		if (!this.#initialized) {
+			this.#scanExistingIds();
+			this.#initialized = true;
+		}
+	}
+
+	/**
+	 * Scan existing artifact files to find the next available ID.
+	 * Ensures we don't overwrite artifacts when resuming a session.
+	 */
+	#scanExistingIds(): void {
+		const files = this.listFiles();
+		let maxId = -1;
+		for (const file of files) {
+			const match = file.match(/^(\d+)\..*\.log$/);
+			if (match) {
+				const id = parseInt(match[1], 10);
+				if (id > maxId) maxId = id;
+			}
+		}
+		this.#nextId = maxId + 1;
+	}
+
+	/** Atomically allocate next artifact ID. */
+	allocateId(): number {
+		this.#ensureDir();
+		return this.#nextId++;
+	}
+
+	/**
+	 * Allocate a new artifact path and ID without writing content.
+	 * @param toolType Tool name for file extension (e.g., "bash", "fetch")
+	 */
+	allocatePath(toolType: string): { id: string; path: string } {
+		this.#ensureDir();
+		const id = String(this.allocateId());
+		const filename = `${id}.${toolType}.log`;
+		return { id, path: join(this.#dir, filename) };
+	}
+
+	/**
+	 * Save content as an artifact and return the artifact ID.
+	 * @param content Full content to save
+	 * @param toolType Tool name for file extension (e.g., "bash", "fetch")
+	 * @returns Artifact ID (numeric string)
+	 */
+	save(content: string, toolType: string): string {
+		const { id, path } = this.allocatePath(toolType);
+		writeFileSync(path, content);
+		return id;
+	}
+
+	/**
+	 * Check if an artifact exists.
+	 * @param id Artifact ID (numeric string)
+	 */
+	exists(id: string): boolean {
+		const files = this.listFiles();
+		return files.some((f) => f.startsWith(`${id}.`));
+	}
+
+	/**
+	 * List all artifact files in the directory.
+	 * Returns empty array if directory doesn't exist.
+	 */
+	listFiles(): string[] {
+		try {
+			return readdirSync(this.#dir);
+		} catch {
+			return [];
+		}
+	}
+
+	/**
+	 * Get the full path to an artifact file.
+	 * Returns null if artifact doesn't exist.
+	 * @param id Artifact ID (numeric string)
+	 */
+	getPath(id: string): string | null {
+		const files = this.listFiles();
+		const match = files.find((f) => f.startsWith(`${id}.`));
+		return match ? join(this.#dir, match) : null;
+	}
+}

package/packages/gsd-agent-core/src/bash-executor.ts

@@ -0,0 +1,352 @@
+/**
+ * Bash command execution with streaming support and cancellation.
+ *
+ * This module provides a unified bash execution implementation used by:
+ * - AgentSession.executeBash() for interactive and RPC modes
+ * - Direct calls from modes that need bash execution
+ */
+
+import { randomBytes } from "node:crypto";
+import { createWriteStream, unlinkSync, type WriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type ChildProcess, spawn, spawnSync } from "child_process";
+
+/** Track temp files created by bash execution for cleanup on exit. */
+const bashTempFiles = new Set<string>();
+
+let cleanupRegistered = false;
+function registerTempCleanup(): void {
+	if (cleanupRegistered) return;
+	cleanupRegistered = true;
+	process.on("exit", () => {
+		for (const file of bashTempFiles) {
+			try {
+				unlinkSync(file);
+			} catch {
+				// Best-effort cleanup
+			}
+		}
+	});
+}
+import { processStreamChunk, type StreamState } from "@gsd/native";
+import { getShellConfig, DEFAULT_MAX_BYTES, truncateTail } from "@gsd/pi-coding-agent";
+
+function getShellEnv(): NodeJS.ProcessEnv {
+	return { ...process.env };
+}
+
+function killProcessTree(pid: number): void {
+	if (process.platform === "win32") {
+		spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+		return;
+	}
+
+	try {
+		process.kill(-pid, "SIGTERM");
+	} catch {
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch {
+			// best effort
+		}
+	}
+}
+
+// sanitizeCommand was removed from @gsd/pi-coding-agent 0.67.2. The function
+// stripped null bytes and other control characters that could confuse the shell.
+// Phase 09: move to @gsd/agent-types or inline permanently.
+export function sanitizeCommand(cmd: string): string {
+	// Remove null bytes and ASCII control characters (except newline/tab which are valid in scripts)
+	// eslint-disable-next-line no-control-regex -- intentional: sanitizing shell command input
+	return cmd.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+}
+
+/**
+ * Dynamically import a sibling module relative to an extension's import.meta.url.
+ * Replaces the removed @gsd/pi-coding-agent importExtensionModule (0.67.2).
+ *
+ * Usage: const mod = await importExtensionModule<typeof import("./foo.js")>(import.meta.url, "./foo.js");
+ */
+export async function importExtensionModule<T = unknown>(parentModuleUrl: string, specifier: string): Promise<T> {
+	const resolvedPath = fileURLToPath(new URL(specifier, parentModuleUrl));
+	return import(resolvedPath) as Promise<T>;
+}
+
+import type { BashOperations } from "@gsd/agent-types";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface BashExecutorOptions {
+	/** Callback for streaming output chunks (already sanitized) */
+	onChunk?: (chunk: string) => void;
+	/** AbortSignal for cancellation */
+	signal?: AbortSignal;
+}
+
+export interface BashResult {
+	/** Combined stdout + stderr output (sanitized, possibly truncated) */
+	output: string;
+	/** Process exit code (undefined if killed/cancelled) */
+	exitCode: number | undefined;
+	/** Whether the command was cancelled via signal */
+	cancelled: boolean;
+	/** Whether the output was truncated */
+	truncated: boolean;
+	/** Path to temp file containing full output (if output exceeded truncation threshold) */
+	fullOutputPath?: string;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Execute a bash command with optional streaming and cancellation support.
+ *
+ * Features:
+ * - Streams sanitized output via onChunk callback
+ * - Writes large output to temp file for later retrieval
+ * - Supports cancellation via AbortSignal
+ * - Sanitizes output (strips ANSI, removes binary garbage, normalizes newlines)
+ * - Truncates output if it exceeds the default max bytes
+ *
+ * @param command - The bash command to execute
+ * @param options - Optional streaming callback and abort signal
+ * @returns Promise resolving to execution result
+ */
+export function executeBash(command: string, options?: BashExecutorOptions & { loginShell?: boolean }): Promise<BashResult> {
+	// Check abort BEFORE spawning to avoid leaking the child process
+	if (options?.signal?.aborted) {
+		return Promise.resolve({ output: "", exitCode: undefined, cancelled: true, truncated: false });
+	}
+
+	return new Promise((resolve, reject) => {
+		let shell: string;
+		let args: string[];
+		if (options?.loginShell) {
+			// Use the user's login shell with -l for PATH/env from shell profiles
+			shell = process.env.SHELL || "/bin/bash";
+			args = ["-l", "-c"];
+		} else {
+			({ shell, args } = getShellConfig());
+		}
+		// On Windows, detached: true sets CREATE_NEW_PROCESS_GROUP which can
+		// cause EINVAL in VSCode/ConPTY terminal contexts.  The bg-shell
+		// extension already guards this (process-manager.ts); align here.
+		// Process-tree cleanup uses taskkill /F /T on Windows regardless.
+		const child: ChildProcess = spawn(shell, [...args, sanitizeCommand(command)], {
+			detached: process.platform !== "win32",
+			env: getShellEnv(),
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		// Track sanitized output for truncation
+		const outputChunks: string[] = [];
+		let outputBytes = 0;
+		const maxOutputBytes = DEFAULT_MAX_BYTES * 2;
+
+		// Temp file for large output
+		let tempFilePath: string | undefined;
+		let tempFileStream: WriteStream | undefined;
+		let totalBytes = 0;
+
+		// Handle abort signal
+		const abortHandler = (): void => {
+			if (child.pid) {
+				killProcessTree(child.pid);
+			}
+		};
+
+		if (options?.signal) {
+			options.signal.addEventListener("abort", abortHandler, { once: true });
+		}
+
+		let streamState: StreamState | undefined;
+
+		const handleData = (data: Buffer): void => {
+			totalBytes += data.length;
+
+			// Single-pass native processing: UTF-8 decode + ANSI strip + binary sanitize + CR removal
+			const result = processStreamChunk(data, streamState);
+			streamState = result.state;
+			const text = result.text;
+
+			// Start writing to temp file if exceeds threshold
+			if (totalBytes > DEFAULT_MAX_BYTES && !tempFilePath) {
+				registerTempCleanup();
+				const id = randomBytes(8).toString("hex");
+				tempFilePath = join(tmpdir(), `pi-bash-${id}.log`);
+				bashTempFiles.add(tempFilePath);
+				tempFileStream = createWriteStream(tempFilePath);
+				// Write already-buffered chunks to temp file
+				for (const chunk of outputChunks) {
+					tempFileStream.write(chunk);
+				}
+			}
+
+			if (tempFileStream) {
+				tempFileStream.write(text);
+			}
+
+			// Keep rolling buffer of sanitized text
+			outputChunks.push(text);
+			outputBytes += text.length;
+			while (outputBytes > maxOutputBytes && outputChunks.length > 1) {
+				const removed = outputChunks.shift()!;
+				outputBytes -= removed.length;
+			}
+
+			// Stream to callback if provided
+			if (options?.onChunk) {
+				options.onChunk(text);
+			}
+		};
+
+		child.stdout?.on("data", handleData);
+		child.stderr?.on("data", handleData);
+
+		child.on("close", (code) => {
+			// Clean up abort listener
+			if (options?.signal) {
+				options.signal.removeEventListener("abort", abortHandler);
+			}
+
+			if (tempFileStream && !tempFileStream.writableEnded) {
+				tempFileStream.end();
+			}
+
+			// Combine buffered chunks for truncation (already sanitized)
+			const fullOutput = outputChunks.join("");
+			const truncationResult = truncateTail(fullOutput);
+
+			// code === null means killed (cancelled)
+			const cancelled = code === null;
+
+			resolve({
+				output: truncationResult.truncated ? truncationResult.content : fullOutput,
+				exitCode: cancelled ? undefined : code,
+				cancelled,
+				truncated: truncationResult.truncated,
+				fullOutputPath: tempFilePath,
+			});
+		});
+
+		child.on("error", (err) => {
+			// Clean up abort listener
+			if (options?.signal) {
+				options.signal.removeEventListener("abort", abortHandler);
+			}
+
+			if (tempFileStream) {
+				tempFileStream.end();
+			}
+
+			reject(err);
+		});
+	});
+}
+
+/**
+ * Execute a bash command using custom BashOperations.
+ * Used for remote execution (SSH, containers, etc.).
+ */
+export async function executeBashWithOperations(
+	command: string,
+	cwd: string,
+	operations: BashOperations,
+	options?: BashExecutorOptions,
+): Promise<BashResult> {
+	const outputChunks: string[] = [];
+	let outputBytes = 0;
+	const maxOutputBytes = DEFAULT_MAX_BYTES * 2;
+
+	let tempFilePath: string | undefined;
+	let tempFileStream: WriteStream | undefined;
+	let totalBytes = 0;
+
+	let streamState2: StreamState | undefined;
+
+	const onData = (data: Buffer): void => {
+		totalBytes += data.length;
+
+		// Single-pass native processing: UTF-8 decode + ANSI strip + binary sanitize + CR removal
+		const result = processStreamChunk(data, streamState2);
+		streamState2 = result.state;
+		const text = result.text;
+
+		// Start writing to temp file if exceeds threshold
+		if (totalBytes > DEFAULT_MAX_BYTES && !tempFilePath) {
+			registerTempCleanup();
+			const id = randomBytes(8).toString("hex");
+			tempFilePath = join(tmpdir(), `pi-bash-${id}.log`);
+			bashTempFiles.add(tempFilePath);
+			tempFileStream = createWriteStream(tempFilePath);
+			for (const chunk of outputChunks) {
+				tempFileStream.write(chunk);
+			}
+		}
+
+		if (tempFileStream) {
+			tempFileStream.write(text);
+		}
+
+		// Keep rolling buffer
+		outputChunks.push(text);
+		outputBytes += text.length;
+		while (outputBytes > maxOutputBytes && outputChunks.length > 1) {
+			const removed = outputChunks.shift()!;
+			outputBytes -= removed.length;
+		}
+
+		// Stream to callback
+		if (options?.onChunk) {
+			options.onChunk(text);
+		}
+	};
+
+	try {
+		const result = await operations.exec(command, cwd, {
+			onData,
+			signal: options?.signal,
+		});
+
+		if (tempFileStream) {
+			tempFileStream.end();
+		}
+
+		const fullOutput = outputChunks.join("");
+		const truncationResult = truncateTail(fullOutput);
+		const cancelled = options?.signal?.aborted ?? false;
+
+		return {
+			output: truncationResult.truncated ? truncationResult.content : fullOutput,
+			exitCode: cancelled ? undefined : (result.exitCode ?? undefined),
+			cancelled,
+			truncated: truncationResult.truncated,
+			fullOutputPath: tempFilePath,
+		};
+	} catch (err) {
+		if (tempFileStream) {
+			tempFileStream.end();
+		}
+
+		// Check if it was an abort
+		if (options?.signal?.aborted) {
+			const fullOutput = outputChunks.join("");
+			const truncationResult = truncateTail(fullOutput);
+			return {
+				output: truncationResult.truncated ? truncationResult.content : fullOutput,
+				exitCode: undefined,
+				cancelled: true,
+				truncated: truncationResult.truncated,
+				fullOutputPath: tempFilePath,
+			};
+		}
+
+		throw err;
+	}
+}

package/packages/gsd-agent-core/src/blob-store.ts

@@ -0,0 +1,154 @@
+/**
+ * Content-addressed blob store for externalizing large binary data (images) from session JSONL files.
+ *
+ * Files are stored at `<dir>/<sha256-hex>` with no extension. The SHA-256 hash is computed
+ * over the raw binary data (not base64). Content-addressing makes writes idempotent and
+ * provides automatic deduplication across sessions.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, accessSync, unlinkSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const BLOB_PREFIX = "blob:sha256:";
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/;
+
+export interface BlobPutResult {
+	hash: string;
+	path: string;
+	get ref(): string;
+}
+
+export class BlobStore {
+	readonly dir: string;
+	constructor(dir: string) {
+		this.dir = dir;
+		mkdirSync(dir, { recursive: true });
+	}
+
+	/** Write binary data to the blob store. Idempotent — same content → same hash. */
+	put(data: Buffer): BlobPutResult {
+		const hash = createHash("sha256").update(data).digest("hex");
+		const blobPath = join(this.dir, hash);
+		const result: BlobPutResult = {
+			hash,
+			path: blobPath,
+			get ref() {
+				return `${BLOB_PREFIX}${hash}`;
+			},
+		};
+
+		try {
+			writeFileSync(blobPath, data, { flag: "wx" }); // Atomic: fails if file exists
+		} catch (err: unknown) {
+			if (typeof err !== "object" || err === null || (err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+			// File already exists — expected for content-addressed storage
+		}
+		return result;
+	}
+
+	/** Read blob by hash, returns Buffer or null if not found. */
+	get(hash: string): Buffer | null {
+		if (!SHA256_HEX_RE.test(hash)) return null;
+		const blobPath = join(this.dir, hash);
+		try {
+			return readFileSync(blobPath);
+		} catch {
+			return null;
+		}
+	}
+
+	/** Check if a blob exists. */
+	has(hash: string): boolean {
+		if (!SHA256_HEX_RE.test(hash)) return false;
+		try {
+			accessSync(join(this.dir, hash));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Remove blobs not referenced by any session file.
+	 * @param referencedHashes Set of SHA-256 hashes still referenced in session files.
+	 * @returns Number of orphaned blobs removed.
+	 */
+	gc(referencedHashes: Set<string>): number {
+		let removed = 0;
+		try {
+			const entries = readdirSync(this.dir);
+			for (const entry of entries) {
+				if (!SHA256_HEX_RE.test(entry)) continue;
+				if (!referencedHashes.has(entry)) {
+					try {
+						unlinkSync(join(this.dir, entry));
+						removed++;
+					} catch {
+						// Best-effort removal
+					}
+				}
+			}
+		} catch {
+			// Blob dir may not exist or be unreadable
+		}
+		return removed;
+	}
+
+	/** Get total size of all blobs in bytes, or 0 if the directory is empty/unreadable. */
+	totalSize(): number {
+		try {
+			const entries = readdirSync(this.dir);
+			let total = 0;
+			for (const entry of entries) {
+				if (!SHA256_HEX_RE.test(entry)) continue;
+				try {
+					total += statSync(join(this.dir, entry)).size;
+				} catch {
+					// Skip unreadable files
+				}
+			}
+			return total;
+		} catch {
+			return 0;
+		}
+	}
+}
+
+/** Check if a data string is a blob reference. */
+export function isBlobRef(data: string): boolean {
+	return data.startsWith(BLOB_PREFIX);
+}
+
+/** Extract the SHA-256 hash from a blob reference string. Returns null if format is invalid. */
+export function parseBlobRef(data: string): string | null {
+	if (!data.startsWith(BLOB_PREFIX)) return null;
+	const hash = data.slice(BLOB_PREFIX.length);
+	if (!SHA256_HEX_RE.test(hash)) return null;
+	return hash;
+}
+
+/**
+ * Externalize an image's base64 data to the blob store, returning a blob reference.
+ * If the data is already a blob reference, returns it unchanged.
+ */
+export function externalizeImageData(blobStore: BlobStore, base64Data: string): string {
+	if (isBlobRef(base64Data)) return base64Data;
+	const buffer = Buffer.from(base64Data, "base64");
+	const { ref } = blobStore.put(buffer);
+	return ref;
+}
+
+/**
+ * Resolve a blob reference back to base64 data.
+ * If the data is not a blob reference, returns it unchanged.
+ * If the blob is missing, returns the ref unchanged.
+ */
+export function resolveImageData(blobStore: BlobStore, data: string): string {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+
+	const buffer = blobStore.get(hash);
+	if (!buffer) return data; // Missing blob — return ref as-is
+
+	return buffer.toString("base64");
+}