@objectstack/service-ai 4.0.3 → 4.0.5

package/src/plugin.ts

@@ -1,391 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import type { IAIService, IAIConversationService, IDataEngine, IMetadataService, LLMAdapter } from '@objectstack/spec/contracts';
-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';
-import { registerMetadataTools } from './tools/metadata-tools.js';
-import { AgentRuntime } from './agent-runtime.js';
-import { DATA_CHAT_AGENT, METADATA_ASSISTANT_AGENT } from './agents/index.js';
-import { VercelLLMAdapter } from './adapters/vercel-adapter.js';
-import { MemoryLLMAdapter } from './adapters/memory-adapter.js';
-
-/**
- * Configuration options for the AIServicePlugin.
- */
-export interface AIServicePluginOptions {
-  /** LLM adapter to use (defaults to MemoryLLMAdapter). */
-  adapter?: LLMAdapter;
-  /** Enable debug logging. */
-  debug?: boolean;
-  /** Explicit conversation service override. When set, auto-detection is skipped. */
-  conversationService?: IAIConversationService;
-}
-
-/**
- * AIServicePlugin — Kernel plugin for the unified AI capability service.
- *
- * Lifecycle:
- * 1. **init** — Creates {@link AIService}, registers as `'ai'` service.
- *    If an existing AI service is already registered, it is replaced.
- * 2. **start** — Triggers `'ai:ready'` hook so other plugins can register
- *    tools or extend the service.  Registers REST/SSE routes.
- * 3. **destroy** — Cleans up references.
- *
- * @example
- * ```ts
- * import { LiteKernel } from '@objectstack/core';
- * import { AIServicePlugin } from '@objectstack/service-ai';
- *
- * const kernel = new LiteKernel();
- * kernel.use(new AIServicePlugin());
- * await kernel.bootstrap();
- *
- * const ai = kernel.getService<IAIService>('ai');
- * const result = await ai.chat([{ role: 'user', content: 'Hello' }]);
- * ```
- */
-export class AIServicePlugin implements Plugin {
-  name = 'com.objectstack.service-ai';
-  version = '1.0.0';
-  type = 'standard' as const;
-  dependencies: string[] = ['com.objectstack.engine.objectql']; // manifest service required
-
-  private service?: AIService;
-  private readonly options: AIServicePluginOptions;
-
-  constructor(options: AIServicePluginOptions = {}) {
-    this.options = options;
-  }
-
-  /**
-   * Auto-detect LLM provider from environment variables.
-   *
-   * Priority order:
-   * 1. AI_GATEWAY_MODEL → Vercel AI Gateway
-   * 2. OPENAI_API_KEY → OpenAI
-   * 3. ANTHROPIC_API_KEY → Anthropic
-   * 4. GOOGLE_GENERATIVE_AI_API_KEY → Google
-   * 5. Fallback → MemoryLLMAdapter
-   *
-   * Returns the adapter and a description for logging.
-   */
-  private async detectAdapter(ctx: PluginContext): Promise<{ adapter: LLMAdapter; description: string }> {
-    // 1. Vercel AI Gateway — works with any provider via gateway('provider/model')
-    const gatewayModel = process.env.AI_GATEWAY_MODEL;
-    if (gatewayModel) {
-      try {
-        const gatewayPkg = '@ai-sdk/gateway';
-        const { gateway } = await import(/* webpackIgnore: true */ gatewayPkg);
-        const adapter = new VercelLLMAdapter({ model: gateway(gatewayModel) });
-        return { adapter, description: `Vercel AI Gateway (model: ${gatewayModel})` };
-      } catch (err) {
-        ctx.logger.warn(
-          `[AI] Failed to load @ai-sdk/gateway for AI_GATEWAY_MODEL=${gatewayModel}, trying next provider`,
-          err instanceof Error ? { error: err.message } : undefined
-        );
-      }
-    }
-
-    // 2. Direct provider SDKs
-    const providerConfigs: Array<{
-      envKey: string;
-      pkg: string;
-      factory: string;
-      defaultModel: string;
-      displayName: string;
-    }> = [
-      {
-        envKey: 'OPENAI_API_KEY',
-        pkg: '@ai-sdk/openai',
-        factory: 'openai',
-        defaultModel: 'gpt-4o',
-        displayName: 'OpenAI'
-      },
-      {
-        envKey: 'ANTHROPIC_API_KEY',
-        pkg: '@ai-sdk/anthropic',
-        factory: 'anthropic',
-        defaultModel: 'claude-sonnet-4-20250514',
-        displayName: 'Anthropic'
-      },
-      {
-        envKey: 'GOOGLE_GENERATIVE_AI_API_KEY',
-        pkg: '@ai-sdk/google',
-        factory: 'google',
-        defaultModel: 'gemini-2.0-flash',
-        displayName: 'Google'
-      },
-    ];
-
-    for (const { envKey, pkg, factory, defaultModel, displayName } of providerConfigs) {
-      if (process.env[envKey]) {
-        try {
-          const mod = await import(/* webpackIgnore: true */ pkg);
-          const createModel = mod[factory] ?? mod.default;
-          if (typeof createModel === 'function') {
-            const modelId = process.env.AI_MODEL ?? defaultModel;
-            const adapter = new VercelLLMAdapter({ model: createModel(modelId) });
-            return { adapter, description: `${displayName} (model: ${modelId})` };
-          }
-        } catch (err) {
-          ctx.logger.warn(
-            `[AI] Failed to load ${pkg} for ${envKey}, trying next provider`,
-            err instanceof Error ? { error: err.message } : undefined
-          );
-        }
-      }
-    }
-
-    // 3. Fallback to MemoryLLMAdapter
-    ctx.logger.warn('[AI] No LLM provider configured via environment variables. Falling back to MemoryLLMAdapter (echo mode). Set AI_GATEWAY_MODEL, OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY to use a real LLM.');
-    return { adapter: new MemoryLLMAdapter(), description: 'MemoryLLMAdapter (echo mode - for testing only)' };
-  }
-
-  async init(ctx: PluginContext): Promise<void> {
-    // Check if there is an existing AI service (e.g. from dev-plugin)
-    let hasExisting = false;
-    try {
-      const existing = ctx.getService<IAIService>('ai');
-      if (existing && typeof existing.chat === 'function') {
-        hasExisting = true;
-        ctx.logger.debug('[AI] Found existing AI service, replacing');
-      }
-    } catch {
-      // No existing service — that's fine
-    }
-
-    // Determine conversation service: explicit > auto-detect IDataEngine > InMemory fallback
-    let conversationService: IAIConversationService | undefined = this.options.conversationService;
-    if (!conversationService) {
-      try {
-        const engine = ctx.getService<IDataEngine>('data');
-        if (engine && typeof engine.find === 'function') {
-          conversationService = new ObjectQLConversationService(engine);
-          ctx.logger.info('[AI] Using ObjectQLConversationService (IDataEngine detected)');
-        }
-      } catch {
-        // No data engine — fall back to InMemory
-      }
-    }
-
-    // Determine LLM adapter: explicit > auto-detect from env > MemoryLLMAdapter fallback
-    let adapter: LLMAdapter;
-    let adapterDescription: string;
-
-    if (this.options.adapter) {
-      // User provided an explicit adapter
-      adapter = this.options.adapter;
-      adapterDescription = `${adapter.name} (explicitly configured)`;
-    } else {
-      // Auto-detect from environment variables
-      const detected = await this.detectAdapter(ctx);
-      adapter = detected.adapter;
-      adapterDescription = detected.description;
-    }
-
-    // Log the selected adapter
-    ctx.logger.info(`[AI] Using LLM adapter: ${adapterDescription}`);
-
-    const config: AIServiceConfig = {
-      adapter,
-      logger: ctx.logger,
-      conversationService,
-    };
-
-    this.service = new AIService(config);
-
-    // Register or replace the AI service
-    if (hasExisting) {
-      ctx.replaceService('ai', this.service);
-    } else {
-      ctx.registerService('ai', this.service);
-    }
-
-    // Register AI system objects via the manifest service.
-    ctx.getService<{ register(m: any): void }>('manifest').register({
-      id: 'com.objectstack.service-ai',
-      name: 'AI Service',
-      version: '1.0.0',
-      type: 'plugin',
-      namespace: 'ai',
-      objects: [AiConversationObject, AiMessageObject],
-    });
-
-    if (this.options.debug) {
-      ctx.hook('ai:beforeChat', async (messages: unknown) => {
-        ctx.logger.debug('[AI] Before chat', { messages });
-      });
-    }
-
-    // Contribute navigation items to the Setup App (if SetupPlugin is loaded).
-    try {
-      const setupNav = ctx.getService<{ contribute(c: any): void }>('setupNav');
-      if (setupNav) {
-        setupNav.contribute({
-          areaId: 'area_ai',
-          items: [
-            { id: 'nav_ai_conversations', type: 'object', label: { key: 'setup.nav.ai_conversations', defaultValue: 'Conversations' }, objectName: 'conversations', icon: 'message-square', order: 10 },
-            { id: 'nav_ai_messages', type: 'object', label: { key: 'setup.nav.ai_messages', defaultValue: 'Messages' }, objectName: 'messages', icon: 'messages-square', order: 20 },
-          ],
-        });
-        ctx.logger.info('[AI] Navigation items contributed to Setup App');
-      }
-    } catch {
-      // SetupPlugin not loaded — skip silently
-    }
-
-    ctx.logger.info('[AI] Service initialized');
-  }
-
-  async start(ctx: PluginContext): Promise<void> {
-    if (!this.service) return;
-
-    // ── Auto-register built-in tools & agents when services are available ──
-    let metadataService: IMetadataService | undefined;
-    try {
-      metadataService = ctx.getService<IMetadataService>('metadata');
-      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 only the data engine
-    try {
-      const dataEngine = ctx.getService<IDataEngine>('data');
-      if (dataEngine) {
-        registerDataTools(this.service.toolRegistry, { dataEngine });
-        ctx.logger.info('[AI] Built-in data tools registered');
-
-        // 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 {
-      ctx.logger.debug('[AI] Data engine not available, skipping data tools');
-    }
-
-    // Metadata tools require only the metadata service
-    if (metadataService) {
-      try {
-        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
-        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);
-      }
-    }
-
-    // Trigger hook to notify AI service is ready — other plugins can register tools
-    await ctx.trigger('ai:ready', this.service);
-
-    // 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
-    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');
-    }
-
-    // Trigger hook so HTTP server plugins can mount these routes
-    await ctx.trigger('ai:routes', routes);
-
-    // Cache routes on the kernel so HttpDispatcher can find them
-    const kernel = ctx.getKernel();
-    if (kernel) {
-      (kernel as any).__aiRoutes = routes;
-    }
-
-    ctx.logger.info(
-      `[AI] Service started — adapter="${this.service.adapterName}", ` +
-      `tools=${this.service.toolRegistry.size}, ` +
-      `routes=${routes.length}`,
-    );
-  }
-
-  async destroy(): Promise<void> {
-    this.service = undefined;
-  }
-}

