@n8n/agents 0.6.0 → 0.7.0

package/dist/runtime/agent-runtime.js

@@ -32,17 +32,14 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRuntime = void 0;
 const ai_1 = require("ai");
-const ajv_1 = __importDefault(require("ajv"));
 const zod_to_json_schema_1 = require("zod-to-json-schema");
 const catalog_1 = require("../sdk/catalog");
 const message_1 = require("../sdk/message");
 const event_bus_1 = require("./event-bus");
+const json_value_1 = require("./json-value");
 const memory_store_1 = require("./memory-store");
 const message_list_1 = require("./message-list");
 const messages_1 = require("./messages");
@@ -54,9 +51,67 @@ const strip_orphaned_tool_messages_1 = require("./strip-orphaned-tool-messages")
 const title_generation_1 = require("./title-generation");
 const tool_adapter_1 = require("./tool-adapter");
 const working_memory_1 = require("./working-memory");
+const parse_1 = require("../utils/parse");
 const zod_1 = require("../utils/zod");
+function isActiveSpanTracer(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof Reflect.get(value, 'startActiveSpan') === 'function');
+}
+function stringifyTelemetryValue(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function getToolInputSchema(tool) {
+    if (!tool.inputSchema) {
+        return undefined;
+    }
+    return (0, zod_1.isZodSchema)(tool.inputSchema) ? (0, zod_to_json_schema_1.zodToJsonSchema)(tool.inputSchema) : tool.inputSchema;
+}
+function summarizeToolForTelemetry(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        type: tool.mcpTool ? 'mcp' : 'local',
+        ...(tool.mcpServerName ? { mcp_server: tool.mcpServerName } : {}),
+        ...(tool.suspendSchema || tool.resumeSchema || tool.withDefaultApproval
+            ? { approval: true }
+            : {}),
+        ...(tool.inputSchema ? { input_schema: getToolInputSchema(tool) } : {}),
+    };
+}
+function summarizeProviderToolForTelemetry(tool) {
+    const [provider] = tool.name.split('.');
+    return {
+        name: tool.name,
+        provider,
+        type: 'provider',
+        args: tool.args,
+        ...(tool.inputSchema ? { input_schema: getToolInputSchema(tool) } : {}),
+    };
+}
+function buildAgentRootInputAttributes(config) {
+    const localTools = (config.tools ?? []).map(summarizeToolForTelemetry);
+    const providerTools = (config.providerTools ?? []).map(summarizeProviderToolForTelemetry);
+    const tools = [...localTools, ...providerTools];
+    const toolNames = tools
+        .map((tool) => (typeof tool.name === 'string' ? tool.name : undefined))
+        .filter((name) => name !== undefined);
+    const serialized = stringifyTelemetryValue({
+        agent: config.name,
+        tool_count: tools.length,
+        tools,
+    });
+    return {
+        ...(toolNames.length > 0 ? { 'langsmith.metadata.available_tools': toolNames } : {}),
+        ...(serialized ? { 'gen_ai.prompt': serialized } : {}),
+    };
+}
 const MAX_LOOP_ITERATIONS = 20;
