@oh-my-pi/pi-agent-core 17.2.3 → 17.2.5

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [17.2.5] - 2026-08-03
+
+### Breaking Changes
+
+- Tool examples embedded in tool descriptions now always render in Python call syntax, and the `exampleDialect` option has been removed from `AppendOnlyContextManager` build options.
+- Updated `normalizeTools` to accept a `NormalizeToolsOptions` configuration object (`{ injectIntent, pruneDescriptions }`) instead of positional booleans.
+
+### Fixed
+
+- Fixed an issue where runs would fail with an error if an Anthropic stream was truncated after complete tool calls were streamed; the agent now recovers and executes those tool calls.
+- Fixed an issue where artifact recovery reads could be incorrectly elided during compaction.
+
+## [17.2.4] - 2026-08-01
+
+### Fixed
+
+- Fixed Codex V2 remote compaction bypassing the provider's live WebSocket transport before trying SSE ([#7198](https://github.com/can1357/oh-my-pi/issues/7198)).
+- Tool calls skipped mid-batch to service queued steering/peer input now distinguish calls that never entered `tool.execute` (`SyntheticToolResultDetails`, `executed: false`) from in-flight calls that may have performed partial work (`execution: "started"`), allowing UI/telemetry consumers to render normal steering control flow without misreporting execution state ([#7199](https://github.com/can1357/oh-my-pi/issues/7199)).
+
 ## [17.2.2] - 2026-07-31
 
 ### Fixed

package/dist/types/agent-loop.d.ts

@@ -80,7 +80,13 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
     readonly detailed: () => Promise<AgentLoopDetailedResult>;
 };
 export declare function normalizeMessagesForProvider(messages: Context["messages"], model: AgentLoopConfig["model"]): Context["messages"];
-export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean, exampleDialect?: Dialect, pruneDescriptions?: boolean): Context["tools"];
+export interface NormalizeToolsOptions {
+    /** Inject the `i` intent field into tool schemas (subject to `PI_NO_INTENT`). */
+    injectIntent: boolean;
+    /** Strip descriptions from the wire specs when the catalog rides in the system prompt. */
+    pruneDescriptions?: boolean;
+}
+export declare function normalizeTools(tools: AgentContext["tools"], options: NormalizeToolsOptions): Context["tools"];
 /** Resolve the human-readable reason an abort carried. A caller that aborts via
  *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
  *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the
@@ -101,13 +107,15 @@ export declare function abortReasonText(signal: AbortSignal | undefined): string
  * (#4321): a provider-side stream error after tool-call emission (e.g. Codex
  * websocket close) was surfaced by the CLI as if the local tool had failed.
  *
- * `source` names the assistant-side termination state that prevented
- * execution; `upstreamError` is the provider-reported message when the turn
- * ended with `stopReason === "error"`.
+ * `source` names the state that prevented execution — either an assistant-side
+ * turn termination (`assistant_stop_*`) or a mid-batch interrupt that skipped a
+ * still-pending call to service queued steering/peer input (`interrupt_skipped`).
+ * `upstreamError` is the provider-reported message when the turn ended with
+ * `stopReason === "error"`.
  */
 export interface SyntheticToolResultDetails {
     __synthetic: true;
-    source: "assistant_stop_aborted" | "assistant_stop_error" | "assistant_stop_skipped" | "assistant_stop_length";
+    source: "assistant_stop_aborted" | "assistant_stop_error" | "assistant_stop_skipped" | "assistant_stop_length" | "interrupt_skipped";
     executed: false;
     upstreamError?: string;
 }

package/dist/types/append-only-context.d.ts

