@objectstack/service-ai 4.0.1 → 4.0.3

package/src/routes/ai-routes.ts

@@ -1,7 +1,9 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { IAIService, IAIConversationService, AIMessage } from '@objectstack/spec/contracts';
+import type { IAIService, IAIConversationService, ModelMessage } from '@objectstack/spec/contracts';
 import type { Logger } from '@objectstack/spec/contracts';
+import { encodeVercelDataStream } from '../stream/vercel-stream-encoder.js';
+import { normalizeMessage, validateMessageContent } from './message-utils.js';
 
 /**
  * Minimal HTTP handler abstraction so routes stay framework-agnostic.
@@ -63,14 +65,27 @@ export interface RouteResponse {
   stream?: boolean;
   /** Async iterable of SSE events (when stream=true) */
   events?: AsyncIterable<unknown>;
+  /**
+   * When `true`, the HTTP server layer should encode the `events` iterable
+   * using the Vercel AI Data Stream Protocol frame format (`0:`, `9:`, `d:`, …)
+   * instead of generic SSE `data:` lines.
+   *
+   * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+   */
+  vercelDataStream?: boolean;
 }
 
 /** Valid message roles accepted by the AI routes. */
 const VALID_ROLES = new Set<string>(['system', 'user', 'assistant', 'tool']);
 
 /**
- * Validate that `raw` is a well-formed AIMessage.
+ * Validate that `raw` is a well-formed message.
  * Returns null on success, or an error string on failure.
+ *
+ * Accepts:
+ *  - Simple string `content` (legacy)
+ *  - Array `content` (e.g. `[{ type: 'text', text: '...' }]`)
+ *  - Vercel AI SDK v6 `parts` format (content may be absent/null)
  */
 function validateMessage(raw: unknown): string | null {
   if (typeof raw !== 'object' || raw === null) {
@@ -80,10 +95,10 @@ function validateMessage(raw: unknown): string | null {
   if (typeof msg.role !== 'string' || !VALID_ROLES.has(msg.role)) {
     return `message.role must be one of ${[...VALID_ROLES].map(r => `"${r}"`).join(', ')}`;
   }
-  if (typeof msg.content !== 'string') {
-    return 'message.content must be a string';
-  }
-  return null;
+
+  // Assistant / tool messages may legitimately have null or missing content
+  const allowEmpty = msg.role === 'assistant' || msg.role === 'tool';
+  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
 }
 
 /**
@@ -112,18 +127,26 @@ export function buildAIRoutes(
 ): RouteDefinition[] {
   return [
     // ── Chat ────────────────────────────────────────────────────
+    //
+    // Dual-mode endpoint compatible with both the legacy ObjectStack
+    // format (`{ messages, options }`) and the Vercel AI SDK useChat
+    // flat format (`{ messages, system, model, stream, … }`).
+    //
+    // Behaviour:
+    //   • `stream !== false` → Vercel Data Stream Protocol (SSE)
+    //   • `stream === false`  → JSON response (legacy)
+    //
     {
       method: 'POST',
       path: '/api/v1/ai/chat',
-      description: 'Synchronous chat completion',
+      description: 'Chat completion (supports Vercel AI Data Stream Protocol)',
       auth: true,
       permissions: ['ai:chat'],
       handler: async (req) => {
-        const { messages, options } = (req.body ?? {}) as {
-          messages?: unknown[];
-          options?: Record<string, unknown>;
-        };
+        const body = (req.body ?? {}) as Record<string, unknown>;
 
+        // ── Parse messages ───────────────────────────────────
+        const messages = body.messages as unknown[] | undefined;
         if (!Array.isArray(messages) || messages.length === 0) {
           return { status: 400, body: { error: 'messages array is required' } };
         }
@@ -133,8 +156,64 @@ export function buildAIRoutes(
           if (err) return { status: 400, body: { error: err } };
         }
 
+        // ── Resolve options ──────────────────────────────────
+        // Accept legacy nested `options` object **or** Vercel-style
+        // flat fields (`model`, `temperature`, `maxTokens`).
+        const nested = (body.options ?? {}) as Record<string, unknown>;
+        const resolvedOptions: Record<string, unknown> = {
+          ...nested,
+          ...(body.model != null && { model: body.model }),
+          ...(body.temperature != null && { temperature: body.temperature }),
+          ...(body.maxTokens != null && { maxTokens: body.maxTokens }),
+        };
+
+        // ── Prepend system prompt ────────────────────────────
+        // Vercel useChat sends `system` (or the deprecated `systemPrompt`)
+        // as a top-level field.  We prepend it as a system message.
+        const rawSystemPrompt = body.system ?? body.systemPrompt;
+        if (rawSystemPrompt != null && typeof rawSystemPrompt !== 'string') {
+          return { status: 400, body: { error: 'system/systemPrompt must be a string' } };
+        }
+        const systemPrompt = rawSystemPrompt as string | undefined;
+        const finalMessages: ModelMessage[] = [
+          ...(systemPrompt
+            ? [{ role: 'system' as const, content: systemPrompt }]
+            : []),
+          ...messages.map(m => normalizeMessage(m as Record<string, unknown>)),
+        ];
+
+        // ── Choose response mode ─────────────────────────────
+        const wantStream = body.stream !== false;
+
+        if (wantStream) {
+          // UI Message Stream Protocol (SSE with JSON payloads)
+          try {
+            if (!(aiService as any).streamChatWithTools) {
+              return { status: 501, body: { error: 'Streaming is not supported by the configured AI service' } };
+            }
+            const events = (aiService as any).streamChatWithTools(finalMessages, resolvedOptions as any);
+            return {
+              status: 200,
+              stream: true,
+              vercelDataStream: true,
+              contentType: 'text/event-stream',
+              headers: {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+                'x-vercel-ai-ui-message-stream': 'v1',
+              },
+              events: encodeVercelDataStream(events),
+            };
+          } catch (err) {
+            logger.error('[AI Route] /chat stream error', err instanceof Error ? err : undefined);
+            return { status: 500, body: { error: 'Internal AI service error' } };
+          }
+        }
+
+        // JSON response (non-streaming)
         try {
-          const result = await aiService.chat(messages as AIMessage[], options as any);
+          const result = await (aiService as any).chatWithTools(finalMessages, resolvedOptions as any);
           return { status: 200, body: result };
         } catch (err) {
           logger.error('[AI Route] /chat error', err instanceof Error ? err : undefined);
@@ -169,7 +248,7 @@ export function buildAIRoutes(
           if (!aiService.streamChat) {
             return { status: 501, body: { error: 'Streaming is not supported by the configured AI service' } };
           }
-          const events = aiService.streamChat(messages as AIMessage[], options as any);
+          const events = aiService.streamChat(messages.map(m => normalizeMessage(m as Record<string, unknown>)), options as any);
           return { status: 200, stream: true, events };
         } catch (err) {
           logger.error('[AI Route] /chat/stream error', err instanceof Error ? err : undefined);
@@ -312,7 +391,7 @@ export function buildAIRoutes(
             }
           }
 
-          const conversation = await conversationService.addMessage(id, message as AIMessage);
+          const conversation = await conversationService.addMessage(id, message as ModelMessage);
           return { status: 200, body: conversation };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);

package/src/routes/index.ts

@@ -2,3 +2,4 @@
 
 export { buildAIRoutes } from './ai-routes.js';
 export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './ai-routes.js';
+export { normalizeMessage, validateMessageContent } from './message-utils.js';

package/src/routes/message-utils.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ModelMessage } from '@objectstack/spec/contracts';
+
+/**
+ * Normalize a Vercel AI SDK v6 message (which may use `parts` instead of
+ * `content`) into a plain `{ role, content }` ModelMessage.
+ *
+ * Shared between the general chat routes and agent chat routes.
+ */
+export function normalizeMessage(raw: Record<string, unknown>): ModelMessage {
+  const role = raw.role as string;
+
+  // If content is already a string, use it directly
+  if (typeof raw.content === 'string') {
+    return { role, content: raw.content } as unknown as ModelMessage;
+  }
+
+  // If content is an array (multi-part), pass through
+  if (Array.isArray(raw.content)) {
+    return { role, content: raw.content } as unknown as ModelMessage;
+  }
+
+  // Vercel AI SDK v6: extract text from `parts` array
+  if (Array.isArray(raw.parts)) {
+    const textParts = (raw.parts as Array<Record<string, unknown>>)
+      .filter(p => p.type === 'text' && typeof p.text === 'string')
+      .map(p => p.text as string);
+    if (textParts.length > 0) {
+      return { role, content: textParts.join('') } as unknown as ModelMessage;
+    }
+  }
+
+  // Fallback: empty content (e.g. tool-only assistant messages)
+  return { role, content: '' } as unknown as ModelMessage;
+}
+
+/**
+ * Validate message content/parts format (role-agnostic).
+ *
+ * Returns `null` when the content shape is valid, or an error string
+ * describing the first violation found.
+ *
+ * Accepts:
+ *  - Simple string `content` (legacy)
+ *  - Array `content` (e.g. `[{ type: 'text', text: '...' }]`)
+ *  - Vercel AI SDK v6 `parts` format (content may be absent/null)
+ *  - Null/undefined `content` for assistant messages (when `allowEmpty` is true)
+ */
+export function validateMessageContent(
+  msg: Record<string, unknown>,
+  opts?: { allowEmptyContent?: boolean },
+): string | null {
+  const content = msg.content;
+
+  // Vercel AI SDK v6 sends `parts` instead of (or alongside) `content`.
+  // Accept any message that carries a `parts` array, even when `content` is absent.
+  if (Array.isArray(msg.parts)) {
+    return null;
+  }
+
+  // content is a plain string — OK
+  if (typeof content === 'string') {
+    return null;
+  }
+
+  // content is an array of typed parts (legacy multi-part format)
+  if (Array.isArray(content)) {
+    for (const part of content as unknown[]) {
+      if (typeof part !== 'object' || part === null) {
+        return 'message.content array elements must be non-null objects';
+      }
+      const partObj = part as Record<string, unknown>;
+      if (typeof partObj.type !== 'string') {
+        return 'each message.content array element must have a string "type" property';
+      }
+      if (partObj.type === 'text' && typeof partObj.text !== 'string') {
+        return 'message.content elements with type "text" must have a string "text" property';
+      }
+    }
+    return null;
+  }
+
+  // Allow empty content for certain roles (e.g. assistant tool-call messages)
+  if ((content === null || content === undefined) && opts?.allowEmptyContent) {
+    return null;
+  }
+
+  return 'message.content must be a string, an array, or include parts';
+}

package/src/routes/tool-routes.ts

@@ -0,0 +1,142 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Logger } from '@objectstack/spec/contracts';
+import type { AIService } from '../ai-service.js';
+import type { RouteDefinition } from './ai-routes.js';
+
+/**
+ * Extract string value from tool execution result output.
+ */
+function extractOutputValue(output: any): string {
+  if (!output) return '';
+  if (typeof output === 'string') return output;
+  if (typeof output === 'object' && 'value' in output) {
+    return String(output.value ?? '');
+  }
+  return JSON.stringify(output);
+}
+
+/**
+ * Build tool-specific REST routes.
+ *
+ * | Method | Path | Description |
+ * |:---|:---|:---|
+ * | GET  | /api/v1/ai/tools | List all registered tools |
+ * | POST | /api/v1/ai/tools/:toolName/execute | Execute a tool with parameters |
+ */
+export function buildToolRoutes(
+  aiService: AIService,
+  logger: Logger,
+): RouteDefinition[] {
+  return [
+    // ── List registered tools ──────────────────────────────────────
+    {
+      method: 'GET',
+      path: '/api/v1/ai/tools',
+      description: 'List all registered AI tools',
+      auth: true,
+      permissions: ['ai:tools'],
+      handler: async () => {
+        try {
+          const tools = aiService.toolRegistry.getAll();
+          return {
+            status: 200,
+            body: {
+              tools: tools.map(t => ({
+                name: t.name,
+                description: t.description,
+                category: (t as any).category,
+              }))
+            }
+          };
+        } catch (err) {
+          logger.error(
+            '[AI Route] /tools list error',
+            err instanceof Error ? err : undefined,
+          );
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+
+    // ── Execute a tool ──────────────────────────────────────────────
+    //
+    // Executes a tool with the provided parameters.
+    // This is intended for testing/playground use.
+    //
+    {
+      method: 'POST',
+      path: '/api/v1/ai/tools/:toolName/execute',
+      description: 'Execute a tool with parameters (playground/testing)',
+      auth: true,
+      permissions: ['ai:tools', 'ai:execute'],
+      handler: async (req) => {
+        const toolName = req.params?.toolName;
+        if (!toolName) {
+          return { status: 400, body: { error: 'toolName parameter is required' } };
+        }
+
+        // Parse request body
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const { parameters } = body as {
+          parameters?: Record<string, unknown>;
+        };
+
+        if (!parameters || typeof parameters !== 'object') {
+          return { status: 400, body: { error: 'parameters object is required' } };
+        }
+
+        try {
+          // Check if tool exists
+          if (!aiService.toolRegistry.has(toolName)) {
+            return { status: 404, body: { error: `Tool "${toolName}" not found` } };
+          }
+
+          // Execute the tool using ToolRegistry's execute method
+          const startTime = Date.now();
+
+          const toolCallPart = {
+            type: 'tool-call' as const,
+            toolCallId: `playground-${Date.now()}`,
+            toolName,
+            input: parameters,
+          };
+
+          const result = await aiService.toolRegistry.execute(toolCallPart);
+          const duration = Date.now() - startTime;
+
+          // Check if execution resulted in an error
+          if (result.isError) {
+            const errorMsg = extractOutputValue(result.output);
+            logger.error(
+              `[AI Route] Tool execution error: ${toolName}`,
+              new Error(errorMsg),
+            );
+            return {
+              status: 500,
+              body: {
+                error: errorMsg,
+                duration,
+              },
+            };
+          }
+
+          return {
+            status: 200,
+            body: {
+              result: extractOutputValue(result.output),
+              duration,
+              toolName,
+            },
+          };
+        } catch (err) {
+          logger.error(
+            '[AI Route] /tools/:toolName/execute error',
+            err instanceof Error ? err : undefined,
+          );
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+  ];
+}

package/src/stream/index.ts

@@ -0,0 +1,3 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { encodeStreamPart, encodeVercelDataStream } from './vercel-stream-encoder.js';

package/src/stream/vercel-stream-encoder.ts

@@ -0,0 +1,153 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Vercel AI SDK v6 — UI Message Stream Encoder
+ *
+ * Converts `AsyncIterable<TextStreamPart<ToolSet>>` (the internal ObjectStack
+ * streaming format) into the Vercel AI SDK v6 **UI Message Stream Protocol**.
+ *
+ * Wire format: Server-Sent Events (SSE) with JSON payloads.
+ *   `data: {"type":"text-delta","id":"0","delta":"Hello"}\n\n`
+ *
+ * The client-side `DefaultChatTransport` from `ai` v6 uses
+ * `parseJsonEventStream` to parse these SSE events.
+ *
+ * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+ */
+
+import type { TextStreamPart, ToolSet } from 'ai';
+
+// ── SSE helpers ──────────────────────────────────────────────────────
+
+function sse(data: object): string {
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
+
+/**
+ * Encode data using Vercel AI SDK Data Stream Protocol prefixes.
+ * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+ */
+function dataStreamLine(prefix: string, data: object): string {
+  return `${prefix}:${JSON.stringify(data)}\n`;
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Encode a single `TextStreamPart` event into SSE-formatted UI Message
+ * Stream chunk(s).
+ *
+ * Returns an empty string for event types that have no wire-format mapping.
+ */
+export function encodeStreamPart(part: TextStreamPart<ToolSet>): string {
+  switch (part.type) {
+    case 'text-delta':
+      return sse({ type: 'text-delta', id: '0', delta: part.text });
+
+    case 'tool-input-start':
+      return sse({
+        type: 'tool-input-start',
+        toolCallId: part.id,
+        toolName: part.toolName,
+      });
+
+    case 'tool-input-delta':
+      return sse({
+        type: 'tool-input-delta',
+        toolCallId: part.id,
+        inputTextDelta: part.delta,
+      });
+
+    case 'tool-call':
+      return sse({
+        type: 'tool-input-available',
+        toolCallId: part.toolCallId,
+        toolName: part.toolName,
+        input: part.input,
+      });
+
+    case 'tool-result':
+      return sse({
+        type: 'tool-output-available',
+        toolCallId: part.toolCallId,
+        output: part.output,
+      });
+
+    case 'error':
+      return sse({
+        type: 'error',
+        errorText: String(part.error),
+      });
+
+    // Handle reasoning/thinking streams (DeepSeek R1, o1-style models)
+    // Use 'g:' prefix for reasoning content per Vercel AI SDK protocol
+    case 'reasoning-start':
+      return dataStreamLine('g', { text: '' });
+
+    case 'reasoning-delta':
+      return dataStreamLine('g', { text: part.text });
+
+    case 'reasoning-end':
+      return ''; // No specific end marker needed for reasoning
+
+    // finish-step and finish are handled by the generator, not here
+    default:
+      // Pass through any unknown event types that might be custom
+      // (e.g., step-start, step-finish from custom providers)
+      if ((part as any).type?.startsWith('step-')) {
+        return sse(part as any);
+      }
+      return '';
+  }
+}
+
+/**
+ * Transform an `AsyncIterable<TextStreamPart>` into an `AsyncIterable<string>`
+ * where each yielded string is an SSE-formatted UI Message Stream chunk.
+ *
+ * Lifecycle order required by the client:
+ *   start → start-step → text-start → text-delta* → text-end → finish-step → finish → [DONE]
+ */
+export async function* encodeVercelDataStream(
+  events: AsyncIterable<TextStreamPart<ToolSet>>,
+): AsyncIterable<string> {
+  // Preamble
+  yield sse({ type: 'start' });
+  yield sse({ type: 'start-step' });
+  yield sse({ type: 'text-start', id: '0' });
+
+  let textOpen = true;
+  let finishReason = 'stop';
+
+  for await (const part of events) {
+    // Capture finish reason
+    if (part.type === 'finish') {
+      finishReason = part.finishReason ?? 'stop';
+    }
+
+    // Before finish-step/finish, close the text part first
+    if (part.type === 'finish-step' || part.type === 'finish') {
+      if (textOpen) {
+        yield sse({ type: 'text-end', id: '0' });
+        textOpen = false;
+      }
+      // Don't emit these via encodeStreamPart — we handle them in postamble
+      continue;
+    }
+
+    const frame = encodeStreamPart(part);
+    if (frame) {
+      yield frame;
+    }
+  }
+
+  // Close text if still open (safety)
+  if (textOpen) {
+    yield sse({ type: 'text-end', id: '0' });
+  }
+
+  // Postamble
+  yield sse({ type: 'finish-step' });
+  yield sse({ type: 'finish', finishReason });
+  yield 'data: [DONE]\n\n';
+}

package/src/tools/add-field.tool.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * add_field — AI Tool Metadata
+ *
+ * Adds a new field (column) to an existing data object.
+ * Validates snake_case for objectName, field name, reference,
+ * and select option values before merging into the definition.
+ */
+export const addFieldTool = defineTool({
+  name: 'add_field',
+  label: 'Add Field',
+  description:
+    'Adds a new field (column) to an existing data object. ' +
+    'Use this when the user wants to add a property, column, or attribute to a table.',
+  category: 'data',
+  builtIn: true,
+  parameters: {
+    type: 'object',
+    properties: {
+      objectName: {
+        type: 'string',
+        description: 'Target object machine name (snake_case)',
+      },
+      name: {
+        type: 'string',
+        description: 'Field machine name (snake_case, e.g. due_date)',
+      },
+      label: {
+        type: 'string',
+        description: 'Human-readable field label (e.g. Due Date)',
+      },
+      type: {
+        type: 'string',
+        description: 'Field data type',
+        enum: ['text', 'textarea', 'number', 'boolean', 'date', 'datetime', 'select', 'lookup', 'formula', 'autonumber'],
+      },
+      required: {
+        type: 'boolean',
+        description: 'Whether the field is required',
+      },
+      defaultValue: {
+        description: 'Default value for the field',
+      },
+      options: {
+        type: 'array',
+        description: 'Options for select/picklist fields',
+        items: {
+          type: 'object',
+          properties: {
+            label: { type: 'string' },
+            value: {
+              type: 'string',
+              description: 'Option machine identifier (lowercase snake_case, e.g. high_priority)',
+              pattern: '^[a-z_][a-z0-9_]*$',
+            },
+          },
+        },
+      },
+      reference: {
+        type: 'string',
+        description: 'Referenced object name for lookup fields (snake_case, e.g. account)',
+      },
+    },
+    required: ['objectName', 'name', 'type'],
+    additionalProperties: false,
+  },
+});