@agentionai/agents 1.1.0 → 1.3.0

package/dist/agents/BaseAgent.d.ts

@@ -12,10 +12,60 @@ export interface BaseAgentConfig extends CommonAgentConfig {
     vendor: AgentVendor;
     vendorConfig?: VendorSpecificConfig;
 }
+/**
+ * Token counts and timing for one or more provider API calls.
+ *
+ * Counts are always present. Timing fields are optional because their
+ * availability depends on the provider and on whether the call was streamed:
+ *
+ * - `totalMs` is always measured (wall clock around the API call).
+ * - `timeToFirstTokenMs` / `generationMs` require either a streamed response
+ *   (measured locally) or a provider that reports its own timings
+ *   (Ollama, llama.cpp).
+ *
+ * When usage from several calls is folded together (a tool-use loop, for
+ * example) the counts and durations are summed and the rates recomputed from
+ * those totals.
+ */
 export type TokenUsage = {
     input_tokens: number;
     output_tokens: number;
     total_tokens: number;
+    /**
+     * Reasoning/thinking tokens, where the provider reports them separately
+     * (OpenAI, Gemini). These are a subset of `output_tokens`, not an addition
+     * to them. Undefined when the provider does not break them out — Anthropic,
+     * for instance, folds thinking tokens into `output_tokens`.
+     */
+    reasoning_tokens?: number;
+    /**
+     * Milliseconds from sending the request to the first token of the response —
+     * prompt upload plus prompt processing.
+     */
+    timeToFirstTokenMs?: number;
+    /** Milliseconds spent generating the response after the first token. */
+    generationMs?: number;
+    /** Total wall-clock milliseconds spent in provider API calls. */
+    totalMs?: number;
+    /**
+     * Prompt processing throughput: `input_tokens` over `timeToFirstTokenMs`.
+     * Undefined when the time to first token is unknown.
+     */
+    inputTokensPerSecond?: number;
+    /**
+     * Generation throughput: `output_tokens` over `generationMs`. Falls back to
+     * `totalMs` when the first-token time is unknown (an unstreamed call), in
+     * which case it is an end-to-end rate rather than a pure generation rate.
+     *
+     * Accurate wherever thinking is streamed, because the first thinking chunk
+     * starts the generation window — verified on Anthropic extended thinking and
+     * on DeepSeek via OpenRouter. It over-reports on OpenAI's Responses API,
+     * which does not stream raw reasoning: there the thinking finishes before the
+     * first visible token, so it lands inside `timeToFirstTokenMs` while its
+     * tokens still count toward `output_tokens`. For the visible-output rate on
+     * that path, divide `output_tokens - reasoning_tokens` by `generationMs`.
+     */
+    outputTokensPerSecond?: number;
 };
 /**
  * The base agent is what the other agents are inheriting from
@@ -33,6 +83,16 @@ export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> ext
     protected vendor: AgentVendor;
     /** The model identifier for this agent */
     protected model: string;
+    /**
+     * Token counts and timings for the most recent `execute()` call, summed
+     * across every provider API call it made (including tool-use follow-ups).
+     * Reset at the start of each execution.
+     */
+    lastTokenUsage?: TokenUsage;
+    /** Start of the API call currently in flight, set by `startTurnTimer()`. */
+    private turnStartedAt?;
+    /** First-token timestamp of the call in flight, set by `markFirstToken()`. */
+    private turnFirstTokenAt?;
     /**
      * An Agent is the primary LLM entity.
      *
@@ -78,5 +138,35 @@ export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> ext
     getTools(): Tool<unknown>[];
     clearHistory(): void;
     protected abstract parseUsage(input: unknown): TokenUsage;
+    /**
+     * Clear accumulated usage. Called at the start of every `execute()` /
+     * `executeStream()` so `lastTokenUsage` describes a single execution.
+     */
+    protected resetTokenUsage(): void;
+    /**
+     * Mark the moment a provider API call is sent. Call this immediately before
+     * every request so the usage folded in afterwards can be timed.
+     */
+    protected startTurnTimer(): void;
+    /**
+     * Mark the arrival of the first token of a streamed response. Subsequent
+     * calls within the same turn are ignored, so it is safe to call on every
+     * chunk.
+     */
+    protected markFirstToken(): void;
+    /**
+     * Fold one API call's usage into `lastTokenUsage`, filling in any timings
+     * the provider did not report from the local turn timer.
+     *
+     * @returns the usage for this single call, with timings and rates filled in —
+     *          `lastTokenUsage` holds the running total across calls.
+     */
+    protected accumulateUsage(usage: TokenUsage): TokenUsage;
+    /**
+     * Add locally measured timings to a provider-parsed usage object. Timings the
+     * provider reported itself (Ollama, llama.cpp) are kept as-is — they exclude
+     * network overhead and are more accurate than anything measured here.
+     */
+    private applyTurnTiming;
 }
 //# sourceMappingURL=BaseAgent.d.ts.map