@@ -14,7 +14,6 @@
  *    message delta is a cache miss each turn.
  */
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
-import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { AgentContext } from "./types.js";
 /** Frozen system prompt + tool spec snapshot. */
 export interface StablePrefixSnapshot {
@@ -26,7 +25,6 @@ export interface StablePrefixSnapshot {
 export interface BuildOptions {
     /** Inject the `i` intent field into tool schemas (must match agent-loop's normalizeTools). */
     intentTracing: boolean;
-    exampleDialect?: Dialect;
     /** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
     pruneToolDescriptions?: boolean;
 }

package/dist/types/compaction/compaction-v2-streaming.d.ts

@@ -68,6 +68,7 @@ export declare function requestCompactionV2Streaming(model: Model, apiKey: strin
     retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
     providerSessionState?: Map<string, ProviderSessionState>;
     codexCompaction?: CodexCompactionContext;
+    preferWebsockets?: boolean;
 }): Promise<CompactionV2Response>;
 /** Build Codex-style V2 replacement history from prompt input plus compaction output. */
 export declare function buildCompactionV2ReplacementHistory(input: unknown[], compactionItem: Record<string, unknown>, retainedMessageBudget?: number): {

package/dist/types/compaction/compaction.d.ts

@@ -200,6 +200,8 @@ export interface SummaryOptions {
     promptCacheKey?: string;
     /** Mutable provider state used to keep Codex compaction on the live session identity. */
     providerSessionState?: Map<string, ProviderSessionState>;
+    /** Whether Codex remote compaction should prefer the provider WebSocket transport. */
+    preferWebsockets?: boolean;
     /** Classification shared by every provider request in this logical compaction. */
     codexCompaction?: CodexCompactionContext;
     /** Provider-visible tools for remote compaction transports that replay native tool history. */

package/dist/types/compaction/shake.d.ts

@@ -31,8 +31,13 @@ export interface ShakeConfig {
 }
 /** Auto-shake config: protects the live tail, conservative thresholds. */
 export declare const DEFAULT_SHAKE_CONFIG: ShakeConfig;
-/** Manual `/shake`: aggressive — drops every eligible region across history. */
+/**
+ * Manual `/shake`: aggressive — drops every eligible region across history,
+ * artifact recovery reads included (the user's full escape hatch).
+ */
 export declare const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig;
+/** Compaction dead-end rescue: aggressive reach, but artifact recovery reads stay protected. */
+export declare const RESCUE_SHAKE_CONFIG: ShakeConfig;
 /** A located eligible region. */
 export interface ToolResultShakeRegion {
     kind: "toolResult";

package/dist/types/compaction/tool-protection.d.ts

@@ -14,4 +14,6 @@ export declare function collectToolCallsById(entries: readonly SessionEntry[]):
  */
 export declare function getReadToolPath({ toolResult, toolCall }: ProtectedToolContext): string | undefined;
 export declare function isSkillReadToolResult(context: ProtectedToolContext): boolean;
+/** Recovery reads of session artifacts — eliding one only mints another artifact and can repeat indefinitely. */
+export declare function isArtifactRecoveryToolResult(context: ProtectedToolContext): boolean;
 export declare function isProtectedToolResult(toolResult: ToolResultMessage, toolCall: AgentToolCall | undefined, matchers: readonly ProtectedToolMatcher[]): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "17.2.3",
+	"version": "17.2.5",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,12 +35,12 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.2.3",
-		"@oh-my-pi/pi-catalog": "17.2.3",
-		"@oh-my-pi/pi-natives": "17.2.3",
-		"@oh-my-pi/pi-utils": "17.2.3",
-		"@oh-my-pi/pi-wire": "17.2.3",
-		"@oh-my-pi/snapcompact": "17.2.3",
+		"@oh-my-pi/pi-ai": "17.2.5",
+		"@oh-my-pi/pi-catalog": "17.2.5",
+		"@oh-my-pi/pi-natives": "17.2.5",
+		"@oh-my-pi/pi-utils": "17.2.5",
+		"@oh-my-pi/pi-wire": "17.2.5",
+		"@oh-my-pi/snapcompact": "17.2.5",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -42,7 +42,6 @@ import {
 	recoverHarmonyToolCall,
 	signalListLabel,
 } from "@oh-my-pi/pi-ai/utils/harmony-leak";
-import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { logger, sanitizeText, structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
 import { agentPauseGate } from "./pause";
@@ -829,13 +828,16 @@ function injectIntentIntoSchema(
 	};
 }
 
-export function normalizeTools(
-	tools: AgentContext["tools"],
-	injectIntent: boolean,
-	exampleDialect?: Dialect,
-	pruneDescriptions = false,
-): Context["tools"] {
-	injectIntent = injectIntent && Bun.env.PI_NO_INTENT !== "1";
+export interface NormalizeToolsOptions {
+	/** Inject the `i` intent field into tool schemas (subject to `PI_NO_INTENT`). */
+	injectIntent: boolean;
+	/** Strip descriptions from the wire specs when the catalog rides in the system prompt. */
+	pruneDescriptions?: boolean;
+}
+
+export function normalizeTools(tools: AgentContext["tools"], options: NormalizeToolsOptions): Context["tools"] {
+	const pruneDescriptions = options.pruneDescriptions === true;
+	const injectIntent = options.injectIntent && Bun.env.PI_NO_INTENT !== "1";
 	return tools?.map(t => {
 		const intentMode = resolveIntentMode(t.intent);
 		const doInjectIntent = injectIntent && intentMode !== "omit";
@@ -853,9 +855,7 @@ export function normalizeTools(
 		let parameters = toolWireSchema(t) as TSchema;
 		if (doInjectIntent) parameters = injectIntentIntoSchema(parameters, intentMode) as TSchema;
 		const description = t.description ?? "";
-		const examplesBlock = exampleDialect
-			? renderToolExamples({ ...t, parameters }, exampleDialect, doInjectIntent ? INTENT_FIELD : undefined)
-			: "";
+		const examplesBlock = renderToolExamples({ ...t, parameters }, doInjectIntent ? INTENT_FIELD : undefined);
 		const finalDescription = examplesBlock ? `${description}\n\n${examplesBlock}` : description;
 		return { ...t, parameters, description: finalDescription };
 	});
@@ -1498,21 +1498,22 @@ async function prepareProviderCall(
 	const llmMessages = await config.convertToLlm(messages);
 	const normalizedMessages = normalizeMessagesForProvider(llmMessages, model);
 	const ownedDialect: Dialect | undefined = config.dialect ?? resolveOwnedDialectFromEnv(Bun.env.PI_DIALECT);
-	const exampleDialect = ownedDialect ?? preferredDialect(model.id);
 	const pruneToolDescriptions = !!config.pruneToolDescriptions && !ownedDialect;
 	let llmContext: Context;
 	if (config.appendOnlyContext) {
 		config.appendOnlyContext.syncMessages(normalizedMessages);
 		llmContext = config.appendOnlyContext.build(context, {
 			intentTracing: !!config.intentTracing,
-			exampleDialect,
 			pruneToolDescriptions,
 		});
 	} else {
 		llmContext = {
 			systemPrompt: context.systemPrompt,
 			messages: normalizedMessages,
-			tools: normalizeTools(context.tools, !!config.intentTracing, exampleDialect, pruneToolDescriptions),
+			tools: normalizeTools(context.tools, {
+				injectIntent: !!config.intentTracing,
+				pruneDescriptions: pruneToolDescriptions,
+			}),
 		};
 	}
 	if (config.transformProviderContext) {
@@ -1928,8 +1929,10 @@ function recoverTransientErrorToolTurn(
 		if (tool.customWireName !== undefined) availableToolNames.add(tool.customWireName);
 	}
 	if (!toolCalls.every(toolCall => availableToolNames.has(toolCall.name))) return message;
+	const errorText = `${message.errorMessage ?? ""}\n${message.stopDetails?.explanation ?? ""}`;
 	if (
-		!AIError.isStreamReadErrorText(`${message.errorMessage ?? ""}\n${message.stopDetails?.explanation ?? ""}`) &&
+		!AIError.isStreamReadErrorText(errorText) &&
+		!AIError.isStreamEnvelopeErrorText(errorText) &&
 		!AIError.isTransientStreamParseError(message.errorMessage) &&
 		!AIError.isTransientStreamParseError(message.stopDetails?.explanation)
 	)
@@ -2454,6 +2457,7 @@ async function executeToolCalls(
 		let isError = false;
 		let caughtError: unknown;
 		let completedToolExecution = false;
+		let executionStarted = false;
 
 		await runInActiveSpan(toolSpan, async () => {
 			try {
@@ -2487,6 +2491,7 @@ async function executeToolCalls(
 							providerMetadata: toolCall.providerMetadata,
 						})
 					: undefined;
+				executionStarted = true;
 				const rawResult = await tool.execute(
 					toolCall.id,
 					executionArgs,
@@ -2557,12 +2562,12 @@ async function executeToolCalls(
 		const interrupted = interruptState.triggered;
 		const perToolAborted = record.signal.aborted;
 		const abortedDuringExecution = perToolAborted && isError && !completedToolExecution;
-		if (interrupted && perToolAborted && isError && !completedToolExecution) {
-			// This tool's own signal fired AND it failed to produce a result: `tool.execute()`
-			// never returned (it threw on the abort), so it was genuinely cut off before
-			// producing usable output. Report it as skipped.
+		if (interrupted && abortedDuringExecution) {
+			// This tool's own signal fired AND it failed to produce a result. The
+			// execution may already have performed partial work before throwing on
+			// abort, so preserve that distinction in the placeholder metadata.
 			record.skipped = true;
-			emitToolResult(record, createSkippedToolResult(interruptState.source), true);
+			emitToolResult(record, createSkippedToolResult(interruptState.source, executionStarted), true);
 		} else {
 			// No interrupt on this signal, or the tool finished before the interrupt landed
 			// (`completedToolExecution`) — even if the signal aborted around completion. Keep
@@ -2703,7 +2708,7 @@ async function executeToolCalls(
 				toolName: record.toolCall.name,
 				status: "skipped",
 			});
-			emitToolResult(record, createSkippedToolResult(interruptState.source), true);
+			emitToolResult(record, createSkippedToolResult(interruptState.source, false), true);
 		}
 	}
 
@@ -2723,17 +2728,34 @@ async function executeToolCalls(
  * (#4321): a provider-side stream error after tool-call emission (e.g. Codex
  * websocket close) was surfaced by the CLI as if the local tool had failed.
  *
- * `source` names the assistant-side termination state that prevented
- * execution; `upstreamError` is the provider-reported message when the turn
- * ended with `stopReason === "error"`.
+ * `source` names the state that prevented execution — either an assistant-side
+ * turn termination (`assistant_stop_*`) or a mid-batch interrupt that skipped a
+ * still-pending call to service queued steering/peer input (`interrupt_skipped`).
+ * `upstreamError` is the provider-reported message when the turn ended with
+ * `stopReason === "error"`.
  */
 export interface SyntheticToolResultDetails {
 	__synthetic: true;
-	source: "assistant_stop_aborted" | "assistant_stop_error" | "assistant_stop_skipped" | "assistant_stop_length";
+	source:
+		| "assistant_stop_aborted"
+		| "assistant_stop_error"
+		| "assistant_stop_skipped"
+		| "assistant_stop_length"
+		| "interrupt_skipped";
 	executed: false;
 	upstreamError?: string;
 }
 
+/**
+ * Metadata for an interrupt-aborted call that entered `tool.execute()` but
+ * threw before returning a usable result. It may have performed partial work.
+ */
+interface InterruptedToolResultDetails {
+	__interrupted: true;
+	source: "interrupt_skipped";
+	execution: "started";
+}
+
 /**
  * Narrow an {@link AgentMessage} to a synthetic {@link ToolResultMessage} —
  * a tool_result emitted for a tool call the assistant never invoked (see
@@ -2844,7 +2866,10 @@ function createToolSignalAbortedResult(signal: AbortSignal): AgentToolResult<unk
 	};
 }
 
-function createSkippedToolResult(source: SteeringInterruptSource | "irc" | undefined): AgentToolResult<any> {
+function createSkippedToolResult(
+	source: SteeringInterruptSource | "irc" | undefined,
+	executionStarted: boolean,
+): AgentToolResult<SyntheticToolResultDetails | InterruptedToolResultDetails> {
 	let reason = "pending steering message";
 	let blocker = "queued message";
 	if (source === "user") {
@@ -2864,6 +2889,8 @@ function createSkippedToolResult(source: SteeringInterruptSource | "irc" | undef
 				text: `Skipped due to ${reason}. Do not count this skipped result as completed work or verification. After the ${blocker} is handled on the next step, retry the skipped tool if it is still needed.`,
 			},
 		],
-		details: {},
+		details: executionStarted
+			? { __interrupted: true, source: "interrupt_skipped", execution: "started" }
+			: { __synthetic: true, source: "interrupt_skipped", executed: false },
 	};
 }

package/src/agent.ts

@@ -24,7 +24,6 @@ import {
 } from "@oh-my-pi/pi-ai";
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
-import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { getBundledModel } from "@oh-my-pi/pi-catalog/models";
 import { logger } from "@oh-my-pi/pi-utils";
 import {
@@ -771,12 +770,10 @@ export class Agent {
 		const messages = normalizeMessagesForProvider(llmMessages, model);
 		const tools = ownedDialect
 			? []
-			: (normalizeTools(
-					this.#toolsForModel(model),
-					this.#intentTracing,
-					preferredDialect(model.id),
-					this.#pruneToolDescriptions,
-				) ?? []);
+			: (normalizeTools(this.#toolsForModel(model), {
+					injectIntent: this.#intentTracing,
+					pruneDescriptions: this.#pruneToolDescriptions,
+				}) ?? []);
 		let context: Context = { systemPrompt, messages, tools };
 		if (this.#transformProviderContext) context = await this.#transformProviderContext(context, model);
 		return context;

package/src/append-only-context.ts

@@ -15,7 +15,6 @@
  */
 
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
-import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import { normalizeTools } from "./agent-loop";
 import type { AgentContext } from "./types";
 
@@ -34,7 +33,6 @@ export interface StablePrefixSnapshot {
 export interface BuildOptions {
 	/** Inject the `i` intent field into tool schemas (must match agent-loop's normalizeTools). */
 	intentTracing: boolean;
-	exampleDialect?: Dialect;
 	/** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
 	pruneToolDescriptions?: boolean;
 }
@@ -317,7 +315,10 @@ export class AppendOnlyContextManager {
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
 	const tools =
-		normalizeTools(context.tools, options.intentTracing, options.exampleDialect, options.pruneToolDescriptions) ?? [];
+		normalizeTools(context.tools, {
+			injectIntent: options.intentTracing,
+			pruneDescriptions: options.pruneToolDescriptions,
+		}) ?? [];
 	return {
 		systemPrompt,
 		tools,
@@ -337,7 +338,6 @@ function computeFingerprint(systemPrompt: string[], tools: Tool[], options: Buil
 			cw: t.customWireName,
 		})),
 		i: options.intentTracing,
-		ex: options.exampleDialect,
 		pd: options.pruneToolDescriptions,
 	});
 	let hash = 0;

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

@@ -13,7 +13,9 @@ import { applyCodexResponsesLiteShape } from "@oh-my-pi/pi-ai/providers/openai-c
 import {
 	createOpenAICodexCompactionRequestContext,
 	createOpenAICodexCompatibilityMetadata,
+	type OpenAICodexCompactionBody,
 	type OpenAICodexCompatibilityMetadata,
+	openCodexCompactionEventStream,
 } from "@oh-my-pi/pi-ai/providers/openai-codex-responses";
 import {
 	getOpenAIPromptCacheKey,
@@ -128,6 +130,14 @@ function isOpenAiV2CompatibleModel(model: Model): boolean {
 	return api === "openai-responses" || api === "azure-openai-responses" || api === "openai-codex-responses";
 }
 
+function shouldUseCodexProviderTransport(model: Model): model is Model<"openai-codex-responses"> {
+	return (
+		model.api === "openai-codex-responses" &&
+		model.remoteCompaction?.v2Endpoint === undefined &&
+		model.remoteCompaction?.streamingEndpoint === undefined
+	);
+}
+
 function resolveOpenAiResponsesEndpoint(baseUrl: string | undefined): string {
 	const rawBase = baseUrl && baseUrl.length > 0 ? baseUrl : "https://api.openai.com/v1";
 	const normalizedBase = rawBase.replace(/\/+$/, "");
@@ -228,6 +238,7 @@ export async function requestCompactionV2Streaming(
 		retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
 		providerSessionState?: Map<string, ProviderSessionState>;
 		codexCompaction?: CodexCompactionContext;
+		preferWebsockets?: boolean;
 	},
 ): Promise<CompactionV2Response> {
 	const endpoint = getCompactionV2Endpoint(model);
@@ -238,31 +249,29 @@ export async function requestCompactionV2Streaming(
 	const fetchImpl = options?.fetch ?? globalThis.fetch;
 	const retryWait = options?.retryWait ?? ((delayMs: number) => Bun.sleep(delayMs));
 	const isCodexResponses = compactionV2Api(model) === "openai-codex-responses" || model.provider === "openai-codex";
-	const codexMetadata = isCodexResponses
-		? createOpenAICodexCompatibilityMetadata({
-				sessionId: request.sessionId,
-				providerSessionState: options?.providerSessionState,
-				requestKind: "compaction",
-				compaction: createOpenAICodexCompactionRequestContext({
-					context: options?.codexCompaction,
-					implementation: "responses_compaction_v2",
-				}),
-			})
-		: undefined;
+	const codexMetadata =
+		isCodexResponses && !shouldUseCodexProviderTransport(model)
+			? createOpenAICodexCompatibilityMetadata({
+					sessionId: request.sessionId,
+					providerSessionState: options?.providerSessionState,
+					requestKind: "compaction",
+					compaction: createOpenAICodexCompactionRequestContext({
+						context: options?.codexCompaction,
+						implementation: "responses_compaction_v2",
+					}),
+				})
+			: undefined;
 	let lastError: Error | undefined;
 
 	for (let attempt = 0; attempt <= V2_COMPACTION_MAX_RETRIES; attempt++) {
 		const timeoutSignal = withRequestTimeout(signal, options?.timeoutMs ?? V2_COMPACTION_TIMEOUT_MS);
 		try {
-			return await attemptCompactionV2Streaming(
-				endpoint,
-				apiKey,
-				model,
-				request,
-				fetchImpl,
-				timeoutSignal,
+			return await attemptCompactionV2Streaming(endpoint, apiKey, model, request, fetchImpl, timeoutSignal, {
 				codexMetadata,
-			);
+				providerSessionState: options?.providerSessionState,
+				codexCompaction: options?.codexCompaction,
+				preferWebsockets: options?.preferWebsockets,
+			});
 		} catch (err) {
 			const error = err instanceof Error ? err : new Error(String(err));
 			if (signal?.aborted) throw error;
@@ -292,15 +301,20 @@ async function attemptCompactionV2Streaming(
 	model: Model,
 	request: CompactionV2Request,
 	fetchImpl: FetchImpl,
-	signal?: AbortSignal,
-	codexMetadata?: OpenAICodexCompatibilityMetadata,
+	signal: AbortSignal | undefined,
+	options: {
+		codexMetadata?: OpenAICodexCompatibilityMetadata;
+		providerSessionState?: Map<string, ProviderSessionState>;
+		codexCompaction?: CodexCompactionContext;
+		preferWebsockets?: boolean;
+	},
 ): Promise<CompactionV2Response> {
 	// Faithful to Codex: append the compaction trigger as the final input item
 	// of an otherwise-normal Responses request, then stream the result. `store`
 	// stays false — compaction must never persist a server-side response object.
 	const cacheOptions = { sessionId: request.sessionId, promptCacheKey: request.promptCacheKey };
 	const promptCacheKey = getOpenAIPromptCacheKey(cacheOptions);
-	const body: Record<string, unknown> = {
+	const body: OpenAICodexCompactionBody = {
 		model: request.model,
 		input: [...request.input, COMPACTION_TRIGGER_ITEM],
 		instructions: request.instructions,
@@ -318,8 +332,8 @@ async function attemptCompactionV2Streaming(
 		...(promptCacheKey ? { prompt_cache_key: promptCacheKey } : {}),
 		...(request.tools && request.tools.length > 0 ? { tools: request.tools, tool_choice: "auto" } : {}),
 	};
-	if (codexMetadata) {
-		body.client_metadata = codexMetadata.clientMetadata;
+	if (options.codexMetadata) {
+		body.client_metadata = options.codexMetadata.clientMetadata;
 	}
 	// Responses Lite models take the same rewrite on the compaction stream:
 	// instructions/tools ride as input items (codex-rs `compact_remote_v2`
@@ -327,9 +341,27 @@ async function attemptCompactionV2Streaming(
 	if (model.useResponsesLite) {
 		applyCodexResponsesLiteShape(body);
 	}
+
+	if (shouldUseCodexProviderTransport(model)) {
+		const eventStream = await openCodexCompactionEventStream(model, body, {
+			apiKey,
+			signal,
+			fetch: fetchImpl,
+			sessionId: request.sessionId,
+			providerSessionState: options.providerSessionState,
+			preferWebsockets: options.preferWebsockets,
+			responsesLite: model.useResponsesLite,
+			codexCompaction: createOpenAICodexCompactionRequestContext({
+				context: options.codexCompaction,
+				implementation: "responses_compaction_v2",
+			}),
+		});
+		return collectCompactionV2Events(eventStream, request);
+	}
+
 	const response = await fetchImpl(endpoint, {
 		method: "POST",
-		headers: buildCompactionV2Headers(model, apiKey, request, codexMetadata),
+		headers: buildCompactionV2Headers(model, apiKey, request, options.codexMetadata),
 		body: stringifyJson(body),
 		signal,
 	});
@@ -400,6 +432,33 @@ function buildCompactionV2Headers(
 	return headers;
 }
 
+interface CompactionV2CollectionState {
+	outputItemCount: number;
+	compactionItems: Array<Record<string, unknown>>;
+	sawCompleted: boolean;
+	usage: CompactionV2Usage | undefined;
+}
+
+function createCompactionV2CollectionState(): CompactionV2CollectionState {
+	return {
+		outputItemCount: 0,
+		compactionItems: [],
+		sawCompleted: false,
+		usage: undefined,
+	};
+}
+
+async function collectCompactionV2Events(
+	events: AsyncIterable<Record<string, unknown>>,
+	request: CompactionV2Request,
+): Promise<CompactionV2Response> {
+	const state = createCompactionV2CollectionState();
+	for await (const event of events) {
+		handleCompactionV2Event(event, undefined, state);
+	}
+	return finishCompactionV2Collection(state, request);
+}
+
 async function collectCompactionV2Output(
 	response: Response,
 	request: CompactionV2Request,
@@ -409,13 +468,7 @@ async function collectCompactionV2Output(
 		throw new Error("No response body for V2 compaction streaming");
 	}
 
-	const state = {
-		outputItemCount: 0,
-		compactionItems: [] as Array<Record<string, unknown>>,
-		sawCompleted: false,
-		usage: undefined as CompactionV2Usage | undefined,
-	};
-
+	const state = createCompactionV2CollectionState();
 	try {
 		const decoder = new TextDecoder();
 		let buffer = "";
@@ -462,6 +515,13 @@ async function collectCompactionV2Output(
 		reader.releaseLock();
 	}
 
+	return finishCompactionV2Collection(state, request);
+}
+
+function finishCompactionV2Collection(
+	state: CompactionV2CollectionState,
+	request: CompactionV2Request,
+): CompactionV2Response {
 	if (!state.sawCompleted) {
 		throw new Error("V2 compaction stream closed before response.completed");
 	}
@@ -477,7 +537,6 @@ async function collectCompactionV2Output(
 		compactionItem,
 		request.retainedMessageBudget,
 	);
-
 	return {
 		compactionItem,
 		replacementHistory,
@@ -490,12 +549,7 @@ async function collectCompactionV2Output(
 function handleCompactionV2SseEvent(
 	data: string,
 	eventName: string | undefined,
-	state: {
-		outputItemCount: number;
-		compactionItems: Array<Record<string, unknown>>;
-		sawCompleted: boolean;
-		usage: CompactionV2Usage | undefined;
-	},
+	state: CompactionV2CollectionState,
 ): void {
 	if (data === "[DONE]") return;
 	let event: Record<string, unknown>;
@@ -504,7 +558,14 @@ function handleCompactionV2SseEvent(
 	} catch (err) {
 		throw new Error(`V2 compaction stream parse failed: ${err instanceof Error ? err.message : String(err)}`);
 	}
+	handleCompactionV2Event(event, eventName, state);
+}
 
+function handleCompactionV2Event(
+	event: Record<string, unknown>,
+	eventName: string | undefined,
+	state: CompactionV2CollectionState,
+): void {
 	const type = typeof event.type === "string" ? event.type : eventName;
 	if (type === "response.output_item.done") {
 		state.outputItemCount++;

package/src/compaction/compaction.ts

@@ -809,6 +809,8 @@ export interface SummaryOptions {
 	promptCacheKey?: string;
 	/** Mutable provider state used to keep Codex compaction on the live session identity. */
 	providerSessionState?: Map<string, ProviderSessionState>;
+	/** Whether Codex remote compaction should prefer the provider WebSocket transport. */
+	preferWebsockets?: boolean;
 	/** Classification shared by every provider request in this logical compaction. */
 	codexCompaction?: CodexCompactionContext;
 	/** Provider-visible tools for remote compaction transports that replay native tool history. */
@@ -1432,6 +1434,7 @@ export async function compact(
 		sessionId: options?.sessionId,
 		promptCacheKey: options?.promptCacheKey,
 		providerSessionState: options?.providerSessionState,
+		preferWebsockets: options?.preferWebsockets,
 		codexCompaction: options?.codexCompaction,
 		tools: options?.tools,
 		fetch: options?.fetch,
@@ -1509,6 +1512,7 @@ export async function compact(
 						requestCompactionV2Streaming(model, key, request, signal, {
 							fetch: summaryOptions.fetch,
 							providerSessionState: summaryOptions.providerSessionState,
+							preferWebsockets: summaryOptions.preferWebsockets,
 							codexCompaction: summaryOptions.codexCompaction,
 						}),
 					{ signal },

package/src/compaction/shake.ts

@@ -18,6 +18,7 @@ import type { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./en
 import { invalidateMessageCache } from "./message-cache";
 import {
 	collectToolCallsById,
+	isArtifactRecoveryToolResult,
 	isProtectedToolResult,
 	isSkillReadToolResult,
 	type ProtectedToolMatcher,
@@ -46,11 +47,14 @@ export interface ShakeConfig {
 export const DEFAULT_SHAKE_CONFIG: ShakeConfig = {
 	protectTokens: 16_000,
 	minSavings: 4_000,
-	protectedTools: ["skill", isSkillReadToolResult],
+	protectedTools: ["skill", isSkillReadToolResult, isArtifactRecoveryToolResult],
 	fenceMinTokens: 400,
 };
 
-/** Manual `/shake`: aggressive — drops every eligible region across history. */
+/**
+ * Manual `/shake`: aggressive — drops every eligible region across history,
+ * artifact recovery reads included (the user's full escape hatch).
+ */
 export const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig = {
 	protectTokens: 0,
 	minSavings: 0,
@@ -58,6 +62,12 @@ export const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig = {
 	fenceMinTokens: 400,
 };
 
+/** Compaction dead-end rescue: aggressive reach, but artifact recovery reads stay protected. */
+export const RESCUE_SHAKE_CONFIG: ShakeConfig = {
+	...AGGRESSIVE_SHAKE_CONFIG,
+	protectedTools: [...AGGRESSIVE_SHAKE_CONFIG.protectedTools, isArtifactRecoveryToolResult],
+};
+
 /** Rough token cost of a placeholder line; used only for the savings gate. */
 const PLACEHOLDER_TOKEN_ESTIMATE = 16;
 

package/src/compaction/tool-protection.ts

@@ -39,6 +39,16 @@ export function isSkillReadToolResult(context: ProtectedToolContext): boolean {
 	return getReadToolPath(context)?.startsWith(SKILL_INTERNAL_URL_PREFIX) ?? false;
 }
 
+const ARTIFACT_INTERNAL_URL_PREFIX = "artifact://";
+
+/** Recovery reads of session artifacts — eliding one only mints another artifact and can repeat indefinitely. */
+export function isArtifactRecoveryToolResult(context: ProtectedToolContext): boolean {
+	if (getReadToolPath(context)?.startsWith(ARTIFACT_INTERNAL_URL_PREFIX)) return true;
+	const meta = (context.toolResult.details as { meta?: { source?: { type?: string; value?: string } } } | undefined)
+		?.meta;
+	return meta?.source?.type === "internal" && (meta.source.value?.startsWith(ARTIFACT_INTERNAL_URL_PREFIX) ?? false);
+}
+
 export function isProtectedToolResult(
 	toolResult: ToolResultMessage,
 	toolCall: AgentToolCall | undefined,