@falai/agent 2.6.1 → 3.0.0

package/src/core/ToolLoopExecutor.ts

@@ -18,15 +18,41 @@ import type {
     AgentOptions,
     AgentResponseStreamChunk,
     AgentStructuredResponse,
+    Directive,
     HistoryItem,
     SessionState,
     ToolCallRequest,
-} from "../types";
-import type { Flow } from "./Flow";
-import type { Step } from "./Step";
-import type { ToolManager } from "./ToolManager";
-import { ResponseGenerationError } from "./ResponseGenerationError";
-import { historyToEvents, logger, serializeToolResult, assistantMessage, toolMessage } from "../utils";
+} from "../types/index.js";
+import type { Flow } from "./Flow.js";
+import type { Step } from "./Step.js";
+import type { ToolManager } from "./ToolManager.js";
+import { ResponseGenerationError } from "./ResponseGenerationError.js";
+import { flow } from "./flow-namespace.js";
+import { historyToEvents, logger, serializeToolResult, assistantMessage, toolMessage } from "../utils/index.js";
+
+/**
+ * One attempted tool execution, keyed by CALL (not tool name): parallel or
+ * repeated calls to the same tool in one turn keep their own results instead
+ * of overwriting each other.
+ */
+interface ToolExecutionRecord {
+    requestId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    /** Which loop round produced this call (0 = the initial streamed batch). */
+    round: number;
+    /** Serialized result fed back to the model; set EVEN on failure. */
+    result?: string;
+}
+
+const executionFailure = (toolName: string, error: unknown): string =>
+    JSON.stringify({
+        success: false,
+        error: `${toolName}: ${error instanceof Error ? error.message : String(error)}`,
+    });
+
+const toolNotFoundFailure = (toolName: string): string =>
+    JSON.stringify({ success: false, error: `Tool "${toolName}" is not registered in any scope.` });
 
 export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
     constructor(
@@ -69,6 +95,8 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
         finalToolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
         finalMessage?: string;
         structured?: AgentStructuredResponse;
+        /** Directives emitted by tools this turn (ctx.dispatch / `{directive}` returns), merged. */
+        directives?: Directive<TContext, TData>;
     }> {
         try {
             const { context, history, selectedFlow, responsePrompt, availableTools, responseSchema, signal } = params;
@@ -77,22 +105,32 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             const { toolCalls } = params;
             let { session } = params;
 
+            // Directives emitted by tools this turn — consumed by the caller
+            const collectedDirectives: Directive<TContext, TData>[] = [];
+
             // Convert HistoryItem[] to Event[] for internal processing
             const historyEvents = historyToEvents(history);
 
-            // Map to store tool execution results for history
-            const toolResultsMap = new Map<string, string>();
-            // Map to store tool call arguments for history reconstruction
-            const toolArgsMap = new Map<string, Record<string, unknown>>();
+            // Execution records keyed by call — shared with the follow-up loop
+            const records: ToolExecutionRecord[] = [];
 
             // Execute initial dynamic tool calls
             if (toolCalls && toolCalls.length > 0) {
                 logger.debug(`[ToolLoopExecutor] Executing ${toolCalls.length} dynamic tool calls:`, toolCalls.map(tc => tc.toolName));
 
-                for (const toolCall of toolCalls) {
+                for (const [callIndex, toolCall] of toolCalls.entries()) {
+                    const record: ToolExecutionRecord = {
+                        requestId: `init-${callIndex}-${toolCall.toolName}`,
+                        toolName: toolCall.toolName,
+                        arguments: toolCall.arguments,
+                        round: 0,
+                    };
+                    records.push(record);
+
                     const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
                     if (!tool) {
-                        logger.warn(`[ToolExecutionError] Tool not found: "${toolCall.toolName}" is not registered in any scope. Skipping this tool call. Register the tool or check the tool name.`);
+                        logger.warn(`[ToolExecutionError] Tool not found: "${toolCall.toolName}" is not registered in any scope. Register the tool or check the tool name.`);
+                        record.result = toolNotFoundFailure(toolCall.toolName);
                         continue;
                     }
 
@@ -109,8 +147,12 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                         });
 
                         // Store the actual tool result data for history
-                        toolResultsMap.set(toolCall.toolName, serializeToolResult(toolResult));
-                        toolArgsMap.set(toolCall.toolName, toolCall.arguments);
+                        record.result = serializeToolResult(toolResult);
+
+                        // Collect tool-emitted directives (ctx.dispatch / {directive})
+                        if (toolResult.directives?.length) {
+                            collectedDirectives.push(...toolResult.directives as Directive<TContext, TData>[]);
+                        }
 
                         // Check if tool execution was successful
                         if (!toolResult.success) {
@@ -143,20 +185,37 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                         logger.debug(`[ToolLoopExecutor] Executed dynamic tool: ${toolCall.toolName} (success: ${toolResult.success})`);
                     } catch (error) {
                         logger.error(`[ToolLoopExecutor] Tool execution error for ${toolCall.toolName}:`, error);
-                        // Continue with other tools rather than failing the entire response
+                        // A thrown handler must be visible to the model as a FAILED
+                        // tool call — reporting success makes it confirm actions
+                        // that never happened.
+                        record.result = executionFailure(toolCall.toolName, error);
                         continue;
                     }
                 }
             }
 
+            // A tool spoke verbatim this turn: its reply IS the final message —
+            // skip the follow-up LLM call (documented dispatch semantics).
+            const preLoopDirectives = flow.mergeAll(collectedDirectives);
+            if (preLoopDirectives?.reply) {
+                logger.debug("[ToolLoopExecutor] Tool directive reply short-circuits follow-up LLM call");
+                return {
+                    session,
+                    finalToolCalls: toolCalls,
+                    finalMessage: preLoopDirectives.reply,
+                    structured: { message: preLoopDirectives.reply },
+                    directives: preLoopDirectives,
+                };
+            }
+
             // Hand off to the multi-round follow-up loop shared with the
             // streaming path. The initial batch above already executed
             // sequentially and populated the result maps.
             return await this.runFollowUpLoop({
                 toolCalls,
                 session,
-                toolResultsMap,
-                toolArgsMap,
+                records,
+                collectedDirectives,
                 context,
                 history,
                 selectedFlow,
@@ -186,8 +245,10 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
     private async runFollowUpLoop(params: {
         toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
         session: SessionState<TData>;
-        toolResultsMap: Map<string, string>;
-        toolArgsMap: Map<string, Record<string, unknown>>;
+        /** Execution records from prior rounds (initial batch = round 0). */
+        records: ToolExecutionRecord[];
+        /** Shared directive collector — initial-batch emissions land here too. */
+        collectedDirectives?: Directive<TContext, TData>[];
         context: TContext;
         history: HistoryItem[];
         selectedFlow?: Flow<TContext, TData>;
@@ -205,8 +266,9 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
         finalToolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
         finalMessage?: string;
         structured?: AgentStructuredResponse;
+        directives?: Directive<TContext, TData>;
     }> {
-        const { context, history, selectedFlow, responsePrompt, availableTools, responseSchema, signal, toolResultsMap, toolArgsMap } = params;
+        const { context, history, selectedFlow, responsePrompt, availableTools, responseSchema, signal, records, collectedDirectives = [] } = params;
         let { toolCalls, session } = params;
         try {
             // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution
@@ -222,45 +284,43 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                 toolLoopCount++;
                 logger.debug(`[ToolLoopExecutor] Starting tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS} with ${toolCalls?.length || 0} tool calls`);
 
-                // Create tool result history items
+                // Create tool result history items for the PREVIOUS round's
+                // calls. Failures are reported as failures — never as success.
+                const previousRound = toolLoopCount - 1;
+                const roundRecords = records.filter((r) => r.round === previousRound);
                 const toolResultHistoryItems: HistoryItem[] = [];
-                for (const toolCall of toolCalls || []) {
-                    const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
-                    if (tool) {
-                        // assistant tool_call + tool result pair, via the shared
-                        // history factories (same as forceFinalTextFromTools).
-                        toolResultHistoryItems.push(
-                            assistantMessage(null, [
-                                { id: toolCall.toolName, name: toolCall.toolName, arguments: toolCall.arguments },
-                            ]),
-                            toolMessage(
-                                toolCall.toolName,
-                                toolCall.toolName,
-                                toolResultsMap.get(toolCall.toolName) || "Tool executed successfully",
-                            ),
-                        );
-                    }
+                for (const record of roundRecords) {
+                    toolResultHistoryItems.push(
+                        assistantMessage(null, [
+                            { id: record.requestId, name: record.toolName, arguments: record.arguments },
+                        ]),
+                        toolMessage(
+                            record.toolName,
+                            record.requestId,
+                            record.result ?? toolNotFoundFailure(record.toolName),
+                        ),
+                    );
                 }
 
                 // Create updated history with tool results
                 const updatedHistory = [...history, ...toolResultHistoryItems];
 
-                // Make follow-up AI call to see if more tools are needed
-                // After first iteration, don't provide tools to force a text response
+                // Make follow-up AI call to see if more tools are needed.
+                // Tools are offered EVERY iteration — the loop is already bounded
+                // by MAX_TOOL_LOOPS, so withholding them after round  only made
+                // maxToolLoops values above 2 unreachable.
                 const agentOptions = this.deps.getAgentOptions();
-                const shouldProvideTools = toolLoopCount === 1;
 
                 logger.debug(`[ToolLoopExecutor] Making follow-up AI call (loop ${toolLoopCount}):`, {
-                    providingTools: shouldProvideTools,
-                    toolsCount: shouldProvideTools ? availableTools.length : 0,
-                    addingTextInstruction: toolLoopCount > 1,
+                    providingTools: true,
+                    toolsCount: availableTools.length,
                 });
 
                 const followUpResult = await agentOptions.provider.generateMessage({
-                    prompt: responsePrompt + (toolLoopCount > 1 ? "\n\nProvide a text response to the user based on the tool results." : ""),
+                    prompt: responsePrompt,
                     history: updatedHistory, // Use HistoryItem[] for AI provider
                     context,
-                    tools: shouldProvideTools ? availableTools : [], // Only provide tools on first iteration
+                    tools: availableTools,
                     parameters: responseSchema ? {
                         jsonSchema: responseSchema,
                         schemaName: "tool_followup",
@@ -284,10 +344,19 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                     logger.debug(`[ToolLoopExecutor] Follow-up call produced ${followUpToolCalls!.length} additional tool calls`);
 
                     // Execute the follow-up tool calls
-                    for (const toolCall of followUpToolCalls!) {
+                    for (const [callIndex, toolCall] of followUpToolCalls!.entries()) {
+                        const record: ToolExecutionRecord = {
+                            requestId: `fup-${toolLoopCount}-${callIndex}-${toolCall.toolName}`,
+                            toolName: toolCall.toolName,
+                            arguments: toolCall.arguments,
+                            round: toolLoopCount,
+                        };
+                        records.push(record);
+
                         const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
                         if (!tool) {
-                            logger.warn(`[ToolExecutionError] Tool not found in follow-up: "${toolCall.toolName}" is not registered in any scope. Skipping this tool call. Register the tool or check the tool name.`);
+                            logger.warn(`[ToolExecutionError] Tool not found in follow-up: "${toolCall.toolName}" is not registered in any scope. Register the tool or check the tool name.`);
+                            record.result = toolNotFoundFailure(toolCall.toolName);
                             continue;
                         }
 
@@ -328,16 +397,34 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                             }
 
                             // Store the follow-up tool result for potential next loop iteration
-                            toolResultsMap.set(toolCall.toolName, serializeToolResult(toolResult));
-                            toolArgsMap.set(toolCall.toolName, toolCall.arguments);
+                            record.result = serializeToolResult(toolResult);
+
+                            // Collect tool-emitted directives (ctx.dispatch / {directive})
+                            if (toolResult.directives?.length) {
+                                collectedDirectives.push(...toolResult.directives as Directive<TContext, TData>[]);
+                            }
 
                             logger.debug(`[ToolLoopExecutor] Executed follow-up tool: ${toolCall.toolName} (success: ${toolResult.success})`);
                         } catch (error) {
                             logger.error(`[ToolLoopExecutor] Follow-up tool execution error for ${toolCall.toolName}:`, error);
+                            // Visible failure beats a fabricated success.
+                            record.result = executionFailure(toolCall.toolName, error);
                             continue;
                         }
                     }
 
+                    // A tool emitted a verbatim reply this round: it IS the final
+                    // message — stop looping and skip any further LLM call.
+                    const roundDirectives = flow.mergeAll(collectedDirectives);
+                    if (roundDirectives?.reply) {
+                        logger.debug("[ToolLoopExecutor] Tool directive reply short-circuits remaining tool loop");
+                        finalMessage = roundDirectives.reply;
+                        followUpStructured = { message: roundDirectives.reply };
+                        hasToolCalls = false;
+                        toolCalls = undefined;
+                        break;
+                    }
+
                     // Update toolCalls for next iteration or final response
                     toolCalls = followUpToolCalls;
                 } else {
@@ -363,8 +450,7 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                 logger.debug(`[ToolLoopExecutor] No final message after tool loop, making additional LLM call for text response`);
                 const forced = await this.forceFinalTextFromTools({
                     history,
-                    toolResultsMap,
-                    toolArgsMap,
+                    records,
                     responsePrompt,
                     responseSchema,
                     context,
@@ -390,6 +476,7 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                 finalToolCalls: toolCalls,
                 finalMessage,
                 structured: followUpStructured,
+                directives: flow.mergeAll(collectedDirectives),
             };
         } catch (error) {
             throw ResponseGenerationError.fromError(error, 'tool_execution', params, {
@@ -408,24 +495,25 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
      */
     private async forceFinalTextFromTools(params: {
         history: HistoryItem[];
-        toolResultsMap: Map<string, string>;
-        toolArgsMap: Map<string, Record<string, unknown>>;
+        records: ToolExecutionRecord[];
         responsePrompt: string;
         responseSchema?: Record<string, unknown>;
         context: TContext;
         signal?: AbortSignal;
     }): Promise<{ finalMessage?: string; structured?: AgentStructuredResponse }> {
-        const { history, toolResultsMap, toolArgsMap, responsePrompt, responseSchema, context, signal } = params;
+        const { history, records, responsePrompt, responseSchema, context, signal } = params;
 
         // Reconstruct assistant tool_call + tool result pairs so the follow-up
-        // call can see what the tools returned.
+        // call can see what the tools returned — every executed call, keyed by
+        // its own request id.
         const finalToolResultHistoryItems: HistoryItem[] = [];
-        for (const [toolName, toolResult] of toolResultsMap) {
+        for (const record of records) {
+            if (!record.result) continue;
             finalToolResultHistoryItems.push(
                 assistantMessage(null, [
-                    { id: toolName, name: toolName, arguments: toolArgsMap.get(toolName) || {} },
+                    { id: record.requestId, name: record.toolName, arguments: record.arguments },
                 ]),
-                toolMessage(toolName, toolName, toolResult),
+                toolMessage(record.toolName, record.requestId, record.result),
             );
         }
 
@@ -494,12 +582,17 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             /** Closing message forced from the tool results, if one was generated. */
             finalMessage?: string;
             structured?: AgentStructuredResponse;
+            /** Directives emitted by tools this turn (ctx.dispatch / `{directive}` returns), merged. */
+            directives?: Directive<TContext, TData>;
         }
     > {
         const { context, history, selectedFlow, step, accumulated, responsePrompt, availableTools, responseSchema, signal } = params;
         let { session } = params;
         let toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }> | undefined = params.toolCalls;
 
+        // Directives emitted by tools this turn — surfaced to the caller
+        const collectedDirectives: Directive<TContext, TData>[] = [];
+
         // Use concurrent execution for the initial batch of tool calls
         const toolCallRequests: ToolCallRequest[] = params.toolCalls.map((tc, i) => ({
             id: `${tc.toolName}-${i}-${Date.now()}`,
@@ -508,9 +601,15 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
         }));
         // Map request id -> request so completed results can be attributed back
         // to their tool name/arguments for the forced final-text call.
-        const requestById = new Map(toolCallRequests.map((r) => [r.id, r]));
-        const toolResultsMap = new Map<string, string>();
-        const toolArgsMap = new Map<string, Record<string, unknown>>();
+        // Execution records keyed by call id — seeded at queue time so results
+        // (and failures) attach to the right call even for same-name calls.
+        const records: ToolExecutionRecord[] = toolCallRequests.map((req) => ({
+            requestId: req.id,
+            toolName: req.toolName,
+            arguments: req.arguments,
+            round: 0,
+        }));
+        const recordById = new Map(records.map((r) => [r.requestId, r]));
 
         const historyEvents = historyToEvents(history);
 
@@ -547,10 +646,13 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
 
                 // Capture tool results for the forced final-text call
                 if (update.result) {
-                    const req = requestById.get(update.toolCallId);
-                    if (req) {
-                        toolResultsMap.set(req.toolName, serializeToolResult(update.result));
-                        toolArgsMap.set(req.toolName, req.arguments);
+                    const record = recordById.get(update.toolCallId);
+                    if (record) {
+                        record.result = serializeToolResult(update.result);
+                    }
+                    // Collect tool-emitted directives (ctx.dispatch / {directive})
+                    if (update.result.directives?.length) {
+                        collectedDirectives.push(...update.result.directives as Directive<TContext, TData>[]);
                     }
                 }
 
@@ -578,8 +680,8 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             const followUp = await this.runFollowUpLoop({
                 toolCalls,
                 session,
-                toolResultsMap,
-                toolArgsMap,
+                records,
+                collectedDirectives,
                 context,
                 history,
                 selectedFlow,
@@ -593,21 +695,45 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             finalMessage = followUp.finalMessage;
             structured = followUp.structured;
         } catch (error) {
-            logger.error(`[ToolLoopExecutor] Concurrent tool execution failed, falling back to sequential:`, error);
-            // Fall back to the unified tool loop on failure. runLoop re-executes
-            // the tools from scratch, so any partial results collected above are
-            // intentionally discarded (it builds and forces its own).
-            const toolResult = await this.runLoop({
-                toolCalls, context, session, history, selectedFlow,
-                responsePrompt, availableTools, responseSchema, signal,
-            });
-            session = toolResult.session;
-            toolCalls = toolResult.finalToolCalls;
-            finalMessage = toolResult.finalMessage;
-            structured = toolResult.structured;
+            logger.error(`[ToolLoopExecutor] Concurrent batch failed:`, error);
+            const executedRecords = records.filter((r) => r.result !== undefined);
+            if (executedRecords.length > 0) {
+                // Some tools already executed — re-running them would duplicate
+                // real-world side effects (sends, writes, charges). Close the
+                // turn from the results we have instead.
+                logger.warn(
+                    `[ToolLoopExecutor] ${executedRecords.length} tool(s) already executed; closing the turn from their results rather than re-executing.`
+                );
+                const forced = await this.forceFinalTextFromTools({
+                    history,
+                    records,
+                    responsePrompt,
+                    responseSchema,
+                    context,
+                    signal,
+                });
+                if (forced.finalMessage) {
+                    finalMessage = forced.finalMessage;
+                }
+                structured = structured ?? forced.structured;
+            } else {
+                // Nothing executed — safe to fall back to the unified loop.
+                const toolResult = await this.runLoop({
+                    toolCalls, context, session, history, selectedFlow,
+                    responsePrompt, availableTools, responseSchema, signal,
+                });
+                session = toolResult.session;
+                toolCalls = toolResult.finalToolCalls;
+                finalMessage = toolResult.finalMessage;
+                structured = toolResult.structured;
+                if (toolResult.directives) {
+                    collectedDirectives.length = 0;
+                    collectedDirectives.push(toolResult.directives);
+                }
+            }
         }
 
-        return { session, toolCalls, finalMessage, structured };
+        return { session, toolCalls, finalMessage, structured, directives: flow.mergeAll(collectedDirectives) };
     }
 
     /**

package/src/core/ToolManager.ts

@@ -15,16 +15,16 @@ import type {
   ToolCallRequest,
   ToolExecutionUpdate,
   Event,
-} from "../types";
-import type { Directive } from "../types/flow";
-import { ToolScope } from "../types";
-import { logger } from "../utils";
+} from "../types/index.js";
+import type { Directive } from "../types/flow.js";
+import { ToolScope } from "../types/index.js";
+import { logger, isToolResultLike, extractResultDirectives } from "../utils/index.js";
 // Type-only import: ToolManager must not create a runtime cycle with Agent
-import type { Agent } from "./Agent";
-import { Flow } from "./Flow";
-import { Step } from "./Step";
-import { StreamingToolExecutor } from "./StreamingToolExecutor";
-import { evaluateToolGates } from "./toolGates";
+import type { Agent } from "./Agent.js";
+import { Flow } from "./Flow.js";
+import { Step } from "./Step.js";
+import { StreamingToolExecutor } from "./StreamingToolExecutor.js";
+import { evaluateToolGates } from "./toolGates.js";
 
 /**
  * Error thrown when tool creation fails
@@ -81,7 +81,7 @@ export class ToolManager<TContext = unknown, TData = unknown> {
    * Set the transient tool layer for the current turn.
    *
    * Accepts the merged `injectTools` array from pre-LLM emitters
-   * (already concatenated in outer-to-inner order by the DirectiveBus).
+   * (concatenated in outer-to-inner order).
    * Deduplicates by tool `id` with last-definition-wins.
    *
    * Must be paired with `clearTransientTools()` in a try/finally guard
@@ -678,6 +678,7 @@ export class ToolManager<TContext = unknown, TData = unknown> {
   }): Promise<ToolExecutionResult> {
     const { tool, context, updateContext, updateData, history, data, toolArguments } = params;
     const startTime = Date.now();
+      const executionTimeout = 30000; // 30 seconds default timeout
 
     try {
       // Validate tool before execution
@@ -725,24 +726,40 @@ export class ToolManager<TContext = unknown, TData = unknown> {
         return gateDenial;
       }
 
-      // Execute tool with timeout protection
-      const executionTimeout = 30000; // 30 seconds default timeout
+      // Execute tool with timeout protection. The timer is cleared when the
+      // race settles AND unref'd so a pending timer never delays process
+      // shutdown; a handler that loses the race keeps running detached (its
+      // result is discarded), which we surface in a warn.
+      let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
       const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error(`Tool execution timeout after ${executionTimeout}ms`)), executionTimeout);
+        timeoutTimer = setTimeout(
+          () => reject(new Error(`Tool execution timeout after ${executionTimeout}ms`)),
+          executionTimeout
+        );
+        timeoutTimer.unref?.();
       });
 
-      const result = await Promise.race([
-        tool.handler(toolContext, toolArguments),
-        timeoutPromise
-      ]);
+      let result: unknown;
+      try {
+        // Attach a no-op catch to the losing handler promise so a post-timeout
+        // rejection can't surface as an unhandled rejection and crash the process.
+        const handlerPromise = Promise.resolve(tool.handler(toolContext, toolArguments));
+        handlerPromise.catch(() => undefined);
+        result = await Promise.race([handlerPromise, timeoutPromise]);
+      } finally {
+        clearTimeout(timeoutTimer);
+      }
 
       const executionTime = Date.now() - startTime;
       logger.debug(`[ToolManager] Tool ${tool.id} completed in ${executionTime}ms`);
 
-      // Handle different result types
+      // Handle different result types. Only SEMANTIC markers identify a
+      // ToolResult — bare `{data}` / `{error}` shapes are indistinguishable
+      // from ordinary business payloads (e.g. upstream API envelopes) and are
+      // wrapped as raw results instead.
       let toolResult: ToolResult<unknown, TContext, TData>;
 
-      if (result && typeof result === 'object' && ('data' in result || 'success' in result || 'error' in result || 'directive' in result)) {
+      if (isToolResultLike(result)) {
         // It's already a ToolResult-like object
         toolResult = result as ToolResult<unknown, TContext, TData>;
       } else {
@@ -753,10 +770,9 @@ export class ToolManager<TContext = unknown, TData = unknown> {
         };
       }
 
-      // Collect directive from ToolResult.directive (if present)
-      if (toolResult.directive) {
-        collectedDirectives.push(toolResult.directive);
-      }
+      // Collect directives from the result — singular and plural forms both
+      // count, ordered identically to the concurrent executor.
+      collectedDirectives.push(...extractResultDirectives(toolResult));
 
       // Apply data updates from tool result with validation
       if (toolResult.dataUpdate) {
@@ -813,6 +829,15 @@ export class ToolManager<TContext = unknown, TData = unknown> {
       const executionTime = Date.now() - startTime;
 
       logger.error(`[ToolManager] Tool execution error for ${tool.id} after ${executionTime}ms:`, error);
+      if (error instanceof Error && error.message.includes("Tool execution timeout")) {
+        // The losing handler may still be running with captured callbacks.
+        // Its writes are NOT rolled back here — tools should stay idempotent
+        // or accept their own cancellation via interruptBehavior/abort.
+        logger.warn(
+          `[ToolManager] Handler for "${tool.id}" exceeded ${executionTimeout}ms and was abandoned while still running. ` +
+          `Its eventual side effects are not cancelled or rolled back.`
+        );
+      }
 
       // Re-throw the error so callers can handle it
       throw error;
@@ -871,9 +896,11 @@ export class ToolManager<TContext = unknown, TData = unknown> {
         return data != null && key in (data as Record<string, unknown>);
       },
       dispatch: (_directive: Directive<TContext, TData>): void => {
-        // Directives from concurrent execution are collected by the StreamingToolExecutor
-        // and surfaced via ToolExecutionUpdate. This is a no-op placeholder;
-        // full directive bus integration happens in ResponsePipeline (task 1.6).
+        // Handlers never see THIS context — StreamingToolExecutor.executeTool
+        // wraps each call in a per-call context whose dispatch attributes the
+        // directive to that tool. Reaching here means a gate or future caller
+        // dispatched outside a tool execution; surface it instead of dropping.
+        logger.warn("[ToolManager] ctx.dispatch called outside tool execution has no turn to attach to; directive dropped.");
       },
     };
 

package/src/core/createAgent.ts

@@ -18,8 +18,8 @@
  * **Validates: Requirements 14.1–14.7**
  */
 
-import { Agent } from "./Agent";
-import type { AgentOptions } from "../types";
+import { Agent } from "./Agent.js";
+import type { AgentOptions } from "../types/index.js";
 
 /**
  * Create an Agent from a single options object.