@prestyj/agent 5.6.0 → 5.8.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 {
@@ -49,11 +49,26 @@ interface AgentToolCallEndEvent {
     isError: boolean;
     durationMs: number;
 }
+interface AgentTurnTiming {
+    /** Logical turn start, before context transforms or provider retries. Unix epoch milliseconds. */
+    startedAt: number;
+    /** First provider event, or full-response arrival for non-streaming fallback. */
+    firstProviderEventAt?: number;
+    /** Successful provider response completion. Unix epoch milliseconds. */
+    completedAt: number;
+    /** Time spent awaiting provider attempts, including failed attempts but excluding retry backoff. */
+    providerDurationMs: number;
+    /** Time from logical turn start to the first provider event. */
+    ttftMs?: number;
+    /** Output tokens divided by total provider duration. Omitted when no rate is measurable. */
+    outputTokensPerSecond?: number;
+}
 interface AgentTurnEndEvent {
     type: "turn_end";
     turn: number;
     stopReason: StopReason;
     usage: Usage;
+    timing: AgentTurnTiming;
 }
 interface AgentDoneEvent {
     type: "agent_done";
@@ -121,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;
@@ -129,6 +152,8 @@ interface AgentOptions {
     priorMessages?: Message[];
     tools?: AgentTool[];
     serverTools?: ServerToolDefinition[];
+    /** Control whether tools may/must be called, or select a named tool when supported. */
+    toolChoice?: StreamOptions["toolChoice"];
     maxTurns?: number;
     maxTokens?: number;
     temperature?: number;
@@ -163,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;
@@ -171,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).
@@ -282,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 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 {
@@ -49,11 +49,26 @@ interface AgentToolCallEndEvent {
     isError: boolean;
     durationMs: number;
 }
+interface AgentTurnTiming {
+    /** Logical turn start, before context transforms or provider retries. Unix epoch milliseconds. */
+    startedAt: number;
+    /** First provider event, or full-response arrival for non-streaming fallback. */
+    firstProviderEventAt?: number;
+    /** Successful provider response completion. Unix epoch milliseconds. */
+    completedAt: number;
+    /** Time spent awaiting provider attempts, including failed attempts but excluding retry backoff. */
+    providerDurationMs: number;
+    /** Time from logical turn start to the first provider event. */
+    ttftMs?: number;
+    /** Output tokens divided by total provider duration. Omitted when no rate is measurable. */
+    outputTokensPerSecond?: number;
+}
 interface AgentTurnEndEvent {
     type: "turn_end";
     turn: number;
     stopReason: StopReason;
     usage: Usage;
+    timing: AgentTurnTiming;
 }
 interface AgentDoneEvent {
     type: "agent_done";
@@ -121,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;
@@ -129,6 +152,8 @@ interface AgentOptions {
     priorMessages?: Message[];
     tools?: AgentTool[];
     serverTools?: ServerToolDefinition[];
+    /** Control whether tools may/must be called, or select a named tool when supported. */
+    toolChoice?: StreamOptions["toolChoice"];
     maxTurns?: number;
     maxTokens?: number;
     temperature?: number;
@@ -163,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;
@@ -171,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).
@@ -282,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 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

@@ -7,7 +7,8 @@ import {
   stream,
   EventStream,
   EZCoderAIError,
-  isHardBillingMessage
+  isHardBillingMessage,
+  redactValue
 } from "@prestyj/ai";
 var DEFAULT_MAX_TURNS = 300;
 var _diagFn = null;
@@ -126,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)) {
@@ -232,6 +233,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;
@@ -268,10 +271,14 @@ async function* agentLoop(messages, options) {
   const initialHardTimeoutMs = isSakana ? STREAM_THINKING_HARD_TIMEOUT_MS : STREAM_HARD_TIMEOUT_MS;
   const MAX_TOOLCALL_DELTA_CHARS = 1e6;
   const MAX_TOOLCALL_DELTA_EVENTS = 2e4;
+  let logicalTurnStartedAt = 0;
+  let firstProviderEventAt;
+  let providerDurationMs = 0;
   try {
     while (turn < maxTurns) {
       options.signal?.throwIfAborted();
       turn++;
+      if (logicalTurnStartedAt === 0) logicalTurnStartedAt = Date.now();
       toolMap = new Map((options.tools ?? []).map((t) => [t.name, t]));
       if (_diagFn) {
         let msgChars = 0;
@@ -304,7 +311,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,
@@ -312,6 +323,8 @@ async function* agentLoop(messages, options) {
           });
           messages.length = 0;
           messages.push(...transformed);
+          latestProviderUsage = void 0;
+          usageAnchorIndex = void 0;
         }
         diag("transform_end");
       }
@@ -321,6 +334,7 @@ async function* agentLoop(messages, options) {
       let idleTimer = null;
       let hardTimer = null;
       let idleTimedOut = false;
+      let providerAttemptStartedAt;
       let streamEventCount = 0;
       let lastEventTime = Date.now();
       let streamCallStart = Date.now();
@@ -366,12 +380,14 @@ async function* agentLoop(messages, options) {
       try {
         diag("stream_call", { nonStreaming: useNonStreamingFallback });
         streamCallStart = Date.now();
+        providerAttemptStartedAt = streamCallStart;
         const result = stream({
           provider: options.provider,
           model: options.model,
           messages,
           tools: options.tools,
           serverTools: options.serverTools,
+          toolChoice: options.toolChoice,
           webSearch: options.webSearch,
           maxTokens: options.maxTokens,
           temperature: options.temperature,
@@ -414,6 +430,7 @@ async function* agentLoop(messages, options) {
             maxConsumerLagMs = consumerLag;
           }
           streamEventCount++;
+          if (firstProviderEventAt === void 0) firstProviderEventAt = pullTime;
           eventTypeCounts[event.type] = (eventTypeCounts[event.type] ?? 0) + 1;
           lastEventType = event.type;
           if ((event.type === "text_delta" || event.type === "server_toolcall" || event.type === "toolcall_delta") && !hasReceivedEvent) {
@@ -506,6 +523,7 @@ async function* agentLoop(messages, options) {
           eventTypes: eventTypeCounts
         });
         response = await abortablePromise(result.response, streamController.signal);
+        if (firstProviderEventAt === void 0) firstProviderEventAt = Date.now();
       } catch (err) {
         if (streamController.signal.aborted) closeIterator(streamIterator);
         const errMsg = err instanceof Error ? err.message : String(err);
@@ -567,10 +585,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,
@@ -730,6 +755,9 @@ async function* agentLoop(messages, options) {
         });
         throw err;
       } finally {
+        if (providerAttemptStartedAt !== void 0) {
+          providerDurationMs += Date.now() - providerAttemptStartedAt;
+        }
         if (idleTimer) clearTimeout(idleTimer);
         if (hardTimer) clearTimeout(hardTimer);
         options.signal?.removeEventListener("abort", forwardAbort);
@@ -773,11 +801,29 @@ 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 = {
+        startedAt: logicalTurnStartedAt,
+        ...firstProviderEventAt !== void 0 ? {
+          firstProviderEventAt,
+          ttftMs: Math.max(0, firstProviderEventAt - logicalTurnStartedAt)
+        } : {},
+        completedAt,
+        providerDurationMs,
+        ...outputTokensPerSecond !== void 0 ? { outputTokensPerSecond } : {}
+      };
+      logicalTurnStartedAt = 0;
+      firstProviderEventAt = void 0;
+      providerDurationMs = 0;
       yield {
         type: "turn_end",
         turn,
         stopReason: response.stopReason,
-        usage: response.usage
+        usage: response.usage,
+        timing
       };
       if (response.stopReason === "pause_turn") {
         consecutivePauses++;
@@ -844,6 +890,7 @@ async function* agentLoop(messages, options) {
       const executionOptions = {
         signal: options.signal,
         maxToolResultChars: options.maxToolResultChars,
+        maxTurnToolResultChars: options.maxTurnToolResultChars,
         toolMap,
         invalidToolArgumentCounts,
         markFatalToolArgumentError
@@ -961,8 +1008,8 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
         ctx.signal
       );
       const normalized = normalizeToolResult(raw);
-      resultContent = normalized.content;
-      details = normalized.details;
+      resultContent = redactValue(normalized.content);
+      details = redactValue(normalized.details);
       for (const key of options.invalidToolArgumentCounts.keys()) {
         if (key.startsWith(`${toolCall.name}:`)) options.invalidToolArgumentCounts.delete(key);
       }
@@ -990,10 +1037,12 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
           );
         }
       } else {
-        resultContent = err instanceof Error ? err.message : String(err);
+        resultContent = redactValue(err instanceof Error ? err.message : String(err));
       }
     }
   }
+  resultContent = redactValue(resultContent);
+  details = redactValue(details);
   const durationMs = Date.now() - startTime;
   pushEvent({
     type: "tool_call_end",
@@ -1081,6 +1130,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) {
@@ -1120,6 +1170,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) {
@@ -1162,6 +1213,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;
 }