@objectstack/service-ai 4.0.2 → 4.0.3

package/src/__tests__/tool-routes.test.ts

@@ -0,0 +1,191 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { buildToolRoutes } from '../routes/tool-routes.js';
+import { AIService } from '../ai-service.js';
+import { InMemoryConversationService } from '../conversation/in-memory-conversation-service.js';
+import { ToolRegistry } from '../tools/tool-registry.js';
+import type { Logger } from '@objectstack/spec/contracts';
+
+const silentLogger: Logger = {
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  fatal: vi.fn(),
+};
+
+describe('Tool Routes', () => {
+  let aiService: AIService;
+  let routes: ReturnType<typeof buildToolRoutes>;
+
+  beforeEach(() => {
+    const conversationService = new InMemoryConversationService();
+    aiService = new AIService({
+      adapter: 'memory',
+      conversationService,
+    });
+
+    // Register a test tool
+    aiService.toolRegistry.register(
+      {
+        name: 'test_tool',
+        description: 'A test tool for playground',
+        parameters: {
+          type: 'object',
+          properties: {
+            message: { type: 'string' },
+          },
+          required: ['message'],
+        },
+      },
+      async (params: any) => {
+        return JSON.stringify({ echo: params.message });
+      }
+    );
+
+    routes = buildToolRoutes(aiService, silentLogger);
+  });
+
+  describe('GET /api/v1/ai/tools', () => {
+    it('should list all registered tools', async () => {
+      const listRoute = routes.find(r => r.method === 'GET' && r.path === '/api/v1/ai/tools');
+      expect(listRoute).toBeDefined();
+
+      const response = await listRoute!.handler({});
+      expect(response.status).toBe(200);
+      expect(response.body).toHaveProperty('tools');
+      expect(Array.isArray((response.body as any).tools)).toBe(true);
+
+      const tools = (response.body as any).tools;
+      expect(tools.length).toBeGreaterThan(0);
+      expect(tools.some((t: any) => t.name === 'test_tool')).toBe(true);
+    });
+
+    it('should require authentication', () => {
+      const listRoute = routes.find(r => r.method === 'GET' && r.path === '/api/v1/ai/tools');
+      expect(listRoute?.auth).toBe(true);
+      expect(listRoute?.permissions).toContain('ai:tools');
+    });
+  });
+
+  describe('POST /api/v1/ai/tools/:toolName/execute', () => {
+    it('should execute a tool with parameters', async () => {
+      const executeRoute = routes.find(
+        r => r.method === 'POST' && r.path === '/api/v1/ai/tools/:toolName/execute'
+      );
+      expect(executeRoute).toBeDefined();
+
+      const response = await executeRoute!.handler({
+        params: { toolName: 'test_tool' },
+        body: {
+          parameters: { message: 'Hello, Playground!' },
+        },
+      });
+
+      expect(response.status).toBe(200);
+      expect(response.body).toHaveProperty('result');
+      // Result is a JSON string from the handler
+      expect((response.body as any).result).toBe('{"echo":"Hello, Playground!"}');
+      expect((response.body as any).toolName).toBe('test_tool');
+      expect((response.body as any).duration).toBeTypeOf('number');
+    });
+
+    it('should return 404 for non-existent tool', async () => {
+      const executeRoute = routes.find(
+        r => r.method === 'POST' && r.path === '/api/v1/ai/tools/:toolName/execute'
+      );
+
+      const response = await executeRoute!.handler({
+        params: { toolName: 'non_existent_tool' },
+        body: {
+          parameters: {},
+        },
+      });
+
+      expect(response.status).toBe(404);
+      expect((response.body as any).error).toContain('not found');
+    });
+
+    it('should return 400 when toolName is missing', async () => {
+      const executeRoute = routes.find(
+        r => r.method === 'POST' && r.path === '/api/v1/ai/tools/:toolName/execute'
+      );
+
+      const response = await executeRoute!.handler({
+        body: {
+          parameters: {},
+        },
+      });
+
+      expect(response.status).toBe(400);
+      expect((response.body as any).error).toContain('toolName');
+    });
+
+    it('should return 400 when parameters are missing', async () => {
+      const executeRoute = routes.find(
+        r => r.method === 'POST' && r.path === '/api/v1/ai/tools/:toolName/execute'
+      );
+
+      const response = await executeRoute!.handler({
+        params: { toolName: 'test_tool' },
+        body: {},
+      });
+
+      expect(response.status).toBe(400);
+      expect((response.body as any).error).toContain('parameters');
+    });
+
+    it('should handle tool execution errors', async () => {
+      // Register a tool that throws an error
+      aiService.toolRegistry.register(
+        {
+          name: 'error_tool',
+          description: 'A tool that throws an error',
+          parameters: { type: 'object', properties: {} },
+        },
+        async () => {
+          throw new Error('Tool execution failed');
+        }
+      );
+
+      const executeRoute = routes.find(
+        r => r.method === 'POST' && r.path === '/api/v1/ai/tools/:toolName/execute'
+      );
+
+      const response = await executeRoute!.handler({
+        params: { toolName: 'error_tool' },
+        body: {
+          parameters: {},
+        },
+      });
+
+      expect(response.status).toBe(500);
+      expect((response.body as any).error).toContain('Tool execution failed');
+      expect((response.body as any).duration).toBeTypeOf('number');
+    });
+
+    it('should require authentication and permissions', () => {
+      const executeRoute = routes.find(
+        r => r.method === 'POST' && r.path === '/api/v1/ai/tools/:toolName/execute'
+      );
+
+      expect(executeRoute?.auth).toBe(true);
+      expect(executeRoute?.permissions).toContain('ai:tools');
+      expect(executeRoute?.permissions).toContain('ai:execute');
+    });
+  });
+
+  describe('Route Configuration', () => {
+    it('should register exactly 2 routes', () => {
+      expect(routes).toHaveLength(2);
+    });
+
+    it('should have descriptive route descriptions', () => {
+      routes.forEach(route => {
+        expect(route.description).toBeTruthy();
+        expect(route.description.length).toBeGreaterThan(10);
+      });
+    });
+  });
+});

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