package/dist/agents/BaseAgent.js

@@ -120,6 +120,113 @@ class BaseAgent extends events_1.default {
     clearHistory() {
         this.history.clear();
     }
+    /**
+     * Clear accumulated usage. Called at the start of every `execute()` /
+     * `executeStream()` so `lastTokenUsage` describes a single execution.
+     */
+    resetTokenUsage() {
+        this.lastTokenUsage = undefined;
+        this.turnStartedAt = undefined;
+        this.turnFirstTokenAt = undefined;
+    }
+    /**
+     * Mark the moment a provider API call is sent. Call this immediately before
+     * every request so the usage folded in afterwards can be timed.
+     */
+    startTurnTimer() {
+        this.turnStartedAt = Date.now();
+        this.turnFirstTokenAt = undefined;
+    }
+    /**
+     * Mark the arrival of the first token of a streamed response. Subsequent
+     * calls within the same turn are ignored, so it is safe to call on every
+     * chunk.
+     */
+    markFirstToken() {
+        if (this.turnStartedAt !== undefined &&
+            this.turnFirstTokenAt === undefined) {
+            this.turnFirstTokenAt = Date.now();
+        }
+    }
+    /**
+     * Fold one API call's usage into `lastTokenUsage`, filling in any timings
+     * the provider did not report from the local turn timer.
+     *
+     * @returns the usage for this single call, with timings and rates filled in —
+     *          `lastTokenUsage` holds the running total across calls.
+     */
+    accumulateUsage(usage) {
+        const timed = this.applyTurnTiming(usage);
+        const previous = this.lastTokenUsage;
+        const merged = previous
+            ? {
+                input_tokens: previous.input_tokens + timed.input_tokens,
+                output_tokens: previous.output_tokens + timed.output_tokens,
+                total_tokens: previous.total_tokens + timed.total_tokens,
+                reasoning_tokens: sumOptional(previous.reasoning_tokens, timed.reasoning_tokens),
+                timeToFirstTokenMs: sumOptional(previous.timeToFirstTokenMs, timed.timeToFirstTokenMs),
+                generationMs: sumOptional(previous.generationMs, timed.generationMs),
+                totalMs: sumOptional(previous.totalMs, timed.totalMs),
+            }
+            : { ...timed };
+        this.lastTokenUsage = withThroughput(merged);
+        this.turnStartedAt = undefined;
+        this.turnFirstTokenAt = undefined;
+        return withThroughput(timed);
+    }
+    /**
+     * Add locally measured timings to a provider-parsed usage object. Timings the
+     * provider reported itself (Ollama, llama.cpp) are kept as-is — they exclude
+     * network overhead and are more accurate than anything measured here.
+     */
+    applyTurnTiming(usage) {
+        if (this.turnStartedAt === undefined)
+            return usage;
+        const now = Date.now();
+        const timed = { ...usage };
+        timed.totalMs ?? (timed.totalMs = now - this.turnStartedAt);
+        if (this.turnFirstTokenAt !== undefined) {
+            timed.timeToFirstTokenMs ?? (timed.timeToFirstTokenMs = this.turnFirstTokenAt - this.turnStartedAt);
+            timed.generationMs ?? (timed.generationMs = now - this.turnFirstTokenAt);
+        }
+        return timed;
+    }
 }
 exports.BaseAgent = BaseAgent;
