@objectstack/service-ai 4.0.0

package/dist/index.cjs

@@ -0,0 +1,1418 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AIService: () => AIService,
+  AIServicePlugin: () => AIServicePlugin,
+  AgentRuntime: () => AgentRuntime,
+  AiConversationObject: () => AiConversationObject,
+  AiMessageObject: () => AiMessageObject,
+  DATA_CHAT_AGENT: () => DATA_CHAT_AGENT,
+  DATA_TOOL_DEFINITIONS: () => DATA_TOOL_DEFINITIONS,
+  InMemoryConversationService: () => InMemoryConversationService,
+  MemoryLLMAdapter: () => MemoryLLMAdapter,
+  ObjectQLConversationService: () => ObjectQLConversationService,
+  ToolRegistry: () => ToolRegistry,
+  buildAIRoutes: () => buildAIRoutes,
+  buildAgentRoutes: () => buildAgentRoutes,
+  registerDataTools: () => registerDataTools
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ai-service.ts
+var import_core = require("@objectstack/core");
+
+// src/adapters/memory-adapter.ts
+var MemoryLLMAdapter = class {
+  constructor() {
+    this.name = "memory";
+  }
+  async chat(messages, options) {
+    const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
+    const content = lastUserMessage ? `[memory] ${lastUserMessage.content}` : "[memory] (no user message)";
+    return {
+      content,
+      model: options?.model ?? "memory",
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+    };
+  }
+  async complete(prompt, options) {
+    return {
+      content: `[memory] ${prompt}`,
+      model: options?.model ?? "memory",
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+    };
+  }
+  async *streamChat(messages, _options) {
+    const result = await this.chat(messages);
+    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 };
+    }
+    yield { type: "finish", result };
+  }
+  async embed(input) {
+    const texts = Array.isArray(input) ? input : [input];
+    return texts.map(() => [0, 0, 0]);
+  }
+  async listModels() {
+    return ["memory"];
+  }
+};
+
+// src/tools/tool-registry.ts
+var ToolRegistry = class {
+  constructor() {
+    this.definitions = /* @__PURE__ */ new Map();
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a tool with its definition and handler.
+   * @param definition - Tool definition (name, description, parameters schema)
+   * @param handler    - Async function that executes the tool
+   */
+  register(definition, handler) {
+    this.definitions.set(definition.name, definition);
+    this.handlers.set(definition.name, handler);
+  }
+  /**
+   * Unregister a tool by name.
+   */
+  unregister(name) {
+    this.definitions.delete(name);
+    this.handlers.delete(name);
+  }
+  /**
+   * Check whether a tool is registered.
+   */
+  has(name) {
+    return this.definitions.has(name);
+  }
+  /**
+   * Get the definition for a registered tool.
+   */
+  getDefinition(name) {
+    return this.definitions.get(name);
+  }
+  /**
+   * Return all registered tool definitions.
+   */
+  getAll() {
+    return Array.from(this.definitions.values());
+  }
+  /** Number of registered tools. */
+  get size() {
+    return this.definitions.size;
+  }
+  /** All registered tool names. */
+  names() {
+    return Array.from(this.definitions.keys());
+  }
+  /**
+   * Execute a tool call and return the result.
+   */
+  async execute(toolCall) {
+    const handler = this.handlers.get(toolCall.name);
+    if (!handler) {
+      return {
+        toolCallId: toolCall.id,
+        content: `Tool "${toolCall.name}" is not registered`,
+        isError: true
+      };
+    }
+    try {
+      const args = JSON.parse(toolCall.arguments);
+      const content = await handler(args);
+      return { toolCallId: toolCall.id, content };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { toolCallId: toolCall.id, content: message, isError: true };
+    }
+  }
+  /**
+   * Execute multiple tool calls in parallel.
+   */
+  async executeAll(toolCalls) {
+    return Promise.all(toolCalls.map((tc) => this.execute(tc)));
+  }
+  /**
+   * Clear all registered tools.
+   */
+  clear() {
+    this.definitions.clear();
+    this.handlers.clear();
+  }
+};
+
+// src/conversation/in-memory-conversation-service.ts
+var InMemoryConversationService = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+    this.counter = 0;
+  }
+  async create(options = {}) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const id = `conv_${++this.counter}`;
+    const conversation = {
+      id,
+      title: options.title,
+      agentId: options.agentId,
+      userId: options.userId,
+      messages: [],
+      createdAt: now,
+      updatedAt: now,
+      metadata: options.metadata
+    };
+    this.store.set(id, conversation);
+    return conversation;
+  }
+  async get(conversationId) {
+    return this.store.get(conversationId) ?? null;
+  }
+  async list(options = {}) {
+    let results = Array.from(this.store.values());
+    if (options.userId) {
+      results = results.filter((c) => c.userId === options.userId);
+    }
+    if (options.agentId) {
+      results = results.filter((c) => c.agentId === options.agentId);
+    }
+    if (options.cursor) {
+      const idx = results.findIndex((c) => c.id === options.cursor);
+      if (idx >= 0) {
+        results = results.slice(idx + 1);
+      }
+    }
+    if (options.limit && options.limit > 0) {
+      results = results.slice(0, options.limit);
+    }
+    return results;
+  }
+  async addMessage(conversationId, message) {
+    const conversation = this.store.get(conversationId);
+    if (!conversation) {
+      throw new Error(`Conversation "${conversationId}" not found`);
+    }
+    conversation.messages.push(message);
+    conversation.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return conversation;
+  }
+  async delete(conversationId) {
+    this.store.delete(conversationId);
+  }
+  /** Total number of stored conversations. */
+  get size() {
+    return this.store.size;
+  }
+  /** Clear all conversations. */
+  clear() {
+    this.store.clear();
+    this.counter = 0;
+  }
+};
+
+// src/ai-service.ts
+var _AIService = class _AIService {
+  constructor(config = {}) {
+    this.adapter = config.adapter ?? new MemoryLLMAdapter();
+    this.logger = config.logger ?? (0, import_core.createLogger)({ level: "info", format: "pretty" });
+    this.toolRegistry = config.toolRegistry ?? new ToolRegistry();
+    this.conversationService = config.conversationService ?? new InMemoryConversationService();
+    this.logger.info(
+      `[AI] Service initialized with adapter="${this.adapter.name}", tools=${this.toolRegistry.size}`
+    );
+  }
+  /** The name of the active LLM adapter. */
+  get adapterName() {
+    return this.adapter.name;
+  }
+  // ── IAIService implementation ──────────────────────────────────
+  async chat(messages, options) {
+    this.logger.debug("[AI] chat", { messageCount: messages.length, model: options?.model });
+    return this.adapter.chat(messages, options);
+  }
+  async complete(prompt, options) {
+    this.logger.debug("[AI] complete", { promptLength: prompt.length, model: options?.model });
+    return this.adapter.complete(prompt, options);
+  }
+  async *streamChat(messages, options) {
+    this.logger.debug("[AI] streamChat", { messageCount: messages.length, model: options?.model });
+    if (!this.adapter.streamChat) {
+      const result = await this.adapter.chat(messages, options);
+      yield { type: "text-delta", textDelta: result.content };
+      yield { type: "finish", result };
+      return;
+    }
+    yield* this.adapter.streamChat(messages, options);
+  }
+  async embed(input, model) {
+    if (!this.adapter.embed) {
+      throw new Error(`[AI] Adapter "${this.adapter.name}" does not support embeddings`);
+    }
+    return this.adapter.embed(input, model);
+  }
+  async listModels() {
+    if (!this.adapter.listModels) {
+      return [];
+    }
+    return this.adapter.listModels();
+  }
+  /**
+   * Chat with automatic tool call resolution.
+   *
+   * 1. Merges registered tool definitions into `options.tools`.
+   * 2. Calls the LLM adapter.
+   * 3. If the response contains `toolCalls`, executes them via the
+   *    {@link ToolRegistry}, appends tool results as `role: 'tool'`
+   *    messages, and loops back to step 2.
+   * 4. Repeats until the model produces a final text response or the
+   *    maximum number of iterations (`maxIterations`) is reached.
+   */
+  async chatWithTools(messages, options) {
+    const { maxIterations: maxIter, ...restOptions } = options ?? {};
+    const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
+    const registeredTools = this.toolRegistry.getAll();
+    const mergedTools = [
+      ...registeredTools,
+      ...restOptions.tools ?? []
+    ];
+    const chatOptions = {
+      ...restOptions,
+      tools: mergedTools.length > 0 ? mergedTools : void 0,
+      toolChoice: mergedTools.length > 0 ? restOptions.toolChoice ?? "auto" : void 0
+    };
+    const conversation = [...messages];
+    this.logger.debug("[AI] chatWithTools start", {
+      messageCount: conversation.length,
+      toolCount: mergedTools.length,
+      maxIterations
+    });
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      const result = await this.adapter.chat(conversation, chatOptions);
+      if (!result.toolCalls || result.toolCalls.length === 0) {
+        this.logger.debug("[AI] chatWithTools finished", { iteration, content: result.content.slice(0, 80) });
+        return result;
+      }
+      this.logger.debug("[AI] chatWithTools tool calls", {
+        iteration,
+        calls: result.toolCalls.map((tc) => tc.name)
+      });
+      conversation.push({
+        role: "assistant",
+        content: result.content ?? "",
+        toolCalls: result.toolCalls
+      });
+      const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
+      for (const tr of toolResults) {
+        conversation.push({
+          role: "tool",
+          content: tr.content,
+          toolCallId: tr.toolCallId
+        });
+      }
+    }
+    this.logger.warn("[AI] chatWithTools max iterations reached, forcing final response");
+    const finalResult = await this.adapter.chat(conversation, {
+      ...chatOptions,
+      tools: void 0,
+      toolChoice: void 0
+    });
+    return finalResult;
+  }
+};
+// ── Tool Call Loop ────────────────────────────────────────────
+/** Default maximum iterations for the tool call loop. */
+_AIService.DEFAULT_MAX_ITERATIONS = 10;
+var AIService = _AIService;
+
+// src/routes/ai-routes.ts
+var VALID_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+function validateMessage(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return "each message must be an object";
+  }
+  const msg = raw;
+  if (typeof msg.role !== "string" || !VALID_ROLES.has(msg.role)) {
+    return `message.role must be one of ${[...VALID_ROLES].map((r) => `"${r}"`).join(", ")}`;
+  }
+  if (typeof msg.content !== "string") {
+    return "message.content must be a string";
+  }
+  return null;
+}
+function buildAIRoutes(aiService, conversationService, logger) {
+  return [
+    // ── Chat ────────────────────────────────────────────────────
+    {
+      method: "POST",
+      path: "/api/v1/ai/chat",
+      description: "Synchronous chat completion",
+      handler: async (req) => {
+        const { messages, options } = req.body ?? {};
+        if (!Array.isArray(messages) || messages.length === 0) {
+          return { status: 400, body: { error: "messages array is required" } };
+        }
+        for (const msg of messages) {
+          const err = validateMessage(msg);
+          if (err) return { status: 400, body: { error: err } };
+        }
+        try {
+          const result = await aiService.chat(messages, options);
+          return { status: 200, body: result };
+        } catch (err) {
+          logger.error("[AI Route] /chat error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── Stream Chat (SSE) ──────────────────────────────────────
+    {
+      method: "POST",
+      path: "/api/v1/ai/chat/stream",
+      description: "SSE streaming chat completion",
+      handler: async (req) => {
+        const { messages, options } = req.body ?? {};
+        if (!Array.isArray(messages) || messages.length === 0) {
+          return { status: 400, body: { error: "messages array is required" } };
+        }
+        for (const msg of messages) {
+          const err = validateMessage(msg);
+          if (err) return { status: 400, body: { error: err } };
+        }
+        try {
+          if (!aiService.streamChat) {
+            return { status: 501, body: { error: "Streaming is not supported by the configured AI service" } };
+          }
+          const events = aiService.streamChat(messages, options);
+          return { status: 200, stream: true, events };
+        } catch (err) {
+          logger.error("[AI Route] /chat/stream error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── Complete ────────────────────────────────────────────────
+    {
+      method: "POST",
+      path: "/api/v1/ai/complete",
+      description: "Text completion",
+      handler: async (req) => {
+        const { prompt, options } = req.body ?? {};
+        if (!prompt || typeof prompt !== "string") {
+          return { status: 400, body: { error: "prompt string is required" } };
+        }
+        try {
+          const result = await aiService.complete(prompt, options);
+          return { status: 200, body: result };
+        } catch (err) {
+          logger.error("[AI Route] /complete error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── Models ──────────────────────────────────────────────────
+    {
+      method: "GET",
+      path: "/api/v1/ai/models",
+      description: "List available models",
+      handler: async () => {
+        try {
+          const models = aiService.listModels ? await aiService.listModels() : [];
+          return { status: 200, body: { models } };
+        } catch (err) {
+          logger.error("[AI Route] /models error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── Conversations ──────────────────────────────────────────
+    {
+      method: "POST",
+      path: "/api/v1/ai/conversations",
+      description: "Create a conversation",
+      handler: async (req) => {
+        try {
+          const options = req.body ?? {};
+          const conversation = await conversationService.create(options);
+          return { status: 201, body: conversation };
+        } catch (err) {
+          logger.error("[AI Route] POST /conversations error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    {
+      method: "GET",
+      path: "/api/v1/ai/conversations",
+      description: "List conversations",
+      handler: async (req) => {
+        try {
+          const rawQuery = req.query ?? {};
+          const options = { ...rawQuery };
+          if (typeof rawQuery.limit === "string") {
+            const parsedLimit = Number(rawQuery.limit);
+            if (!Number.isFinite(parsedLimit) || parsedLimit <= 0 || !Number.isInteger(parsedLimit)) {
+              return { status: 400, body: { error: "Invalid limit parameter" } };
+            }
+            options.limit = parsedLimit;
+          }
+          const conversations = await conversationService.list(options);
+          return { status: 200, body: { conversations } };
+        } catch (err) {
+          logger.error("[AI Route] GET /conversations error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    {
+      method: "POST",
+      path: "/api/v1/ai/conversations/:id/messages",
+      description: "Add message to a conversation",
+      handler: async (req) => {
+        const id = req.params?.id;
+        if (!id) {
+          return { status: 400, body: { error: "conversation id is required" } };
+        }
+        const message = req.body;
+        const validationError = validateMessage(message);
+        if (validationError) {
+          return { status: 400, body: { error: validationError } };
+        }
+        try {
+          const conversation = await conversationService.addMessage(id, message);
+          return { status: 200, body: conversation };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg.includes("not found")) {
+            return { status: 404, body: { error: msg } };
+          }
+          logger.error("[AI Route] POST /conversations/:id/messages error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    {
+      method: "DELETE",
+      path: "/api/v1/ai/conversations/:id",
+      description: "Delete a conversation",
+      handler: async (req) => {
+        const id = req.params?.id;
+        if (!id) {
+          return { status: 400, body: { error: "conversation id is required" } };
+        }
+        try {
+          await conversationService.delete(id);
+          return { status: 204 };
+        } catch (err) {
+          logger.error("[AI Route] DELETE /conversations/:id error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    }
+  ];
+}
+
+// src/routes/agent-routes.ts
+var ALLOWED_AGENT_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
+function validateAgentMessage(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return "each message must be an object";
+  }
+  const msg = raw;
+  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;
+}
+function buildAgentRoutes(aiService, agentRuntime, logger) {
+  return [
+    {
+      method: "POST",
+      path: "/api/v1/ai/agents/:agentName/chat",
+      description: "Chat with a specific AI agent",
+      handler: async (req) => {
+        const agentName = req.params?.agentName;
+        if (!agentName) {
+          return { status: 400, body: { error: "agentName parameter is required" } };
+        }
+        const {
+          messages: rawMessages,
+          context: chatContext,
+          options: extraOptions
+        } = req.body ?? {};
+        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 } };
+        }
+        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 {
+          const systemMessages = agentRuntime.buildSystemMessages(agent, chatContext);
+          const agentOptions = agentRuntime.buildRequestOptions(
+            agent,
+            aiService.toolRegistry.getAll()
+          );
+          const safeOverrides = {};
+          if (extraOptions) {
+            const ALLOWED_KEYS = /* @__PURE__ */ 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 };
+          const fullMessages = [
+            ...systemMessages,
+            ...rawMessages
+          ];
+          const result = await aiService.chatWithTools(fullMessages, {
+            ...mergedOptions,
+            maxIterations: agent.planning?.maxIterations
+          });
+          return { status: 200, body: result };
+        } catch (err) {
+          logger.error(
+            "[AI Route] /agents/:agentName/chat error",
+            err instanceof Error ? err : void 0
+          );
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    }
+  ];
+}
+
+// src/conversation/objectql-conversation-service.ts
+var import_node_crypto = require("crypto");
+var CONVERSATIONS_OBJECT = "ai_conversations";
+var MESSAGES_OBJECT = "ai_messages";
+var CONVERSATION_ORDER = [
+  { field: "created_at", order: "asc" },
+  { field: "id", order: "asc" }
+];
+var MESSAGE_ORDER = [
+  { field: "created_at", order: "asc" },
+  { field: "id", order: "asc" }
+];
+var ObjectQLConversationService = class {
+  constructor(engine) {
+    this.engine = engine;
+  }
+  async create(options = {}) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const id = `conv_${(0, import_node_crypto.randomUUID)()}`;
+    const record = {
+      id,
+      title: options.title ?? null,
+      agent_id: options.agentId ?? null,
+      user_id: options.userId ?? null,
+      metadata: options.metadata ? JSON.stringify(options.metadata) : null,
+      created_at: now,
+      updated_at: now
+    };
+    await this.engine.insert(CONVERSATIONS_OBJECT, record);
+    return {
+      id,
+      title: options.title,
+      agentId: options.agentId,
+      userId: options.userId,
+      messages: [],
+      createdAt: now,
+      updatedAt: now,
+      metadata: options.metadata
+    };
+  }
+  async get(conversationId) {
+    const row = await this.engine.findOne(CONVERSATIONS_OBJECT, {
+      where: { id: conversationId }
+    });
+    if (!row) return null;
+    const messages = await this.engine.find(MESSAGES_OBJECT, {
+      where: { conversation_id: conversationId },
+      orderBy: MESSAGE_ORDER
+    });
+    return this.toConversation(row, messages);
+  }
+  async list(options = {}) {
+    const where = {};
+    if (options.userId) where.user_id = options.userId;
+    if (options.agentId) where.agent_id = options.agentId;
+    if (options.cursor) {
+      const cursorRow = await this.engine.findOne(CONVERSATIONS_OBJECT, {
+        where: { id: options.cursor },
+        fields: ["created_at", "id"]
+      });
+      if (cursorRow) {
+        where.$or = [
+          { created_at: { $gt: cursorRow.created_at } },
+          { created_at: cursorRow.created_at, id: { $gt: cursorRow.id } }
+        ];
+      }
+    }
+    const rows = await this.engine.find(CONVERSATIONS_OBJECT, {
+      where: Object.keys(where).length > 0 ? where : void 0,
+      orderBy: CONVERSATION_ORDER,
+      limit: options.limit && options.limit > 0 ? options.limit : void 0
+    });
+    const conversations = await Promise.all(
+      rows.map(async (row) => {
+        const messages = await this.engine.find(MESSAGES_OBJECT, {
+          where: { conversation_id: row.id },
+          orderBy: MESSAGE_ORDER
+        });
+        return this.toConversation(row, messages);
+      })
+    );
+    return conversations;
+  }
+  async addMessage(conversationId, message) {
+    const row = await this.engine.findOne(CONVERSATIONS_OBJECT, {
+      where: { id: conversationId }
+    });
+    if (!row) {
+      throw new Error(`Conversation "${conversationId}" not found`);
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const msgId = `msg_${(0, import_node_crypto.randomUUID)()}`;
+    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,
+      created_at: now
+    });
+    await this.engine.update(CONVERSATIONS_OBJECT, { id: conversationId, updated_at: now }, {
+      where: { id: conversationId }
+    });
+    return await this.get(conversationId);
+  }
+  async delete(conversationId) {
+    await this.engine.delete(MESSAGES_OBJECT, {
+      where: { conversation_id: conversationId },
+      multi: true
+    });
+    await this.engine.delete(CONVERSATIONS_OBJECT, {
+      where: { id: conversationId }
+    });
+  }
+  // ── Private helpers ──────────────────────────────────────────────
+  /**
+   * Safely parse a JSON string, returning `undefined` on failure.
+   */
+  safeParse(value, fallback) {
+    if (!value) return void 0;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return fallback;
+    }
+  }
+  /**
+   * Map a database row + message rows to an AIConversation.
+   */
+  toConversation(row, messageRows) {
+    return {
+      id: row.id,
+      title: row.title ?? void 0,
+      agentId: row.agent_id ?? void 0,
+      userId: row.user_id ?? void 0,
+      messages: messageRows.map((m) => this.toMessage(m)),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      metadata: this.safeParse(row.metadata)
+    };
+  }
+  /**
+   * Map a database row to an AIMessage.
+   */
+  toMessage(row) {
+    const msg = {
+      role: row.role,
+      content: row.content
+    };
+    const toolCalls = this.safeParse(row.tool_calls);
+    if (toolCalls) {
+      msg.toolCalls = toolCalls;
+    }
+    if (row.tool_call_id) {
+      msg.toolCallId = row.tool_call_id;
+    }
+    return msg;
+  }
+};
+
+// src/objects/ai-conversation.object.ts
+var import_data = require("@objectstack/spec/data");
+var AiConversationObject = import_data.ObjectSchema.create({
+  namespace: "ai",
+  name: "conversations",
+  label: "AI Conversation",
+  pluralLabel: "AI Conversations",
+  icon: "message-square",
+  isSystem: true,
+  description: "Persistent AI conversation metadata",
+  fields: {
+    id: import_data.Field.text({
+      label: "Conversation ID",
+      required: true,
+      readonly: true
+    }),
+    title: import_data.Field.text({
+      label: "Title",
+      required: false,
+      maxLength: 500,
+      description: "Conversation title or summary"
+    }),
+    agent_id: import_data.Field.text({
+      label: "Agent ID",
+      required: false,
+      maxLength: 255,
+      description: "Associated AI agent identifier"
+    }),
+    user_id: import_data.Field.text({
+      label: "User ID",
+      required: false,
+      maxLength: 255,
+      description: "User who owns the conversation"
+    }),
+    metadata: import_data.Field.textarea({
+      label: "Metadata",
+      required: false,
+      description: "JSON-serialized conversation metadata"
+    }),
+    created_at: import_data.Field.datetime({
+      label: "Created At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true
+    }),
+    updated_at: import_data.Field.datetime({
+      label: "Updated At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true
+    })
+  },
+  indexes: [
+    { fields: ["user_id"] },
+    { fields: ["agent_id"] },
+    { fields: ["created_at"] }
+  ],
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list", "create", "update", "delete"],
+    trash: false,
+    mru: false
+  }
+});
+
+// src/objects/ai-message.object.ts
+var import_data2 = require("@objectstack/spec/data");
+var AiMessageObject = import_data2.ObjectSchema.create({
+  namespace: "ai",
+  name: "messages",
+  label: "AI Message",
+  pluralLabel: "AI Messages",
+  icon: "message-circle",
+  isSystem: true,
+  description: "Individual messages within AI conversations",
+  fields: {
+    id: import_data2.Field.text({
+      label: "Message ID",
+      required: true,
+      readonly: true
+    }),
+    conversation_id: import_data2.Field.text({
+      label: "Conversation ID",
+      required: true,
+      description: "Foreign key to ai_conversations"
+    }),
+    role: import_data2.Field.select({
+      label: "Role",
+      required: true,
+      options: [
+        { label: "System", value: "system" },
+        { label: "User", value: "user" },
+        { label: "Assistant", value: "assistant" },
+        { label: "Tool", value: "tool" }
+      ]
+    }),
+    content: import_data2.Field.textarea({
+      label: "Content",
+      required: true,
+      description: "Message content"
+    }),
+    tool_calls: import_data2.Field.textarea({
+      label: "Tool Calls",
+      required: false,
+      description: "JSON-serialized tool calls (when role=assistant)"
+    }),
+    tool_call_id: import_data2.Field.text({
+      label: "Tool Call ID",
+      required: false,
+      maxLength: 255,
+      description: "ID of the tool call this message responds to (when role=tool)"
+    }),
+    created_at: import_data2.Field.datetime({
+      label: "Created At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true
+    })
+  },
+  indexes: [
+    { fields: ["conversation_id"] },
+    { fields: ["conversation_id", "created_at"] }
+  ],
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list", "create"],
+    trash: false,
+    mru: false
+  }
+});
+
+// src/tools/data-tools.ts
+var MAX_QUERY_LIMIT = 200;
+var DEFAULT_QUERY_LIMIT = 20;
+var LIST_OBJECTS_TOOL = {
+  name: "list_objects",
+  description: "List all available data objects (tables) in the system. Returns object names and labels.",
+  parameters: {
+    type: "object",
+    properties: {},
+    additionalProperties: false
+  }
+};
+var DESCRIBE_OBJECT_TOOL = {
+  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
+  }
+};
+var QUERY_RECORDS_TOOL = {
+  name: "query_records",
+  description: "Query records from a data object with optional filters, field selection, sorting, and pagination. Returns an array of matching records.",
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "The snake_case name of the object to query"
+      },
+      where: {
+        type: "object",
+        description: 'Filter conditions as key-value pairs (e.g. { "status": "active" }) or MongoDB-style operators (e.g. { "amount": { "$gt": 100 } })'
+      },
+      fields: {
+        type: "array",
+        items: { type: "string" },
+        description: "List of field names to return (omit for all fields)"
+      },
+      orderBy: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            field: { type: "string" },
+            order: { type: "string", enum: ["asc", "desc"] }
+          }
+        },
+        description: 'Sort order (e.g. [{ "field": "created_at", "order": "desc" }])'
+      },
+      limit: {
+        type: "number",
+        description: `Maximum number of records to return (default ${DEFAULT_QUERY_LIMIT}, max ${MAX_QUERY_LIMIT})`
+      },
+      offset: {
+        type: "number",
+        description: "Number of records to skip for pagination"
+      }
+    },
+    required: ["objectName"],
+    additionalProperties: false
+  }
+};
+var GET_RECORD_TOOL = {
+  name: "get_record",
+  description: "Get a single record by its ID from a data object.",
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "The snake_case name of the object"
+      },
+      recordId: {
+        type: "string",
+        description: "The unique ID of the record"
+      },
+      fields: {
+        type: "array",
+        items: { type: "string" },
+        description: "List of field names to return (omit for all fields)"
+      }
+    },
+    required: ["objectName", "recordId"],
+    additionalProperties: false
+  }
+};
+var AGGREGATE_DATA_TOOL = {
+  name: "aggregate_data",
+  description: "Perform aggregation/statistical operations on a data object. Supports count, sum, avg, min, max with optional groupBy and where filters.",
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "The snake_case name of the object to aggregate"
+      },
+      aggregations: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            function: {
+              type: "string",
+              enum: ["count", "sum", "avg", "min", "max", "count_distinct"],
+              description: "Aggregation function"
+            },
+            field: {
+              type: "string",
+              description: "Field to aggregate (optional for count)"
+            },
+            alias: {
+              type: "string",
+              description: "Result column alias"
+            }
+          },
+          required: ["function", "alias"]
+        },
+        description: "Aggregation definitions"
+      },
+      groupBy: {
+        type: "array",
+        items: { type: "string" },
+        description: "Fields to group by"
+      },
+      where: {
+        type: "object",
+        description: "Filter conditions applied before aggregation"
+      }
+    },
+    required: ["objectName", "aggregations"],
+    additionalProperties: false
+  }
+};
+var DATA_TOOL_DEFINITIONS = [
+  LIST_OBJECTS_TOOL,
+  DESCRIBE_OBJECT_TOOL,
+  QUERY_RECORDS_TOOL,
+  GET_RECORD_TOOL,
+  AGGREGATE_DATA_TOOL
+];
+function createListObjectsHandler(ctx) {
+  return async () => {
+    const objects = await ctx.metadataService.listObjects();
+    const summary = objects.map((o) => ({
+      name: o.name,
+      label: o.label ?? o.name
+    }));
+    return JSON.stringify(summary);
+  };
+}
+function createDescribeObjectHandler(ctx) {
+  return async (args) => {
+    const { objectName } = args;
+    const objectDef = await ctx.metadataService.getObject(objectName);
+    if (!objectDef) {
+      return JSON.stringify({ error: `Object "${objectName}" not found` });
+    }
+    const def = objectDef;
+    const fields = def.fields ?? {};
+    const fieldSummary = {};
+    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) {
+  return async (args) => {
+    const {
+      objectName,
+      where,
+      fields,
+      orderBy,
+      limit,
+      offset
+    } = args;
+    const rawLimit = limit ?? DEFAULT_QUERY_LIMIT;
+    const safeLimit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(Math.floor(rawLimit), MAX_QUERY_LIMIT) : DEFAULT_QUERY_LIMIT;
+    const safeOffset = Number.isFinite(offset) && offset >= 0 ? Math.floor(offset) : void 0;
+    const records = await ctx.dataEngine.find(objectName, {
+      where,
+      fields,
+      orderBy,
+      limit: safeLimit,
+      offset: safeOffset
+    });
+    return JSON.stringify({ count: records.length, records });
+  };
+}
+function createGetRecordHandler(ctx) {
+  return async (args) => {
+    const { objectName, recordId, fields } = args;
+    const record = await ctx.dataEngine.findOne(objectName, {
+      where: { id: recordId },
+      fields
+    });
+    if (!record) {
+      return JSON.stringify({ error: `Record "${recordId}" not found in "${objectName}"` });
+    }
+    return JSON.stringify(record);
+  };
+}
+var VALID_AGG_FUNCTIONS = /* @__PURE__ */ new Set([
+  "count",
+  "sum",
+  "avg",
+  "min",
+  "max",
+  "count_distinct"
+]);
+function createAggregateDataHandler(ctx) {
+  return async (args) => {
+    const { objectName, aggregations, groupBy, where } = args;
+    for (const a of aggregations) {
+      if (!VALID_AGG_FUNCTIONS.has(a.function)) {
+        return JSON.stringify({
+          error: `Invalid aggregation function "${a.function}". Allowed: ${[...VALID_AGG_FUNCTIONS].join(", ")}`
+        });
+      }
+    }
+    const result = await ctx.dataEngine.aggregate(objectName, {
+      where,
+      groupBy,
+      aggregations: aggregations.map((a) => ({
+        function: a.function,
+        field: a.field,
+        alias: a.alias
+      }))
+    });
+    return JSON.stringify(result);
+  };
+}
+function registerDataTools(registry, context) {
+  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));
+}
+
+// src/agent-runtime.ts
+var import_ai = require("@objectstack/spec/ai");
+var AgentRuntime = class {
+  constructor(metadataService) {
+    this.metadataService = metadataService;
+  }
+  // ── Public API ────────────────────────────────────────────────
+  /**
+   * Load and validate an agent definition by name.
+   *
+   * The raw metadata is validated through {@link AgentSchema} to ensure
+   * required fields (`instructions`, `name`, `role`, etc.) are present
+   * and well-typed.  Returns `undefined` when the agent does not exist
+   * or validation fails.
+   */
+  async loadAgent(agentName) {
+    const raw = await this.metadataService.get("agent", agentName);
+    if (!raw) return void 0;
+    const result = import_ai.AgentSchema.safeParse(raw);
+    if (!result.success) {
+      return void 0;
+    }
+    return result.data;
+  }
+  /**
+   * Build the system message(s) that should be prepended to the
+   * conversation when chatting with the given agent.
+   */
+  buildSystemMessages(agent, context) {
+    const parts = [];
+    parts.push(agent.instructions);
+    if (context) {
+      const ctx = [];
+      if (context.objectName) ctx.push(`Current object: ${context.objectName}`);
+      if (context.recordId) ctx.push(`Selected record ID: ${context.recordId}`);
+      if (context.viewName) ctx.push(`Current view: ${context.viewName}`);
+      if (ctx.length > 0) {
+        parts.push("\n--- Current Context ---\n" + ctx.join("\n"));
+      }
+    }
+    return [{ role: "system", content: parts.join("\n") }];
+  }
+  /**
+   * Derive {@link AIRequestOptions} from an agent definition.
+   *
+   * Tool references declared in `agent.tools` are resolved by name against
+   * `availableTools` (i.e. the full set of ToolRegistry definitions).
+   * Any unresolved references (tools the agent declares but that are not
+   * registered) are silently skipped — this is intentional so that agents
+   * can be defined before all tools are available.
+   *
+   * @param agent          - The agent definition to derive options from
+   * @param availableTools - All tool definitions currently registered in the ToolRegistry
+   * @returns Request options with model config and resolved tool definitions
+   */
+  buildRequestOptions(agent, availableTools) {
+    const options = {};
+    if (agent.model) {
+      options.model = agent.model.model;
+      options.temperature = agent.model.temperature;
+      options.maxTokens = agent.model.maxTokens;
+    }
+    if (agent.tools && agent.tools.length > 0) {
+      const toolMap = new Map(availableTools.map((t) => [t.name, t]));
+      const resolved = [];
+      for (const ref of agent.tools) {
+        const def = toolMap.get(ref.name);
+        if (def) {
+          resolved.push(def);
+        }
+      }
+      if (resolved.length > 0) {
+        options.tools = resolved;
+        options.toolChoice = "auto";
+      }
+    }
+    return options;
+  }
+};
+
+// src/agents/data-chat-agent.ts
+var DATA_CHAT_AGENT = {
+  name: "data_chat",
+  label: "Data Assistant",
+  role: "Business Data Analyst",
+  instructions: `You are a helpful data assistant that helps users explore and understand their business data through natural language.
+
+Capabilities:
+- List available data objects (tables) and their schemas
+- Query records with filters, sorting, and pagination
+- Look up individual records by ID
+- Perform aggregations and statistical analysis (count, sum, avg, min, max)
+
+Guidelines:
+1. Always use the describe_object tool first to understand a table's structure before querying it.
+2. Respect the user's current context \u2014 if they are viewing a specific object or record, use that as the default scope.
+3. When presenting data, format it in a clear and readable way using markdown tables or bullet lists.
+4. For large result sets, summarize the data and mention the total count.
+5. When performing aggregations, explain the results in plain language.
+6. If a query returns no results, suggest possible reasons and alternative queries.
+7. Never expose internal IDs unless the user explicitly asks for them.
+8. Always answer in the same language the user is using.`,
+  model: {
+    provider: "openai",
+    model: "gpt-4",
+    temperature: 0.3,
+    maxTokens: 4096
+  },
+  tools: [
+    { type: "query", name: "list_objects", description: "List all available data objects" },
+    { type: "query", name: "describe_object", description: "Get schema/fields of a data object" },
+    { type: "query", name: "query_records", description: "Query records with filters and pagination" },
+    { type: "query", name: "get_record", description: "Get a single record by ID" },
+    { type: "query", name: "aggregate_data", description: "Aggregate/statistics on data" }
+  ],
+  active: true,
+  visibility: "global",
+  guardrails: {
+    maxTokensPerInvocation: 8192,
+    maxExecutionTimeSec: 30,
+    blockedTopics: ["delete_records", "drop_table", "alter_schema"]
+  },
+  planning: {
+    strategy: "react",
+    maxIterations: 5,
+    allowReplan: false
+  },
+  memory: {
+    shortTerm: {
+      maxMessages: 20,
+      maxTokens: 4096
+    }
+  }
+};
+
+// src/plugin.ts
+var AIServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service-ai";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = [];
+    this.options = options;
+  }
+  async init(ctx) {
+    let hasExisting = false;
+    try {
+      const existing = ctx.getService("ai");
+      if (existing && typeof existing.chat === "function") {
+        hasExisting = true;
+        ctx.logger.debug("[AI] Found existing AI service, replacing");
+      }
+    } catch {
+    }
+    let conversationService = this.options.conversationService;
+    if (!conversationService) {
+      try {
+        const engine = ctx.getService("data");
+        if (engine && typeof engine.find === "function") {
+          conversationService = new ObjectQLConversationService(engine);
+          ctx.logger.info("[AI] Using ObjectQLConversationService (IDataEngine detected)");
+        }
+      } catch {
+      }
+    }
+    const config = {
+      adapter: this.options.adapter,
+      logger: ctx.logger,
+      conversationService
+    };
+    this.service = new AIService(config);
+    if (hasExisting) {
+      ctx.replaceService("ai", this.service);
+    } else {
+      ctx.registerService("ai", this.service);
+    }
+    ctx.registerService("app.com.objectstack.service-ai", {
+      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) => {
+        ctx.logger.debug("[AI] Before chat", { messages });
+      });
+    }
+    ctx.logger.info("[AI] Service initialized");
+  }
+  async start(ctx) {
+    if (!this.service) return;
+    try {
+      const dataEngine = ctx.getService("data");
+      const metadataService = ctx.getService("metadata");
+      if (dataEngine && metadataService) {
+        registerDataTools(this.service.toolRegistry, { dataEngine, metadataService });
+        ctx.logger.info("[AI] Built-in data tools registered");
+        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");
+        }
+      }
+    } catch {
+      ctx.logger.debug("[AI] Data engine or metadata service not available, skipping data tools");
+    }
+    await ctx.trigger("ai:ready", this.service);
+    const routes = buildAIRoutes(this.service, this.service.conversationService, ctx.logger);
+    try {
+      const metadataService = ctx.getService("metadata");
+      if (metadataService) {
+        const agentRuntime = new AgentRuntime(metadataService);
+        const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
+        routes.push(...agentRoutes);
+      }
+    } catch {
+      ctx.logger.debug("[AI] Metadata service not available, skipping agent routes");
+    }
+    await ctx.trigger("ai:routes", routes);
+    ctx.logger.info(
+      `[AI] Service started \u2014 adapter="${this.service.adapterName}", tools=${this.service.toolRegistry.size}, routes=${routes.length}`
+    );
+  }
+  async destroy() {
+    this.service = void 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AIService,
+  AIServicePlugin,
+  AgentRuntime,
+  AiConversationObject,
+  AiMessageObject,
+  DATA_CHAT_AGENT,
+  DATA_TOOL_DEFINITIONS,
+  InMemoryConversationService,
+  MemoryLLMAdapter,
+  ObjectQLConversationService,
+  ToolRegistry,
+  buildAIRoutes,
+  buildAgentRoutes,
+  registerDataTools
+});
+//# sourceMappingURL=index.cjs.map