@agentionai/agents 0.14.0 → 1.0.1

package/README.md

@@ -6,7 +6,7 @@
 
 A comprehensive TypeScript toolkit for building LLM-powered agents with RAG, and multi-agent workflows. No hidden state machines, no forced abstractions—just typed agents, composable graphs, and complete control in a complete toolkit.
 
-**[Documentation](https://docs.agention.ai/)** • **[Examples](https://docs.agention.ai/guide/examples)** • **[GitHub](https://github.com/laurentzuijdwijk/agention-lib)**
+**[Documentation](https://docs.agention.ai/)** • **[Examples](https://docs.agention.ai/guide/examples)** • **[GitHub](https://github.com/laurentzuijdwijk/agention-lib)** • **[npm](https://www.npmjs.com/package/@agentionai/agents)**
 
 ## Quick Start
 
@@ -42,10 +42,11 @@ export ANTHROPIC_API_KEY=your-key-here
 import { ClaudeAgent } from '@agentionai/agents/claude';
 
 const agent = new ClaudeAgent({
-  apiKey: process.env.ANTHROPIC_API_KEY,  // Or pass directly (not recommended for production)
-  model: 'claude-sonnet-4-5',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  id: 'assistant',
   name: 'Assistant',
   description: 'You are a helpful assistant.',
+  model: 'claude-sonnet-4-5',
 });
 
 const response = await agent.execute('What can you help me with?');
@@ -75,6 +76,8 @@ import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
 ## Features
 
 - **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral, plus local models via Ollama and llama.cpp—same interface. Switch models with one line.
+- **Composable Context Management** - Tool result masking (lossless, free) + rolling summarization (auto-firing) + sub-agent delegation (token isolation by architecture).
+- **Streaming** - `executeStream()` on Claude, OpenAI, and all OpenAI-compatible agents. Yields `{ type: "text" | "reasoning" }` chunks; tool calls handled transparently.
 - **Built-In Tools** - Use provider-defined server-side tools (e.g. Anthropic's web search, bash, text editor) alongside your own.
 - **Composable, Not Magical** - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
 - **Multimodal / Vision** - Send images alongside text with a unified `MessageContent[]` API across all providers.
@@ -110,15 +113,50 @@ const weatherTool = new Tool({
 
 const agent = new GeminiAgent({
   apiKey: process.env.GEMINI_API_KEY,
-  model: 'gemini-flash-lite-latest',
+  id: 'weather-agent',
   name: 'Weather Agent',
   description: 'You are a weather assistant.',
+  model: 'gemini-flash-lite-latest',
   tools: [weatherTool],
 });
 
 const response = await agent.execute("What's the weather in Paris?");
 ```
 
+### Context Management
+
+Every agent conversation grows — tool results pile up, turns accumulate, tokens compound. Agention's history plugins keep the context window lean automatically, without manual bookkeeping.
+
+```typescript
+import { toolResultMaskingPlugin, compressionPlugin } from '@agentionai/agents/history/plugins';
+import { History } from '@agentionai/agents/history';
+
+// Mask old tool results at read time — sync, free, lossless
+const maskingPlugin = toolResultMaskingPlugin({ keepRecentResults: 2 });
+
+// Compress old turns into a rolling summary — auto-fires past a token budget
+const history = new History([], { maxTokens: 50000 })
+  .use(maskingPlugin)
+  .use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 8000 } }));
+
+const agent = new ClaudeAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  id: 'researcher',
+  name: 'Researcher',
+  description: 'Research topics thoroughly.',
+  model: 'claude-sonnet-4-6',
+  tools: [searchTool, maskingPlugin.retrieveTool],
+}, history);
+```
+
+| Strategy | Cost | Data loss | Trigger |
+|---|---|---|---|
+| `toolResultMaskingPlugin` | Zero — sync, no LLM calls | None — full content always retrievable | Every `getEntries()` call |
+| `compressionPlugin` | LLM tokens (use a cheap model) | Yes — detail traded for brevity | `autoReduceWhen` threshold or manual `history.reduce()` |
+| `Tool.fromAgent()` | None — structural choice | None in main context (sub-agent history is independent) | Automatic — just wrap an agent as a tool |
+
+[Context Management guide →](https://docs.agention.ai/guide/context-management) · [History API →](https://docs.agention.ai/guide/history)
+
 ### Local Models (Ollama / llama.cpp / OpenAI-compatible servers)
 
 Run models on your own machine — no API key required. Same agent interface as every other provider:
@@ -171,8 +209,7 @@ class VLLMAgent extends OpenAICompatibleAgent {
 Use a provider's own server-side tools (executed by the provider, not locally) alongside your custom tools:
 
 ```typescript
