feat(service-ai): implement ObjectQL-backed persistent ConversationService

- Add ai_conversations and ai_messages system object definitions
- Implement ObjectQLConversationService using IDataEngine interface
- Update AIServicePlugin to auto-detect IDataEngine and select service
- Register AI system objects via plugin
- Update conversation/index.ts and src/index.ts exports
- Add 16 test cases for ObjectQLConversationService
- Update CHANGELOG.md

Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/ddfac0ae-2aa3-487e-945d-687d8e3bc7d5

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

Author: Copilot

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **`@objectstack/service-ai` — ObjectQL-backed persistent ConversationService** — New
+  `ObjectQLConversationService` implements `IAIConversationService` using `IDataEngine`
+  for durable conversation and message storage across service restarts:
+  - `ai_conversations` and `ai_messages` system object definitions (namespace `ai`)
+  - Full CRUD: `create`, `get`, `list` (with userId/agentId/limit/cursor filters),
+    `addMessage` (with toolCalls/toolCallId support), and `delete` (cascade)
+  - `AIServicePlugin` auto-detects `IDataEngine` in the kernel service registry and
+    uses `ObjectQLConversationService` when available, falling back to
+    `InMemoryConversationService` for dev/test environments
+  - `AIServicePluginOptions.conversationService` allows explicit override
+  - Plugin registers AI system objects via `app.com.objectstack.service-ai` service
+  - 16 new test cases covering all five interface methods plus edge cases
+
 ### Fixed
 - **ObjectQL build failure** — Fixed TypeScript TS2345 errors in `packages/objectql/src/protocol.ts`
   where `SchemaRegistry.registerItem()` calls failed type checking for the `keyField` parameter.

packages/services/service-ai/src/__tests__/objectql-conversation-service.test.ts

