@objectstack/service-ai 4.0.2 → 4.0.4

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/vercel-stream-encoder.ts

@@ -23,6 +23,14 @@ 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 ──────────────────────────────────────────────────────
 
 /**
@@ -71,8 +79,24 @@ export function encodeStreamPart(part: TextStreamPart<ToolSet>): string {
         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 '';
   }
 }

package/src/tools/data-tools.ts

@@ -1,30 +1,9 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { AIToolDefinition, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
+import type { AIToolDefinition, IDataEngine } from '@objectstack/spec/contracts';
 import type { ToolHandler } from './tool-registry.js';
 import type { ToolRegistry } from './tool-registry.js';
 
-// ---------------------------------------------------------------------------
-// Internal type aliases for metadata payloads (returned as `unknown` from
-// IMetadataService — we cast to these lightweight shapes for field access).
-// ---------------------------------------------------------------------------
-
-/** Minimal shape of an object definition as returned by IMetadataService. */
-interface ObjectDef {
-  name: string;
-  label?: string;
-  fields?: Record<string, FieldDef>;
-}
-
-/** Minimal shape of a field definition inside an object. */
-interface FieldDef {
-  type?: string;
-  label?: string;
-  required?: boolean;
-  reference?: string;
-  options?: unknown;
-}
-
 // ---------------------------------------------------------------------------
 // Data context — injected once at registration time
 // ---------------------------------------------------------------------------
