@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

package/src/session/artifacts.ts

@@ -39,7 +39,7 @@ export class ArtifactManager {
 	#nextId = 0;
 	readonly #dir: string;
 	#dirCreated = false;
-	#initialized = false;
+	#initPromise: Promise<void> | null = null;
 
 	/**
 	 * @param dir Directory that will hold artifact files. Created lazily on first save.
@@ -61,10 +61,11 @@ export class ArtifactManager {
 			await fs.mkdir(this.#dir, { recursive: true });
 			this.#dirCreated = true;
 		}
-		if (!this.#initialized) {
-			await this.#scanExistingIds();
-			this.#initialized = true;
-		}
+		// Memoize the first-use scan so it runs exactly once. Concurrent callers
+		// share the in-flight promise instead of each re-seeding #nextId across
+		// the readdir yield in #scanExistingIds (which would hand duplicate ids).
+		this.#initPromise ??= this.#scanExistingIds();
+		await this.#initPromise;
 	}
 
 	/**

package/src/session/async-job-delivery.ts

@@ -0,0 +1,74 @@
+/**
+ * Owner-routed async job delivery: formatting and batch-message assembly for
+ * `async-result` follow-ups.
+ *
+ * Each {@link AgentSession} registers a delivery sink for its own agent id
+ * (`AsyncJobManager.registerDeliverySink`) and enqueues formatted entries on
+ * its yield queue; the queue's idle flush injects them as a follow-up turn.
+ * This replaces the old single hardwired `onJobComplete` closure that routed
+ * every completion — regardless of owner — into the first top-level session.
+ */
+import { prompt } from "@oh-my-pi/pi-utils";
+import type { AsyncJob } from "../async";
+import asyncResultTemplate from "../prompts/tools/async-result.md" with { type: "text" };
+import type { CustomMessage } from "./messages";
+
+/**
+ * `customType` of the injected async-result follow-up message. The task
+ * executor's run monitor matches on it to invalidate a previously recorded
+ * yield: a result injected after the yield supersedes that yield's payload.
+ */
+export const ASYNC_RESULT_MESSAGE_TYPE = "async-result";
+
+/** Result payloads longer than this spill to an artifact with an inline preview. */
+export const ASYNC_INLINE_RESULT_MAX_CHARS = 12_000;
+export const ASYNC_PREVIEW_MAX_CHARS = 4_000;
+
+export interface AsyncResultEntry {
+	jobId: string;
+	result: string;
+	job: AsyncJob | undefined;
+	durationMs: number | undefined;
+}
+
+type AsyncResultJobDetails = {
+	jobId: string;
+	type?: "bash" | "task";
+	label?: string;
+	durationMs?: number;
+};
+
+export type AsyncResultDetails = {
+	jobs: AsyncResultJobDetails[];
+};
+
+export function buildAsyncResultBatchMessage(entries: AsyncResultEntry[]): CustomMessage<AsyncResultDetails> | null {
+	if (entries.length === 0) return null;
+	const jobs = entries.map(entry => ({
+		jobId: entry.jobId,
+		result: entry.result,
+		type: entry.job?.type,
+		label: entry.job?.label,
+		durationMs: entry.durationMs,
+	}));
+	const details: AsyncResultDetails = {
+		jobs: jobs.map(job => ({
+			jobId: job.jobId,
+			type: job.type,
+			label: job.label,
+			durationMs: job.durationMs,
+		})),
+	};
+	return {
+		role: "custom",
+		customType: ASYNC_RESULT_MESSAGE_TYPE,
+		content: prompt.render(asyncResultTemplate, {
+			multiple: jobs.length > 1,
+			jobs,
+		}),
+		display: true,
+		attribution: "agent",
+		details,
+		timestamp: Date.now(),
+	};
+}

package/src/session/bash-runner.ts

@@ -0,0 +1,326 @@
+import * as path from "node:path";
+import type { Agent } from "@oh-my-pi/pi-agent-core";
+import { logger } from "@oh-my-pi/pi-utils";
+import type { Settings } from "../config/settings";
+import { type BashResult, executeBash as executeBashCommand } from "../exec/bash-executor";
+import type { ExtensionRunner } from "../extensibility/extensions";
+import { outputMeta } from "../tools/output-meta";
+import { clampTimeout } from "../tools/tool-timeouts";
+import type { BashExecutionMessage } from "./messages";
+import type { SessionManager } from "./session-manager";
+
+/** Destination that owns a bash result after a session or branch transition. */
+export type BashAppendDestination =
+	| { kind: "current"; manager: SessionManager }
+	| { kind: "detached"; manager: SessionManager }
+	| { kind: "branch"; manager: SessionManager; parentId: string | null };
+
+/** Reference-counted session target captured when a bash execution starts. */
+export interface BashSessionTarget {
+	sessionId: string;
+	refs: number;
+	destination?: BashAppendDestination;
+	pending?: Promise<BashAppendDestination>;
+}
+
+interface PendingBashMessage {
+	target: BashSessionTarget;
+	message: BashExecutionMessage;
+}
+
+/** Ownership snapshot spanning a session or branch transition. */
+export interface BashSessionTransition {
+	oldTarget: BashSessionTarget;
+	newTarget: BashSessionTarget;
+	oldSessionId: string;
+	oldSessionFile: string | undefined;
+	oldLeafId: string | null;
+	detachedManager: SessionManager | undefined;
+	resolveOld: ((destination: BashAppendDestination) => void) | undefined;
+	resolveNew: (destination: BashAppendDestination) => void;
+}
+
+/** Capabilities the bash runner borrows from its owning session. */
+export interface BashRunnerHost {
+	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
+	extensionRunner(): ExtensionRunner | undefined;
+	isStreaming(): boolean;
+}
+
+/** Owns bash execution and preserves result ownership across transcript transitions. */
+export class BashRunner {
+	readonly #host: BashRunnerHost;
+	#abortControllers = new Set<AbortController>();
+	#pendingMessages: PendingBashMessage[] = [];
+	#sessionTarget: BashSessionTarget;
+
+	constructor(host: BashRunnerHost) {
+		this.#host = host;
+		this.#sessionTarget = {
+			sessionId: host.sessionManager.getSessionId(),
+			refs: 0,
+			destination: { kind: "current", manager: host.sessionManager },
+		};
+	}
+
+	/** Executes a bash command while retaining the session and branch that owned its start. */
+	async executeBash(
+		command: string,
+		onChunk?: (chunk: string) => void,
+		options?: { excludeFromContext?: boolean; useUserShell?: boolean },
+	): Promise<BashResult> {
+		const target = this.#captureSessionTarget();
+		let targetTransferred = false;
+		const excludeFromContext = options?.excludeFromContext === true;
+		const cwd = this.#host.sessionManager.getCwd();
+		try {
+			const extensionRunner = this.#host.extensionRunner();
+			if (extensionRunner?.hasHandlers("user_bash")) {
+				const hookResult = await extensionRunner.emitUserBash({
+					type: "user_bash",
+					command,
+					excludeFromContext,
+					cwd,
+				});
+				if (hookResult?.result) {
+					targetTransferred = true;
+					await this.#recordResultForTarget(target, command, hookResult.result, options);
+					return hookResult.result;
+				}
+			}
+
+			const abortController = new AbortController();
+			this.#abortControllers.add(abortController);
+			let result: BashResult;
+			try {
+				result = await executeBashCommand(command, {
+					onChunk,
+					signal: abortController.signal,
+					sessionKey: target.sessionId,
+					cwd,
+					timeout: clampTimeout("bash", undefined, this.#host.settings.get("tools.maxTimeout")) * 1000,
+					onMinimizedSave: originalText => this.#saveOriginalArtifact(target, originalText),
+					useUserShell: options?.useUserShell,
+				});
+			} finally {
+				this.#abortControllers.delete(abortController);
+			}
+			targetTransferred = true;
+			await this.#recordResultForTarget(target, command, result, options);
+			return result;
+		} finally {
+			if (!targetTransferred) await this.#releaseSessionTarget(target);
+		}
+	}
+
+	/** Records a bash result supplied outside executeBash in the current ownership scope. */
+	recordBashResult(command: string, result: BashResult, options?: { excludeFromContext?: boolean }): void {
+		const target = this.#captureSessionTarget();
+		const message = this.#createMessage(command, result, options);
+		if (this.#host.isStreaming() && target === this.#sessionTarget) {
+			this.#pendingMessages.push({ target, message });
+			return;
+		}
+		if (target.destination) {
+			try {
+				this.#appendMessage(target.destination, message);
+			} finally {
+				void this.#releaseSessionTarget(target);
+			}
+			return;
+		}
+		void this.#appendOwnedMessage(target, message).catch(error => {
+			logger.error("Failed to record bash result in its owning session", { error: String(error) });
+		});
+	}
+
+	/** Cancels every running bash command. */
+	abort(): void {
+		for (const abortController of this.#abortControllers) abortController.abort();
+	}
+
+	/** Whether a bash command is currently running. */
+	get isRunning(): boolean {
+		return this.#abortControllers.size > 0;
+	}
+
+	/** Whether bash results are waiting for a safe persistence boundary. */
+	get hasPendingMessages(): boolean {
+		return this.#pendingMessages.length > 0;
+	}
+
+	/** Flushes deferred bash results without changing their captured ownership. */
+	async flushPending(): Promise<void> {
+		if (this.#pendingMessages.length === 0) return;
+		const pending = this.#pendingMessages;
+		this.#pendingMessages = [];
+		for (const { target, message } of pending) await this.#appendOwnedMessage(target, message);
+	}
+
+	/** Runs a leaf rewrite while retaining in-flight bash on its originating branch. */
+	withBranchTransition<T>(mutate: () => T): T {
+		const transition = this.beginSessionTransition();
+		let transitioned = false;
+		try {
+			const result = mutate();
+			this.markSessionTransition(transition);
+			transitioned = true;
+			return result;
+		} finally {
+			this.finishSessionTransition(transition, transitioned);
+		}
+	}
+
+	/** Snapshots the owner of in-flight bash before a session or branch transition. */
+	beginSessionTransition(options?: { persistDetached?: boolean }): BashSessionTransition {
+		const oldTarget = this.#sessionTarget;
+		let detachedManager: SessionManager | undefined;
+		let resolveOld: ((destination: BashAppendDestination) => void) | undefined;
+		if (oldTarget.refs > 0) {
+			detachedManager = this.#host.sessionManager.cloneCurrentSession({ persist: options?.persistDetached });
+			const pendingOld = Promise.withResolvers<BashAppendDestination>();
+			oldTarget.destination = undefined;
+			oldTarget.pending = pendingOld.promise;
+			resolveOld = pendingOld.resolve;
+		}
+		const pendingNew = Promise.withResolvers<BashAppendDestination>();
+		return {
+			oldTarget,
+			newTarget: {
+				sessionId: this.#host.sessionManager.getSessionId(),
+				refs: 0,
+				pending: pendingNew.promise,
+			},
+			oldSessionId: this.#host.sessionManager.getSessionId(),
+			oldSessionFile: this.#host.sessionManager.getSessionFile(),
+			oldLeafId: this.#host.sessionManager.getLeafId(),
+			detachedManager,
+			resolveOld,
+			resolveNew: pendingNew.resolve,
+		};
+	}
+
+	/** Adopts a transition's new target as the live bash owner. */
+	markSessionTransition(transition: BashSessionTransition): void {
+		transition.newTarget.sessionId = this.#host.sessionManager.getSessionId();
+		this.#sessionTarget = transition.newTarget;
+	}
+
+	/** Resolves destinations opened by beginSessionTransition. */
+	finishSessionTransition(transition: BashSessionTransition, success: boolean): void {
+		const manager = this.#host.sessionManager;
+		const currentDestination: BashAppendDestination = { kind: "current", manager };
+		let oldDestination: BashAppendDestination = currentDestination;
+		if (success && transition.resolveOld) {
+			const currentFile = manager.getSessionFile();
+			const sameFile =
+				transition.oldSessionFile === currentFile ||
+				(transition.oldSessionFile !== undefined &&
+					currentFile !== undefined &&
+					path.resolve(transition.oldSessionFile) === path.resolve(currentFile));
+			const sameSession = transition.oldSessionId === manager.getSessionId() && sameFile;
+			if (sameSession) {
+				oldDestination =
+					transition.oldLeafId === manager.getLeafId()
+						? currentDestination
+						: { kind: "branch", manager, parentId: transition.oldLeafId };
+			} else if (transition.detachedManager) {
+				oldDestination = { kind: "detached", manager: transition.detachedManager };
+			}
+		}
+		if (transition.resolveOld) {
+			transition.oldTarget.pending = undefined;
+			transition.oldTarget.destination = oldDestination;
+			transition.resolveOld(oldDestination);
+		}
+		transition.newTarget.pending = undefined;
+		transition.newTarget.destination = currentDestination;
+		if (!success) transition.newTarget.sessionId = manager.getSessionId();
+		transition.resolveNew(currentDestination);
+		if (transition.detachedManager && (oldDestination.kind !== "detached" || transition.oldTarget.refs === 0)) {
+			void transition.detachedManager.close().catch(error => {
+				logger.warn("Failed to close detached bash session writer", { error: String(error) });
+			});
+		}
+	}
+
+	async #saveOriginalArtifact(target: BashSessionTarget, originalText: string): Promise<string | undefined> {
+		try {
+			const destination = target.destination ?? (await target.pending);
+			return await destination?.manager.saveArtifact(originalText, "bash-original");
+		} catch {
+			return undefined;
+		}
+	}
+
+	#createMessage(
+		command: string,
+		result: BashResult,
+		options?: { excludeFromContext?: boolean },
+	): BashExecutionMessage {
+		const meta = outputMeta().truncationFromSummary(result, { direction: "tail" }).get();
+		return {
+			role: "bashExecution",
+			command,
+			output: result.output,
+			exitCode: result.exitCode,
+			cancelled: result.cancelled,
+			truncated: result.truncated,
+			meta,
+			timestamp: Date.now(),
+			excludeFromContext: options?.excludeFromContext,
+		};
+	}
+
+	#captureSessionTarget(): BashSessionTarget {
+		this.#sessionTarget.refs++;
+		return this.#sessionTarget;
+	}
+
+	async #releaseSessionTarget(target: BashSessionTarget): Promise<void> {
+		if (target.refs <= 0) throw new Error("Bash session target released more than once");
+		target.refs--;
+		if (target.refs === 0 && target.destination?.kind === "detached") await target.destination.manager.close();
+	}
+
+	#appendMessage(destination: BashAppendDestination, message: BashExecutionMessage): void {
+		switch (destination.kind) {
+			case "current":
+				this.#host.agent.appendMessage(message);
+				destination.manager.appendMessage(message);
+				break;
+			case "detached":
+				destination.manager.appendMessage(message);
+				break;
+			case "branch":
+				destination.parentId = destination.manager.appendMessageToBranch(message, destination.parentId);
+				break;
+		}
+	}
+
+	async #appendOwnedMessage(target: BashSessionTarget, message: BashExecutionMessage): Promise<void> {
+		try {
+			const destination = target.destination ?? (await target.pending);
+			if (!destination) throw new Error("Bash session target has no append destination");
+			this.#appendMessage(destination, message);
+		} finally {
+			await this.#releaseSessionTarget(target);
+		}
+	}
+
+	async #recordResultForTarget(
+		target: BashSessionTarget,
+		command: string,
+		result: BashResult,
+		options?: { excludeFromContext?: boolean },
+	): Promise<void> {
+		const message = this.#createMessage(command, result, options);
+		if (this.#host.isStreaming() && target === this.#sessionTarget) {
+			this.#pendingMessages.push({ target, message });
+			return;
+		}
+		await this.#appendOwnedMessage(target, message);
+	}
+}