@@ -0,0 +1,306 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { IDataEngine } from '@objectstack/spec/contracts';
+import type { AIMessage } from '@objectstack/spec/contracts';
+import { ObjectQLConversationService } from '../conversation/objectql-conversation-service.js';
+
+// ─────────────────────────────────────────────────────────────────
+// In-memory IDataEngine stub (mimics driver-memory behavior)
+// ─────────────────────────────────────────────────────────────────
+
+function createMemoryEngine(): IDataEngine {
+  const tables = new Map<string, any[]>();
+
+  const getTable = (name: string) => {
+    if (!tables.has(name)) tables.set(name, []);
+    return tables.get(name)!;
+  };
+
+  return {
+    find: async (objectName, query?) => {
+      let rows = [...getTable(objectName)];
+      if (query?.where) {
+        rows = rows.filter(row => {
+          for (const [key, value] of Object.entries(query.where as Record<string, any>)) {
+            if (typeof value === 'object' && value !== null && '$gt' in value) {
+              if (!(row[key] > value.$gt)) return false;
+            } else if (row[key] !== value) {
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+      if (query?.orderBy) {
+        for (const sort of [...query.orderBy].reverse()) {
+          const field = (sort as any).field;
+          const dir = (sort as any).order === 'desc' ? -1 : 1;
+          rows.sort((a, b) => (a[field] < b[field] ? -dir : a[field] > b[field] ? dir : 0));
+        }
+      }
+      if (query?.limit) {
+        rows = rows.slice(0, query.limit);
+      }
+      return rows;
+    },
+    findOne: async (objectName, query?) => {
+      let rows = [...getTable(objectName)];
+      if (query?.where) {
+        rows = rows.filter(row => {
+          for (const [key, value] of Object.entries(query.where as Record<string, any>)) {
+            if (typeof value === 'object' && value !== null && '$gt' in value) {
+              if (!(row[key] > value.$gt)) return false;
+            } else if (row[key] !== value) {
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+      return rows[0] ?? null;
+    },
+    insert: async (objectName, data) => {
+      const table = getTable(objectName);
+      if (Array.isArray(data)) {
+        table.push(...data);
+        return data;
+      }
+      table.push({ ...data });
+      return data;
+    },
+    update: async (objectName, data, options?) => {
+      const table = getTable(objectName);
+      const where = options?.where as Record<string, any> | undefined;
+      for (let i = 0; i < table.length; i++) {
+        if (where) {
+          let match = true;
+          for (const [key, value] of Object.entries(where)) {
+            if (table[i][key] !== value) { match = false; break; }
+          }
+          if (!match) continue;
+        }
+        Object.assign(table[i], data);
+        return table[i];
+      }
+      return data;
+    },
+    delete: async (objectName, options?) => {
+      const table = getTable(objectName);
+      const where = options?.where as Record<string, any> | undefined;
+      let deleted = 0;
+      const multi = (options as any)?.multi ?? false;
+      for (let i = table.length - 1; i >= 0; i--) {
+        if (where) {
+          let match = true;
+          for (const [key, value] of Object.entries(where)) {
+            if (table[i][key] !== value) { match = false; break; }
+          }
+          if (!match) continue;
+        }
+        table.splice(i, 1);
+        deleted++;
+        if (!multi) break;
+      }
+      return { deleted };
+    },
+    count: async (objectName, query?) => {
+      let rows = [...getTable(objectName)];
+      if (query?.where) {
+        rows = rows.filter(row => {
+          for (const [key, value] of Object.entries(query.where as Record<string, any>)) {
+            if (row[key] !== value) return false;
+          }
+          return true;
+        });
+      }
+      return rows.length;
+    },
+    aggregate: async () => [],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────
+
+describe('ObjectQLConversationService', () => {
+  let engine: IDataEngine;
+  let service: ObjectQLConversationService;
+
+  beforeEach(() => {
+    engine = createMemoryEngine();
+    service = new ObjectQLConversationService(engine);
+  });
+
+  // ── create() ───────────────────────────────────────────────────
+
+  it('should create a conversation with all options', async () => {
+    const conv = await service.create({
+      title: 'Test Chat',
+      agentId: 'agent_1',
+      userId: 'user_1',
+      metadata: { source: 'web' },
+    });
+
+    expect(conv.id).toMatch(/^conv_/);
+    expect(conv.title).toBe('Test Chat');
+    expect(conv.agentId).toBe('agent_1');
+    expect(conv.userId).toBe('user_1');
+    expect(conv.messages).toEqual([]);
+    expect(conv.createdAt).toBeDefined();
+    expect(conv.updatedAt).toBeDefined();
+    expect(conv.metadata).toEqual({ source: 'web' });
+  });
+
+  it('should create a conversation with no options', async () => {
+    const conv = await service.create();
+
+    expect(conv.id).toMatch(/^conv_/);
+    expect(conv.title).toBeUndefined();
+    expect(conv.agentId).toBeUndefined();
+    expect(conv.userId).toBeUndefined();
+    expect(conv.messages).toEqual([]);
+  });
+
+  it('should generate unique conversation IDs', async () => {
+    const c1 = await service.create({ title: 'A' });
+    const c2 = await service.create({ title: 'B' });
+
+    expect(c1.id).not.toBe(c2.id);
+  });
+
+  // ── get() ──────────────────────────────────────────────────────
+
+  it('should retrieve a conversation by ID', async () => {
+    const created = await service.create({ title: 'Retrieve Me' });
+    const fetched = await service.get(created.id);
+
+    expect(fetched).not.toBeNull();
+    expect(fetched!.id).toBe(created.id);
+    expect(fetched!.title).toBe('Retrieve Me');
+  });
+
+  it('should return null for non-existent conversation', async () => {
+    const result = await service.get('conv_nonexistent');
+    expect(result).toBeNull();
+  });
+
+  // ── list() ─────────────────────────────────────────────────────
+
+  it('should list conversations filtered by userId', async () => {
+    await service.create({ userId: 'user_a' });
+    await service.create({ userId: 'user_b' });
+    await service.create({ userId: 'user_a' });
+
+    const results = await service.list({ userId: 'user_a' });
+    expect(results).toHaveLength(2);
+    results.forEach(c => expect(c.userId).toBe('user_a'));
+  });
+
+  it('should list conversations filtered by agentId', async () => {
+    await service.create({ agentId: 'bot_x' });
+    await service.create({ agentId: 'bot_y' });
+
+    const results = await service.list({ agentId: 'bot_x' });
+    expect(results).toHaveLength(1);
+    expect(results[0].agentId).toBe('bot_x');
+  });
+
+  it('should limit the number of listed conversations', async () => {
+    await service.create({ title: '1' });
+    await service.create({ title: '2' });
+    await service.create({ title: '3' });
+
+    const results = await service.list({ limit: 2 });
+    expect(results).toHaveLength(2);
+  });
+
+  // ── addMessage() ───────────────────────────────────────────────
+
+  it('should add a user message to a conversation', async () => {
+    const conv = await service.create({ title: 'Chat' });
+
+    const msg: AIMessage = { role: 'user', content: 'Hello AI!' };
+    const updated = await service.addMessage(conv.id, msg);
+
+    expect(updated.messages).toHaveLength(1);
+    expect(updated.messages[0].role).toBe('user');
+    expect(updated.messages[0].content).toBe('Hello AI!');
+    expect(updated.updatedAt >= conv.updatedAt).toBe(true);
+  });
+
+  it('should add a tool message with toolCallId', async () => {
+    const conv = await service.create();
+    const msg: AIMessage = {
+      role: 'tool',
+      content: '{"temp": 22}',
+      toolCallId: 'call_abc',
+    };
+
+    const updated = await service.addMessage(conv.id, msg);
+    expect(updated.messages).toHaveLength(1);
+    expect(updated.messages[0].toolCallId).toBe('call_abc');
+  });
+
+  it('should add an assistant message with toolCalls', async () => {
+    const conv = await service.create();
+    const msg: AIMessage = {
+      role: 'assistant',
+      content: '',
+      toolCalls: [{ id: 'call_1', name: 'get_weather', arguments: '{}' }],
+    };
+
+    const updated = await service.addMessage(conv.id, msg);
+    expect(updated.messages).toHaveLength(1);
+    expect(updated.messages[0].toolCalls).toHaveLength(1);
+    expect(updated.messages[0].toolCalls![0].name).toBe('get_weather');
+  });
+
+  it('should throw when adding message to non-existent conversation', async () => {
+    const msg: AIMessage = { role: 'user', content: 'Hello' };
+    await expect(service.addMessage('conv_ghost', msg)).rejects.toThrow(
+      'Conversation "conv_ghost" not found',
+    );
+  });
+
+  it('should preserve message order (ordered by createdAt)', async () => {
+    const conv = await service.create();
+    await service.addMessage(conv.id, { role: 'user', content: 'First' });
+    await service.addMessage(conv.id, { role: 'assistant', content: 'Second' });
+    await service.addMessage(conv.id, { role: 'user', content: 'Third' });
+
+    const fetched = await service.get(conv.id);
+    expect(fetched!.messages).toHaveLength(3);
+    expect(fetched!.messages[0].content).toBe('First');
+    expect(fetched!.messages[1].content).toBe('Second');
+    expect(fetched!.messages[2].content).toBe('Third');
+  });
+
+  // ── delete() ───────────────────────────────────────────────────
+
+  it('should delete a conversation and its messages', async () => {
+    const conv = await service.create({ title: 'Delete Me' });
+    await service.addMessage(conv.id, { role: 'user', content: 'Bye' });
+
+    await service.delete(conv.id);
+
+    const result = await service.get(conv.id);
+    expect(result).toBeNull();
+  });
+
+  it('should handle deleting a non-existent conversation gracefully', async () => {
+    // Should not throw
+    await expect(service.delete('conv_missing')).resolves.toBeUndefined();
+  });
+
+  // ── metadata serialization round-trip ──────────────────────────
+
+  it('should round-trip metadata through JSON serialization', async () => {
+    const metadata = { tags: ['important', 'follow-up'], priority: 1 };
+    const conv = await service.create({ metadata });
+
+    const fetched = await service.get(conv.id);
+    expect(fetched!.metadata).toEqual(metadata);
+  });
+});

packages/services/service-ai/src/conversation/index.ts

@@ -1,3 +1,4 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export { InMemoryConversationService } from './in-memory-conversation-service.js';
+export { ObjectQLConversationService } from './objectql-conversation-service.js';