-import { ClaudeAgent } from '@agentionai/agents/claude';
-import { webSearchTool } from '@agentionai/agents/claude';
+import { ClaudeAgent, webSearchTool } from '@agentionai/agents/claude';
 
 const agent = new ClaudeAgent({
   apiKey: process.env.ANTHROPIC_API_KEY,
@@ -186,6 +223,27 @@ const agent = new ClaudeAgent({
 const response = await agent.execute('What happened in the news today?');
 ```
 
+### Streaming
+
+All three major providers support streaming via `executeStream()`, which returns an `AsyncGenerator<StreamChunk>`. Each chunk is `{ type: "text" | "reasoning"; content: string }` — text for visible output, reasoning for internal thinking tokens (DeepSeek R1, Claude extended thinking, OpenAI o-series).
+
+```typescript
+import { ClaudeAgent } from '@agentionai/agents/claude';
+
+const agent = new ClaudeAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  id: 'assistant',
+  name: 'Assistant',
+  description: 'You are a helpful assistant.',
+});
+
+for await (const chunk of agent.executeStream('Tell me a story')) {
+  if (chunk.type === 'text') process.stdout.write(chunk.content);
+}
+```
+
+Tool calls are handled transparently — the generator continues streaming after each round-trip. The same API works across `ClaudeAgent`, `OpenAiAgent`, and `LlamaCppAgent` / any `OpenAICompatibleAgent` subclass.
+
 ### Multi-Agent Pipeline
 
 Chain agents together with different providers and models:
@@ -258,9 +316,10 @@ import * as fs from 'fs';
 
 const agent = new ClaudeAgent({
   apiKey: process.env.ANTHROPIC_API_KEY,
-  model: 'claude-opus-4-6',
+  id: 'vision-agent',
   name: 'VisionAgent',
   description: 'You analyze images.',
+  model: 'claude-opus-4-6',
 });
 
 // Remote image by URL
@@ -296,16 +355,16 @@ JSON Schema + handler pattern. Unique capability: wrap any agent as a tool for d
 
 [Learn more →](https://docs.agention.ai/guide/tools)
 
+### Context Management
+Tool result masking (lossless, free) + rolling summarization (auto-firing) + sub-agent delegation (token isolation by architecture). Composable plugins keep the context window lean automatically.
+
+[Learn more →](https://docs.agention.ai/guide/context-management) · [History API →](https://docs.agention.ai/guide/history)
+
 ### Multimodal / Vision
 Unified `MessageContent[]` interface for images across all providers. URL and base64 images, mix text and images freely in a single call.
 
 [Learn more →](https://docs.agention.ai/guide/multimodal)
 
-### History
-Provider-agnostic, persistent (Redis, file, custom), shareable across agents of different providers.
-
-[Learn more →](https://docs.agention.ai/guide/history)
-
 ### Graph Pipelines
 Compose sequential, parallel, voting, routing, and nested graphs. Mix models and providers freely.
 
@@ -324,10 +383,11 @@ Per-call and per-node token counts, duration metrics, full execution visibility.
 ## Documentation
 
 - **[Getting Started](https://docs.agention.ai/guide/getting-started)** - Installation and first agent
-- **[Quick Start](https://docs.agention.ai/guide/quickstart)** - Build a weather assistant in 5 minutes
+- **[Context Management](https://docs.agention.ai/guide/context-management)** - Token budgets, masking, and compression
 - **[Agents](https://docs.agention.ai/guide/agents)** - Agent configuration and providers
 - **[Tools](https://docs.agention.ai/guide/tools)** - Adding capabilities and agent delegation
 - **[Multimodal / Vision](https://docs.agention.ai/guide/multimodal)** - Sending images across all providers
+- **[History](https://docs.agention.ai/guide/history)** - Conversation persistence and plugins
 - **[Graph Pipelines](https://docs.agention.ai/guide/graph-pipelines)** - Multi-agent workflows
 - **[Vector Stores](https://docs.agention.ai/guide/vector-stores)** - RAG and semantic search
 - **[Examples](https://docs.agention.ai/guide/examples)** - Real-world implementations

package/dist/agents/AgentConfig.d.ts

@@ -73,6 +73,16 @@ export interface ClaudeSpecificConfig {
      * implementation detail that can change.
      */
     authType?: "apiKey" | "oauth";
+    /**
+     * Enable extended thinking by setting a thinking token budget. When set (> 0), the
+     * agent requests `thinking: { type: "enabled", budget_tokens }` and surfaces thinking
+     * tokens as `"reasoning"` chunks from `executeStream()`.
+     *
+     * Constraints (enforced by Anthropic): `budget_tokens` must be ≥ 1024 and strictly less
+     * than `maxTokens`. When enabled, `temperature`/`topP`/`topK` are not sent (the API
+     * requires default sampling with thinking).
+     */
+    thinkingBudgetTokens?: number;
 }
 /**
  * Vendor-specific configuration for OpenAI

package/dist/agents/AgentEvent.d.ts

@@ -10,6 +10,8 @@ export declare class AgentEvent {
     static MAX_RETRIES_EXCEEDED: string;
     static MAX_TOKENS_EXCEEDED: string;
     static TOOL_ERROR: string;
+    static CHUNK: string;
+    static REASONING_CHUNK: string;
     private defaultPrevented;
     constructor(target: BaseAgent<any>);
     preventDefault(): void;

package/dist/agents/AgentEvent.js

@@ -23,4 +23,6 @@ AgentEvent.RETRY = "retry";
 AgentEvent.MAX_RETRIES_EXCEEDED = "max_retries_exceeded";
 AgentEvent.MAX_TOKENS_EXCEEDED = "max_tokens_exceeded";
 AgentEvent.TOOL_ERROR = "tool_error";
+AgentEvent.CHUNK = "chunk";
+AgentEvent.REASONING_CHUNK = "reasoning_chunk";
 //# sourceMappingURL=AgentEvent.js.map

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

@@ -1,8 +1,10 @@
+import { Anthropic } from "@anthropic-ai/sdk";
 import { Message, ToolUnion, Usage } from "@anthropic-ai/sdk/resources";
 import { type ToolDefinition } from "../../tools/Tool";
 import { type BuiltInTool } from "../../tools/BuiltInTool";
 import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
 import { History, MessageContent } from "../../history/History";
+import { StreamChunk } from "../openai-compatible/OpenAICompatibleAgent";
 import { ClaudeModel } from "../model-types";
 type AgentConfig = BaseAgentConfig & {
     apiKey: string;
@@ -22,6 +24,12 @@ type AgentConfig = BaseAgentConfig & {
      * @see lib/tools/BuiltInTool.ts
      */
     builtInTools?: BuiltInTool[];
+    /**
+     * Enable extended thinking with this token budget (≥ 1024, and strictly less than
+     * `maxTokens`). When set, thinking tokens are streamed as `"reasoning"` chunks and
+     * `temperature`/`topP`/`topK` are omitted (required by the API when thinking is on).
+     */
+    thinkingBudgetTokens?: number;
 };
 /**
  * Agent for Anthropic models.
@@ -54,10 +62,56 @@ export declare class ClaudeAgent extends BaseAgent {
      * (server-side) built-in tools, in the shape Anthropic's API expects.
      */
     protected getAllToolDefinitions(): ToolUnion[];
+    /**
+     * Build the common `messages.create` params (shared by `execute()` and
+     * `executeStream()`), excluding `stream`. When extended thinking is enabled
+     * (`thinkingBudgetTokens > 0`) the API requires default sampling, so
+     * `temperature`/`top_p`/`top_k` are omitted in favour of the `thinking` block.
+     */
+    protected buildMessageParams(): {
+        thinking: {
+            type: "enabled";
+            budget_tokens: number;
+        };
+        model: string & ClaudeModel;
+        system: string | undefined;
+        max_tokens: number;
+        messages: Anthropic.Messages.MessageParam[];
+        tools: Anthropic.Messages.ToolUnion[];
+        stop_sequences: string[] | undefined;
+        metadata: Record<string, string> | undefined;
+    } | {
+        temperature: number | undefined;
+        top_p: number | undefined;
+        top_k: number | undefined;
+        model: string & ClaudeModel;
+        system: string | undefined;
+        max_tokens: number;
+        messages: Anthropic.Messages.MessageParam[];
+        tools: Anthropic.Messages.ToolUnion[];
+        stop_sequences: string[] | undefined;
+        metadata: Record<string, string> | undefined;
+    };
     protected process(_input: string): Promise<string>;
     execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: Message): Promise<string>;
     private handleToolUse;
+    /**
+     * Stream a response as an async generator of `StreamChunk` objects.
+     * Yields `{ type: "text" }` for visible output and `{ type: "reasoning" }` for
+     * extended thinking tokens (models with thinking enabled). Tool calls are handled
+     * transparently — the generator continues streaming after each round-trip.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of agent.executeStream("Explain recursion")) {
+     *   if (chunk.type === "text") process.stdout.write(chunk.content);
+     *   else process.stderr.write(`[thinking] ${chunk.content}`);
+     * }
+     * ```
+     */
+    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    private streamTurn;
     protected parseUsage(input: Usage): TokenUsage;
 }
 export {};

package/dist/agents/anthropic/ClaudeAgent.js

@@ -38,6 +38,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         const metadata = config.metadata ?? vendorConfig.metadata;
         const builtInTools = config.builtInTools ?? vendorConfig.builtInTools;
         const authType = config.authType ?? vendorConfig.authType ?? "apiKey";
+        const thinkingBudgetTokens = config.thinkingBudgetTokens ?? vendorConfig.thinkingBudgetTokens;
         this.client = new sdk_1.Anthropic(authType === "oauth"
             ? { authToken: config.apiKey }
             : { apiKey: config.apiKey });
@@ -48,6 +49,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             metadata,
             builtInTools,
             authType,
+            thinkingBudgetTokens,
             apiKey: config.apiKey,
             temperature: config.temperature,
             topP: config.topP,
@@ -70,6 +72,37 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             ...(this.config.builtInTools ?? []),
         ];
     }
