@objectstack/service-ai 4.0.0 → 4.0.2

package/dist/index.cjs

@@ -28,12 +28,24 @@ __export(index_exports, {
   DATA_CHAT_AGENT: () => DATA_CHAT_AGENT,
   DATA_TOOL_DEFINITIONS: () => DATA_TOOL_DEFINITIONS,
   InMemoryConversationService: () => InMemoryConversationService,
+  METADATA_ASSISTANT_AGENT: () => METADATA_ASSISTANT_AGENT,
+  METADATA_TOOL_DEFINITIONS: () => METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter: () => MemoryLLMAdapter,
   ObjectQLConversationService: () => ObjectQLConversationService,
   ToolRegistry: () => ToolRegistry,
+  VercelLLMAdapter: () => VercelLLMAdapter,
+  addFieldTool: () => addFieldTool,
   buildAIRoutes: () => buildAIRoutes,
   buildAgentRoutes: () => buildAgentRoutes,
-  registerDataTools: () => registerDataTools
+  createObjectTool: () => createObjectTool,
+  deleteFieldTool: () => deleteFieldTool,
+  describeMetadataObjectTool: () => describeMetadataObjectTool,
+  encodeStreamPart: () => encodeStreamPart,
+  encodeVercelDataStream: () => encodeVercelDataStream,
+  listMetadataObjectsTool: () => listMetadataObjectsTool,
+  modifyFieldTool: () => modifyFieldTool,
+  registerDataTools: () => registerDataTools,
+  registerMetadataTools: () => registerMetadataTools
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -47,7 +59,9 @@ var MemoryLLMAdapter = class {
   }
   async chat(messages, options) {
     const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
-    const content = lastUserMessage ? `[memory] ${lastUserMessage.content}` : "[memory] (no user message)";
+    const userContent = lastUserMessage?.content;
+    const text = typeof userContent === "string" ? userContent : "(complex content)";
+    const content = lastUserMessage ? `[memory] ${text}` : "[memory] (no user message)";
     return {
       content,
       model: options?.model ?? "memory",
@@ -65,10 +79,15 @@ var MemoryLLMAdapter = class {
     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 };
+      const wordText = i === 0 ? words[i] : ` ${words[i]}`;
+      yield { type: "text-delta", id: `delta_${i}`, text: wordText };
     }
-    yield { type: "finish", result };
+    yield {
+      type: "finish",
+      finishReason: "stop",
+      totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      rawFinishReason: "stop"
+    };
   }
   async embed(input) {
     const texts = Array.isArray(input) ? input : [input];
@@ -131,21 +150,34 @@ var ToolRegistry = class {
    * Execute a tool call and return the result.
    */
   async execute(toolCall) {
-    const handler = this.handlers.get(toolCall.name);
+    const handler = this.handlers.get(toolCall.toolName);
     if (!handler) {
       return {
-        toolCallId: toolCall.id,
-        content: `Tool "${toolCall.name}" is not registered`,
+        type: "tool-result",
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: { type: "text", value: `Tool "${toolCall.toolName}" is not registered` },
         isError: true
       };
     }
     try {
-      const args = JSON.parse(toolCall.arguments);
+      const args = typeof toolCall.input === "string" ? JSON.parse(toolCall.input) : toolCall.input ?? {};
       const content = await handler(args);
-      return { toolCallId: toolCall.id, content };
+      return {
+        type: "tool-result",
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: { type: "text", value: content }
+      };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      return { toolCallId: toolCall.id, content: message, isError: true };
+      return {
+        type: "tool-result",
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: { type: "text", value: message },
+        isError: true
+      };
     }
   }
   /**
@@ -231,6 +263,17 @@ var InMemoryConversationService = class {
 };
 
 // src/ai-service.ts
+function textDeltaPart(id, text) {
+  return { type: "text-delta", id, text };
+}
+function finishPart(result) {
+  return {
+    type: "finish",
+    finishReason: "stop",
+    totalUsage: result?.usage ?? { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    rawFinishReason: "stop"
+  };
+}
 var _AIService = class _AIService {
   constructor(config = {}) {
     this.adapter = config.adapter ?? new MemoryLLMAdapter();
@@ -258,8 +301,8 @@ var _AIService = class _AIService {
     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 };
+      yield textDeltaPart("fallback", result.content);
+      yield finishPart(result);
       return;
     }
     yield* this.adapter.streamChat(messages, options);
@@ -276,6 +319,10 @@ var _AIService = class _AIService {
     }
     return this.adapter.listModels();
   }
+  /** Extract the text value from a ToolExecutionResult's output. */
+  static extractOutputText(tr) {
+    return tr.output && typeof tr.output === "object" && "value" in tr.output ? String(tr.output.value) : "unknown error";
+  }
   /**
    * Chat with automatic tool call resolution.
    *
@@ -288,7 +335,7 @@ var _AIService = class _AIService {
    *    maximum number of iterations (`maxIterations`) is reached.
    */
   async chatWithTools(messages, options) {
-    const { maxIterations: maxIter, ...restOptions } = options ?? {};
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
     const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
     const mergedTools = [
@@ -301,11 +348,13 @@ var _AIService = class _AIService {
       toolChoice: mergedTools.length > 0 ? restOptions.toolChoice ?? "auto" : void 0
     };
     const conversation = [...messages];
+    const toolErrors = [];
     this.logger.debug("[AI] chatWithTools start", {
       messageCount: conversation.length,
       toolCount: mergedTools.length,
       maxIterations
     });
+    let abortedByCallback = false;
     for (let iteration = 0; iteration < maxIterations; iteration++) {
       const result = await this.adapter.chat(conversation, chatOptions);
       if (!result.toolCalls || result.toolCalls.length === 0) {
@@ -314,23 +363,47 @@ var _AIService = class _AIService {
       }
       this.logger.debug("[AI] chatWithTools tool calls", {
         iteration,
-        calls: result.toolCalls.map((tc) => tc.name)
+        calls: result.toolCalls.map((tc) => tc.toolName)
       });
+      const assistantContent = [];
+      if (result.content) assistantContent.push({ type: "text", text: result.content });
+      assistantContent.push(...result.toolCalls);
       conversation.push({
         role: "assistant",
-        content: result.content ?? "",
-        toolCalls: result.toolCalls
+        content: assistantContent
       });
       const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
       for (const tr of toolResults) {
+        if (tr.isError) {
+          const matchedCall = result.toolCalls.find((tc) => tc.toolCallId === tr.toolCallId);
+          const toolName = matchedCall?.toolName ?? "unknown";
+          const errorText = _AIService.extractOutputText(tr);
+          const errorEntry = { iteration, toolName, error: errorText };
+          toolErrors.push(errorEntry);
+          this.logger.warn("[AI] chatWithTools tool error", errorEntry);
+          if (onToolError && matchedCall) {
+            const action = onToolError(matchedCall, errorText);
+            if (action === "abort") {
+              abortedByCallback = true;
+            }
+          }
+        }
         conversation.push({
           role: "tool",
-          content: tr.content,
-          toolCallId: tr.toolCallId
+          content: [tr]
         });
       }
+      if (abortedByCallback) {
+        break;
+      }
+    }
+    if (abortedByCallback) {
+      this.logger.warn("[AI] chatWithTools aborted by onToolError callback", { toolErrors });
+    } else {
+      this.logger.warn("[AI] chatWithTools max iterations reached, forcing final response", {
+        toolErrors: toolErrors.length > 0 ? toolErrors : void 0
+      });
     }
-    this.logger.warn("[AI] chatWithTools max iterations reached, forcing final response");
     const finalResult = await this.adapter.chat(conversation, {
       ...chatOptions,
       tools: void 0,
@@ -338,14 +411,175 @@ var _AIService = class _AIService {
     });
     return finalResult;
   }
+  /**
+   * Stream chat with automatic tool call resolution.
+   *
+   * Works like {@link chatWithTools} but yields SSE events.  When the model
+   * requests tool calls during streaming, they are executed and the results
+   * fed back until a final text stream is produced.
+   */
+  async *streamChatWithTools(messages, options) {
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
+    const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
+    const registeredTools = this.toolRegistry.getAll();
+    const mergedTools = [
+      ...registeredTools,
+      ...restOptions.tools ?? []
+    ];
+    const chatOptions = {
+      ...restOptions,
+      tools: mergedTools.length > 0 ? mergedTools : void 0,
+      toolChoice: mergedTools.length > 0 ? restOptions.toolChoice ?? "auto" : void 0
+    };
+    const conversation = [...messages];
+    let abortedByCallback = false;
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      const result2 = await this.adapter.chat(conversation, chatOptions);
+      if (!result2.toolCalls || result2.toolCalls.length === 0) {
+        yield textDeltaPart("stream", result2.content);
+        yield finishPart(result2);
+        return;
+      }
+      for (const tc of result2.toolCalls) {
+        yield { type: "tool-call", toolCallId: tc.toolCallId, toolName: tc.toolName, input: tc.input };
+      }
+      const assistantContent = [];
+      if (result2.content) assistantContent.push({ type: "text", text: result2.content });
+      assistantContent.push(...result2.toolCalls);
+      conversation.push({
+        role: "assistant",
+        content: assistantContent
+      });
+      const toolResults = await this.toolRegistry.executeAll(result2.toolCalls);
+      for (const tr of toolResults) {
+        if (tr.isError && onToolError) {
+          const matchedCall = result2.toolCalls.find((tc) => tc.toolCallId === tr.toolCallId);
+          if (matchedCall) {
+            const errorText = _AIService.extractOutputText(tr);
+            const action = onToolError(matchedCall, errorText);
+            if (action === "abort") {
+              abortedByCallback = true;
+            }
+          }
+        }
+        conversation.push({
+          role: "tool",
+          content: [tr]
+        });
+      }
+      if (abortedByCallback) {
+        break;
+      }
+    }
+    if (abortedByCallback) {
+      this.logger.warn("[AI] streamChatWithTools aborted by onToolError callback");
+    } else {
+      this.logger.warn("[AI] streamChatWithTools max iterations reached");
+    }
+    const finalOptions = { ...chatOptions, tools: void 0, toolChoice: void 0 };
+    const result = await this.adapter.chat(conversation, finalOptions);
+    yield textDeltaPart("stream", result.content);
+    yield finishPart(result);
+  }
 };
 // ── Tool Call Loop ────────────────────────────────────────────
 /** Default maximum iterations for the tool call loop. */
 _AIService.DEFAULT_MAX_ITERATIONS = 10;
 var AIService = _AIService;
 
+// src/stream/vercel-stream-encoder.ts
+function sse(data) {
+  return `data: ${JSON.stringify(data)}
+
+`;
+}
+function encodeStreamPart(part) {
+  switch (part.type) {
+    case "text-delta":
+      return sse({ type: "text-delta", id: "0", delta: part.text });
+    case "tool-input-start":
+      return sse({
+        type: "tool-input-start",
+        toolCallId: part.id,
+        toolName: part.toolName
+      });
+    case "tool-input-delta":
+      return sse({
+        type: "tool-input-delta",
+        toolCallId: part.id,
+        inputTextDelta: part.delta
+      });
+    case "tool-call":
+      return sse({
+        type: "tool-input-available",
+        toolCallId: part.toolCallId,
+        toolName: part.toolName,
+        input: part.input
+      });
+    case "tool-result":
+      return sse({
+        type: "tool-output-available",
+        toolCallId: part.toolCallId,
+        output: part.output
+      });
+    case "error":
+      return sse({
+        type: "error",
+        errorText: String(part.error)
+      });
+    // finish-step and finish are handled by the generator, not here
+    default:
+      return "";
+  }
+}
+async function* encodeVercelDataStream(events) {
+  yield sse({ type: "start" });
+  yield sse({ type: "start-step" });
+  yield sse({ type: "text-start", id: "0" });
+  let textOpen = true;
+  let finishReason = "stop";
+  for await (const part of events) {
+    if (part.type === "finish") {
+      finishReason = part.finishReason ?? "stop";
+    }
+    if (part.type === "finish-step" || part.type === "finish") {
+      if (textOpen) {
+        yield sse({ type: "text-end", id: "0" });
+        textOpen = false;
+      }
+      continue;
+    }
+    const frame = encodeStreamPart(part);
+    if (frame) {
+      yield frame;
+    }
+  }
+  if (textOpen) {
+    yield sse({ type: "text-end", id: "0" });
+  }
+  yield sse({ type: "finish-step" });
+  yield sse({ type: "finish", finishReason });
+  yield "data: [DONE]\n\n";
+}
+
 // src/routes/ai-routes.ts
 var VALID_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+function normalizeMessage(raw) {
+  const role = raw.role;
+  if (typeof raw.content === "string") {
+    return { role, content: raw.content };
+  }
+  if (Array.isArray(raw.content)) {
+    return { role, content: raw.content };
+  }
+  if (Array.isArray(raw.parts)) {
+    const textParts = raw.parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text);
+    if (textParts.length > 0) {
+      return { role, content: textParts.join("") };
+    }
+  }
+  return { role, content: "" };
+}
 function validateMessage(raw) {
   if (typeof raw !== "object" || raw === null) {
     return "each message must be an object";
@@ -354,20 +588,56 @@ function validateMessage(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";
+  const content = msg.content;
+  if (Array.isArray(msg.parts)) {
+    return null;
   }
-  return null;
+  if (typeof content === "string") {
+    return null;
+  }
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      if (typeof part !== "object" || part === null) {
+        return "message.content array elements must be non-null objects";
+      }
+      const partObj = part;
+      if (typeof partObj.type !== "string") {
+        return 'each message.content array element must have a string "type" property';
+      }
+      if (partObj.type === "text" && typeof partObj.text !== "string") {
+        return 'message.content elements with type "text" must have a string "text" property';
+      }
+    }
+    return null;
+  }
+  if (content === null || content === void 0) {
+    if (msg.role === "assistant" || msg.role === "tool") {
+      return null;
+    }
+  }
+  return "message.content must be a string, an array, or include parts";
 }
 function buildAIRoutes(aiService, conversationService, logger) {
   return [
     // ── Chat ────────────────────────────────────────────────────
+    //
+    // Dual-mode endpoint compatible with both the legacy ObjectStack
+    // format (`{ messages, options }`) and the Vercel AI SDK useChat
+    // flat format (`{ messages, system, model, stream, … }`).
+    //
+    // Behaviour:
+    //   • `stream !== false` → Vercel Data Stream Protocol (SSE)
+    //   • `stream === false`  → JSON response (legacy)
+    //
     {
       method: "POST",
       path: "/api/v1/ai/chat",
-      description: "Synchronous chat completion",
+      description: "Chat completion (supports Vercel AI Data Stream Protocol)",
+      auth: true,
+      permissions: ["ai:chat"],
       handler: async (req) => {
-        const { messages, options } = req.body ?? {};
+        const body = req.body ?? {};
+        const messages = body.messages;
         if (!Array.isArray(messages) || messages.length === 0) {
           return { status: 400, body: { error: "messages array is required" } };
         }
@@ -375,8 +645,49 @@ function buildAIRoutes(aiService, conversationService, logger) {
           const err = validateMessage(msg);
           if (err) return { status: 400, body: { error: err } };
         }
+        const nested = body.options ?? {};
+        const resolvedOptions = {
+          ...nested,
+          ...body.model != null && { model: body.model },
+          ...body.temperature != null && { temperature: body.temperature },
+          ...body.maxTokens != null && { maxTokens: body.maxTokens }
+        };
+        const rawSystemPrompt = body.system ?? body.systemPrompt;
+        if (rawSystemPrompt != null && typeof rawSystemPrompt !== "string") {
+          return { status: 400, body: { error: "system/systemPrompt must be a string" } };
+        }
+        const systemPrompt = rawSystemPrompt;
+        const finalMessages = [
+          ...systemPrompt ? [{ role: "system", content: systemPrompt }] : [],
+          ...messages.map((m) => normalizeMessage(m))
+        ];
+        const wantStream = body.stream !== false;
+        if (wantStream) {
+          try {
+            if (!aiService.streamChatWithTools) {
+              return { status: 501, body: { error: "Streaming is not supported by the configured AI service" } };
+            }
+            const events = aiService.streamChatWithTools(finalMessages, resolvedOptions);
+            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)
+            };
+          } catch (err) {
+            logger.error("[AI Route] /chat stream error", err instanceof Error ? err : void 0);
+            return { status: 500, body: { error: "Internal AI service error" } };
+          }
+        }
         try {
-          const result = await aiService.chat(messages, options);
+          const result = await aiService.chatWithTools(finalMessages, resolvedOptions);
           return { status: 200, body: result };
         } catch (err) {
           logger.error("[AI Route] /chat error", err instanceof Error ? err : void 0);
@@ -389,6 +700,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/chat/stream",
       description: "SSE streaming chat completion",
+      auth: true,
+      permissions: ["ai:chat"],
       handler: async (req) => {
         const { messages, options } = req.body ?? {};
         if (!Array.isArray(messages) || messages.length === 0) {
@@ -402,7 +715,7 @@ function buildAIRoutes(aiService, conversationService, logger) {
           if (!aiService.streamChat) {
             return { status: 501, body: { error: "Streaming is not supported by the configured AI service" } };
           }
-          const events = aiService.streamChat(messages, options);
+          const events = aiService.streamChat(messages.map((m) => normalizeMessage(m)), options);
           return { status: 200, stream: true, events };
         } catch (err) {
           logger.error("[AI Route] /chat/stream error", err instanceof Error ? err : void 0);
@@ -415,6 +728,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/complete",
       description: "Text completion",
+      auth: true,
+      permissions: ["ai:complete"],
       handler: async (req) => {
         const { prompt, options } = req.body ?? {};
         if (!prompt || typeof prompt !== "string") {
@@ -434,6 +749,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "GET",
       path: "/api/v1/ai/models",
       description: "List available models",
+      auth: true,
+      permissions: ["ai:read"],
       handler: async () => {
         try {
           const models = aiService.listModels ? await aiService.listModels() : [];
@@ -449,9 +766,17 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/conversations",
       description: "Create a conversation",
+      auth: true,
+      permissions: ["ai:conversations"],
       handler: async (req) => {
         try {
-          const options = req.body ?? {};
+          if (req.body !== void 0 && req.body !== null && (typeof req.body !== "object" || Array.isArray(req.body))) {
+            return { status: 400, body: { error: "Invalid request payload" } };
+          }
+          const options = { ...req.body ?? {} };
+          if (req.user?.userId) {
+            options.userId = req.user.userId;
+          }
           const conversation = await conversationService.create(options);
           return { status: 201, body: conversation };
         } catch (err) {
@@ -464,6 +789,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "GET",
       path: "/api/v1/ai/conversations",
       description: "List conversations",
+      auth: true,
+      permissions: ["ai:conversations"],
       handler: async (req) => {
         try {
           const rawQuery = req.query ?? {};
@@ -475,6 +802,9 @@ function buildAIRoutes(aiService, conversationService, logger) {
             }
             options.limit = parsedLimit;
           }
+          if (req.user?.userId) {
+            options.userId = req.user.userId;
+          }
           const conversations = await conversationService.list(options);
           return { status: 200, body: { conversations } };
         } catch (err) {
@@ -487,6 +817,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/conversations/:id/messages",
       description: "Add message to a conversation",
+      auth: true,
+      permissions: ["ai:conversations"],
       handler: async (req) => {
         const id = req.params?.id;
         if (!id) {
@@ -498,6 +830,15 @@ function buildAIRoutes(aiService, conversationService, logger) {
           return { status: 400, body: { error: validationError } };
         }
         try {
+          if (req.user?.userId) {
+            const existing = await conversationService.get(id);
+            if (!existing) {
+              return { status: 404, body: { error: `Conversation "${id}" not found` } };
+            }
+            if (existing.userId && existing.userId !== req.user.userId) {
+              return { status: 403, body: { error: "You do not have access to this conversation" } };
+            }
+          }
           const conversation = await conversationService.addMessage(id, message);
           return { status: 200, body: conversation };
         } catch (err) {
@@ -514,12 +855,23 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "DELETE",
       path: "/api/v1/ai/conversations/:id",
       description: "Delete a conversation",
+      auth: true,
+      permissions: ["ai:conversations"],
       handler: async (req) => {
         const id = req.params?.id;
         if (!id) {
           return { status: 400, body: { error: "conversation id is required" } };
         }
         try {
+          if (req.user?.userId) {
+            const existing = await conversationService.get(id);
+            if (!existing) {
+              return { status: 404, body: { error: `Conversation "${id}" not found` } };
+            }
+            if (existing.userId && existing.userId !== req.user.userId) {
+              return { status: 403, body: { error: "You do not have access to this conversation" } };
+            }
+          }
           await conversationService.delete(id);
           return { status: 204 };
         } catch (err) {
@@ -548,10 +900,33 @@ function validateAgentMessage(raw) {
 }
 function buildAgentRoutes(aiService, agentRuntime, logger) {
   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 : void 0
+          );
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── Chat with a specific agent ──────────────────────────────
     {
       method: "POST",
       path: "/api/v1/ai/agents/:agentName/chat",
       description: "Chat with a specific AI agent",
+      auth: true,
+      permissions: ["ai:chat", "ai:agents"],
       handler: async (req) => {
         const agentName = req.params?.agentName;
         if (!agentName) {
@@ -705,13 +1080,35 @@ var ObjectQLConversationService = class {
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const msgId = `msg_${(0, import_node_crypto.randomUUID)()}`;
+    let contentStr;
+    let toolCallsJson = null;
+    let toolCallId = null;
+    if (message.role === "system" || message.role === "user") {
+      contentStr = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
+    } else if (message.role === "assistant") {
+      if (typeof message.content === "string") {
+        contentStr = message.content;
+      } else {
+        const parts = message.content;
+        const textParts = parts.filter((p) => p.type === "text").map((p) => p.text);
+        const toolCalls = parts.filter((p) => p.type === "tool-call");
+        contentStr = textParts.join("");
+        if (toolCalls.length > 0) toolCallsJson = JSON.stringify(toolCalls);
+      }
+    } else if (message.role === "tool") {
+      contentStr = JSON.stringify(message.content);
+      const firstResult = Array.isArray(message.content) ? message.content[0] : void 0;
+      if (firstResult && "toolCallId" in firstResult) toolCallId = firstResult.toolCallId;
+    } else {
+      contentStr = "";
+    }
     await this.engine.insert(MESSAGES_OBJECT, {
       id: msgId,
       conversation_id: conversationId,
       role: message.role,
-      content: message.content,
-      tool_calls: message.toolCalls ? JSON.stringify(message.toolCalls) : null,
-      tool_call_id: message.toolCallId ?? null,
+      content: contentStr,
+      tool_calls: toolCallsJson,
+      tool_call_id: toolCallId,
       created_at: now
     });
     await this.engine.update(CONVERSATIONS_OBJECT, { id: conversationId, updated_at: now }, {
@@ -756,21 +1153,42 @@ var ObjectQLConversationService = class {
     };
   }
   /**
-   * Map a database row to an AIMessage.
+   * Map a database row to a ModelMessage.
    */
   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;
+    switch (row.role) {
+      case "system":
+        return { role: "system", content: row.content };
+      case "user":
+        return { role: "user", content: row.content };
+      case "assistant": {
+        const toolCalls = this.safeParse(row.tool_calls);
+        if (toolCalls && toolCalls.length > 0) {
+          const content = [];
+          if (row.content) content.push({ type: "text", text: row.content });
+          content.push(...toolCalls);
+          return { role: "assistant", content };
+        }
+        return { role: "assistant", content: row.content };
+      }
+      case "tool": {
+        const toolResults = this.safeParse(row.content);
+        if (toolResults && toolResults.length > 0 && toolResults[0]?.type === "tool-result") {
+          return { role: "tool", content: toolResults };
+        }
+        return {
+          role: "tool",
+          content: [{
+            type: "tool-result",
+            toolCallId: row.tool_call_id ?? "",
+            toolName: "unknown",
+            output: { type: "text", value: row.content }
+          }]
+        };
+      }
+      default:
+        return { role: "user", content: row.content };
     }
-    return msg;
   }
 };
 
@@ -1167,13 +1585,507 @@ function registerDataTools(registry, context) {
   registry.register(AGGREGATE_DATA_TOOL, createAggregateDataHandler(context));
 }
 
-// src/agent-runtime.ts
+// src/tools/create-object.tool.ts
 var import_ai = require("@objectstack/spec/ai");
+var createObjectTool = (0, import_ai.defineTool)({
+  name: "create_object",
+  label: "Create Object",
+  description: "Creates a new data object (table) with the specified name, label, and optional field definitions. Use this when the user wants to create a new entity, table, or data model.",
+  category: "data",
+  builtIn: true,
+  // NOTE: requiresConfirmation is intentionally false (default) because the
+  // server-side tool-call loop in AIService.chatWithTools/streamChatWithTools
+  // executes tool calls immediately without checking this flag.  The flag
+  // should only be set once server-side approval gating is implemented to
+  // avoid giving users a false sense of safety.
+  parameters: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "Machine name for the object (snake_case, e.g. project_task)"
+      },
+      label: {
+        type: "string",
+        description: "Human-readable display name (e.g. Project Task)"
+      },
+      fields: {
+        type: "array",
+        description: "Initial fields to create with the object",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Field machine name (snake_case)" },
+            label: { type: "string", description: "Field display name" },
+            type: {
+              type: "string",
+              description: "Field data type",
+              enum: ["text", "textarea", "number", "boolean", "date", "datetime", "select", "lookup", "formula", "autonumber"]
+            },
+            required: { type: "boolean", description: "Whether the field is required" }
+          },
+          required: ["name", "type"]
+        }
+      },
+      enableFeatures: {
+        type: "object",
+        description: "Object capability flags",
+        properties: {
+          trackHistory: { type: "boolean" },
+          apiEnabled: { type: "boolean" }
+        }
+      }
+    },
+    required: ["name", "label"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/add-field.tool.ts
+var import_ai2 = require("@objectstack/spec/ai");
+var addFieldTool = (0, import_ai2.defineTool)({
+  name: "add_field",
+  label: "Add Field",
+  description: "Adds a new field (column) to an existing data object. Use this when the user wants to add a property, column, or attribute to a table.",
+  category: "data",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "Target object machine name (snake_case)"
+      },
+      name: {
+        type: "string",
+        description: "Field machine name (snake_case, e.g. due_date)"
+      },
+      label: {
+        type: "string",
+        description: "Human-readable field label (e.g. Due Date)"
+      },
+      type: {
+        type: "string",
+        description: "Field data type",
+        enum: ["text", "textarea", "number", "boolean", "date", "datetime", "select", "lookup", "formula", "autonumber"]
+      },
+      required: {
+        type: "boolean",
+        description: "Whether the field is required"
+      },
+      defaultValue: {
+        description: "Default value for the field"
+      },
+      options: {
+        type: "array",
+        description: "Options for select/picklist fields",
+        items: {
+          type: "object",
+          properties: {
+            label: { type: "string" },
+            value: {
+              type: "string",
+              description: "Option machine identifier (lowercase snake_case, e.g. high_priority)",
+              pattern: "^[a-z_][a-z0-9_]*$"
+            }
+          }
+        }
+      },
+      reference: {
+        type: "string",
+        description: "Referenced object name for lookup fields (snake_case, e.g. account)"
+      }
+    },
+    required: ["objectName", "name", "type"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/modify-field.tool.ts
+var import_ai3 = require("@objectstack/spec/ai");
+var modifyFieldTool = (0, import_ai3.defineTool)({
+  name: "modify_field",
+  label: "Modify Field",
+  description: "Modifies an existing field definition (label, type, required, default value, etc.) on a data object. Use this when the user wants to change or reconfigure an existing column or attribute (not rename it).",
+  category: "data",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "Target object machine name (snake_case)"
+      },
+      fieldName: {
+        type: "string",
+        description: "Existing field machine name to modify (snake_case)"
+      },
+      changes: {
+        type: "object",
+        description: "Field properties to update (partial patch)",
+        properties: {
+          label: { type: "string", description: "New display label" },
+          type: { type: "string", description: "New field type" },
+          required: { type: "boolean", description: "Update required constraint" },
+          defaultValue: { description: "New default value" }
+        }
+      }
+    },
+    required: ["objectName", "fieldName", "changes"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/delete-field.tool.ts
+var import_ai4 = require("@objectstack/spec/ai");
+var deleteFieldTool = (0, import_ai4.defineTool)({
+  name: "delete_field",
+  label: "Delete Field",
+  description: "Removes a field (column) from an existing data object. This is a destructive operation. Use this when the user explicitly wants to remove an attribute or column from a table.",
+  category: "data",
+  builtIn: true,
+  // NOTE: requiresConfirmation is intentionally false (default) because the
+  // server-side tool-call loop in AIService.chatWithTools/streamChatWithTools
+  // executes tool calls immediately without checking this flag.  The flag
+  // should only be set once server-side approval gating is implemented.
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "Target object machine name (snake_case)"
+      },
+      fieldName: {
+        type: "string",
+        description: "Field machine name to delete (snake_case)"
+      }
+    },
+    required: ["objectName", "fieldName"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/list-metadata-objects.tool.ts
+var import_ai5 = require("@objectstack/spec/ai");
+var listMetadataObjectsTool = (0, import_ai5.defineTool)({
+  name: "list_metadata_objects",
+  label: "List Metadata Objects",
+  description: "Lists all registered metadata objects (tables) in the current environment. Use this when the user wants to see what tables, entities, or data models are defined in metadata.",
+  category: "data",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      filter: {
+        type: "string",
+        description: "Optional name or label substring to filter objects"
+      },
+      includeFields: {
+        type: "boolean",
+        description: "Whether to include field summaries for each object (default: false)"
+      }
+    },
+    additionalProperties: false
+  }
+});
+
+// src/tools/describe-metadata-object.tool.ts
+var import_ai6 = require("@objectstack/spec/ai");
+var describeMetadataObjectTool = (0, import_ai6.defineTool)({
+  name: "describe_metadata_object",
+  label: "Describe Metadata Object",
+  description: "Returns the full metadata schema details of a data object, including all fields, types, relationships, and configuration. Use this when the user wants to inspect or understand the metadata structure of a specific table or entity.",
+  category: "data",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      objectName: {
+        type: "string",
+        description: "Object machine name to describe (snake_case)"
+      }
+    },
+    required: ["objectName"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/metadata-tools.ts
+var METADATA_TOOL_DEFINITIONS = [
+  createObjectTool,
+  addFieldTool,
+  modifyFieldTool,
+  deleteFieldTool,
+  listMetadataObjectsTool,
+  describeMetadataObjectTool
+];
+var SNAKE_CASE_RE = /^[a-z_][a-z0-9_]*$/;
+function isSnakeCase(value) {
+  return SNAKE_CASE_RE.test(value);
+}
+function createCreateObjectHandler(ctx) {
+  return async (args) => {
+    const { name, label, fields, enableFeatures } = args;
+    if (!name || !label) {
+      return JSON.stringify({ error: 'Both "name" and "label" are required' });
+    }
+    if (!isSnakeCase(name)) {
+      return JSON.stringify({ error: `Invalid object name "${name}". Must be snake_case.` });
+    }
+    const existing = await ctx.metadataService.getObject(name);
+    if (existing) {
+      return JSON.stringify({ error: `Object "${name}" already exists` });
+    }
+    const fieldMap = {};
+    if (fields && Array.isArray(fields)) {
+      const seenNames = /* @__PURE__ */ new Set();
+      for (const f of fields) {
+        if (!f.name) {
+          return JSON.stringify({ error: 'Each field must have a "name" property' });
+        }
+        if (!isSnakeCase(f.name)) {
+          return JSON.stringify({ error: `Invalid field name "${f.name}". Must be snake_case.` });
+        }
+        if (seenNames.has(f.name)) {
+          return JSON.stringify({ error: `Duplicate field name "${f.name}" in initial fields` });
+        }
+        seenNames.add(f.name);
+        fieldMap[f.name] = {
+          type: f.type,
+          ...f.label ? { label: f.label } : {},
+          ...f.required !== void 0 ? { required: f.required } : {}
+        };
+      }
+    }
+    const objectDef = {
+      name,
+      label,
+      ...Object.keys(fieldMap).length > 0 ? { fields: fieldMap } : {},
+      ...enableFeatures ? { enable: enableFeatures } : {}
+    };
+    await ctx.metadataService.register("object", name, objectDef);
+    return JSON.stringify({
+      name,
+      label,
+      fieldCount: Object.keys(fieldMap).length
+    });
+  };
+}
+function createAddFieldHandler(ctx) {
+  return async (args) => {
+    const { objectName, name, label, type, required, defaultValue, options, reference } = args;
+    if (!objectName || !name || !type) {
+      return JSON.stringify({ error: '"objectName", "name", and "type" are required' });
+    }
+    if (!isSnakeCase(objectName)) {
+      return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
+    }
+    if (!isSnakeCase(name)) {
+      return JSON.stringify({ error: `Invalid field name "${name}". Must be snake_case.` });
+    }
+    if (reference && !isSnakeCase(reference)) {
+      return JSON.stringify({ error: `Invalid reference "${reference}". Must be a snake_case object name.` });
+    }
+    if (options && Array.isArray(options)) {
+      for (const opt of options) {
+        if (opt.value && !isSnakeCase(opt.value)) {
+          return JSON.stringify({ error: `Invalid option value "${opt.value}". Must be lowercase snake_case.` });
+        }
+      }
+    }
+    const objectDef = await ctx.metadataService.getObject(objectName);
+    if (!objectDef) {
+      return JSON.stringify({ error: `Object "${objectName}" not found` });
+    }
+    const def = objectDef;
+    if (def.fields && def.fields[name]) {
+      return JSON.stringify({ error: `Field "${name}" already exists on object "${objectName}"` });
+    }
+    const fieldDef = {
+      type,
+      ...label ? { label } : {},
+      ...required !== void 0 ? { required } : {},
+      ...defaultValue !== void 0 ? { defaultValue } : {},
+      ...options ? { options } : {},
+      ...reference ? { reference } : {}
+    };
+    const updatedFields = { ...def.fields ?? {}, [name]: fieldDef };
+    await ctx.metadataService.register("object", objectName, {
+      ...def,
+      fields: updatedFields
+    });
+    return JSON.stringify({
+      objectName,
+      fieldName: name,
+      fieldType: type
+    });
+  };
+}
+function createModifyFieldHandler(ctx) {
+  return async (args) => {
+    const { objectName, fieldName, changes } = args;
+    if (!objectName || !fieldName || !changes) {
+      return JSON.stringify({ error: '"objectName", "fieldName", and "changes" are required' });
+    }
+    if (!isSnakeCase(objectName)) {
+      return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
+    }
+    if (!isSnakeCase(fieldName)) {
+      return JSON.stringify({ error: `Invalid field name "${fieldName}". Must be snake_case.` });
+    }
+    const objectDef = await ctx.metadataService.getObject(objectName);
+    if (!objectDef) {
+      return JSON.stringify({ error: `Object "${objectName}" not found` });
+    }
+    const def = objectDef;
+    if (!def.fields || !def.fields[fieldName]) {
+      return JSON.stringify({ error: `Field "${fieldName}" not found on object "${objectName}"` });
+    }
+    const existingField = def.fields[fieldName];
+    const updatedField = { ...existingField, ...changes };
+    const updatedFields = { ...def.fields, [fieldName]: updatedField };
+    await ctx.metadataService.register("object", objectName, {
+      ...def,
+      fields: updatedFields
+    });
+    return JSON.stringify({
+      objectName,
+      fieldName,
+      updatedProperties: Object.keys(changes)
+    });
+  };
+}
+function createDeleteFieldHandler(ctx) {
+  return async (args) => {
+    const { objectName, fieldName } = args;
+    if (!objectName || !fieldName) {
+      return JSON.stringify({ error: '"objectName" and "fieldName" are required' });
+    }
+    if (!isSnakeCase(objectName)) {
+      return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
+    }
+    if (!isSnakeCase(fieldName)) {
+      return JSON.stringify({ error: `Invalid field name "${fieldName}". Must be snake_case.` });
+    }
+    const objectDef = await ctx.metadataService.getObject(objectName);
+    if (!objectDef) {
+      return JSON.stringify({ error: `Object "${objectName}" not found` });
+    }
+    const def = objectDef;
+    if (!def.fields || !def.fields[fieldName]) {
+      return JSON.stringify({ error: `Field "${fieldName}" not found on object "${objectName}"` });
+    }
+    const { [fieldName]: _removed, ...remainingFields } = def.fields;
+    await ctx.metadataService.register("object", objectName, {
+      ...def,
+      fields: remainingFields
+    });
+    return JSON.stringify({
+      objectName,
+      fieldName,
+      success: true
+    });
+  };
+}
+function createListObjectsHandler2(ctx) {
+  return async (args) => {
+    const { filter, includeFields } = args ?? {};
+    const objects = await ctx.metadataService.listObjects();
+    let result = objects.map((o) => {
+      const base = {
+        name: o.name,
+        label: o.label ?? o.name,
+        fieldCount: o.fields ? Object.keys(o.fields).length : 0
+      };
+      if (includeFields && o.fields) {
+        base.fields = Object.entries(o.fields).map(([key, f]) => ({
+          name: key,
+          type: f.type,
+          label: f.label ?? key
+        }));
+      }
+      return base;
+    });
+    if (filter) {
+      const lower = filter.toLowerCase();
+      result = result.filter(
+        (o) => o.name.toLowerCase().includes(lower) || o.label.toLowerCase().includes(lower)
+      );
+    }
+    return JSON.stringify({
+      objects: result,
+      totalCount: result.length
+    });
+  };
+}
+function createDescribeObjectHandler2(ctx) {
+  return async (args) => {
+    const { objectName } = args;
+    if (!objectName) {
+      return JSON.stringify({ error: '"objectName" is required' });
+    }
+    if (!isSnakeCase(objectName)) {
+      return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
+    }
+    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 = Object.entries(fields).map(([key, f]) => ({
+      name: 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,
+      enableFeatures: def.enable ?? {}
+    });
+  };
+}
+function registerMetadataTools(registry, context) {
+  registry.register(createObjectTool, createCreateObjectHandler(context));
+  registry.register(addFieldTool, createAddFieldHandler(context));
+  registry.register(modifyFieldTool, createModifyFieldHandler(context));
+  registry.register(deleteFieldTool, createDeleteFieldHandler(context));
+  registry.register(listMetadataObjectsTool, createListObjectsHandler2(context));
+  registry.register(describeMetadataObjectTool, createDescribeObjectHandler2(context));
+}
+
+// src/agent-runtime.ts
+var import_ai7 = require("@objectstack/spec/ai");
 var AgentRuntime = class {
   constructor(metadataService) {
     this.metadataService = metadataService;
   }
   // ── 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() {
+    const rawItems = await this.metadataService.list("agent");
+    const agents = [];
+    for (const raw of rawItems) {
+      const result = import_ai7.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.
    *
@@ -1185,7 +2097,7 @@ var AgentRuntime = class {
   async loadAgent(agentName) {
     const raw = await this.metadataService.get("agent", agentName);
     if (!raw) return void 0;
-    const result = import_ai.AgentSchema.safeParse(raw);
+    const result = import_ai7.AgentSchema.safeParse(raw);
     if (!result.success) {
       return void 0;
     }
@@ -1302,15 +2214,233 @@ Guidelines:
   }
 };
 
+// src/agents/metadata-assistant-agent.ts
+var METADATA_ASSISTANT_AGENT = {
+  name: "metadata_assistant",
+  label: "Metadata Assistant",
+  role: "Schema Architect",
+  instructions: `You are an expert metadata architect that helps users design and manage their data models through natural language.
+
+Capabilities:
+- Create new data objects (tables) with fields
+- Add fields (columns) to existing objects
+- Modify field properties (label, type, required, default value)
+- Delete fields from objects
+- List all registered metadata objects and their schemas
+- Describe the full schema of a specific object
+
+Guidelines:
+1. Before creating a new object, use list_metadata_objects to check if a similar one already exists.
+2. Before modifying or deleting fields, use describe_metadata_object to understand the current schema.
+3. Always use snake_case for object names and field names (e.g. project_task, due_date).
+4. Suggest meaningful field types based on the user's description (e.g. "deadline" \u2192 date, "active" \u2192 boolean).
+5. When creating objects, propose a reasonable set of initial fields based on the entity type.
+6. Explain what changes you are about to make before executing them.
+7. After making changes, confirm the result by describing the updated schema.
+8. For destructive operations (deleting fields), always warn the user about potential data loss.
+9. Always answer in the same language the user is using.
+10. If the user's request is ambiguous, ask clarifying questions before proceeding.`,
+  model: {
+    provider: "openai",
+    model: "gpt-4",
+    temperature: 0.2,
+    maxTokens: 4096
+  },
+  tools: [
+    { type: "action", name: "create_object", description: "Create a new data object (table)" },
+    { type: "action", name: "add_field", description: "Add a field to an existing object" },
+    { type: "action", name: "modify_field", description: "Modify an existing field definition" },
+    { type: "action", name: "delete_field", description: "Delete a field from an object" },
+    { type: "query", name: "list_metadata_objects", description: "List all metadata objects" },
+    { type: "query", name: "describe_metadata_object", description: "Describe an object schema" }
+  ],
+  active: true,
+  visibility: "global",
+  guardrails: {
+    maxTokensPerInvocation: 8192,
+    maxExecutionTimeSec: 60,
+    blockedTopics: ["drop_database", "raw_sql", "system_tables"]
+  },
+  planning: {
+    strategy: "react",
+    maxIterations: 10,
+    allowReplan: true
+  },
+  memory: {
+    shortTerm: {
+      maxMessages: 30,
+      maxTokens: 8192
+    }
+  }
+};
+
+// src/adapters/vercel-adapter.ts
+var import_ai8 = require("ai");
+function buildVercelOptions(options) {
+  if (!options) return {};
+  const opts = {};
+  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 = {};
+    for (const t of options.tools) {
+      tools[t.name] = (0, import_ai8.tool)({
+        description: t.description,
+        inputSchema: (0, import_ai8.jsonSchema)(t.parameters)
+      });
+    }
+    opts.tools = tools;
+  }
+  if (options.toolChoice != null) {
+    opts.toolChoice = options.toolChoice;
+  }
+  return opts;
+}
+var VercelLLMAdapter = class {
+  constructor(config) {
+    this.name = "vercel";
+    this.model = config.model;
+  }
+  async chat(messages, options) {
+    const result = await (0, import_ai8.generateText)({
+      model: this.model,
+      messages,
+      ...buildVercelOptions(options)
+    });
+    return {
+      content: result.text,
+      model: result.response?.modelId,
+      toolCalls: result.toolCalls?.length ? result.toolCalls : void 0,
+      usage: result.usage ? {
+        promptTokens: result.usage.inputTokens ?? 0,
+        completionTokens: result.usage.outputTokens ?? 0,
+        totalTokens: result.usage.totalTokens ?? 0
+      } : void 0
+    };
+  }
+  async complete(prompt, options) {
+    const result = await (0, import_ai8.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
+      } : void 0
+    };
+  }
+  async *streamChat(messages, options) {
+    const result = (0, import_ai8.streamText)({
+      model: this.model,
+      messages,
+      ...buildVercelOptions(options)
+    });
+    for await (const part of result.fullStream) {
+      yield part;
+    }
+  }
+  async embed(_input) {
+    throw new Error(
+      "[VercelLLMAdapter] Embeddings require a dedicated EmbeddingModel. Configure an embedding adapter instead."
+    );
+  }
+  async listModels() {
+    return [];
+  }
+};
+
 // 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.dependencies = ["com.objectstack.engine.objectql"];
     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.
+   */
+  async detectAdapter(ctx) {
+    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 } : void 0
+        );
+      }
+    }
+    const providerConfigs = [
+      {
+        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 } : void 0
+          );
+        }
+      }
+    }
+    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) {
     let hasExisting = false;
     try {
@@ -1332,8 +2462,19 @@ var AIServicePlugin = class {
       } catch {
       }
     }
+    let adapter;
+    let adapterDescription;
+    if (this.options.adapter) {
+      adapter = this.options.adapter;
+      adapterDescription = `${adapter.name} (explicitly configured)`;
+    } else {
+      const detected = await this.detectAdapter(ctx);
+      adapter = detected.adapter;
+      adapterDescription = detected.description;
+    }
+    ctx.logger.info(`[AI] Using LLM adapter: ${adapterDescription}`);
     const config = {
-      adapter: this.options.adapter,
+      adapter,
       logger: ctx.logger,
       conversationService
     };
@@ -1343,7 +2484,7 @@ var AIServicePlugin = class {
     } else {
       ctx.registerService("ai", this.service);
     }
-    ctx.registerService("app.com.objectstack.service-ai", {
+    ctx.getService("manifest").register({
       id: "com.objectstack.service-ai",
       name: "AI Service",
       version: "1.0.0",
@@ -1356,13 +2497,32 @@ var AIServicePlugin = class {
         ctx.logger.debug("[AI] Before chat", { messages });
       });
     }
+    try {
+      const setupNav = ctx.getService("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 {
+    }
     ctx.logger.info("[AI] Service initialized");
   }
   async start(ctx) {
     if (!this.service) return;
+    let metadataService;
+    try {
+      metadataService = ctx.getService("metadata");
+    } catch {
+      ctx.logger.debug("[AI] Metadata service not available");
+    }
     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");
@@ -1375,14 +2535,29 @@ var AIServicePlugin = class {
         }
       }
     } catch {
-      ctx.logger.debug("[AI] Data engine or metadata service not available, skipping data tools");
+      ctx.logger.debug("[AI] Data engine not available, skipping data tools");
+    }
+    if (metadataService) {
+      try {
+        registerMetadataTools(this.service.toolRegistry, { metadataService });
+        ctx.logger.info("[AI] Built-in metadata tools registered");
+        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);
+          ctx.logger.info("[AI] metadata_assistant agent registered");
+        } else {
+          ctx.logger.debug("[AI] metadata_assistant agent already exists, skipping auto-registration");
+        }
+      } catch (err) {
+        ctx.logger.debug("[AI] Failed to register metadata tools", err instanceof Error ? err : void 0);
+      }
     }
     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 metadataService2 = ctx.getService("metadata");
+      if (metadataService2) {
+        const agentRuntime = new AgentRuntime(metadataService2);
         const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
         routes.push(...agentRoutes);
       }
@@ -1390,6 +2565,10 @@ var AIServicePlugin = class {
       ctx.logger.debug("[AI] Metadata service not available, skipping agent routes");
     }
     await ctx.trigger("ai:routes", routes);
+    const kernel = ctx.getKernel();
+    if (kernel) {
+      kernel.__aiRoutes = routes;
+    }
     ctx.logger.info(
       `[AI] Service started \u2014 adapter="${this.service.adapterName}", tools=${this.service.toolRegistry.size}, routes=${routes.length}`
     );
@@ -1408,11 +2587,23 @@ var AIServicePlugin = class {
   DATA_CHAT_AGENT,
   DATA_TOOL_DEFINITIONS,
   InMemoryConversationService,
+  METADATA_ASSISTANT_AGENT,
+  METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter,
   ObjectQLConversationService,
   ToolRegistry,
+  VercelLLMAdapter,
+  addFieldTool,
   buildAIRoutes,
   buildAgentRoutes,
-  registerDataTools
+  createObjectTool,
+  deleteFieldTool,
+  describeMetadataObjectTool,
+  encodeStreamPart,
+  encodeVercelDataStream,
+  listMetadataObjectsTool,
+  modifyFieldTool,
+  registerDataTools,
+  registerMetadataTools
 });
 //# sourceMappingURL=index.cjs.map