@@ -38,8 +17,6 @@ interface FieldDef {
 export interface DataToolContext {
   /** ObjectQL data engine for record-level operations. */
   dataEngine: IDataEngine;
-  /** Metadata service for schema/object introspection. */
-  metadataService: IMetadataService;
 }
 
 // ---------------------------------------------------------------------------
@@ -52,34 +29,6 @@ const MAX_QUERY_LIMIT = 200;
 /** Default record limit when not specified. */
 const DEFAULT_QUERY_LIMIT = 20;
 
-export const LIST_OBJECTS_TOOL: AIToolDefinition = {
-  name: 'list_objects',
-  description: 'List all available data objects (tables) in the system. Returns object names and labels.',
-  parameters: {
-    type: 'object',
-    properties: {},
-    additionalProperties: false,
-  },
-};
-
-export const DESCRIBE_OBJECT_TOOL: AIToolDefinition = {
-  name: 'describe_object',
-  description:
-    'Get the schema (fields, types, labels) of a specific data object. ' +
-    'Use this to understand the structure of a table before querying it.',
-  parameters: {
-    type: 'object',
-    properties: {
-      objectName: {
-        type: 'string',
-        description: 'The snake_case name of the object to describe',
-      },
-    },
-    required: ['objectName'],
-    additionalProperties: false,
-  },
-};
-
 export const QUERY_RECORDS_TOOL: AIToolDefinition = {
   name: 'query_records',
   description:
@@ -203,10 +152,8 @@ export const AGGREGATE_DATA_TOOL: AIToolDefinition = {
   },
 };
 
-/** All built-in data tool definitions. */
+/** All built-in data tools definitions. */
 export const DATA_TOOL_DEFINITIONS: AIToolDefinition[] = [
-  LIST_OBJECTS_TOOL,
-  DESCRIBE_OBJECT_TOOL,
   QUERY_RECORDS_TOOL,
   GET_RECORD_TOOL,
   AGGREGATE_DATA_TOOL,
@@ -216,46 +163,6 @@ export const DATA_TOOL_DEFINITIONS: AIToolDefinition[] = [
 // Handler Factories
 // ---------------------------------------------------------------------------
 
-function createListObjectsHandler(ctx: DataToolContext): ToolHandler {
-  return async () => {
-    const objects = await ctx.metadataService.listObjects();
-    const summary = (objects as ObjectDef[]).map(o => ({
-      name: o.name,
-      label: o.label ?? o.name,
-    }));
-    return JSON.stringify(summary);
-  };
-}
-
-function createDescribeObjectHandler(ctx: DataToolContext): ToolHandler {
-  return async (args) => {
-    const { objectName } = args as { objectName: string };
-    const objectDef = await ctx.metadataService.getObject(objectName);
-    if (!objectDef) {
-      return JSON.stringify({ error: `Object "${objectName}" not found` });
-    }
-
-    const def = objectDef as ObjectDef;
-    const fields = def.fields ?? {};
-    const fieldSummary: Record<string, Record<string, unknown>> = {};
-    for (const [key, f] of Object.entries(fields)) {
-      fieldSummary[key] = {
-        type: f.type,
-        label: f.label ?? key,
-        required: f.required ?? false,
-        ...(f.reference ? { reference: f.reference } : {}),
-        ...(f.options ? { options: f.options } : {}),
-      };
-    }
-
-    return JSON.stringify({
-      name: def.name,
-      label: def.label ?? def.name,
-      fields: fieldSummary,
-    });
-  };
-}
-
 function createQueryRecordsHandler(ctx: DataToolContext): ToolHandler {
   return async (args) => {
     const {
@@ -366,15 +273,13 @@ function createAggregateDataHandler(ctx: DataToolContext): ToolHandler {
 /**
  * Register all built-in data tools on the given {@link ToolRegistry}.
  *
- * Typically called from the `ai:ready` hook after both the data engine
- * and metadata service are available.
+ * Typically called from the `ai:ready` hook after the data engine is available.
  *
  * @example
  * ```ts
  * ctx.hook('ai:ready', async (aiService) => {
  *   const dataEngine = ctx.getService<IDataEngine>('data');
- *   const metadataService = ctx.getService<IMetadataService>('metadata');
- *   registerDataTools(aiService.toolRegistry, { dataEngine, metadataService });
+ *   registerDataTools(aiService.toolRegistry, { dataEngine });
  * });
  * ```
  */
@@ -382,8 +287,6 @@ export function registerDataTools(
   registry: ToolRegistry,
   context: DataToolContext,
 ): void {
-  registry.register(LIST_OBJECTS_TOOL, createListObjectsHandler(context));
-  registry.register(DESCRIBE_OBJECT_TOOL, createDescribeObjectHandler(context));
   registry.register(QUERY_RECORDS_TOOL, createQueryRecordsHandler(context));
   registry.register(GET_RECORD_TOOL, createGetRecordHandler(context));
   registry.register(AGGREGATE_DATA_TOOL, createAggregateDataHandler(context));

package/src/tools/describe-object.tool.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * describe_object — AI Tool Metadata
+ *
+ * Returns the full schema of a data object including all fields, types,
+ * relationships, and configuration. This is the single, unified tool for
+ * describing objects — used by both data_chat and metadata_assistant agents.
+ */
+export const describeObjectTool = defineTool({
+  name: 'describe_object',
+  label: 'Describe Object',
+  description:
+    'Returns the full schema details of a data object, including all fields, types, relationships, and configuration. ' +
+    'Use this to understand the structure of a table before querying or modifying it.',
+  category: 'data',
+  builtIn: true,
+  parameters: {
+    type: 'object',
+    properties: {
+      objectName: {
+        type: 'string',
+        description: 'Object machine name to describe (snake_case)',
+      },
+    },
+    required: ['objectName'],
+    additionalProperties: false,
+  },
+});

package/src/tools/index.ts

@@ -14,5 +14,5 @@ export { createObjectTool } from './create-object.tool.js';
 export { addFieldTool } from './add-field.tool.js';
 export { modifyFieldTool } from './modify-field.tool.js';
 export { deleteFieldTool } from './delete-field.tool.js';
-export { listMetadataObjectsTool } from './list-metadata-objects.tool.js';
-export { describeMetadataObjectTool } from './describe-metadata-object.tool.js';
+export { listObjectsTool } from './list-objects.tool.js';
+export { describeObjectTool } from './describe-object.tool.js';

package/src/tools/{list-metadata-objects.tool.ts → list-objects.tool.ts}

@@ -3,18 +3,18 @@
 import { defineTool } from '@objectstack/spec/ai';
 
 /**
- * list_metadata_objects — AI Tool Metadata
+ * list_objects — AI Tool Metadata
  *
- * Lists all registered metadata objects (tables) with optional filtering.
- * Uses a unique name (`list_metadata_objects`) to avoid collision with
- * the data-tools `list_objects` tool.
+ * Lists all registered data objects (tables) with optional filtering
+ * and field summaries. This is the single, unified tool for listing
+ * objects — used by both data_chat and metadata_assistant agents.
  */
-export const listMetadataObjectsTool = defineTool({
-  name: 'list_metadata_objects',
-  label: 'List Metadata Objects',
+export const listObjectsTool = defineTool({
+  name: 'list_objects',
+  label: 'List Objects',
   description:
-    'Lists all registered metadata objects (tables) in the current environment. ' +
-    'Use this when the user wants to see what tables, entities, or data models are defined in metadata.',
+    'Lists all registered data objects (tables) in the current environment. ' +
+    'Use this when the user wants to see what tables, entities, or data models are available.',
   category: 'data',
   builtIn: true,
   parameters: {

package/src/tools/metadata-tools.ts

@@ -13,15 +13,15 @@ export { createObjectTool } from './create-object.tool.js';
 export { addFieldTool } from './add-field.tool.js';
 export { modifyFieldTool } from './modify-field.tool.js';
 export { deleteFieldTool } from './delete-field.tool.js';
-export { listMetadataObjectsTool } from './list-metadata-objects.tool.js';
-export { describeMetadataObjectTool } from './describe-metadata-object.tool.js';
+export { listObjectsTool } from './list-objects.tool.js';
+export { describeObjectTool } from './describe-object.tool.js';
 
 import { createObjectTool } from './create-object.tool.js';
 import { addFieldTool } from './add-field.tool.js';
 import { modifyFieldTool } from './modify-field.tool.js';
 import { deleteFieldTool } from './delete-field.tool.js';
-import { listMetadataObjectsTool } from './list-metadata-objects.tool.js';
-import { describeMetadataObjectTool } from './describe-metadata-object.tool.js';
+import { listObjectsTool } from './list-objects.tool.js';
+import { describeObjectTool } from './describe-object.tool.js';
 
 /** All built-in metadata management tool definitions (Tool metadata). */
 export const METADATA_TOOL_DEFINITIONS: Tool[] = [
@@ -29,8 +29,8 @@ export const METADATA_TOOL_DEFINITIONS: Tool[] = [
   addFieldTool,
   modifyFieldTool,
   deleteFieldTool,
-  listMetadataObjectsTool,
-  describeMetadataObjectTool,
+  listObjectsTool,
+  describeObjectTool,
 ];
 
 // ---------------------------------------------------------------------------
@@ -425,6 +425,6 @@ export function registerMetadataTools(
   registry.register(addFieldTool, createAddFieldHandler(context));
   registry.register(modifyFieldTool, createModifyFieldHandler(context));
   registry.register(deleteFieldTool, createDeleteFieldHandler(context));
-  registry.register(listMetadataObjectsTool, createListObjectsHandler(context));
-  registry.register(describeMetadataObjectTool, createDescribeObjectHandler(context));
+  registry.register(listObjectsTool, createListObjectsHandler(context));
+  registry.register(describeObjectTool, createDescribeObjectHandler(context));
 }

package/vitest.config.ts

@@ -0,0 +1,23 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+  },
+  resolve: {
+    alias: {
+      '@objectstack/core': path.resolve(__dirname, '../../core/src/index.ts'),
+      '@objectstack/spec/ai': path.resolve(__dirname, '../../spec/src/ai/index.ts'),
+      '@objectstack/spec/api': path.resolve(__dirname, '../../spec/src/api/index.ts'),
+      '@objectstack/spec/contracts': path.resolve(__dirname, '../../spec/src/contracts/index.ts'),
+      '@objectstack/spec/data': path.resolve(__dirname, '../../spec/src/data/index.ts'),
+      '@objectstack/spec/kernel': path.resolve(__dirname, '../../spec/src/kernel/index.ts'),
+      '@objectstack/spec/system': path.resolve(__dirname, '../../spec/src/system/index.ts'),
+      '@objectstack/spec': path.resolve(__dirname, '../../spec/src/index.ts'),
+    },
+  },
+});

package/src/tools/describe-metadata-object.tool.ts

@@ -1,32 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { defineTool } from '@objectstack/spec/ai';
-
-/**
- * describe_metadata_object — AI Tool Metadata
- *
- * Returns the full metadata schema of a data object including all
- * fields, types, relationships, and configuration. Uses a unique name
- * (`describe_metadata_object`) to avoid collision with the data-tools
- * `describe_object` tool.
- */
-export const describeMetadataObjectTool = defineTool({
-  name: 'describe_metadata_object',
-  label: 'Describe Metadata Object',
-  description:
-    'Returns the full metadata schema details of a data object, including all fields, types, relationships, and configuration. ' +
-    'Use this when the user wants to inspect or understand the metadata structure of a specific table or entity.',
-  category: 'data',
-  builtIn: true,
-  parameters: {
-    type: 'object',
-    properties: {
-      objectName: {
-        type: 'string',
-        description: 'Object machine name to describe (snake_case)',
-      },
-    },
-    required: ['objectName'],
-    additionalProperties: false,
-  },
-});