@oh-my-pi/pi-agent-core 17.3.4 → 17.3.5

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [17.3.5] - 2026-08-16
+
+### Added
+
+- Added automatic retry support for transient provider failures during one-shot completions, allowing callers such as compaction to opt in to resilient request handling.
+
+### Fixed
+
+- Fixed /handoff, branch summarization, and manual /compact failing outright on transient provider errors (e.g. Anthropic overloaded/429/529 responses); these operations now retry automatically instead of leaving the user's context full.
+
 ## [17.3.4] - 2026-08-14
 
 ### Fixed

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

@@ -4,7 +4,7 @@
  * Pure functions for compaction logic. The session manager handles I/O,
  * and after compaction the session is reloaded.
  */
-import { type Api, type ApiKey, type AssistantMessage, type CodexCompactionContext, type Context, type FetchImpl, type MessageAttribution, type Model, type ProviderSessionState, type SimpleStreamOptions, type Tool, type Usage } from "@oh-my-pi/pi-ai";
+import { type Api, type ApiKey, type AssistantMessage, type CodexCompactionContext, type Context, type FetchImpl, type MessageAttribution, type Model, type OneshotRetryOptions, type ProviderSessionState, type SimpleStreamOptions, type Tool, type Usage } from "@oh-my-pi/pi-ai";
 import { type AgentTelemetry } from "../telemetry.js";
 import { ThinkingLevel } from "../thinking.js";
 import type { AgentMessage } from "../types.js";
@@ -217,6 +217,20 @@ export interface SummaryOptions {
      * the live agent turn also bracket compaction HTTP requests.
      */
     completeImpl?: <TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions) => Promise<AssistantMessage>;
