@prestyj/agent 5.7.0 → 5.9.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, StopReason, Usage, AssistantMessage } from '@prestyj/ai';
+import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@prestyj/ai';
 import { z } from 'zod';
 
 interface StructuredToolResult {
@@ -87,9 +87,22 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: number;
 }
+/**
+ * Warning signal emitted when a turn ended on a non-clean stop reason —
+ * `max_tokens` (output clipped at the model's output-token limit), `refusal`,
+ * or a provider-reported `error` stop. Distinguishes a truncated/degraded
+ * completion from a clean one so hosts can warn the user instead of silently
+ * presenting incomplete output as done.
+ */
+interface AgentTruncatedEvent {
+    type: "truncated";
+    reason: "max_tokens" | "refusal" | "provider_error";
+    /** True when the loop injected a continuation and will keep going. */
+    continued: boolean;
+}
 interface AgentRetryEvent {
     type: "retry";
-    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch";
+    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall";
     attempt: number;
     maxAttempts: number;
     delayMs: number;
@@ -135,7 +148,15 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
+interface TransformContextOptions {
+    /** Force a transform after the provider reports context overflow. */
+    force?: boolean;
+    /** Latest successful provider usage, anchored at its assistant message. */
+    usage?: Usage;
+    /** Messages appended after that usage sample and not yet seen by the provider. */
+    pendingMessages: Message[];
+}
 interface AgentOptions {
     provider: StreamOptions["provider"];
     model: string;
@@ -180,6 +201,10 @@ interface AgentOptions {
     clearToolUses?: boolean;
     /** Max characters for a single tool result. Results exceeding this are truncated with a notice. */
     maxToolResultChars?: number;
+    /** Aggregate budget for ALL tool results in one assistant turn. Protects
+     *  against parallel fan-outs injecting huge uncached context in one turn;
+     *  the largest results are trimmed (water-filling) with a re-run notice. */
+    maxTurnToolResultChars?: number;
     /** Max consecutive pause_turn continuations before stopping (default: 5).
      *  Prevents infinite loops when server-side tools keep pausing. */
     maxContinuations?: number;
@@ -188,12 +213,12 @@ interface AgentOptions {
      * the messages array (e.g. compaction, truncation). Return the same array
      * for no-op, or a new array to replace the conversation context.
      *
+     * The latest provider usage is authoritative for the history through its
+     * assistant response. `pendingMessages` contains context appended afterward.
      * When `options.force` is true, the caller should compact unconditionally
      * (e.g. after a context overflow error from the API).
      */
-    transformContext?: (messages: Message[], options?: {
-        force?: boolean;
-    }) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: Message[], options: TransformContextOptions) => Message[] | Promise<Message[]>;
     /**
      * Polled after tool execution completes each turn. Returns user messages
      * to inject into the conversation before the next LLM call (steering).
@@ -299,4 +324,4 @@ declare function isBillingError(err: unknown): boolean;
 declare function isUsageLimitError(err: unknown): boolean;
 declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGenerator<AgentEvent, AgentResult>;
 
-export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };
+export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, StopReason, Usage, AssistantMessage } from '@prestyj/ai';
+import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@prestyj/ai';
 import { z } from 'zod';
 
 interface StructuredToolResult {
@@ -87,9 +87,22 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: number;
 }
+/**
+ * Warning signal emitted when a turn ended on a non-clean stop reason —
+ * `max_tokens` (output clipped at the model's output-token limit), `refusal`,
+ * or a provider-reported `error` stop. Distinguishes a truncated/degraded
+ * completion from a clean one so hosts can warn the user instead of silently
+ * presenting incomplete output as done.
+ */
+interface AgentTruncatedEvent {
+    type: "truncated";
+    reason: "max_tokens" | "refusal" | "provider_error";
+    /** True when the loop injected a continuation and will keep going. */
+    continued: boolean;
+}
 interface AgentRetryEvent {
     type: "retry";
-    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch";
+    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall";
     attempt: number;
     maxAttempts: number;
     delayMs: number;
@@ -135,7 +148,15 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
+interface TransformContextOptions {
+    /** Force a transform after the provider reports context overflow. */
+    force?: boolean;
+    /** Latest successful provider usage, anchored at its assistant message. */
+    usage?: Usage;
+    /** Messages appended after that usage sample and not yet seen by the provider. */
+    pendingMessages: Message[];
+}
 interface AgentOptions {
     provider: StreamOptions["provider"];
     model: string;
@@ -180,6 +201,10 @@ interface AgentOptions {
     clearToolUses?: boolean;
     /** Max characters for a single tool result. Results exceeding this are truncated with a notice. */
     maxToolResultChars?: number;
+    /** Aggregate budget for ALL tool results in one assistant turn. Protects
+     *  against parallel fan-outs injecting huge uncached context in one turn;
+     *  the largest results are trimmed (water-filling) with a re-run notice. */
+    maxTurnToolResultChars?: number;
     /** Max consecutive pause_turn continuations before stopping (default: 5).
      *  Prevents infinite loops when server-side tools keep pausing. */
     maxContinuations?: number;
@@ -188,12 +213,12 @@ interface AgentOptions {
      * the messages array (e.g. compaction, truncation). Return the same array
      * for no-op, or a new array to replace the conversation context.
      *
+     * The latest provider usage is authoritative for the history through its
+     * assistant response. `pendingMessages` contains context appended afterward.
      * When `options.force` is true, the caller should compact unconditionally
      * (e.g. after a context overflow error from the API).
      */
-    transformContext?: (messages: Message[], options?: {
-        force?: boolean;
-    }) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: Message[], options: TransformContextOptions) => Message[] | Promise<Message[]>;
     /**
      * Polled after tool execution completes each turn. Returns user messages
      * to inject into the conversation before the next LLM call (steering).
@@ -299,4 +324,4 @@ declare function isBillingError(err: unknown): boolean;
 declare function isUsageLimitError(err: unknown): boolean;
 declare function agentLoop(messages: Message[], options: AgentOptions): AsyncGenerator<AgentEvent, AgentResult>;
 
-export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };
+export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };

package/dist/index.js

@@ -127,7 +127,7 @@ function classifyOverload(err) {
   if (statusCode === 529 || msg.includes("overloaded") || msg.includes("529")) {
     return "overloaded";
   }
-  if (statusCode === 500 || statusCode === 502 || statusCode === 503 || statusCode === 504 || msg.includes("api_error") || msg.includes("server_error") || msg.includes("internal server error") || msg.includes("bad gateway") || msg.includes("service unavailable") || msg.includes("gateway timeout")) {
+  if (statusCode === 500 || statusCode === 502 || statusCode === 503 || statusCode === 504 || statusCode === 507 || msg.includes("api_error") || msg.includes("server_error") || msg.includes("internal server error") || msg.includes("bad gateway") || msg.includes("service unavailable") || msg.includes("gateway timeout") || msg.includes("exceeded request buffer limit while retrying upstream")) {
     return "provider_error";
   }
   if (isOpaqueProviderMessage(err.message)) {
@@ -188,7 +188,11 @@ function createAbortError() {
 }
 function abortablePromise(promise, signal) {
   if (!signal) return promise;
-  if (signal.aborted) return Promise.reject(createAbortError());
+  if (signal.aborted) {
+    promise.catch(() => {
+    });
+    return Promise.reject(createAbortError());
+  }
   return new Promise((resolve, reject) => {
     let settled = false;
     const cleanup = () => signal.removeEventListener("abort", onAbort);
@@ -233,6 +237,8 @@ async function* agentLoop(messages, options) {
   const maxContinuations = options.maxContinuations ?? 5;
   let toolMap = new Map((options.tools ?? []).map((t) => [t.name, t]));
   const totalUsage = { inputTokens: 0, outputTokens: 0 };
+  let latestProviderUsage;
+  let usageAnchorIndex;
   let turn = 0;
   let hitMaxTurns = false;
   let firstTurn = true;
@@ -242,6 +248,7 @@ async function* agentLoop(messages, options) {
   let overloadRetries = 0;
   let emptyResponseRetries = 0;
   let stallRetries = 0;
+  let runawayToolcallRetries = 0;
   let overflowCompactionAttempts = 0;
   let toolResultTruncationAttempted = false;
   const invalidToolArgumentCounts = /* @__PURE__ */ new Map();
@@ -250,11 +257,16 @@ async function* agentLoop(messages, options) {
   const MAX_OVERLOAD_RETRIES = 10;
   const MAX_EMPTY_RESPONSE_RETRIES = 2;
   const MAX_STALL_RETRIES = 10;
+  const MAX_RUNAWAY_TOOLCALL_RETRIES = 2;
+  const RUNAWAY_TOOLCALL_RETRY_DELAY_MS = 1e3;
   const MAX_OVERFLOW_COMPACTIONS = 2;
   const STALL_RETRIES_BEFORE_NON_STREAMING = 2;
   const STALL_DELAY_MS = 1e3;
   const MIN_PARTIAL_PRESERVE_CHARS = 200;
   const PARTIAL_CONTINUATION_PROMPT = "[Your previous response was cut off by a connection failure. The text above is what was already delivered to the user. Continue exactly from where it stopped \u2014 do not repeat or restart it.]";
+  const MAX_OUTPUT_CONTINUATIONS = 2;
+  const MAX_TOKENS_CONTINUATION_PROMPT = "[Your previous response hit the output-token limit and was cut off. The text above is what was already delivered to the user. Continue exactly from where it stopped \u2014 do not repeat or restart it.]";
+  let maxTokensContinuations = 0;
   const OVERLOAD_BASE_DELAY_MS = 2e3;
   const OVERLOAD_MAX_DELAY_MS = 3e4;
   const STREAM_FIRST_EVENT_TIMEOUT_MS = 45e3;
@@ -309,7 +321,11 @@ async function* agentLoop(messages, options) {
       firstTurn = false;
       if (options.transformContext) {
         diag("transform_start");
-        const transformed = await options.transformContext(messages);
+        const pendingMessages = usageAnchorIndex === void 0 ? [] : messages.slice(usageAnchorIndex + 1);
+        const transformed = await options.transformContext(messages, {
+          usage: latestProviderUsage,
+          pendingMessages
+        });
         if (transformed !== messages) {
           diag("transform_compacted", {
             before: messages.length,
@@ -317,6 +333,8 @@ async function* agentLoop(messages, options) {
           });
           messages.length = 0;
           messages.push(...transformed);
+          latestProviderUsage = void 0;
+          usageAnchorIndex = void 0;
         }
         diag("transform_end");
       }
@@ -577,10 +595,17 @@ async function* agentLoop(messages, options) {
               ...overflowDetails
             });
             try {
-              const compacted = await options.transformContext(messages, { force: true });
+              const pendingMessages = usageAnchorIndex === void 0 ? [] : messages.slice(usageAnchorIndex + 1);
+              const compacted = await options.transformContext(messages, {
+                force: true,
+                usage: latestProviderUsage,
+                pendingMessages
+              });
               if (compacted !== messages && compacted.length < messages.length) {
                 messages.length = 0;
                 messages.push(...compacted);
+                latestProviderUsage = void 0;
+                usageAnchorIndex = void 0;
                 diag("overflow_compact_success", {
                   attempt: overflowCompactionAttempts,
                   messages: messages.length,
@@ -644,11 +669,33 @@ async function* agentLoop(messages, options) {
             provider: options.provider,
             model: options.model
           });
+          if (runawayToolcallRetries < MAX_RUNAWAY_TOOLCALL_RETRIES) {
+            runawayToolcallRetries++;
+            const delayMs = RUNAWAY_TOOLCALL_RETRY_DELAY_MS * runawayToolcallRetries;
+            diag("retry", {
+              reason: "runaway_toolcall",
+              attempt: runawayToolcallRetries,
+              maxAttempts: MAX_RUNAWAY_TOOLCALL_RETRIES,
+              delayMs,
+              ...runawayDetected
+            });
+            yield {
+              type: "retry",
+              reason: "runaway_toolcall",
+              attempt: runawayToolcallRetries,
+              maxAttempts: MAX_RUNAWAY_TOOLCALL_RETRIES,
+              delayMs,
+              silent: true
+            };
+            await abortableSleep(delayMs, options.signal);
+            turn--;
+            continue;
+          }
           const detail = runawayDetected.kind === "chars" ? `${(runawayDetected.chars / 1024).toFixed(0)} KB of tool-call arguments` : `${runawayDetected.events} tool-call delta events`;
           yield {
             type: "error",
             error: new Error(
-              `The model glitched mid-tool-call and produced ${detail} without closing the call. This is usually an upstream model bug \u2014 try the same request again or switch models. Your conversation is preserved.`
+              `The model repeatedly failed to close a tool call after ${MAX_RUNAWAY_TOOLCALL_RETRIES} automatic retries (${detail}). Switch models and retry; your conversation is preserved.`
             )
           };
           break;
@@ -749,6 +796,7 @@ async function* agentLoop(messages, options) {
       }
       overloadRetries = 0;
       stallRetries = 0;
+      runawayToolcallRetries = 0;
       const contentArr = Array.isArray(response.message.content) ? response.message.content : null;
       const hasActionableContent = response.message.content !== "" && contentArr !== null && contentArr.some(
         (p) => p.type === "text" || p.type === "tool_call" || p.type === "server_tool_call"
@@ -786,6 +834,8 @@ async function* agentLoop(messages, options) {
         totalUsage.cacheWrite = (totalUsage.cacheWrite ?? 0) + response.usage.cacheWrite;
       }
       messages.push(response.message);
+      latestProviderUsage = response.usage;
+      usageAnchorIndex = messages.length - 1;
       const completedAt = Date.now();
       const outputTokensPerSecond = providerDurationMs > 0 && response.usage.outputTokens > 0 ? response.usage.outputTokens / (providerDurationMs / 1e3) : void 0;
       const timing = {
@@ -818,6 +868,27 @@ async function* agentLoop(messages, options) {
       consecutivePauses = 0;
       const allToolCalls = extractToolCalls(response.message.content);
       if (response.stopReason !== "tool_use" && allToolCalls.length === 0) {
+        if (response.stopReason === "max_tokens") {
+          if (maxTokensContinuations < MAX_OUTPUT_CONTINUATIONS) {
+            maxTokensContinuations++;
+            diag("max_tokens_continuation", {
+              attempt: maxTokensContinuations,
+              maxAttempts: MAX_OUTPUT_CONTINUATIONS,
+              provider: options.provider,
+              model: options.model
+            });
+            yield { type: "truncated", reason: "max_tokens", continued: true };
+            messages.push({ role: "user", content: MAX_TOKENS_CONTINUATION_PROMPT });
+            continue;
+          }
+          yield { type: "truncated", reason: "max_tokens", continued: false };
+        } else if (response.stopReason === "refusal" || response.stopReason === "error") {
+          yield {
+            type: "truncated",
+            reason: response.stopReason === "refusal" ? "refusal" : "provider_error",
+            continued: false
+          };
+        }
         if (options.getSteeringMessages) {
           const steering = await options.getSteeringMessages();
           if (steering && steering.length > 0) {
@@ -873,6 +944,7 @@ async function* agentLoop(messages, options) {
       const executionOptions = {
         signal: options.signal,
         maxToolResultChars: options.maxToolResultChars,
+        maxTurnToolResultChars: options.maxTurnToolResultChars,
         toolMap,
         invalidToolArgumentCounts,
         markFatalToolArgumentError
@@ -1112,6 +1184,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   }
   const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById);
   capToolResults(toolResults, options.maxToolResultChars);
+  capTurnToolResults(toolResults, options.maxTurnToolResultChars);
   return { toolResults, aborted };
 }
 async function* executeToolCallsParallel(toolCalls, initialToolResults, options) {
@@ -1151,6 +1224,7 @@ async function* executeToolCallsParallel(toolCalls, initialToolResults, options)
   }
   const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById);
   capToolResults(toolResults, options.maxToolResultChars);
+  capTurnToolResults(toolResults, options.maxTurnToolResultChars);
   return { toolResults, aborted };
 }
 function buildToolResults(initialToolResults, toolCalls, resultsById) {
@@ -1181,16 +1255,56 @@ function capToolResults(toolResults, maxToolResultChars) {
   const max = Math.min(maxToolResultChars, hardMax);
   for (const toolResult of toolResults) {
     if (typeof toolResult.content !== "string" || toolResult.content.length <= max) continue;
+    const originalChars = toolResult.content.length;
     const headChars = Math.floor(max * 0.7);
     const tailChars = max - headChars;
     const head = toolResult.content.slice(0, headChars);
     const tail = toolResult.content.slice(-tailChars);
-    const omitted = toolResult.content.length - headChars - tailChars;
+    const omitted = originalChars - headChars - tailChars;
     toolResult.content = head + `
 
 [... ${omitted} characters omitted ...]
 
 ` + tail;
+    toolResult.capped = {
+      originalChars,
+      keptChars: toolResult.content.length,
+      scope: "per-result"
+    };
+  }
+}
+function capTurnToolResults(toolResults, maxTurnToolResultChars) {
+  if (!maxTurnToolResultChars) return;
+  const textResults = toolResults.filter(
+    (toolResult) => typeof toolResult.content === "string"
+  );
+  const total = textResults.reduce((sum, toolResult) => sum + toolResult.content.length, 0);
+  if (total <= maxTurnToolResultChars) return;
+  const bySize = [...textResults].sort((a, b) => a.content.length - b.content.length);
+  let remaining = maxTurnToolResultChars;
+  let left = bySize.length;
+  for (const toolResult of bySize) {
+    const fairShare = Math.floor(remaining / left);
+    left--;
+    if (toolResult.content.length <= fairShare) {
+      remaining -= toolResult.content.length;
+      continue;
+    }
+    remaining -= fairShare;
+    const originalChars = toolResult.content.length;
+    const headChars = Math.floor(fairShare * 0.7);
+    const tailChars = fairShare - headChars;
+    const omitted = originalChars - fairShare;
+    toolResult.content = toolResult.content.slice(0, headChars) + `
+
+[... ${omitted} characters trimmed: this turn's combined tool results exceeded the per-turn budget. Re-run this call alone with narrower filters or offset/limit if you need the omitted content ...]
+
+` + (tailChars > 0 ? toolResult.content.slice(-tailChars) : "");
+    toolResult.capped = {
+      originalChars: toolResult.capped?.originalChars ?? originalChars,
+      keptChars: toolResult.content.length,
+      scope: "per-turn"
+    };
   }
 }
 function normalizeToolResult(raw) {