@objectstack/service-ai 4.0.0 → 4.0.2

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

@@ -0,0 +1,87 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Agent } from '@objectstack/spec';
+
+/**
+ * Built-in `metadata_assistant` agent definition.
+ *
+ * This agent powers AI-driven metadata management — users can create objects,
+ * add/modify/delete fields, and inspect schema definitions through natural
+ * language conversation.
+ *
+ * It is registered automatically by the AI service plugin alongside the
+ * `data_chat` agent when the metadata service is available.
+ *
+ * @example
+ * ```
+ * POST /api/v1/ai/agents/metadata_assistant/chat
+ * {
+ *   "messages": [{ "role": "user", "content": "Create a contracts table with name, value, and status fields" }],
+ *   "context": {}
+ * }
+ * ```
+ */
+export const METADATA_ASSISTANT_AGENT: Agent = {
+  name: 'metadata_assistant',
+  label: 'Metadata Assistant',
+  role: 'Schema Architect',
+  instructions: `You are an expert metadata architect that helps users design and manage their data models through natural language.
+
+Capabilities:
+- Create new data objects (tables) with fields
+- Add fields (columns) to existing objects
+- Modify field properties (label, type, required, default value)
+- Delete fields from objects
+- List all registered metadata objects and their schemas
+- 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.
+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.
+6. Explain what changes you are about to make before executing them.
+7. After making changes, confirm the result by describing the updated schema.
+8. For destructive operations (deleting fields), always warn the user about potential data loss.
+9. Always answer in the same language the user is using.
+10. If the user's request is ambiguous, ask clarifying questions before proceeding.`,
+
+  model: {
+    provider: 'openai',
+    model: 'gpt-4',
+    temperature: 0.2,
+    maxTokens: 4096,
+  },
+
+  tools: [
+    { type: 'action', name: 'create_object', description: 'Create a new data object (table)' },
+    { 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' },
+  ],
+
+  active: true,
+  visibility: 'global',
+
+  guardrails: {
+    maxTokensPerInvocation: 8192,
+    maxExecutionTimeSec: 60,
+    blockedTopics: ['drop_database', 'raw_sql', 'system_tables'],
+  },
+
+  planning: {
+    strategy: 'react',
+    maxIterations: 10,
+    allowReplan: true,
+  },
+
+  memory: {
+    shortTerm: {
+      maxMessages: 30,
+      maxTokens: 8192,
+    },
+  },
+};

package/src/ai-service.ts

@@ -1,10 +1,12 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type {
-  AIMessage,
+  ModelMessage,
+  ToolCallPart,
+  TextStreamPart,
+  ToolSet,
   AIRequestOptions,
   AIResult,
-  AIStreamEvent,
   IAIService,
   IAIConversationService,
   ChatWithToolsOptions,
@@ -14,8 +16,28 @@ import type { Logger } from '@objectstack/spec/contracts';
 import { createLogger } from '@objectstack/core';
 import { MemoryLLMAdapter } from './adapters/memory-adapter.js';
 import { ToolRegistry } from './tools/tool-registry.js';
+import type { ToolExecutionResult } from './tools/tool-registry.js';
 import { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
 
+// ── Stream event helpers ──────────────────────────────────────────
+// These helpers construct properly-typed Vercel AI SDK stream parts
+// to avoid repeated `as unknown as TextStreamPart<ToolSet>` casts.
+
+/** Create a text-delta stream part. */
+function textDeltaPart(id: string, text: string): TextStreamPart<ToolSet> {
+  return { type: 'text-delta', id, text } as TextStreamPart<ToolSet>;
+}
+
+/** Create a finish stream part from an AIResult. */
+function finishPart(result?: AIResult): TextStreamPart<ToolSet> {
+  return {
+    type: 'finish',
+    finishReason: 'stop',
+    totalUsage: result?.usage ?? { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    rawFinishReason: 'stop',
+  } as unknown as TextStreamPart<ToolSet>;
+}
+
 /**
  * Configuration for AIService.
  */
@@ -70,7 +92,7 @@ export class AIService implements IAIService {
 
   // ── IAIService implementation ──────────────────────────────────
 
-  async chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult> {
+  async chat(messages: ModelMessage[], options?: AIRequestOptions): Promise<AIResult> {
     this.logger.debug('[AI] chat', { messageCount: messages.length, model: options?.model });
     return this.adapter.chat(messages, options);
   }
@@ -81,16 +103,16 @@ export class AIService implements IAIService {
   }
 
   async *streamChat(
-    messages: AIMessage[],
+    messages: ModelMessage[],
     options?: AIRequestOptions,
-  ): AsyncIterable<AIStreamEvent> {
+  ): AsyncIterable<TextStreamPart<ToolSet>> {
     this.logger.debug('[AI] streamChat', { messageCount: messages.length, model: options?.model });
 
     if (!this.adapter.streamChat) {
       // Fallback: emit the entire response as a single text-delta + finish
       const result = await this.adapter.chat(messages, options);
-      yield { type: 'text-delta', textDelta: result.content };
-      yield { type: 'finish', result };
+      yield textDeltaPart('fallback', result.content);
+      yield finishPart(result);
       return;
     }
 
@@ -116,6 +138,12 @@ export class AIService implements IAIService {
   /** Default maximum iterations for the tool call loop. */
   static readonly DEFAULT_MAX_ITERATIONS = 10;
 
+  /** Extract the text value from a ToolExecutionResult's output. */
+  private static extractOutputText(tr: ToolExecutionResult): string {
+    return tr.output && typeof tr.output === 'object' && 'value' in tr.output
+      ? String(tr.output.value) : 'unknown error';
+  }
+
   /**
    * Chat with automatic tool call resolution.
    *
@@ -128,11 +156,11 @@ export class AIService implements IAIService {
    *    maximum number of iterations (`maxIterations`) is reached.
    */
   async chatWithTools(
-    messages: AIMessage[],
+    messages: ModelMessage[],
     options?: ChatWithToolsOptions,
   ): Promise<AIResult> {
-    // Destructure maxIterations out so it is never forwarded to the adapter
-    const { maxIterations: maxIter, ...restOptions } = options ?? {};
+    // Destructure loop-specific options so they are never forwarded to the adapter
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
     const maxIterations = maxIter ?? AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
 
@@ -152,12 +180,17 @@ export class AIService implements IAIService {
     // Working copy of the conversation
     const conversation = [...messages];
 
+    // Track errors across iterations for diagnostics
+    const toolErrors: Array<{ iteration: number; toolName: string; error: string }> = [];
+
     this.logger.debug('[AI] chatWithTools start', {
       messageCount: conversation.length,
       toolCount: mergedTools.length,
       maxIterations,
     });
 
+    let abortedByCallback = false;
+
     for (let iteration = 0; iteration < maxIterations; iteration++) {
       const result = await this.adapter.chat(conversation, chatOptions);
 
@@ -169,32 +202,62 @@ export class AIService implements IAIService {
 
       this.logger.debug('[AI] chatWithTools tool calls', {
         iteration,
-        calls: result.toolCalls.map(tc => tc.name),
+        calls: result.toolCalls.map(tc => tc.toolName),
       });
 
       // Append the assistant's response (with tool call metadata) to the conversation
+      const assistantContent: Array<{ type: 'text'; text: string } | ToolCallPart> = [];
+      if (result.content) assistantContent.push({ type: 'text', text: result.content });
+      assistantContent.push(...result.toolCalls);
       conversation.push({
         role: 'assistant',
-        content: result.content ?? '',
-        toolCalls: result.toolCalls,
-      });
+        content: assistantContent,
+      } as ModelMessage);
 
       // Execute all tool calls in parallel
-      const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
+      const toolResults: ToolExecutionResult[] = await this.toolRegistry.executeAll(result.toolCalls);
 
-      // Append each tool result as a `role: 'tool'` message
+      // Process results: track errors and honour onToolError callback
       for (const tr of toolResults) {
+        if (tr.isError) {
+          // Match tool call by toolCallId for robust attribution
+          const matchedCall = result.toolCalls!.find(tc => tc.toolCallId === tr.toolCallId);
+          const toolName = matchedCall?.toolName ?? 'unknown';
+          const errorText = AIService.extractOutputText(tr);
+          const errorEntry = { iteration, toolName, error: errorText };
+          toolErrors.push(errorEntry);
+          this.logger.warn('[AI] chatWithTools tool error', errorEntry);
+
+          if (onToolError && matchedCall) {
+            const action = onToolError(matchedCall, errorText);
+            if (action === 'abort') {
+              abortedByCallback = true;
+            }
+          }
+        }
+
+        // Append each tool result as a `role: 'tool'` message
         conversation.push({
           role: 'tool',
-          content: tr.content,
-          toolCallId: tr.toolCallId,
-        });
+          content: [tr],
+        } as ModelMessage);
       }
+
+      if (abortedByCallback) {
+        break;
+      }
+    }
+
+    // Distinguish user-driven abort from max-iterations exhaustion in logs
+    if (abortedByCallback) {
+      this.logger.warn('[AI] chatWithTools aborted by onToolError callback', { toolErrors });
+    } else {
+      this.logger.warn('[AI] chatWithTools max iterations reached, forcing final response', {
+        toolErrors: toolErrors.length > 0 ? toolErrors : undefined,
+      });
     }
 
-    // If we exhausted the loop without a final response, make one last
-    // call *without* tools so the model is forced to produce text.
-    this.logger.warn('[AI] chatWithTools max iterations reached, forcing final response');
+    // Make one last call *without* tools so the model is forced to produce text.
     const finalResult = await this.adapter.chat(conversation, {
       ...chatOptions,
       tools: undefined,
@@ -202,4 +265,93 @@ export class AIService implements IAIService {
     });
     return finalResult;
   }
+
+  /**
+   * Stream chat with automatic tool call resolution.
+   *
+   * Works like {@link chatWithTools} but yields SSE events.  When the model
+   * requests tool calls during streaming, they are executed and the results
+   * fed back until a final text stream is produced.
+   */
+  async *streamChatWithTools(
+    messages: ModelMessage[],
+    options?: ChatWithToolsOptions,
+  ): AsyncIterable<TextStreamPart<ToolSet>> {
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
+    const maxIterations = maxIter ?? AIService.DEFAULT_MAX_ITERATIONS;
+    const registeredTools = this.toolRegistry.getAll();
+
+    const mergedTools = [
+      ...registeredTools,
+      ...(restOptions.tools ?? []),
+    ];
+
+    const chatOptions: AIRequestOptions = {
+      ...restOptions,
+      tools: mergedTools.length > 0 ? mergedTools : undefined,
+      toolChoice: mergedTools.length > 0 ? (restOptions.toolChoice ?? 'auto') : undefined,
+    };
+
+    const conversation = [...messages];
+    let abortedByCallback = false;
+
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      // Use non-streaming chat for intermediate tool-call rounds
+      const result = await this.adapter.chat(conversation, chatOptions);
+
+      if (!result.toolCalls || result.toolCalls.length === 0) {
+        // Final round — return the probed result without an extra model call
+        yield textDeltaPart('stream', result.content);
+        yield finishPart(result);
+        return;
+      }
+
+      // Emit tool-call events so the client can see tool execution progress
+      for (const tc of result.toolCalls) {
+        yield { type: 'tool-call', toolCallId: tc.toolCallId, toolName: tc.toolName, input: tc.input } as TextStreamPart<ToolSet>;
+      }
+
+      const assistantContent: Array<{ type: 'text'; text: string } | ToolCallPart> = [];
+      if (result.content) assistantContent.push({ type: 'text', text: result.content });
+      assistantContent.push(...result.toolCalls);
+      conversation.push({
+        role: 'assistant',
+        content: assistantContent,
+      } as ModelMessage);
+
+      const toolResults: ToolExecutionResult[] = await this.toolRegistry.executeAll(result.toolCalls);
+
+      for (const tr of toolResults) {
+        if (tr.isError && onToolError) {
+          const matchedCall = result.toolCalls!.find(tc => tc.toolCallId === tr.toolCallId);
+          if (matchedCall) {
+            const errorText = AIService.extractOutputText(tr);
+            const action = onToolError(matchedCall, errorText);
+            if (action === 'abort') {
+              abortedByCallback = true;
+            }
+          }
+        }
+        conversation.push({
+          role: 'tool',
+          content: [tr],
+        } as ModelMessage);
+      }
+
+      if (abortedByCallback) {
+        break;
+      }
+    }
+
+    // Forced final response (no tools) — either aborted or max iterations
+    if (abortedByCallback) {
+      this.logger.warn('[AI] streamChatWithTools aborted by onToolError callback');
+    } else {
+      this.logger.warn('[AI] streamChatWithTools max iterations reached');
+    }
+    const finalOptions = { ...chatOptions, tools: undefined, toolChoice: undefined };
+    const result = await this.adapter.chat(conversation, finalOptions);
+    yield textDeltaPart('stream', result.content);
+    yield finishPart(result);
+  }
 }

package/src/conversation/in-memory-conversation-service.ts

@@ -2,7 +2,7 @@
 
 import type {
   AIConversation,
-  AIMessage,
+  ModelMessage,
   IAIConversationService,
 } from '@objectstack/spec/contracts';
 
@@ -75,7 +75,7 @@ export class InMemoryConversationService implements IAIConversationService {
     return results;
   }
 
-  async addMessage(conversationId: string, message: AIMessage): Promise<AIConversation> {
+  async addMessage(conversationId: string, message: ModelMessage): Promise<AIConversation> {
     const conversation = this.store.get(conversationId);
     if (!conversation) {
       throw new Error(`Conversation "${conversationId}" not found`);

package/src/conversation/objectql-conversation-service.ts

@@ -3,7 +3,9 @@
 import { randomUUID } from 'node:crypto';
 import type {
   AIConversation,
-  AIMessage,
+  ModelMessage,
+  ToolCallPart,
+  ToolResultPart,
   IAIConversationService,
   IDataEngine,
 } from '@objectstack/spec/contracts';
@@ -157,7 +159,7 @@ export class ObjectQLConversationService implements IAIConversationService {
     return conversations;
   }
 
-  async addMessage(conversationId: string, message: AIMessage): Promise<AIConversation> {
+  async addMessage(conversationId: string, message: ModelMessage): Promise<AIConversation> {
     // Verify conversation exists
     const row: DbConversationRow | null = await this.engine.findOne(CONVERSATIONS_OBJECT, {
       where: { id: conversationId },
@@ -169,14 +171,39 @@ export class ObjectQLConversationService implements IAIConversationService {
     const now = new Date().toISOString();
     const msgId = `msg_${randomUUID()}`;
 
+    // Extract flat fields from the discriminated union
+    let contentStr: string;
+    let toolCallsJson: string | null = null;
+    let toolCallId: string | null = null;
+
+    if (message.role === 'system' || message.role === 'user') {
+      contentStr = typeof message.content === 'string' ? message.content : JSON.stringify(message.content);
+    } else if (message.role === 'assistant') {
+      if (typeof message.content === 'string') {
+        contentStr = message.content;
+      } else {
+        const parts = message.content;
+        const textParts = parts.filter((p): p is { type: 'text'; text: string } => p.type === 'text').map(p => p.text);
+        const toolCalls = parts.filter(p => p.type === 'tool-call');
+        contentStr = textParts.join('');
+        if (toolCalls.length > 0) toolCallsJson = JSON.stringify(toolCalls);
+      }
+    } else if (message.role === 'tool') {
+      contentStr = JSON.stringify(message.content);
+      const firstResult = Array.isArray(message.content) ? message.content[0] : undefined;
+      if (firstResult && 'toolCallId' in firstResult) toolCallId = firstResult.toolCallId;
+    } else {
+      contentStr = '';
+    }
+
     // Insert the message
     await this.engine.insert(MESSAGES_OBJECT, {
       id: msgId,
       conversation_id: conversationId,
       role: message.role,
-      content: message.content,
-      tool_calls: message.toolCalls ? JSON.stringify(message.toolCalls) : null,
-      tool_call_id: message.toolCallId ?? null,
+      content: contentStr,
+      tool_calls: toolCallsJson,
+      tool_call_id: toolCallId,
       created_at: now,
     });
 
@@ -233,20 +260,42 @@ export class ObjectQLConversationService implements IAIConversationService {
   }
 
   /**
-   * Map a database row to an AIMessage.
+   * Map a database row to a ModelMessage.
    */
-  private toMessage(row: DbMessageRow): AIMessage {
-    const msg: AIMessage = {
-      role: row.role,
-      content: row.content,
-    };
-    const toolCalls = this.safeParse<any[]>(row.tool_calls);
-    if (toolCalls) {
-      msg.toolCalls = toolCalls;
-    }
-    if (row.tool_call_id) {
-      msg.toolCallId = row.tool_call_id;
+  private toMessage(row: DbMessageRow): ModelMessage {
+    switch (row.role) {
+      case 'system':
+        return { role: 'system', content: row.content };
+      case 'user':
+        return { role: 'user', content: row.content };
+      case 'assistant': {
+        const toolCalls = this.safeParse<ToolCallPart[]>(row.tool_calls);
+        if (toolCalls && toolCalls.length > 0) {
+          const content: Array<{ type: 'text'; text: string } | ToolCallPart> = [];
+          if (row.content) content.push({ type: 'text', text: row.content });
+          content.push(...toolCalls);
+          return { role: 'assistant', content };
+        }
+        return { role: 'assistant', content: row.content };
+      }
+      case 'tool': {
+        const toolResults = this.safeParse<ToolResultPart[]>(row.content);
+        if (toolResults && toolResults.length > 0 && toolResults[0]?.type === 'tool-result') {
+          return { role: 'tool', content: toolResults };
+        }
+        // Backward compat: old format was a plain string
+        return {
+          role: 'tool',
+          content: [{
+            type: 'tool-result' as const,
+            toolCallId: row.tool_call_id ?? '',
+            toolName: 'unknown',
+            output: { type: 'text' as const, value: row.content },
+          }],
+        };
+      }
+      default:
+        return { role: 'user', content: row.content };
     }
-    return msg;
   }
 }

package/src/index.ts

@@ -10,26 +10,45 @@ export type { AIServicePluginOptions } from './plugin.js';
 
 // Adapters
 export { MemoryLLMAdapter } from './adapters/memory-adapter.js';
+export { VercelLLMAdapter } from './adapters/vercel-adapter.js';
+export type { VercelLLMAdapterConfig } from './adapters/vercel-adapter.js';
 export type { LLMAdapter } from '@objectstack/spec/contracts';
 
+// Vercel Data Stream encoder
+export { encodeStreamPart, encodeVercelDataStream } from './stream/vercel-stream-encoder.js';
+
 // Conversation
 export { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
 export { ObjectQLConversationService } from './conversation/objectql-conversation-service.js';
 
 // Tool registry
 export { ToolRegistry } from './tools/tool-registry.js';
-export type { ToolHandler } from './tools/tool-registry.js';
+export type { ToolHandler, ToolExecutionResult } from './tools/tool-registry.js';
 
 // Data tools
 export { registerDataTools, DATA_TOOL_DEFINITIONS } from './tools/data-tools.js';
 export type { DataToolContext } from './tools/data-tools.js';
 
+// Metadata tools
+export { registerMetadataTools, METADATA_TOOL_DEFINITIONS } from './tools/metadata-tools.js';
+export type { MetadataToolContext } from './tools/metadata-tools.js';
+
+// Individual tool metadata (first-class Tool definitions via defineTool)
+export {
+  createObjectTool,
+  addFieldTool,
+  modifyFieldTool,
+  deleteFieldTool,
+  listMetadataObjectsTool,
+  describeMetadataObjectTool,
+} from './tools/metadata-tools.js';
+
 // Agent runtime
 export { AgentRuntime } from './agent-runtime.js';
 export type { AgentChatContext } from './agent-runtime.js';
 
 // Built-in agents
-export { DATA_CHAT_AGENT } from './agents/index.js';
+export { DATA_CHAT_AGENT, METADATA_ASSISTANT_AGENT } from './agents/index.js';
 
 // Object definitions
 export { AiConversationObject, AiMessageObject } from './objects/index.js';
@@ -37,4 +56,4 @@ export { AiConversationObject, AiMessageObject } from './objects/index.js';
 // Routes
 export { buildAIRoutes } from './routes/ai-routes.js';
 export { buildAgentRoutes } from './routes/agent-routes.js';
-export type { RouteDefinition, RouteRequest, RouteResponse } from './routes/ai-routes.js';
+export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './routes/ai-routes.js';