+    /**
+     * Transient-failure retry for the summarization oneshots (`generateSummary`,
+     * `generateShortSummary`, `generateTurnPrefixSummary`).
+     *
+     * Defaults to enabled, which is what a one-shot caller such as manual
+     * `/compact` needs: a single Anthropic `overloaded_error` / 429 / 529 should
+     * not abort compaction and leave the context full.
+     *
+     * Pass `false` when the CALLER already owns a retry loop around the whole
+     * compaction attempt — auto-compaction does — otherwise the two budgets
+     * multiply (10 outer attempts x 3 inner = 30 requests) and each outer wait
+     * stacks on top of the inner backoff.
+     */
+    oneshotRetry?: OneshotRetryOptions | false;
 }
 export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: ApiKey, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
 export interface HandoffOptions {

package/dist/types/telemetry.d.ts

@@ -22,7 +22,7 @@
  * registered, `@opentelemetry/api` returns a no-op tracer and all calls are
  * cheap pass-throughs.
  */
-import { type Api, type AssistantMessage, type Context, type Message, type Model, type ServiceTier, type SimpleStreamOptions, type StopReason, type ToolChoice, type Usage } from "@oh-my-pi/pi-ai";
+import { type Api, type AssistantMessage, type Context, type Message, type Model, type OneshotRetryOptions, type ServiceTier, type SimpleStreamOptions, type StopReason, type ToolChoice, type Usage } from "@oh-my-pi/pi-ai";
 import { type Attributes, type AttributeValue, type Span, SpanKind, SpanStatusCode, type Tracer, trace } from "@opentelemetry/api";
 import { AgentRunCollector, type AgentRunCoverage, type AgentRunSummary, type ToolStatus } from "./run-collector.js";
 import type { AgentTool } from "./types.js";
@@ -479,6 +479,23 @@ export interface InstrumentedChatSpanOptions {
      * seam while still going through the chat-span lifecycle.
      */
     readonly completeImpl?: <TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions) => Promise<AssistantMessage>;
+    /**
+     * Opt in to transient-failure retry for this oneshot (Anthropic
+     * `overloaded_error`, `rate_limit_error`, 429/500/502/503/529). Omitted or
+     * `undefined` means **no retry** — the failure is surfaced exactly as before.
+     *
+     * Deliberately opt-in rather than default-on: `oneshotKind` is free-form and
+     * callers may pass arbitrary `ctx.tools` / `options.toolChoice`, so this
+     * funnel cannot itself prove a given request is replay-safe. Re-issuing is
+     * only safe when the call performs no side effect and nothing consumed
+     * partial output — true for summaries, titles, handoffs and image
+     * descriptions, which parse a complete response after it resolves. Enable it
+     * per call site, as a reviewed decision.
+     *
+     * Pass `{}` to accept the {@link retryTransientCompletion} defaults
+     * (3 attempts, 500ms base backoff, `retry-after` honored).
+     */
+    readonly retry?: OneshotRetryOptions;
 }
 /**
  * Wrap a {@link completeSimple} round-trip with the same chat-span lifecycle

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "17.3.4",
+	"version": "17.3.5",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,16 +35,16 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.3.4",
-		"@oh-my-pi/pi-catalog": "17.3.4",
-		"@oh-my-pi/pi-natives": "17.3.4",
-		"@oh-my-pi/pi-utils": "17.3.4",
-		"@oh-my-pi/pi-wire": "17.3.4",
-		"@oh-my-pi/snapcompact": "17.3.4",
+		"@oh-my-pi/pi-ai": "17.3.5",
+		"@oh-my-pi/pi-catalog": "17.3.5",
+		"@oh-my-pi/pi-natives": "17.3.5",
+		"@oh-my-pi/pi-utils": "17.3.5",
+		"@oh-my-pi/pi-wire": "17.3.5",
+		"@oh-my-pi/snapcompact": "17.3.5",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "17.3.4",
+		"@oh-my-pi/omptype": "17.3.5",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/compaction/branch-summarization.ts

@@ -334,12 +334,18 @@ export async function generateBranchSummary(
 	];
 
 	// Call LLM for summarization
-	const response = await instrumentedCompleteSimple(
-		model,
-		{ systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT], messages: summarizationMessages },
-		{ apiKey, signal, maxTokens: 2048, metadata },
-		{ telemetry: options.telemetry, oneshotKind: "branch_summary", completeImpl: options.completeImpl },
-	);
+	let response: AssistantMessage;
+	try {
+		response = await instrumentedCompleteSimple(
+			model,
+			{ systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT], messages: summarizationMessages },
+			{ apiKey, signal, maxTokens: 2048, metadata },
+			{ telemetry: options.telemetry, oneshotKind: "branch_summary", completeImpl: options.completeImpl, retry: {} },
+		);
+	} catch (error) {
+		if (signal.aborted) return { aborted: true };
+		throw error;
+	}
 
 	// Check if aborted or errored
 	if (response.stopReason === "aborted") {

package/src/compaction/compaction.ts

@@ -16,6 +16,7 @@ import {
 	type Message,
 	type MessageAttribution,
 	type Model,
+	type OneshotRetryOptions,
 	type ProviderSessionState,
 	type SimpleStreamOptions,
 	type Tool,
@@ -470,8 +471,8 @@ function computeMessageTokens(message: AgentMessage, options?: { excludeEncrypte
 					if (!options?.excludeEncryptedReasoning) fragments.push(block.data);
 				} else if (block.type === "anthropicServerTool") {
 					// Native Anthropic server-tool call/result replayed verbatim on the
-					// wire (server_tool_use input, web_search_tool_result
-					// encrypted_content). Opaque provider-replay state the provider still
+					// wire (server_tool_use input and opaque result content). This opaque
+					// provider-replay state the provider still
 					// bills for on same-provider replay; excluded from the compaction
 					// floor like other encrypted reasoning because its local byte size
 					// diverges from provider billing.
@@ -831,6 +832,31 @@ export interface SummaryOptions {
 		ctx: Context,
 		options: SimpleStreamOptions,
 	) => Promise<AssistantMessage>;
+	/**
+	 * Transient-failure retry for the summarization oneshots (`generateSummary`,
+	 * `generateShortSummary`, `generateTurnPrefixSummary`).
+	 *
+	 * Defaults to enabled, which is what a one-shot caller such as manual
+	 * `/compact` needs: a single Anthropic `overloaded_error` / 429 / 529 should
+	 * not abort compaction and leave the context full.
+	 *
+	 * Pass `false` when the CALLER already owns a retry loop around the whole
+	 * compaction attempt — auto-compaction does — otherwise the two budgets
+	 * multiply (10 outer attempts x 3 inner = 30 requests) and each outer wait
+	 * stacks on top of the inner backoff.
+	 */
+	oneshotRetry?: OneshotRetryOptions | false;
+}
+
+/**
+ * Resolve the oneshot retry policy for a summarization call. Enabled by default
+ * so a lone transient blip cannot abort compaction; `false` opts out for callers
+ * that already retry the whole attempt (see `SummaryOptions.oneshotRetry`).
+ */
+function summaryOneshotRetry(options: SummaryOptions | undefined): OneshotRetryOptions | undefined {
+	const configured = options?.oneshotRetry;
+	if (configured === false) return undefined;
+	return configured ?? {};
 }
 
 function localCodexCompaction(options: SummaryOptions | undefined) {
@@ -935,7 +961,12 @@ export async function generateSummary(
 			providerSessionState: options?.providerSessionState,
 			codexCompaction: localCodexCompaction(options),
 		},
-		{ telemetry: options?.telemetry, oneshotKind: "compaction_summary", completeImpl: options?.completeImpl },
+		{
+			telemetry: options?.telemetry,
+			oneshotKind: "compaction_summary",
+			completeImpl: options?.completeImpl,
+			retry: summaryOneshotRetry(options),
+		},
 	);
 
 	if (response.stopReason === "error") {
@@ -1034,13 +1065,14 @@ export async function generateHandoffFromContext(
 		telemetry: options.telemetry,
 		oneshotKind: "handoff",
 		completeImpl: options.completeImpl,
+		retry: {},
 	});
 	if (response.stopReason === "error" && shouldRetryHandoffWithAutoToolChoice(response)) {
 		response = await instrumentedCompleteSimple(
 			model,
 			context,
 			{ ...requestOptions, toolChoice: "auto" },
-			{ telemetry: options.telemetry, oneshotKind: "handoff", completeImpl: options.completeImpl },
+			{ telemetry: options.telemetry, oneshotKind: "handoff", completeImpl: options.completeImpl, retry: {} },
 		);
 	}
 
