feat: add tool execution timeout guard

.changeset/tool-timeout-guard.md

@@ -0,0 +1,6 @@
+---
+'@chatcops/core': patch
+'@chatcops/server': patch
+---
+
+Add a configurable timeout guard for tool execution so hanging tools fail gracefully instead of blocking provider responses indefinitely.

packages/core/src/providers/tool-execution.ts

@@ -1,6 +1,7 @@
 import type { ProviderChatParams, ProviderToolCall, ToolResult } from '../types.js';
 
 export const MAX_TOOL_ROUNDS = 5;
+export const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
 
 export function parseToolInput(rawInput: string): Record<string, unknown> {
   if (!rawInput.trim()) return {};
@@ -45,9 +46,27 @@ export async function executeToolCall(
     };
   }
 
+  const timeoutMs = params.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+  const timers = globalThis as typeof globalThis & {
+    setTimeout: (callback: () => void, delay?: number) => unknown;
+    clearTimeout: (timeoutId: unknown) => void;
+  };
+  let timeoutId: unknown;
+
   try {
-    return await params.toolExecutor(call);
+    return await Promise.race([
+      params.toolExecutor(call),
+      new Promise<never>((_, reject) => {
+        timeoutId = timers.setTimeout(() => {
+          reject(new Error(`Tool execution timed out after ${timeoutMs}ms.`));
+        }, timeoutMs);
+      }),
+    ]);
   } catch (error) {
     return toToolFailure(error);
+  } finally {
+    if (timeoutId !== undefined) {
+      timers.clearTimeout(timeoutId);
+    }
   }
 }

packages/core/src/types.ts

@@ -88,6 +88,7 @@ export interface ProviderChatParams {
   systemPrompt: string;
   tools?: ToolDefinition[];
   toolExecutor?: ProviderToolExecutor;
+  toolTimeoutMs?: number;
   maxTokens?: number;
   temperature?: number;
 }

packages/core/tests/providers/tool-execution.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { executeToolCall } from '../../src/providers/tool-execution.js';
+import type { ProviderChatParams, ProviderToolCall, ToolResult } from '../../src/types.js';
+
+function createParams(overrides?: Partial<ProviderChatParams>): ProviderChatParams {
+  return {
+    messages: [{ id: '1', role: 'user', content: 'Check order 123', timestamp: Date.now() }],
+    systemPrompt: 'You are helpful.',
+    ...overrides,
+  };
+}
+
+const toolCall: ProviderToolCall = {
+  id: 'call_1',
+  name: 'lookup_order',
+  input: { orderId: '123' },
+};
+
+function createHangingToolExecutor(): NonNullable<ProviderChatParams['toolExecutor']> {
+  return vi.fn().mockImplementation(
+    () => new Promise<ToolResult>(() => undefined)
+  ) as NonNullable<ProviderChatParams['toolExecutor']>;
+}
+
+describe('executeToolCall', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns a failure result when tool execution exceeds the timeout', async () => {
+    vi.useFakeTimers();
+
+    const resultPromise = executeToolCall(
+      createParams({
+        toolTimeoutMs: 50,
+        toolExecutor: createHangingToolExecutor(),
+      }),
+      toolCall
+    );
+
+    await vi.advanceTimersByTimeAsync(50);
+
+    await expect(resultPromise).resolves.toEqual({
+      success: false,
+      message: 'Tool execution timed out after 50ms.',
+    });
+  });
+
+  it('returns the tool result when execution completes before the timeout', async () => {
+    vi.useFakeTimers();
+
+    const expectedResult: ToolResult = {
+      success: true,
+      data: { status: 'shipped' },
+      message: 'Order found',
+    };
+
+    const result = await executeToolCall(
+      createParams({
+        toolTimeoutMs: 50,
+        toolExecutor: vi.fn().mockResolvedValue(expectedResult),
+      }),
+      toolCall
+    );
+
+    expect(result).toEqual(expectedResult);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('uses the configured timeout value', async () => {
+    vi.useFakeTimers();
+
+    const resultPromise = executeToolCall(
+      createParams({
+        toolTimeoutMs: 10,
+        toolExecutor: createHangingToolExecutor(),
+      }),
+      toolCall
+    );
+
+    await vi.advanceTimersByTimeAsync(9);
+    await expect(Promise.race([resultPromise, Promise.resolve('pending')])).resolves.toBe('pending');
+
+    await vi.advanceTimersByTimeAsync(1);
+    await expect(resultPromise).resolves.toEqual({
+      success: false,
+      message: 'Tool execution timed out after 10ms.',
+    });
+  });
+});

