@oh-my-pi/pi-agent-core 18.15.0 → 18.17.0

package/src/agent.ts

@@ -62,6 +62,7 @@ import type {
 	AsideBoundary,
 	AsideMessage,
 	PrepareQueuedMessages,
+	QueuedMessageGate,
 	QueuedMessageQueue,
 	SpeculativeToolExecutionConfig,
 	StreamFn,
@@ -279,6 +280,8 @@ export interface AgentOptions {
 
 	/** Enable intent tracing schema injection/stripping in the harness. */
 	intentTracing?: boolean;
+	/** Schema description of the injected intent field; `PI_INTENT_DESC` overrides it. Default `concise intent`. */
+	intentDescription?: string;
 	/**
 	 * Strip tool descriptions from provider-bound tool specs (top-level + nested
 	 * schema annotations). Use when the full catalog is rendered into the system
@@ -493,6 +496,7 @@ export class Agent {
 	#resolveFallbackTool?: (name: string, advertised: readonly AgentTool<any>[]) => AgentTool<any> | undefined;
 	#suggestFallbackToolNames?: () => Iterable<string>;
 	#intentTracing: boolean;
+	#intentDescription?: string;
 	#pruneToolDescriptions: boolean;
 	#dialect?: Dialect;
 	#dialectResolver?: (model: Model) => Dialect | undefined;
@@ -525,6 +529,12 @@ export class Agent {
 	getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | undefined;
 	/** Prepare actual queue deliveries after dequeue gates; commit runs only while ownership remains valid. */
 	prepareQueuedMessages?: PrepareQueuedMessages;
+	/**
+	 * Consulted synchronously whenever queued messages are removed for delivery and
+	 * told about claimed messages that went back undelivered (see {@link QueuedMessageGate}).
+	 * Unset, batches are taken as they are.
+	 */
+	queuedMessageGate?: QueuedMessageGate;
 	/**
 	 * Hook invoked after tool arguments are validated and before execution.
 	 * Reassign at any time to swap the implementation (e.g. on extension reload).
@@ -602,6 +612,7 @@ export class Agent {
 		this.#resolveFallbackTool = opts.resolveFallbackTool;
 		this.#suggestFallbackToolNames = opts.suggestFallbackToolNames;
 		this.#intentTracing = opts.intentTracing === true;
+		this.#intentDescription = opts.intentDescription;
 		this.#pruneToolDescriptions = opts.pruneToolDescriptions === true;
 		this.#dialect = opts.dialect;
 		this.#dialectResolver = opts.dialectResolver;
@@ -864,6 +875,11 @@ export class Agent {
 		this.#intentTracing = value;
 	}
 
+	/** The intent field's schema description this agent was built with (`PI_INTENT_DESC` still overrides it). */
+	get intentDescription(): string | undefined {
+		return this.#intentDescription;
+	}
+
 	/** Abort the provider request on a fabricated tool result; applies from the next prompt run. */
 	get abortOnFabricatedToolResult(): boolean | undefined {
 		return this.#abortOnFabricatedToolResult;
@@ -970,6 +986,7 @@ export class Agent {
 			? []
 			: (normalizeTools(this.#toolsForModel(model), {
 					injectIntent: this.#intentTracing,
+					intentDescription: this.#intentDescription,
 					pruneDescriptions: this.#pruneToolDescriptions,
 				}) ?? []);
 		let context: Context = { systemPrompt, messages, tools };
@@ -1042,12 +1059,14 @@ export class Agent {
 		const runController = this.#abortController;
 		if (!prepare) {
 			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0, additional: [] });
+			this.#emitQueueChanged();
 			return messages;
 		}
 
 		const claim: QueuedMessageClaim = { messages, controller: new AbortController() };
 		this.#queuedMessageClaims[queue] = claim;
 		const preparationSignal = AbortSignal.any([signal, claim.controller.signal]);
+		this.#emitQueueChanged();
 		try {
 			const preparation = await prepare(messages, preparationSignal, queue);
 			signal.throwIfAborted();
@@ -1067,6 +1086,7 @@ export class Agent {
 				next: 0,
 				additional: additional ?? [],
 			});
+			this.#emitQueueChanged();
 			return additional?.length ? [...messages, ...additional] : messages;
 		} catch (error) {
 			if (signal.aborted) throw error;
@@ -1086,6 +1106,7 @@ export class Agent {
 		const claim = this.#queuedMessageClaims[queue];
 		if (!claim) return;
 		delete this.#queuedMessageClaims[queue];
+		this.queuedMessageGate?.release(claim.messages);
 		if (restore) {
 			if (queue === "steering") {
 				this.#steeringQueue = [...claim.messages, ...this.#steeringQueue];
@@ -1104,6 +1125,7 @@ export class Agent {
 		// Live steering was taken before anything the run still holds undelivered.
 		this.#liveSteered = this.#liveSteered.filter(entry => {
 			if (entry.controller !== controller) return true;
+			if (entry.message.role === "user") delete entry.message.liveSteered;
 			restored.steering.push(entry.message);
 			return false;
 		});
@@ -1114,12 +1136,14 @@ export class Agent {
 				restored[delivery.queue].push(delivery.messages[i]);
 			}
 		}
+		if (restored.steering.length === 0 && restored.followUp.length === 0) return;
+		this.queuedMessageGate?.release([...restored.steering, ...restored.followUp]);
 		if (restored.steering.length > 0) {
 			this.#steeringQueue = [...restored.steering, ...this.#steeringQueue];
 			this.#notifySteeringWaiters();
 		}
 		if (restored.followUp.length > 0) this.#followUpQueue = [...restored.followUp, ...this.#followUpQueue];
-		if (restored.steering.length > 0 || restored.followUp.length > 0) this.#emitQueueChanged();
+		this.#emitQueueChanged();
 	}
 
 	/** Move steering live steering took out of the queue-delivery records into {@link #liveSteered}. */
@@ -1177,6 +1201,9 @@ export class Agent {
 			for (const message of [...pending, ...delivery.additional]) suppress(message, delivery.controller);
 		}
 		this.#queuedMessageDeliveries.clear();
+		if (withdrawn.steering.length > 0 || withdrawn.followUp.length > 0) {
+			this.queuedMessageGate?.release([...withdrawn.steering, ...withdrawn.followUp]);
+		}
 		if (hadLiveSteered) this.#emitQueueChanged();
 		return withdrawn;
 	}
@@ -1336,11 +1363,9 @@ export class Agent {
 		this.#state.messages = ms.slice();
 	}
 
-	/** Signal that the steering/follow-up queue contents may have changed. Every
-	 *  queue mutator below calls this once after mutating, so external layers
-	 *  (AgentSession's `queue_update` coalescing) have a single seam to observe
-	 *  enqueue, dequeue-on-delivery, clear, and restore without emits scattered
-	 *  across every call site that queues or dequeues a message. */
+	/** Signal after a queue transition has settled its pending, claim, and
+	 *  delivery state, so AgentSession's `queue_update` coalescing observes
+	 *  a consistent snapshot across enqueue, preparation, delivery, and restore. */
 	#emitQueueChanged(): void {
 		for (const listener of this.#queueListeners) {
 			try {
@@ -1507,6 +1532,19 @@ export class Agent {
 		return claim ? [...claim.messages, ...this.#steeringQueue] : this.#steeringQueue;
 	}
 
+	#isUndeliveredQueuedMessage(message: AgentMessage): boolean {
+		for (const entry of this.#liveSteered) {
+			if (entry.message === message || entry.additional?.includes(message)) return true;
+		}
+		for (const delivery of this.#queuedMessageDeliveries) {
+			if (delivery.additional.includes(message)) return true;
+			for (let i = delivery.next; i < delivery.messages.length; i++) {
+				if (delivery.messages[i] === message) return true;
+			}
+		}
+		return false;
+	}
+
 	/** Dequeued messages not yet in the transcript, e.g. steering a provider
 	 *  took into its in-flight response via live steering. Aborting the run
 	 *  requeues them, so the session's empty-submit interrupt counts them as
@@ -1553,17 +1591,50 @@ export class Agent {
 		return queue.slice(0, count);
 	}
 
+	/**
+	 * The next delivery batch of `queue`. With a {@link queuedMessageGate}, the
+	 * gate sees each candidate batch first; what it vetoes leaves the queue and
+	 * the batch is recomputed, and candidates it claimed that the final batch no
+	 * longer holds are released again.
+	 */
+	#nextDeliveryBatch(queue: QueuedMessageQueue): AgentMessage[] {
+		const mode = queue === "steering" ? this.#steeringMode : this.#followUpMode;
+		let batch = this.#dequeueMessages(queue === "steering" ? this.#steeringQueue : this.#followUpQueue, mode);
+		const gate = this.queuedMessageGate;
+		if (!gate || batch.length === 0) return batch;
+		let claimedEarlier: AgentMessage[] | undefined;
+		let dropped = false;
+		while (batch.length > 0) {
+			const veto = gate.claim(queue, batch);
+			if (veto.length === 0) break;
+			const drop = new Set(veto);
+			const pending = queue === "steering" ? this.#steeringQueue : this.#followUpQueue;
+			const kept = pending.filter(message => !drop.has(message));
+			if (kept.length === pending.length) break;
+			for (const message of batch) if (!drop.has(message)) (claimedEarlier ??= []).push(message);
+			if (queue === "steering") this.#steeringQueue = kept;
+			else this.#followUpQueue = kept;
+			dropped = true;
+			batch = this.#dequeueMessages(kept, mode);
+		}
+		if (claimedEarlier) {
+			const final = new Set(batch);
+			const stale = claimedEarlier.filter(message => !final.has(message));
+			if (stale.length > 0) gate.release(stale);
+		}
+		if (dropped && batch.length === 0) this.#emitQueueChanged();
+		return batch;
+	}
+
 	#dequeueSteeringMessages(): AgentMessage[] {
-		const messages = this.#dequeueMessages(this.#steeringQueue, this.#steeringMode);
+		const messages = this.#nextDeliveryBatch("steering");
 		this.#steeringQueue = this.#steeringQueue.slice(messages.length);
-		if (messages.length > 0) this.#emitQueueChanged();
 		return messages;
 	}
 
 	#dequeueFollowUpMessages(): AgentMessage[] {
-		const messages = this.#dequeueMessages(this.#followUpQueue, this.#followUpMode);
+		const messages = this.#nextDeliveryBatch("followUp");
 		this.#followUpQueue = this.#followUpQueue.slice(messages.length);
-		if (messages.length > 0) this.#emitQueueChanged();
 		return messages;
 	}
 