@@ -128,6 +128,53 @@ describe('encodeStreamPart', () => {
     const part = { type: 'unknown-internal' } as unknown as TextStreamPart<ToolSet>;
     expect(encodeStreamPart(part)).toBe('');
   });
+
+  it('should encode reasoning-start part with g: prefix', () => {
+    const part = {
+      type: 'reasoning-start',
+      id: 'r1',
+    } as unknown as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    expect(frame).toBe('g:{"text":""}\n');
+  });
+
+  it('should encode reasoning-delta part with g: prefix', () => {
+    const part = {
+      type: 'reasoning-delta',
+      id: 'r1',
+      text: 'Let me think through this step by step...',
+    } as unknown as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    expect(frame).toBe('g:{"text":"Let me think through this step by step..."}\n');
+  });
+
+  it('should encode reasoning-end part as empty (no specific end marker)', () => {
+    const part = {
+      type: 'reasoning-end',
+      id: 'r1',
+    } as unknown as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    expect(frame).toBe('');
+  });
+
+  it('should pass through custom step events', () => {
+    const part = {
+      type: 'step-start',
+      stepId: 'step_1',
+      stepName: 'Query database',
+    } as unknown as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    const payload = parseSSE(frame);
+    expect(payload).toEqual({
+      type: 'step-start',
+      stepId: 'step_1',
+      stepName: 'Query database',
+    });
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────

package/src/agents/metadata-assistant-agent.ts

@@ -36,8 +36,8 @@ Capabilities:
 - Describe the full schema of a specific object
 
 Guidelines:
-1. Before creating a new object, use list_metadata_objects to check if a similar one already exists.
-2. Before modifying or deleting fields, use describe_metadata_object to understand the current schema.
+1. Before creating a new object, use list_objects to check if a similar one already exists.
+2. Before modifying or deleting fields, use describe_object to understand the current schema.
 3. Always use snake_case for object names and field names (e.g. project_task, due_date).
 4. Suggest meaningful field types based on the user's description (e.g. "deadline" → date, "active" → boolean).
 5. When creating objects, propose a reasonable set of initial fields based on the entity type.
@@ -59,8 +59,8 @@ Guidelines:
     { type: 'action', name: 'add_field', description: 'Add a field to an existing object' },
     { type: 'action', name: 'modify_field', description: 'Modify an existing field definition' },
     { type: 'action', name: 'delete_field', description: 'Delete a field from an object' },
-    { type: 'query', name: 'list_metadata_objects', description: 'List all metadata objects' },
-    { type: 'query', name: 'describe_metadata_object', description: 'Describe an object schema' },
+    { type: 'query', name: 'list_objects', description: 'List all data objects' },
+    { type: 'query', name: 'describe_object', description: 'Describe an object schema' },
   ],
 
   active: true,

package/src/ai-service.ts

@@ -332,6 +332,13 @@ export class AIService implements IAIService {
             }
           }
         }