packages/server/src/config.ts

@@ -5,6 +5,7 @@ export interface ChatCopsServerConfig {
   provider: ProviderConfig;
   systemPrompt: string;
   tools?: ChatTool[];
+  toolTimeoutMs?: number;
   knowledge?: KnowledgeSource[];
   rateLimit?: { maxRequests: number; windowMs: number };
   webhooks?: WebhookConfig[];

packages/server/src/handler.ts

@@ -109,6 +109,7 @@ export function createChatHandler(config: ChatCopsServerConfig) {
         messages,
         systemPrompt,
         tools: toolDefs.length > 0 ? toolDefs : undefined,
+        toolTimeoutMs: config.toolTimeoutMs,
         toolExecutor: async (toolCall) => {
           const tool = toolsByName.get(toolCall.name);
           if (!tool) {

packages/server/tests/handler.test.ts

@@ -1,10 +1,96 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-vi.mock('@chatcops/core', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@chatcops/core')>();
+vi.mock('@chatcops/core', () => {
+  class ConversationManager {
+    private readonly conversations = new Map<
+      string,
+      {
+        id: string;
+        messages: Array<{
+          id: string;
+          role: 'user' | 'assistant' | 'system';
+          content: string;
+          timestamp: number;
+          metadata?: Record<string, unknown>;
+        }>;
+        metadata?: Record<string, unknown>;
+        createdAt: number;
+        updatedAt: number;
+      }
+    >();
+
+    async getOrCreate(id: string) {
+      const existing = this.conversations.get(id);
+      if (existing) {
+        return existing;
+      }
+
+      const now = Date.now();
+      const conversation = {
+        id,
+        messages: [],
+        createdAt: now,
+        updatedAt: now,
+      };
+      this.conversations.set(id, conversation);
+      return conversation;
+    }
+
+    async addMessage(conversationId: string, message: {
+      id: string;
+      role: 'user' | 'assistant' | 'system';
+      content: string;
+      timestamp: number;
+      metadata?: Record<string, unknown>;
+    }) {
+      const conversation = await this.getOrCreate(conversationId);
+      conversation.messages.push(message);
+      conversation.updatedAt = Date.now();
+    }
+
+    async getMessages(conversationId: string) {
+      const conversation = await this.getOrCreate(conversationId);
+      return [...conversation.messages];
+    }
+  }
+
+  class AnalyticsCollector {
+    private totalConversations = 0;
+    private leadsCapture = 0;
+
+    track(event: string) {
+      if (event === 'conversation:started') {
+        this.totalConversations += 1;
+      }
+
+      if (event === 'lead:captured') {
+        this.leadsCapture += 1;
+      }
+    }
+
+    getStats() {
+      return {
+        totalConversations: this.totalConversations,
+        leadsCapture: this.leadsCapture,
+      };
+    }
+  }
+
   return {
-    ...actual,
     createProvider: vi.fn(),
+    ConversationManager,
+    AnalyticsCollector,
+    toolToDefinition: (tool: {
+      name: string;
+      description: string;
+      parameters: Record<string, { type: 'string' | 'number' | 'boolean'; description: string; enum?: string[] }>;
+      required: string[];
+    }) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+      required: tool.required,
+    }),
   };
 });
 
@@ -96,6 +182,37 @@ describe('createChatHandler', () => {
     ]);
   });
 
+  it('passes the configured tool timeout into the provider chat params', async () => {
+    const receivedTimeouts: Array<number | undefined> = [];
+
+    mockedCreateProvider.mockResolvedValue({
+      name: 'test-provider',
+      async *chat(params) {
+        receivedTimeouts.push(params.toolTimeoutMs);
+        yield 'Configured timeout received.';
+      },
+      async chatSync() {
+        return '';
+      },
+    });
+
+    const { handleChat } = createChatHandler({
+      provider: { type: 'openai', apiKey: 'test-key' },
+      systemPrompt: 'Test',
+      cors: '*',
+      toolTimeoutMs: 2_500,
+    });
+
+    for await (const _chunk of handleChat({
+      conversationId: 'conv-timeout',
+      message: 'Hello',
+    })) {
+      // Drain the stream.
+    }
+
+    expect(receivedTimeouts).toEqual([2_500]);
+  });
+
   it('tracks lead capture analytics when a tool succeeds', async () => {
     const leadTool = {
       name: 'capture_lead',