@@ -1991,6 +2062,7 @@ export class Agent {
 			resolveFallbackTool: this.#resolveFallbackTool,
 			suggestFallbackToolNames: this.#suggestFallbackToolNames,
 			intentTracing: this.#intentTracing,
+			intentDescription: this.#intentDescription,
 			pruneToolDescriptions: this.#pruneToolDescriptions,
 			dialect: this.#dialect,
 			getDialect: this.#dialectResolver,
@@ -2024,6 +2096,7 @@ export class Agent {
 				}
 				return this.#dequeueSteeringMessagesAfterHooks(signal ?? loopSignal);
 			},
+			isUndeliveredQueuedMessage: message => this.#isUndeliveredQueuedMessage(message),
 			hasSteeringMessages: () =>
 				steeringQueueState(
 					this.#steeringQueue,

package/src/append-only-context.ts

@@ -82,6 +82,8 @@ export interface StablePrefixSnapshot {
 export interface BuildOptions {
 	/** Inject the `i` intent field into tool schemas (must match agent-loop's normalizeTools). */
 	intentTracing: boolean;
+	/** Schema description of the injected `i` field (must match agent-loop's normalizeTools). */
+	intentDescription?: string;
 	/** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
 	pruneToolDescriptions?: boolean;
 }
@@ -136,6 +138,7 @@ export class StablePrefix {
 	// but changes any of these must miss the fast path.
 	#lastToolKey: readonly string[] | undefined;
 	#lastIntentTracing: boolean | undefined;
+	#lastIntentDescription: string | undefined;
 	#lastPruneToolDescriptions: boolean | undefined;
 
 	build(context: AgentContext, options: BuildOptions): boolean {
@@ -166,6 +169,7 @@ export class StablePrefix {
 	#fastPathHit(context: AgentContext, options: BuildOptions, toolKeys: readonly string[]): boolean {
 		if (
 			this.#lastIntentTracing !== options.intentTracing ||
+			this.#lastIntentDescription !== options.intentDescription ||
 			this.#lastPruneToolDescriptions !== options.pruneToolDescriptions
 		) {
 			return false;
@@ -196,6 +200,7 @@ export class StablePrefix {
 	#recordFastPathKey(context: AgentContext, options: BuildOptions, renderedToolKeys: readonly string[]): void {
 		this.#lastPromptSegments = [...context.systemPrompt];
 		this.#lastIntentTracing = options.intentTracing;
+		this.#lastIntentDescription = options.intentDescription;
 		this.#lastPruneToolDescriptions = options.pruneToolDescriptions;
 		this.#lastToolKey = renderedToolKeys;
 	}
@@ -470,11 +475,7 @@ export class AppendOnlyContextManager {
 
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
-	const tools =
-		normalizeTools(context.tools, {
-			injectIntent: options.intentTracing,
-			pruneDescriptions: options.pruneToolDescriptions,
-		}) ?? [];
+	const tools = normalizeWireTools(context.tools, options);
 	return {
 		systemPrompt,
 		tools,
@@ -482,20 +483,50 @@ function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefi
 	};
 }
 
+function normalizeWireTools(tools: AgentContext["tools"], options: BuildOptions): Tool[] {
+	return (
+		normalizeTools(tools, {
+			injectIntent: options.intentTracing,
+			intentDescription: options.intentDescription,
+			pruneDescriptions: options.pruneToolDescriptions,
+		}) ?? []
+	);
+}
+
+/** The fields of a provider-bound tool spec the wire carries; `normalizeTools` has rendered `examples` into the description. */
+function wireToolFields(t: Tool) {
+	return {
+		n: t.name,
+		d: t.description,
+		p: t.parameters,
+		s: t.strict,
+		cf: t.customFormat,
+		cw: t.customWireName,
+	};
+}
+
+/**
+ * Fingerprint of the tool specs a request built with `options` sends: the
+ * tools half of the prefix fingerprint, for a caller that compares tool sets
+ * across requests. A same-name tool whose description, schema, examples,
+ * `strict`, `customFormat` or `customWireName` changed makes another one.
+ */
+export function wireToolsFingerprint(tools: AgentContext["tools"], options: BuildOptions): string {
+	return hashPayload(JSON.stringify(normalizeWireTools(tools, options).map(wireToolFields)));
+}
+
 function computeFingerprint(systemPrompt: string[], tools: Tool[], options: BuildOptions): string {
-	const payload = JSON.stringify({
-		s: systemPrompt,
-		t: tools.map(t => ({
-			n: t.name,
-			d: t.description,
-			p: t.parameters,
-			s: t.strict,
-			cf: t.customFormat,
-			cw: t.customWireName,
-		})),
-		i: options.intentTracing,
-		pd: options.pruneToolDescriptions,
-	});
+	return hashPayload(
+		JSON.stringify({
+			s: systemPrompt,
+			t: tools.map(wireToolFields),
+			i: options.intentTracing,
+			pd: options.pruneToolDescriptions,
+		}),
+	);
+}
+
+function hashPayload(payload: string): string {
 	let hash = 0;
 	for (let i = 0; i < payload.length; i++) {
 		hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;

package/src/compaction/branch-summarization.ts

@@ -24,16 +24,12 @@ import {
 import branchSummaryPrompt from "./prompts/branch-summary.md" with { type: "text" };
 import branchSummaryPreamble from "./prompts/branch-summary-preamble.md" with { type: "text" };
 import {
-	computeFileLists,
-	createFileOps,
 	extractFileOpsFromMessage,
-	type FileOperations,
 	incompleteOutputError,
 	SUMMARIZATION_SYSTEM_PROMPT,
 	serializeConversationForSummary,
 	stripReadSelector,
 	truncateToolResultForSummary,
-	upsertFileOperations,
 } from "./utils";
 
 // ============================================================================
@@ -54,13 +50,11 @@ export interface BranchSummaryDetails {
 	modifiedFiles: string[];
 }
 
-export type { FileOperations } from "./utils";
-
 export interface BranchPreparation {
 	/** Messages extracted for summarization, in chronological order */
 	messages: AgentMessage[];
 	/** File operations extracted from tool calls */
-	fileOps: FileOperations;
+	fileOps: snapcompact.FileOperations;
 	/** Total estimated tokens in messages */
 	totalTokens: number;
 }
@@ -252,7 +246,7 @@ export function prepareBranchEntries(
 	tokenBudget: number = 0,
 ): BranchPreparation {
 	const messages: AgentMessage[] = [];
-	const fileOps = createFileOps();
+	const fileOps = snapcompact.createFileOps();
 	let totalTokens = 0;
 
 	// First pass: collect file ops from ALL entries (even if they don't fit in token budget)
@@ -400,8 +394,8 @@ export async function generateBranchSummary(
 	summary = BRANCH_SUMMARY_PREAMBLE + summary;
 
 	// Compute file lists and append to summary
-	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
-	summary = upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
+	const { readFiles, modifiedFiles } = snapcompact.computeFileLists(fileOps);
+	summary = snapcompact.upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
 
 	return {
 		summary: summary || "No summary generated",

package/src/compaction/compaction-v2-streaming.ts

@@ -32,7 +32,7 @@ import {
 	OPENAI_HEADER_VALUES,
 	OPENAI_HEADERS,
 } from "@oh-my-pi/pi-catalog/wire/codex";
-import { $env, isUnexpectedSocketCloseMessage, logger, ptree, stringifyJson } from "@oh-my-pi/pi-utils";
+import { $env, isUnexpectedSocketCloseMessage, logger, ptree, stringifyJson, toError } from "@oh-my-pi/pi-utils";
 import { appendAzureApiVersion, resolveAzureOpenAiBaseUrl } from "./azure-openai-endpoint";
 import { prepareBedrockCompactionRequest } from "./bedrock";
 
@@ -320,7 +320,7 @@ export async function requestCompactionV2Streaming(
 				codexAccessPrograms: options?.codexAccessPrograms,
 			});
 		} catch (err) {
-			const error = err instanceof Error ? err : new Error(String(err));
+			const error = toError(err);
 			if (signal?.aborted) throw error;
 
 			if (isRetryableCompactionError(error) && attempt < V2_COMPACTION_MAX_RETRIES) {
@@ -472,7 +472,6 @@ function buildCompactionV2Headers(
 			headers[OPENAI_HEADERS.SESSION_ID] = routingSessionId;
 			headers["x-client-request-id"] = routingSessionId;
 		}
-		headers[OPENAI_HEADERS.BETA] = OPENAI_HEADER_VALUES.BETA_RESPONSES;
 		headers[OPENAI_HEADERS.ORIGINATOR] = OPENAI_HEADER_VALUES.ORIGINATOR_CODEX;
 		headers[OPENAI_HEADERS.CODEX_BETA_FEATURES] = OPENAI_HEADER_VALUES.REMOTE_COMPACTION_V2;
 		headers[OPENAI_HEADERS.ROUTING_HINT] = codexRoutingHint(request.body.model, undefined);

package/src/compaction/compaction.ts

@@ -86,16 +86,12 @@ import handoffDocumentPrompt from "./prompts/handoff-document.md" with { type: "
 import snapcompactArchiveContextPrompt from "./prompts/snapcompact-archive-context.md" with { type: "text" };
 
 import {
-	computeFileLists,
-	createFileOps,
 	escapeSummaryBoundaryTags,
 	extractFileOpsFromMessage,
-	type FileOperations,
 	incompleteOutputError,
 	SUMMARIZATION_SYSTEM_PROMPT,
 	serializeConversationForSummary,
 	stripReadSelector,
-	upsertFileOperations,
 } from "./utils";
 
 // ============================================================================
@@ -115,8 +111,8 @@ function extractFileOperations(
 	messages: AgentMessage[],
 	entries: SessionEntry[],
 	prevCompactionIndex: number,
-): FileOperations {
-	const fileOps = createFileOps();
+): snapcompact.FileOperations {
+	const fileOps = snapcompact.createFileOps();
 
 	// Collect from previous compaction's details (if pi-generated)
 	if (prevCompactionIndex >= 0) {
@@ -1384,7 +1380,7 @@ export interface CompactionPreparation {
 	/** Preserved opaque compaction payload from the previous compaction, if any. */
 	previousPreserveData?: Record<string, unknown>;
 	/** File operations extracted from messagesToSummarize */
-	fileOps: FileOperations;
+	fileOps: snapcompact.FileOperations;
 	/** Compaction settions from settings.jsonl	*/
 	settings: CompactionSettings;
 }
@@ -2343,8 +2339,8 @@ export async function compact(
 			});
 
 	// Compute file lists and append to summary
-	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
-	summary = upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
+	const { readFiles, modifiedFiles } = snapcompact.computeFileLists(fileOps);
+	summary = snapcompact.upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
 	if (nativeSummary !== undefined) {
 		// The replayed block (summary and any `tool_changes`) stays
 		// byte-identical to the API's output so it matches its signature. The
@@ -2352,7 +2348,7 @@ export async function compact(
 		// summary message with the block and skips its text, so they would
 		// otherwise be invisible to this provider. Every other provider keeps
 		// reading the entry text.
-		const filesText = upsertFileOperations("", readFiles, modifiedFiles, fileOps.read) || undefined;
+		const filesText = snapcompact.upsertFileOperations("", readFiles, modifiedFiles, fileOps.read) || undefined;
 		preserveData = withAnthropicCompactionPreserveData(preserveData, {
 			provider: model.provider,
 			content: nativeSummary,

package/src/compaction/openai.ts

@@ -965,7 +965,6 @@ export async function requestOpenAiRemoteCompaction(
 		if (attestation) {
 			headers[OPENAI_HEADERS.ATTESTATION] = attestation;
 		}
-		headers[OPENAI_HEADERS.BETA] = OPENAI_HEADER_VALUES.BETA_RESPONSES;
 		headers[OPENAI_HEADERS.ORIGINATOR] = OPENAI_HEADER_VALUES.ORIGINATOR_CODEX;
 		// This compaction request sends no `service_tier`, so the hint is model-only.
 		headers[OPENAI_HEADERS.ROUTING_HINT] = codexRoutingHint(request.model, undefined);

package/src/compaction/utils.ts

@@ -5,27 +5,27 @@
 import type { Message, ToolCall } from "@oh-my-pi/pi-ai";
 import { type Dialect, getDialectDefinition } from "@oh-my-pi/pi-ai/dialect";
 import { escapeHarmonyControlTokens } from "@oh-my-pi/pi-ai/utils/harmony-leak";
-import { formatGroupedPaths, prompt, stringifyJson } from "@oh-my-pi/pi-utils";
+import { prompt, stringifyJson } from "@oh-my-pi/pi-utils";
+import * as snapcompact from "@oh-my-pi/snapcompact";
 import type { AgentMessage } from "../types";
-import fileOperationsTemplate from "./prompts/file-operations.md" with { type: "text" };
 import summarizationSystemPrompt from "./prompts/summarization-system.md" with { type: "text" };
 
-// ============================================================================
-// File Operation Tracking
-// ============================================================================
+/** @deprecated Import these from `@oh-my-pi/snapcompact`. */
+export {
+	computeFileLists,
+	createFileOps,
+	type FileOperations,
+	isUrlSchemePath,
+	upsertFileOperations,
+} from "@oh-my-pi/snapcompact";
 
-export interface FileOperations {
-	read: Set<string>;
-	written: Set<string>;
-	edited: Set<string>;
-}
-
-export function createFileOps(): FileOperations {
-	return {
-		read: new Set(),
-		written: new Set(),
-		edited: new Set(),
-	};
+/** @deprecated Use `upsertFileOperations("", readFiles, modifiedFiles, readSet)` from `@oh-my-pi/snapcompact`. */
+export function formatFileOperations(
+	readFiles: string[],
+	modifiedFiles: string[],
+	readSet?: ReadonlySet<string>,
+): string {
+	return snapcompact.upsertFileOperations("", readFiles, modifiedFiles, readSet);
 }
 
 /** Error text for a summarization call that hit its output limit (`stopReason: "length"`): partial text is never used. */
@@ -91,27 +91,10 @@ export function isAlternateFormReadSelector(sel: string): boolean {
 	return sel.split(":").some(part => READ_ALTERNATE_FORM_RE.test(part));
 }
 
-/**
- * A real filesystem path never contains a `scheme://` URL. Tool-call paths that
- * do — `conflict://1`, `artifact://3`, `local://ctx.md`, `history://…`,
- * `issue://12`, `https://…`, and the tolerated `file.ts:conflict://1` prefix
- * form — are session-scoped or remote resources, not files the post-compaction
- * agent can re-ground on. Keep them out of the `<files>` summary.
- */
-const URL_SCHEME_RE = /[a-z][a-z0-9+.-]*:\/\//i;
-
-/**
- * Whether `path` references a `scheme://` URL (internal URI or web URL) rather
- * than a filesystem path that belongs in the compaction `<files>` summary.
- */
-export function isUrlSchemePath(path: string): boolean {
-	return URL_SCHEME_RE.test(path);
-}
-
 /**
  * Extract file operations from tool calls in an assistant message.
  */
-export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void {
+export function extractFileOpsFromMessage(message: AgentMessage, fileOps: snapcompact.FileOperations): void {
 	if (message.role !== "assistant") return;
 	if (!("content" in message) || !Array.isArray(message.content)) return;
 
@@ -128,7 +111,7 @@ export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOp
 
 		// Internal URIs (conflict://, artifact://, local://, history://, …) and
 		// web URLs are not re-groundable files — keep them out of `<files>`.
-		if (isUrlSchemePath(path)) continue;
+		if (snapcompact.isUrlSchemePath(path)) continue;
 
 		switch (block.name) {
 			case "read":
@@ -144,68 +127,6 @@ export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOp
 	}
 }
 
-/**
- * Compute final file lists from file operations.
- * Returns readFiles (files only read, not modified) and modifiedFiles.
- */
-export function computeFileLists(fileOps: FileOperations): { readFiles: string[]; modifiedFiles: string[] } {
-	// Drop any `scheme://` URLs (e.g. legacy `conflict://`/`artifact://` entries
-	// rehydrated straight into `fileOps` from a pre-fix compaction summary) — only
-	// real files belong in `<files>`. New tool-call scans are already filtered.
-	const modified = new Set([...fileOps.edited, ...fileOps.written].filter(f => !isUrlSchemePath(f)));
-	const readOnly = [...fileOps.read].filter(f => !isUrlSchemePath(f) && !modified.has(f)).sort();
-	const modifiedFiles = [...modified].sort();
-	return { readFiles: readOnly, modifiedFiles };
-}
-
-/**
- * Format file operations as one `<files>` tag: a grouped, prefix-folded
- * directory tree (find-tool shape — `# dir/` headers, bare basenames) with a
- * ` (Read)` / ` (Write)` / ` (RW)` marker per file instead of separate
- * read/modified lists. `readSet` is the cumulative read set (`fileOps.read`),
- * used to tell modified files that were also read (RW) from blind writes.
- */
-const FILE_OPERATION_SUMMARY_LIMIT = 20;
-
-function stripFileOperationTags(summary: string): string {
-	// Legacy <read-files>/<modified-files> tags are still stripped so summaries
-	// written before the combined <files> tag self-heal on the next compaction.
-	return summary
-		.replace(/<files>[\s\S]*?<\/files>\s*/g, "")
-		.replace(/<read-files>[\s\S]*?<\/read-files>\s*/g, "")
-		.replace(/<modified-files>[\s\S]*?<\/modified-files>\s*/g, "")
-		.trimEnd();
-}
-export function formatFileOperations(
-	readFiles: string[],
-	modifiedFiles: string[],
-	readSet?: ReadonlySet<string>,
-): string {
-	if (readFiles.length === 0 && modifiedFiles.length === 0) return "";
-	const mode = new Map<string, "Read" | "Write" | "RW">();
-	for (const file of readFiles) mode.set(file, "Read");
-	for (const file of modifiedFiles) mode.set(file, readSet?.has(file) ? "RW" : "Write");
-	const all = [...mode.keys()].sort();
-	let files = formatGroupedPaths(all.slice(0, FILE_OPERATION_SUMMARY_LIMIT), path => ` (${mode.get(path)})`);
-	if (all.length > FILE_OPERATION_SUMMARY_LIMIT) {
-		files += `\n[…${all.length - FILE_OPERATION_SUMMARY_LIMIT} files elided…]`;
-	}
-	return prompt.render(fileOperationsTemplate, { files });
-}
-
-export function upsertFileOperations(
-	summary: string,
-	readFiles: string[],
-	modifiedFiles: string[],
-	readSet?: ReadonlySet<string>,
-): string {
-	const baseSummary = stripFileOperationTags(summary);
-	const fileOperations = formatFileOperations(readFiles, modifiedFiles, readSet);
-	if (!fileOperations) return baseSummary;
-	if (!baseSummary) return fileOperations;
-	return `${baseSummary}\n\n${fileOperations}`;
-}
-
 // ============================================================================
 // Message Serialization
 // ============================================================================

package/src/telemetry.ts

@@ -1836,7 +1836,7 @@ export interface InstrumentedChatSpanOptions {
 export async function instrumentedCompleteSimple<TApi extends Api>(
 	model: Model<TApi>,
 	ctx: Context,
-	options: SimpleStreamOptions,
+	options: SimpleStreamOptions & { onAttempt?: (message: AssistantMessage) => void },
 	span: InstrumentedChatSpanOptions,
 ): Promise<AssistantMessage> {
 	const { telemetry, parent, oneshotKind } = span;