@prestyj/agent 5.6.0 → 5.7.0

package/dist/index.d.cts

@@ -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";
@@ -129,6 +144,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;
@@ -282,4 +299,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, agentLoop, isAbortError, isBillingError, isContextOverflow, isUsageLimitError, setStreamDiagnostic };

package/dist/index.d.ts

@@ -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";
@@ -129,6 +144,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;
@@ -282,4 +299,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, 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;
@@ -268,10 +269,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;
@@ -321,6 +326,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 +372,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 +422,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 +515,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);
@@ -730,6 +740,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 +786,27 @@ async function* agentLoop(messages, options) {
         totalUsage.cacheWrite = (totalUsage.cacheWrite ?? 0) + response.usage.cacheWrite;
       }
       messages.push(response.message);
+      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++;
@@ -961,8 +990,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 +1019,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",