@objectstack/service-ai 4.0.0 → 4.0.2

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

@@ -2,7 +2,7 @@
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import type { IDataEngine } from '@objectstack/spec/contracts';
-import type { AIMessage } from '@objectstack/spec/contracts';
+import type { ModelMessage } from '@objectstack/spec/contracts';
 import { ObjectQLConversationService } from '../conversation/objectql-conversation-service.js';
 
 // ─────────────────────────────────────────────────────────────────
@@ -242,7 +242,7 @@ describe('ObjectQLConversationService', () => {
   it('should add a user message to a conversation', async () => {
     const conv = await service.create({ title: 'Chat' });
 
-    const msg: AIMessage = { role: 'user', content: 'Hello AI!' };
+    const msg: ModelMessage = { role: 'user', content: 'Hello AI!' };
     const updated = await service.addMessage(conv.id, msg);
 
     expect(updated.messages).toHaveLength(1);
@@ -253,33 +253,49 @@ describe('ObjectQLConversationService', () => {
 
   it('should add a tool message with toolCallId', async () => {
     const conv = await service.create();
-    const msg: AIMessage = {
-      role: 'tool',
-      content: '{"temp": 22}',
-      toolCallId: 'call_abc',
+    const msg: ModelMessage = {
+      role: 'tool' as const,
+      content: [{
+        type: 'tool-result' as const,
+        toolCallId: 'call_abc',
+        toolName: 'get_weather',
+        output: { type: 'text' as const, value: '{"temp": 22}' },
+      }],
     };
 
     const updated = await service.addMessage(conv.id, msg);
     expect(updated.messages).toHaveLength(1);
-    expect(updated.messages[0].toolCallId).toBe('call_abc');
+    const firstMsg = updated.messages[0];
+    if (firstMsg.role === 'tool' && Array.isArray(firstMsg.content)) {
+      expect(firstMsg.content[0].toolCallId).toBe('call_abc');
+    } else {
+      throw new Error('Expected tool message with array content');
+    }
   });
 
   it('should add an assistant message with toolCalls', async () => {
     const conv = await service.create();
-    const msg: AIMessage = {
-      role: 'assistant',
-      content: '',
-      toolCalls: [{ id: 'call_1', name: 'get_weather', arguments: '{}' }],
+    const msg: ModelMessage = {
+      role: 'assistant' as const,
+      content: [
+        { type: 'tool-call' as const, toolCallId: 'call_1', toolName: 'get_weather', input: {} },
+      ],
     };
 
     const updated = await service.addMessage(conv.id, msg);
     expect(updated.messages).toHaveLength(1);
-    expect(updated.messages[0].toolCalls).toHaveLength(1);
-    expect(updated.messages[0].toolCalls![0].name).toBe('get_weather');
+    const firstMsg = updated.messages[0];
+    if (firstMsg.role === 'assistant' && Array.isArray(firstMsg.content)) {
+      const toolCallParts = firstMsg.content.filter((p) => p.type === 'tool-call');
+      expect(toolCallParts).toHaveLength(1);
+      expect(toolCallParts[0].toolName).toBe('get_weather');
+    } else {
+      throw new Error('Expected assistant message with array content');
+    }
   });
 
   it('should throw when adding message to non-existent conversation', async () => {
-    const msg: AIMessage = { role: 'user', content: 'Hello' };
+    const msg: ModelMessage = { role: 'user', content: 'Hello' };
     await expect(service.addMessage('conv_ghost', msg)).rejects.toThrow(
       'Conversation "conv_ghost" not found',
     );
@@ -352,13 +368,15 @@ describe('ObjectQLConversationService', () => {
 
   it('should handle invalid JSON in tool_calls gracefully', async () => {
     const conv = await service.create();
-    await service.addMessage(conv.id, { role: 'user', content: 'hi' });
+    await service.addMessage(conv.id, { role: 'assistant', content: 'checking tools' });
 
     // Manually corrupt tool_calls in the engine
     const msgs = await engine.find('ai_messages', { where: { conversation_id: conv.id } });
     msgs[0].tool_calls = 'broken{json';
 
     const fetched = await service.get(conv.id);
-    expect(fetched!.messages[0].toolCalls).toBeUndefined();
+    // With broken tool_calls, the assistant message should still load with string content
+    expect(fetched!.messages[0].role).toBe('assistant');
+    expect(fetched!.messages[0].content).toBe('checking tools');
   });
 });

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

@@ -0,0 +1,263 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import type { TextStreamPart, ToolSet } from '@objectstack/spec/contracts';
+import { encodeStreamPart, encodeVercelDataStream } from '../stream/vercel-stream-encoder.js';
+
+// Helper to parse SSE frame payload
+function parseSSE(frame: string): Record<string, unknown> | null {
+  if (!frame.startsWith('data: ') || !frame.endsWith('\n\n')) return null;
+  const json = frame.slice(6, -2);
+  if (json === '[DONE]') return null;
+  return JSON.parse(json);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// encodeStreamPart — individual frame encoding (v6 SSE format)
+// ─────────────────────────────────────────────────────────────────
+
+describe('encodeStreamPart', () => {
+  it('should encode text-delta as SSE frame', () => {
+    const part = { type: 'text-delta', text: 'Hello world' } as TextStreamPart<ToolSet>;
+    const frame = encodeStreamPart(part);
+    const payload = parseSSE(frame);
+    expect(payload).toEqual({ type: 'text-delta', id: '0', delta: 'Hello world' });
+  });
+
+  it('should JSON-escape text-delta content', () => {
+    const part = { type: 'text-delta', text: 'say "hi"\nnewline' } as TextStreamPart<ToolSet>;
+    const frame = encodeStreamPart(part);
+    expect(frame.startsWith('data: ')).toBe(true);
+    expect(frame.endsWith('\n\n')).toBe(true);
+
+    // Verify round-trip: decode the frame payload back to the original text
+    const payload = parseSSE(frame);
+    expect(payload).not.toBeNull();
+    expect((payload as Record<string, unknown>).delta).toBe('say "hi"\nnewline');
+  });
+
+  it('should encode tool-call as tool-input-available SSE frame', () => {
+    const part = {
+      type: 'tool-call',
+      toolCallId: 'call_1',
+      toolName: 'get_weather',
+      input: { location: 'San Francisco' },
+    } as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    const payload = parseSSE(frame);
+    expect(payload).toEqual({
+      type: 'tool-input-available',
+      toolCallId: 'call_1',
+      toolName: 'get_weather',
+      input: { location: 'San Francisco' },
+    });
+  });
+
+  it('should encode tool-input-start as SSE frame', () => {
+    const part = {
+      type: 'tool-input-start',
+      id: 'call_2',
+      toolName: 'search',
+    } as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    const payload = parseSSE(frame);
+    expect(payload).toEqual({
+      type: 'tool-input-start',
+      toolCallId: 'call_2',
+      toolName: 'search',
+    });
+  });
+
+  it('should encode tool-input-delta as SSE frame', () => {
+    const part = {
+      type: 'tool-input-delta',
+      id: 'call_2',
+      delta: '{"query":',
+    } as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    const payload = parseSSE(frame);
+    expect(payload).toEqual({
+      type: 'tool-input-delta',
+      toolCallId: 'call_2',
+      inputTextDelta: '{"query":',
+    });
+  });
+
+  it('should encode tool-result as tool-output-available SSE frame', () => {
+    const part = {
+      type: 'tool-result',
+      toolCallId: 'call_1',
+      toolName: 'get_weather',
+      output: { temperature: 72 },
+    } as TextStreamPart<ToolSet>;
+
+    const frame = encodeStreamPart(part);
+    const payload = parseSSE(frame);
+    expect(payload).toEqual({
+      type: 'tool-output-available',
+      toolCallId: 'call_1',
+      output: { temperature: 72 },
+    });
+  });
+
+  it('should return empty string for finish (handled by generator)', () => {
+    const part = {
+      type: 'finish',
+      finishReason: 'stop',
+      totalUsage: { promptTokens: 10, completionTokens: 20, totalTokens: 30 },
+      rawFinishReason: 'stop',
+    } as unknown as TextStreamPart<ToolSet>;
+
+    expect(encodeStreamPart(part)).toBe('');
+  });
+
+  it('should return empty string for finish-step (handled by generator)', () => {
+    const part = {
+      type: 'finish-step',
+      finishReason: 'tool-calls',
+      usage: { promptTokens: 5, completionTokens: 10, totalTokens: 15 },
+    } as unknown as TextStreamPart<ToolSet>;
+
+    expect(encodeStreamPart(part)).toBe('');
+  });
+
+  it('should return empty string for unknown event types', () => {
+    const part = { type: 'unknown-internal' } as unknown as TextStreamPart<ToolSet>;
+    expect(encodeStreamPart(part)).toBe('');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────
+// encodeVercelDataStream — async iterable transformation (v6 SSE)
+//
+// Lifecycle: start → start-step → text-start → ...events... → text-end → finish-step → finish → [DONE]
+// ─────────────────────────────────────────────────────────────────
+
+describe('encodeVercelDataStream', () => {
+  it('should transform stream events into v6 UI Message Stream frames', async () => {
+    async function* source(): AsyncIterable<TextStreamPart<ToolSet>> {
+      yield { type: 'text-delta', text: 'Hello' } as TextStreamPart<ToolSet>;
+      yield { type: 'text-delta', text: ' world' } as TextStreamPart<ToolSet>;
+      yield {
+        type: 'finish',
+        finishReason: 'stop',
+        totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        rawFinishReason: 'stop',
+      } as unknown as TextStreamPart<ToolSet>;
+    }
+
+    const frames: string[] = [];
+    for await (const frame of encodeVercelDataStream(source())) {
+      frames.push(frame);
+    }
+
+    // Preamble: start, start-step, text-start
+    // Content: 2 text-deltas
+    // Postamble: text-end, finish-step, finish, [DONE]
+    expect(frames).toHaveLength(9);
+
+    // Preamble
+    expect(parseSSE(frames[0])).toEqual({ type: 'start' });
+    expect(parseSSE(frames[1])).toEqual({ type: 'start-step' });
+    expect(parseSSE(frames[2])).toEqual({ type: 'text-start', id: '0' });
+
+    // Content
+    expect(parseSSE(frames[3])).toMatchObject({ type: 'text-delta', delta: 'Hello' });
+    expect(parseSSE(frames[4])).toMatchObject({ type: 'text-delta', delta: ' world' });
+
+    // Postamble
+    expect(parseSSE(frames[5])).toEqual({ type: 'text-end', id: '0' });
+    expect(parseSSE(frames[6])).toEqual({ type: 'finish-step' });
+    expect(parseSSE(frames[7])).toMatchObject({ type: 'finish', finishReason: 'stop' });
+    expect(frames[8]).toBe('data: [DONE]\n\n');
+  });
+
+  it('should skip events with no wire format mapping', async () => {
+    async function* source(): AsyncIterable<TextStreamPart<ToolSet>> {
+      yield { type: 'text-delta', text: 'Hi' } as TextStreamPart<ToolSet>;
+      yield { type: 'unknown-internal' } as unknown as TextStreamPart<ToolSet>;
+      yield {
+        type: 'finish',
+        finishReason: 'stop',
+        totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        rawFinishReason: 'stop',
+      } as unknown as TextStreamPart<ToolSet>;
+    }
+
+    const frames: string[] = [];
+    for await (const frame of encodeVercelDataStream(source())) {
+      frames.push(frame);
+    }
+
+    // Preamble(3) + 1 text-delta + Postamble(4) = 8 ('unknown-internal' dropped)
+    expect(frames).toHaveLength(8);
+    expect(parseSSE(frames[3])).toMatchObject({ type: 'text-delta', delta: 'Hi' });
+  });
+
+  it('should handle empty stream', async () => {
+    async function* source(): AsyncIterable<TextStreamPart<ToolSet>> {
+      // empty
+    }
+
+    const frames: string[] = [];
+    for await (const frame of encodeVercelDataStream(source())) {
+      frames.push(frame);
+    }
+
+    // Preamble(3) + text-end + finish-step + finish + [DONE] = 7
+    expect(frames).toHaveLength(7);
+    expect(parseSSE(frames[0])).toEqual({ type: 'start' });
+    expect(parseSSE(frames[3])).toEqual({ type: 'text-end', id: '0' });
+    expect(frames[6]).toBe('data: [DONE]\n\n');
+  });
+
+  it('should handle tool-call events in stream', async () => {
+    async function* source(): AsyncIterable<TextStreamPart<ToolSet>> {
+      yield {
+        type: 'tool-call',
+        toolCallId: 'call_1',
+        toolName: 'search',
+        input: { query: 'test' },
+      } as TextStreamPart<ToolSet>;
+      yield {
+        type: 'tool-result',
+        toolCallId: 'call_1',
+        toolName: 'search',
+        output: { hits: 42 },
+      } as TextStreamPart<ToolSet>;
+      yield {
+        type: 'finish',
+        finishReason: 'tool-calls',
+        totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        rawFinishReason: 'tool_calls',
+      } as unknown as TextStreamPart<ToolSet>;
+    }
+
+    const frames: string[] = [];
+    for await (const frame of encodeVercelDataStream(source())) {
+      frames.push(frame);
+    }
+
+    // Preamble(3) + tool-input-available + tool-output-available + Postamble(4) = 9
+    expect(frames).toHaveLength(9);
+
+    // Verify tool-call frame content
+    const toolCallPayload = parseSSE(frames[3]);
+    expect(toolCallPayload).toMatchObject({
+      type: 'tool-input-available',
+      toolCallId: 'call_1',
+      toolName: 'search',
+      input: { query: 'test' },
+    });
+
+    const toolResultPayload = parseSSE(frames[4]);
+    expect(toolResultPayload).toMatchObject({
+      type: 'tool-output-available',
+      toolCallId: 'call_1',
+      output: { hits: 42 },
+    });
+  });
+});

package/src/adapters/index.ts

@@ -2,3 +2,5 @@
 
 export type { LLMAdapter } from '@objectstack/spec/contracts';
 export { MemoryLLMAdapter } from './memory-adapter.js';
+export { VercelLLMAdapter } from './vercel-adapter.js';
+export type { VercelLLMAdapterConfig } from './vercel-adapter.js';

package/src/adapters/memory-adapter.ts

@@ -1,10 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type {
-  AIMessage,
+  ModelMessage,
   AIRequestOptions,
   AIResult,
-  AIStreamEvent,
+  TextStreamPart,
+  ToolSet,
 } from '@objectstack/spec/contracts';
 import type { LLMAdapter } from '@objectstack/spec/contracts';
 
@@ -17,10 +18,12 @@ import type { LLMAdapter } from '@objectstack/spec/contracts';
 export class MemoryLLMAdapter implements LLMAdapter {
   readonly name = 'memory';
 
-  async chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult> {
+  async chat(messages: ModelMessage[], options?: AIRequestOptions): Promise<AIResult> {
     const lastUserMessage = [...messages].reverse().find(m => m.role === 'user');
+    const userContent = lastUserMessage?.content;
+    const text = typeof userContent === 'string' ? userContent : '(complex content)';
     const content = lastUserMessage
-      ? `[memory] ${lastUserMessage.content}`
+      ? `[memory] ${text}`
       : '[memory] (no user message)';
 
     return {
@@ -39,17 +42,22 @@ export class MemoryLLMAdapter implements LLMAdapter {
   }
 
   async *streamChat(
-    messages: AIMessage[],
+    messages: ModelMessage[],
     _options?: AIRequestOptions,
-  ): AsyncIterable<AIStreamEvent> {
+  ): AsyncIterable<TextStreamPart<ToolSet>> {
     const result = await this.chat(messages);
     // Emit word-by-word deltas for realistic streaming simulation
     const words = result.content.split(' ');
     for (let i = 0; i < words.length; i++) {
-      const textDelta = i === 0 ? words[i] : ` ${words[i]}`;
-      yield { type: 'text-delta', textDelta };
+      const wordText = i === 0 ? words[i] : ` ${words[i]}`;
+      yield { type: 'text-delta', id: `delta_${i}`, text: wordText } as TextStreamPart<ToolSet>;
     }
-    yield { type: 'finish', result };
+    yield {
+      type: 'finish',
+      finishReason: 'stop' as const,
+      totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      rawFinishReason: 'stop',
+    } as unknown as TextStreamPart<ToolSet>;
   }
 
   async embed(input: string | string[]): Promise<number[][]> {

package/src/adapters/vercel-adapter.ts

@@ -0,0 +1,148 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  ModelMessage,
+  AIRequestOptions,
+  AIResult,
+  TextStreamPart,
+  ToolSet,
+} from '@objectstack/spec/contracts';
+import type { LLMAdapter } from '@objectstack/spec/contracts';
+import type { AIToolDefinition } from '@objectstack/spec/contracts';
+import type { LanguageModelV2 } from '@ai-sdk/provider';
+import { generateText, streamText, tool as vercelTool, jsonSchema } from 'ai';
+
+/**
+ * Convert ObjectStack `AIRequestOptions` into the subset of Vercel AI SDK
+ * options supported by `generateText` / `streamText`.
+ *
+ * Forwards: temperature, maxTokens, stop (→ stopSequences), tools, toolChoice.
+ */
+function buildVercelOptions(options?: AIRequestOptions): Record<string, unknown> {
+  if (!options) return {};
+
+  const opts: Record<string, unknown> = {};
+
+  if (options.temperature != null) opts.temperature = options.temperature;
+  if (options.maxTokens != null) opts.maxTokens = options.maxTokens;
+  if (options.stop?.length) opts.stopSequences = options.stop;
+
+  if (options.tools?.length) {
+    const tools: Record<string, unknown> = {};
+    for (const t of options.tools as AIToolDefinition[]) {
+      tools[t.name] = vercelTool({
+        description: t.description,
+        inputSchema: jsonSchema(t.parameters as any),
+      });
+    }
+    opts.tools = tools;
+  }
+
+  if (options.toolChoice != null) {
+    opts.toolChoice = options.toolChoice;
+  }
+
+  return opts;
+}
+
+/**
+ * VercelLLMAdapter — Production LLM adapter powered by the Vercel AI SDK.
+ *
+ * Wraps `generateText` / `streamText` from the `ai` package, delegating to
+ * any Vercel AI SDK–compatible model provider (OpenAI, Anthropic, Google,
+ * Ollama, etc.).
+ *
+ * @example
+ * ```typescript
+ * import { openai } from '@ai-sdk/openai';
+ * import { VercelLLMAdapter } from '@objectstack/service-ai';
+ *
+ * const adapter = new VercelLLMAdapter({ model: openai('gpt-4o') });
+ * ```
+ */
+export class VercelLLMAdapter implements LLMAdapter {
+  readonly name = 'vercel';
+
+  private readonly model: LanguageModelV2;
+
+  constructor(config: VercelLLMAdapterConfig) {
+    this.model = config.model;
+  }
+
+  async chat(messages: ModelMessage[], options?: AIRequestOptions): Promise<AIResult> {
+    const result = await generateText({
+      model: this.model,
+      messages,
+      ...buildVercelOptions(options),
+    });
+
+    return {
+      content: result.text,
+      model: result.response?.modelId,
+      toolCalls: result.toolCalls?.length ? result.toolCalls : undefined,
+      usage: result.usage ? {
+        promptTokens: result.usage.inputTokens ?? 0,
+        completionTokens: result.usage.outputTokens ?? 0,
+        totalTokens: result.usage.totalTokens ?? 0,
+      } : undefined,
+    };
+  }
+
+  async complete(prompt: string, options?: AIRequestOptions): Promise<AIResult> {
+    const result = await generateText({
+      model: this.model,
+      prompt,
+      ...buildVercelOptions(options),
+    });
+
+    return {
+      content: result.text,
+      model: result.response?.modelId,
+      usage: result.usage ? {
+        promptTokens: result.usage.inputTokens ?? 0,
+        completionTokens: result.usage.outputTokens ?? 0,
+        totalTokens: result.usage.totalTokens ?? 0,
+      } : undefined,
+    };
+  }
+
+  async *streamChat(
+    messages: ModelMessage[],
+    options?: AIRequestOptions,
+  ): AsyncIterable<TextStreamPart<ToolSet>> {
+    const result = streamText({
+      model: this.model,
+      messages,
+      ...buildVercelOptions(options),
+    });
+
+    for await (const part of result.fullStream) {
+      yield part as TextStreamPart<ToolSet>;
+    }
+  }
+
+  async embed(_input: string | string[]): Promise<number[][]> {
+    // Vercel AI SDK uses a separate EmbeddingModel — not supported via this adapter.
+    throw new Error(
+      '[VercelLLMAdapter] Embeddings require a dedicated EmbeddingModel. ' +
+      'Configure an embedding adapter instead.',
+    );
+  }
+
+  async listModels(): Promise<string[]> {
+    // Model listing is provider-specific and not available through the base SDK.
+    return [];
+  }
+}
+
+/**
+ * Configuration for the Vercel LLM adapter.
+ */
+export interface VercelLLMAdapterConfig {
+  /**
+   * A Vercel AI SDK–compatible language model instance.
+   *
+   * @example `openai('gpt-4o')` or `anthropic('claude-sonnet-4-20250514')`
+   */
+  model: LanguageModelV2;
+}

package/src/agent-runtime.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type {
-  AIMessage,
+  ModelMessage,
   AIRequestOptions,
   AIToolDefinition,
   IMetadataService,
@@ -40,6 +40,30 @@ export class AgentRuntime {
 
   // ── Public API ────────────────────────────────────────────────
 
+  /**
+   * List all active agents registered in the metadata service.
+   *
+   * Returns a summary for each agent (name, label, role) suitable
+   * for populating an agent selector dropdown in the UI.
+   */
+  async listAgents(): Promise<Array<{ name: string; label: string; role: string }>> {
+    const rawItems = await this.metadataService.list('agent');
+    const agents: Array<{ name: string; label: string; role: string }> = [];
+
+    for (const raw of rawItems) {
+      const result = AgentSchema.safeParse(raw);
+      if (result.success && result.data.active) {
+        agents.push({
+          name: result.data.name,
+          label: result.data.label,
+          role: result.data.role,
+        });
+      }
+    }
+
+    return agents;
+  }
+
   /**
    * Load and validate an agent definition by name.
    *
@@ -63,7 +87,7 @@ export class AgentRuntime {
    * Build the system message(s) that should be prepended to the
    * conversation when chatting with the given agent.
    */
-  buildSystemMessages(agent: Agent, context?: AgentChatContext): AIMessage[] {
+  buildSystemMessages(agent: Agent, context?: AgentChatContext): ModelMessage[] {
     const parts: string[] = [];
 
     // Base instructions
@@ -80,7 +104,7 @@ export class AgentRuntime {
       }
     }
 
-    return [{ role: 'system', content: parts.join('\n') }];
+    return [{ role: 'system' as const, content: parts.join('\n') }];
   }
 
   /**

package/src/agents/index.ts

@@ -1,3 +1,4 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export { DATA_CHAT_AGENT } from './data-chat-agent.js';
+export { METADATA_ASSISTANT_AGENT } from './metadata-assistant-agent.js';