+/**
+ * Add two values that may each be undefined, returning undefined only when
+ * neither side has a value (so "not reported" never reads as zero).
+ */
+function sumOptional(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return a + b;
+}
+/**
+ * Derive tokens-per-second rates from the counts and durations on a usage
+ * object. Recomputed from totals rather than averaged, so folding several calls
+ * together stays correct.
+ *
+ * Fields that stayed unknown are dropped rather than left as explicit
+ * `undefined`, keeping serialized usage free of empty keys.
+ */
+function withThroughput(usage) {
+    const result = { ...usage };
+    if (result.timeToFirstTokenMs) {
+        result.inputTokensPerSecond =
+            result.input_tokens / (result.timeToFirstTokenMs / 1000);
+    }
+    const outputWindowMs = result.generationMs || result.totalMs;
+    if (outputWindowMs) {
+        result.outputTokensPerSecond =
+            result.output_tokens / (outputWindowMs / 1000);
+    }
+    for (const key of Object.keys(result)) {
+        if (result[key] === undefined)
+            delete result[key];
+    }
+    return result;
+}
 //# sourceMappingURL=BaseAgent.js.map

package/dist/agents/anthropic/ClaudeAgent.d.ts

@@ -49,8 +49,6 @@ type AgentConfig = BaseAgentConfig & {
 export declare class ClaudeAgent extends BaseAgent {
     private client;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/anthropic/ClaudeAgent.js

@@ -43,7 +43,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             ? { authToken: config.apiKey }
             : { apiKey: config.apiKey });
         this.config = {
-            model: config.model || "claude-3-5-haiku-latest",
+            model: config.model || "claude-haiku-4-5",
             maxTokens: config.maxTokens || 1024,
             disableParallelToolUse,
             metadata,
@@ -109,7 +109,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
     async execute(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         // Reset token usage for this execution
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         // Normalise input to a display string for viz reporting
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
@@ -135,6 +135,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         // mid-loop. endExecution() in the finally block enforces limits once.
         this.history.beginExecution();
         try {
+            this.startTurnTimer();
             const response = (await this.client.messages.create(this.buildMessageParams()));
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response);
@@ -167,16 +168,8 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }
     }
     async handleResponse(response) {
-        const usage = this.parseUsage(response.usage);
         // Store token usage for metrics tracking
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += usage.input_tokens;
-            this.lastTokenUsage.output_tokens += usage.output_tokens;
-            this.lastTokenUsage.total_tokens += usage.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = { ...usage };
-        }
+        const usage = this.accumulateUsage(this.parseUsage(response.usage));
         if (response.stop_reason === "max_tokens") {
             const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
@@ -232,6 +225,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 this.addMessageToHistory("user", toolResults);
                 // Continue conversation with tool results
                 try {
+                    this.startTurnTimer();
                     const newResponse = (await this.client.messages.create(this.buildMessageParams()));
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse);
@@ -329,7 +323,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
      */
     async *executeStream(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         if (VizConfig_1.vizConfig.isEnabled()) {
@@ -379,6 +373,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }
     }
     async *streamTurn() {
+        this.startTurnTimer();
         const stream = await this.client.messages.create({
             ...this.buildMessageParams(),
             stream: true,
@@ -416,6 +411,9 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 }
             }
             if (event.type === "content_block_delta") {
+                // First generated content of the turn — thinking counts, since it is
+                // generation time either way.
+                this.markFirstToken();
                 const e = event;
                 const delta = e.delta;
                 const acc = blocks.get(e.index);
@@ -442,19 +440,11 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 }
             }
         }
-        const usage = {
+        this.accumulateUsage({
             input_tokens: inputTokens,
             output_tokens: outputTokens,
             total_tokens: inputTokens + outputTokens,
-        };
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += usage.input_tokens;
-            this.lastTokenUsage.output_tokens += usage.output_tokens;
-            this.lastTokenUsage.total_tokens += usage.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = { ...usage };
-        }
+        });
         if (stopReason === "max_tokens") {
             const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);