+    /**
+     * Build the common `messages.create` params (shared by `execute()` and
+     * `executeStream()`), excluding `stream`. When extended thinking is enabled
+     * (`thinkingBudgetTokens > 0`) the API requires default sampling, so
+     * `temperature`/`top_p`/`top_k` are omitted in favour of the `thinking` block.
+     */
+    buildMessageParams() {
+        const messages = transformers_1.anthropicTransformer.toProvider(this.history.getEntries());
+        const thinkingEnabled = (this.config.thinkingBudgetTokens ?? 0) > 0;
+        return {
+            model: this.config.model,
+            system: this.history.getSystemMessage(),
+            max_tokens: this.config.maxTokens,
+            messages,
+            tools: this.getAllToolDefinitions(),
+            stop_sequences: this.config.stopSequences,
+            metadata: this.config.metadata,
+            ...(thinkingEnabled
+                ? {
+                    thinking: {
+                        type: "enabled",
+                        budget_tokens: this.config.thinkingBudgetTokens,
+                    },
+                }
+                : {
+                    temperature: this.config.temperature,
+                    top_p: this.config.topP,
+                    top_k: this.config.topK,
+                }),
+        };
+    }
     async process(_input) {
         return "";
     }
@@ -102,20 +135,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         // mid-loop. endExecution() in the finally block enforces limits once.
         this.history.beginExecution();
         try {
-            const messages = transformers_1.anthropicTransformer.toProvider(this.history.getEntries());
-            const systemMessage = this.history.getSystemMessage();
-            const response = await this.client.messages.create({
-                model: this.config.model,
-                system: systemMessage,
-                max_tokens: this.config.maxTokens,
-                messages,
-                tools: this.getAllToolDefinitions(),
-                temperature: this.config.temperature,
-                top_p: this.config.topP,
-                top_k: this.config.topK,
-                stop_sequences: this.config.stopSequences,
-                metadata: this.config.metadata,
-            });
+            const response = (await this.client.messages.create(this.buildMessageParams()));
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response);
         }