package/src/routes/agent-routes.ts

@@ -1,190 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { ModelMessage } from '@objectstack/spec/contracts';
-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.
- *
- * Only `user` and `assistant` are accepted from clients.
- * `system` messages are injected server-side from agent instructions,
- * and `tool` messages are produced by the tool-call loop — accepting
- * either from the client would allow callers to override agent
- * guardrails or inject fabricated tool results.
- */
-const ALLOWED_AGENT_ROLES = new Set<string>(['user', 'assistant']);
-
-function validateAgentMessage(raw: unknown): string | null {
-  if (typeof raw !== 'object' || raw === null) {
-    return 'each message must be an object';
-  }
-  const msg = raw as Record<string, unknown>;
-  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`;
-  }
-
-  // Assistant messages may legitimately have empty content (e.g. tool-call-only)
-  const allowEmpty = msg.role === 'assistant';
-  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
-}
-
-/**
- * Build agent-specific REST routes.
- *
- * | Method | Path | Description |
- * |:---|:---|:---|
- * | GET  | /api/v1/ai/agents | List all active agents |
- * | POST | /api/v1/ai/agents/:agentName/chat | Chat with a specific agent |
- */
-export function buildAgentRoutes(
-  aiService: AIService,
-  agentRuntime: AgentRuntime,
-  logger: Logger,
-): RouteDefinition[] {
-  return [
-    // ── List active agents ──────────────────────────────────────
-    {
-      method: 'GET',
-      path: '/api/v1/ai/agents',
-      description: 'List all active AI agents',
-      auth: true,
-      permissions: ['ai:chat'],
-      handler: async () => {
-        try {
-          const agents = await agentRuntime.listAgents();
-          return { status: 200, body: { agents } };
-        } catch (err) {
-          logger.error(
-            '[AI Route] /agents list error',
-            err instanceof Error ? err : undefined,
-          );
-          return { status: 500, body: { error: 'Internal AI service error' } };
-        }
-      },
-    },
-
-    // ── 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 (supports Vercel AI Data Stream Protocol)',
-      auth: true,
-      permissions: ['ai:chat', 'ai:agents'],
-      handler: async (req) => {
-        const agentName = req.params?.agentName;
-        if (!agentName) {
-          return { status: 400, body: { error: 'agentName parameter is required' } };
-        }
-
-        // Parse request body
-        const body = (req.body ?? {}) as Record<string, unknown>;
-        const {
-          messages: rawMessages,
-          context: chatContext,
-          options: extraOptions,
-        } = body as {
-          messages?: unknown[];
-          context?: AgentChatContext;
-          options?: Record<string, unknown>;
-        };
-
-        if (!Array.isArray(rawMessages) || rawMessages.length === 0) {
-          return { status: 400, body: { error: 'messages array is required' } };
-        }
-
-        for (const msg of rawMessages) {
-          const err = validateAgentMessage(msg);
-          if (err) return { status: 400, body: { error: err } };
-        }
-
-        // Load agent definition
-        const agent = await agentRuntime.loadAgent(agentName);
-        if (!agent) {
-          return { status: 404, body: { error: `Agent "${agentName}" not found` } };
-        }
-        if (!agent.active) {
-          return { status: 403, body: { error: `Agent "${agentName}" is not active` } };
-        }
-
-        try {
-          // Build system messages from agent instructions + UI context
-          const systemMessages = agentRuntime.buildSystemMessages(agent, chatContext);
-
-          // Resolve agent model/tools → request options
-          const agentOptions = agentRuntime.buildRequestOptions(
-            agent,
-            aiService.toolRegistry.getAll(),
-          );
-
-          // Whitelist only safe caller overrides — block tools/toolChoice/model
-          // to prevent tool-definition injection or DoS via unregistered tools.
-          const safeOverrides: Record<string, unknown> = {};
-          if (extraOptions) {
-            const ALLOWED_KEYS = new Set(['temperature', 'maxTokens', 'stop']);
-            for (const key of Object.keys(extraOptions)) {
-              if (ALLOWED_KEYS.has(key)) {
-                safeOverrides[key] = extraOptions[key];
-              }
-            }
-          }
-          const mergedOptions = { ...agentOptions, ...safeOverrides };
-
-          // Prepend system messages then user conversation
-          const fullMessages: ModelMessage[] = [
-            ...systemMessages,
-            ...rawMessages.map(m => normalizeMessage(m as Record<string, unknown>)),
-          ];
-
-          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(
-            '[AI Route] /agents/:agentName/chat error',
-            err instanceof Error ? err : undefined,
-          );
-          return { status: 500, body: { error: 'Internal AI service error' } };
-        }
-      },
-    },
-  ];
-}