@objectstack/service-ai 4.0.4 → 4.1.0

package/dist/index.cjs

@@ -256,6 +256,10 @@ var init_create_object_tool = __esm({
             type: "string",
             description: "Human-readable display name (e.g. Project Task)"
           },
+          packageId: {
+            type: "string",
+            description: "Package ID that will own this object (e.g., com.acme.crm). If not provided, uses the active package from conversation context."
+          },
           fields: {
             type: "array",
             description: "Initial fields to create with the object",
@@ -305,6 +309,10 @@ var init_add_field_tool = __esm({
       parameters: {
         type: "object",
         properties: {
+          packageId: {
+            type: "string",
+            description: "Package ID that owns the target object (e.g., com.acme.crm). If not provided, uses the active package from conversation context."
+          },
           objectName: {
             type: "string",
             description: "Target object machine name (snake_case)"
@@ -371,6 +379,10 @@ var init_modify_field_tool = __esm({
       parameters: {
         type: "object",
         properties: {
+          packageId: {
+            type: "string",
+            description: "Package ID that owns the target object (e.g., com.acme.crm). If not provided, uses the active package from conversation context."
+          },
           objectName: {
             type: "string",
             description: "Target object machine name (snake_case)"
@@ -416,6 +428,10 @@ var init_delete_field_tool = __esm({
       parameters: {
         type: "object",
         properties: {
+          packageId: {
+            type: "string",
+            description: "Package ID that owns the target object (e.g., com.acme.crm). If not provided, uses the active package from conversation context."
+          },
           objectName: {
             type: "string",
             description: "Target object machine name (snake_case)"
@@ -504,12 +520,55 @@ __export(metadata_tools_exports, {
 function isSnakeCase(value) {
   return SNAKE_CASE_RE.test(value);
 }
+async function getActivePackageId(ctx) {
+  if (!ctx.conversationService?.getMetadata || !ctx.conversationId) {
+    return null;
+  }
+  const metadata = await ctx.conversationService.getMetadata(ctx.conversationId);
+  return metadata?.activePackageId ?? null;
+}
+async function resolvePackageId(ctx, explicitPackageId) {
+  let packageId = null;
+  if (explicitPackageId) {
+    packageId = explicitPackageId;
+  } else {
+    packageId = await getActivePackageId(ctx);
+  }
+  if (!packageId) {
+    return {
+      packageId: null,
+      warning: "No package specified. Metadata will be created without package association. Consider using set_active_package or providing packageId parameter."
+    };
+  }
+  if (ctx.packageRegistry) {
+    const exists = await ctx.packageRegistry.exists(packageId);
+    if (!exists) {
+      return {
+        packageId: null,
+        error: `Package "${packageId}" not found. Use list_packages to see available packages or create_package to create a new one.`
+      };
+    }
+    const pkg = await ctx.packageRegistry.get(packageId);
+    if (pkg?.manifest.source === "filesystem") {
+      return {
+        packageId: null,
+        error: `Package "${packageId}" is read-only (loaded from code). Only database packages can be modified. Use create_package to create a new database package.`
+      };
+    }
+  }
+  return { packageId };
+}
 function createCreateObjectHandler(ctx) {
   return async (args) => {
-    const { name, label, fields, enableFeatures } = args;
+    const { name, label, packageId: explicitPackageId, fields, enableFeatures } = args;
     if (!name || !label) {
       return JSON.stringify({ error: 'Both "name" and "label" are required' });
     }
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
+    const packageId = resolved.packageId;
     if (!isSnakeCase(name)) {
       return JSON.stringify({ error: `Invalid object name "${name}". Must be snake_case.` });
     }
@@ -541,6 +600,7 @@ function createCreateObjectHandler(ctx) {
     const objectDef = {
       name,
       label,
+      ...packageId ? { packageId } : {},
       ...Object.keys(fieldMap).length > 0 ? { fields: fieldMap } : {},
       ...enableFeatures ? { enable: enableFeatures } : {}
     };
@@ -548,16 +608,21 @@ function createCreateObjectHandler(ctx) {
     return JSON.stringify({
       name,
       label,
+      ...packageId ? { packageId } : {},
       fieldCount: Object.keys(fieldMap).length
     });
   };
 }
 function createAddFieldHandler(ctx) {
   return async (args) => {
-    const { objectName, name, label, type, required, defaultValue, options, reference } = args;
+    const { objectName, name, label, type, required, defaultValue, options, reference, packageId: explicitPackageId } = args;
     if (!objectName || !name || !type) {
       return JSON.stringify({ error: '"objectName", "name", and "type" are required' });
     }
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
     if (!isSnakeCase(objectName)) {
       return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
     }
@@ -598,16 +663,21 @@ function createAddFieldHandler(ctx) {
     return JSON.stringify({
       objectName,
       fieldName: name,
-      fieldType: type
+      fieldType: type,
+      packageId: resolved.packageId
     });
   };
 }
 function createModifyFieldHandler(ctx) {
   return async (args) => {
-    const { objectName, fieldName, changes } = args;
+    const { objectName, fieldName, changes, packageId: explicitPackageId } = args;
     if (!objectName || !fieldName || !changes) {
       return JSON.stringify({ error: '"objectName", "fieldName", and "changes" are required' });
     }
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
     if (!isSnakeCase(objectName)) {
       return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
     }
@@ -632,16 +702,21 @@ function createModifyFieldHandler(ctx) {
     return JSON.stringify({
       objectName,
       fieldName,
-      updatedProperties: Object.keys(changes)
+      updatedProperties: Object.keys(changes),
+      packageId: resolved.packageId
     });
   };
 }
 function createDeleteFieldHandler(ctx) {
   return async (args) => {
-    const { objectName, fieldName } = args;
+    const { objectName, fieldName, packageId: explicitPackageId } = args;
     if (!objectName || !fieldName) {
       return JSON.stringify({ error: '"objectName" and "fieldName" are required' });
     }
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
     if (!isSnakeCase(objectName)) {
       return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
     }
@@ -664,7 +739,8 @@ function createDeleteFieldHandler(ctx) {
     return JSON.stringify({
       objectName,
       fieldName,
-      success: true
+      success: true,
+      packageId: resolved.packageId
     });
   };
 }
@@ -781,21 +857,30 @@ __export(index_exports, {
   METADATA_TOOL_DEFINITIONS: () => METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter: () => MemoryLLMAdapter,
   ObjectQLConversationService: () => ObjectQLConversationService,
+  PACKAGE_TOOL_DEFINITIONS: () => PACKAGE_TOOL_DEFINITIONS,
+  SkillRegistry: () => SkillRegistry,
   ToolRegistry: () => ToolRegistry,
   VercelLLMAdapter: () => VercelLLMAdapter,
   addFieldTool: () => addFieldTool,
   buildAIRoutes: () => buildAIRoutes,
   buildAgentRoutes: () => buildAgentRoutes,
+  buildAssistantRoutes: () => buildAssistantRoutes,
   buildToolRoutes: () => buildToolRoutes,
   createObjectTool: () => createObjectTool,
+  createPackageTool: () => createPackageTool,
   deleteFieldTool: () => deleteFieldTool,
   describeObjectTool: () => describeObjectTool,
   encodeStreamPart: () => encodeStreamPart,
   encodeVercelDataStream: () => encodeVercelDataStream,
+  getActivePackageTool: () => getActivePackageTool,
+  getPackageTool: () => getPackageTool,
   listObjectsTool: () => listObjectsTool,
+  listPackagesTool: () => listPackagesTool,
   modifyFieldTool: () => modifyFieldTool,
   registerDataTools: () => registerDataTools,
-  registerMetadataTools: () => registerMetadataTools
+  registerMetadataTools: () => registerMetadataTools,
+  registerPackageTools: () => registerPackageTools,
+  setActivePackageTool: () => setActivePackageTool
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1310,25 +1395,41 @@ async function* encodeVercelDataStream(events) {
   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;
+  let errorMessage;
+  try {
+    for await (const part of events) {
+      if (part.type === "error") {
+        const errPart = part;
+        const raw = errPart.error;
+        errorMessage = raw && typeof raw === "object" && "message" in raw ? String(raw.message) : typeof raw === "string" ? raw : "Unknown provider error";
+        finishReason = "error";
+        break;
+      }
+      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;
       }
-      continue;
-    }
-    const frame = encodeStreamPart(part);
-    if (frame) {
-      yield frame;
     }
+  } catch (err) {
+    errorMessage = err instanceof Error ? err.message : String(err);
+    finishReason = "error";
   }
   if (textOpen) {
     yield sse({ type: "text-end", id: "0" });
   }
+  if (errorMessage) {
+    yield sse({ type: "error", errorText: errorMessage });
+  }
   yield sse({ type: "finish-step" });
   yield sse({ type: "finish", finishReason });
   yield "data: [DONE]\n\n";
@@ -1732,10 +1833,12 @@ function buildAgentRoutes(aiService, agentRuntime, logger) {
           return { status: 403, body: { error: `Agent "${agentName}" is not active` } };
         }
         try {
-          const systemMessages = agentRuntime.buildSystemMessages(agent, chatContext);
+          const activeSkills = await agentRuntime.resolveActiveSkills(agent, chatContext);
+          const systemMessages = agentRuntime.buildSystemMessages(agent, chatContext, activeSkills);
           const agentOptions = agentRuntime.buildRequestOptions(
             agent,
-            aiService.toolRegistry.getAll()
+            aiService.toolRegistry.getAll(),
+            activeSkills
           );
           const safeOverrides = {};
           if (extraOptions) {
@@ -1789,6 +1892,217 @@ function buildAgentRoutes(aiService, agentRuntime, logger) {
   ];
 }
 
+// src/routes/assistant-routes.ts
+var ALLOWED_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
+function validateAssistantMessage(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return "each message must be an object";
+  }
+  const msg = raw;
+  if (typeof msg.role !== "string" || !ALLOWED_ROLES.has(msg.role)) {
+    return `message.role must be one of ${[...ALLOWED_ROLES].map((r) => `"${r}"`).join(", ")} for assistant chat`;
+  }
+  const allowEmpty = msg.role === "assistant";
+  return validateMessageContent(msg, { allowEmptyContent: allowEmpty });
+}
+function parseContext(raw) {
+  if (typeof raw !== "object" || raw === null) return {};
+  const obj = raw;
+  const ctx = {};
+  for (const key of Object.keys(obj)) {
+    ctx[key] = obj[key];
+  }
+  return ctx;
+}
+function buildAssistantRoutes(aiService, agentRuntime, skillRegistry, logger) {
+  return [
+    // ── Resolve current assistant + skill set ──────────────────
+    {
+      method: "GET",
+      path: "/api/v1/ai/assistant",
+      description: "Resolve the default AI assistant and active skills for a given context",
+      auth: true,
+      permissions: ["ai:chat"],
+      handler: async (req) => {
+        try {
+          const context = parseContextFromQuery(req.query);
+          const explicitAgentName = typeof req.query?.agent === "string" ? req.query.agent : void 0;
+          const agent = explicitAgentName ? await agentRuntime.loadAgent(explicitAgentName) : await agentRuntime.resolveDefaultAgent(context);
+          if (!agent) {
+            return {
+              status: 200,
+              body: { agent: null, skills: [] }
+            };
+          }
+          const skills = await agentRuntime.resolveActiveSkills(agent, context);
+          return {
+            status: 200,
+            body: {
+              agent: {
+                name: agent.name,
+                label: agent.label,
+                role: agent.role,
+                avatar: agent.avatar,
+                instructions: agent.instructions
+              },
+              skills: skills.map((s) => skillRegistry.toSummary(s)),
+              context
+            }
+          };
+        } catch (err) {
+          logger.error("[AI Route] /assistant error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── List active skills (slash-command palette) ─────────────
+    {
+      method: "GET",
+      path: "/api/v1/ai/assistant/skills",
+      description: "List active AI skills for a given context (used by slash-command palettes)",
+      auth: true,
+      permissions: ["ai:chat"],
+      handler: async (req) => {
+        try {
+          const context = parseContextFromQuery(req.query);
+          const agentName = typeof req.query?.agent === "string" ? req.query.agent : void 0;
+          let restrictTo;
+          if (agentName) {
+            const agent = await agentRuntime.loadAgent(agentName);
+            if (agent?.skills) restrictTo = agent.skills;
+          }
+          const skills = await skillRegistry.listActiveSkills(context, restrictTo);
+          return {
+            status: 200,
+            body: { skills: skills.map((s) => skillRegistry.toSummary(s)) }
+          };
+        } catch (err) {
+          logger.error("[AI Route] /assistant/skills error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
+    // ── Ambient chat (the "single entry" Claude-Code pattern) ──
+    {
+      method: "POST",
+      path: "/api/v1/ai/assistant/chat",
+      description: "Ambient AI chat \u2014 auto-resolves agent and skills from context (supports Vercel Data Stream Protocol)",
+      auth: true,
+      permissions: ["ai:chat"],
+      handler: async (req) => {
+        const body = req.body ?? {};
+        const {
+          messages: rawMessages,
+          context: rawContext,
+          options: extraOptions,
+          agent: explicitAgentName,
+          skill: explicitSkillName
+        } = body;
+        if (!Array.isArray(rawMessages) || rawMessages.length === 0) {
+          return { status: 400, body: { error: "messages array is required" } };
+        }
+        for (const msg of rawMessages) {
+          const err = validateAssistantMessage(msg);
+          if (err) return { status: 400, body: { error: err } };
+        }
+        const context = parseContext(rawContext);
+        const agent = explicitAgentName ? await agentRuntime.loadAgent(explicitAgentName) : await agentRuntime.resolveDefaultAgent(context);
+        if (!agent) {
+          return {
+            status: 404,
+            body: { error: "No active assistant available \u2014 register at least one agent or set defaultAgent on the app metadata" }
+          };
+        }
+        if (agent.active === false) {
+          return { status: 403, body: { error: `Agent "${agent.name}" is not active` } };
+        }
+        try {
+          let activeSkills = await agentRuntime.resolveActiveSkills(agent, context);
+          if (explicitSkillName) {
+            activeSkills = activeSkills.filter((s) => s.name === explicitSkillName);
+            if (activeSkills.length === 0) {
+              const direct = await skillRegistry.loadSkill(explicitSkillName);
+              if (direct && direct.active !== false) activeSkills = [direct];
+            }
+          }
+          const systemMessages = agentRuntime.buildSystemMessages(agent, context, activeSkills);
+          const agentOptions = agentRuntime.buildRequestOptions(
+            agent,
+            aiService.toolRegistry.getAll(),
+            activeSkills
+          );
+          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.map((m) => normalizeMessage(m))
+          ];
+          const chatWithToolsOptions = {
+            ...mergedOptions,
+            maxIterations: agent.planning?.maxIterations
+          };
+          const wantStream = body.stream !== false;
+          if (wantStream) {
+            if (!aiService.streamChatWithTools) {
+              return { status: 501, body: { error: "Streaming is not supported by the configured AI service" } };
+            }
+            const events = aiService.streamChatWithTools(fullMessages, chatWithToolsOptions);
+            return {
+              status: 200,
+              stream: true,
+              vercelDataStream: true,
+              contentType: "text/event-stream",
+              headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "x-vercel-ai-ui-message-stream": "v1",
+                "x-objectstack-agent": agent.name,
+                "x-objectstack-skills": activeSkills.map((s) => s.name).join(",")
+              },
+              events: encodeVercelDataStream(events)
+            };
+          }
+          const result = await aiService.chatWithTools(fullMessages, chatWithToolsOptions);
+          return {
+            status: 200,
+            body: {
+              ...result ?? {},
+              _agent: agent.name,
+              _skills: activeSkills.map((s) => s.name)
+            }
+          };
+        } catch (err) {
+          logger.error(
+            "[AI Route] /assistant/chat error",
+            err instanceof Error ? err : void 0
+          );
+          const upstreamMsg = err instanceof Error ? err.message : String(err);
+          return {
+            status: 500,
+            body: { error: "Internal AI service error", detail: upstreamMsg }
+          };
+        }
+      }
+    }
+  ];
+}
+function parseContextFromQuery(query) {
+  if (!query) return {};
+  const ctx = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (value == null) continue;
+    ctx[key] = value;
+  }
+  return ctx;
+}
+
 // src/routes/tool-routes.ts
 function extractOutputValue(output) {
   if (!output) return "";
@@ -2104,8 +2418,7 @@ var ObjectQLConversationService = class {
 // src/objects/ai-conversation.object.ts
 var import_data = require("@objectstack/spec/data");
 var AiConversationObject = import_data.ObjectSchema.create({
-  namespace: "ai",
-  name: "conversations",
+  name: "ai_conversations",
   label: "AI Conversation",
   pluralLabel: "AI Conversations",
   icon: "message-square",
@@ -2124,15 +2437,14 @@ var AiConversationObject = import_data.ObjectSchema.create({
       description: "Conversation title or summary"
     }),
     agent_id: import_data.Field.text({
-      label: "Agent ID",
+      label: "Agent",
       required: false,
-      maxLength: 255,
-      description: "Associated AI agent identifier"
+      maxLength: 128,
+      description: "Associated AI agent (metadata name \u2014 agents live as JSON in sys_metadata, no lookup table)"
     }),
-    user_id: import_data.Field.text({
-      label: "User ID",
+    user_id: import_data.Field.lookup("sys_user", {
+      label: "User",
       required: false,
-      maxLength: 255,
       description: "User who owns the conversation"
     }),
     metadata: import_data.Field.textarea({
@@ -2171,8 +2483,7 @@ var AiConversationObject = import_data.ObjectSchema.create({
 // src/objects/ai-message.object.ts
 var import_data2 = require("@objectstack/spec/data");
 var AiMessageObject = import_data2.ObjectSchema.create({
-  namespace: "ai",
-  name: "messages",
+  name: "ai_messages",
   label: "AI Message",
   pluralLabel: "AI Messages",
   icon: "message-circle",
@@ -2184,8 +2495,8 @@ var AiMessageObject = import_data2.ObjectSchema.create({
       required: true,
       readonly: true
     }),
-    conversation_id: import_data2.Field.text({
-      label: "Conversation ID",
+    conversation_id: import_data2.Field.lookup("ai_conversations", {
+      label: "Conversation",
       required: true,
       description: "Foreign key to ai_conversations"
     }),
@@ -2243,8 +2554,9 @@ init_metadata_tools();
 // src/agent-runtime.ts
 var import_ai7 = require("@objectstack/spec/ai");
 var AgentRuntime = class {
-  constructor(metadataService) {
+  constructor(metadataService, skillRegistry) {
     this.metadataService = metadataService;
+    this.skillRegistry = skillRegistry;
   }
   // ── Public API ────────────────────────────────────────────────
   /**
@@ -2288,12 +2600,21 @@ var AgentRuntime = class {
   /**
    * Build the system message(s) that should be prepended to the
    * conversation when chatting with the given agent.
+   *
+   * The composed prompt has up to three sections:
+   * 1. The agent's base `instructions` (its persona / prime directives).
+   * 2. UI context hints from {@link AgentChatContext} (current object,
+   *    record, view) so the agent can tailor responses without extra
+   *    tool calls.
+   * 3. An "Active Skills" block describing the capabilities currently
+   *    available — only populated when `activeSkills` is provided.
    */
-  buildSystemMessages(agent, context) {
+  buildSystemMessages(agent, context, activeSkills) {
     const parts = [];
     parts.push(agent.instructions);
     if (context) {
       const ctx = [];
+      if (context.appName) ctx.push(`Current app: ${context.appName}`);
       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}`);
@@ -2301,6 +2622,10 @@ var AgentRuntime = class {
         parts.push("\n--- Current Context ---\n" + ctx.join("\n"));
       }
     }
+    if (activeSkills && activeSkills.length > 0 && this.skillRegistry) {
+      const block = this.skillRegistry.composeInstructionsBlock(activeSkills);
+      if (block) parts.push(block);
+    }
     return [{ role: "system", content: parts.join("\n") }];
   }
   /**
@@ -2308,37 +2633,272 @@ var AgentRuntime = class {
    *
    * 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.
+   * Tools belonging to `activeSkills` are also resolved and merged into
+   * the final tool list (deduplicated by name).
+   *
+   * Any unresolved references (tools the agent or skill declares but
+   * that are not registered) are silently skipped — this is intentional
+   * so that agents/skills 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
+   * @param activeSkills   - Skills resolved from agent.skills[] + context filtering
    * @returns Request options with model config and resolved tool definitions
    */
-  buildRequestOptions(agent, availableTools) {
+  buildRequestOptions(agent, availableTools, activeSkills) {
     const options = {};
     if (agent.model) {
       options.model = agent.model.model;
       options.temperature = agent.model.temperature;
       options.maxTokens = agent.model.maxTokens;
     }
+    const toolMap = new Map(availableTools.map((t) => [t.name, t]));
+    const seen = /* @__PURE__ */ new Set();
+    const resolved = [];
     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) {
+        if (seen.has(ref.name)) continue;
         const def = toolMap.get(ref.name);
         if (def) {
           resolved.push(def);
+          seen.add(ref.name);
         }
       }
-      if (resolved.length > 0) {
-        options.tools = resolved;
-        options.toolChoice = "auto";
+    }
+    if (activeSkills && activeSkills.length > 0 && this.skillRegistry) {
+      const skillTools = this.skillRegistry.flattenToTools(activeSkills, availableTools);
+      for (const def of skillTools) {
+        if (seen.has(def.name)) continue;
+        resolved.push(def);
+        seen.add(def.name);
       }
     }
+    if (resolved.length > 0) {
+      options.tools = resolved;
+      options.toolChoice = "auto";
+    }
     return options;
   }
+  // ── Skill resolution helpers ─────────────────────────────────
+  /**
+   * Resolve the set of skills active for a given agent in a given
+   * context. Combines:
+   *
+   * 1. The agent's declared `skills[]` whitelist (if any).
+   * 2. Filtering by `triggerConditions` against the runtime context.
+   *
+   * When the agent declares no skills, returns the empty list (i.e.
+   * the agent only uses its inline `tools[]`).
+   *
+   * Returns an empty array if no SkillRegistry was provided to the
+   * runtime (legacy mode).
+   */
+  async resolveActiveSkills(agent, context) {
+    if (!this.skillRegistry) return [];
+    if (!agent.skills || agent.skills.length === 0) return [];
+    return this.skillRegistry.listActiveSkills(context ?? {}, agent.skills);
+  }
+  /**
+   * Pick a default agent for the given context, used by the ambient
+   * chat endpoint when the client doesn't specify an `agentName`.
+   *
+   * Resolution order:
+   * 1. The `defaultAgent` of the app named by `context.appName`.
+   * 2. The first active agent in the registry (deterministic fallback).
+   * 3. `undefined` if no agents are registered.
+   */
+  async resolveDefaultAgent(context) {
+    if (context?.appName) {
+      const rawApp = await this.metadataService.get("app", context.appName).catch(() => void 0);
+      const defaultAgentName = rawApp?.defaultAgent;
+      if (defaultAgentName) {
+        const agent = await this.loadAgent(defaultAgentName);
+        if (agent && agent.active !== false) return agent;
+      }
+    }
+    const summaries = await this.listAgents();
+    if (summaries.length === 0) return void 0;
+    return this.loadAgent(summaries[0].name);
+  }
+};
+
+// src/skill-registry.ts
+var import_ai8 = require("@objectstack/spec/ai");
+var SkillRegistry = class {
+  constructor(metadataService) {
+    this.metadataService = metadataService;
+  }
+  // ── Loading ────────────────────────────────────────────────────
+  /**
+   * Load and validate a single skill definition by name.
+   *
+   * Returns `undefined` when the skill is missing or fails Zod
+   * validation (so callers don't accidentally feed malformed metadata
+   * to the LLM).
+   */
+  async loadSkill(skillName) {
+    const raw = await this.metadataService.get("skill", skillName);
+    if (!raw) return void 0;
+    const result = import_ai8.SkillSchema.safeParse(raw);
+    if (!result.success) return void 0;
+    return result.data;
+  }
+  /**
+   * Load all skill definitions, dropping any that fail validation
+   * or are explicitly inactive.
+   */
+  async listSkills() {
+    const raw = await this.metadataService.list("skill");
+    const skills = [];
+    for (const item of raw) {
+      const result = import_ai8.SkillSchema.safeParse(item);
+      if (result.success && result.data.active !== false) {
+        skills.push(result.data);
+      }
+    }
+    return skills;
+  }
+  /**
+   * Load only the skills referenced by `skillNames`, preserving
+   * declaration order. Missing or invalid skill names are silently
+   * dropped (logged at the route layer if needed) so an Agent can be
+   * defined before all its skills are persisted.
+   */
+  async loadSkills(skillNames) {
+    const skills = [];
+    for (const name of skillNames) {
+      const skill = await this.loadSkill(name);
+      if (skill && skill.active !== false) {
+        skills.push(skill);
+      }
+    }
+    return skills;
+  }
+  // ── Context filtering ──────────────────────────────────────────
+  /**
+   * Return skills whose `triggerConditions` are satisfied by the
+   * given context. Skills without any conditions are always considered
+   * active and returned in their declaration order.
+   *
+   * If `restrictTo` is provided, the result is intersected with that
+   * allow-list (typically the agent's `skills[]` field) so an agent
+   * never sees skills outside its declared scope.
+   */
+  async listActiveSkills(context = {}, restrictTo) {
+    const allowList = restrictTo ? new Set(restrictTo) : void 0;
+    const all = await this.listSkills();
+    return all.filter((skill) => {
+      if (allowList && !allowList.has(skill.name)) return false;
+      return this.matchesContext(skill, context);
+    });
+  }
+  /**
+   * Evaluate a skill's `triggerConditions` against the given context.
+   *
+   * Semantics:
+   * - No conditions defined → always matches.
+   * - All conditions must pass (logical AND).
+   * - Operators: `eq`, `neq`, `in`, `not_in`, `contains`.
+   * - `contains` does substring matching for strings and `Array.includes`
+   *   for arrays.
+   * - Missing context fields fail unless the operator is `neq` /
+   *   `not_in` (treating "absent" as "not equal to anything").
+   */
+  matchesContext(skill, context) {
+    const conditions = skill.triggerConditions;
+    if (!conditions || conditions.length === 0) return true;
+    return conditions.every((cond) => this.evaluateCondition(cond, context));
+  }
+  evaluateCondition(cond, context) {
+    const fieldValue = context[cond.field];
+    const expected = cond.value;
+    switch (cond.operator) {
+      case "eq":
+        return fieldValue === expected;
+      case "neq":
+        return fieldValue !== expected;
+      case "in": {
+        const list = Array.isArray(expected) ? expected : [expected];
+        return list.includes(fieldValue);
+      }
+      case "not_in": {
+        const list = Array.isArray(expected) ? expected : [expected];
+        return !list.includes(fieldValue);
+      }
+      case "contains": {
+        if (typeof fieldValue === "string" && typeof expected === "string") {
+          return fieldValue.includes(expected);
+        }
+        if (Array.isArray(fieldValue)) {
+          return Array.isArray(expected) ? expected.every((v) => fieldValue.includes(v)) : fieldValue.includes(expected);
+        }
+        return false;
+      }
+      default:
+        return false;
+    }
+  }
+  // ── Tool resolution ───────────────────────────────────────────
+  /**
+   * Flatten a list of skills to a deduplicated array of concrete tool
+   * definitions, preserving the order skills declared their tools.
+   *
+   * Tools that are declared by a skill but missing from the available
+   * tool registry are silently dropped — this is intentional so a skill
+   * can be authored before all its underlying tools are registered.
+   */
+  flattenToTools(skills, availableTools) {
+    const toolMap = new Map(availableTools.map((t) => [t.name, t]));
+    const seen = /* @__PURE__ */ new Set();
+    const resolved = [];
+    for (const skill of skills) {
+      for (const toolName of skill.tools) {
+        if (seen.has(toolName)) continue;
+        const def = toolMap.get(toolName);
+        if (def) {
+          resolved.push(def);
+          seen.add(toolName);
+        }
+      }
+    }
+    return resolved;
+  }
+  // ── System-prompt composition ─────────────────────────────────
+  /**
+   * Build the "Active Skills" block to append to an agent's system
+   * prompt. The block lists each skill's label + instructions so the
+   * LLM knows which capabilities are available and how to invoke them.
+   *
+   * Returns an empty string when there are no skills, so the caller
+   * can safely concatenate without producing dangling whitespace.
+   */
+  composeInstructionsBlock(skills) {
+    if (skills.length === 0) return "";
+    const lines = ["", "--- Active Skills ---"];
+    for (const skill of skills) {
+      lines.push(`
+### ${skill.label} (${skill.name})`);
+      if (skill.description) lines.push(skill.description);
+      if (skill.instructions) lines.push(skill.instructions);
+      if (skill.tools.length > 0) {
+        lines.push(`Tools: ${skill.tools.join(", ")}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Project a skill to a wire-friendly summary suitable for the
+   * `/api/v1/ai/skills` endpoint and slash-command palettes.
+   */
+  toSummary(skill) {
+    return {
+      name: skill.name,
+      label: skill.label,
+      description: skill.description,
+      triggerPhrases: skill.triggerPhrases,
+      toolCount: skill.tools.length
+    };
+  }
 };
 
 // src/agents/data-chat-agent.ts
@@ -2348,34 +2908,15 @@ var DATA_CHAT_AGENT = {
   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.`,
+Always answer in the same language the user is using. Detailed tool-usage guidance is supplied by the skills attached to this agent.`,
   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" }
-  ],
+  // Capability bundle lives on the skill; the agent only references it.
+  skills: ["data_explorer"],
   active: true,
   visibility: "global",
   guardrails: {
@@ -2403,39 +2944,15 @@ var METADATA_ASSISTANT_AGENT = {
   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_objects to check if a similar one already exists.
-2. Before modifying or deleting fields, use describe_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.`,
+Always answer in the same language the user is using. If the user's request is ambiguous, ask clarifying questions before proceeding. Detailed tool-usage guidance is supplied by the skills attached to this agent.`,
   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_objects", description: "List all data objects" },
-    { type: "query", name: "describe_object", description: "Describe an object schema" }
-  ],
+  // Capability bundle lives on the skill; the agent only references it.
+  skills: ["metadata_authoring"],
   active: true,
   visibility: "global",
   guardrails: {
@@ -2456,8 +2973,100 @@ Guidelines:
   }
 };
 
+// src/skills/data-explorer-skill.ts
+var DATA_EXPLORER_SKILL = {
+  name: "data_explorer",
+  label: "Data Explorer",
+  description: "Read-only Q&A over the user's business data \u2014 schema discovery, filtered queries, lookups, and aggregations.",
+  instructions: `You can explore the user's business data through these tools.
+
+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.`,
+  tools: [
+    "list_objects",
+    "describe_object",
+    "query_records",
+    "get_record",
+    "aggregate_data"
+  ],
+  triggerPhrases: [
+    "show me",
+    "list",
+    "how many",
+    "count",
+    "find records",
+    "query",
+    "aggregate",
+    "sum",
+    "average"
+  ],
+  active: true
+};
+
+// src/skills/metadata-authoring-skill.ts
+var METADATA_AUTHORING_SKILL = {
+  name: "metadata_authoring",
+  label: "Metadata Authoring",
+  description: "Create and modify ObjectStack metadata \u2014 objects, fields, schema changes through natural language.",
+  instructions: `You are an expert metadata architect. When the user asks you to design or change a data model, use these tools.
+
+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_objects to check if a similar one already exists.
+2. Before modifying or deleting fields, use describe_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.`,
+  tools: [
+    "create_object",
+    "add_field",
+    "modify_field",
+    "delete_field",
+    "list_objects",
+    "describe_object"
+  ],
+  triggerPhrases: [
+    "create object",
+    "create table",
+    "add field",
+    "add column",
+    "modify field",
+    "change field",
+    "delete field",
+    "drop field",
+    "design schema",
+    "new entity"
+  ],
+  active: true
+};
+
 // src/adapters/vercel-adapter.ts
-var import_ai8 = require("ai");
+var import_ai9 = require("ai");
 function buildVercelOptions(options) {
   if (!options) return {};
   const opts = {};
@@ -2467,9 +3076,9 @@ function buildVercelOptions(options) {
   if (options.tools?.length) {
     const tools = {};
     for (const t of options.tools) {
-      tools[t.name] = (0, import_ai8.tool)({
+      tools[t.name] = (0, import_ai9.tool)({
         description: t.description,
-        inputSchema: (0, import_ai8.jsonSchema)(t.parameters)
+        inputSchema: (0, import_ai9.jsonSchema)(t.parameters)
       });
     }
     opts.tools = tools;
@@ -2485,7 +3094,7 @@ var VercelLLMAdapter = class {
     this.model = config.model;
   }
   async chat(messages, options) {
-    const result = await (0, import_ai8.generateText)({
+    const result = await (0, import_ai9.generateText)({
       model: this.model,
       messages,
       ...buildVercelOptions(options)
@@ -2502,7 +3111,7 @@ var VercelLLMAdapter = class {
     };
   }
   async complete(prompt, options) {
-    const result = await (0, import_ai8.generateText)({
+    const result = await (0, import_ai9.generateText)({
       model: this.model,
       prompt,
       ...buildVercelOptions(options)
@@ -2518,13 +3127,20 @@ var VercelLLMAdapter = class {
     };
   }
   async *streamChat(messages, options) {
-    const result = (0, import_ai8.streamText)({
+    const result = (0, import_ai9.streamText)({
       model: this.model,
       messages,
       ...buildVercelOptions(options)
     });
-    for await (const part of result.fullStream) {
-      yield part;
+    try {
+      for await (const part of result.fullStream) {
+        yield part;
+      }
+    } catch (err) {
+      yield {
+        type: "error",
+        error: err instanceof Error ? err : new Error(String(err))
+      };
     }
   }
   async embed(_input) {
@@ -2606,11 +3222,14 @@ var AIServicePlugin = class {
             /* webpackIgnore: true */
             pkg
           );
-          const createModel = mod[factory] ?? mod.default;
-          if (typeof createModel === "function") {
+          const provider = mod[factory] ?? mod.default;
+          if (typeof provider === "function") {
             const modelId = process.env.AI_MODEL ?? defaultModel;
-            const adapter = new VercelLLMAdapter({ model: createModel(modelId) });
-            return { adapter, description: `${displayName} (model: ${modelId})` };
+            const useChatApi = factory === "openai" && typeof provider.chat === "function";
+            const model = useChatApi ? provider.chat(modelId) : provider(modelId);
+            const adapter = new VercelLLMAdapter({ model });
+            const apiSuffix = useChatApi ? " [chat-completions]" : "";
+            return { adapter, description: `${displayName} (model: ${modelId})${apiSuffix}` };
           }
         } catch (err) {
           ctx.logger.warn(
@@ -2671,6 +3290,7 @@ var AIServicePlugin = class {
       name: "AI Service",
       version: "1.0.0",
       type: "plugin",
+      scope: "project",
       namespace: "ai",
       objects: [AiConversationObject, AiMessageObject]
     });
@@ -2679,25 +3299,12 @@ 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: "Conversations", objectName: "conversations", icon: "message-square", order: 10 },
-            { id: "nav_ai_messages", type: "object", label: "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;
+    const withTimeout = (promise, ms = 2e3) => Promise.race([promise, new Promise((resolve) => setTimeout(() => resolve(null), ms))]);
     try {
       metadataService = ctx.getService("metadata");
       console.log("[AI Plugin] Retrieved metadata service:", !!metadataService, "has getRegisteredTypes:", typeof metadataService?.getRegisteredTypes);
@@ -2705,6 +3312,13 @@ var AIServicePlugin = class {
       console.log("[AI] Metadata service not available:", e.message);
       ctx.logger.debug("[AI] Metadata service not available");
     }
+    if (metadataService && typeof metadataService.exists === "function") {
+      const probeResult = await withTimeout(metadataService.exists("tool", "__probe__"), 3e3);
+      if (probeResult === null) {
+        ctx.logger.warn("[AI] Metadata service unreachable (timed out) \u2014 AI tools/agents will work but Studio visibility unavailable");
+        metadataService = void 0;
+      }
+    }
     try {
       const dataEngine = ctx.getService("data");
       if (dataEngine) {
@@ -2713,18 +3327,31 @@ var AIServicePlugin = class {
         if (metadataService) {
           const { DATA_TOOL_DEFINITIONS: DATA_TOOL_DEFINITIONS2 } = await Promise.resolve().then(() => (init_data_tools(), data_tools_exports));
           for (const toolDef of DATA_TOOL_DEFINITIONS2) {
-            const toolExists = typeof metadataService.exists === "function" ? await metadataService.exists("tool", toolDef.name) : false;
+            const toolExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("tool", toolDef.name)) : false;
+            if (toolExists === null) {
+              ctx.logger.warn("[AI] Metadata service timed out checking tool existence (non-fatal), skipping persistence");
+              break;
+            }
             if (!toolExists) {
-              await metadataService.register("tool", toolDef.name, toolDef);
+              try {
+                await withTimeout(metadataService.register("tool", toolDef.name, toolDef));
+              } catch (err) {
+                ctx.logger.warn(
+                  "[AI] Failed to persist tool metadata (non-fatal)",
+                  err instanceof Error ? { tool: toolDef.name, error: err.message } : { tool: toolDef.name }
+                );
+              }
             }
           }
           ctx.logger.info(`[AI] ${DATA_TOOL_DEFINITIONS2.length} data tools registered as metadata`);
         }
         if (metadataService) {
           try {
-            const agentExists = typeof metadataService.exists === "function" ? await metadataService.exists("agent", DATA_CHAT_AGENT.name) : false;
-            if (!agentExists) {
-              await metadataService.register("agent", DATA_CHAT_AGENT.name, DATA_CHAT_AGENT);
+            const agentExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("agent", DATA_CHAT_AGENT.name)) : false;
+            if (agentExists === null) {
+              ctx.logger.warn("[AI] Metadata service timed out checking data_chat agent, skipping");
+            } else if (!agentExists) {
+              await withTimeout(metadataService.register("agent", DATA_CHAT_AGENT.name, DATA_CHAT_AGENT));
               console.log("[AI] Registered data_chat agent to metadataService");
               ctx.logger.info("[AI] data_chat agent registered");
             } else {
@@ -2734,6 +3361,19 @@ var AIServicePlugin = class {
           } catch (err) {
             ctx.logger.warn("[AI] Failed to register data_chat agent", err instanceof Error ? { error: err.message, stack: err.stack } : { error: String(err) });
           }
+          try {
+            const skillExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("skill", DATA_EXPLORER_SKILL.name)) : false;
+            if (skillExists === null) {
+              ctx.logger.warn("[AI] Metadata service timed out checking data_explorer skill, skipping");
+            } else if (!skillExists) {
+              await withTimeout(metadataService.register("skill", DATA_EXPLORER_SKILL.name, DATA_EXPLORER_SKILL));
+              ctx.logger.info("[AI] data_explorer skill registered");
+            } else {
+              ctx.logger.debug("[AI] data_explorer skill already exists, skipping auto-registration");
+            }
+          } catch (err) {
+            ctx.logger.warn("[AI] Failed to register data_explorer skill", err instanceof Error ? { error: err.message } : { error: String(err) });
+          }
         }
       }
     } catch {
@@ -2745,16 +3385,29 @@ var AIServicePlugin = class {
         ctx.logger.info("[AI] Built-in metadata tools registered");
         const { METADATA_TOOL_DEFINITIONS: METADATA_TOOL_DEFINITIONS2 } = await Promise.resolve().then(() => (init_metadata_tools(), metadata_tools_exports));
         for (const toolDef of METADATA_TOOL_DEFINITIONS2) {
-          const toolExists = typeof metadataService.exists === "function" ? await metadataService.exists("tool", toolDef.name) : false;
+          const toolExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("tool", toolDef.name)) : false;
+          if (toolExists === null) {
+            ctx.logger.warn("[AI] Metadata service timed out checking tool existence (non-fatal), skipping persistence");
+            break;
+          }
           if (!toolExists) {
-            await metadataService.register("tool", toolDef.name, toolDef);
+            try {
+              await withTimeout(metadataService.register("tool", toolDef.name, toolDef));
+            } catch (err) {
+              ctx.logger.warn(
+                "[AI] Failed to persist tool metadata (non-fatal)",
+                err instanceof Error ? { tool: toolDef.name, error: err.message } : { tool: toolDef.name }
+              );
+            }
           }
         }
         ctx.logger.info(`[AI] ${METADATA_TOOL_DEFINITIONS2.length} metadata tools registered as metadata`);
         try {
-          const agentExists = typeof metadataService.exists === "function" ? await metadataService.exists("agent", METADATA_ASSISTANT_AGENT.name) : false;
-          if (!agentExists) {
-            await metadataService.register("agent", METADATA_ASSISTANT_AGENT.name, METADATA_ASSISTANT_AGENT);
+          const agentExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("agent", METADATA_ASSISTANT_AGENT.name)) : false;
+          if (agentExists === null) {
+            ctx.logger.warn("[AI] Metadata service timed out checking metadata_assistant agent, skipping");
+          } else if (!agentExists) {
+            await withTimeout(metadataService.register("agent", METADATA_ASSISTANT_AGENT.name, METADATA_ASSISTANT_AGENT));
             console.log("[AI] Registered metadata_assistant agent to metadataService");
             ctx.logger.info("[AI] metadata_assistant agent registered");
           } else {
@@ -2764,22 +3417,71 @@ var AIServicePlugin = class {
         } catch (err) {
           ctx.logger.warn("[AI] Failed to register metadata_assistant agent", err instanceof Error ? { error: err.message, stack: err.stack } : { error: String(err) });
         }
+        try {
+          const skillExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("skill", METADATA_AUTHORING_SKILL.name)) : false;
+          if (skillExists === null) {
+            ctx.logger.warn("[AI] Metadata service timed out checking metadata_authoring skill, skipping");
+          } else if (!skillExists) {
+            await withTimeout(metadataService.register("skill", METADATA_AUTHORING_SKILL.name, METADATA_AUTHORING_SKILL));
+            ctx.logger.info("[AI] metadata_authoring skill registered");
+          } else {
+            ctx.logger.debug("[AI] metadata_authoring skill already exists, skipping auto-registration");
+          }
+        } catch (err) {
+          ctx.logger.warn("[AI] Failed to register metadata_authoring skill", err instanceof Error ? { error: err.message } : { error: String(err) });
+        }
       } catch (err) {
         ctx.logger.debug("[AI] Failed to register metadata tools", err instanceof Error ? err : void 0);
       }
     }
     await ctx.trigger("ai:ready", this.service);
+    if (metadataService) {
+      try {
+        const objectql = ctx.getService("objectql");
+        const registry = objectql?.registry;
+        if (registry && typeof registry.listItems === "function") {
+          const stackAgents = registry.listItems("agent");
+          let bridged = 0;
+          for (const entry of stackAgents) {
+            const agent = entry?.content ?? entry;
+            const agentName = agent?.name;
+            if (!agentName || typeof agentName !== "string") continue;
+            const exists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("agent", agentName)) : false;
+            if (exists === true) continue;
+            try {
+              await withTimeout(metadataService.register("agent", agentName, agent));
+              bridged++;
+            } catch (err) {
+              ctx.logger.warn(
+                "[AI] Failed to bridge stack agent into metadata service (non-fatal)",
+                err instanceof Error ? { agent: agentName, error: err.message } : { agent: agentName }
+              );
+            }
+          }
+          if (bridged > 0) {
+            ctx.logger.info(`[AI] Bridged ${bridged} stack-defined agent(s) from ObjectQL registry`);
+            console.log(`[AI] Bridged ${bridged} stack-defined agent(s) from ObjectQL registry`);
+          }
+        }
+      } catch (err) {
+        ctx.logger.debug("[AI] ObjectQL registry not available, skipping agent bridge", err instanceof Error ? err : void 0);
+      }
+    }
     const routes = buildAIRoutes(this.service, this.service.conversationService, ctx.logger);
     const toolRoutes = buildToolRoutes(this.service, ctx.logger);
     routes.push(...toolRoutes);
     ctx.logger.info(`[AI] Tool routes registered (${toolRoutes.length} routes)`);
     if (metadataService) {
-      const agentRuntime = new AgentRuntime(metadataService);
+      const skillRegistry = new SkillRegistry(metadataService);
+      const agentRuntime = new AgentRuntime(metadataService, skillRegistry);
       const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
       routes.push(...agentRoutes);
       ctx.logger.info(`[AI] Agent routes registered (${agentRoutes.length} routes)`);
+      const assistantRoutes = buildAssistantRoutes(this.service, agentRuntime, skillRegistry, ctx.logger);
+      routes.push(...assistantRoutes);
+      ctx.logger.info(`[AI] Assistant (ambient) routes registered (${assistantRoutes.length} routes)`);
     } else {
-      ctx.logger.debug("[AI] Metadata service not available, skipping agent routes");
+      ctx.logger.debug("[AI] Metadata service not available, skipping agent and assistant routes");
     }
     await ctx.trigger("ai:routes", routes);
     const kernel = ctx.getKernel();
@@ -2799,6 +3501,337 @@ var AIServicePlugin = class {
 init_data_tools();
 init_metadata_tools();
 init_metadata_tools();
+
+// src/tools/list-packages.tool.ts
+var import_ai10 = require("@objectstack/spec/ai");
+var listPackagesTool = (0, import_ai10.defineTool)({
+  name: "list_packages",
+  label: "List Packages",
+  description: "Lists all installed packages in the system. Use this to see what packages are available before creating or modifying metadata. Packages are the containers that hold metadata.",
+  category: "utility",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        description: "Filter by package status",
+        enum: ["installed", "disabled", "installing", "upgrading", "uninstalling", "error"]
+      },
+      enabled: {
+        type: "boolean",
+        description: "Filter by enabled state (true = only enabled, false = only disabled)"
+      }
+    },
+    additionalProperties: false
+  }
+});
+
+// src/tools/get-package.tool.ts
+var import_ai11 = require("@objectstack/spec/ai");
+var getPackageTool = (0, import_ai11.defineTool)({
+  name: "get_package",
+  label: "Get Package",
+  description: "Gets detailed information about a specific installed package, including its manifest, metadata, and installation status.",
+  category: "utility",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      packageId: {
+        type: "string",
+        description: "Package identifier (reverse domain notation, e.g., com.acme.crm)"
+      }
+    },
+    required: ["packageId"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/create-package.tool.ts
+var import_ai12 = require("@objectstack/spec/ai");
+var createPackageTool = (0, import_ai12.defineTool)({
+  name: "create_package",
+  label: "Create Package",
+  description: "Creates a new package (metadata container) with the specified manifest. All metadata in ObjectStack should belong to a package. Use this when starting new development or when the user wants to organize their metadata into a new module.",
+  category: "utility",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      id: {
+        type: "string",
+        description: "Package identifier in reverse domain notation (e.g., com.acme.crm, org.mycompany.sales)"
+      },
+      name: {
+        type: "string",
+        description: 'Human-readable package name (e.g., "CRM Application", "Sales Module")'
+      },
+      version: {
+        type: "string",
+        description: 'Semantic version (e.g., "1.0.0")',
+        default: "1.0.0"
+      },
+      description: {
+        type: "string",
+        description: "Brief description of what this package provides"
+      },
+      namespace: {
+        type: "string",
+        description: "Namespace prefix for metadata (snake_case, e.g., crm, sales). If not provided, derived from package ID."
+      },
+      type: {
+        type: "string",
+        description: "Package type",
+        enum: ["application", "plugin", "library", "template"],
+        default: "application"
+      }
+    },
+    required: ["id", "name"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/get-active-package.tool.ts
+var import_ai13 = require("@objectstack/spec/ai");
+var getActivePackageTool = (0, import_ai13.defineTool)({
+  name: "get_active_package",
+  label: "Get Active Package",
+  description: "Gets the currently active package in this conversation. The active package determines where new metadata will be created. Returns null if no package is set.",
+  category: "utility",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {},
+    additionalProperties: false
+  }
+});
+
+// src/tools/set-active-package.tool.ts
+var import_ai14 = require("@objectstack/spec/ai");
+var setActivePackageTool = (0, import_ai14.defineTool)({
+  name: "set_active_package",
+  label: "Set Active Package",
+  description: "Sets the active package for this conversation. All subsequent metadata creation operations (objects, views, flows, etc.) will be associated with this package unless explicitly overridden.",
+  category: "utility",
+  builtIn: true,
+  parameters: {
+    type: "object",
+    properties: {
+      packageId: {
+        type: "string",
+        description: "Package identifier to set as active (e.g., com.acme.crm)"
+      }
+    },
+    required: ["packageId"],
+    additionalProperties: false
+  }
+});
+
+// src/tools/package-tools.ts
+var PACKAGE_TOOL_DEFINITIONS = [
+  listPackagesTool,
+  getPackageTool,
+  createPackageTool,
+  getActivePackageTool,
+  setActivePackageTool
+];
+var REVERSE_DOMAIN_RE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/;
+var SNAKE_CASE_RE2 = /^[a-z_][a-z0-9_]*$/;
+var SEMVER_RE = /^\d+\.\d+\.\d+(-[a-z0-9]+(\.[a-z0-9]+)*)?$/;
+function isReverseDomain(value) {
+  return REVERSE_DOMAIN_RE.test(value);
+}
+function isSnakeCase2(value) {
+  return SNAKE_CASE_RE2.test(value);
+}
+function isSemVer(value) {
+  return SEMVER_RE.test(value);
+}
+function deriveNamespace(packageId) {
+  const parts = packageId.split(".");
+  return parts[parts.length - 1];
+}
+function createListPackagesHandler(ctx) {
+  return async (args) => {
+    const { status, enabled } = args ?? {};
+    const filter = {};
+    if (status) filter.status = status;
+    if (enabled !== void 0) filter.enabled = enabled;
+    const packages = await ctx.packageRegistry.list(filter);
+    const result = packages.map((pkg) => ({
+      id: pkg.manifest.id,
+      name: pkg.manifest.name,
+      version: pkg.manifest.version,
+      type: pkg.manifest.type,
+      status: pkg.status,
+      enabled: pkg.enabled,
+      installedAt: pkg.installedAt,
+      description: pkg.manifest.description
+    }));
+    return JSON.stringify({
+      packages: result,
+      total: result.length
+    });
+  };
+}
+function createGetPackageHandler(ctx) {
+  return async (args) => {
+    const { packageId } = args;
+    if (!packageId) {
+      return JSON.stringify({ error: "packageId is required" });
+    }
+    const pkg = await ctx.packageRegistry.get(packageId);
+    if (!pkg) {
+      return JSON.stringify({ error: `Package "${packageId}" not found` });
+    }
+    return JSON.stringify({
+      id: pkg.manifest.id,
+      name: pkg.manifest.name,
+      version: pkg.manifest.version,
+      type: pkg.manifest.type,
+      status: pkg.status,
+      enabled: pkg.enabled,
+      installedAt: pkg.installedAt,
+      updatedAt: pkg.updatedAt,
+      description: pkg.manifest.description,
+      namespace: pkg.manifest.namespace,
+      dependencies: pkg.manifest.dependencies,
+      registeredNamespaces: pkg.registeredNamespaces
+    });
+  };
+}
+function createCreatePackageHandler(ctx) {
+  return async (args) => {
+    const { id, name, version = "1.0.0", description, namespace, type = "application" } = args;
+    if (!id || !name) {
+      return JSON.stringify({ error: 'Both "id" and "name" are required' });
+    }
+    if (!isReverseDomain(id)) {
+      return JSON.stringify({
+        error: `Invalid package ID "${id}". Must be in reverse domain notation (e.g., com.acme.crm, org.mycompany.sales)`
+      });
+    }
+    if (!isSemVer(version)) {
+      return JSON.stringify({
+        error: `Invalid version "${version}". Must be semantic version (e.g., 1.0.0, 2.1.3-beta)`
+      });
+    }
+    const exists = await ctx.packageRegistry.exists(id);
+    if (exists) {
+      return JSON.stringify({ error: `Package "${id}" already exists` });
+    }
+    const derivedNamespace = namespace || deriveNamespace(id);
+    if (!isSnakeCase2(derivedNamespace)) {
+      return JSON.stringify({
+        error: `Invalid namespace "${derivedNamespace}". Must be snake_case (e.g., crm, sales_module)`
+      });
+    }
+    const manifest = {
+      id,
+      name,
+      version,
+      type,
+      namespace: derivedNamespace,
+      ...description ? { description } : {}
+    };
+    const installedPackage = await ctx.packageRegistry.install(manifest);
+    if (ctx.conversationService && ctx.conversationId) {
+      try {
+        await ctx.conversationService.updateMetadata?.(ctx.conversationId, {
+          activePackageId: id
+        });
+      } catch (err) {
+        console.warn("Failed to set active package in conversation:", err);
+      }
+    }
+    return JSON.stringify({
+      packageId: installedPackage.manifest.id,
+      name: installedPackage.manifest.name,
+      version: installedPackage.manifest.version,
+      namespace: installedPackage.manifest.namespace,
+      status: installedPackage.status,
+      message: `Package "${name}" created successfully and set as active package`
+    });
+  };
+}
+function createGetActivePackageHandler(ctx) {
+  return async () => {
+    if (!ctx.conversationService || !ctx.conversationId) {
+      return JSON.stringify({
+        activePackageId: null,
+        message: "No conversation context available to track active package"
+      });
+    }
+    try {
+      const metadata = await ctx.conversationService.getMetadata?.(ctx.conversationId);
+      const activePackageId = metadata?.activePackageId;
+      if (!activePackageId) {
+        return JSON.stringify({
+          activePackageId: null,
+          message: "No active package set. Use set_active_package or create a new package."
+        });
+      }
+      const pkg = await ctx.packageRegistry.get(activePackageId);
+      if (!pkg) {
+        return JSON.stringify({
+          activePackageId,
+          error: `Active package "${activePackageId}" not found. It may have been uninstalled.`
+        });
+      }
+      return JSON.stringify({
+        activePackageId: pkg.manifest.id,
+        name: pkg.manifest.name,
+        version: pkg.manifest.version,
+        namespace: pkg.manifest.namespace,
+        type: pkg.manifest.type
+      });
+    } catch (err) {
+      return JSON.stringify({
+        error: `Failed to get active package: ${err.message}`
+      });
+    }
+  };
+}
+function createSetActivePackageHandler(ctx) {
+  return async (args) => {
+    const { packageId } = args;
+    if (!packageId) {
+      return JSON.stringify({ error: "packageId is required" });
+    }
+    const pkg = await ctx.packageRegistry.get(packageId);
+    if (!pkg) {
+      return JSON.stringify({ error: `Package "${packageId}" not found` });
+    }
+    if (!ctx.conversationService || !ctx.conversationId) {
+      return JSON.stringify({
+        error: "No conversation context available. Cannot set active package."
+      });
+    }
+    try {
+      await ctx.conversationService.updateMetadata?.(ctx.conversationId, {
+        activePackageId: packageId
+      });
+      return JSON.stringify({
+        activePackageId: packageId,
+        name: pkg.manifest.name,
+        namespace: pkg.manifest.namespace,
+        message: `Active package set to "${pkg.manifest.name}"`
+      });
+    } catch (err) {
+      return JSON.stringify({
+        error: `Failed to set active package: ${err.message}`
+      });
+    }
+  };
+}
+function registerPackageTools(registry, context) {
+  registry.register(listPackagesTool, createListPackagesHandler(context));
+  registry.register(getPackageTool, createGetPackageHandler(context));
+  registry.register(createPackageTool, createCreatePackageHandler(context));
+  registry.register(getActivePackageTool, createGetActivePackageHandler(context));
+  registry.register(setActivePackageTool, createSetActivePackageHandler(context));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AIService,
@@ -2813,20 +3846,29 @@ init_metadata_tools();
   METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter,
   ObjectQLConversationService,
+  PACKAGE_TOOL_DEFINITIONS,
+  SkillRegistry,
   ToolRegistry,
   VercelLLMAdapter,
   addFieldTool,
   buildAIRoutes,
   buildAgentRoutes,
+  buildAssistantRoutes,
   buildToolRoutes,
   createObjectTool,
+  createPackageTool,
   deleteFieldTool,
   describeObjectTool,
   encodeStreamPart,
   encodeVercelDataStream,
+  getActivePackageTool,
+  getPackageTool,
   listObjectsTool,
+  listPackagesTool,
   modifyFieldTool,
   registerDataTools,
-  registerMetadataTools
+  registerMetadataTools,
+  registerPackageTools,
+  setActivePackageTool
 });
 //# sourceMappingURL=index.cjs.map