@@ -212,19 +232,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 this.addMessageToHistory("user", toolResults);
                 // Continue conversation with tool results
                 try {
-                    const messages = transformers_1.anthropicTransformer.toProvider(this.history.getEntries());
-                    const newResponse = await this.client.messages.create({
-                        model: this.config.model,
-                        system: this.history.getSystemMessage(),
-                        max_tokens: this.config.maxTokens,
-                        messages,
-                        tools: this.getAllToolDefinitions(),
-                        temperature: this.config.temperature,
-                        top_p: this.config.topP,
-                        top_k: this.config.topK,
-                        stop_sequences: this.config.stopSequences,
-                        metadata: this.config.metadata,
-                    });
+                    const newResponse = (await this.client.messages.create(this.buildMessageParams()));
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse);
                 }
@@ -305,6 +313,206 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }));
         return results;
     }
+    /**
+     * Stream a response as an async generator of `StreamChunk` objects.
+     * Yields `{ type: "text" }` for visible output and `{ type: "reasoning" }` for
+     * extended thinking tokens (models with thinking enabled). Tool calls are handled
+     * transparently — the generator continues streaming after each round-trip.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of agent.executeStream("Explain recursion")) {
+     *   if (chunk.type === "text") process.stdout.write(chunk.content);
+     *   else process.stderr.write(`[thinking] ${chunk.content}`);
+     * }
+     * ```
+     */
+    async *executeStream(input) {
+        this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
+        this.lastTokenUsage = undefined;
+        this.currentToolCallCount = 0;
+        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
+        if (VizConfig_1.vizConfig.isEnabled()) {
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "anthropic", inputPreview);
+        }
+        if (this.history.transient) {
+            this.history.clear();
+            this.addSystemMessage(this.getSystemMessage());
+        }
+        if (typeof input === "string") {
+            this.addTextToHistory("user", input);
+        }
+        else {
+            this.addMessageToHistory("user", input);
+        }
+        this.history.setSessionAnchor();
+        this.history.beginExecution();
+        try {
+            yield* this.streamTurn();
+        }
+        catch (error) {
+            if (error instanceof sdk_1.APIError) {
+                const apiError = new AgentError_1.ApiError(`Anthropic API error: ${error.message}`, error.status, error);
+                this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, error.status === 429);
+                    this.vizEventId = undefined;
+                }
+                throw apiError;
+            }
+            // Errors raised inside streamTurn() (e.g. MaxTokensExceededError) are
+            // already emitted and viz-reported at the throw site — preserve their
+            // type rather than re-wrapping them in a generic ExecutionError.
+            if (error instanceof AgentError_1.AgentError) {
+                throw error;
+            }
+            const executionError = new AgentError_1.ExecutionError(`Anthropic error: ${error instanceof Error ? error.message : "Unknown error"}`);
+            this.emit(AgentEvent_1.AgentEvent.ERROR, executionError);
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentError(this.vizEventId, "ExecutionError", executionError.message, false);
+                this.vizEventId = undefined;
+            }
+            throw executionError;
+        }
+        finally {
+            this.history.endExecution();
+        }
+    }
+    async *streamTurn() {
+        const stream = await this.client.messages.create({
+            ...this.buildMessageParams(),
+            stream: true,
+        });
+        const blocks = new Map();
+        let textContent = "";
+        let stopReason = null;
+        let inputTokens = 0;
+        let outputTokens = 0;
+        for await (const event of stream) {
+            if (event.type === "message_start") {
+                const e = event;
+                inputTokens = e.message.usage.input_tokens;
+                outputTokens = e.message.usage.output_tokens;
+            }
+            if (event.type === "message_delta") {
+                const e = event;
+                stopReason = e.delta.stop_reason ?? stopReason;
+                outputTokens += e.usage?.output_tokens ?? 0;
+            }
+            if (event.type === "content_block_start") {
+                const e = event;
+                const block = e.content_block;
+                if (block.type === "tool_use") {
+                    blocks.set(e.index, { kind: "tool_use", id: block.id, name: block.name, inputJson: "" });
+                }
+                else if (block.type === "text") {
+                    blocks.set(e.index, { kind: "text", text: "" });
+                }
+                else if (block.type === "thinking") {
+                    blocks.set(e.index, { kind: "thinking", thinking: "", signature: "" });
+                }
+                else if (block.type === "redacted_thinking") {
+                    blocks.set(e.index, { kind: "redacted_thinking", data: block.data });
+                }
+            }
+            if (event.type === "content_block_delta") {
+                const e = event;
+                const delta = e.delta;
+                const acc = blocks.get(e.index);
+                if (delta.type === "text_delta") {
+                    textContent += delta.text;
+                    if (acc?.kind === "text")
+                        acc.text += delta.text;
+                    this.emit(AgentEvent_1.AgentEvent.CHUNK, delta.text);
+                    yield { type: "text", content: delta.text };
+                }
+                else if (delta.type === "thinking_delta") {
+                    if (acc?.kind === "thinking")
+                        acc.thinking += delta.thinking;
+                    this.emit(AgentEvent_1.AgentEvent.REASONING_CHUNK, delta.thinking);
+                    yield { type: "reasoning", content: delta.thinking };
+                }
+                else if (delta.type === "signature_delta") {
+                    if (acc?.kind === "thinking")
+                        acc.signature += delta.signature;
+                }
+                else if (delta.type === "input_json_delta") {
+                    if (acc?.kind === "tool_use")
+                        acc.inputJson += delta.partial_json;
+                }
+            }
+        }
+        const usage = {
+            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);
+            this.emit(AgentEvent_1.AgentEvent.ERROR, error);
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentError(this.vizEventId, "MaxTokensExceededError", error.message, false);
+                this.vizEventId = undefined;
+            }
+            throw error;
+        }
+        // Rebuild the assistant turn in stream order (thinking → text → tool_use).
+        const orderedBlocks = Array.from(blocks.entries())
+            .sort(([a], [b]) => a - b)
+            .map(([, b]) => {
+            switch (b.kind) {
+                case "thinking":
+                    return { type: "thinking", thinking: b.thinking, signature: b.signature };
+                case "redacted_thinking":
+                    return { type: "redacted_thinking", data: b.data };
+                case "tool_use":
+                    return {
+                        type: "tool_use",
+                        id: b.id,
+                        name: b.name,
+                        input: JSON.parse(b.inputJson || "{}"),
+                    };
+                case "text":
+                    return { type: "text", text: b.text, citations: [] };
+            }
+        });
+        // Fallback: preserve streamed text even if no text block start was observed.
+        if (textContent && !orderedBlocks.some((b) => b.type === "text")) {
+            orderedBlocks.push({ type: "text", text: textContent, citations: [] });
+        }
+        const toolUseBlocks = orderedBlocks.filter((b) => b.type === "tool_use");
+        if (stopReason === "tool_use" && toolUseBlocks.length > 0) {
+            this.emit(AgentEvent_1.AgentEvent.TOOL_USE, orderedBlocks);
+            this.currentToolCallCount += toolUseBlocks.length;
+            const assistantEntry = transformers_1.anthropicTransformer.fromProviderContent("assistant", orderedBlocks);
+            this.addToHistory(assistantEntry);
+            const toolResults = await this.handleToolUse(orderedBlocks);
+            this.addMessageToHistory("user", toolResults);
+            yield* this.streamTurn();
+        }
+        else {
+            const assistantEntry = transformers_1.anthropicTransformer.fromProviderContent("assistant", orderedBlocks);
+            this.addToHistory(assistantEntry);
+            this.emit(AgentEvent_1.AgentEvent.DONE, { content: textContent }, this.lastTokenUsage);
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentComplete(this.vizEventId, {
+                    input: this.lastTokenUsage?.input_tokens || 0,
+                    output: this.lastTokenUsage?.output_tokens || 0,
+                    total: this.lastTokenUsage?.total_tokens || 0,
+                }, "end_turn", this.currentToolCallCount > 0, this.currentToolCallCount, textContent);
+                this.vizEventId = undefined;
+            }
+        }
+    }
     parseUsage(input) {
         return {
             input_tokens: input.input_tokens,

package/dist/agents/google/GeminiAgent.js

@@ -118,7 +118,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                     items: this.convertPropertyToSchema(prop.items),
                     description,
                 };
-            case "object":
+            case "object": {
                 const objProps = {};
                 if (prop.properties) {
                     const subProps = prop.properties;
@@ -132,6 +132,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                     description,
                     required: prop.required,
                 };
+            }
             default:
                 return { type: generative_ai_1.SchemaType.STRING, description };
         }

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

@@ -2,6 +2,7 @@ import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
 import { History, MessageContent } from "../../history/History";
 import { Tool, Response, ResponseUsage } from "openai/resources/responses/responses";
 import { OpenAIModel } from "../model-types";
+import { StreamChunk } from "../openai-compatible/OpenAICompatibleAgent";
 type AgentConfig = BaseAgentConfig & {
     apiKey: string;
     model?: OpenAIModel;
@@ -42,6 +43,20 @@ export declare class OpenAiAgent extends BaseAgent {
     execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: Response): Promise<string>;
     private handleToolUse;
+    /**
+     * Stream a response as an async generator of `StreamChunk` objects.
+     * Yields `{ type: "text" }` for visible output and `{ type: "reasoning" }` for
+     * reasoning summary tokens (o-series models). Tool calls are handled transparently.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of agent.executeStream("Explain recursion")) {
+     *   if (chunk.type === "text") process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    private streamTurn;
     protected parseUsage(input: ResponseUsage): TokenUsage;
 }
 export {};