package/src/session/blob-store.test.ts

@@ -0,0 +1,56 @@
+import { afterAll, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { BlobStore, parseBlobRef, resolveImageData, resolveImageDataSync, resolveImageDataUrl } from "./blob-store";
+
+const base = fs.mkdtempSync(path.join(os.tmpdir(), "blob-store-test-"));
+const blobDir = path.join(base, "agent", "blobs", "data");
+fs.mkdirSync(blobDir, { recursive: true });
+fs.writeFileSync(path.join(base, "secret.txt"), "TOP-SECRET-CONTENTS");
+const store = new BlobStore(blobDir);
+
+afterAll(() => {
+	fs.rmSync(base, { recursive: true, force: true });
+});
+
+describe("parseBlobRef validation", () => {
+	it("accepts a canonical 64-char lowercase hex suffix", () => {
+		const hash = "a".repeat(64);
+		expect(parseBlobRef(`blob:sha256:${hash}`)).toBe(hash);
+	});
+
+	it("returns null for non-blob strings", () => {
+		expect(parseBlobRef("data:image/png;base64,AAAA")).toBeNull();
+	});
+
+	it.each([
+		"../../../secret.txt",
+		`${"../".repeat(6)}etc/passwd`,
+		"A".repeat(64), // uppercase hex is not the canonical shape
+		"a".repeat(63), // too short
+		"a".repeat(65), // too long
+		"", // empty
+	])("rejects malformed suffix %p", suffix => {
+		expect(parseBlobRef(`blob:sha256:${suffix}`)).toBeNull();
+	});
+});
+
+describe("blob resolution path confinement", () => {
+	const traversalRef = "blob:sha256:../../../secret.txt";
+
+	it("leaves a traversal ref unresolved instead of reading outside the blob dir (base64 path)", async () => {
+		expect(await resolveImageData(store, traversalRef)).toBe(traversalRef);
+		expect(resolveImageDataSync(store, traversalRef)).toBe(traversalRef);
+	});
+
+	it("leaves a traversal ref unresolved instead of reading outside the blob dir (data-url path)", async () => {
+		expect(await resolveImageDataUrl(store, traversalRef)).toBe(traversalRef);
+	});
+
+	it("still resolves a valid stored blob", async () => {
+		const put = store.putSync(Buffer.from("hello"));
+		expect(Buffer.from(resolveImageDataSync(store, put.ref), "base64").toString("utf8")).toBe("hello");
+		expect(Buffer.from(await resolveImageData(store, put.ref), "base64").toString("utf8")).toBe("hello");
+	});
+});

package/src/session/blob-store.ts

@@ -5,6 +5,9 @@ import { isEnoent, logger } from "@oh-my-pi/pi-utils";
 
 const BLOB_PREFIX = "blob:sha256:";
 
+/** Canonical blob hash shape: exactly 64 lowercase hex chars (a SHA-256 digest). */
+export const BLOB_HASH_RE = /^[a-f0-9]{64}$/;
+
 export interface BlobPutOptions {
 	/** Optional file extension for a sidecar hardlink/copy that OS openers can type-detect. */
 	extension?: string;
@@ -179,10 +182,23 @@ export function isBlobRef(data: string): boolean {
 	return data.startsWith(BLOB_PREFIX);
 }
 
-/** Extract the SHA-256 hash from a blob reference string. */
+/**
+ * Extract the SHA-256 hash from a blob reference string.
+ *
+ * Returns null when the string is not a blob ref, or when the suffix is not a
+ * canonical 64-char lowercase hex hash. Rejecting non-hash suffixes here is the
+ * single choke point that keeps every resolution path confined to the blob dir:
+ * `get`/`getSync` feed this value into `path.join(this.dir, hash)`, so an
+ * unvalidated `../` suffix would otherwise escape the store and read arbitrary files.
+ */
 export function parseBlobRef(data: string): string | null {
 	if (!data.startsWith(BLOB_PREFIX)) return null;
-	return data.slice(BLOB_PREFIX.length);
+	const hash = data.slice(BLOB_PREFIX.length);
+	if (!BLOB_HASH_RE.test(hash)) {
+		logger.warn("Rejected malformed blob reference", { suffix: hash });
+		return null;
+	}
+	return hash;
 }
 
 /** Identify provider transport image data URLs so persistence can externalize and restore them losslessly. */

package/src/session/checkpoint-entries.ts

@@ -0,0 +1,81 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import { stringProperty } from "@oh-my-pi/pi-utils";
+import type { CompletedRewindState } from "../tools/checkpoint";
+import { writeDeviceDispatch } from "../tools/resolve";
+import type { SessionEntry } from "./session-entries";
+
+/** Extracts text from custom message content. */
+export function customMessageContentText(content: string | (TextContent | ImageContent)[]): string {
+	if (typeof content === "string") return content;
+	const parts: string[] = [];
+	for (const part of content) {
+		if (part.type === "text") parts.push(part.text);
+	}
+	return parts.join("\n");
+}
+
+/** Extracts the report body from persisted rewind-report content. */
+export function reportFromRewindReportContent(content: string): string {
+	const marker = "\nReport:\n";
+	const index = content.lastIndexOf(marker);
+	const report = index >= 0 ? content.slice(index + marker.length) : content;
+	return report.trim();
+}
+
+/** Checkpoint-domain tool names normalized from native and xdev calls. */
+export type SemanticCheckpointToolName = "checkpoint" | "rewind";
+
+/** Normalized checkpoint-domain tool result. */
+export interface SemanticToolResult {
+	toolName: SemanticCheckpointToolName;
+	details?: unknown;
+}
+
+/** Normalizes checkpoint and rewind results across native calls and xdev dispatches. */
+export function semanticToolResult(toolName: string | undefined, result: unknown): SemanticToolResult | undefined {
+	if (toolName === "checkpoint" || toolName === "rewind") {
+		const details = result && typeof result === "object" && "details" in result ? result.details : undefined;
+		return { toolName, details };
+	}
+	const dispatch = writeDeviceDispatch(toolName ?? "", result);
+	if (dispatch?.mode !== "execute" || (dispatch.tool !== "checkpoint" && dispatch.tool !== "rewind")) {
+		return undefined;
+	}
+	return { toolName: dispatch.tool, details: dispatch.inner };
+}
+
+/** Restores completed rewind state from a persisted session entry. */
+export function completedRewindFromEntry(entry: SessionEntry): CompletedRewindState | undefined {
+	if (entry.type !== "custom_message" || entry.customType !== "rewind-report") return undefined;
+	const details = entry.details;
+	if (!details || typeof details !== "object") return undefined;
+	const startedAt = stringProperty(details, "startedAt");
+	const rewoundAt = stringProperty(details, "rewoundAt");
+	if (!startedAt || !rewoundAt) return undefined;
+	const report =
+		stringProperty(details, "report")?.trim() ||
+		reportFromRewindReportContent(customMessageContentText(entry.content));
+	return report.length > 0 ? { report, startedAt, rewoundAt } : undefined;
+}
+
+/** Whether an entry is a successful checkpoint tool result. */
+export function isSuccessfulCheckpointEntry(
+	entry: SessionEntry,
+): entry is SessionEntry & { type: "message"; message: Extract<AgentMessage, { role: "toolResult" }> } {
+	if (entry.type !== "message" || entry.message.role !== "toolResult" || entry.message.isError === true) {
+		return false;
+	}
+	return semanticToolResult(entry.message.toolName, entry.message)?.toolName === "checkpoint";
+}
+
+/** Returns the checkpoint start timestamp represented by an entry. */
+export function checkpointStartedAtFromEntry(entry: SessionEntry): string | undefined {
+	if (!isSuccessfulCheckpointEntry(entry)) return undefined;
+	const details = semanticToolResult(entry.message.toolName, entry.message)?.details;
+	if (details && typeof details === "object") {
+		const startedAt = stringProperty(details, "startedAt");
+		if (startedAt) return startedAt;
+	}
+	return entry.timestamp;
+}