@kenkaiiii/gg-agent 5.19.0 → 5.19.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, StopReason, Usage, AssistantMessage } from '@kenkaiiii/gg-ai';
+import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@kenkaiiii/gg-ai';
 import { z } from 'zod';
 
 interface StructuredToolResult {
@@ -136,6 +136,14 @@ interface AgentFollowUpMessageEvent {
     content: Message["content"];
 }
 type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | 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 +188,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 +200,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 +311,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 '@kenkaiiii/gg-ai';
+import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@kenkaiiii/gg-ai';
 import { z } from 'zod';
 
 interface StructuredToolResult {
@@ -136,6 +136,14 @@ interface AgentFollowUpMessageEvent {
     content: Message["content"];
 }
 type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | 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 +188,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 +200,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 +311,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

@@ -189,6 +189,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;
@@ -265,7 +267,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,
@@ -273,6 +279,8 @@ async function* agentLoop(messages, options) {
           });
           messages.length = 0;
           messages.push(...transformed);
+          latestProviderUsage = void 0;
+          usageAnchorIndex = void 0;
         }
         diag("transform_end");
       }
@@ -527,10 +535,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,
@@ -736,6 +751,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 = {
@@ -823,6 +840,7 @@ async function* agentLoop(messages, options) {
       const executionOptions = {
         signal: options.signal,
         maxToolResultChars: options.maxToolResultChars,
+        maxTurnToolResultChars: options.maxTurnToolResultChars,
         toolMap,
         invalidToolArgumentCounts,
         markFatalToolArgumentError
@@ -1059,6 +1077,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) {
@@ -1098,6 +1117,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) {
@@ -1140,6 +1160,34 @@ function capToolResults(toolResults, maxToolResultChars) {
 ` + tail;
   }
 }
+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 headChars = Math.floor(fairShare * 0.7);
+    const tailChars = fairShare - headChars;
+    const omitted = toolResult.content.length - 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) : "");
+  }
+}
 function normalizeToolResult(raw) {
   return typeof raw === "string" ? { content: raw } : raw;
 }