@@ -2,14 +2,10 @@ import type { FlexibleSchema, StepResult } from "ai";
22 import { dynamicTool, jsonSchema, stepCountIs, streamText } from "ai";
33 import { isApiLogEnabled, logApiEvent } from "./api-log.ts";
44 import {
5- getReasoningDeltaFromStreamChunk,
65 isOpenAIGPT,
76 normalizeOpenAICompatibleToolCallInputs,
8- sanitizeGeminiToolMessages,
97 sanitizeGeminiToolMessagesWithMetadata,
10- stripGPTCommentaryFromHistory,
118 stripOpenAIHistoryTransforms,
12- stripOpenAIItemIdsFromHistory,
139 } from "./history-transforms.ts";
1410 import {
1511 getCacheFamily,
@@ -28,6 +24,7 @@ import {
2824 } from "./turn-context.ts";
2925
3026 export type { ContextPruningMode } from "./turn-context.ts";
27+
3128 import {
3229 mapStreamChunkToTurnEvent,
3330 shouldLogStreamChunk,
@@ -40,18 +37,33 @@ type CoreModel = StreamTextOptions["model"];
4037 type ToolSet = NonNullable<StreamTextOptions["tools"]>;
4138 type ToolEntry = ToolSet extends Record<string, infer T> ? T : never;
4239
43-type StreamTextResult = ReturnType<typeof streamText>;
44-type StreamTextResultFull = StreamTextResult & {
40+type StreamTextResultFull = ReturnType<typeof streamText> & {
4541 fullStream: AsyncIterable<{ type?: string; [key: string]: unknown }>;
4642 response: Promise<{ messages?: CoreMessage[] }>;
4743 };
4844
4945 const MAX_STEPS = 50;
5046
47+// ─── Local helpers ────────────────────────────────────────────────────────────
48+
5149 function isRecord(value: unknown): value is Record<string, unknown> {
5250 return value !== null && typeof value === "object";
5351 }
5452
53+function mergeDeep(
54+ target: Record<string, unknown>,
55+ source: Record<string, unknown>,
56+): Record<string, unknown> {
57+ const output: Record<string, unknown> = { ...target };
58+ for (const key in source) {
59+ const sVal = source[key];
60+ const tVal = target[key];
61+ output[key] =
62+ isRecord(sVal) && isRecord(tVal) ? { ...tVal, ...sVal } : sVal;
63+ }
64+ return output;
65+}
66+
5567 function isZodSchema(s: unknown): boolean {
5668 return s !== null && typeof s === "object" && "_def" in (s as object);
5769 }
@@ -73,24 +85,124 @@ function toCoreTool(def: ToolDef): ReturnType<typeof dynamicTool> {
7385 });
7486 }
7587
76-const mergeDeep = (
77- target: Record<string, unknown>,
78- source: Record<string, unknown>,
79-) => {
80- const output: Record<string, unknown> = { ...target };
81- for (const key in source) {
82- const sVal = source[key];
83- const tVal = target[key];
84- if (isRecord(sVal) && isRecord(tVal)) {
85- output[key] = { ...tVal, ...sVal };
86- } else {
87- output[key] = sVal;
88- }
88+// ─── Message preparation pipeline ────────────────────────────────────────────
89+
90+interface PreparedMessages {
91+ messages: CoreMessage[];
92+ systemPrompt: string | undefined;
93+ /** True if context pruning removed any messages. */
94+ pruned: boolean;
95+ prePruneMessageCount: number;
96+ prePruneTotalBytes: number;
97+ postPruneMessageCount: number;
98+ postPruneTotalBytes: number;
99+}
100+
101+/**
102+ * Apply provider-specific history sanitisation, context pruning, and
103+ * payload compaction. Returns the messages ready to send to the model.
104+ */
105+function prepareMessages(
106+ messages: CoreMessage[],
107+ modelString: string,
108+ toolCount: number,
109+ systemPrompt: string | undefined,
110+ pruningMode: ContextPruningMode,
111+ toolResultPayloadCapBytes: number,
112+ promptCachingEnabled: boolean,
113+): PreparedMessages {
114+ const apiLogOn = isApiLogEnabled();
115+
116+ // 1. Provider-specific sanitisation
117+ const geminiResult = sanitizeGeminiToolMessagesWithMetadata(
118+ messages,
119+ modelString,
120+ toolCount > 0,
121+ );
122+ if (geminiResult.repaired && apiLogOn) {
123+ logApiEvent("gemini tool history repaired", {
124+ modelString,
125+ reason: geminiResult.reason,
126+ repairedFromIndex: geminiResult.repairedFromIndex,
127+ droppedMessageCount: geminiResult.droppedMessageCount,
128+ tailOnlyAffected: geminiResult.tailOnlyAffected,
129+ });
130+ }
131+
132+ const openaiStripped = stripOpenAIHistoryTransforms(
133+ geminiResult.messages,
134+ modelString,
135+ );
136+ if (openaiStripped !== geminiResult.messages && apiLogOn) {
137+ logApiEvent("openai history transforms applied", { modelString });
138+ }
139+
140+ const normalised = normalizeOpenAICompatibleToolCallInputs(
141+ openaiStripped,
142+ modelString,
143+ );
144+ if (normalised !== openaiStripped && apiLogOn) {
145+ logApiEvent("openai-compatible tool input normalized", { modelString });
146+ }
147+
148+ // 2. Context pruning
149+ const preStats = apiLogOn
150+ ? getMessageDiagnostics(normalised)
151+ : getMessageStats(normalised);
152+ if (apiLogOn) logApiEvent("turn context pre-prune", preStats);
153+
154+ const pruned = applyContextPruning(normalised, pruningMode);
155+
156+ const postStats = apiLogOn
157+ ? getMessageDiagnostics(pruned)
158+ : getMessageStats(pruned);
159+ if (apiLogOn) logApiEvent("turn context post-prune", postStats);
160+
161+ // 3. Payload compaction
162+ const compacted = compactToolResultPayloads(
163+ pruned,
164+ toolResultPayloadCapBytes,
165+ );
166+ if (compacted !== pruned && apiLogOn) {
167+ logApiEvent("turn context post-compaction", {
168+ capBytes: toolResultPayloadCapBytes,
169+ diagnostics: getMessageDiagnostics(compacted),
170+ });
89171 }
90- return output;
91-};
92172
173+ // 4. Anthropic prompt caching breakpoints
174+ let finalMessages = compacted;
175+ let finalSystemPrompt = systemPrompt;
93176
177+ const cacheFamily = getCacheFamily(modelString);
178+ if (cacheFamily === "anthropic" && promptCachingEnabled) {
179+ const annotated = annotateAnthropicCacheBreakpoints(
180+ compacted,
181+ systemPrompt,
182+ );
183+ finalMessages = annotated.messages;
184+ finalSystemPrompt = annotated.systemPrompt;
185+ if (apiLogOn)
186+ logApiEvent("Anthropic prompt caching", annotated.diagnostics);
187+ }
188+
189+ const wasPruned =
190+ (pruningMode === "balanced" || pruningMode === "aggressive") &&
191+ (postStats.messageCount < preStats.messageCount ||
192+ postStats.totalBytes < preStats.totalBytes);
193+
194+ return {
195+ messages: finalMessages,
196+ systemPrompt: finalSystemPrompt,
197+ pruned: wasPruned,
198+ prePruneMessageCount: preStats.messageCount,
199+ prePruneTotalBytes: preStats.totalBytes,
200+ postPruneMessageCount: postStats.messageCount,
201+ postPruneTotalBytes: postStats.totalBytes,
202+ };
203+}
204+
205+// ─── runTurn ──────────────────────────────────────────────────────────────────
94206
95207 /**
96208 * Run a single agent turn against the model.
@@ -143,118 +255,63 @@ export async function* runTurn(options: {
143255 const thinkingOpts = thinkingEffort
144256 ? getThinkingProviderOptions(modelString, thinkingEffort)
145257 : null;
146- const reasoningSummaryRequested =
147- isRecord(thinkingOpts) &&
148- isRecord(thinkingOpts.openai) &&
149- typeof thinkingOpts.openai.reasoningSummary === "string";
258+
150259 logApiEvent("turn start", {
151260 modelString,
152261 messageCount: messages.length,
153- reasoningSummaryRequested,
262+ reasoningSummaryRequested:
263+ isRecord(thinkingOpts) &&
264+ isRecord(thinkingOpts.openai) &&
265+ typeof thinkingOpts.openai.reasoningSummary === "string",
154266 pruningMode,
155267 toolResultPayloadCapBytes,
156268 });
157269
158- const geminiSanitizationResult = sanitizeGeminiToolMessagesWithMetadata(
270+ // Prepare messages: sanitize, prune, compact, annotate cache breakpoints
271+ const prepared = prepareMessages(
159272 messages,
160273 modelString,
161- toolCount > 0,
162- );
163- const geminiSanitizedMessages = geminiSanitizationResult.messages;
164- if (geminiSanitizationResult.repaired) {
165- logApiEvent("gemini tool history repaired", {
166- modelString,
167- reason: geminiSanitizationResult.reason,
168- repairedFromIndex: geminiSanitizationResult.repairedFromIndex,
169- droppedMessageCount: geminiSanitizationResult.droppedMessageCount,
170- tailOnlyAffected: geminiSanitizationResult.tailOnlyAffected,
171- });
172- }
173-
174- const openAIStrippedMessages = stripOpenAIHistoryTransforms(
175- geminiSanitizedMessages,
176- modelString,
177- );
178- if (
179- openAIStrippedMessages !== geminiSanitizedMessages &&
180- isApiLogEnabled()
181- ) {
182- logApiEvent("openai history transforms applied", { modelString });
183- }
184-
185- const compatNormalizedMessages = normalizeOpenAICompatibleToolCallInputs(
186- openAIStrippedMessages,
187- modelString,
188- );
189- if (
190- compatNormalizedMessages !== openAIStrippedMessages &&
191- isApiLogEnabled()
192- ) {
193- logApiEvent("openai-compatible tool input normalized", { modelString });
194- }
195-
196- const apiLogOn = isApiLogEnabled();
197- const prePruneDiagnostics = apiLogOn
198- ? getMessageDiagnostics(compatNormalizedMessages)
199- : getMessageStats(compatNormalizedMessages);
200- if (apiLogOn) logApiEvent("turn context pre-prune", prePruneDiagnostics);
201-
202- const prunedMessages = applyContextPruning(
203- compatNormalizedMessages,
274+ toolCount,
275+ systemPrompt,
204276 pruningMode,
277+ toolResultPayloadCapBytes,
278+ promptCachingEnabled,
205279 );
206- const postPruneDiagnostics = apiLogOn
207- ? getMessageDiagnostics(prunedMessages)
208- : getMessageStats(prunedMessages);
209- if (apiLogOn) logApiEvent("turn context post-prune", postPruneDiagnostics);
210-
211- if (
212- (pruningMode === "balanced" || pruningMode === "aggressive") &&
213- (postPruneDiagnostics.messageCount < prePruneDiagnostics.messageCount ||
214- postPruneDiagnostics.totalBytes < prePruneDiagnostics.totalBytes)
215- ) {
280+
281+ if (prepared.pruned) {
216282 yield {
217283 type: "context-pruned",
218- mode: pruningMode,
219- beforeMessageCount: prePruneDiagnostics.messageCount,
220- afterMessageCount: postPruneDiagnostics.messageCount,
284+ mode: pruningMode as "balanced" | "aggressive",
285+ beforeMessageCount: prepared.prePruneMessageCount,
286+ afterMessageCount: prepared.postPruneMessageCount,
221287 removedMessageCount:
222- prePruneDiagnostics.messageCount - postPruneDiagnostics.messageCount,
223- beforeTotalBytes: prePruneDiagnostics.totalBytes,
224- afterTotalBytes: postPruneDiagnostics.totalBytes,
288+ prepared.prePruneMessageCount - prepared.postPruneMessageCount,
289+ beforeTotalBytes: prepared.prePruneTotalBytes,
290+ afterTotalBytes: prepared.postPruneTotalBytes,
225291 removedBytes:
226- prePruneDiagnostics.totalBytes - postPruneDiagnostics.totalBytes,
292+ prepared.prePruneTotalBytes - prepared.postPruneTotalBytes,
227293 };
228294 }
229295
230- const turnMessages = compactToolResultPayloads(
231- prunedMessages,
232- toolResultPayloadCapBytes,
233- );
234- if (turnMessages !== prunedMessages && apiLogOn) {
235- logApiEvent("turn context post-compaction", {
236- capBytes: toolResultPayloadCapBytes,
237- diagnostics: getMessageDiagnostics(turnMessages),
238- });
239- }
240-
296+ // Build provider options (thinking + cache)
241297 const cacheFamily = getCacheFamily(modelString);
242- const googleExplicitCachingCompatible = toolCount === 0 && !systemPrompt;
243298 const cacheOpts = getCachingProviderOptions(modelString, {
244299 enabled: promptCachingEnabled,
245300 openaiRetention: openaiPromptCacheRetention,
246301 googleCachedContent,
247- googleExplicitCachingCompatible,
248- });
249- logApiEvent("prompt caching configured", {
250- enabled: promptCachingEnabled,
251- cacheFamily,
252- cacheOpts,
253- googleExplicitCachingCompatible,
302+ googleExplicitCachingCompatible: toolCount === 0 && !systemPrompt,
254303 });
304+ if (isApiLogEnabled()) {
305+ logApiEvent("prompt caching configured", {
306+ enabled: promptCachingEnabled,
307+ cacheFamily,
308+ cacheOpts,
309+ });
310+ }
255311
256- let mergedProviderOptions = {
312+ const baseProviderOpts = {
257313 ...(thinkingOpts ?? {}),
314+ // GPT models via responses API: opt out of storage, merge thinking opts
258315 ...(isOpenAIGPT(modelString)
259316 ? {
260317 openai: {
@@ -266,27 +323,13 @@ export async function* runTurn(options: {
266323 }
267324 : {}),
268325 };
326+ const mergedProviderOpts = cacheOpts
327+ ? mergeDeep(baseProviderOpts, cacheOpts)
328+ : baseProviderOpts;
269329
270- if (cacheOpts) {
271- mergedProviderOptions = mergeDeep(mergedProviderOptions, cacheOpts);
272- }
273-
274- let finalMessages = turnMessages;
275- let finalSystemPrompt = systemPrompt;
276-
277- if (cacheFamily === "anthropic" && promptCachingEnabled) {
278- const annotated = annotateAnthropicCacheBreakpoints(
279- turnMessages,
280- systemPrompt,
281- );
282- finalMessages = annotated.messages;
283- finalSystemPrompt = annotated.systemPrompt;
284- logApiEvent("Anthropic prompt caching", annotated.diagnostics);
285- }
286-
287- const streamOpts: StreamTextOptions = {
330+ const result = streamText({
288331 model,
289- messages: finalMessages,
332+ messages: prepared.messages,
290333 tools: toolSet,
291334 stopWhen: stepCountIs(MAX_STEPS),
292335 onStepFinish: (step: StepResult<ToolSet>) => {
@@ -299,7 +342,6 @@ export async function* runTurn(options: {
299342 outputTokens += step.usage?.outputTokens ?? 0;
300343 contextTokens = step.usage?.inputTokens ?? contextTokens;
301344 stepCount++;
302-
303345 const s = step as unknown as {
304346 response?: { messages?: CoreMessage[] };
305347 messages?: CoreMessage[];
@@ -308,20 +350,19 @@ export async function* runTurn(options: {
308350 s.response?.messages ?? s.messages ?? partialState.messages;
309351 },
310352 prepareStep: ({ stepNumber }: { stepNumber: number }) => {
353+ // On the last allowed step, disable tools so the model gives a final answer
311354 if (stepNumber >= MAX_STEPS - 1) {
312355 return { activeTools: [] as Array<keyof typeof toolSet> };
313356 }
314357 return undefined;
315358 },
316- ...(finalSystemPrompt ? { system: finalSystemPrompt } : {}),
317- ...(Object.keys(mergedProviderOptions).length > 0
318- ? { providerOptions: mergedProviderOptions }
359+ ...(prepared.systemPrompt ? { system: prepared.systemPrompt } : {}),
360+ ...(Object.keys(mergedProviderOpts).length > 0
361+ ? { providerOptions: mergedProviderOpts }
319362 : {}),
320363 ...(signal ? { abortSignal: signal } : {}),
321364 timeout: { chunkMs: 120_000 },
322- };
323-
324- const result = streamText(streamOpts) as StreamTextResultFull;
365+ } as StreamTextOptions) as StreamTextResultFull;
325366 result.response.catch(() => {});
326367
327368 for await (const chunk of result.fullStream) {
@@ -340,9 +381,8 @@ export async function* runTurn(options: {
340381 if (event) yield event;
341382 }
342383
343- const newMessages = partialState.messages;
344384 logApiEvent("turn complete", {
345- newMessagesCount: newMessages.length,
385+ newMessagesCount: partialState.messages.length,
346386 inputTokens,
347387 outputTokens,
348388 });
@@ -352,7 +392,7 @@ export async function* runTurn(options: {
352392 inputTokens,
353393 outputTokens,
354394 contextTokens,
355- messages: newMessages,
395+ messages: partialState.messages,
356396 };
357397 } catch (err) {
358398 logApiEvent("turn error", err);