@@ -1143,7 +1175,12 @@ async function generateShortSummary(
 			providerSessionState: options?.providerSessionState,
 			codexCompaction: localCodexCompaction(options),
 		},
-		{ telemetry: options?.telemetry, oneshotKind: "compaction_short_summary", completeImpl: options?.completeImpl },
+		{
+			telemetry: options?.telemetry,
+			oneshotKind: "compaction_short_summary",
+			completeImpl: options?.completeImpl,
+			retry: summaryOneshotRetry(options),
+		},
 	);
 
 	if (response.stopReason === "error") {
@@ -1719,7 +1756,12 @@ async function generateTurnPrefixSummary(
 			providerSessionState: options?.providerSessionState,
 			codexCompaction: localCodexCompaction(options),
 		},
-		{ telemetry: options?.telemetry, oneshotKind: "compaction_turn_prefix", completeImpl: options?.completeImpl },
+		{
+			telemetry: options?.telemetry,
+			oneshotKind: "compaction_turn_prefix",
+			completeImpl: options?.completeImpl,
+			retry: summaryOneshotRetry(options),
+		},
 	);
 
 	if (response.stopReason === "error") {

package/src/telemetry.ts

@@ -30,6 +30,8 @@ import {
 	completeSimple,
 	type Message,
 	type Model,
+	type OneshotRetryOptions,
+	retryTransientCompletion,
 	type ServiceTier,
 	type SimpleStreamOptions,
 	type StopReason,
@@ -1663,6 +1665,23 @@ export interface InstrumentedChatSpanOptions {
 		ctx: Context,
 		options: SimpleStreamOptions,
 	) => Promise<AssistantMessage>;
+	/**
+	 * Opt in to transient-failure retry for this oneshot (Anthropic
+	 * `overloaded_error`, `rate_limit_error`, 429/500/502/503/529). Omitted or
+	 * `undefined` means **no retry** — the failure is surfaced exactly as before.
+	 *
+	 * Deliberately opt-in rather than default-on: `oneshotKind` is free-form and
+	 * callers may pass arbitrary `ctx.tools` / `options.toolChoice`, so this
+	 * funnel cannot itself prove a given request is replay-safe. Re-issuing is
+	 * only safe when the call performs no side effect and nothing consumed
+	 * partial output — true for summaries, titles, handoffs and image
+	 * descriptions, which parse a complete response after it resolves. Enable it
+	 * per call site, as a reviewed decision.
+	 *
+	 * Pass `{}` to accept the {@link retryTransientCompletion} defaults
+	 * (3 attempts, 500ms base backoff, `retry-after` honored).
+	 */
+	readonly retry?: OneshotRetryOptions;
 }
 
 /**
@@ -1723,10 +1742,26 @@ export async function instrumentedCompleteSimple<TApi extends Api>(
 	try {
 		return await runInActiveSpan(chatSpan, async () => {
 			const complete = span.completeImpl ?? completeSimple;
-			const message = await complete(model, ctx, {
-				...options,
-				onResponse: captureOnResponse,
-			});
+			// Opt-in only (see `retry` on InstrumentedChatSpanOptions): each attempt
+			// re-issues the whole request, which is safe only for replay-safe
+			// oneshots. `getResponseHeaders` hands the failed attempt's headers to
+			// the retry layer — an AssistantMessage carries none, so this is what
+			// makes `retry-after` on a real 429/529 actually honored.
+			const runOnce = () => {
+				// Clear first so a previous attempt's `retry-after` can never be
+				// reused for a later failure that arrived without headers.
+				capturedHeaders = undefined;
+				return complete(model, ctx, { ...options, onResponse: captureOnResponse });
+			};
+			const message = span.retry
+				? await retryTransientCompletion(runOnce, {
+						...span.retry,
+						// Framework-owned: the caller must not be able to detach the
+						// abort signal or the header source by passing them itself.
+						signal: options.signal,
+						getResponseHeaders: () => capturedHeaders,
+					})
+				: await runOnce();
 			await finishChatSpan(telemetry, chatSpan, message, {
 				stepNumber,
 				serviceTier: options.serviceTier,