@nebulaos/core 0.1.1

package/dist/agent/Agent.js

@@ -0,0 +1,861 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const index_js_1 = require("./skills/index.js");
+const node_crypto_1 = require("node:crypto");
+const index_js_2 = require("../logger/index.js");
+const agent_logger_js_1 = require("../logger/agent-logger.js");
+const index_js_3 = require("../tracing/index.js");
+const BaseAgent_js_1 = require("./BaseAgent.js");
+const index_js_4 = require("../execution-context/index.js");
+function generateCorrelationId() {
+    return `exec_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+const MAX_MESSAGE_FILE_BYTES_DEFAULT = 10 * 1024 * 1024; // 10MB
+// =============================================================================
+// Agent Class
+// =============================================================================
+class Agent extends BaseAgent_js_1.BaseAgent {
+    config;
+    resolvedInstructions;
+    requestInterceptors = [];
+    responseInterceptors = [];
+    // @ts-ignore: used for side-effects (binding events)
+    loggerAdapter;
+    skillsInitialized = false;
+    httpClient;
+    constructor(config) {
+        super(config.id, config.name, config.piiMasker, config.memory);
+        this.config = config;
+        this.requestInterceptors = config.interceptors?.request || [];
+        this.responseInterceptors = config.interceptors?.response || [];
+        // Setup Logger
+        const logger = config.logger || new index_js_2.ConsoleLogger(config.logLevel || "error");
+        this.loggerAdapter = new agent_logger_js_1.AgentLogger(this, logger);
+    }
+    /**
+     * Sets the HTTP client for tool execution context.
+     * This is typically called by the client package with InstrumentedHttpClient.
+     */
+    setHttpClient(client) {
+        this.httpClient = client;
+    }
+    // ==========================================================================
+    // Skills Initialization
+    // ==========================================================================
+    async initializeSkills() {
+        if (this.skillsInitialized)
+            return;
+        const skills = this.config.skills || [];
+        if (skills.length === 0) {
+            this.skillsInitialized = true;
+            return;
+        }
+        // Initialize each skill
+        for (const skill of skills) {
+            if (!(0, index_js_1.isSkill)(skill)) {
+                throw new Error(`Invalid skill: object does not implement ISkill interface`);
+            }
+            // Call optional initialize method
+            if (skill.initialize) {
+                await skill.initialize();
+            }
+            // Get tools from skill
+            const skillTools = await Promise.resolve(skill.getTools());
+            // Merge skill tools with existing tools
+            this.config.tools = [...(this.config.tools || []), ...skillTools];
+        }
+        this.skillsInitialized = true;
+    }
+    // ==========================================================================
+    // Instructions
+    // ==========================================================================
+    async resolveInstructions() {
+        if (this.resolvedInstructions !== undefined)
+            return this.resolvedInstructions;
+        let baseInstructions = "";
+        if (typeof this.config.instructions === "string") {
+            baseInstructions = this.config.instructions;
+        }
+        else if (this.isInstruction(this.config.instructions)) {
+            baseInstructions = await this.config.instructions.resolve();
+        }
+        // Append skill instructions if any
+        const skills = this.config.skills || [];
+        const skillInstructions = [];
+        for (const skill of skills) {
+            if (skill.getInstructions) {
+                const instructions = await Promise.resolve(skill.getInstructions());
+                if (instructions) {
+                    skillInstructions.push(instructions);
+                }
+            }
+        }
+        if (skillInstructions.length > 0) {
+            this.resolvedInstructions = [baseInstructions, ...skillInstructions].filter(Boolean).join("\n\n");
+        }
+        else {
+            this.resolvedInstructions = baseInstructions;
+        }
+        return this.resolvedInstructions;
+    }
+    isInstruction(obj) {
+        return obj && typeof obj.resolve === "function";
+    }
+    clearInstructionsCache() {
+        this.resolvedInstructions = undefined;
+    }
+    // ==========================================================================
+    // Memory
+    // ==========================================================================
+    async addMessage(message, ctx) {
+        this.memory = this.config.memory;
+        await this.config.memory.addMessage(message, ctx);
+    }
+    async getMessagesWithContext(ctx) {
+        const instructions = await this.resolveInstructions();
+        const msgs = await this.config.memory.getMessages(ctx);
+        // Ensure system prompt is present if instructions exist
+        if (instructions && !msgs.some((m) => m.role === "system")) {
+            msgs.unshift({ role: "system", content: instructions });
+        }
+        return msgs;
+    }
+    async execute(arg1 = {}, arg2 = {}) {
+        // Parse input: can be string, ContentPart[], or undefined
+        const input = typeof arg1 === "string" || Array.isArray(arg1) ? arg1 : undefined;
+        const options = typeof arg1 === "string" || Array.isArray(arg1) ? (arg2 ?? {}) : (arg1 ?? {});
+        const startTime = Date.now();
+        const correlationId = generateCorrelationId();
+        const maxSteps = options.maxSteps ?? this.config.maxSteps ?? 10;
+        // Create memory context for partitioning
+        const memoryCtx = options.memoryKey
+            ? { memoryKey: options.memoryKey }
+            : undefined;
+        const toolExecutions = [];
+        const collectedToolCalls = [];
+        let llmCalls = 0;
+        let truncated = false;
+        let totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        const runWithExecutionContext = async () => index_js_3.Tracing.withSpan({
+            kind: "agent",
+            name: `agent:${this.name}`,
+            correlationId,
+            executionId: options.executionId,
+            data: { agentName: this.name, input },
+        }, async (agentSpan) => {
+            this.emit("agent:execution:start", {
+                correlationId,
+                executionId: options.executionId,
+                data: {
+                    agentId: this.id,
+                    agentName: this.name,
+                    input,
+                },
+            });
+            try {
+                // Initialize skills if not already initialized
+                await this.initializeSkills();
+                if (input) {
+                    await this.addMessage({ role: "user", content: input }, memoryCtx);
+                }
+                let step = 0;
+                while (step < maxSteps) {
+                    step++;
+                    llmCalls++;
+                    let messages = await this.getMessagesWithContext(memoryCtx);
+                    let tools = !options.disableTools && this.config.tools ? [...this.config.tools] : [];
+                    // Apply Request Interceptors
+                    let context = { messages, tools };
+                    for (const interceptor of this.requestInterceptors) {
+                        context = await interceptor(context);
+                    }
+                    messages = context.messages;
+                    tools = context.tools;
+                    this.validateMessagesForModel(messages, {
+                        maxFileBytes: MAX_MESSAGE_FILE_BYTES_DEFAULT,
+                        providerName: this.config.model.providerName,
+                        modelName: this.config.model.modelName,
+                        capabilities: this.config.model.capabilities,
+                    });
+                    const llmTools = tools.length > 0
+                        ? tools.map(t => t.toLLMDefinition())
+                        : undefined;
+                    this.emit("agent:llm:call", {
+                        correlationId,
+                        executionId: options.executionId,
+                        data: {
+                            agentId: this.id,
+                            agentName: this.name,
+                            step,
+                            messages,
+                            tools: llmTools,
+                            responseFormat: options.responseFormat,
+                            model: {
+                                provider: this.config.model.providerName,
+                                model: this.config.model.modelName,
+                            },
+                        },
+                    });
+                    // No SDK-side LLM span: the LLM Gateway creates its own span
+                    // with richer data. We just call generate under the agent span so
+                    // the provider can read the current trace context (traceparent).
+                    const rawResponse = await this.config.model.generate(messages, llmTools, {
+                        responseFormat: options.responseFormat,
+                    });
+                    let response = rawResponse;
+                    this.emit("agent:llm:response", {
+                        correlationId,
+                        executionId: options.executionId,
+                        data: {
+                            agentId: this.id,
+                            agentName: this.name,
+                            step,
+                            content: response.content,
+                            toolCalls: response.toolCalls,
+                            usage: response.usage,
+                            model: {
+                                provider: this.config.model.providerName,
+                                model: this.config.model.modelName,
+                            },
+                        },
+                    });
+                    // Accumulate token usage
+                    if (response.usage) {
+                        totalUsage.promptTokens += response.usage.promptTokens;
+                        totalUsage.completionTokens += response.usage.completionTokens;
+                        totalUsage.totalTokens += response.usage.totalTokens;
+                        if (response.usage.reasoningTokens) {
+                            totalUsage.reasoningTokens = (totalUsage.reasoningTokens || 0) + response.usage.reasoningTokens;
+                        }
+                    }
+                    if (!response.toolCalls || response.toolCalls.length === 0 || options.disableTools) {
+                        // Apply Response Interceptors (Final Answer)
+                        for (const interceptor of this.responseInterceptors) {
+                            response = await interceptor(response);
+                        }
+                        await this.addMessage({ role: "assistant", content: response.content }, memoryCtx);
+                        await agentSpan.end({
+                            status: "success",
+                            data: {
+                                output: options.responseFormat?.type === "json"
+                                    ? this.safeParseJson(response.content)
+                                    : response.content,
+                                usage: totalUsage,
+                            },
+                        });
+                        return this.finishResult({
+                            correlationId,
+                            executionId: options.executionId,
+                            content: options.responseFormat?.type === "json"
+                                ? this.safeParseJson(response.content)
+                                : response.content,
+                            toolExecutions,
+                            toolCalls: options.disableTools ? response.toolCalls : undefined,
+                            llmCalls,
+                            totalDurationMs: Date.now() - startTime,
+                            truncated: false,
+                            totalUsage,
+                        });
+                    }
+                    // Add assistant message with tool calls before executing tools
+                    await this.addMessage({
+                        role: "assistant",
+                        content: response.content,
+                        tool_calls: response.toolCalls
+                    }, memoryCtx);
+                    for (const toolCall of response.toolCalls) {
+                        const parentExec = index_js_4.ExecutionContext.getOrUndefined();
+                        const toolExecutionId = parentExec?.executionId || options.executionId ? (0, node_crypto_1.randomUUID)() : undefined;
+                        await index_js_3.Tracing.withSpan({
+                            kind: "tool",
+                            name: `tool:${toolCall.function.name}`,
+                            correlationId,
+                            executionId: toolExecutionId ?? options.executionId,
+                            data: {
+                                toolName: toolCall.function.name,
+                                toolCallId: toolCall.id,
+                                args: toolCall.function.arguments,
+                            },
+                        }, async (toolSpan) => {
+                            this.emit("agent:tool:call", {
+                                correlationId,
+                                executionId: options.executionId,
+                                data: {
+                                    agentId: this.id,
+                                    agentName: this.name,
+                                    toolName: toolCall.function.name,
+                                    toolCallId: toolCall.id,
+                                    args: toolCall.function.arguments,
+                                },
+                            });
+                            const execution = await this.executeToolCall(toolCall, toolExecutionId);
+                            toolExecutions.push(execution);
+                            collectedToolCalls.push(toolCall);
+                            this.emit("agent:tool:result", {
+                                correlationId,
+                                executionId: options.executionId,
+                                data: {
+                                    agentId: this.id,
+                                    agentName: this.name,
+                                    toolName: toolCall.function.name,
+                                    toolCallId: toolCall.id,
+                                    output: execution.output,
+                                    error: execution.error,
+                                    durationMs: execution.durationMs,
+                                },
+                            });
+                            await toolSpan.end({
+                                status: execution.error ? "error" : "success",
+                                data: {
+                                    output: execution.output,
+                                    error: execution.error,
+                                },
+                            });
+                            await this.addMessage({
+                                role: "tool",
+                                tool_call_id: toolCall.id,
+                                content: execution.error ? `Error: ${execution.error}` : JSON.stringify(execution.output),
+                            }, memoryCtx);
+                        });
+                    }
+                }
+                truncated = true;
+                llmCalls++;
+                // Final run after max steps (force answer)
+                let finalMessages = await this.getMessagesWithContext(memoryCtx);
+                let finalTools = !options.disableTools && this.config.tools ? [...this.config.tools] : [];
+                // Interceptors for final run
+                let context = { messages: finalMessages, tools: finalTools };
+                for (const interceptor of this.requestInterceptors) {
+                    context = await interceptor(context);
+                }
+                finalMessages = context.messages;
+                // We ignore tools for final run usually, but keep consistency
+                this.validateMessagesForModel(finalMessages, {
+                    maxFileBytes: MAX_MESSAGE_FILE_BYTES_DEFAULT,
+                    providerName: this.config.model.providerName,
+                    modelName: this.config.model.modelName,
+                    capabilities: this.config.model.capabilities,
+                });
+                let finalResponse = await this.config.model.generate(finalMessages);
+                // Response interceptors for final run
+                for (const interceptor of this.responseInterceptors) {
+                    finalResponse = await interceptor(finalResponse);
+                }
+                await this.addMessage({ role: "assistant", content: finalResponse.content }, memoryCtx);
+                await agentSpan.end({
+                    status: truncated ? "cancelled" : "success",
+                    data: {
+                        output: finalResponse.content,
+                        usage: totalUsage,
+                    },
+                });
+                return this.finishResult({
+                    correlationId,
+                    executionId: options.executionId,
+                    content: finalResponse.content,
+                    toolExecutions,
+                    toolCalls: collectedToolCalls,
+                    llmCalls,
+                    totalDurationMs: Date.now() - startTime,
+                    truncated,
+                    totalUsage,
+                });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.emit("agent:execution:error", {
+                    correlationId,
+                    executionId: options.executionId,
+                    data: {
+                        agentId: this.id,
+                        agentName: this.name,
+                        error: {
+                            message: error.message,
+                            stack: error.stack,
+                            name: error.name,
+                        },
+                        durationMs: Date.now() - startTime,
+                    },
+                });
+                await agentSpan.end({ status: "error" });
+                throw err;
+            }
+        });
+        // Ensure execution hierarchy is available for tool sub-executions.
+        // IMPORTANT: Do NOT override an existing ExecutionContext (e.g. when this agent is a sub-execution inside a workflow).
+        const existingExecContext = index_js_4.ExecutionContext.getOrUndefined();
+        if (!existingExecContext && options.executionId) {
+            return index_js_4.ExecutionContext.run({ executionId: options.executionId, rootExecutionId: options.executionId, parentExecutionId: undefined }, runWithExecutionContext);
+        }
+        return runWithExecutionContext();
+    }
+    async *executeStream(options = {}) {
+        const startTime = Date.now();
+        const correlationId = generateCorrelationId();
+        const maxSteps = options.maxSteps ?? this.config.maxSteps ?? 10;
+        // Create memory context for partitioning
+        const memoryCtx = options.memoryKey
+            ? { memoryKey: options.memoryKey }
+            : undefined;
+        const toolExecutions = [];
+        const collectedToolCalls = [];
+        let llmCalls = 0;
+        let truncated = false;
+        let totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        this.emit("agent:execution:start", {
+            correlationId,
+            executionId: options.executionId,
+            data: {
+                agentId: this.id,
+                agentName: this.name,
+                input: undefined,
+            },
+        });
+        try {
+            // Initialize skills if not already initialized
+            await this.initializeSkills();
+            let step = 0;
+            while (step < maxSteps) {
+                step++;
+                llmCalls++;
+                let messages = await this.getMessagesWithContext(memoryCtx);
+                let tools = !options.disableTools && this.config.tools ? [...this.config.tools] : [];
+                // Apply Request Interceptors
+                let context = { messages, tools };
+                for (const interceptor of this.requestInterceptors) {
+                    context = await interceptor(context);
+                }
+                messages = context.messages;
+                tools = context.tools;
+                this.validateMessagesForModel(messages, {
+                    maxFileBytes: MAX_MESSAGE_FILE_BYTES_DEFAULT,
+                    providerName: this.config.model.providerName,
+                    modelName: this.config.model.modelName,
+                    capabilities: this.config.model.capabilities,
+                });
+                const llmTools = tools.length > 0
+                    ? tools.map(t => t.toLLMDefinition())
+                    : undefined;
+                this.emit("agent:llm:call", {
+                    correlationId,
+                    executionId: options.executionId,
+                    data: {
+                        agentId: this.id,
+                        agentName: this.name,
+                        step,
+                        messages,
+                        tools: llmTools,
+                        responseFormat: options.responseFormat,
+                        model: {
+                            provider: this.config.model.providerName,
+                            model: this.config.model.modelName,
+                        },
+                    },
+                });
+                const stream = this.config.model.generateStream(messages, llmTools, { responseFormat: options.responseFormat });
+                let fullContent = "";
+                let toolCallsBuffer = {};
+                let chunkUsage;
+                for await (const chunk of stream) {
+                    yield chunk;
+                    if (chunk.type === "content_delta") {
+                        fullContent += chunk.delta;
+                    }
+                    else if (chunk.type === "tool_call_start") {
+                        toolCallsBuffer[chunk.index] = {
+                            id: chunk.id,
+                            name: chunk.name,
+                            args: "",
+                            thought_signature: chunk.thought_signature
+                        };
+                    }
+                    else if (chunk.type === "tool_call_delta") {
+                        if (toolCallsBuffer[chunk.index]) {
+                            toolCallsBuffer[chunk.index].args += chunk.args;
+                        }
+                    }
+                    else if (chunk.type === "finish") {
+                        chunkUsage = chunk.usage;
+                    }
+                }
+                // Accumulate token usage
+                if (chunkUsage) {
+                    totalUsage.promptTokens += chunkUsage.promptTokens;
+                    totalUsage.completionTokens += chunkUsage.completionTokens;
+                    totalUsage.totalTokens += chunkUsage.totalTokens;
+                    if (chunkUsage.reasoningTokens) {
+                        totalUsage.reasoningTokens = (totalUsage.reasoningTokens || 0) + chunkUsage.reasoningTokens;
+                    }
+                }
+                const toolCalls = Object.values(toolCallsBuffer).map(tc => ({
+                    id: tc.id,
+                    type: "function",
+                    function: { name: tc.name, arguments: tc.args },
+                    ...(tc.thought_signature ? { thought_signature: tc.thought_signature } : {})
+                }));
+                this.emit("agent:llm:response", {
+                    correlationId,
+                    executionId: options.executionId,
+                    data: {
+                        agentId: this.id,
+                        agentName: this.name,
+                        step,
+                        content: fullContent,
+                        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                        usage: chunkUsage,
+                        model: {
+                            provider: this.config.model.providerName,
+                            model: this.config.model.modelName,
+                        },
+                    },
+                });
+                if (toolCalls.length === 0 || options.disableTools) {
+                    await this.addMessage({ role: "assistant", content: fullContent }, memoryCtx);
+                    // Emit execution:end event
+                    this.emit("agent:execution:end", {
+                        correlationId,
+                        executionId: options.executionId,
+                        data: {
+                            agentId: this.id,
+                            agentName: this.name,
+                            status: "success",
+                            output: options.responseFormat?.type === "json"
+                                ? this.safeParseJson(fullContent)
+                                : fullContent,
+                            durationMs: Date.now() - startTime,
+                            usage: totalUsage,
+                        },
+                    });
+                    return;
+                }
+                await this.addMessage({ role: "assistant", content: fullContent || null, tool_calls: toolCalls }, memoryCtx);
+                for (const toolCall of toolCalls) {
+                    const execution = await index_js_3.Tracing.withSpan({
+                        kind: "tool",
+                        name: `tool:${toolCall.function.name}`,
+                        correlationId,
+                        executionId: options.executionId,
+                        data: {
+                            toolName: toolCall.function.name,
+                            toolCallId: toolCall.id,
+                            args: toolCall.function.arguments,
+                        },
+                    }, async (toolSpan) => {
+                        this.emit("agent:tool:call", {
+                            correlationId,
+                            executionId: options.executionId,
+                            data: {
+                                agentId: this.id,
+                                agentName: this.name,
+                                toolName: toolCall.function.name,
+                                toolCallId: toolCall.id,
+                                args: toolCall.function.arguments,
+                            },
+                        });
+                        const exec = await this.executeToolCall(toolCall);
+                        toolExecutions.push(exec);
+                        collectedToolCalls.push(toolCall);
+                        this.emit("agent:tool:result", {
+                            correlationId,
+                            executionId: options.executionId,
+                            data: {
+                                agentId: this.id,
+                                agentName: this.name,
+                                toolName: toolCall.function.name,
+                                toolCallId: toolCall.id,
+                                output: exec.output,
+                                error: exec.error,
+                                durationMs: exec.durationMs,
+                            },
+                        });
+                        await toolSpan.end({
+                            status: exec.error ? "error" : "success",
+                            data: { output: exec.output, error: exec.error },
+                        });
+                        return exec;
+                    });
+                    yield {
+                        type: "tool_result",
+                        toolCallId: toolCall.id,
+                        result: execution.output
+                    };
+                    await this.addMessage({
+                        role: "tool",
+                        tool_call_id: toolCall.id,
+                        content: execution.error ? `Error: ${execution.error}` : JSON.stringify(execution.output),
+                    }, memoryCtx);
+                }
+            }
+            // Max steps reached - do final non-stream call
+            truncated = true;
+            llmCalls++;
+            let finalMessages = await this.getMessagesWithContext(memoryCtx);
+            let finalTools = !options.disableTools && this.config.tools ? [...this.config.tools] : [];
+            // Apply Request Interceptors for final call
+            let finalContext = { messages: finalMessages, tools: finalTools };
+            for (const interceptor of this.requestInterceptors) {
+                finalContext = await interceptor(finalContext);
+            }
+            finalMessages = finalContext.messages;
+            this.validateMessagesForModel(finalMessages, {
+                maxFileBytes: MAX_MESSAGE_FILE_BYTES_DEFAULT,
+                providerName: this.config.model.providerName,
+                modelName: this.config.model.modelName,
+                capabilities: this.config.model.capabilities,
+            });
+            const finalResponse = await this.config.model.generate(finalMessages);
+            // Accumulate final usage
+            if (finalResponse.usage) {
+                totalUsage.promptTokens += finalResponse.usage.promptTokens;
+                totalUsage.completionTokens += finalResponse.usage.completionTokens;
+                totalUsage.totalTokens += finalResponse.usage.totalTokens;
+                if (finalResponse.usage.reasoningTokens) {
+                    totalUsage.reasoningTokens = (totalUsage.reasoningTokens || 0) + finalResponse.usage.reasoningTokens;
+                }
+            }
+            await this.addMessage({ role: "assistant", content: finalResponse.content }, memoryCtx);
+            // Emit final result
+            this.emit("agent:execution:end", {
+                correlationId,
+                executionId: options.executionId,
+                data: {
+                    agentId: this.id,
+                    agentName: this.name,
+                    status: truncated ? "truncated" : "success",
+                    output: finalResponse.content,
+                    durationMs: Date.now() - startTime,
+                    usage: totalUsage,
+                },
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.emit("agent:execution:error", {
+                correlationId,
+                executionId: options.executionId,
+                data: {
+                    agentId: this.id,
+                    agentName: this.name,
+                    error: {
+                        message: error.message,
+                        stack: error.stack,
+                        name: error.name,
+                    },
+                    durationMs: Date.now() - startTime,
+                },
+            });
+            yield { type: "error", error };
+        }
+    }
+    // ==========================================================================
+    // Tools Execution
+    // ==========================================================================
+    async executeToolCall(toolCall, toolExecutionId) {
+        const startTime = Date.now();
+        const toolName = toolCall.function.name;
+        const tool = this.config.tools?.find((t) => t.id === toolName);
+        if (!tool) {
+            return {
+                id: toolCall.id,
+                name: toolName,
+                input: toolCall.function.arguments,
+                output: null,
+                durationMs: Date.now() - startTime,
+                error: `Tool '${toolName}' not found`,
+            };
+        }
+        try {
+            const parentExec = index_js_4.ExecutionContext.getOrUndefined();
+            if (toolExecutionId && parentExec) {
+                return index_js_4.ExecutionContext.run({
+                    executionId: toolExecutionId,
+                    rootExecutionId: parentExec.rootExecutionId ?? parentExec.executionId,
+                    parentExecutionId: parentExec.executionId,
+                }, async () => {
+                    this.emit("tool:execution:start", {
+                        data: {
+                            toolId: tool.id,
+                            toolName,
+                            toolCallId: toolCall.id,
+                            input: toolCall.function.arguments,
+                        },
+                    });
+                    try {
+                        const toolCtx = this.httpClient ? { http: this.httpClient } : {};
+                        const output = await tool.execute(toolCtx, toolCall.function.arguments);
+                        const durationMs = Date.now() - startTime;
+                        this.emit("tool:execution:end", {
+                            data: {
+                                toolId: tool.id,
+                                toolName,
+                                toolCallId: toolCall.id,
+                                status: "success",
+                                // IMPORTANT:
+                                // Tool outputs are not guaranteed to be JSON and can be large.
+                                // For domain events (materialization stream), we intentionally do NOT send the full output.
+                                // The execution detail screen should use tracing/parent execution output for deep debugging.
+                                durationMs,
+                            },
+                        });
+                        return {
+                            id: toolCall.id,
+                            name: toolName,
+                            input: toolCall.function.arguments,
+                            output,
+                            durationMs,
+                        };
+                    }
+                    catch (err) {
+                        const durationMs = Date.now() - startTime;
+                        const msg = err instanceof Error ? err.message : String(err);
+                        this.emit("tool:execution:error", {
+                            data: {
+                                toolId: tool.id,
+                                toolName,
+                                toolCallId: toolCall.id,
+                                error: { message: msg },
+                                durationMs,
+                            },
+                        });
+                        return {
+                            id: toolCall.id,
+                            name: toolName,
+                            input: toolCall.function.arguments,
+                            output: null,
+                            durationMs,
+                            error: msg,
+                        };
+                    }
+                });
+            }
+            const toolCtx = this.httpClient ? { http: this.httpClient } : {};
+            const output = await tool.execute(toolCtx, toolCall.function.arguments);
+            return {
+                id: toolCall.id,
+                name: toolName,
+                input: toolCall.function.arguments,
+                output,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            return {
+                id: toolCall.id,
+                name: toolName,
+                input: toolCall.function.arguments,
+                output: null,
+                durationMs: Date.now() - startTime,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    // ==========================================================================
+    // Helpers
+    // ==========================================================================
+    safeParseJson(content) {
+        if (!content)
+            return null;
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            return content;
+        }
+    }
+    validateMessagesForModel(messages, params) {
+        const fileParts = [];
+        for (const msg of messages) {
+            if (!Array.isArray(msg.content))
+                continue;
+            for (const part of msg.content) {
+                if (part.type === "file")
+                    fileParts.push(part);
+            }
+        }
+        if (fileParts.length === 0)
+            return;
+        // Enforce max size for base64 (URL is best-effort unless sizeBytes is provided)
+        for (const part of fileParts) {
+            const source = part.file.source;
+            if (source.type === "base64") {
+                const bytes = this.estimateBase64Bytes(source.base64);
+                if (bytes > params.maxFileBytes) {
+                    const name = part.file.name ?? "unknown";
+                    throw new Error(`Message file '${name}' exceeds max size (${bytes} bytes > ${params.maxFileBytes} bytes)`);
+                }
+            }
+            else {
+                const size = source.sizeBytes;
+                if (typeof size === "number" && size > params.maxFileBytes) {
+                    const name = part.file.name ?? "unknown";
+                    throw new Error(`Message file '${name}' exceeds max size (${size} bytes > ${params.maxFileBytes} bytes)`);
+                }
+            }
+        }
+        const caps = params.capabilities?.inputFiles;
+        if (!caps) {
+            throw new Error(`Model does not support file inputs (provider=${params.providerName}, model=${params.modelName})`);
+        }
+        for (const part of fileParts) {
+            const mimeType = part.file.mimeType;
+            const sourceType = part.file.source.type;
+            if (!caps.sources.includes(sourceType)) {
+                throw new Error(`Model does not support file source '${sourceType}' (provider=${params.providerName}, model=${params.modelName})`);
+            }
+            if (caps.mimeTypes === "any")
+                continue;
+            const ok = caps.mimeTypes.some((allowed) => this.mimeTypeMatches(allowed, mimeType));
+            if (!ok) {
+                throw new Error(`Model does not support file mimeType '${mimeType}' (provider=${params.providerName}, model=${params.modelName})`);
+            }
+        }
+    }
+    mimeTypeMatches(allowed, actual) {
+        if (allowed === actual)
+            return true;
+        if (allowed.endsWith("/*")) {
+            const prefix = allowed.slice(0, allowed.length - 1); // keep trailing '/'
+            return actual.startsWith(prefix);
+        }
+        return false;
+    }
+    /**
+     * Estimates the decoded byte length of a base64 string without decoding it.
+     */
+    estimateBase64Bytes(base64) {
+        const trimmed = base64.trim();
+        if (!trimmed)
+            return 0;
+        // Remove whitespace/newlines if present
+        const normalized = trimmed.replace(/\s+/g, "");
+        const len = normalized.length;
+        const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+        return Math.floor((len * 3) / 4) - padding;
+    }
+    finishResult(params) {
+        const result = {
+            content: params.content,
+            toolExecutions: params.toolExecutions,
+            toolCalls: params.toolCalls,
+            llmCalls: params.llmCalls,
+            totalDurationMs: params.totalDurationMs,
+            truncated: params.truncated,
+        };
+        this.emit("agent:execution:end", {
+            correlationId: params.correlationId,
+            executionId: params.executionId,
+            data: {
+                agentId: this.id,
+                agentName: this.name,
+                status: params.truncated ? "truncated" : "success",
+                output: result.content,
+                usage: params.totalUsage,
+                durationMs: params.totalDurationMs,
+            },
+        });
+        return result;
+    }
+}
+exports.Agent = Agent;