-const ajv = new ajv_1.default({ strict: false });
 const EMPTY_MESSAGE_LIST = {
     messages: [],
     historyIds: [],
@@ -65,11 +120,9 @@ const EMPTY_MESSAGE_LIST = {
 };
 class AgentRuntime {
     constructor(config) {
-        this.runId = '';
         this.config = config;
-        this.runState = config.runState ?? new run_state_1.RunStateManager(config.checkpointStorage);
+        this.runState = new run_state_1.RunStateManager(config.checkpointStorage);
         this.eventBus = config.eventBus ?? new event_bus_1.AgentEventBus();
-        this.modelCost = config.modelCost;
         this.currentState = {
             persistence: undefined,
             status: 'idle',
@@ -84,58 +137,44 @@ class AgentRuntime {
         this.eventBus.abort();
     }
     async generate(input, options) {
-        this.runId = (0, run_state_1.generateRunId)();
-        this.executionOptions = options;
-        this.updateState({ persistence: options?.persistence });
+        const runId = (0, run_state_1.generateRunId)();
         let list = undefined;
         try {
-            list = await this.initRun(input);
-            const rawResult = await this.runGenerateLoop(list);
-            return this.finalizeGenerate(rawResult, list);
+            const initializedList = await this.initRun(input, options);
+            list = initializedList;
+            const rawResult = await this.withTelemetryRootSpan('generate', options, runId, async () => await this.runGenerateLoop({ list: initializedList, options, runId }));
+            return this.finalizeGenerate(rawResult, list, runId);
         }
         catch (error) {
-            await this.flushTelemetry();
+            await this.flushTelemetry(options);
             const isAbort = this.eventBus.isAborted;
             this.updateState({ status: isAbort ? 'cancelled' : 'failed' });
             if (!isAbort) {
-                this.emitEvent({ type: "error", message: String(error), error });
+                this.eventBus.emit({ type: "error", message: String(error), error });
             }
-            return {
-                runId: this.runId,
-                messages: list?.responseDelta() ?? [],
-                finishReason: 'error',
-                error,
-                getState: () => this.getState(),
-            };
+            return { runId, messages: list?.responseDelta() ?? [], finishReason: 'error', error };
         }
     }
     async stream(input, options) {
-        this.runId = (0, run_state_1.generateRunId)();
-        this.executionOptions = options;
-        this.updateState({ persistence: options?.persistence });
+        const runId = (0, run_state_1.generateRunId)();
         let list;
         try {
-            list = await this.initRun(input);
+            list = await this.initRun(input, options);
         }
         catch (error) {
             const isAbort = this.eventBus.isAborted;
             this.updateState({ status: isAbort ? 'cancelled' : 'failed' });
             if (!isAbort) {
-                this.emitEvent({ type: "error", message: String(error), error });
+                this.eventBus.emit({ type: "error", message: String(error), error });
             }
-            return { runId: this.runId, stream: (0, runtime_helpers_1.makeErrorStream)(error), getState: () => this.getState() };
+            return { runId, stream: (0, runtime_helpers_1.makeErrorStream)(error) };
         }
-        return {
-            runId: this.runId,
-            stream: this.startStreamLoop(list),
-            getState: () => this.getState(),
-        };
+        return { runId, stream: this.startStreamLoop({ list, options, runId }) };
     }
     async resume(method, data, options) {
-        this.runId = options.runId;
-        const state = await this.runState.resume(this.runId);
+        const state = await this.runState.resume(options.runId);
         if (!state)
-            throw new Error(`No suspended run found for runId: ${this.runId}`);
+            throw new Error(`No suspended run found for runId: ${options.runId}`);
         const toolCall = state.pendingToolCalls[options.toolCallId];
         if (!toolCall)
             throw new Error(`No tool call found for toolCallId: ${options.toolCallId}`);
@@ -144,9 +183,9 @@ class AgentRuntime {
             throw new Error(`Tool ${toolCall.toolName} not found`);
         let resumeData = data;
         if (tool.resumeSchema) {
-            const parseResult = await tool.resumeSchema.safeParseAsync(data);
+            const parseResult = await (0, parse_1.parseWithSchema)(tool.resumeSchema, data);
             if (!parseResult.success) {
-                throw new Error(`Invalid resume payload: ${parseResult.error.message}`);
+                throw new Error(`Invalid resume payload: ${parseResult.error}`);
             }
             resumeData = parseResult.data;
         }
@@ -158,9 +197,11 @@ class AgentRuntime {
                 ...persisted,
                 ...callerExecOptions,
             };
-            this.executionOptions = mergedExecOptions;
-            this.updateState({ persistence: state.persistence });
-            this.eventBus.resetAbort(this.executionOptions?.abortSignal);
+            const resumeOptions = {
+                persistence: state.persistence,
+                ...mergedExecOptions,
+            };
+            this.eventBus.resetAbort(resumeOptions.abortSignal);
             const pendingResume = {
                 pendingToolCalls: state.pendingToolCalls,
                 resumeToolCallId: options.toolCallId,
@@ -170,51 +211,58 @@ class AgentRuntime {
             await this.ensureModelCost();
             await this.setListWorkingMemoryConfig(list, state.persistence);
             if (method === 'generate') {
-                const rawResult = await this.runGenerateLoop(list, pendingResume);
+                const rawResult = await this.withTelemetryRootSpan('generate', resumeOptions, options.runId, async () => await this.runGenerateLoop({
+                    list,
+                    options: resumeOptions,
+                    runId: options.runId,
+                    pendingResume,
+                }));
                 if (!rawResult.pendingSuspend) {
-                    await this.cleanupRun();
+                    await this.cleanupRun(options.runId);
                 }
-                return this.finalizeGenerate(rawResult, list);
+                return this.finalizeGenerate(rawResult, list, options.runId);
             }
             return {
-                runId: this.runId,
-                stream: this.startStreamLoop(list, pendingResume),
-                getState: () => this.getState(),
+                runId: options.runId,
+                stream: this.startStreamLoop({
+                    list,
+                    options: resumeOptions,
+                    runId: options.runId,
+                    pendingResume,
+                }),
             };
         }
         catch (error) {
             const isAbort = this.eventBus.isAborted;
             this.updateState({ status: isAbort ? 'cancelled' : 'failed' });
             if (!isAbort) {
-                this.emitEvent({ type: "error", message: String(error), error });
+                this.eventBus.emit({ type: "error", message: String(error), error });
             }
             if (method === 'generate') {
                 return {
-                    runId: this.runId,
+                    runId: options.runId,
                     messages: [],
                     finishReason: 'error',
                     error,
-                    getState: () => this.getState(),
                 };
             }
-            return { runId: this.runId, stream: (0, runtime_helpers_1.makeErrorStream)(error), getState: () => this.getState() };
+            return { runId: options.runId, stream: (0, runtime_helpers_1.makeErrorStream)(error) };
         }
     }
-    async buildMessageList(input) {
+    async buildMessageList(input, options) {
         const list = new message_list_1.AgentMessageList();
-        const persistence = this.currentState.persistence;
-        if (this.config.memory && persistence?.threadId) {
-            const memMessages = await this.config.memory.getMessages(persistence.threadId, {
+        if (this.config.memory && options?.persistence?.threadId) {
+            const memMessages = await this.config.memory.getMessages(options.persistence.threadId, {
                 limit: this.config.lastMessages ?? 10,
             });
             if (memMessages.length > 0) {
                 list.addHistory((0, strip_orphaned_tool_messages_1.stripOrphanedToolMessages)(memMessages));
             }
         }
-        if (this.config.semanticRecall && persistence?.threadId) {
-            await this.performSemanticRecall(list, input, persistence.threadId, persistence.resourceId);
+        if (this.config.semanticRecall && options?.persistence?.threadId) {
+            await this.performSemanticRecall(list, input, options.persistence.threadId, options.persistence.resourceId);
         }
-        await this.setListWorkingMemoryConfig(list, persistence);
+        await this.setListWorkingMemoryConfig(list, options?.persistence);
         list.addInput(input);
         return list;
     }
@@ -296,34 +344,37 @@ class AgentRuntime {
             return mid && expandedIds.has(mid);
         });
     }
-    async initRun(input) {
-        this.eventBus.resetAbort(this.executionOptions?.abortSignal);
-        this.updateState({ status: 'running' });
-        this.emitEvent({ type: "agent_start" });
+    async initRun(input, options) {
+        this.eventBus.resetAbort(options?.abortSignal);
+        this.updateState({
+            status: 'running',
+            persistence: options?.persistence,
+        });
+        this.eventBus.emit({ type: "agent_start" });
         await this.ensureModelCost();
         const normalizedInput = (0, runtime_helpers_1.normalizeInput)(input);
-        return await this.buildMessageList(normalizedInput);
+        return await this.buildMessageList(normalizedInput, options);
     }
-    finalizeGenerate(result, list) {
-        result.runId = this.runId;
+    finalizeGenerate(result, list, runId) {
+        result.runId = runId;
         result.usage = this.applyCost(result.usage);
         result.model = this.modelIdString;
         const finalized = (0, runtime_helpers_1.applySubAgentUsage)(result);
         this.updateState({ status: 'success', messageList: list.serialize() });
-        this.emitEvent({ type: "agent_end", messages: finalized.messages });
-        return { ...finalized, getState: () => this.getState() };
+        this.eventBus.emit({ type: "agent_end", messages: finalized.messages });
+        return finalized;
     }
-    resolveTelemetry() {
+    resolveTelemetry(options) {
         if (this.config.telemetry)
             return this.config.telemetry;
-        const inherited = this.executionOptions?.telemetry;
+        const inherited = options?.telemetry;
         if (!inherited)
             return undefined;
         return { ...inherited, functionId: this.config.name };
     }
-    async flushTelemetry() {
+    async flushTelemetry(options) {
         try {
-            const resolved = this.resolveTelemetry();
+            const resolved = this.resolveTelemetry(options);
             if (resolved?.provider) {
                 await resolved.provider.forceFlush();
             }
@@ -331,8 +382,8 @@ class AgentRuntime {
         catch {
         }
     }
-    buildTelemetryOptions() {
-        const t = this.resolveTelemetry();
+    buildTelemetryOptions(options) {
+        const t = this.resolveTelemetry(options);
         if (!t?.enabled)
             return {};
         return {
@@ -347,23 +398,103 @@ class AgentRuntime {
             },
         };
     }
-    async runGenerateLoop(list, pendingResume) {
-        const { model, toolMap, aiTools, providerOptions, hasTools, outputSpec } = this.buildLoopContext();
+    buildTelemetryRootAttributes(t, spanName, runId) {
+        const metadataAttributes = this.buildTelemetryMetadataAttributes(t, 'langsmith.metadata');
+        return {
+            'langsmith.traceable': 'true',
+            'langsmith.trace.name': spanName,
+            'langsmith.span.kind': 'chain',
+            'langsmith.metadata.agent_name': this.config.name,
+            'langsmith.metadata.agent_run_id': runId,
+            ...metadataAttributes,
+            ...buildAgentRootInputAttributes(this.config),
+        };
+    }
+    buildTelemetryMetadataAttributes(t, prefix) {
+        return Object.fromEntries(Object.entries(t.metadata ?? {}).map(([key, value]) => [`${prefix}.${key}`, value]));
+    }
+    buildAiSdkOperationAttributes(operationId, t) {
+        const functionId = t.functionId ?? this.config.name;
+        return {
+            'operation.name': `${operationId} ${functionId}`,
+            'resource.name': functionId,
+            'ai.operationId': operationId,
+            'ai.telemetry.functionId': functionId,
+            ...this.buildTelemetryMetadataAttributes(t, 'ai.telemetry.metadata'),
+        };
+    }
+    async withTelemetryRootSpan(operation, options, runId, fn) {
+        const t = this.resolveTelemetry(options);
+        if (!t?.enabled || t.runtimeRootSpanEnabled === false || !isActiveSpanTracer(t.tracer)) {
+            return await fn();
+        }
+        const spanName = `${t.functionId ?? this.config.name}.${operation}`;
+        return await t.tracer.startActiveSpan(spanName, { attributes: this.buildTelemetryRootAttributes(t, spanName, runId) }, async (span) => {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                span.recordException?.(error);
+                span.setStatus?.({ code: 2, message: String(error) });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    async withTelemetryToolSpan(toolCallId, toolName, input, t, fn) {
+        if (!t?.enabled || !isActiveSpanTracer(t.tracer)) {
+            return await fn();
+        }
+        const shouldRecordInputs = t.recordInputs ?? true;
+        const inputValue = shouldRecordInputs ? stringifyTelemetryValue(input) : undefined;
+        return await t.tracer.startActiveSpan('ai.toolCall', {
+            attributes: {
+                ...this.buildAiSdkOperationAttributes('ai.toolCall', t),
+                'ai.toolCall.name': toolName,
+                'ai.toolCall.id': toolCallId,
+                ...(inputValue !== undefined ? { 'ai.toolCall.args': inputValue } : {}),
+            },
+        }, async (span) => {
+            try {
+                const result = await fn();
+                const shouldRecordOutputs = t.recordOutputs ?? true;
+                const outputValue = shouldRecordOutputs ? stringifyTelemetryValue(result) : undefined;
+                if (outputValue !== undefined) {
+                    span.setAttributes?.({ 'ai.toolCall.result': outputValue });
+                }
+                return result;
+            }
+            catch (error) {
+                span.recordException?.(error);
+                span.setStatus?.({ code: 2, message: String(error) });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    async runGenerateLoop(ctx) {
+        const { list, options, runId, pendingResume } = ctx;
+        const { model, toolMap, aiTools, providerOptions, hasTools, outputSpec, effectiveInstructions, } = this.buildLoopContext({ ...options, persistence: options?.persistence });
         let totalUsage;
         let lastFinishReason = 'stop';
         let structuredOutput;
         const toolCallSummary = [];
         const collectedSubAgentUsage = [];
-        const runTelemetry = this.resolveTelemetry();
+        const runTelemetry = this.resolveTelemetry(options);
+        const toolCtx = { toolMap, list, runId, telemetry: runTelemetry };
         if (pendingResume) {
-            const batch = await this.iteratePendingToolCallsConcurrent(pendingResume, toolMap, list, runTelemetry);
+            const batch = await this.iteratePendingToolCallsConcurrent({ ...toolCtx, pendingResume });
             for (const r of batch.results) {
                 toolCallSummary.push(r.toolEntry);
                 if (r.subAgentUsage)
                     collectedSubAgentUsage.push(...r.subAgentUsage);
             }
             if (Object.keys(batch.pending).length > 0) {
-                const suspendRunId = await this.persistSuspension(batch.pending, list, totalUsage);
+                const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
                 return {
                     runId: suspendRunId,
                     messages: list.responseDelta(),
@@ -377,27 +508,26 @@ class AgentRuntime {
                         suspendPayload: s.payload,
                         resumeSchema: s.resumeSchema,
                     })),
-                    getState: () => this.getState(),
                 };
             }
         }
-        const maxIterations = this.executionOptions?.maxIterations ?? MAX_LOOP_ITERATIONS;
+        const maxIterations = options?.maxIterations ?? MAX_LOOP_ITERATIONS;
         for (let i = 0; i < maxIterations; i++) {
             if (this.eventBus.isAborted) {
                 this.updateState({ status: 'cancelled' });
                 throw new Error('Agent run was aborted');
             }
-            this.emitEvent({ type: "turn_start" });
+            this.eventBus.emit({ type: "turn_start" });
             const result = await (0, ai_1.generateText)({
                 model,
-                messages: list.forLlm(this.config.instructions, this.config.instructionProviderOptions),
+                messages: list.forLlm(effectiveInstructions, this.config.instructionProviderOptions),
                 abortSignal: this.eventBus.signal,
                 ...(hasTools ? { tools: aiTools } : {}),
                 ...(providerOptions
                     ? { providerOptions: providerOptions }
                     : {}),
                 ...(outputSpec ? { output: outputSpec } : {}),
-                ...this.buildTelemetryOptions(),
+                ...this.buildTelemetryOptions(options),
             });
             const aiFinishReason = result.finishReason;
             lastFinishReason = (0, messages_1.fromAiFinishReason)(aiFinishReason);
@@ -409,17 +539,20 @@ class AgentRuntime {
                 if (outputSpec) {
                     structuredOutput = result.output;
                 }
-                this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractToolResults)(newMessages));
+                this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(newMessages));
                 break;
             }
-            const batch = await this.iterateToolCallsConcurrent(result.toolCalls, toolMap, list, runTelemetry);
+            const batch = await this.iterateToolCallsConcurrent({
+                ...toolCtx,
+                toolCalls: result.toolCalls,
+            });
             for (const r of batch.results) {
                 toolCallSummary.push(r.toolEntry);
                 if (r.subAgentUsage)
                     collectedSubAgentUsage.push(...r.subAgentUsage);
             }
             if (Object.keys(batch.pending).length > 0) {
-                const suspendRunId = await this.persistSuspension(batch.pending, list, totalUsage);
+                const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
                 return {
                     runId: suspendRunId,
                     messages: list.responseDelta(),
@@ -433,44 +566,58 @@ class AgentRuntime {
                         suspendPayload: s.payload,
                         resumeSchema: s.resumeSchema,
                     })),
-                    getState: () => this.getState(),
                 };
             }
-            this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractToolResults)(list.responseDelta()));
+            this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(list.responseDelta()));
         }
         if (lastFinishReason === 'tool-calls') {
             throw new Error(`Agent loop exceeded ${maxIterations} iterations without reaching a stop condition`);
         }
-        await this.saveToMemory(list);
-        await this.flushTelemetry();
-        const persistence = this.currentState.persistence;
-        if (this.config.titleGeneration && persistence?.threadId && this.config.memory) {
-            void (0, title_generation_1.generateThreadTitle)({
+        await this.saveToMemory(list, options);
+        await this.flushTelemetry(options);
+        if (this.config.titleGeneration && options?.persistence?.threadId && this.config.memory) {
+            const titlePromise = (0, title_generation_1.generateThreadTitle)({
                 memory: this.config.memory,
-                threadId: persistence.threadId,
-                resourceId: persistence.resourceId,
+                threadId: options.persistence.threadId,
+                resourceId: options.persistence.resourceId,
                 titleConfig: this.config.titleGeneration,
                 agentModel: this.config.model,
                 turnDelta: list.turnDelta(),
             });
+            if (this.config.titleGeneration.sync) {
+                await titlePromise;
+            }
         }
         return {
-            runId: this.runId,
+            runId: runId ?? '',
             messages: list.responseDelta(),
             finishReason: lastFinishReason,
             usage: totalUsage,
             ...(structuredOutput !== undefined && { structuredOutput }),
             ...(toolCallSummary.length > 0 && { toolCalls: toolCallSummary }),
             ...(collectedSubAgentUsage.length > 0 && { subAgentUsage: collectedSubAgentUsage }),
-            getState: () => this.getState(),
         };
     }
-    startStreamLoop(list, pendingResume) {
+    startStreamLoop(ctx) {
+        const { options, runId } = ctx;
         const { readable, writable } = new TransformStream();
         const writer = writable.getWriter();
-        this.runStreamLoop(list, writer, pendingResume).catch(async (error) => {
-            await this.flushTelemetry();
-            await this.cleanupRun();
+        const onToolExecutionStart = (data) => {
+            if (data.type !== "tool_execution_start")
+                return;
+            writer
+                .write({
+                type: 'tool-execution-start',
+                toolCallId: data.toolCallId,
+                toolName: data.toolName,
+            })
+                .catch(() => { });
+        };
+        this.eventBus.on("tool_execution_start", onToolExecutionStart);
+        this.withTelemetryRootSpan('stream', options, runId, async () => await this.runStreamLoop({ ...ctx, writer }))
+            .catch(async (error) => {
+            await this.flushTelemetry(options);
+            await this.cleanupRun(runId);
             try {
                 await writer.write({ type: 'error', error });
                 await writer.write({ type: 'finish', finishReason: 'error' });
@@ -479,11 +626,15 @@ class AgentRuntime {
             catch {
                 writer.abort(error).catch(() => { });
             }
+        })
+            .finally(() => {
+            this.eventBus.off("tool_execution_start", onToolExecutionStart);
         });
         return readable;
     }
-    async runStreamLoop(list, writer, pendingResume) {
-        const { model, toolMap, aiTools, providerOptions, hasTools, outputSpec } = this.buildLoopContext();
+    async runStreamLoop(ctx) {
+        const { list, options, runId, pendingResume, writer } = ctx;
+        const { model, toolMap, aiTools, providerOptions, hasTools, outputSpec, effectiveInstructions, } = this.buildLoopContext({ ...options, persistence: options?.persistence });
         const writeChunk = async (chunk) => {
             await writer.write(chunk);
         };
@@ -491,9 +642,9 @@ class AgentRuntime {
         let lastFinishReason = 'stop';
         let structuredOutput;
         const collectedSubAgentUsage = [];
-        const maxIterations = this.executionOptions?.maxIterations ?? MAX_LOOP_ITERATIONS;
+        const maxIterations = options?.maxIterations ?? MAX_LOOP_ITERATIONS;
         const closeStreamWithError = async (error, status) => {
-            await this.cleanupRun();
+            await this.cleanupRun(runId);
             this.updateState({ status });
             await writer.write({ type: 'error', error });
             await writer.write({ type: 'finish', finishReason: 'error' });
@@ -505,16 +656,22 @@ class AgentRuntime {
             await closeStreamWithError(new Error('Agent run was aborted'), 'cancelled');
             return true;
         };
-        const runTelemetry = this.resolveTelemetry();
+        const runTelemetry = this.resolveTelemetry(options);
+        const toolCtx = { toolMap, list, runId, telemetry: runTelemetry };
         if (pendingResume) {
             try {
-                const batch = await this.iteratePendingToolCallsConcurrent(pendingResume, toolMap, list, runTelemetry);
+                const batch = await this.iteratePendingToolCallsConcurrent({
+                    ...toolCtx,
+                    pendingResume,
+                });
                 for (const r of batch.results) {
                     if (r.subAgentUsage)
                         collectedSubAgentUsage.push(...r.subAgentUsage);
                     await writer.write({
-                        type: 'message',
-                        message: r.message,
+                        type: 'tool-result',
+                        toolCallId: r.toolCallId,
+                        toolName: r.toolName,
+                        output: r.modelOutput,
                     });
                     if (r.customMessage) {
                         await writer.write({ type: 'message', message: r.customMessage });
@@ -522,12 +679,15 @@ class AgentRuntime {
                 }
                 for (const e of batch.errors) {
                     await writer.write({
-                        type: 'message',
-                        message: e.message,
+                        type: 'tool-result',
+                        toolCallId: e.toolCallId,
+                        toolName: e.toolName,
+                        output: e.error,
+                        isError: true,
                     });
                 }
                 if (Object.keys(batch.pending).length > 0) {
-                    const suspendRunId = await this.persistSuspension(batch.pending, list, totalUsage);
+                    const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
                     for (const s of batch.suspensions) {
                         await writer.write({
                             type: 'tool-call-suspended',
@@ -545,7 +705,7 @@ class AgentRuntime {
                 }
             }
             catch (error) {
-                this.emitEvent({ type: "error", message: String(error), error });
+                this.eventBus.emit({ type: "error", message: String(error), error });
                 await closeStreamWithError(error, 'failed');
                 return;
             }
@@ -553,21 +713,22 @@ class AgentRuntime {
         for (let i = 0; i < maxIterations; i++) {
             if (await handleAbort())
                 return;
-            this.emitEvent({ type: "turn_start" });
+            this.eventBus.emit({ type: "turn_start" });
+            const messages = list.forLlm(effectiveInstructions, this.config.instructionProviderOptions);
             const result = (0, ai_1.streamText)({
                 model,
-                messages: list.forLlm(this.config.instructions, this.config.instructionProviderOptions),
+                messages,
                 abortSignal: this.eventBus.signal,
                 ...(hasTools ? { tools: aiTools } : {}),
                 ...(providerOptions
                     ? { providerOptions: providerOptions }
                     : {}),
                 ...(outputSpec ? { output: outputSpec } : {}),
-                ...this.buildTelemetryOptions(),
+                ...this.buildTelemetryOptions(options),
             });
             try {
                 for await (const chunk of result.fullStream) {
-                    if (chunk.type === 'finish' || chunk.type === 'finish-step')
+                    if (chunk.type === 'finish')
                         continue;
                     const converted = (0, stream_1.convertChunk)(chunk);
                     if (converted)
@@ -577,7 +738,7 @@ class AgentRuntime {
             catch (streamError) {
                 if (await handleAbort())
                     return;
-                this.emitEvent({
+                this.eventBus.emit({
                     type: "error",
                     message: String(streamError),
                     error: streamError,
@@ -599,20 +760,22 @@ class AgentRuntime {
                 if (outputSpec) {
                     structuredOutput = await result.output;
                 }
-                this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractToolResults)(newMessages));
+                this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(newMessages));
                 break;
             }
             const toolCalls = await result.toolCalls;
             try {
-                const batch = await this.iterateToolCallsConcurrent(toolCalls, toolMap, list, runTelemetry);
+                const batch = await this.iterateToolCallsConcurrent({ ...toolCtx, toolCalls });
                 if (await handleAbort())
                     return;
                 for (const r of batch.results) {
                     if (r.subAgentUsage)
                         collectedSubAgentUsage.push(...r.subAgentUsage);
                     await writer.write({
-                        type: 'message',
-                        message: r.message,
+                        type: 'tool-result',
+                        toolCallId: r.toolCallId,
+                        toolName: r.toolName,
+                        output: r.modelOutput,
                     });
                     if (r.customMessage) {
                         await writer.write({ type: 'message', message: r.customMessage });
@@ -620,12 +783,15 @@ class AgentRuntime {
                 }
                 for (const e of batch.errors) {
                     await writer.write({
-                        type: 'message',
-                        message: e.message,
+                        type: 'tool-result',
+                        toolCallId: e.toolCallId,
+                        toolName: e.toolName,
+                        output: e.error,
+                        isError: true,
                     });
                 }
                 if (Object.keys(batch.pending).length > 0) {
-                    const suspendRunId = await this.persistSuspension(batch.pending, list, totalUsage);
+                    const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
                     for (const s of batch.suspensions) {
                         await writer.write({
                             type: 'tool-call-suspended',
@@ -643,11 +809,11 @@ class AgentRuntime {
                 }
             }
             catch (error) {
-                this.emitEvent({ type: "error", message: String(error), error });
+                this.eventBus.emit({ type: "error", message: String(error), error });
                 await closeStreamWithError(error, 'failed');
                 return;
             }
-            this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractToolResults)(list.responseDelta()));
+            this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(list.responseDelta()));
         }
         const costUsage = this.applyCost(totalUsage);
         const parentCost = costUsage?.cost ?? 0;
@@ -664,37 +830,38 @@ class AgentRuntime {
             }),
         });
         try {
-            await this.saveToMemory(list);
-            const persistence = this.currentState.persistence;
-            if (this.config.titleGeneration && persistence && this.config.memory) {
-                void (0, title_generation_1.generateThreadTitle)({
+            await this.saveToMemory(list, options);
+            if (this.config.titleGeneration && options?.persistence && this.config.memory) {
+                const titlePromise = (0, title_generation_1.generateThreadTitle)({
                     memory: this.config.memory,
-                    threadId: persistence.threadId,
-                    resourceId: persistence.resourceId,
+                    threadId: options.persistence.threadId,
+                    resourceId: options.persistence.resourceId,
                     titleConfig: this.config.titleGeneration,
                     agentModel: this.config.model,
                     turnDelta: list.turnDelta(),
                 });
+                if (this.config.titleGeneration.sync) {
+                    await titlePromise;
+                }
             }
-            await this.cleanupRun();
-            await this.flushTelemetry();
+            await this.cleanupRun(runId);
+            await this.flushTelemetry(options);
             this.updateState({ status: 'success', messageList: list.serialize() });
-            this.emitEvent({ type: "agent_end", messages: list.responseDelta() });
+            this.eventBus.emit({ type: "agent_end", messages: list.responseDelta() });
         }
         finally {
             await writer.close();
         }
     }
-    async saveToMemory(list) {
-        const persistence = this.currentState.persistence;
-        if (!this.config.memory || !persistence)
+    async saveToMemory(list, options) {
+        if (!this.config.memory || !options?.persistence)
             return;
         const delta = list.turnDelta();
         if (delta.length === 0)
             return;
-        await (0, memory_store_1.saveMessagesToThread)(this.config.memory, persistence.threadId, persistence.resourceId, delta);
+        await (0, memory_store_1.saveMessagesToThread)(this.config.memory, options.persistence.threadId, options.persistence.resourceId, delta);
         if (this.config.semanticRecall?.embedder && this.config.memory.saveEmbeddings) {
-            await this.saveEmbeddingsForMessages(persistence.threadId, persistence.resourceId, delta);
+            await this.saveEmbeddingsForMessages(options.persistence.threadId, options.persistence.resourceId, delta);
         }
     }
     async saveEmbeddingsForMessages(threadId, resourceId, messages) {
@@ -792,7 +959,8 @@ class AgentRuntime {
         }
         return merged;
     }
-    async iterateToolCallsConcurrent(toolCalls, toolMap, list, resolvedTelemetry) {
+    async iterateToolCallsConcurrent(ctx) {
+        const { toolCalls, toolMap, list, runId, telemetry: resolvedTelemetry } = ctx;
         const executableCalls = toolCalls.filter((tc) => !tc.providerExecuted);
         const executableCallsById = new Map(executableCalls.map((tc) => [tc.toolCallId, tc]));
         const unexecutedIds = new Set(executableCalls.map((tc) => tc.toolCallId));
@@ -817,12 +985,12 @@ class AgentRuntime {
                 const tc = batch[i];
                 const toolInput = tc.input;
                 if (result.status === 'rejected') {
+                    list.setToolCallError(tc.toolCallId, result.reason);
                     errors.push({
                         toolCallId: tc.toolCallId,
                         toolName: tc.toolName,
                         input: toolInput,
                         error: result.reason,
-                        message: (0, runtime_helpers_1.makeErrorToolResultMessage)(tc.toolCallId, tc.toolName, result.reason),
                     });
                 }
                 else if (result.value.outcome === 'suspended') {
@@ -841,6 +1009,7 @@ class AgentRuntime {
                         input: toolInput,
                         suspendPayload: result.value.payload,
                         resumeSchema: result.value.resumeSchema,
+                        runId,
                     };
                 }
                 else if (result.value.outcome === 'success') {
@@ -849,9 +1018,9 @@ class AgentRuntime {
                         toolName: tc.toolName,
                         input: toolInput,
                         toolEntry: result.value.toolEntry,
+                        modelOutput: result.value.modelOutput,
                         subAgentUsage: result.value.subAgentUsage,
                         customMessage: result.value.customMessage,
-                        message: result.value.message,
                     });
                 }
                 else if (result.value.outcome === 'error') {
@@ -860,7 +1029,6 @@ class AgentRuntime {
                         toolName: tc.toolName,
                         input: toolInput,
                         error: result.value.error,
-                        message: result.value.message,
                     });
                 }
                 else if (result.value.outcome === 'noop') {
@@ -881,7 +1049,8 @@ class AgentRuntime {
         }
         return { results, suspensions, errors, pending };
     }
-    async iteratePendingToolCallsConcurrent(pendingResume, toolMap, list, resolvedTelemetry) {
+    async iteratePendingToolCallsConcurrent(ctx) {
+        const { pendingResume, toolMap, list, runId, telemetry: resolvedTelemetry } = ctx;
         const resumedId = pendingResume.resumeToolCallId;
         const resumedEntry = pendingResume.pendingToolCalls[resumedId];
         if (!resumedEntry) {
@@ -899,6 +1068,7 @@ class AgentRuntime {
                 suspended: true,
                 suspendPayload: processResult.payload,
                 resumeSchema: processResult.resumeSchema,
+                runId,
             };
             suspensions.push({
                 toolCallId: resumedId,
@@ -914,9 +1084,9 @@ class AgentRuntime {
                 toolName: resumedToolName,
                 input: resumedEntry.input,
                 toolEntry: processResult.toolEntry,
+                modelOutput: processResult.modelOutput,
                 subAgentUsage: processResult.subAgentUsage,
                 customMessage: processResult.customMessage,
-                message: processResult.message,
             });
         }
         else if (processResult.outcome === 'error') {
@@ -925,7 +1095,6 @@ class AgentRuntime {
                 toolName: resumedToolName,
                 input: resumedEntry.input,
                 error: processResult.error,
-                message: processResult.message,
             });
         }
         else if (processResult.outcome === 'noop') {
@@ -954,7 +1123,13 @@ class AgentRuntime {
             }
         }
         if (unexecuted.length > 0) {
-            const batch = await this.iterateToolCallsConcurrent(unexecuted, toolMap, list, resolvedTelemetry);
+            const batch = await this.iterateToolCallsConcurrent({
+                toolCalls: unexecuted,
+                toolMap,
+                list,
+                runId,
+                telemetry: resolvedTelemetry,
+            });
             results.push(...batch.results);
             suspensions.push(...batch.suspensions);
             errors.push(...batch.errors);
@@ -964,71 +1139,66 @@ class AgentRuntime {
     }
     async processToolCall(toolCallId, toolName, toolInput, toolMap, list, resumeData, resolvedTelemetry) {
         const builtTool = toolMap.get(toolName);
-        this.emitEvent({
+        this.eventBus.emit({
             type: "tool_execution_start",
             toolCallId,
             toolName,
             args: toolInput,
         });
         const makeToolError = (error) => {
-            this.emitEvent({
+            this.eventBus.emit({
                 type: "tool_execution_end",
                 toolCallId,
                 toolName,
                 result: error,
                 isError: true,
             });
-            const errorMsg = (0, runtime_helpers_1.makeErrorToolResultMessage)(toolCallId, toolName, error);
-            list.addResponse([errorMsg]);
-            return { outcome: 'error', error, message: errorMsg };
+            list.setToolCallError(toolCallId, error);
+            return { outcome: 'error', error };
         };
         if (!builtTool) {
             return makeToolError(new Error(`Tool ${toolName} not found`));
         }
-        const existingToolResults = list
+        const settledBlock = list
             .responseDelta()
-            .filter((m) => (0, message_1.isLlmMessage)(m) && m.role === 'tool')
-            .flatMap((m) => m.content.filter((content) => content.type === 'tool-result'));
-        const existingToolResult = existingToolResults.find((r) => r.toolCallId === toolCallId);
-        if (existingToolResult) {
-            this.emitEvent({
+            .flatMap((m) => ((0, message_1.isLlmMessage)(m) && 'content' in m ? m.content : []))
+            .find((c) => c.type === 'tool-call' && c.toolCallId === toolCallId && c.state !== 'pending');
+        if (settledBlock) {
+            let settledResult;
+            if (settledBlock.state === 'resolved') {
+                settledResult = settledBlock.output;
+            }
+            else {
+                settledResult = settledBlock.error;
+            }
+            this.eventBus.emit({
                 type: "tool_execution_end",
                 toolCallId,
                 toolName,
-                result: existingToolResult.result,
-                isError: !!existingToolResult.isError,
+                result: settledResult,
+                isError: settledBlock.state === 'rejected',
             });
             return { outcome: 'noop' };
         }
         if (builtTool.inputSchema) {
-            if ((0, zod_1.isZodSchema)(builtTool.inputSchema)) {
-                const result = await builtTool.inputSchema.safeParseAsync(toolInput);
-                if (!result.success) {
-                    return makeToolError(new Error(`Invalid tool input: ${result.error.message}`));
-                }
-                toolInput = result.data;
-            }
-            else {
-                const validate = ajv.compile(builtTool.inputSchema);
-                const valid = validate(toolInput);
-                if (!valid) {
-                    const message = ajv.errorsText(validate.errors);
-                    return makeToolError(new Error(`Invalid tool input: ${message}`));
-                }
+            const result = await (0, parse_1.parseWithSchema)(builtTool.inputSchema, toolInput);
+            if (!result.success) {
+                return makeToolError(new Error(`Invalid tool input: ${result.error}`));
             }
+            toolInput = result.data;
         }
         let toolResult;
         try {
-            toolResult = await (0, tool_adapter_1.executeTool)(toolInput, builtTool, resumeData, resolvedTelemetry);
+            toolResult = await this.withTelemetryToolSpan(toolCallId, toolName, toolInput, resolvedTelemetry, async () => await (0, tool_adapter_1.executeTool)(toolInput, builtTool, resumeData, resolvedTelemetry, toolCallId));
         }
         catch (error) {
             return makeToolError(error);
         }
         if ((0, tool_adapter_1.isSuspendedToolResult)(toolResult)) {
             if (builtTool?.suspendSchema) {
-                const parseResult = await builtTool.suspendSchema.safeParseAsync(toolResult.payload);
+                const parseResult = await (0, parse_1.parseWithSchema)(builtTool.suspendSchema, toolResult.payload);
                 if (!parseResult.success) {
-                    return makeToolError(new Error(`Invalid suspend payload: ${parseResult.error.message}`));
+                    return makeToolError(new Error(`Invalid suspend payload: ${parseResult.error}`));
                 }
                 toolResult.payload = parseResult.data;
             }
@@ -1036,8 +1206,17 @@ class AgentRuntime {
                 const error = new Error(`Tool ${toolName} has no resume schema`);
                 return makeToolError(error);
             }
-            const resumeSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(builtTool.resumeSchema);
-            return { outcome: 'suspended', payload: toolResult.payload, resumeSchema };
+            const resumeSchema = (0, zod_1.isZodSchema)(builtTool.resumeSchema)
+                ? (0, zod_to_json_schema_1.zodToJsonSchema)(builtTool.resumeSchema)
+                : builtTool.resumeSchema;
+            if (!resumeSchema) {
+                return makeToolError(new Error('Invalid resume schema'));
+            }
+            return {
+                outcome: 'suspended',
+                payload: toolResult.payload,
+                resumeSchema,
+            };
         }
         let actualResult = toolResult;
         let extractedSubAgentUsage;
@@ -1045,7 +1224,7 @@ class AgentRuntime {
             actualResult = toolResult.output;
             extractedSubAgentUsage = toolResult.subAgentUsage;
         }
-        this.emitEvent({
+        this.eventBus.emit({
             type: "tool_execution_end",
             toolCallId,
             toolName,
@@ -1055,8 +1234,7 @@ class AgentRuntime {
         const modelResult = builtTool.toModelOutput
             ? builtTool.toModelOutput(actualResult)
             : actualResult;
-        const toolResultMsg = (0, runtime_helpers_1.makeToolResultMessage)(toolCallId, toolName, modelResult);
-        list.addResponse([toolResultMsg]);
+        list.setToolCallResult(toolCallId, (0, json_value_1.toJsonValue)(modelResult));
         const customMessage = builtTool?.toMessage?.(actualResult);
         if (customMessage) {
             list.addResponse([customMessage]);
@@ -1069,30 +1247,42 @@ class AgentRuntime {
                 output: actualResult,
                 transformed: !!builtTool.toModelOutput,
             },
+            modelOutput: modelResult,
             subAgentUsage: extractedSubAgentUsage,
             customMessage,
-            message: toolResultMsg,
         };
     }
-    buildLoopContext() {
-        const wmTool = this.buildWorkingMemoryToolForRun(this.currentState.persistence);
+    buildLoopContext(execOptions) {
+        const wmTool = this.buildWorkingMemoryToolForRun(execOptions?.persistence);
         const allUserTools = wmTool
             ? [...(this.config.tools ?? []), wmTool]
             : (this.config.tools ?? []);
         const aiTools = (0, tool_adapter_1.toAiSdkTools)(allUserTools);
         const aiProviderTools = (0, tool_adapter_1.toAiSdkProviderTools)(this.config.providerTools);
         const allTools = { ...aiTools, ...aiProviderTools };
+        const model = (0, model_factory_1.createModel)(this.config.model);
         return {
-            model: (0, model_factory_1.createModel)(this.config.model),
+            model,
             toolMap: (0, tool_adapter_1.buildToolMap)(allUserTools),
             aiTools: allTools,
-            providerOptions: this.buildCallProviderOptions(this.executionOptions?.providerOptions),
+            providerOptions: this.buildCallProviderOptions(execOptions?.providerOptions),
             hasTools: Object.keys(allTools).length > 0,
             outputSpec: this.config.structuredOutput
                 ? ai_1.Output.object({ schema: this.config.structuredOutput })
                 : undefined,
+            effectiveInstructions: this.composeEffectiveInstructions(allUserTools),
         };
     }
+    composeEffectiveInstructions(tools) {
+        const fragments = tools
+            .map((t) => t.systemInstruction)
+            .filter((s) => typeof s === 'string' && s.trim().length > 0);
+        const userInstructions = this.config.instructions;
+        if (fragments.length === 0)
+            return userInstructions;
+        const block = `<built_in_rules>\n${fragments.map((f) => `- ${f}`).join('\n')}\n</built_in_rules>`;
+        return userInstructions ? `${block}\n\n${userInstructions}` : block;
+    }
     buildWorkingMemoryToolForRun(persistence) {
         const wmParams = this.resolveWorkingMemoryParams(persistence);
         if (!wmParams)
@@ -1103,31 +1293,30 @@ class AgentRuntime {
             persist: wmParams.persistFn,
         });
     }
-    async persistSuspension(pendingToolCalls, list, totalUsage) {
-        const executionOptions = this.executionOptions?.maxIterations !== undefined
-            ? { maxIterations: this.executionOptions.maxIterations }
-            : undefined;
+    async persistSuspension(pendingToolCalls, options, list, totalUsage, existingRunId) {
+        const runId = existingRunId ?? (0, run_state_1.generateRunId)();
+        const executionOptions = options?.maxIterations !== undefined ? { maxIterations: options.maxIterations } : undefined;
         const state = {
-            persistence: this.currentState.persistence,
+            persistence: options?.persistence,
             status: 'suspended',
             messageList: list.serialize(),
             pendingToolCalls,
             usage: totalUsage,
             executionOptions,
         };
-        await this.runState.suspend(this.runId, state);
+        await this.runState.suspend(runId, state);
         this.updateState({ status: 'suspended', pendingToolCalls, messageList: list.serialize() });
-        return this.runId;
+        return runId;
     }
-    async cleanupRun() {
-        if (this.runId) {
-            await this.runState.complete(this.runId);
+    async cleanupRun(runId) {
+        if (runId) {
+            await this.runState.complete(runId);
         }
     }
     emitTurnEnd(newMessages, toolResults) {
         const assistantMsg = newMessages.find((m) => 'role' in m && m.role === 'assistant');
         if (assistantMsg) {
-            this.emitEvent({ type: "turn_end", message: assistantMsg, toolResults });
+            this.eventBus.emit({ type: "turn_end", message: assistantMsg, toolResults });
         }
     }
     updateState(patch) {
@@ -1175,9 +1364,6 @@ class AgentRuntime {
             ...(wmParams.instruction !== undefined && { instruction: wmParams.instruction }),
         };
     }
-    emitEvent(data) {
-        this.eventBus.emit({ ...data, runId: this.runId });
-    }
     resolveWorkingMemoryParams(options) {
         if (!options)
             return null;