@linxiraos/pi-agent-core 1.1.15 → 1.1.16

package/src/append-only-context.ts

@@ -14,7 +14,9 @@
  *    message delta is a cache miss each turn.
  */
 
+import type { AgentTool } from "./types";
 import type { Context, Message, Tool } from "@linxiraos/pi-ai";
+import { toolWireSchema } from "@linxiraos/pi-ai";
 import { normalizeTools } from "./agent-loop";
 import { messageEstimateVersion } from "./compaction/message-cache";
 import type { AgentContext, AgentMessage } from "./types";
@@ -23,6 +25,52 @@ import type { AgentContext, AgentMessage } from "./types";
 // StablePrefix (formerly ImmutablePrefix)
 // ---------------------------------------------------------------------------
 
+/**
+ * Cheap per-tool wire-identity key: every field normalizeTools and
+ * computeFingerprint read. The resolved parameters contribute by object
+ * identity — the wire-schema memo is stamp-keyed on the parameters object,
+ * so identity equals normalized bytes (modulo intent injection, a pure
+ * function of the mode flags compared separately). `customFormat` and
+ * `examples` contribute by reference: both are treated as immutable config
+ * (a registry swap replaces the object), matching how the snapshot consumes
+ * them. `intent` functions are compared by reference — same closure means
+ * same mode resolution.
+ */
+function toolKeyForPrefix(tool: AgentTool): string {
+	const params = toolWireSchema(tool);
+	const customFormat = tool.customFormat;
+	const examples = (tool as { examples?: unknown }).examples;
+	// Identity strings for objects (Map-assigned ids, no string-build cost
+	// on the hot path beyond the first sighting per object).
+	return [
+		tool.name ?? "",
+		tool.description ?? "",
+		String(tool.strict ?? ""),
+		tool.customWireName ?? "",
+		typeof tool.intent === "function" ? `fn:${objectId(tool.intent)}` : `mode:${tool.intent ?? "require"}`,
+		objectId(params),
+		objectId(customFormat),
+		objectId(examples),
+	].join("\u0000");
+}
+
+const objectIds = new WeakMap<object, number>();
+let nextObjectId = 1;
+
+function objectId(obj: unknown): number {
+	if (obj === null || obj === undefined || (typeof obj !== "object" && typeof obj !== "function")) {
+		// Primitives contribute by value below via String(); the id path is
+		// only for reference-identity comparison of config objects.
+		return 0;
+	}
+	let id = objectIds.get(obj);
+	if (id === undefined) {
+		id = nextObjectId++;
+		objectIds.set(obj, id);
+	}
+	return id;
+}
+
 /** Frozen system prompt + tool spec snapshot. */
 export interface StablePrefixSnapshot {
 	systemPrompt: string[];
@@ -63,10 +111,42 @@ export class StablePrefix {
 	/**
 	 * Build or rebuild from live context.
 	 * Returns `true` if the prefix actually changed (cache miss imminent).
+	 *
+	 * Steady-state fast path: when the live prompt reference is unchanged
+	 * AND every tool resolves to the same normalized parameters identity as
+	 * last build, the fingerprint cannot have changed, so the full snapshot
+	 * + stringify is skipped. Comparing resolved parameters (not the tool
+	 * container) is load-bearing: tools like ReadTool expose `parameters` as
+	 * a getter over live settings (`skillful`, `memory.backend`), so the
+	 * schema can swap under stable tool references when a setting toggles.
+	 * Any other in-place mutation must go through `invalidate()`.
 	 */
+	#lastPrompt: readonly string[] | undefined;
+	// Joined prompt bytes snapshot: the prompt array is caller-owned and
+	// mutable in place (Agent.setSystemPrompt stores the caller's array;
+	// anyone holding it can push/splice), so reference equality alone cannot
+	// prove the bytes are unchanged. Compared by value on the fast path.
+	#lastPromptText: string | undefined;
+	// Per-tool wire-identity snapshot: every field normalizeTools and
+	// computeFingerprint read (name, description, resolved parameters,
+	// strict, customFormat, customWireName, intent mode, examples
+	// reference). A registry swap that keeps name/description/parameters
+	// but changes any of these must miss the fast path.
+	#lastToolKey: readonly string[] | undefined;
+	#lastIntentTracing: boolean | undefined;
+	#lastPruneToolDescriptions: boolean | undefined;
+
 	build(context: AgentContext, options: BuildOptions): boolean {
+		const prev = this.#snapshot;
+		if (prev !== null && this.#fastPathHit(context, options)) {
+			return false;
+		}
 		const snapshot = takeSnapshot(context, options);
-		if (this.#snapshot && this.#snapshot.fingerprint === snapshot.fingerprint) {
+		this.#recordFastPathKey(context, options, snapshot.tools);
+		if (prev && prev.fingerprint === snapshot.fingerprint) {
+			// Identity changed but bytes did not (e.g. equivalent rebuild):
+			// keep serving the cached snapshot so downstream memo identity
+			// (stamp-keyed schema caches) stays stable.
 			return false;
 		}
 		this.#snapshot = snapshot;
@@ -74,9 +154,50 @@ export class StablePrefix {
 		return true;
 	}
 
+	/** True when the cheap key matches: prompt + per-tool resolved identity. */
+	#fastPathHit(context: AgentContext, options: BuildOptions): boolean {
+		if (
+			this.#lastIntentTracing !== options.intentTracing ||
+			this.#lastPruneToolDescriptions !== options.pruneToolDescriptions
+		) {
+			return false;
+		}
+		// Prompt by reference first (steady state), then by joined bytes so
+		// an in-place push/splice of the same array still misses.
+		if (this.#lastPrompt !== context.systemPrompt) return false;
+		if (this.#lastPromptText !== undefined) {
+			const text = context.systemPrompt.join("\u0000");
+			if (text !== this.#lastPromptText) return false;
+		}
+		const tools = context.tools ?? [];
+		if (this.#lastToolKey === undefined || this.#lastToolKey.length !== tools.length) {
+			return false;
+		}
+		for (let i = 0; i < tools.length; i++) {
+			if (this.#lastToolKey[i] !== toolKeyForPrefix(tools[i]!)) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	#recordFastPathKey(context: AgentContext, options: BuildOptions, normalized: Tool[]): void {
+		this.#lastPrompt = context.systemPrompt;
+		this.#lastPromptText = context.systemPrompt.join("\u0000");
+		this.#lastIntentTracing = options.intentTracing;
+		this.#lastPruneToolDescriptions = options.pruneToolDescriptions;
+		this.#lastToolKey = (context.tools ?? []).map(tool => toolKeyForPrefix(tool));
+		void normalized;
+	}
+
 	/** Force rebuild on the next `build()` call. */
 	invalidate(): void {
 		this.#snapshot = null;
+		this.#lastPrompt = undefined;
+		this.#lastPromptText = undefined;
+		this.#lastToolKey = undefined;
+		this.#lastIntentTracing = undefined;
+		this.#lastPruneToolDescriptions = undefined;
 	}
 
 	/**

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

@@ -32,7 +32,7 @@ import {
 	OPENAI_HEADER_VALUES,
 	OPENAI_HEADERS,
 } from "@linxiraos/pi-catalog/wire/codex";
-import { $env, logger, stringifyJson } from "@linxiraos/pi-utils";
+import { $env, isUnexpectedSocketCloseMessage, logger, stringifyJson } from "@linxiraos/pi-utils";
 
 // ============================================================================
 // Types & Configuration
@@ -651,6 +651,7 @@ function isRetryableCompactionError(error: Error): boolean {
 	}
 	const message = error.message.toLowerCase();
 	return (
+		isUnexpectedSocketCloseMessage(message) ||
 		message.includes("stream closed before response.completed") ||
 		message.includes("stream parse failed") ||
 		message.includes("server_error") ||

package/src/compaction/compaction.ts

@@ -72,6 +72,7 @@ import {
 import {
 	buildOpenAiNativeHistory,
 	getPreservedOpenAiRemoteCompactionData,
+	isOpenAiRemoteCompactionApi,
 	requestOpenAiRemoteCompaction,
 	requestRemoteCompaction,
 	shouldUseOpenAiRemoteCompaction,
@@ -459,6 +460,23 @@ function findValidCutPoints(entries: SessionEntry[], startIndex: number, endInde
 	return cutPoints;
 }
 
+/**
+ * True for entries that begin a conversational turn (a user request, a
+ * bash-execution card, a branch summary, or a custom user-role message).
+ * Compaction cut alignment, turn discovery, and the collapsed display
+ * transcript's orphan-head trim all share this boundary definition.
+ */
+export function isTurnStartEntry(entry: SessionEntry): boolean {
+	if (entry.type === "branch_summary" || entry.type === "custom_message") {
+		return true;
+	}
+	if (entry.type === "message") {
+		const role = entry.message.role as string;
+		return role === "user" || role === "bashExecution";
+	}
+	return false;
+}
+
 /**
  * Find the user message (or bashExecution) that starts the turn containing the given entry index.
  * Returns -1 if no turn start found before the index.
@@ -466,17 +484,9 @@ function findValidCutPoints(entries: SessionEntry[], startIndex: number, endInde
  */
 export function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number {
 	for (let i = entryIndex; i >= startIndex; i--) {
-		const entry = entries[i];
-		// branch_summary and custom_message are user-role messages, can start a turn
-		if (entry.type === "branch_summary" || entry.type === "custom_message") {
+		if (isTurnStartEntry(entries[i])) {
 			return i;
 		}
-		if (entry.type === "message") {
-			const role = entry.message.role as string;
-			if (role === "user" || role === "bashExecution") {
-				return i;
-			}
-		}
 	}
 	return -1;
 }
@@ -491,10 +501,11 @@ export interface CutPointResult {
 }
 
 /**
- * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ * Find the oldest complete recent-history suffix that fits `keepRecentTokens`.
  *
- * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
- * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ * Walk backwards by valid cut points, measuring whole assistant/tool groups.
+ * Keep the newest group even when it alone exceeds the budget; never retain
+ * an additional older group that would push an otherwise fitting suffix over.
  *
  * Can cut at user OR assistant messages (never tool results). When cutting at an
  * assistant message with tool calls, its tool results come after and will be kept.
@@ -519,55 +530,45 @@ export function findCutPoint(
 		return { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false };
 	}
 
-	// Walk backwards from newest, accumulating estimated message sizes
+	// Evaluate the budget only at valid boundaries, after counting all results
+	// belonging to an assistant. Checking individual messages can either retain
+	// the oversized older assistant or miss its boundary and retain all history.
 	let accumulatedTokens = 0;
-	let cutIndex = cutPoints[0]; // Default: keep from first message (not header)
+	let cutPointIndex = cutPoints.length - 1;
+	let cutIndex = cutPoints[cutPointIndex];
 
 	for (let i = endIndex - 1; i >= startIndex; i--) {
 		const entry = entries[i];
-		if (entry.type !== "message") continue;
-
-		// Estimate this message's size
-		const messageTokens = tokenizer.countMessage(entry.message);
-		accumulatedTokens += messageTokens;
-
-		// Check if we've exceeded the budget
-		if (accumulatedTokens >= keepRecentTokens) {
-			// Find the closest valid cut point at or after this entry
-			for (let c = 0; c < cutPoints.length; c++) {
-				if (cutPoints[c] >= i) {
-					cutIndex = cutPoints[c];
-					break;
-				}
-			}
-			break;
-		}
+		const message = getMessageFromEntry(entry);
+		if (message) accumulatedTokens += tokenizer.countMessage(message);
+		if (i !== cutPoints[cutPointIndex]) continue;
+		if (accumulatedTokens > keepRecentTokens) break;
+		cutIndex = i;
+		cutPointIndex--;
 	}
 
-	// Scan backwards from cutIndex to include any non-message entries (bash, settings, etc.)
+	const isTurnStart = isTurnStartEntry(entries[cutIndex]);
+	const turnStartIndex = isTurnStart ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
+
+	// Scan backwards from cutIndex to include any non-message entries (settings changes, etc.)
 	while (cutIndex > startIndex) {
 		const prevEntry = entries[cutIndex - 1];
-		// Stop at session header or compaction boundaries
-		if (prevEntry.type === "compaction") {
+		// Stop at session header, compaction, or reset boundaries
+		if (prevEntry.type === "compaction" || prevEntry.type === "reset_boundary") {
 			break;
 		}
-		if (prevEntry.type === "message") {
-			// Stop if we hit any message
+		if (getMessageFromEntry(prevEntry)) {
+			// Stop if we hit any entry that contributes a message
 			break;
 		}
-		// Include this non-message entry (bash, settings change, etc.)
+		// Include this non-message entry (settings change, label, etc.)
 		cutIndex--;
 	}
 
-	// Determine if this is a split turn
-	const cutEntry = entries[cutIndex];
-	const isUserMessage = cutEntry.type === "message" && cutEntry.message.role === "user";
-	const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
-
 	return {
 		firstKeptEntryIndex: cutIndex,
 		turnStartIndex,
-		isSplitTurn: !isUserMessage && turnStartIndex !== -1,
+		isSplitTurn: !isTurnStart && turnStartIndex !== -1,
 	};
 }
 
@@ -1267,19 +1268,27 @@ export interface CompactionPreparation {
 }
 
 /**
- * Whether a prior remote compaction's provider-native replay can still be read
- * by the active model — the model that assembles the request context on every
- * turn. A local compaction (no remote preserve) always can: it holds a real
- * textual summary. A remote compaction (V2 or V1) only can when the active model
- * shares the blob's provider AND remote replay is still enabled; otherwise the
- * active model's encoder drops the payload (see `getOpenAIResponsesHistoryPayload`)
- * and only the opaque placeholder summary survives, so the caller must re-expand
- * the originals into a portable local summary rather than strand that history.
+ * Whether the active model's normal encoder can consume stored native history.
+ * Creating future compactions is a separate policy: disabling it does not disable
+ * Responses-family replay. Local summaries have no provider restriction.
+ */
+export function canReplayRemoteCompaction(
+	preserveData: Record<string, unknown> | undefined,
+	activeModel: Model,
+): boolean {
+	const remote = getCompactionV2PreserveData(preserveData) ?? getPreservedOpenAiRemoteCompactionData(preserveData);
+	return !remote || (remote.provider === activeModel.provider && isOpenAiRemoteCompactionApi(activeModel.api));
+}
+
+/**
+ * Whether compaction preparation may reuse a native boundary instead of
+ * re-expanding its original messages. This is deliberately stricter than normal
+ * replay: the active model must both read the payload and remain eligible for
+ * native compaction under the current settings. Otherwise local summarization
+ * needs the originals, not an opaque placeholder.
  *
- * Judged against the ACTIVE model, not the compaction candidate set: a role
- * model (e.g. `modelRoles.smol`) that still maps to the blob's provider does not
- * let the active model replay it, so keying reuse on "any candidate shares the
- * provider" left a provider-switched session permanently context-less (#6343).
+ * Main-session preparation is judged against the active model, not any role
+ * candidate, so a provider switch cannot strand the original history (#6343).
  */
 export function remotePreserveReusable(
 	preserveData: Record<string, unknown> | undefined,
@@ -1288,15 +1297,16 @@ export function remotePreserveReusable(
 ): boolean {
 	const remote = getCompactionV2PreserveData(preserveData) ?? getPreservedOpenAiRemoteCompactionData(preserveData);
 	if (!remote) return true;
-	if (settings.remoteEnabled === false) return false;
-	if (remote.provider !== activeModel.provider) return false;
-	const v2Ok = settings.remoteStreamingV2Enabled !== false && shouldUseCompactionV2Streaming(activeModel);
-	return v2Ok || shouldUseOpenAiRemoteCompaction(activeModel);
+	return (
+		remote.provider === activeModel.provider &&
+		isOpenAiRemoteCompactionApi(activeModel.api) &&
+		shouldUseProviderNativeCompaction(activeModel, settings)
+	);
 }
 
 /**
- * Index of the newest compaction entry the active model can actually read, or
- * `-1` when none can.
+ * Index of the newest compaction boundary reusable under preparation policy,
+ * or `-1` when none can be reused (see {@link remotePreserveReusable}).
  *
  * A provider-native remote compaction (V2 or V1) stores an opaque replay payload
  * and only a placeholder summary, so for any OTHER provider that entry
@@ -1331,14 +1341,16 @@ export function prepareCompaction(
 	activeModel?: Model,
 	tokenizer: Tokenizer = new Tokenizer(activeModel),
 ): CompactionPreparation | undefined {
-	if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
+	const lastEntry = pathEntries[pathEntries.length - 1];
+	// A speculative native record may leave uncovered messages before the record.
+	if (lastEntry?.type === "compaction" && !lastEntry.providerReplayThroughEntryId) {
 		return undefined;
 	}
 
 	let prevCompactionIndex = findReadableCompactionIndex(pathEntries, settings, activeModel);
 
-	// A reset after the reusable compaction clears its summary too. An older
-	// reset still bounds how far we may recover that compaction's kept messages.
+	// A newer reset clears the previous summary. An older reset bounds both
+	// the local retained tail and the native snapshot-to-commit interval.
 	let resetBoundaryIndex = -1;
 	for (let i = pathEntries.length - 1; i >= 0; i--) {
 		if (pathEntries[i].type === "reset_boundary") {
@@ -1354,9 +1366,20 @@ export function prepareCompaction(
 	let boundaryStart = Math.max(prevCompactionIndex, resetBoundaryIndex) + 1;
 	if (
 		previousCompaction &&
-		!getCompactionV2PreserveData(previousCompaction.preserveData) &&
-		!getPreservedOpenAiRemoteCompactionData(previousCompaction.preserveData)
+		(getCompactionV2PreserveData(previousCompaction.preserveData) ||
+			getPreservedOpenAiRemoteCompactionData(previousCompaction.preserveData))
 	) {
+		if (previousCompaction.providerReplayThroughEntryId) {
+			const replayThroughIndex = pathEntries.findIndex(
+				entry => entry.id === previousCompaction.providerReplayThroughEntryId,
+			);
+			if (replayThroughIndex >= 0 && replayThroughIndex < prevCompactionIndex) {
+				// Native replay covers the snapshot, not messages appended while the
+				// request was running. Include that interval in the next preparation.
+				boundaryStart = Math.max(replayThroughIndex, resetBoundaryIndex) + 1;
+			}
+		}
+	} else if (previousCompaction) {
 		// Local summaries exclude the retained tail, whose original entries precede
 		// the compaction record. Native replay already carries that tail. Only look
 		// backwards: advisor snapshots put all retained messages after the summary
@@ -1605,12 +1628,21 @@ export async function compact(
 	const snapcompactArchiveMigrationMessage = previousSnapcompactArchiveText
 		? createSnapcompactArchiveMigrationMessage(previousSnapcompactArchiveText)
 		: undefined;
+	const previousNativeHistory =
+		getCompactionV2PreserveData(previousPreserveData) ?? getPreservedOpenAiRemoteCompactionData(previousPreserveData);
+	// A local summary has no native payload to carry it into the first remote
+	// request. Encode it as history; do not resend opaque native placeholders.
+	const previousSummaryMigrationMessage =
+		settings.remoteEnabled !== false && previousSummary && !previousNativeHistory
+			? createCompactionSummaryMessage(previousSummary, tokensBefore, new Date().toISOString())
+			: undefined;
 
 	let preserveData = withAnthropicCompactionPreserveData(
 		withOpenAiRemoteCompactionPreserveData(previousPreserveData, undefined),
 		undefined,
 	);
 	const remoteMessages: AgentMessage[] = [
+		...(previousSummaryMigrationMessage ? [previousSummaryMigrationMessage] : []),
 		...(snapcompactArchiveMigrationMessage ? [snapcompactArchiveMigrationMessage] : []),
 		...messagesToSummarize,
 		...turnPrefixMessages,

package/src/compaction/entries.ts

@@ -37,6 +37,8 @@ export interface CompactionEntry<T = unknown> extends SessionEntryBase {
 	shortSummary?: string;
 	firstKeptEntryId: string;
 	tokensBefore: number;
+	/** Last entry covered by native replay; later entries may precede the compaction record. */
+	providerReplayThroughEntryId?: string;
 	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
 	details?: T;
 	/** Hook-provided data to persist across compaction */

package/src/compaction/openai.ts

@@ -282,15 +282,22 @@ export interface RemoteCompactionResponse {
 // OpenAI provider gating + endpoint resolution
 // ============================================================================
 
-function isOpenAiRemoteCompactionApi(api: Api | undefined): boolean {
+export function isOpenAiRemoteCompactionApi(api: Api | undefined): boolean {
 	return api === "openai-responses" || api === "azure-openai-responses" || api === "openai-codex-responses";
 }
 
 export function shouldUseOpenAiRemoteCompaction(model: Model): boolean {
 	if (model.remoteCompaction?.enabled === false) return false;
-	if (model.provider === "openai" || model.provider === "openai-codex") return true;
+	const compactionApi = model.remoteCompaction?.api ?? model.api;
+	// ChatGPT's Codex backend exposes V2 compaction on /codex/responses, but
+	// does not expose the OpenAI V1 /responses/compact endpoint. Only use the
+	// V1 path for Codex when an explicit compatible endpoint was configured.
+	if (model.provider === "openai-codex") {
+		return (model.remoteCompaction?.endpoint?.trim().length ?? 0) > 0;
+	}
+	if (model.provider === "openai") return true;
 	if (model.remoteCompaction?.enabled !== true) return false;
-	return isOpenAiRemoteCompactionApi(model.remoteCompaction.api ?? model.api);
+	return isOpenAiRemoteCompactionApi(compactionApi);
 }
 
 function resolveOpenAiCompactEndpoint(model: Model): string {

package/src/proxy.ts

@@ -20,7 +20,7 @@ import {
 	type StreamingPartialJsonCarrier,
 	setStreamingPartialJson,
 } from "@linxiraos/pi-ai/utils/block-symbols";
-import { parseStreamingJson, readSseJson } from "@linxiraos/pi-utils";
+import { parseStreamingJson, parseStreamingJsonThrottled, readSseJson } from "@linxiraos/pi-utils";
 
 // Event stream adapter for proxy SSE events
 export class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
@@ -117,6 +117,10 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 		};
 
 		let response: Response | null = null;
+		// Declared outside try so the disconnect path (catch) can finalize
+		// still-buffered tool-call arguments before emitting the error event.
+		const partialJsonByIndex = new Map<number, string>();
+		const parsedLenByIndex = new Map<number, number>();
 		const abortHandler = () => {
 			const body = response?.body;
 			if (body) {
@@ -165,12 +169,11 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 			}
 
 			let sawTerminalEvent = false;
-			const partialJsonByIndex = new Map<number, string>();
 			for await (const event of readSseJson<ProxyAssistantMessageEvent>(
 				response.body as ReadableStream<Uint8Array>,
 				options.signal,
 			)) {
-				const parsedEvent = processProxyEvent(event, partial, partialJsonByIndex);
+				const parsedEvent = processProxyEvent(event, partial, partialJsonByIndex, parsedLenByIndex);
 				if (parsedEvent) {
 					if (parsedEvent.type === "done" || parsedEvent.type === "error") {
 						sawTerminalEvent = true;
@@ -193,6 +196,10 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 			const reason = options.signal?.aborted ? "aborted" : "error";
 			partial.stopReason = reason;
 			partial.errorMessage = errorMessage;
+			// Disconnect/abort path: no terminal event ran, so trailing
+			// throttled deltas never reached content.arguments. Finalize
+			// them here so the persisted/retried transcript is complete.
+			finalizeBufferedArguments(partial, partialJsonByIndex);
 			scrubPartialJson(partial);
 			stream.push({
 				type: "error",
@@ -235,6 +242,7 @@ function processProxyEvent(
 	proxyEvent: ProxyAssistantMessageEvent,
 	partial: AssistantMessage,
 	partialJsonByIndex: Map<number, string>,
+	parsedLenByIndex: Map<number, number>,
 ): AssistantMessageEvent | undefined {
 	switch (proxyEvent.type) {
 		case "start":
@@ -335,13 +343,22 @@ function processProxyEvent(
 				[kStreamingPartialJson]: "",
 			} as ToolCall & StreamingPartialJsonCarrier;
 			partialJsonByIndex.set(proxyEvent.contentIndex, "");
+			parsedLenByIndex.set(proxyEvent.contentIndex, 0);
 			return { type: "toolcall_start", contentIndex: proxyEvent.contentIndex, partial };
 		case "toolcall_delta": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "toolCall") {
 				const acc = (partialJsonByIndex.get(proxyEvent.contentIndex) ?? "") + proxyEvent.delta;
 				partialJsonByIndex.set(proxyEvent.contentIndex, acc);
-				content.arguments = parseStreamingJson(acc) || {};
+				// Geometric throttle (same contract as native providers): the
+				// authoritative parse lands at toolcall_end; mid-stream
+				// previews refresh at most ~3% late on large buffers.
+				const lastLen = parsedLenByIndex.get(proxyEvent.contentIndex) ?? 0;
+				const parsed = parseStreamingJsonThrottled(acc, lastLen);
+				if (parsed !== null) {
+					content.arguments = parsed.value || {};
+					parsedLenByIndex.set(proxyEvent.contentIndex, parsed.parsedLen);
+				}
 				setStreamingPartialJson(content, acc);
 				partial.content[proxyEvent.contentIndex] = { ...content }; // Trigger reactivity
 				return {
@@ -357,7 +374,13 @@ function processProxyEvent(
 		case "toolcall_end": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "toolCall") {
+				// Authoritative final parse (mirrors native providers): the
+				// throttle may have skipped trailing deltas, so the last
+				// parsed arguments can lag the accumulated buffer.
+				const acc = partialJsonByIndex.get(proxyEvent.contentIndex);
+				if (acc !== undefined && acc.length > 0) content.arguments = parseStreamingJson(acc) || {};
 				partialJsonByIndex.delete(proxyEvent.contentIndex);
+				parsedLenByIndex.delete(proxyEvent.contentIndex);
 				clearStreamingPartialJson(content);
 				return {
 					type: "toolcall_end",
@@ -373,7 +396,10 @@ function processProxyEvent(
 			partial.stopReason = proxyEvent.reason;
 			partial.usage = proxyEvent.usage;
 			if (proxyEvent.content !== undefined) partial.content = proxyEvent.content;
+			else finalizeBufferedArguments(partial, partialJsonByIndex);
 			scrubPartialJson(partial);
+			partialJsonByIndex.clear();
+			parsedLenByIndex.clear();
 			return { type: "done", reason: proxyEvent.reason, message: partial };
 
 		case "error":
@@ -381,7 +407,26 @@ function processProxyEvent(
 			partial.errorMessage = proxyEvent.errorMessage;
 			partial.usage = proxyEvent.usage;
 			if (proxyEvent.content !== undefined) partial.content = proxyEvent.content;
+			else finalizeBufferedArguments(partial, partialJsonByIndex);
 			scrubPartialJson(partial);
+			partialJsonByIndex.clear();
+			parsedLenByIndex.clear();
 			return { type: "error", reason: proxyEvent.reason, error: partial };
 	}
 }
+
+/**
+ * Authoritatively parse every still-buffered tool-call argument accumulator
+ * into its content block. Terminal `done`/`error` events without a preceding
+ * `toolcall_end` (and with `content` omitted) finalize the partial message as
+ *-is; without this, trailing deltas below the throttle gate never reach
+ * `content.arguments` and the finalized call carries stale arguments.
+ */
+function finalizeBufferedArguments(partial: AssistantMessage, partialJsonByIndex: Map<number, string>): void {
+	if (partialJsonByIndex.size === 0) return;
+	for (const [index, acc] of partialJsonByIndex) {
+		if (acc.length === 0) continue;
+		const content = partial.content[index];
+		if (content?.type === "toolCall") content.arguments = parseStreamingJson(acc) || {};
+	}
+}

package/src/telemetry.ts

@@ -1756,6 +1756,7 @@ export async function instrumentedCompleteSimple<TApi extends Api>(
 			const message = span.retry
 				? await retryTransientCompletion(runOnce, {
 						...span.retry,
+						provider: model.provider,
 						// Framework-owned: the caller must not be able to detach the
 						// abort signal or the header source by passing them itself.
 						signal: options.signal,

package/src/thinking.ts

@@ -1,4 +1,4 @@
-import { Effort } from "@linxiraos/pi-ai";
+import { Effort } from "@linxiraos/pi-catalog/effort";
 
 /**
  * Agent-local thinking selector.

package/src/tokenizer.ts

@@ -274,6 +274,7 @@ export class Tokenizer {
 				}
 				break;
 			}
+			case "custom":
 			case "hookMessage":
 			case "toolResult": {
 				if (typeof message.content === "string") {

package/src/types.ts

@@ -31,6 +31,18 @@ export type StreamFn = (
 	...args: Parameters<typeof streamSimple>
 ) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 
+/** Staged queue preparation; commit synchronously only while the batch is still owned. */
+export interface QueuedMessagePreparation {
+	/** Append context after the originals; undefined stops this attempt, retaining originals unless explicitly removed. */
+	commit(): readonly AgentMessage[] | undefined;
+}
+
+/** Prepare an exclusively claimed batch. Undefined delivers unchanged; the signal also aborts when the claim is cancelled. */
+export type PrepareQueuedMessages = (
+	messages: readonly AgentMessage[],
+	signal: AbortSignal,
+) => QueuedMessagePreparation | undefined | Promise<QueuedMessagePreparation | undefined>;
+
 /** Called once an aside has been inserted into the agent's live context. */
 export const ASIDE_MESSAGE_COMMIT = Symbol("aside-message-commit");
 /** Symbol-keyed handoff for one finalized, tool-owned stream speculation session. */
@@ -1000,8 +1012,9 @@ export interface AgentTool<
 	 * Called at `toolcall_start`, before any argument delta. Return `undefined` to opt out.
 	 */
 	openArgStream?: (init: AgentToolArgStreamInit) => AgentToolArgStream | undefined;
-	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
 	hidden?: boolean;
+	/** If true, the tool can read `skill://<name>` instruction content; prompt builders gate skill guidance on it. */
+	readsSkillUris?: boolean;
 	/** If true, tool can stage a pending action that requires explicit resolution via the resolve tool. */
 	deferrable?: boolean;
 	/** How an enabled tool is presented. See {@link ToolLoadMode}. Omitted is treated as `"essential"` for built-ins; custom-tool adapters normalize omission to `"discoverable"`. */