@objectstack/service-ai 7.2.1 → 7.4.0

package/dist/index.cjs

@@ -5145,7 +5145,8 @@ var SchemaRetriever = class {
       if (obj.label) parts.push(obj.label);
       if (obj.pluralLabel && obj.pluralLabel !== obj.label) parts.push(`(${obj.pluralLabel})`);
       const header = parts.length > 0 ? ` \u2014 ${parts.join(" ")}` : "";
-      lines.push(`### ${obj.name}${header}`);
+      const badge = obj.external !== void 0 ? ` [external, ${obj.external?.writable ? "writable" : "read-only"}, datasource=${obj.datasource ?? "default"}]` : "";
+      lines.push(`### ${obj.name}${header}${badge}`);
       const fields = Object.entries(obj.fields ?? {}).slice(0, maxFieldsPerObject);
       for (const [name, field] of fields) {
         lines.push(`  - ${name}: ${describeField(field)}`);
@@ -5289,6 +5290,15 @@ var QUERY_DATA_TOOL = {
 function createQueryDataHandler(ctx) {
   const retriever = new SchemaRetriever(ctx.metadata, {}, ctx.protocol);
   const maxLimit = ctx.maxLimit ?? 100;
+  const externalTimeoutFallback = ctx.externalQueryTimeoutMs ?? 3e4;
+  const resolveExternalTimeout = async (datasource) => {
+    try {
+      const ds = await ctx.metadata.get?.("datasource", datasource);
+      return ds?.external?.queryTimeoutMs ?? externalTimeoutFallback;
+    } catch {
+      return externalTimeoutFallback;
+    }
+  };
   return async (args, execCtx) => {
     const { request } = args;
     if (!request || typeof request !== "string") {
@@ -5351,14 +5361,20 @@ function createQueryDataHandler(ctx) {
         });
       }
     }
+    const isExternal = matchedObject.external !== void 0;
     try {
-      const records = await ctx.dataEngine.find(plan.objectName, {
+      const findPromise = ctx.dataEngine.find(plan.objectName, {
         where,
         fields: plan.fields ?? void 0,
         orderBy: plan.orderBy ?? void 0,
         limit,
         context: buildAiEngineContext(execCtx)
       });
+      const records = isExternal ? await withTimeout(
+        findPromise,
+        await resolveExternalTimeout(matchedObject.datasource ?? "default"),
+        plan.objectName
+      ) : await findPromise;
       return JSON.stringify({
         plan: { ...plan, where },
         count: records.length,
@@ -5372,6 +5388,28 @@ function createQueryDataHandler(ctx) {
     }
   };
 }
+function withTimeout(p, ms, object) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `query on external object '${object}' exceeded the ${ms}ms timeout. Narrow the filter or lower the limit.`
+        )
+      );
+    }, ms);
+    timer.unref?.();
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
 function registerQueryDataTool(registry, context) {
   registry.register(QUERY_DATA_TOOL, createQueryDataHandler(context));
 }
@@ -5792,6 +5830,82 @@ async function registerActionsAsTools(registry, context) {
 
 // src/agent-runtime.ts
 var import_ai7 = require("@objectstack/spec/ai");
+
+// src/agents/data-chat-agent.ts
+var DEFAULT_DATA_AGENT_NAME = "data_chat";
+var DATA_CHAT_AGENT = {
+  name: DEFAULT_DATA_AGENT_NAME,
+  label: "Data Assistant",
+  role: "Business Data Analyst",
+  instructions: `You are a helpful data assistant that helps users explore and understand their business data through natural language.
+
+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
+  },
+  // Capability bundle lives on the skill; the agent only references it.
+  // `data_explorer` = read side, `actions_executor` = write side.
+  skills: ["data_explorer", "actions_executor"],
+  active: true,
+  visibility: "global",
+  guardrails: {
+    maxTokensPerInvocation: 8192,
+    maxExecutionTimeSec: 30,
+    blockedTopics: ["delete_records", "drop_table", "alter_schema"]
+  },
+  planning: {
+    strategy: "react",
+    maxIterations: 5,
+    allowReplan: false
+  },
+  memory: {
+    shortTerm: {
+      maxMessages: 20,
+      maxTokens: 4096
+    }
+  }
+};
+
+// src/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.
+
+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
+  },
+  // Capability bundle lives on the skill; the agent only references it.
+  skills: ["metadata_authoring"],
+  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/agent-runtime.ts
 var AgentRuntime = class {
   constructor(metadataService, skillRegistry) {
     this.metadataService = metadataService;
@@ -5942,9 +6056,14 @@ var AgentRuntime = class {
    * 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.
+   * 1. The `defaultAgent` of the app named by `context.appName`
+   *    (e.g. Studio → `metadata_assistant`).
+   * 2. The platform data-query agent (`data_chat`) — the implicit
+   *    copilot bound to every app that doesn't pin its own. This is
+   *    what end users get by default, so they never have to choose.
+   * 3. The first active agent in the registry (last-resort fallback,
+   *    e.g. in stripped-down deployments without the data agent).
+   * 4. `undefined` if no agents are registered.
    */
   async resolveDefaultAgent(context) {
     if (context?.appName) {
@@ -5955,6 +6074,8 @@ var AgentRuntime = class {
         if (agent && agent.active !== false) return agent;
       }
     }
+    const dataAgent = await this.loadAgent(DEFAULT_DATA_AGENT_NAME);
+    if (dataAgent && dataAgent.active !== false) return dataAgent;
     const summaries = await this.listAgents();
     if (summaries.length === 0) return void 0;
     return this.loadAgent(summaries[0].name);
@@ -6150,79 +6271,6 @@ var SkillRegistry = class {
   }
 };
 
-// src/agents/data-chat-agent.ts
-var DATA_CHAT_AGENT = {
-  name: "data_chat",
-  label: "Data Assistant",
-  role: "Business Data Analyst",
-  instructions: `You are a helpful data assistant that helps users explore and understand their business data through natural language.
-
-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
-  },
-  // Capability bundle lives on the skill; the agent only references it.
-  // `data_explorer` = read side, `actions_executor` = write side.
-  skills: ["data_explorer", "actions_executor"],
-  active: true,
-  visibility: "global",
-  guardrails: {
-    maxTokensPerInvocation: 8192,
-    maxExecutionTimeSec: 30,
-    blockedTopics: ["delete_records", "drop_table", "alter_schema"]
-  },
-  planning: {
-    strategy: "react",
-    maxIterations: 5,
-    allowReplan: false
-  },
-  memory: {
-    shortTerm: {
-      maxMessages: 20,
-      maxTokens: 4096
-    }
-  }
-};
-
-// src/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.
-
-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
-  },
-  // Capability bundle lives on the skill; the agent only references it.
-  skills: ["metadata_authoring"],
-  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/skills/data-explorer-skill.ts
 var DATA_EXPLORER_SKILL = {
   name: "data_explorer",
@@ -6897,7 +6945,7 @@ var _AIServicePlugin = class _AIServicePlugin {
   async start(ctx) {
     if (!this.service) return;
     let metadataService;
-    const withTimeout = (promise, ms = 2e3) => Promise.race([promise, new Promise((resolve) => setTimeout(() => resolve(null), ms))]);
+    const withTimeout2 = (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);
@@ -6906,7 +6954,7 @@ var _AIServicePlugin = class _AIServicePlugin {
       ctx.logger.debug("[AI] Metadata service not available");
     }
     if (metadataService && typeof metadataService.exists === "function") {
-      const probeResult = await withTimeout(metadataService.exists("tool", "__probe__"), 3e3);
+      const probeResult = await withTimeout2(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;
@@ -6978,7 +7026,7 @@ var _AIServicePlugin = class _AIServicePlugin {
         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 withTimeout(metadataService.exists("tool", toolDef.name)) : false;
+            const toolExists = typeof metadataService.exists === "function" ? await withTimeout2(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;
@@ -6986,7 +7034,7 @@ var _AIServicePlugin = class _AIServicePlugin {
             if (!toolExists) {
               try {
                 const label = toolDef.label ?? toToolLabel(toolDef.name);
-                await withTimeout(metadataService.register("tool", toolDef.name, { ...toolDef, label }));
+                await withTimeout2(metadataService.register("tool", toolDef.name, { ...toolDef, label }));
               } catch (err) {
                 ctx.logger.warn(
                   "[AI] Failed to persist tool metadata (non-fatal)",
@@ -6999,11 +7047,11 @@ var _AIServicePlugin = class _AIServicePlugin {
         }
         if (metadataService) {
           try {
-            const agentExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("agent", DATA_CHAT_AGENT.name)) : false;
+            const agentExists = typeof metadataService.exists === "function" ? await withTimeout2(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));
+              await withTimeout2(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 {
@@ -7014,11 +7062,11 @@ var _AIServicePlugin = class _AIServicePlugin {
             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;
+            const skillExists = typeof metadataService.exists === "function" ? await withTimeout2(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));
+              await withTimeout2(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");
@@ -7027,11 +7075,11 @@ var _AIServicePlugin = class _AIServicePlugin {
             ctx.logger.warn("[AI] Failed to register data_explorer skill", err instanceof Error ? { error: err.message } : { error: String(err) });
           }
           try {
-            const skillExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("skill", ACTIONS_EXECUTOR_SKILL.name)) : false;
+            const skillExists = typeof metadataService.exists === "function" ? await withTimeout2(metadataService.exists("skill", ACTIONS_EXECUTOR_SKILL.name)) : false;
             if (skillExists === null) {
               ctx.logger.warn("[AI] Metadata service timed out checking actions_executor skill, skipping");
             } else if (!skillExists) {
-              await withTimeout(metadataService.register("skill", ACTIONS_EXECUTOR_SKILL.name, ACTIONS_EXECUTOR_SKILL));
+              await withTimeout2(metadataService.register("skill", ACTIONS_EXECUTOR_SKILL.name, ACTIONS_EXECUTOR_SKILL));
               ctx.logger.info("[AI] actions_executor skill registered");
             } else {
               ctx.logger.debug("[AI] actions_executor skill already exists, skipping auto-registration");
@@ -7050,14 +7098,14 @@ var _AIServicePlugin = class _AIServicePlugin {
         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 withTimeout(metadataService.exists("tool", toolDef.name)) : false;
+          const toolExists = typeof metadataService.exists === "function" ? await withTimeout2(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) {
             try {
-              await withTimeout(metadataService.register("tool", toolDef.name, toolDef));
+              await withTimeout2(metadataService.register("tool", toolDef.name, toolDef));
             } catch (err) {
               ctx.logger.warn(
                 "[AI] Failed to persist tool metadata (non-fatal)",
@@ -7068,11 +7116,11 @@ var _AIServicePlugin = class _AIServicePlugin {
         }
         ctx.logger.info(`[AI] ${METADATA_TOOL_DEFINITIONS2.length} metadata tools registered as metadata`);
         try {
-          const agentExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("agent", METADATA_ASSISTANT_AGENT.name)) : false;
+          const agentExists = typeof metadataService.exists === "function" ? await withTimeout2(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));
+            await withTimeout2(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 {
@@ -7083,11 +7131,11 @@ var _AIServicePlugin = class _AIServicePlugin {
           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;
+          const skillExists = typeof metadataService.exists === "function" ? await withTimeout2(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));
+            await withTimeout2(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");
@@ -7111,10 +7159,10 @@ var _AIServicePlugin = class _AIServicePlugin {
             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;
+            const exists = typeof metadataService.exists === "function" ? await withTimeout2(metadataService.exists("agent", agentName)) : false;
             if (exists === true) continue;
             try {
-              await withTimeout(metadataService.register("agent", agentName, agent));
+              await withTimeout2(metadataService.register("agent", agentName, agent));
               bridged++;
             } catch (err) {
               ctx.logger.warn(