feat(contracts): expand AI service contract with streaming, tool calling, and conversation management

- Add AIToolDefinition, AIToolCall, AIToolResult types for tool calling protocol
- Add AIMessageWithTools extending AIMessage with 'tool' role and tool call fields
- Add AIRequestOptionsWithTools extending AIRequestOptions with tool definitions
- Add AIStreamEvent type for streaming chat completions
- Add streamChat optional method to IAIService interface
- Add AIConversation type and IAIConversationService interface for conversation CRUD
- Add comprehensive tests for all new types and interfaces

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/spec/src/contracts/ai-service.test.ts

@@ -1,5 +1,17 @@
 import { describe, it, expect } from 'vitest';
-import type { IAIService, AIMessage, AIResult } from './ai-service';
+import type {
+  IAIService,
+  AIMessage,
+  AIResult,
+  AIToolDefinition,
+  AIToolCall,
+  AIToolResult,
+  AIMessageWithTools,
+  AIRequestOptionsWithTools,
+  AIStreamEvent,
+  AIConversation,
+  IAIConversationService,
+} from './ai-service';
 
 describe('AI Service Contract', () => {
   it('should allow a minimal IAIService implementation with required methods', () => {
@@ -91,4 +103,320 @@ describe('AI Service Contract', () => {
     expect(models).toHaveLength(3);
     expect(models).toContain('gpt-4');
   });
+
+  // -----------------------------------------------------------------------
+  // Tool Calling Types
+  // -----------------------------------------------------------------------
+
+  describe('Tool Calling Types', () => {
+    it('should construct valid AIToolDefinition values', () => {
+      const tool: AIToolDefinition = {
+        name: 'get_weather',
+        description: 'Get current weather for a location',
+        parameters: {
+          type: 'object',
+          properties: { location: { type: 'string' } },
+          required: ['location'],
+        },
+      };
+
+      expect(tool.name).toBe('get_weather');
+      expect(tool.description).toBe('Get current weather for a location');
+      expect(tool.parameters).toBeDefined();
+    });
+
+    it('should construct valid AIToolCall values', () => {
+      const call: AIToolCall = {
+        id: 'call_abc123',
+        name: 'get_weather',
+        arguments: JSON.stringify({ location: 'London' }),
+      };
+
+      expect(call.id).toBe('call_abc123');
+      expect(JSON.parse(call.arguments)).toEqual({ location: 'London' });
+    });
+
+    it('should construct valid AIToolResult values', () => {
+      const result: AIToolResult = {
+        toolCallId: 'call_abc123',
+        content: '{"temp": 18, "unit": "celsius"}',
+      };
+
+      expect(result.toolCallId).toBe('call_abc123');
+      expect(result.isError).toBeUndefined();
+
+      const errorResult: AIToolResult = {
+        toolCallId: 'call_xyz',
+        content: 'Tool not found',
+        isError: true,
+      };
+
+      expect(errorResult.isError).toBe(true);
+    });
+
+    it('should support AIMessageWithTools for tool conversations', () => {
+      const assistantMsg: AIMessageWithTools = {
+        role: 'assistant',
+        content: '',
+        toolCalls: [
+          { id: 'call_1', name: 'get_weather', arguments: '{"location":"Paris"}' },
+        ],
+      };
+
+      expect(assistantMsg.toolCalls).toHaveLength(1);
+      expect(assistantMsg.toolCalls![0].name).toBe('get_weather');
+
+      const toolMsg: AIMessageWithTools = {
+        role: 'tool',
+        content: '{"temp": 22}',
+        toolCallId: 'call_1',
+      };
+
+      expect(toolMsg.role).toBe('tool');
+      expect(toolMsg.toolCallId).toBe('call_1');
+    });
+
+    it('should support AIRequestOptionsWithTools', () => {
+      const options: AIRequestOptionsWithTools = {
+        model: 'gpt-4',
+        temperature: 0.7,
+        tools: [
+          {
+            name: 'search',
+            description: 'Search the web',
+            parameters: { type: 'object', properties: {} },
+          },
+        ],
+        toolChoice: 'auto',
+      };
+
+      expect(options.tools).toHaveLength(1);
+      expect(options.toolChoice).toBe('auto');
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Streaming – streamChat
+  // -----------------------------------------------------------------------
+
+  describe('streamChat', () => {
+    it('should allow IAIService implementation with streamChat', () => {
+      const service: IAIService = {
+        chat: async () => ({ content: '' }),
+        complete: async () => ({ content: '' }),
+        async *streamChat(_messages, _options?) {
+          yield { type: 'text-delta', textDelta: 'Hello' } satisfies AIStreamEvent;
+          yield { type: 'finish', result: { content: 'Hello' } } satisfies AIStreamEvent;
+        },
+      };
+
+      expect(service.streamChat).toBeDefined();
+    });
+
+    it('should stream text-delta events', async () => {
+      const service: IAIService = {
+        chat: async () => ({ content: '' }),
+        complete: async () => ({ content: '' }),
+        async *streamChat() {
+          yield { type: 'text-delta' as const, textDelta: 'Hello' };
+          yield { type: 'text-delta' as const, textDelta: ' world' };
+          yield { type: 'finish' as const, result: { content: 'Hello world' } };
+        },
+      };
+
+      const events: AIStreamEvent[] = [];
+      for await (const event of service.streamChat!([], {})) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(3);
+      expect(events[0].type).toBe('text-delta');
+      expect(events[0].textDelta).toBe('Hello');
+      expect(events[2].type).toBe('finish');
+      expect(events[2].result?.content).toBe('Hello world');
+    });
+
+    it('should stream tool-call events', async () => {
+      const service: IAIService = {
+        chat: async () => ({ content: '' }),
+        complete: async () => ({ content: '' }),
+        async *streamChat() {
+          yield {
+            type: 'tool-call-delta' as const,
+            toolCall: { id: 'call_1', name: 'get_weather' },
+          };
+          yield {
+            type: 'tool-call' as const,
+            toolCall: { id: 'call_1', name: 'get_weather', arguments: '{"location":"NYC"}' },
+          };
+          yield { type: 'finish' as const, result: { content: '' } };
+        },
+      };
+
+      const events: AIStreamEvent[] = [];
+      for await (const event of service.streamChat!([], {})) {
+        events.push(event);
+      }
+
+      expect(events[0].type).toBe('tool-call-delta');
+      expect(events[1].toolCall?.arguments).toBe('{"location":"NYC"}');
+    });
+
+    it('should stream error events', async () => {
+      const service: IAIService = {
+        chat: async () => ({ content: '' }),
+        complete: async () => ({ content: '' }),
+        async *streamChat() {
+          yield { type: 'error' as const, error: 'Rate limit exceeded' };
+        },
+      };
+
+      const events: AIStreamEvent[] = [];
+      for await (const event of service.streamChat!([], {})) {
+        events.push(event);
+      }
+
+      expect(events[0].type).toBe('error');
+      expect(events[0].error).toBe('Rate limit exceeded');
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // IAIConversationService
+  // -----------------------------------------------------------------------
+
+  describe('IAIConversationService', () => {
+    function createMockConversationService(): IAIConversationService {
+      const store = new Map<string, AIConversation>();
+
+      return {
+        async create(options = {}) {
+          const now = new Date().toISOString();
+          const conv: AIConversation = {
+            id: `conv_${store.size + 1}`,
+            title: options.title,
+            agentId: options.agentId,
+            userId: options.userId,
+            messages: [],
+            createdAt: now,
+            updatedAt: now,
+            metadata: options.metadata,
+          };
+          store.set(conv.id, conv);
+          return conv;
+        },
+
+        async get(conversationId) {
+          return store.get(conversationId) ?? null;
+        },
+
+        async list(options = {}) {
+          let results = Array.from(store.values());
+          if (options.userId) {
+            results = results.filter((c) => c.userId === options.userId);
+          }
+          if (options.agentId) {
+            results = results.filter((c) => c.agentId === options.agentId);
+          }
+          if (options.limit) {
+            results = results.slice(0, options.limit);
+          }
+          return results;
+        },
+
+        async addMessage(conversationId, message) {
+          const conv = store.get(conversationId);
+          if (!conv) throw new Error('Conversation not found');
+          conv.messages.push(message);
+          conv.updatedAt = new Date().toISOString();
+          return conv;
+        },
+
+        async delete(conversationId) {
+          store.delete(conversationId);
+        },
+      };
+    }
+
+    it('should create a conversation', async () => {
+      const svc = createMockConversationService();
+      const conv = await svc.create({ title: 'Test Chat', userId: 'user_1' });
+
+      expect(conv.id).toBeDefined();
+      expect(conv.title).toBe('Test Chat');
+      expect(conv.userId).toBe('user_1');
+      expect(conv.messages).toHaveLength(0);
+      expect(conv.createdAt).toBeDefined();
+    });
+
+    it('should get a conversation by ID', async () => {
+      const svc = createMockConversationService();
+      const created = await svc.create({ title: 'Lookup Test' });
+
+      const found = await svc.get(created.id);
+      expect(found).not.toBeNull();
+      expect(found!.id).toBe(created.id);
+
+      const missing = await svc.get('nonexistent');
+      expect(missing).toBeNull();
+    });
+
+    it('should list conversations with filters', async () => {
+      const svc = createMockConversationService();
+      await svc.create({ userId: 'user_a', agentId: 'agent_1' });
+      await svc.create({ userId: 'user_b', agentId: 'agent_1' });
+      await svc.create({ userId: 'user_a', agentId: 'agent_2' });
+
+      const all = await svc.list();
+      expect(all).toHaveLength(3);
+
+      const byUser = await svc.list({ userId: 'user_a' });
+      expect(byUser).toHaveLength(2);
+
+      const byAgent = await svc.list({ agentId: 'agent_1' });
+      expect(byAgent).toHaveLength(2);
+
+      const limited = await svc.list({ limit: 1 });
+      expect(limited).toHaveLength(1);
+    });
+
+    it('should add messages to a conversation', async () => {
+      const svc = createMockConversationService();
+      const conv = await svc.create({ title: 'Message Test' });
+
+      const updated = await svc.addMessage(conv.id, {
+        role: 'user',
+        content: 'Hello!',
+      });
+
+      expect(updated.messages).toHaveLength(1);
+      expect(updated.messages[0].content).toBe('Hello!');
+
+      const updated2 = await svc.addMessage(conv.id, {
+        role: 'assistant',
+        content: 'Hi there!',
+      });
+
+      expect(updated2.messages).toHaveLength(2);
+    });
+
+    it('should delete a conversation', async () => {
+      const svc = createMockConversationService();
+      const conv = await svc.create({ title: 'Delete Me' });
+
+      await svc.delete(conv.id);
+      const result = await svc.get(conv.id);
+      expect(result).toBeNull();
+    });
+
+    it('should support metadata on conversations', async () => {
+      const svc = createMockConversationService();
+      const conv = await svc.create({
+        title: 'With Meta',
+        metadata: { source: 'web', tags: ['support'] },
+      });
+
+      expect(conv.metadata).toEqual({ source: 'web', tags: ['support'] });
+    });
+  });
 });