Align AI chat protocol with Vercel AI SDK — remove custom types and schemas

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **AI Chat Protocol Aligned with Vercel AI SDK** — Removed custom AI chat protocol
+ types and Zod schemas (`AIMessage`, `AIToolCall`, `AIStreamEvent`,
+ `AiChatRequestSchema`, `AiChatResponseSchema`) from `@objectstack/spec`. The
+ canonical message, tool-call, and streaming types are now re-exported from the
+ Vercel AI SDK (`ai` v6):
+ - `ModelMessage` replaces `AIMessage`
+ - `ToolCallPart` replaces `AIToolCall`
+ - `ToolResultPart` replaces `AIToolResult`
+ - `TextStreamPart<ToolSet>` replaces `AIStreamEvent`
+ - `IAIService` and `LLMAdapter` method signatures now accept `ModelMessage[]`
+ and return `TextStreamPart<ToolSet>` for streaming
+ - Deprecated type aliases preserved for migration convenience
+ - NLQ, Suggest, and Insights protocols (ObjectStack-specific) are retained
+- **`@objectstack/service-ai` migrated to Vercel AI SDK types** — All source files
+ and tests now use canonical Vercel types (`ModelMessage`, `ToolCallPart`,
+ `ToolResultPart`, `TextStreamPart<ToolSet>`) instead of deprecated aliases:
+ - `ToolRegistry.execute()` accepts `ToolCallPart` and returns `ToolExecutionResult`
+ (extends `ToolResultPart` with `isError?: boolean`)
+ - Tool call loop in `AIService.chatWithTools()` constructs proper
+ `AssistantModelMessage` and `ToolModelMessage` with Vercel-format content arrays
+ - `MemoryLLMAdapter.streamChat()` emits Vercel `TextStreamPart<ToolSet>` events
+ - Conversation services serialize/deserialize `ModelMessage` union to flat DB columns
+ - All 158 service-ai tests updated and passing
+
+### Removed
+- `AiChatRequestSchema` / `AiChatResponseSchema` Zod schemas from
+ `@objectstack/spec/api` — the AI chat wire protocol now uses Vercel AI SDK's
+ data stream format (`toDataStreamResponse()`)
+- `aiChat` method from `IObjectStackAPI` and client SDK — consumers should use
+ `@ai-sdk/react/useChat` directly
+- AI `/chat` endpoint from `DEFAULT_AI_ROUTES` plugin REST API definition
+
+### Added
+- `ai` v6 as a dependency of `@objectstack/spec` for type re-exports
+
 ## [4.0.1] — 2026-03-31
 
 ### Fixed

ROADMAP.md

@@ -1,6 +1,6 @@
 # ObjectStack Protocol — Road Map
 
-> **Last Updated:** 2026-03-31
+> **Last Updated:** 2026-04-01
 > **Current Version:** v4.0.1 
 > **Status:** Protocol Specification Complete · Runtime Implementation In Progress
 

content/docs/references/api/protocol.mdx

@@ -36,39 +36,13 @@ Architecture Alignment:
 ## TypeScript Usage
 
 ```typescript
-import { AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetViewRequest, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
-import type { AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetViewRequest, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
+import { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetViewRequest, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
+import type { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetViewRequest, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
 
 // Validate data
-const result = AiChatRequest.parse(data);
+const result = AiNlqRequest.parse(data);
 ```
 
----
-
-## AiChatRequest
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **message** | `string` | ✅ | User message |
-| **conversationId** | `string` | optional | Conversation ID for context |
-| **context** | `Record<string, any>` | optional | Additional context data |
-
-
----
-
-## AiChatResponse
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **message** | `string` | ✅ | Assistant response message |
-| **conversationId** | `string` | ✅ | Conversation ID |
-| **actions** | `Object[]` | optional | Suggested actions |
-
-
 ---
 
 ## AiInsightsRequest

packages/client/src/index.ts

