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

package/src/session/session-context.ts

@@ -18,6 +18,8 @@ import { type CompactionEntry, EPHEMERAL_MODEL_CHANGE_ROLE, type SessionEntry }
 const LEGACY_SNAPCOMPACT_FRAME_COUNT_GUARD = 16;
 const LEGACY_SNAPCOMPACT_ARCHIVE_TEXT_GUARD = 250_000;
 const LEGACY_SNAPCOMPACT_TRUNCATED_CHARS_GUARD = 1_000_000;
+const SUPERSEDED_COMPACTION_SUMMARY = "[Superseded compaction summary elided after a newer compaction]";
+const SUPERSEDED_COMPACTION_SHORT_SUMMARY = "Superseded compaction elided";
 
 function hasLegacySnapcompactFrames(archive: snapcompact.Archive): boolean {
 	return archive.frames.some(frame => frame.font === undefined && frame.variant === undefined);
@@ -344,13 +346,14 @@ export function buildSessionContext(
 		for (const entry of path) {
 			handleEntryResetTracking(entry);
 			if (entry.type === "compaction") {
-				const snapcompactArchive = snapcompact.getPreservedArchive(entry.preserveData);
+				const active = entry.id === compaction?.id;
+				const snapcompactArchive = active ? snapcompact.getPreservedArchive(entry.preserveData) : undefined;
 				pushMessage(
 					createCompactionSummaryMessage(
-						entry.summary,
+						active ? entry.summary : SUPERSEDED_COMPACTION_SUMMARY,
 						entry.tokensBefore,
 						entry.timestamp,
-						entry.shortSummary,
+						active ? entry.shortSummary : SUPERSEDED_COMPACTION_SHORT_SUMMARY,
 						undefined,
 						undefined,
 						snapcompactHistoryBlocksForContext(snapcompactArchive, options),

package/src/session/session-entries.ts

@@ -32,6 +32,12 @@ export interface SessionHeader {
 	titleSource?: SessionTitleSource;
 	timestamp: string;
 	cwd: string;
+	/**
+	 * Additional workspace directories beyond `cwd` (multi-root workspace).
+	 * Absolute, normalized, deduplicated. Absent on legacy single-cwd sessions.
+	 * See {@link SessionWorkspace} in `./session-workspace`.
+	 */
+	additionalDirectories?: string[];
 	parentSession?: string;
 	/** Provider prompt-cache identity inherited by exact-route full forks. */
 	providerPromptCacheKey?: string;
@@ -43,6 +49,8 @@ export interface NewSessionOptions {
 	providerPromptCacheKey?: string;
 	/** Skip flushing the current session and delete it instead of saving. */
 	drop?: boolean;
+	/** Additional workspace directories to seed on the new session. */
+	additionalDirectories?: string[];
 }
 
 export interface SessionEntryBase {

package/src/session/session-handoff.ts

@@ -0,0 +1,308 @@
+/** Handoff generation and session transition orchestration. */
+
+import * as path from "node:path";
+import {
+	type Agent,
+	type AgentMessage,
+	resolveTelemetry,
+	type StreamFn,
+	type ThinkingLevel,
+} from "@oh-my-pi/pi-agent-core";
+import { generateHandoffFromContext, renderHandoffPrompt } from "@oh-my-pi/pi-agent-core/compaction";
+import type { Message, Model, ServiceTier, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import { logger, Snowflake } from "@oh-my-pi/pi-utils";
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+import type { ExtensionRunner, SessionBeforeSwitchResult } from "../extensibility/extensions";
+import { obfuscateProviderContext, type SecretObfuscator } from "../secrets/obfuscator";
+import type { HandoffResult, SessionHandoffOptions } from "./agent-session-types";
+import type { BashSessionTransition } from "./bash-runner";
+import type { SessionContext } from "./session-context";
+import type { SessionManager } from "./session-manager";
+
+function createHandoffContext(document: string): string {
+	return `<handoff-context>\n${document}\n</handoff-context>\n\nThe above is a handoff document from a previous session. Use this context to continue the work seamlessly.`;
+}
+
+function createHandoffFileName(date = new Date()): string {
+	const fileTimestamp = date.toISOString().replace(/[:.]/g, "-");
+	return `handoff-${fileTimestamp}.md`;
+}
+
+/** Capabilities borrowed from the owning AgentSession. */
+export interface SessionHandoffHost {
+	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	extensionRunner: ExtensionRunner | undefined;
+	sideStreamFn: StreamFn;
+	obfuscator: SecretObfuscator | undefined;
+	model(): Model | undefined;
+	thinkingLevel(): ThinkingLevel | undefined;
+	sessionId(): string;
+	sessionFile(): string | undefined;
+	baseSystemPrompt(): string[];
+	assertVibeSessionTransitionAllowed(action: string): void;
+	setSkipPostTurnMaintenance(timestamp: number | undefined): void;
+	obfuscateTextForProvider(text: string | undefined): string | undefined;
+	deobfuscateFromProvider(text: string): string;
+	convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
+	prepareSimpleStreamOptions(options: SimpleStreamOptions, provider?: string): SimpleStreamOptions;
+	effectiveServiceTier(model: Model | undefined): ServiceTier | undefined;
+	flushPendingBash(): Promise<void>;
+	beginBashSessionTransition(): BashSessionTransition;
+	markBashSessionTransition(transition: BashSessionTransition): void;
+	finishBashSessionTransition(transition: BashSessionTransition, success: boolean): void;
+	cancelOwnAsyncJobs(): void;
+	clearCheckpointRuntimeState(): void;
+	clearSessionScopedToolState(): void;
+	clearFreshProviderSessionId(): void;
+	syncAgentSessionId(): void;
+	rekeyMemoryForCurrentSessionId(): void;
+	resetMemoryContextForNewTranscript(): Promise<void>;
+	clearPendingNextTurnMessages(): void;
+	resetTodoCycle(): void;
+	buildDisplaySessionContext(): SessionContext;
+	resetAdvisorRuntimes(): void;
+	syncTodoPhasesFromBranch(): void;
+}
+
+/** Generates handoff documents and owns the handoff session transition. */
+export class SessionHandoff {
+	#handoffAbortController: AbortController | undefined;
+	readonly #host: SessionHandoffHost;
+
+	constructor(host: SessionHandoffHost) {
+		this.#host = host;
+	}
+	/**
+	 * Cancel in-progress handoff generation.
+	 */
+	abortHandoff(): void {
+		this.#handoffAbortController?.abort();
+	}
+
+	/**
+	 * Check if handoff generation is in progress.
+	 */
+	get isGeneratingHandoff(): boolean {
+		return this.#handoffAbortController !== undefined;
+	}
+
+	/**
+	 * Generate a handoff document with a oneshot LLM call, then start a new session with it.
+	 *
+	 * @param customInstructions Optional focus for the handoff document
+	 * @param options Handoff execution options
+	 * @returns The handoff document text, or undefined if cancelled/failed
+	 */
+	async handoff(customInstructions?: string, options?: SessionHandoffOptions): Promise<HandoffResult | undefined> {
+		this.#host.assertVibeSessionTransitionAllowed("handoff to a new session");
+		const entries = this.#host.sessionManager.getBranch();
+		const messageCount = entries.filter(e => e.type === "message").length;
+
+		if (messageCount < 2) {
+			throw new Error("Nothing to hand off (no messages yet)");
+		}
+
+		this.#host.setSkipPostTurnMaintenance(undefined);
+
+		this.#handoffAbortController = new AbortController();
+		const handoffAbortController = this.#handoffAbortController;
+		const handoffSignal = handoffAbortController.signal;
+		const sourceSignal = options?.signal;
+		const onSourceAbort = () => {
+			if (!handoffSignal.aborted) {
+				handoffAbortController.abort();
+			}
+		};
+		if (sourceSignal) {
+			sourceSignal.addEventListener("abort", onSourceAbort, { once: true });
+			if (sourceSignal.aborted) {
+				onSourceAbort();
+			}
+		}
+
+		try {
+			if (handoffSignal.aborted) {
+				throw new Error("Handoff cancelled");
+			}
+
+			const model = this.#host.model();
+			if (!model) {
+				throw new Error("No model selected for handoff");
+			}
+			const apiKey = await this.#host.modelRegistry.getApiKey(model, this.#host.sessionId());
+			if (!apiKey) {
+				throw new Error(`No API key for ${model.provider}`);
+			}
+
+			// Build the handoff request through the SAME pipeline a live turn uses
+			// (`runEphemeralTurn` / `/btw` share it) so the oneshot reads the
+			// provider prompt cache the main turn populated instead of cold-missing
+			// the whole prefix: identical system prompt, normalized tools, and
+			// transform-/obfuscation-matched message history via
+			// `convertMessagesToLlm` + `buildSideRequestContext`, plus the live turn's
+			// effective provider cache key with a unique side `sessionId` so
+			// OpenAI/Codex append-only state never mixes with the live turn.
+			const cacheSessionId = this.#host.sessionId();
+			// The loop sends `promptCacheKey` (providerPromptCacheKey) and falls back to
+			// the provider session id; providers route on `promptCacheKey ?? sessionId`.
+			// Both can diverge from this.#host.sessionId() (tan/subagent/shared sessions), so
+			// mirror exactly what the live turn populated the cache under.
+			const handoffPromptCacheKey = this.#host.agent.promptCacheKey ?? this.#host.agent.sessionId;
+			const handoffPromptText = renderHandoffPrompt(this.#host.obfuscateTextForProvider(customInstructions));
+			const handoffSnapshot: AgentMessage[] = [
+				...this.#host.agent.state.messages,
+				{
+					role: "user",
+					content: [{ type: "text", text: handoffPromptText }],
+					attribution: "agent",
+					timestamp: Date.now(),
+				},
+			];
+			const handoffLlmMessages = await this.#host.convertMessagesToLlm(handoffSnapshot, handoffSignal);
+			// Base system prompt, not a per-turn `before_agent_start` hook override —
+			// the handoff seeds a fresh session and must not carry prompt-specific
+			// hook state. Matches the prompt the old handoff path sent.
+			const handoffContext = await this.#host.agent.buildSideRequestContext(
+				handoffLlmMessages,
+				this.#host.baseSystemPrompt(),
+			);
+			const handoffStreamOptions = this.#host.prepareSimpleStreamOptions(
+				{
+					apiKey: this.#host.modelRegistry.resolver(model, cacheSessionId),
+					sessionId: `${cacheSessionId}:side:${Snowflake.next()}`,
+					promptCacheKey: handoffPromptCacheKey,
+					preferWebsockets: false,
+					serviceTier: this.#host.effectiveServiceTier(model),
+					hideThinkingSummary: this.#host.agent.hideThinkingSummary,
+					initiatorOverride: "agent",
+					signal: handoffSignal,
+				},
+				model.provider,
+			);
+			const rawHandoffText = await generateHandoffFromContext(
+				obfuscateProviderContext(this.#host.obfuscator, handoffContext),
+				model,
+				{
+					streamOptions: handoffStreamOptions,
+					completeImpl: async (requestModel, requestContext, requestOptions) => {
+						const stream = await this.#host.sideStreamFn(requestModel, requestContext, requestOptions);
+						return stream.result();
+					},
+					telemetry: resolveTelemetry(this.#host.agent.telemetry, this.#host.sessionId()),
+					// Honor the user's /model thinking selection on the handoff path.
+					// Clamped per-model inside generateHandoffFromContext via
+					// resolveCompactionEffort so unsupported-effort models don't trip
+					// requireSupportedEffort.
+					thinkingLevel: this.#host.thinkingLevel(),
+				},
+			);
+			const handoffText = this.#host.deobfuscateFromProvider(rawHandoffText);
+
+			if (handoffSignal.aborted) {
+				throw new Error("Handoff cancelled");
+			}
+			if (!handoffText) {
+				return undefined;
+			}
+
+			// Start a new session
+			const previousSessionFile = this.#host.sessionFile();
+			if (this.#host.extensionRunner?.hasHandlers("session_before_switch")) {
+				const result = (await this.#host.extensionRunner.emit({
+					type: "session_before_switch",
+					reason: "handoff",
+				})) as SessionBeforeSwitchResult | undefined;
+
+				if (result?.cancel) {
+					options?.onSwitchCancelled?.();
+					return undefined;
+				}
+			}
+			await this.#host.flushPendingBash();
+			await this.#host.sessionManager.flush();
+			const bashTransition = this.#host.beginBashSessionTransition();
+			this.#host.cancelOwnAsyncJobs();
+			let sessionTransitioned = false;
+			try {
+				await this.#host.sessionManager.newSession(
+					previousSessionFile ? { parentSession: previousSessionFile } : undefined,
+				);
+				this.#host.markBashSessionTransition(bashTransition);
+				sessionTransitioned = true;
+			} finally {
+				this.#host.finishBashSessionTransition(bashTransition, sessionTransitioned);
+			}
+
+			this.#host.clearSessionScopedToolState();
+
+			this.#host.clearCheckpointRuntimeState();
+			// agent.reset() clears the core steering/follow-up queues. Preserve any queued
+			// steers/follow-ups (RPC/SDK steer()/followUp() issued during the handoff, or a
+			// pre-loader TUI steer) so they survive into the post-handoff session instead of
+			// being silently dropped. Capture is synchronous immediately before reset and
+			// restore is synchronous immediately after — no await gap — so a steer arriving
+			// later (during ensureOnDisk/Bun.write below) appends to the restored queue
+			// rather than being clobbered.
+			const preservedSteering = this.#host.agent.peekSteeringQueue().slice();
+			const preservedFollowUp = this.#host.agent.peekFollowUpQueue().slice();
+			this.#host.agent.reset();
+			this.#host.agent.replaceQueues(preservedSteering, preservedFollowUp);
+			this.#host.clearFreshProviderSessionId();
+			this.#host.syncAgentSessionId();
+			this.#host.rekeyMemoryForCurrentSessionId();
+			await this.#host.resetMemoryContextForNewTranscript();
+			this.#host.clearPendingNextTurnMessages();
+			this.#host.resetTodoCycle();
+
+			// Inject the handoff document as a custom message
+			const handoffContent = createHandoffContext(handoffText);
+			this.#host.sessionManager.appendCustomMessageEntry("handoff", handoffContent, true, undefined, "agent");
+			await this.#host.sessionManager.ensureOnDisk();
+			let savedPath: string | undefined;
+			if (options?.autoTriggered && this.#host.settings.get("compaction.handoffSaveToDisk")) {
+				const artifactsDir = this.#host.sessionManager.getArtifactsDir();
+				if (artifactsDir) {
+					const handoffFilePath = path.join(artifactsDir, createHandoffFileName());
+					try {
+						await Bun.write(handoffFilePath, `${handoffText}\n`);
+						savedPath = handoffFilePath;
+					} catch (error) {
+						logger.warn("Failed to save handoff document to disk", {
+							path: handoffFilePath,
+							error: error instanceof Error ? error.message : String(error),
+						});
+					}
+				} else {
+					logger.debug("Skipping handoff document save because session is not persisted");
+				}
+			}
+
+			// Rebuild agent messages from session
+			const sessionContext = this.#host.buildDisplaySessionContext();
+			this.#host.agent.replaceMessages(sessionContext.messages);
+			this.#host.resetAdvisorRuntimes();
+			this.#host.syncTodoPhasesFromBranch();
+			if (this.#host.extensionRunner) {
+				await this.#host.extensionRunner.emit({
+					type: "session_switch",
+					reason: "handoff",
+					previousSessionFile,
+				});
+			}
+
+			return { document: handoffText, savedPath };
+		} catch (error) {
+			if (handoffSignal.aborted || (error instanceof Error && error.name === "AbortError")) {
+				throw new Error("Handoff cancelled");
+			}
+			throw error;
+		} finally {
+			sourceSignal?.removeEventListener("abort", onSourceAbort);
+			this.#handoffAbortController = undefined;
+		}
+	}
+}

package/src/session/session-history-format.ts

@@ -85,6 +85,10 @@ function oneLine(text: string, max = PRIMARY_ARG_MAX): string {
 	return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
 
+export function formatExecutionSourcePreview(source: string): string {
+	return oneLine(source);
+}
+
 /** Join the text blocks of a string-or-blocks content field. Images become `[image]`. */
 function contentToText(content: string | readonly (TextContent | ImageContent)[]): string {
 	if (typeof content === "string") return content;
@@ -110,7 +114,7 @@ function primaryArgValue(value: unknown): string {
 }
 
 /** Pick the most informative scalar argument of a tool call. */
-function primaryArg(name: string, args: Record<string, unknown> | undefined): string {
+export function formatToolCallPrimaryArg(name: string, args: Record<string, unknown> | undefined): string {
 	if (!args || typeof args !== "object") return "";
 	// Advisor note is the most informative summary; preserve severity too.
 	if (name === "advise") {
@@ -158,6 +162,15 @@ function primaryArg(name: string, args: Record<string, unknown> | undefined): st
 	}
 }
 
+export function formatToolCallIntentPreview(args: Record<string, unknown> | undefined): string | undefined {
+	const intent = args?.[INTENT_FIELD];
+	return typeof intent === "string" && intent.trim() ? oneLine(intent, 80) : undefined;
+}
+
+export function formatToolResultErrorPreview(content: string | readonly (TextContent | ImageContent)[]): string {
+	return oneLine(contentToText(content).split("\n", 1)[0] ?? "");
+}
+
 /**
  * Wrap a diff body in a backtick fence sized to outlast the longest backtick
  * run inside it, so a diff that touches markdown (triple backticks) can't break
@@ -177,7 +190,7 @@ function toolCallLine(
 	includeToolIntent?: boolean,
 	expandEditDiffs?: boolean,
 ): string {
-	const head = `→ ${name}(${primaryArg(name, args)})`;
+	const head = `→ ${name}(${formatToolCallPrimaryArg(name, args)})`;
 	let base: string;
 	if (!result) {
 		base = `${head} ⇒ pending`;
@@ -186,7 +199,7 @@ function toolCallLine(
 		const lines = lineCount(text);
 		const count = `${lines} ${lines === 1 ? "line" : "lines"}`;
 		if (result.isError) {
-			const firstLine = oneLine(text.split("\n", 1)[0] ?? "");
+			const firstLine = formatToolResultErrorPreview(result.content);
 			base = firstLine ? `${head} ⇒ error · ${count} — ${firstLine}` : `${head} ⇒ error · ${count}`;
 		} else {
 			base = `${head} ⇒ ok · ${count}`;
@@ -200,11 +213,8 @@ function toolCallLine(
 		}
 	}
 
-	const intent = includeToolIntent ? args?.[INTENT_FIELD] : undefined;
-	if (typeof intent === "string" && intent.trim()) {
-		const formattedIntent = oneLine(intent, 80);
-		return `// ${formattedIntent}\n${base}`;
-	}
+	const formattedIntent = includeToolIntent ? formatToolCallIntentPreview(args) : undefined;
+	if (formattedIntent) return `// ${formattedIntent}\n${base}`;
 	return base;
 }
 
@@ -220,7 +230,8 @@ function executionLine(
 			? `error · exit ${msg.exitCode}`
 			: "ok";
 	const lines = lineCount(msg.output);
-	return `→ ${kind}! ${oneLine(source)} ⇒ ${status} · ${lines} ${lines === 1 ? "line" : "lines"}`;
+	const sourcePreview = formatExecutionSourcePreview(source);
+	return `→ ${kind}! ${sourcePreview} ⇒ ${status} · ${lines} ${lines === 1 ? "line" : "lines"}`;
 }
 
 /**

package/src/session/session-loader.ts

@@ -3,7 +3,6 @@ import { getBlobsDir, isEnoent, parseJsonlLenient } from "@oh-my-pi/pi-utils";
 import { BlobStore, isBlobRef, resolveImageData, resolveImageDataUrl } from "./blob-store";
 import { buildSessionContext } from "./session-context";
 import {
-	type CompactionEntry,
 	type FileEntry,
 	type RawFileEntry,
 	SESSION_TITLE_SLOT_BYTES,
@@ -22,8 +21,6 @@ import {
 } from "./session-title-slot";
 
 const STREAM_LOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;
-const ELIDED_COMPACTION_SUMMARY = "[Superseded compaction summary elided during session load]";
-const ELIDED_COMPACTION_SHORT_SUMMARY = "Superseded compaction elided";
 
 function splitTitleSlot(content: string): { body: string; slot: SessionTitleUpdate | undefined } {
 	const slot = titleUpdateFromSlot(parseTitleSlotFromContent(content));
@@ -59,48 +56,6 @@ export function parseSessionContent(content: string): {
 	return { entries: foldTitleSlot(entries, slot), titleSlot: slot };
 }
 
-function elideCompactionSummary(entry: CompactionEntry | undefined): boolean {
-	if (!entry) return false;
-	if (
-		entry.summary === ELIDED_COMPACTION_SUMMARY &&
-		entry.shortSummary === ELIDED_COMPACTION_SHORT_SUMMARY &&
-		entry.preserveData === undefined
-	) {
-		return false;
-	}
-	entry.summary = ELIDED_COMPACTION_SUMMARY;
-	entry.shortSummary = ELIDED_COMPACTION_SHORT_SUMMARY;
-	entry.preserveData = undefined;
-	return true;
-}
-
-function collectActiveBranchIds(entries: FileEntry[]): Set<string> {
-	const byId = new Map<string, SessionEntry>();
-	for (const entry of entries) {
-		const id = (entry as SessionEntry).id;
-		if (typeof id === "string") byId.set(id, entry as SessionEntry);
-	}
-	const branchIds = new Set<string>();
-	let cursor = entries[entries.length - 1] as SessionEntry | undefined;
-	while (cursor && typeof cursor.id === "string" && !branchIds.has(cursor.id)) {
-		branchIds.add(cursor.id);
-		const parentId = cursor.parentId;
-		cursor = parentId ? byId.get(parentId) : undefined;
-	}
-	return branchIds;
-}
-
-function elideSupersededCompactionEntries(entries: FileEntry[]): void {
-	const branchIds = collectActiveBranchIds(entries);
-	let previousCompaction: CompactionEntry | undefined;
-	for (const entry of entries) {
-		if (entry.type !== "compaction") continue;
-		if (!branchIds.has(entry.id)) continue;
-		elideCompactionSummary(previousCompaction);
-		previousCompaction = entry;
-	}
-}
-
 /** Exported for testing — the ≥8MiB streaming path (works on any file size). */
 export async function loadEntriesFromFileStream(filePath: string): Promise<{
 	entries: FileEntry[];
@@ -215,7 +170,6 @@ export async function loadEntriesFromFile(
 		throw err;
 	}
 	const { entries } = loaded;
-	elideSupersededCompactionEntries(entries);
 
 	// Validate session header
 	if (entries.length === 0) return entries;