@linxiraos/pi-agent-core 1.0.4 → 1.0.6

package/dist/types/utils/yield.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cooperative yield utility for preventing Bun event-loop busy-wait.
+ *
+ * ## Root Cause
+ *
+ * Bun 1.3.x (JavaScriptCore) event loop busy-waits (spins in userspace)
+ * when the only pending work is an unresolved Promise — even if there are
+ * active I/O watchers (stdin, child process pipes, etc.).  The event loop
+ * continuously polls for microtask resolution instead of blocking in
+ * `epoll_wait`, consuming ~100% of a CPU core.
+ *
+ * This affects any `await` on a never-resolved Promise, including:
+ * - `Promise.withResolvers()` used for user input callbacks
+ * - `await proc.exited` for long-running child processes
+ * - Agent loop iterations waiting for the next tool call
+ *
+ * ## Fix
+ *
+ * A recurring `setInterval` keeps the event loop sleeping in `epoll_wait`.
+ * The `EventLoopKeepalive` class and `keepaliveWhile()` wrapper provide a
+ * clean way to install and clean up this keepalive timer.
+ *
+ * The older `yieldIfDue()` and `ExponentialYield` approaches (compensated
+ * sleep loops) are retained for the agent-loop hot-path where Promises
+ * resolve frequently and the keepalive alone is insufficient.
+ */
+export declare class EventLoopKeepalive {
+    #private;
+    [Symbol.dispose](): void;
+}
+/**
+ * Cooperative yield gate. Sleeps for at least {@link YieldGateOptions.sleepMs}
+ * but at most once every {@link YieldGateOptions.intervalMs}; hot-path callers
+ * invoke it freely and only the slow path actually sleeps.
+ *
+ * The clock and sleep are injectable so tests drive the gate logic without
+ * touching process-global `Date.now`/`scheduler.wait` — globals a concurrent
+ * test file can restore mid-run, which previously made the shared gate flake.
+ */
+export interface YieldGateOptions {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    intervalMs?: number;
+    sleepMs?: number;
+}
+export declare class YieldGate {
+    #private;
+    constructor(opts?: YieldGateOptions);
+    yieldIfDue(signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most once
+ * every {@link YIELD_INTERVAL_MS} across all callers.
+ */
+export declare function yieldIfDue(): Promise<void>;
+export declare class ExponentialYield {
+    #private;
+    constructor(opts?: {
+        minMs?: number;
+        maxMs?: number;
+        multiplier?: number;
+    });
+    notifyActivity(): void;
+    sleep(signal?: AbortSignal): Promise<number>;
+    /**
+     * Race `racers` against an exponentially-backed-off cooperative yield.
+     * The losing sleep is cancelled as soon as a racer settles, so no stray
+     * timers keep the event loop alive past the racer's resolution.
+     */
+    race<T>(racers: Array<Promise<T>>): Promise<T>;
+}

package/package.json

@@ -1,78 +1,79 @@
-{
-  "type": "module",
-  "name": "@linxiraos/pi-agent-core",
-  "version": "1.0.4",
-  "description": "General-purpose agent with transport abstraction, state management, and attachment support",
-  "homepage": "https://linxira-os.github.io",
-  "author": "Can Boluk",
-  "contributors": [
-    "Mario Zechner"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
-    "directory": "packages/agent"
-  },
-  "bugs": {
-    "url": "https://github.com/can1357/oh-my-pi/issues"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "llm",
-    "transport",
-    "state-management"
-  ],
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "scripts": {
-    "check": "biome check . && bun run check:types",
-    "check:types": "tsgo -p tsconfig.json --noEmit",
-    "lint": "biome lint .",
-    "test": "bun test --parallel",
-    "fix": "biome check --write --unsafe .",
-    "fmt": "biome format --write ."
-  },
-  "dependencies": {
-    "@linxiraos/pi-ai": "1.0.4",
-    "@linxiraos/pi-catalog": "1.0.4",
-    "@linxiraos/pi-natives": "1.0.2",
-    "@linxiraos/pi-utils": "1.0.4",
-    "@linxiraos/pi-wire": "1.0.2",
-    "@linxiraos/pi-snapcompact": "1.0.4",
-    "@opentelemetry/api": "^1.9.1"
-  },
-  "devDependencies": {
-    "@linxiraos/pi-omptype": "1.0.2",
-    "@opentelemetry/context-async-hooks": "^2.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@types/bun": "^1.3.14"
-  },
-  "engines": {
-    "bun": ">=1.3.14"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
-    },
-    "./compaction": {
-      "types": "./src/compaction.ts",
-      "import": "./src/compaction.ts"
-    },
-    "./compaction/*": {
-      "types": "./src/compaction/*.ts",
-      "import": "./src/compaction/*.ts"
-    },
-    "./*": {
-      "types": "./src/*.ts",
-      "import": "./src/*.ts"
-    }
-  }
-}
+{
+	"type": "module",
+	"name": "@linxiraos/pi-agent-core",
+	"version": "1.0.6",
+	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
+	"homepage": "https://linxira-os.github.io",
+	"author": "Can Boluk",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+		"directory": "packages/agent"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/issues"
+	},
+	"keywords": [
+		"ai",
+		"agent",
+		"llm",
+		"transport",
+		"state-management"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@linxiraos/pi-ai": "1.0.6",
+		"@linxiraos/pi-catalog": "1.0.6",
+		"@linxiraos/pi-natives": "1.0.2",
+		"@linxiraos/pi-utils": "1.0.6",
+		"@linxiraos/pi-wire": "1.0.2",
+		"@opentelemetry/api": "^1.9.1",
+		"@linxiraos/pi-snapcompact": "1.0.6"
+	},
+	"devDependencies": {
+		"@linxiraos/pi-omptype": "1.0.2",
+		"@opentelemetry/context-async-hooks": "^2.9.0",
+		"@opentelemetry/sdk-trace-base": "^2.9.0",
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./compaction": {
+			"types": "./dist/types/compaction.d.ts",
+			"import": "./src/compaction.ts"
+		},
+		"./compaction/*": {
+			"types": "./dist/types/compaction/*.d.ts",
+			"import": "./src/compaction/*.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		}
+	}
+}

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-v2-streaming.ts

@@ -423,6 +423,7 @@ function buildCompactionV2Headers(
 		}
 		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;
 		if (model.useResponsesLite) {
 			headers[OPENAI_HEADERS.RESPONSES_LITE] = "true";
 		}

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,