@@ -62,8 +62,6 @@ import {
  MarkAllNotificationsReadResponse,
  AiNlqRequest,
  AiNlqResponse,
- AiChatRequest,
- AiChatResponse,
  AiSuggestRequest,
  AiSuggestResponse,
  AiInsightsRequest,
@@ -1209,17 +1207,7 @@ export class ObjectStackClient {
  return this.unwrapResponse<AiNlqResponse>(res);
  },
 
- /**
- * Multi-turn AI chat
- */
- chat: async (request: AiChatRequest): Promise<AiChatResponse> => {
- const route = this.getRoute('ai');
- const res = await this.fetch(`${this.baseUrl}${route}/chat`, {
- method: 'POST',
- body: JSON.stringify(request)
- });
- return this.unwrapResponse<AiChatResponse>(res);
- },
+ // AI chat method removed — use Vercel AI SDK `useChat()` / `@ai-sdk/react` directly.
 
  /**
  * AI-powered field value suggestions
@@ -1826,8 +1814,6 @@ export type {
  ListNotificationsResponse,
  AiNlqRequest,
  AiNlqResponse,
- AiChatRequest,
- AiChatResponse,
  AiSuggestRequest,
  AiSuggestResponse,
  AiInsightsRequest,

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

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { AIMessage, IAIService, AIStreamEvent } from '@objectstack/spec/contracts';
+import type { ModelMessage, IAIService, TextStreamPart, ToolSet } from '@objectstack/spec/contracts';
 import { AIService } from '../ai-service.js';
 import { MemoryLLMAdapter } from '../adapters/memory-adapter.js';
 import { ToolRegistry } from '../tools/tool-registry.js';
@@ -35,7 +35,7 @@ describe('MemoryLLMAdapter', () => {
  });
 
  it('should echo the last user message in chat()', async () => {
- const messages: AIMessage[] = [
+ const messages: ModelMessage[] = [
  { role: 'system', content: 'You are helpful.' },
  { role: 'user', content: 'Hello AI' },
  ];
@@ -46,7 +46,7 @@ describe('MemoryLLMAdapter', () => {
  });
 
  it('should handle no user message in chat()', async () => {
- const messages: AIMessage[] = [{ role: 'system', content: 'System only' }];
+ const messages: ModelMessage[] = [{ role: 'system', content: 'System only' }];
  const result = await adapter.chat(messages);
  expect(result.content).toBe('[memory] (no user message)');
  });
@@ -57,8 +57,8 @@ describe('MemoryLLMAdapter', () => {
  });
 
  it('should stream word-by-word in streamChat()', async () => {
- const messages: AIMessage[] = [{ role: 'user', content: 'Hi there' }];
- const events: AIStreamEvent[] = [];
+ const messages: ModelMessage[] = [{ role: 'user', content: 'Hi there' }];
+ const events: TextStreamPart<ToolSet>[] = [];
  for await (const event of adapter.streamChat(messages)) {
  events.push(event);
  }
@@ -113,24 +113,26 @@ describe('ToolRegistry', () => {
  );
 
  const result = await registry.execute({
- id: 'call_1',
- name: 'add',
- arguments: JSON.stringify({ a: 3, b: 4 }),
+ type: 'tool-call',
+ toolCallId: 'call_1',
+ toolName: 'add',
+ input: { a: 3, b: 4 },
  });
 
  expect(result.toolCallId).toBe('call_1');
- expect(result.content).toBe('7');
+ expect(result.output).toEqual({ type: 'text', value: '7' });
  expect(result.isError).toBeUndefined();
  });
 
  it('should return error for unknown tool', async () => {
  const result = await registry.execute({
- id: 'call_x',
- name: 'unknown',
- arguments: '{}',
+ type: 'tool-call',
+ toolCallId: 'call_x',
+ toolName: 'unknown',
+ input: {},
  });
  expect(result.isError).toBe(true);
- expect(result.content).toContain('not registered');
+ expect(result.output).toEqual(expect.objectContaining({ type: 'text', value: expect.stringContaining('not registered') }));
  });
 
  it('should return error on handler failure', async () => {
@@ -140,12 +142,13 @@ describe('ToolRegistry', () => {
  );
 
  const result = await registry.execute({
- id: 'call_f',
- name: 'fail_tool',
- arguments: '{}',
+ type: 'tool-call',
+ toolCallId: 'call_f',
+ toolName: 'fail_tool',
+ input: {},
  });
  expect(result.isError).toBe(true);
- expect(result.content).toBe('boom');
+ expect(result.output).toEqual({ type: 'text', value: 'boom' });
  });
 
  it('should execute multiple tool calls in parallel', async () => {
@@ -155,13 +158,13 @@ describe('ToolRegistry', () => {
  );
 
  const results = await registry.executeAll([
- { id: 'c1', name: 'echo', arguments: '{"msg":"a"}' },
- { id: 'c2', name: 'echo', arguments: '{"msg":"b"}' },
+ { type: 'tool-call', toolCallId: 'c1', toolName: 'echo', input: { msg: 'a' } },
+ { type: 'tool-call', toolCallId: 'c2', toolName: 'echo', input: { msg: 'b' } },
  ]);
 
  expect(results).toHaveLength(2);
- expect(results[0].content).toBe('a');
- expect(results[1].content).toBe('b');
+ expect(results[0].output).toEqual({ type: 'text', value: 'a' });
+ expect(results[1].output).toEqual({ type: 'text', value: 'b' });
  });
 
  it('should return all definitions', () => {
@@ -272,7 +275,7 @@ describe('AIService', () => {
 
  it('should stream via adapter.streamChat()', async () => {
  const service = new AIService({ logger: silentLogger });
- const events: AIStreamEvent[] = [];
+ const events: TextStreamPart<ToolSet>[] = [];
  for await (const event of service.streamChat([{ role: 'user', content: 'Hi' }])) {
  events.push(event);
  }
@@ -289,14 +292,14 @@ describe('AIService', () => {
  };
  const service = new AIService({ adapter, logger: silentLogger });
 
- const events: AIStreamEvent[] = [];
+ const events: TextStreamPart<ToolSet>[] = [];
  for await (const event of service.streamChat([{ role: 'user', content: 'Hi' }])) {
  events.push(event);
  }
 
  expect(events).toHaveLength(2);
  expect(events[0].type).toBe('text-delta');
- expect(events[0].textDelta).toBe('response');
+ expect(events[0].type === 'text-delta' && events[0].text).toBe('response');
  expect(events[1].type).toBe('finish');
  });