@oh-my-pi/pi-agent-core 16.2.1 → 16.2.3

package/src/compaction/compaction.ts

@@ -14,12 +14,14 @@ import {
 	type Message,
 	type MessageAttribution,
 	type Model,
-	ProviderHttpError,
 	type SimpleStreamOptions,
 	type Tool,
 	type Usage,
 	withAuth,
 } from "@oh-my-pi/pi-ai";
+import { ProviderHttpError } from "@oh-my-pi/pi-ai/error";
+import { convertTools } from "@oh-my-pi/pi-ai/providers/openai-responses";
+import { buildResponsesInput, resolveOpenAICompatPolicy } from "@oh-my-pi/pi-ai/providers/openai-shared";
 import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { clampThinkingLevelForModel } from "@oh-my-pi/pi-catalog/model-thinking";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
@@ -28,6 +30,14 @@ import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import { ThinkingLevel } from "../thinking";
 import { countTokens } from "../tokenizer";
 import type { AgentMessage } from "../types";
+import {
+	buildCompactionV2Request,
+	getCompactionV2PreserveData,
+	requestCompactionV2Streaming,
+	shouldUseCompactionV2Streaming,
+	storeCompactionV2PreserveData,
+	V2_RETAINED_MESSAGE_TOKEN_BUDGET,
+} from "./compaction-v2-streaming";
 import type { CompactionEntry, SessionEntry } from "./entries";
 import { type ConvertToLlm, createBranchSummaryMessage, createCustomMessage, defaultConvertToLlm } from "./messages";
 import {
@@ -155,6 +165,8 @@ export interface CompactionSettings {
 	autoContinue?: boolean;
 	remoteEnabled?: boolean;
 	remoteEndpoint?: string;
+	remoteStreamingV2Enabled?: boolean;
+	v2RetainedMessageBudget?: number;
 }
 
 export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
@@ -167,6 +179,8 @@ export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
 	keepRecentTokens: 20000,
 	autoContinue: true,
 	remoteEnabled: true,
+	remoteStreamingV2Enabled: true,
+	v2RetainedMessageBudget: V2_RETAINED_MESSAGE_TOKEN_BUDGET,
 };
 
 // ============================================================================
@@ -657,6 +671,12 @@ export interface SummaryOptions {
 	 * `resolveCompactionEffort` for the conversion contract.
 	 */
 	thinkingLevel?: ThinkingLevel;
+	/** Session routing key for remote compaction transports with sticky provider sessions. */
+	sessionId?: string;
+	/** Prompt-cache key for remote compaction transports that support provider prefix caching. */
+	promptCacheKey?: string;
+	/** Provider-visible tools for remote compaction transports that replay native tool history. */
+	tools?: Tool[];
 	/** Optional fetch implementation threaded into remote compaction calls. */
 	fetch?: FetchImpl;
 }
@@ -972,9 +992,34 @@ export interface CompactionPreparation {
 	settings: CompactionSettings;
 }
 