package/dist/agents/google/GeminiAgent.d.ts

@@ -29,8 +29,6 @@ export declare class GeminiAgent extends BaseAgent {
     private client;
     private generativeModel;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */
@@ -57,6 +55,7 @@ export declare class GeminiAgent extends BaseAgent {
         promptTokenCount?: number;
         candidatesTokenCount?: number;
         totalTokenCount?: number;
+        thoughtsTokenCount?: number;
     }): TokenUsage;
 }
 export {};

package/dist/agents/google/GeminiAgent.js

@@ -35,7 +35,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         const responseMimeType = config.responseMimeType ?? vendorConfig.responseMimeType;
         const responseSchema = config.responseSchema ?? vendorConfig.responseSchema;
         this.config = {
-            model: config.model || "gemini-2.0-flash",
+            model: config.model || "gemini-flash-latest",
             maxTokens: config.maxTokens || 1024,
             apiKey: config.apiKey,
             temperature: config.temperature,
@@ -164,7 +164,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
     async execute(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         // Reset token usage for this execution
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
@@ -192,6 +192,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             const contents = transformers_1.geminiTransformer.toProvider(this.history.getEntries());
             const systemMessage = this.history.getSystemMessage();
             const tools = this.getToolDefinitionsForGemini();
+            this.startTurnTimer();
             const response = await this.generativeModel.generateContent({
                 contents,
                 systemInstruction: systemMessage,
@@ -241,15 +242,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         const result = response.response;
         // Parse and track usage
         if (result.usageMetadata) {
-            const usage = this.parseUsage(result.usageMetadata);
-            if (this.lastTokenUsage) {
-                this.lastTokenUsage.input_tokens += usage.input_tokens;
-                this.lastTokenUsage.output_tokens += usage.output_tokens;
-                this.lastTokenUsage.total_tokens += usage.total_tokens;
-            }
-            else {
-                this.lastTokenUsage = { ...usage };
-            }
+            this.accumulateUsage(this.parseUsage(result.usageMetadata));
         }
         // Check for finish reason
         const candidate = result.candidates?.[0];
@@ -309,6 +302,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                 const newContents = transformers_1.geminiTransformer.toProvider(this.history.getEntries());
                 const systemMessage = this.history.getSystemMessage();
                 const tools = this.getToolDefinitionsForGemini();
+                this.startTurnTimer();
                 const newResponse = await this.generativeModel.generateContent({
                     contents: newContents,
                     systemInstruction: systemMessage,
@@ -400,10 +394,17 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         return results;
     }
     parseUsage(input) {
+        // Gemini excludes thought tokens from `candidatesTokenCount` but includes
+        // them in `totalTokenCount`. Fold them into `output_tokens` so
+        // input + output === total holds, matching how other providers report.
+        // `thoughtsTokenCount` is sent by thinking models but is not declared on
+        // the legacy SDK's `UsageMetadata`, hence the widened parameter type.
+        const thoughts = input.thoughtsTokenCount;
         return {
             input_tokens: input.promptTokenCount || 0,
-            output_tokens: input.candidatesTokenCount || 0,
+            output_tokens: (input.candidatesTokenCount || 0) + (thoughts || 0),
             total_tokens: input.totalTokenCount || 0,
+            reasoning_tokens: thoughts,
         };
     }
 }

package/dist/agents/mistral/MistralAgent.d.ts

@@ -29,8 +29,6 @@ type AgentConfig = BaseAgentConfig & {
 export declare class MistralAgent extends BaseAgent {
     private client;
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/mistral/MistralAgent.js

@@ -73,7 +73,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
     async execute(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         // Reset token usage for this execution
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
@@ -99,6 +99,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
         this.history.beginExecution();
         try {
             const messages = transformers_1.mistralTransformer.toProvider(this.history.getEntries());
+            this.startTurnTimer();
             const response = await this.client.chat.complete({
                 model: this.config.model,
                 messages: messages,
@@ -147,16 +148,8 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
             throw error;
         }
         const choice = response.choices[0];
-        const usage = this.parseUsage(response.usage);
         // Track token usage
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += usage.input_tokens;
-            this.lastTokenUsage.output_tokens += usage.output_tokens;
-            this.lastTokenUsage.total_tokens += usage.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = { ...usage };
-        }
+        const usage = this.accumulateUsage(this.parseUsage(response.usage));
         if (choice.finishReason === "length") {
             const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
@@ -218,6 +211,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
                 // Continue conversation
                 try {
                     const messages = transformers_1.mistralTransformer.toProvider(this.history.getEntries());
+                    this.startTurnTimer();
                     const newResponse = await this.client.chat.complete({
                         model: this.config.model,
                         messages: messages,

package/dist/agents/model-types.d.ts

@@ -8,19 +8,19 @@
  * You can also provide any custom string for newer models not yet listed.
  * @see https://docs.anthropic.com/en/docs/about-claude/models
  */
-export type ClaudeModel = "claude-opus-4-7" | "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-opus-4-5" | "claude-sonnet-4-5" | "claude-haiku-4-5" | "claude-haiku-4-5-20251001" | (string & Record<never, never>);
+export type ClaudeModel = "claude-opus-5" | "claude-sonnet-5" | "claude-fable-5" | "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-opus-4-5" | "claude-opus-4-5-20251101" | "claude-sonnet-4-5" | "claude-sonnet-4-5-20250929" | "claude-haiku-4-5" | "claude-haiku-4-5-20251001" | (string & Record<never, never>);
 /**
  * Supported Google Gemini models.
  * You can also provide any custom string for newer models not yet listed.
  * @see https://ai.google.dev/gemini-api/docs/models/gemini
  */
-export type GeminiModel = "gemini-flash-latest" | "gemini-flash-lite-latest" | "gemini-3.0-pro" | "gemini-3.0-flash" | "gemini-2.5-flash-lite" | "gemini-2.0-flash-exp" | "gemini-2.0-flash" | "gemini-2.0-flash-lite" | (string & {});
+export type GeminiModel = "gemini-pro-latest" | "gemini-flash-latest" | "gemini-flash-lite-latest" | "gemini-3.6-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.1-flash-lite" | "gemini-3.1-flash-lite-preview" | "gemini-3-pro-preview" | "gemini-3-flash-preview" | "gemini-2.5-pro" | "gemini-2.5-flash" | "gemini-2.5-flash-lite" | "gemini-2.0-flash" | "gemini-2.0-flash-001" | "gemini-2.0-flash-lite" | "gemini-2.0-flash-lite-001" | (string & {});
 /**
  * Supported Mistral models.
  * You can also provide any custom string for newer models not yet listed.
  * @see https://docs.mistral.ai/getting-started/models/
  */
-export type MistralModel = "mistral-large-latest" | "mistral-small-latest" | "ministral-8b-latest" | "ministral-8b-2410" | "ministral-3b-latest" | "ministral-3b-2410" | "codestral-latest" | "codestral-2405" | "mistral-embed" | "mistral-moderation-latest" | "mistral-moderation-2411" | (string & {});
+export type MistralModel = "mistral-large-latest" | "mistral-large-2512" | "mistral-medium-latest" | "mistral-medium-3.5" | "mistral-small-latest" | "mistral-small-2603" | "magistral-small-latest" | "ministral-14b-latest" | "ministral-8b-latest" | "ministral-8b-2512" | "ministral-3b-latest" | "ministral-3b-2512" | "codestral-latest" | "codestral-2508" | "devstral-latest" | "devstral-medium-latest" | "mistral-embed" | "codestral-embed" | "mistral-moderation-latest" | "mistral-moderation-2603" | "mistral-ocr-latest" | (string & {});
 /**
  * Popular Ollama models (locally hosted).
  * You can also provide any custom string for models you have pulled.

package/dist/agents/ollama/OllamaAgent.d.ts

@@ -46,8 +46,6 @@ type OllamaToolDefinition = {
  */
 export declare class OllamaAgent extends BaseAgent {
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/ollama/OllamaAgent.js

@@ -135,7 +135,7 @@ class OllamaAgent extends BaseAgent_1.BaseAgent {
     }
     async execute(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         if (VizConfig_1.vizConfig.isEnabled()) {
@@ -203,6 +203,7 @@ class OllamaAgent extends BaseAgent_1.BaseAgent {
         const messages = transformers_1.ollamaTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
         const options = this.buildOptions();
+        this.startTurnTimer();
         return client.chat({
             model: this.config.model,
             messages,
@@ -214,15 +215,7 @@ class OllamaAgent extends BaseAgent_1.BaseAgent {
     }
     async handleResponse(response) {
         const ollamaResponse = response;
-        const usage = this.parseUsage(ollamaResponse);
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += usage.input_tokens;
-            this.lastTokenUsage.output_tokens += usage.output_tokens;
-            this.lastTokenUsage.total_tokens += usage.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = { ...usage };
-        }
+        const usage = this.accumulateUsage(this.parseUsage(ollamaResponse));
         if (ollamaResponse.done_reason === "length") {
             const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 2048);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
@@ -306,10 +299,19 @@ class OllamaAgent extends BaseAgent_1.BaseAgent {
     }
     parseUsage(input) {
         const response = input;
+        // Ollama reports its own timings in nanoseconds. Time to first token is
+        // model load plus prompt evaluation — everything before generation starts.
+        const toMs = (ns) => ns === undefined ? undefined : ns / 1000000;
+        const timeToFirstTokenMs = response.prompt_eval_duration === undefined
+            ? undefined
+            : toMs((response.load_duration ?? 0) + response.prompt_eval_duration);
         return {
             input_tokens: response.prompt_eval_count ?? 0,
             output_tokens: response.eval_count ?? 0,
             total_tokens: (response.prompt_eval_count ?? 0) + (response.eval_count ?? 0),
+            timeToFirstTokenMs,
+            generationMs: toMs(response.eval_duration),
+            totalMs: toMs(response.total_duration),
         };
     }
 }

package/dist/agents/openai/OpenAiAgent.d.ts

@@ -62,8 +62,6 @@ export declare class OpenAiAgent<M extends OpenAIModel = OpenAIModel> extends Ba
      * caller's model is known.
      */
     protected config: Partial<AgentConfig>;
-    /** Token usage from the last execution (for metrics tracking) */
-    lastTokenUsage?: TokenUsage;
     /** Current visualization event ID for tracking */
     private vizEventId?;
     /** Count of tool calls in current execution */

package/dist/agents/openai/OpenAiAgent.js

@@ -140,7 +140,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
     async execute(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         // Reset token usage for this execution
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
@@ -166,6 +166,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         this.history.beginExecution();
         try {
             const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+            this.startTurnTimer();
             const response = await this.client.responses.create({
                 model: this.config.model,
                 max_output_tokens: this.config.maxTokens,
@@ -220,15 +221,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         }
         // Track token usage if available
         if (response.usage) {
-            const usage = this.parseUsage(response.usage);
-            if (this.lastTokenUsage) {
-                this.lastTokenUsage.input_tokens += usage.input_tokens;
-                this.lastTokenUsage.output_tokens += usage.output_tokens;
-                this.lastTokenUsage.total_tokens += usage.total_tokens;
-            }
-            else {
-                this.lastTokenUsage = { ...usage };
-            }
+            this.accumulateUsage(this.parseUsage(response.usage));
         }
         const toolCalls = response.output.filter((output) => output.type === "function_call");
         // Find the message output (skip reasoning outputs)
@@ -287,6 +280,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 // Continue conversation
                 try {
                     const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+                    this.startTurnTimer();
                     const newResponse = await this.client.responses.create({
                         model: this.config.model,
                         max_output_tokens: this.config.maxTokens,
@@ -404,7 +398,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
      */
     async *executeStream(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         if (VizConfig_1.vizConfig.isEnabled()) {
@@ -458,6 +452,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
     }
     async *streamTurn() {
         const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+        this.startTurnTimer();
         const stream = await this.client.responses.create({
             model: this.config.model,
             max_output_tokens: this.config.maxTokens,
@@ -473,25 +468,19 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         let completedEvent = null;
         for await (const event of stream) {
             if (event.type === "response.output_text.delta") {
+                this.markFirstToken();
                 this.emit(AgentEvent_1.AgentEvent.CHUNK, event.delta);
                 yield { type: "text", content: event.delta };
             }
             if (event.type === "response.reasoning_summary_text.delta") {
+                this.markFirstToken();
                 this.emit(AgentEvent_1.AgentEvent.REASONING_CHUNK, event.delta);
                 yield { type: "reasoning", content: event.delta };
             }
             if (event.type === "response.completed") {
                 completedEvent = event;
                 if (event.response.usage) {
-                    const usage = this.parseUsage(event.response.usage);
-                    if (this.lastTokenUsage) {
-                        this.lastTokenUsage.input_tokens += usage.input_tokens;
-                        this.lastTokenUsage.output_tokens += usage.output_tokens;
-                        this.lastTokenUsage.total_tokens += usage.total_tokens;
-                    }
-                    else {
-                        this.lastTokenUsage = { ...usage };
-                    }
+                    this.accumulateUsage(this.parseUsage(event.response.usage));
                 }
             }
             if (event.type === "response.incomplete") {
@@ -540,6 +529,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             input_tokens: input.input_tokens,
             output_tokens: input.output_tokens,
             total_tokens: input.total_tokens,
+            // Reasoning tokens are already counted inside `output_tokens`.
+            reasoning_tokens: input.output_tokens_details?.reasoning_tokens,
         };
     }
 }

package/dist/agents/openai-compatible/OpenAICompatibleAgent.d.ts

@@ -32,7 +32,6 @@ export type OpenAICompatibleConfig = BaseAgentConfig & {
 export declare abstract class OpenAICompatibleAgent extends BaseAgent {
     protected client: OpenAI;
     protected config: Partial<OpenAICompatibleConfig>;
-    lastTokenUsage?: TokenUsage;
     private vizEventId?;
     private currentToolCallCount;
     constructor(config: OpenAICompatibleConfig & {

package/dist/agents/openai-compatible/OpenAICompatibleAgent.js

@@ -77,7 +77,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
     }
     async execute(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         if (VizConfig_1.vizConfig.isEnabled()) {
@@ -133,6 +133,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
     async callProvider() {
         const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
+        this.startTurnTimer();
         return this.client.chat.completions.create({
             model: this.config.model,
             messages,
@@ -149,15 +150,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         });
     }
     async handleResponse(response) {
-        const usage = this.parseUsage(response);
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += usage.input_tokens;
-            this.lastTokenUsage.output_tokens += usage.output_tokens;
-            this.lastTokenUsage.total_tokens += usage.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = { ...usage };
-        }
+        const usage = this.accumulateUsage(this.parseUsage(response));
         const choice = response.choices[0];
         const message = choice.message;
         if (choice.finish_reason === "length") {
@@ -253,7 +246,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
      */
     async *executeStream(input) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
-        this.lastTokenUsage = undefined;
+        this.resetTokenUsage();
         this.currentToolCallCount = 0;
         const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         if (VizConfig_1.vizConfig.isEnabled()) {
@@ -307,6 +300,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
     async *streamTurn() {
         const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
+        this.startTurnTimer();
         const stream = await this.client.chat.completions.create({
             model: this.config.model,
             messages,
@@ -326,17 +320,22 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         let reasoningContent = "";
         const toolCallAcc = new Map();
         let finishReason = null;
+        let streamUsage;
         for await (const chunk of stream) {
-            // Final chunk carrying usage (choices is empty)
-            if (chunk.choices.length === 0) {
-                if (chunk.usage)
-                    this.accumulateStreamUsage(chunk.usage);
+            // Usage can ride on any chunk: OpenAI sends it on a final choice-less
+            // chunk, OpenRouter attaches it to the last content chunk (the one
+            // carrying finish_reason). Keep the most recent and fold it in once the
+            // stream ends — it is a running total for the turn, not a delta, so
+            // taking the last one covers both layouts without double-counting.
+            if (chunk.usage)
+                streamUsage = chunk.usage;
+            if (chunk.choices.length === 0)
                 continue;
-            }
             const choice = chunk.choices[0];
             finishReason = choice.finish_reason ?? finishReason;
             const delta = choice.delta;
             if (delta.content) {
+                this.markFirstToken();
                 textContent += delta.content;
                 this.emit(AgentEvent_1.AgentEvent.CHUNK, delta.content);
                 yield { type: "text", content: delta.content };
@@ -348,6 +347,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             const deltaExtras = delta;
             const reasoningDelta = (deltaExtras.reasoning ?? deltaExtras.reasoning_content);
             if (reasoningDelta) {
+                this.markFirstToken();
                 // Accumulated as well as yielded: DeepSeek's thinking mode requires the
                 // assistant turn's reasoning to be replayed on the next request, so it
                 // has to reach history rather than only the caller.
@@ -370,6 +370,10 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
                 }
             }
         }
+        // Before any early return below, so a turn that hits the token limit or
+        // continues into a tool call still reports what it spent.
+        if (streamUsage)
+            this.accumulateStreamUsage(streamUsage);
         if (finishReason === "length") {
             const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
@@ -424,19 +428,12 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
     accumulateStreamUsage(usage) {
         if (!usage)
             return;
-        const u = {
+        this.accumulateUsage({
             input_tokens: usage.prompt_tokens ?? 0,
             output_tokens: usage.completion_tokens ?? 0,
             total_tokens: usage.total_tokens ?? 0,
-        };
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += u.input_tokens;
-            this.lastTokenUsage.output_tokens += u.output_tokens;
-            this.lastTokenUsage.total_tokens += u.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = u;
-        }
+            reasoning_tokens: extractReasoningTokens(usage),
+        });
     }
     parseUsage(response) {
         const usage = response.usage;
@@ -444,8 +441,38 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             input_tokens: usage?.prompt_tokens ?? 0,
             output_tokens: usage?.completion_tokens ?? 0,
             total_tokens: usage?.total_tokens ?? 0,
+            reasoning_tokens: extractReasoningTokens(usage),
+            ...extractServerTimings(response),
         };
     }
 }
 exports.OpenAICompatibleAgent = OpenAICompatibleAgent;
+/**
+ * Reasoning token count from `completion_tokens_details`, which reasoning
+ * models (and OpenAI-compatible proxies fronting them) fill in.
+ */
+function extractReasoningTokens(usage) {
+    const details = usage
+        ?.completion_tokens_details;
+    return details?.reasoning_tokens;
+}
+/**
+ * Timings reported by llama.cpp's `llama-server`, which adds a non-standard
+ * `timings` object to its chat completion responses. Absent on every other
+ * OpenAI-compatible server, in which case the durations are measured locally.
+ */
+function extractServerTimings(response) {
+    const timings = response?.timings;
+    if (!timings)
+        return {};
+    const { prompt_ms, predicted_ms } = timings;
+    const totalMs = prompt_ms === undefined && predicted_ms === undefined
+        ? undefined
+        : (prompt_ms ?? 0) + (predicted_ms ?? 0);
+    return {
+        timeToFirstTokenMs: prompt_ms,
+        generationMs: predicted_ms,
+        totalMs,
+    };
+}
 //# sourceMappingURL=OpenAICompatibleAgent.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",