+        // Emit tool-result so the client can see tool output via SSE
+        yield {
+          type: 'tool-result',
+          toolCallId: tr.toolCallId,
+          toolName: tr.toolName,
+          output: tr.output,
+        } as TextStreamPart<ToolSet>;
         conversation.push({
           role: 'tool',
           content: [tr],

package/src/index.ts

@@ -39,8 +39,8 @@ export {
   addFieldTool,
   modifyFieldTool,
   deleteFieldTool,
-  listMetadataObjectsTool,
-  describeMetadataObjectTool,
+  listObjectsTool,
+  describeObjectTool,
 } from './tools/metadata-tools.js';
 
 // Agent runtime
@@ -56,4 +56,5 @@ export { AiConversationObject, AiMessageObject } from './objects/index.js';
 // Routes
 export { buildAIRoutes } from './routes/ai-routes.js';
 export { buildAgentRoutes } from './routes/agent-routes.js';
+export { buildToolRoutes } from './routes/tool-routes.js';
 export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './routes/ai-routes.js';

package/src/plugin.ts

@@ -6,6 +6,7 @@ import { AIService } from './ai-service.js';
 import type { AIServiceConfig } from './ai-service.js';
 import { buildAIRoutes } from './routes/ai-routes.js';
 import { buildAgentRoutes } from './routes/agent-routes.js';
+import { buildToolRoutes } from './routes/tool-routes.js';
 import { ObjectQLConversationService } from './conversation/objectql-conversation-service.js';
 import { AiConversationObject, AiMessageObject } from './objects/index.js';
 import { registerDataTools } from './tools/data-tools.js';
@@ -250,28 +251,54 @@ export class AIServicePlugin implements Plugin {
     let metadataService: IMetadataService | undefined;
     try {
       metadataService = ctx.getService<IMetadataService>('metadata');
-    } catch {
+      console.log('[AI Plugin] Retrieved metadata service:', !!metadataService, 'has getRegisteredTypes:', typeof (metadataService as any)?.getRegisteredTypes);
+    } catch (e: any) {
+      console.log('[AI] Metadata service not available:', e.message);
       ctx.logger.debug('[AI] Metadata service not available');
     }
 
-    // Data tools require both data engine and metadata service
+    // Data tools require only the data engine
     try {
       const dataEngine = ctx.getService<IDataEngine>('data');
-      if (dataEngine && metadataService) {
-        registerDataTools(this.service.toolRegistry, { dataEngine, metadataService });
+      if (dataEngine) {
+        registerDataTools(this.service.toolRegistry, { dataEngine });
         ctx.logger.info('[AI] Built-in data tools registered');
 
-        // Register the built-in data_chat agent only if it does not already exist
-        const agentExists =
-          typeof metadataService.exists === 'function'
-            ? await metadataService.exists('agent', DATA_CHAT_AGENT.name)
-            : false;
-
-        if (!agentExists) {
-          await metadataService.register('agent', DATA_CHAT_AGENT.name, DATA_CHAT_AGENT);
-          ctx.logger.info('[AI] data_chat agent registered');
-        } else {
-          ctx.logger.debug('[AI] data_chat agent already exists, skipping auto-registration');
+        // Register data tools as metadata (for Studio visibility)
+        if (metadataService) {
+          const { DATA_TOOL_DEFINITIONS } = await import('./tools/data-tools.js');
+          for (const toolDef of DATA_TOOL_DEFINITIONS) {
+            const toolExists =
+              typeof metadataService.exists === 'function'
+                ? await metadataService.exists('tool', toolDef.name)
+                : false;
+
+            if (!toolExists) {
+              await metadataService.register('tool', toolDef.name, toolDef);
+            }
+          }
+          ctx.logger.info(`[AI] ${DATA_TOOL_DEFINITIONS.length} data tools registered as metadata`);
+        }
+
+        // Register the built-in data_chat agent (requires metadata service)
+        if (metadataService) {
+          try {
+            const agentExists =
+              typeof metadataService.exists === 'function'
+                ? await metadataService.exists('agent', DATA_CHAT_AGENT.name)
+                : false;
+
+            if (!agentExists) {
+              await metadataService.register('agent', DATA_CHAT_AGENT.name, DATA_CHAT_AGENT);
+              console.log('[AI] Registered data_chat agent to metadataService');
+              ctx.logger.info('[AI] data_chat agent registered');
+            } else {
+              console.log('[AI] data_chat agent already exists, skipping');
+              ctx.logger.debug('[AI] data_chat agent already exists, skipping auto-registration');
+            }
+          } catch (err) {
+            ctx.logger.warn('[AI] Failed to register data_chat agent', err instanceof Error ? { error: err.message, stack: err.stack } : { error: String(err) });
+          }
         }
       }
     } catch {
@@ -284,17 +311,37 @@ export class AIServicePlugin implements Plugin {
         registerMetadataTools(this.service.toolRegistry, { metadataService });
         ctx.logger.info('[AI] Built-in metadata tools registered');
 
+        // Register metadata tools as metadata (for Studio visibility)
+        const { METADATA_TOOL_DEFINITIONS } = await import('./tools/metadata-tools.js');
+        for (const toolDef of METADATA_TOOL_DEFINITIONS) {
+          const toolExists =
+            typeof metadataService.exists === 'function'
+              ? await metadataService.exists('tool', toolDef.name)
+              : false;
+
+          if (!toolExists) {
+            await metadataService.register('tool', toolDef.name, toolDef);
+          }
+        }
+        ctx.logger.info(`[AI] ${METADATA_TOOL_DEFINITIONS.length} metadata tools registered as metadata`);
+
         // Register the built-in metadata_assistant agent
-        const agentExists =
-          typeof metadataService.exists === 'function'
-            ? await metadataService.exists('agent', METADATA_ASSISTANT_AGENT.name)
-            : false;
-
-        if (!agentExists) {
-          await metadataService.register('agent', METADATA_ASSISTANT_AGENT.name, METADATA_ASSISTANT_AGENT);
-          ctx.logger.info('[AI] metadata_assistant agent registered');
-        } else {
-          ctx.logger.debug('[AI] metadata_assistant agent already exists, skipping auto-registration');
+        try {
+          const agentExists =
+            typeof metadataService.exists === 'function'
+              ? await metadataService.exists('agent', METADATA_ASSISTANT_AGENT.name)
+              : false;
+
+          if (!agentExists) {
+            await metadataService.register('agent', METADATA_ASSISTANT_AGENT.name, METADATA_ASSISTANT_AGENT);
+            console.log('[AI] Registered metadata_assistant agent to metadataService');
+            ctx.logger.info('[AI] metadata_assistant agent registered');
+          } else {
+            console.log('[AI] metadata_assistant agent already exists, skipping');
+            ctx.logger.debug('[AI] metadata_assistant agent already exists, skipping auto-registration');
+          }
+        } catch (err) {
+          ctx.logger.warn('[AI] Failed to register metadata_assistant agent', err instanceof Error ? { error: err.message, stack: err.stack } : { error: String(err) });
         }
       } catch (err) {
         ctx.logger.debug('[AI] Failed to register metadata tools', err instanceof Error ? err : undefined);
@@ -307,15 +354,18 @@ export class AIServicePlugin implements Plugin {
     // Build and expose route definitions
     const routes = buildAIRoutes(this.service, this.service.conversationService, ctx.logger);
 
+    // Build tool routes
+    const toolRoutes = buildToolRoutes(this.service, ctx.logger);
+    routes.push(...toolRoutes);
+    ctx.logger.info(`[AI] Tool routes registered (${toolRoutes.length} routes)`);
+
     // Build agent routes if metadata service is available
-    try {
-      const metadataService = ctx.getService<IMetadataService>('metadata');
-      if (metadataService) {
-        const agentRuntime = new AgentRuntime(metadataService);
-        const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
-        routes.push(...agentRoutes);
-      }
-    } catch {
+    if (metadataService) {
+      const agentRuntime = new AgentRuntime(metadataService);
+      const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
+      routes.push(...agentRoutes);
+      ctx.logger.info(`[AI] Agent routes registered (${agentRoutes.length} routes)`);
+    } else {
       ctx.logger.debug('[AI] Metadata service not available, skipping agent routes');
     }
 

package/src/routes/agent-routes.ts

@@ -5,6 +5,8 @@ import type { Logger } from '@objectstack/spec/contracts';
 import type { AIService } from '../ai-service.js';
 import type { AgentRuntime, AgentChatContext } from '../agent-runtime.js';
 import type { RouteDefinition } from './ai-routes.js';
+import { normalizeMessage, validateMessageContent } from './message-utils.js';
+import { encodeVercelDataStream } from '../stream/vercel-stream-encoder.js';
 
 /**
  * Allowed message roles for the agent chat endpoint.
@@ -25,10 +27,10 @@ function validateAgentMessage(raw: unknown): string | null {
   if (typeof msg.role !== 'string' || !ALLOWED_AGENT_ROLES.has(msg.role)) {
     return `message.role must be one of ${[...ALLOWED_AGENT_ROLES].map(r => `"${r}"`).join(', ')} for agent chat`;
   }
-  if (typeof msg.content !== 'string') {
-    return 'message.content must be a string';
-  }
-  return null;
+
+  // Assistant messages may legitimately have empty content (e.g. tool-call-only)
+  const allowEmpty = msg.role === 'assistant';
+  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
 }
 
 /**
@@ -67,10 +69,15 @@ export function buildAgentRoutes(
     },
 
     // ── Chat with a specific agent ──────────────────────────────
+    //
+    // Dual-mode endpoint matching the general chat route behaviour:
+    //   • `stream !== false` → Vercel Data Stream Protocol (SSE)
+    //   • `stream === false`  → JSON response (legacy)
+    //
     {
       method: 'POST',
       path: '/api/v1/ai/agents/:agentName/chat',
-      description: 'Chat with a specific AI agent',
+      description: 'Chat with a specific AI agent (supports Vercel AI Data Stream Protocol)',
       auth: true,
       permissions: ['ai:chat', 'ai:agents'],
       handler: async (req) => {
@@ -80,11 +87,12 @@ export function buildAgentRoutes(
         }
 
         // Parse request body
+        const body = (req.body ?? {}) as Record<string, unknown>;
         const {
           messages: rawMessages,
           context: chatContext,
           options: extraOptions,
-        } = (req.body ?? {}) as {
+        } = body as {
           messages?: unknown[];
           context?: AgentChatContext;
           options?: Record<string, unknown>;
@@ -134,15 +142,40 @@ export function buildAgentRoutes(
           // Prepend system messages then user conversation
           const fullMessages: ModelMessage[] = [
             ...systemMessages,
-            ...(rawMessages as ModelMessage[]),
+            ...rawMessages.map(m => normalizeMessage(m as Record<string, unknown>)),
           ];
 
-          // Use chatWithTools for automatic tool resolution
-          const result = await aiService.chatWithTools(fullMessages, {
+          const chatWithToolsOptions = {
             ...mergedOptions,
             maxIterations: agent.planning?.maxIterations,
-          });
+          };
+
+          // ── Choose response mode ─────────────────────────────
+          const wantStream = body.stream !== false;
+
+          if (wantStream) {
+            // Vercel Data Stream Protocol (SSE) — matches general chat behaviour
+            if (!aiService.streamChatWithTools) {
+              return { status: 501, body: { error: 'Streaming is not supported by the configured AI service' } };
+            }
+            const events = aiService.streamChatWithTools(fullMessages, chatWithToolsOptions);
+            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),
+            };
+          }
 
+          // JSON response (non-streaming / legacy)
+          const result = await aiService.chatWithTools(fullMessages, chatWithToolsOptions);
           return { status: 200, body: result };
         } catch (err) {
           logger.error(

package/src/routes/ai-routes.ts

@@ -3,6 +3,7 @@
 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.
@@ -77,37 +78,6 @@ export interface RouteResponse {
 /** Valid message roles accepted by the AI routes. */
 const VALID_ROLES = new Set<string>(['system', 'user', 'assistant', 'tool']);
 
-/**
- * Normalize a Vercel AI SDK v6 message (which may use `parts` instead of
- * `content`) into a plain `{ role, content }` ModelMessage.
- */
-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 that `raw` is a well-formed message.
  * Returns null on success, or an error string on failure.
@@ -125,44 +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(', ')}`;
   }
-  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;
-  }
 
   // Assistant / tool messages may legitimately have null or missing content
-  if (content === null || content === undefined) {
-    if (msg.role === 'assistant' || msg.role === 'tool') {
-      return null;
-    }
-  }
-
-  return 'message.content must be a string, an array, or include parts';
+  const allowEmpty = msg.role === 'assistant' || msg.role === 'tool';
+  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
 }
 
 /**

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';