+/**
+ * Whether a prior compaction's preserve data can be carried forward by the
+ * upcoming compaction. A local compaction (no remote preserve) always can — it
+ * holds a real textual summary. A remote compaction (V2 or V1) only can when
+ * some candidate model shares its provider AND remote replay is still enabled;
+ * otherwise its provider-native replay is dead weight and only the opaque
+ * placeholder summary survives, so the caller must re-expand the originals.
+ */
+function remotePreserveReusableByAny(
+	preserveData: Record<string, unknown> | undefined,
+	models: readonly Model[],
+	settings: CompactionSettings,
+): boolean {
+	const remote = getCompactionV2PreserveData(preserveData) ?? getPreservedOpenAiRemoteCompactionData(preserveData);
+	if (!remote) return true;
+	if (settings.remoteEnabled === false) return false;
+	for (const model of models) {
+		if (remote.provider !== model.provider) continue;
+		const v2Ok = settings.remoteStreamingV2Enabled !== false && shouldUseCompactionV2Streaming(model);
+		if (v2Ok || shouldUseOpenAiRemoteCompaction(model)) return true;
+	}
+	return false;
+}
+
 export function prepareCompaction(
 	pathEntries: SessionEntry[],
 	settings: CompactionSettings,
+	compactionModels: readonly Model[] = [],
 ): CompactionPreparation | undefined {
 	if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
 		return undefined;
@@ -982,10 +1027,18 @@ export function prepareCompaction(
 
 	let prevCompactionIndex = -1;
 	for (let i = pathEntries.length - 1; i >= 0; i--) {
-		if (pathEntries[i].type === "compaction") {
-			prevCompactionIndex = i;
-			break;
+		if (pathEntries[i].type !== "compaction") continue;
+		// Skip a prior remote compaction (V2 or V1) whose provider-native replay
+		// none of the upcoming compaction candidates can reuse: its summary is only
+		// an opaque placeholder, so re-expand its original messages and summarize
+		// them locally rather than stranding that history. compact() still reuses it
+		// when a candidate can (same provider, remote enabled).
+		const entry = pathEntries[i] as CompactionEntry;
+		if (compactionModels.length > 0 && !remotePreserveReusableByAny(entry.preserveData, compactionModels, settings)) {
+			continue;
 		}
+		prevCompactionIndex = i;
+		break;
 	}
 	const boundaryStart = prevCompactionIndex + 1;
 	const boundaryEnd = pathEntries.length;
@@ -1079,6 +1132,49 @@ export function prepareCompaction(
 
 const TURN_PREFIX_SUMMARIZATION_PROMPT = prompt.render(compactionTurnPrefixPrompt);
 
+function openAiCompatSupportsImageDetailOriginal(model: Model): boolean {
+	const compat = model.compat;
+	return !!compat && "supportsImageDetailOriginal" in compat && compat.supportsImageDetailOriginal === true;
+}
+
+function buildOpenAiResponsesCompactionInput(
+	messages: Message[],
+	model: Model<"openai-responses" | "azure-openai-responses" | "openai-codex-responses">,
+	previousReplacementHistory: Array<Record<string, unknown>> | undefined,
+): unknown[] {
+	const input = buildResponsesInput({
+		model,
+		context: { messages },
+		strictResponsesPairing: model.compat.strictResponsesPairing,
+		supportsImageDetailOriginal: openAiCompatSupportsImageDetailOriginal(model),
+		nativeHistory: { replay: true, filterReasoning: false },
+		includeThinkingSignatures: true,
+		repairOrphanOutputs: true,
+	});
+	return previousReplacementHistory ? [...previousReplacementHistory, ...input] : input;
+}
+
+/**
+ * Resolve the Responses `reasoning` param for a V2 compaction request the same
+ * way a normal turn does — through {@link resolveOpenAICompatPolicy}, so it
+ * honors per-model effort support, `omitReasoningEffort`, disable modes, and the
+ * wire-effort mapping. Returns `undefined` for non-reasoning models or when the
+ * user selected `Off` (matching the normal-turn omission, not a fabricated shape).
+ */
+function buildCompactionV2Reasoning(
+	model: Model<"openai-responses" | "azure-openai-responses" | "openai-codex-responses">,
+	thinkingLevel: ThinkingLevel | undefined,
+): { effort: string; summary: string } | undefined {
+	const policy = resolveOpenAICompatPolicy(model, {
+		endpoint: "responses",
+		reasoning: resolveCompactionEffort(model, thinkingLevel),
+	});
+	const reasoning = policy.reasoning;
+	if (!reasoning.modelSupported || reasoning.disabled || reasoning.omitReasoningEffort) return undefined;
+	if (reasoning.requestedEffort === undefined) return undefined;
+	return { effort: reasoning.wireEffort ?? reasoning.requestedEffort, summary: "auto" };
+}
+
 /**
  * Generate summaries for compaction using prepared data.
  * Returns CompactionResult - SessionManager adds id/parentId when saving.
@@ -1122,6 +1218,9 @@ export async function compact(
 		// silently falls back to Effort.High — the same defect e07b47ee4 fixed
 		// at the call sites, leaked back in here. See resolveCompactionEffort.
 		thinkingLevel: options?.thinkingLevel,
+		sessionId: options?.sessionId,
+		promptCacheKey: options?.promptCacheKey,
+		tools: options?.tools,
 		fetch: options?.fetch,
 	};
 
@@ -1138,18 +1237,74 @@ export async function compact(
 		: undefined;
 
 	let preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, undefined);
-	if (settings.remoteEnabled !== false && shouldUseOpenAiRemoteCompaction(model)) {
-		const previousRemoteCompaction = getPreservedOpenAiRemoteCompactionData(previousPreserveData);
-		const remoteMessages: AgentMessage[] = [
-			...(snapcompactArchiveMigrationMessage ? [snapcompactArchiveMigrationMessage] : []),
-			...messagesToSummarize,
-			...turnPrefixMessages,
-			...recentMessages,
-		];
+	const remoteMessages: AgentMessage[] = [
+		...(snapcompactArchiveMigrationMessage ? [snapcompactArchiveMigrationMessage] : []),
+		...messagesToSummarize,
+		...turnPrefixMessages,
+		...recentMessages,
+	];
+	let usedRemoteCompaction = false;
+	if (
+		settings.remoteEnabled !== false &&
+		settings.remoteStreamingV2Enabled !== false &&
+		shouldUseCompactionV2Streaming(model)
+	) {
+		const previousRemoteCompaction = getCompactionV2PreserveData(previousPreserveData);
 		const previousReplacementHistory =
 			previousRemoteCompaction?.provider === model.provider
 				? previousRemoteCompaction.replacementHistory
 				: undefined;
+		const remoteHistory = buildOpenAiResponsesCompactionInput(
+			(summaryOptions.convertToLlm ?? defaultConvertToLlm)(remoteMessages),
+			model,
+			previousReplacementHistory,
+		);
+		if (remoteHistory.length > 0) {
+			try {
+				const request = buildCompactionV2Request(
+					model,
+					remoteHistory,
+					summaryOptions.remoteInstructions ?? SUMMARIZATION_SYSTEM_PROMPT,
+					{
+						tools: summaryOptions.tools
+							? convertTools(summaryOptions.tools, model.compat.supportsStrictMode, model)
+							: undefined,
+						reasoning: buildCompactionV2Reasoning(model, summaryOptions.thinkingLevel),
+						sessionId: summaryOptions.sessionId,
+						promptCacheKey: summaryOptions.promptCacheKey,
+						retainedMessageBudget: settings.v2RetainedMessageBudget,
+					},
+				);
+				const remote = await withAuth(
+					apiKey,
+					key => requestCompactionV2Streaming(model, key, request, signal, { fetch: summaryOptions.fetch }),
+					{ signal },
+				);
+				preserveData = { ...(preserveData ?? {}), ...storeCompactionV2PreserveData(remote, model) };
+				usedRemoteCompaction = true;
+			} catch (err) {
+				// A user/session abort is a cancellation, not a remote failure —
+				// swallowing it here would downgrade Esc into "fall back to local
+				// summarization" and keep compaction running on an aborted signal.
+				if (signal?.aborted) throw err;
+				logger.warn("OpenAI V2 remote compaction failed, falling back to V1/local summarization", {
+					error: err instanceof Error ? err.message : String(err),
+					model: model.id,
+					provider: model.provider,
+				});
+			}
+		}
+	}
+
+	if (!usedRemoteCompaction && settings.remoteEnabled !== false && shouldUseOpenAiRemoteCompaction(model)) {
+		const previousRemoteCompaction = getPreservedOpenAiRemoteCompactionData(previousPreserveData);
+		const previousV2Compaction = getCompactionV2PreserveData(previousPreserveData);
+		const previousReplacementHistory =
+			previousRemoteCompaction?.provider === model.provider
+				? previousRemoteCompaction.replacementHistory
+				: previousV2Compaction?.provider === model.provider
+					? previousV2Compaction.replacementHistory
+					: undefined;
 		const remoteHistory = buildOpenAiNativeHistory(
 			(summaryOptions.convertToLlm ?? defaultConvertToLlm)(remoteMessages),
 			model,
@@ -1171,6 +1326,7 @@ export async function compact(
 					{ signal },
 				);
 				preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, remote);
+				usedRemoteCompaction = true;
 			} catch (err) {
 				// A user/session abort is a cancellation, not a remote failure —
 				// swallowing it here would downgrade Esc into "fall back to local
@@ -1188,7 +1344,18 @@ export async function compact(
 	// Generate summaries (can be parallel if both needed) and merge into one
 	let summary: string;
 
-	if (isSplitTurn && turnPrefixMessages.length > 0) {
+	if (usedRemoteCompaction) {
+		// Remote compaction (V2 or V1) already compacted remotely; the durable
+		// history lives in the provider replay payload (preserveData). Skip local
+		// summarization so a successful remote compaction never pays for a second,
+		// redundant LLM round. If a LATER compaction cannot reuse this payload,
+		// prepareCompaction re-expands the original messages and summarizes them
+		// locally then (see remotePreserveReusableByAny).
+		const usedTokens = getCompactionV2PreserveData(preserveData)?.usedTokens ?? 0;
+		summary =
+			"Remote compaction preserved provider-native history for this session." +
+			(usedTokens > 0 ? ` Retained ${usedTokens} tokens in the provider replay payload.` : "");
+	} else if (isSplitTurn && turnPrefixMessages.length > 0) {
 		// Generate both summaries in parallel
 		const [historyResult, turnPrefixResult] = await Promise.all([
 			messagesToSummarize.length > 0 || previousSummaryForCompaction
@@ -1227,25 +1394,19 @@ export async function compact(
 		summary = "No prior history.";
 	}
 
-	const shortSummary = await generateShortSummary(
-		recentMessages,
-		summary,
-		model,
-		settings.reserveTokens,
-		apiKey,
-		signal,
-		{
-			extraContext: options?.extraContext,
-			remoteEndpoint: summaryOptions.remoteEndpoint,
-			initiatorOverride: summaryOptions.initiatorOverride,
-			metadata: summaryOptions.metadata,
-			telemetry: summaryOptions.telemetry,
-			// Same propagation as summaryOptions above — generateShortSummary
-			// resolves its own reasoning via resolveCompactionEffort.
-			thinkingLevel: options?.thinkingLevel,
-			fetch: summaryOptions.fetch,
-		},
-	);
+	const shortSummary = usedRemoteCompaction
+		? "Remote compaction"
+		: await generateShortSummary(recentMessages, summary, model, settings.reserveTokens, apiKey, signal, {
+				extraContext: options?.extraContext,
+				remoteEndpoint: summaryOptions.remoteEndpoint,
+				initiatorOverride: summaryOptions.initiatorOverride,
+				metadata: summaryOptions.metadata,
+				telemetry: summaryOptions.telemetry,
+				// Same propagation as summaryOptions above — generateShortSummary
+				// resolves its own reasoning via resolveCompactionEffort.
+				thinkingLevel: options?.thinkingLevel,
+				fetch: summaryOptions.fetch,
+			});
 
 	// Compute file lists and append to summary
 	const { readFiles, modifiedFiles } = computeFileLists(fileOps);

package/src/compaction/entries.ts

@@ -77,6 +77,14 @@ export interface LabelEntry extends SessionEntryBase {
 	label: string | undefined;
 }
 
+export interface TitleChangeEntry extends SessionEntryBase {
+	type: "title_change";
+	title: string;
+	previousTitle?: string;
+	source: "auto" | "user";
+	trigger?: string;
+}
+
 export interface TtsrInjectionEntry extends SessionEntryBase {
 	type: "ttsr_injection";
 	/** Names of rules that were injected */
@@ -121,6 +129,7 @@ export type SessionEntry =
 	| CustomEntry
 	| CustomMessageEntry
 	| LabelEntry
+	| TitleChangeEntry
 	| TtsrInjectionEntry
 	| MCPToolSelectionEntry
 	| SessionInitEntry

package/src/compaction/openai.ts

@@ -1,9 +1,12 @@
 /**
  * Remote compaction utilities.
  *
- * Provider-side conversation summarization endpoints. Two flavors:
+ * Provider-side conversation summarization endpoints. Three flavors:
  *
- * - **OpenAI remote compaction** (`/responses/compact`): preserves encrypted
+ * - **OpenAI remote compaction V2** (Responses streaming): appends a
+ *   `compaction_trigger` input item to the normal stream and stores the returned
+ *   `compaction` item with retained real user messages in `preserveData`.
+ * - **OpenAI remote compaction V1** (`/responses/compact`): preserves encrypted
  *   reasoning across compactions by submitting the full responses-API native
  *   history and storing the returned `compaction` / `compaction_summary`
  *   item in `preserveData` so future turns can replay the encrypted state.
@@ -12,7 +15,7 @@
  *   with `{ summary, shortSummary? }`.
  */
 
-import { ProviderHttpError } from "@oh-my-pi/pi-ai/errors";
+import { ProviderHttpError } from "@oh-my-pi/pi-ai/error";
 import { parseAzureDeploymentNameMap, parseTextSignature } from "@oh-my-pi/pi-ai/providers/openai-shared";
 import { transformMessages } from "@oh-my-pi/pi-ai/providers/transform-messages";
 import type { Api, AssistantMessage, FetchImpl, Message, Model } from "@oh-my-pi/pi-ai/types";
@@ -29,6 +32,8 @@ import {
 } from "@oh-my-pi/pi-catalog/wire/codex";
 import { $env, logger } from "@oh-my-pi/pi-utils";
 
+export * from "./compaction-v2-streaming";
+
 // ============================================================================
 // Public types
 // ============================================================================
@@ -214,57 +219,12 @@ export function withOpenAiRemoteCompactionPreserveData(
 // Input/output filtering for OpenAI compact endpoint
 // ============================================================================
 
-function shouldTrimOpenAiCompactInputItem(item: Record<string, unknown>): boolean {
-	return item.type === "function_call_output" || (item.type === "message" && item.role === "developer");
-}
-
 function shouldKeepOpenAiCompactOutputItem(item: Record<string, unknown>): boolean {
 	if (item.type === "compaction" || item.type === "compaction_summary") return true;
 	if (item.type !== "message") return false;
 	return item.role === "assistant" || item.role === "user";
 }
 
-function trimOpenAiCompactInput(
-	input: Array<Record<string, unknown>>,
-	contextWindow: number,
-	instructions: string,
-): Array<Record<string, unknown>> {
-	const trimmed = [...input];
-	// Per-item serialized sizes are cached and decremented on removal.
-	// Re-stringifying the whole input per popped item was O(N²) in total chars
-	// — hundreds of MB of stringify churn on a 200k-token codex history,
-	// blocking the event loop for seconds (same class as the addOpenAiCallIds
-	// fix above).
-	const sizes = trimmed.map(item => JSON.stringify(item).length);
-	let chars = instructions.length;
-	for (const size of sizes) chars += size;
-	const removeAt = (index: number): void => {
-		chars -= sizes[index] ?? 0;
-		trimmed.splice(index, 1);
-		sizes.splice(index, 1);
-	};
-	while (trimmed.length > 0 && Math.ceil(chars / 4) > contextWindow) {
-		const last = trimmed[trimmed.length - 1];
-		if (last?.type === "function_call_output" || last?.type === "custom_tool_call_output") {
-			const callId = typeof last.call_id === "string" ? last.call_id : undefined;
-			const callType = last.type === "custom_tool_call_output" ? "custom_tool_call" : "function_call";
-			removeAt(trimmed.length - 1);
-			if (callId) {
-				const matchingCallIndex = trimmed.findLastIndex(item => item.type === callType && item.call_id === callId);
-				if (matchingCallIndex >= 0) {
-					removeAt(matchingCallIndex);
-				}
-			}
-			continue;
-		}
-		if (!last || !shouldTrimOpenAiCompactInputItem(last)) {
-			break;
-		}
-		removeAt(trimmed.length - 1);
-	}
-	return trimmed;
-}
-
 // Register every tool-call id in `items` (and the subset using the custom-tool
 // wire shape) into the running sets. The history builder maintains both sets
 // incrementally as native history is appended, so this only scans the
@@ -506,7 +466,10 @@ export async function requestOpenAiRemoteCompaction(
 	const requestModel = resolveOpenAiCompactModel(model);
 	const request: OpenAiRemoteCompactionRequest = {
 		model: requestModel,
-		input: trimOpenAiCompactInput(compactInput, model.contextWindow ?? Number.POSITIVE_INFINITY, instructions),
+		// Send full history to the endpoint - don't trim locally.
+		// The provider handles compression via the compaction endpoint.
+		// Trimming before sending loses assistant messages and thinking blocks.
+		input: compactInput,
 		instructions,
 	};
 	const isAzureOpenAiResponses = (model.remoteCompaction?.api ?? model.api) === "azure-openai-responses";

package/src/proxy.ts

@@ -13,6 +13,12 @@ import {
 	type StopReason,
 	type ToolCall,
 } from "@oh-my-pi/pi-ai";
+import {
+	clearStreamingPartialJson,
+	kStreamingPartialJson,
+	type StreamingPartialJsonCarrier,
+	setStreamingPartialJson,
+} from "@oh-my-pi/pi-ai/utils/block-symbols";
 import { calculateCost } from "@oh-my-pi/pi-catalog/models";
 import { parseStreamingJson, readSseJson } from "@oh-my-pi/pi-utils";
 
@@ -183,8 +189,8 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 			const errorMessage = error instanceof Error ? error.message : String(error);
 			const reason = options.signal?.aborted ? "aborted" : "error";
 			partial.stopReason = reason;
-			scrubPartialJson(partial);
 			partial.errorMessage = errorMessage;
+			scrubPartialJson(partial);
 			stream.push({
 				type: "error",
 				reason,
@@ -202,14 +208,13 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 }
 
 /**
- * Remove the `partialJson` streaming field from any tool-call content blocks
- * that still carry it (e.g. when the stream ended without a `toolcall_end`).
+ * Clear the `partialJson` streaming symbol from any tool-call content blocks
+ * that still carry it (e.g. when the stream ended without a `toolcall_end`), so
+ * the finalized `AssistantMessage` no longer reads as still-streaming.
  */
 function scrubPartialJson(partial: AssistantMessage): void {
 	for (const block of partial.content) {
-		if (block?.type === "toolCall") {
-			delete (block as ToolCall & { partialJson?: string }).partialJson;
-		}
+		if (block?.type === "toolCall") clearStreamingPartialJson(block);
 	}
 }
 
@@ -218,10 +223,10 @@ function scrubPartialJson(partial: AssistantMessage): void {
  *
  * Streaming `partialJson` for in-progress tool calls is accumulated in a
  * side-channel map keyed by `contentIndex` and also written onto the content
- * object (as a typed intersection field) so downstream renderers can read it
- * during streaming. The field is deleted at `toolcall_end` and scrubbed from
- * any remaining blocks at `done`/`error` to guarantee it never leaks into the
- * final `AssistantMessage`.
+ * object as a symbol-keyed field so downstream renderers can read it
+ * during streaming. The field is cleared at `toolcall_end` and scrubbed from any
+ * remaining blocks at `done`/`error` so the finalized `AssistantMessage` never
+ * reads as still-streaming.
  */
 function processProxyEvent(
 	model: Model,
@@ -240,9 +245,10 @@ function processProxyEvent(
 				totalTokens: 0,
 				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 			};
-			delete (partial as { stopReason?: string }).stopReason;
-			delete (partial as { errorMessage?: string }).errorMessage;
-			delete (partial as { duration?: number }).duration;
+			partial.errorMessage = undefined;
+			partial.errorId = undefined;
+			partial.duration = undefined;
+			(partial as { stopReason?: string }).stopReason = undefined;
 			return { type: "start", partial };
 
 		case "text_start":
@@ -315,8 +321,8 @@ function processProxyEvent(
 				id: proxyEvent.id,
 				name: proxyEvent.toolName,
 				arguments: {},
-				partialJson: "",
-			} as ToolCall & { partialJson: string };
+				[kStreamingPartialJson]: "",
+			} as ToolCall & StreamingPartialJsonCarrier;
 			partialJsonByIndex.set(proxyEvent.contentIndex, "");
 			return { type: "toolcall_start", contentIndex: proxyEvent.contentIndex, partial };
 		case "toolcall_delta": {
@@ -325,7 +331,7 @@ function processProxyEvent(
 				const acc = (partialJsonByIndex.get(proxyEvent.contentIndex) ?? "") + proxyEvent.delta;
 				partialJsonByIndex.set(proxyEvent.contentIndex, acc);
 				content.arguments = parseStreamingJson(acc) || {};
-				(content as ToolCall & { partialJson: string }).partialJson = acc;
+				setStreamingPartialJson(content, acc);
 				partial.content[proxyEvent.contentIndex] = { ...content }; // Trigger reactivity
 				return {
 					type: "toolcall_delta",
@@ -341,7 +347,7 @@ function processProxyEvent(
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "toolCall") {
 				partialJsonByIndex.delete(proxyEvent.contentIndex);
-				delete (content as ToolCall & { partialJson?: string }).partialJson;
+				clearStreamingPartialJson(content);
 				return {
 					type: "toolcall_end",
 					contentIndex: proxyEvent.contentIndex,

package/src/types.ts

@@ -633,6 +633,27 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	 */
 	matcherDigest?: (args: unknown) => string | undefined;
 
+	/**
+	 * Surface the target file paths a (potentially partial) streamed call would
+	 * touch, so path-scoped stream matchers (e.g. TTSR `tool:edit(*.ts)` globs)
+	 * can match without a top-level `path`/`paths` argument. Used for tools whose
+	 * wire grammar embeds paths inside the streamed payload (hashline section
+	 * headers, apply_patch envelope markers). Return `undefined` (or an empty
+	 * array) to fall back to the caller's top-level argument scan.
+	 */
+	matcherPaths?: (args: unknown) => readonly string[] | undefined;
+
+	/**
+	 * Per-file projection of a (potentially partial) streamed call, pairing each
+	 * touched file path with the digest of only the lines added to that file.
+	 * Path-scoped stream matchers (TTSR) evaluate each entry in isolation, so a
+	 * scoped rule like `tool:edit(*.ts)` never fires on text that actually
+	 * belongs to a sibling Markdown hunk in a multi-file payload. Takes
+	 * precedence over {@link matcherDigest} + {@link matcherPaths} when present;
+	 * returns `undefined` (or empty) to fall back to the combined hooks.
+	 */
+	matcherEntries?: (args: unknown) => readonly { path: string; digest: string }[] | undefined;
+
 	/** Capability tier declaration used by approval gates. Omitted means "exec". */
 	approval?: ToolApproval;