@lowdefy/build 5.2.0 → 5.3.0

package/dist/build/buildAgents.js

@@ -0,0 +1,249 @@
+/* eslint-disable no-param-reassign */ /*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import path from 'path';
+import fs from 'fs';
+import { type } from '@lowdefy/helpers';
+import { ConfigError, ConfigWarning } from '@lowdefy/errors';
+import { RESERVED_PLATFORM_TOOL_NAMES } from '@lowdefy/ai-utils';
+import countOperators from '../utils/countOperators.js';
+import createCheckDuplicateId from '../utils/createCheckDuplicateId.js';
+function detectCycles(agents) {
+    const graph = {};
+    for (const agent of agents){
+        graph[agent.agentId] = (agent.agents ?? []).map((ref)=>ref.agentId);
+    }
+    const visited = new Set();
+    const inStack = new Set();
+    function dfs(id) {
+        if (inStack.has(id)) return id;
+        if (visited.has(id)) return null;
+        visited.add(id);
+        inStack.add(id);
+        for (const neighbor of graph[id] ?? []){
+            const cycleNode = dfs(neighbor);
+            if (cycleNode !== null) return cycleNode;
+        }
+        inStack.delete(id);
+        return null;
+    }
+    for (const id of Object.keys(graph)){
+        const cycleNode = dfs(id);
+        if (cycleNode !== null) {
+            return cycleNode;
+        }
+    }
+    return null;
+}
+function buildAgents({ components, context }) {
+    if (!type.isArray(components.agents)) {
+        return components;
+    }
+    context.agentIds = new Set();
+    const checkDuplicateAgentId = createCheckDuplicateId({
+        message: 'Duplicate agentId "{{ id }}".'
+    });
+    components.agents.forEach((agent)=>{
+        const configKey = agent['~k'];
+        // Check duplicates
+        checkDuplicateAgentId({
+            id: agent.id,
+            configKey
+        });
+        // Track type usage for buildTypes validation
+        context.typeCounters.agents.increment(agent.type, configKey);
+        // Validate connectionId is provided
+        if (type.isNone(agent.connectionId)) {
+            throw new ConfigError(`Agent connectionId is not defined at "${agent.id}".`, {
+                configKey
+            });
+        }
+        // Validate connectionId references an existing connection
+        // Connections may have been renamed by buildConnections:
+        //   connection.connectionId = original id, connection.id = 'connection:' + original id
+        const connectionExists = (components.connections ?? []).some((c)=>c.id === agent.connectionId || c.connectionId === agent.connectionId);
+        if (!connectionExists) {
+            throw new ConfigError(`Agent "${agent.id}" references connectionId "${agent.connectionId}" which does not exist.`, {
+                configKey
+            });
+        }
+        // Validate model is defined
+        if (type.isNone(agent.properties?.model)) {
+            throw new ConfigError(`Agent "model" is not defined at "${agent.id}".`, {
+                configKey
+            });
+        }
+        // Normalize tool strings to objects
+        agent.tools = (agent.tools ?? []).map((tool)=>{
+            if (type.isString(tool)) {
+                return {
+                    endpointId: tool
+                };
+            }
+            return tool;
+        });
+        // Validate tools reference existing API endpoints with required tool metadata
+        agent.tools.forEach((toolConfig)=>{
+            if (RESERVED_PLATFORM_TOOL_NAMES.includes(toolConfig.endpointId)) {
+                throw new ConfigError(`Agent "${agent.id}" tool "${toolConfig.endpointId}" uses a reserved platform tool name. Reserved: ${RESERVED_PLATFORM_TOOL_NAMES.join(', ')}.`, {
+                    configKey
+                });
+            }
+            const endpoint = (components.api ?? []).find((e)=>e.id === toolConfig.endpointId || e.endpointId === toolConfig.endpointId);
+            if (!endpoint) {
+                throw new ConfigError(`Agent "${agent.id}" references tool endpoint "${toolConfig.endpointId}" which does not exist.`, {
+                    configKey
+                });
+            }
+            if (type.isNone(endpoint.description)) {
+                throw new ConfigError(`Endpoint "${toolConfig.endpointId}" is used as an agent tool but does not have a "description".`, {
+                    configKey: endpoint['~k']
+                });
+            }
+            if (type.isNone(endpoint.payloadSchema)) {
+                throw new ConfigError(`Endpoint "${toolConfig.endpointId}" is used as an agent tool but does not have a "payloadSchema".`, {
+                    configKey: endpoint['~k']
+                });
+            }
+        });
+        // Normalize MCP string shorthand to connectionId objects (same pattern as tools)
+        agent.mcp = (agent.mcp ?? []).map((mcp)=>{
+            if (type.isString(mcp)) {
+                return {
+                    connectionId: mcp
+                };
+            }
+            return mcp;
+        });
+        // Validate MCP sources
+        agent.mcp.forEach((mcpSource, index)=>{
+            if (!type.isNone(mcpSource.connectionId)) {
+                // Validate connectionId references an existing connection
+                const mcpConnectionExists = (components.connections ?? []).some((c)=>c.id === mcpSource.connectionId || c.connectionId === mcpSource.connectionId);
+                if (!mcpConnectionExists) {
+                    throw new ConfigError(`Agent "${agent.id}" "mcp" source at index ${index} references connection "${mcpSource.connectionId}" which does not exist.`, {
+                        configKey
+                    });
+                }
+            } else if (mcpSource.transport === 'stdio') {
+                if (type.isNone(mcpSource.command)) {
+                    throw new ConfigError(`Agent "${agent.id}" "mcp" source at index ${index} uses stdio transport but is missing "command".`, {
+                        configKey
+                    });
+                }
+            } else {
+                if (type.isNone(mcpSource.url)) {
+                    throw new ConfigError(`Agent "${agent.id}" "mcp" source at index ${index} is missing "url".`, {
+                        configKey
+                    });
+                }
+            }
+        });
+        // Validate hooks reference existing API endpoints
+        const hookNames = [
+            'onStart',
+            'onStepStart',
+            'onToolCallStart',
+            'onToolCallFinish',
+            'onStepFinish',
+            'onFinish'
+        ];
+        hookNames.forEach((hookName)=>{
+            (agent.hooks?.[hookName] ?? []).forEach((endpointId)=>{
+                const endpoint = (components.api ?? []).find((e)=>e.id === endpointId || e.endpointId === endpointId);
+                if (!endpoint) {
+                    throw new ConfigError(`Agent "${agent.id}" hook "${hookName}" references endpoint "${endpointId}" which does not exist.`, {
+                        configKey
+                    });
+                }
+            });
+        });
+        // Normalize sub-agent strings to objects (same pattern as tools/mcp)
+        agent.agents = (agent.agents ?? []).map((ref)=>{
+            if (type.isString(ref)) {
+                return {
+                    agentId: ref
+                };
+            }
+            return ref;
+        });
+        // Validate fileSystem basePath if present
+        if (agent.properties?.fileSystem) {
+            const basePath = agent.properties.fileSystem.basePath;
+            if (!type.isString(basePath)) {
+                throw new ConfigError(`Agent "${agent.id}" fileSystem.basePath is not a string.`, {
+                    received: basePath,
+                    configKey
+                });
+            }
+            const resolved = path.resolve(context.directories.config, basePath);
+            if (!fs.existsSync(resolved)) {
+                throw new ConfigError(`Agent "${agent.id}" fileSystem.basePath "${basePath}" does not exist.`, {
+                    configKey
+                });
+            }
+        }
+        // Rename id to internal format
+        agent.agentId = agent.id;
+        context.agentIds.add(agent.agentId);
+        agent.id = `agent:${agent.agentId}`;
+        // Count server operators in properties
+        countOperators(agent.properties ?? {}, {
+            counter: context.typeCounters.operators.server
+        });
+    });
+    // Second pass: validate sub-agent references (needs all agentIds collected)
+    components.agents.forEach((agent)=>{
+        const configKey = agent['~k'];
+        agent.agents.forEach((subAgentRef)=>{
+            // Validate sub-agent reference exists
+            if (!context.agentIds.has(subAgentRef.agentId)) {
+                throw new ConfigError(`Agent "${agent.agentId}" references sub-agent "${subAgentRef.agentId}" which does not exist.`, {
+                    configKey
+                });
+            }
+            // Reserved platform tool name guard for sub-agents
+            if (RESERVED_PLATFORM_TOOL_NAMES.includes(subAgentRef.agentId)) {
+                throw new ConfigError(`Agent "${agent.agentId}" sub-agent "${subAgentRef.agentId}" uses a reserved platform tool name. Reserved: ${RESERVED_PLATFORM_TOOL_NAMES.join(', ')}.`, {
+                    configKey
+                });
+            }
+            // Check for name collision with endpoint tools
+            const hasToolCollision = agent.tools.some((toolConfig)=>toolConfig.endpointId === subAgentRef.agentId);
+            if (hasToolCollision) {
+                throw new ConfigError(`Agent "${agent.agentId}" sub-agent "${subAgentRef.agentId}" conflicts with an endpoint tool of the same name.`, {
+                    configKey
+                });
+            }
+            // Warn if sub-agent has tools with confirm: true (unsupported in sub-agent context)
+            const subAgent = components.agents.find((a)=>a.agentId === subAgentRef.agentId);
+            const hasConfirmTools = (subAgent?.tools ?? []).some((t)=>t.confirm);
+            if (hasConfirmTools) {
+                context.handleWarning(new ConfigWarning(`Agent "${subAgentRef.agentId}" has tools with confirm: true, but tool approval is not supported in sub-agent context. Tools will auto-execute when called as a sub-agent.`, {
+                    configKey
+                }));
+            }
+        });
+    });
+    // Detect circular sub-agent references
+    const cycleNode = detectCycles(components.agents);
+    if (cycleNode !== null) {
+        const agent = components.agents.find((a)=>a.agentId === cycleNode);
+        throw new ConfigError(`Circular sub-agent reference detected involving "${cycleNode}".`, {
+            configKey: agent?.['~k']
+        });
+    }
+    return components;
+}
+export default buildAgents;

package/dist/build/buildImports/buildImportsDev.js

@@ -22,6 +22,7 @@ function getPluginPackages({ components }) {
         });
     }
     getPackages(components.types.actions);
+    getPackages(components.types.agents);
     getPackages(components.types.auth.adapters);
     getPackages(components.types.auth.callbacks);
     getPackages(components.types.auth.events);
@@ -53,6 +54,10 @@ function buildImportsDev({ components, context }) {
             pluginPackages,
             map: context.typesMap.actions
         }),
+        agents: buildImportClassDev({
+            pluginPackages,
+            map: context.typesMap.agents
+        }),
         auth: {
             adapters: buildImportClassDev({
                 pluginPackages,

package/dist/build/buildImports/buildImportsProd.js

@@ -25,6 +25,7 @@ function buildImportsProd({ components, context }) {
     const blocks = buildImportClassProd(components.types.blocks);
     return {
         actions: buildImportClassProd(components.types.actions),
+        agents: buildImportClassProd(components.types.agents),
         auth: {
             adapters: buildImportClassProd(components.types.auth.adapters),
             callbacks: buildImportClassProd(components.types.auth.callbacks),

package/dist/build/buildTypes.js

@@ -65,6 +65,7 @@ function buildTypes({ components, context }) {
     typeCounters.actions.increment('SetDarkMode');
     components.types = {
         actions: {},
+        agents: {},
         auth: {
             adapters: {},
             callbacks: {},
@@ -86,6 +87,12 @@ function buildTypes({ components, context }) {
         store: components.types.actions,
         typeClass: 'Action'
     });
+    buildTypeClass(context, {
+        counter: typeCounters.agents,
+        definitions: context.typesMap.agents,
+        store: components.types.agents,
+        typeClass: 'Agent'
+    });
     buildTypeClass(context, {
         counter: typeCounters.auth.adapters,
         definitions: context.typesMap.auth.adapters,

package/dist/build/copyAgentFileSystems.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import path from 'path';
+import fs from 'fs';
+import { copyFileOrDirectory } from '@lowdefy/node-utils';
+async function copyAgentFileSystems({ components, context }) {
+    const basePaths = [];
+    const seen = new Set();
+    for (const agent of components.agents ?? []){
+        const basePath = agent.properties?.fileSystem?.basePath;
+        if (!basePath || typeof basePath !== 'string') continue;
+        if (seen.has(basePath)) continue;
+        seen.add(basePath);
+        basePaths.push(basePath);
+    }
+    // Manifest is consumed by next.config.js to populate outputFileTracingIncludes,
+    // so the Next.js tracer bundles these directories on Vercel and standalone builds.
+    await context.writeBuildArtifact('agentFileSystems.json', JSON.stringify(basePaths));
+    if (context.directories.config === context.directories.server) return;
+    for (const basePath of basePaths){
+        const source = path.resolve(context.directories.config, basePath);
+        if (!fs.existsSync(source)) continue;
+        const dest = path.resolve(context.directories.server, basePath);
+        try {
+            await copyFileOrDirectory(source, dest);
+        } catch (err) {
+            throw new Error(`Failed to copy fileSystem basePath "${basePath}" to server directory: ${err.message}`, {
+                cause: err
+            });
+        }
+    }
+}
+export default copyAgentFileSystems;

package/dist/build/full/updateServerPackageJson.js

@@ -25,6 +25,7 @@ async function updateServerPackageJson({ components, context }) {
         });
     }
     getPackages(components.types.actions);
+    getPackages(components.types.agents);
     getPackages(components.types.auth.adapters);
     getPackages(components.types.auth.callbacks);
     getPackages(components.types.auth.events);

package/dist/build/jit/shallowBuild.js

@@ -23,6 +23,7 @@ import addKeys from '../addKeys.js';
 import buildApp from '../buildApp.js';
 import buildAuth from '../buildAuth/buildAuth.js';
 import buildConnections from '../buildConnections.js';
+import buildAgents from '../buildAgents.js';
 import buildApi from '../buildApi/buildApi.js';
 import buildLogger from '../buildLogger.js';
 import buildImports from '../buildImports/buildImports.js';
@@ -32,6 +33,7 @@ import buildModules from '../buildModules.js';
 import buildRefs from '../buildRefs/buildRefs.js';
 import buildTypes from '../buildTypes.js';
 import cleanBuildDirectory from '../cleanBuildDirectory.js';
+import copyAgentFileSystems from '../copyAgentFileSystems.js';
 import copyPublicFolder from '../copyPublicFolder.js';
 import testSchema from '../testSchema.js';
 import validateConfig from '../validateConfig.js';
@@ -39,6 +41,7 @@ import writeApp from '../writeApp.js';
 import writeAuth from '../writeAuth.js';
 import writeConfig from '../writeConfig.js';
 import writeConnections from '../writeConnections.js';
+import writeAgents from '../writeAgents.js';
 import writeApi from '../writeApi.js';
 import writeGlobal from '../writeGlobal.js';
 import writeJs from '../buildJs/writeJs.js';
@@ -146,6 +149,10 @@ async function shallowBuild(options) {
             components,
             context
         });
+        tryBuildStep(buildAgents, 'buildAgents', {
+            components,
+            context
+        });
         const { pageRegistry, sourcelessPageArtifacts } = buildShallowPages({
             components,
             context
@@ -207,6 +214,10 @@ async function shallowBuild(options) {
             components,
             context
         });
+        await writeAgents({
+            components,
+            context
+        });
         await writeConfig({
             components,
             context
@@ -265,6 +276,10 @@ async function shallowBuild(options) {
             components,
             context
         });
+        await copyAgentFileSystems({
+            components,
+            context
+        });
         return {
             components,
             pageRegistry,

package/dist/build/registerModules.js

@@ -156,6 +156,11 @@ async function resolveLocalManifest({ entry, resolvedPaths, context }) {
     validateRequiredVars(varDefs, entry.vars ?? {}, entry.id, entry.source);
     // Validate plugin dependencies against app's declared plugins
     const requiredPlugins = manifest.plugins ?? [];
+    for (const plugin of requiredPlugins){
+        if (!type.isString(plugin.version)) {
+            throw new ConfigError(`Module "${entry.id}": plugin "${plugin.name}" must declare a "version" ` + `(semver range) in module.lowdefy.yaml.`);
+        }
+    }
     const appPlugins = (context.plugins ?? []).reduce((map, p)=>map.set(p.name, p.version), new Map());
     for (const plugin of requiredPlugins){
         if (context.defaultPackageNames.has(plugin.name)) {

package/dist/build/writeAgents.js

@@ -0,0 +1,26 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type, serializer } from '@lowdefy/helpers';
+async function writeAgents({ components, context }) {
+    if (type.isNone(components.agents)) return;
+    if (!type.isArray(components.agents)) {
+        throw new Error(`Agents is not an array.`);
+    }
+    const writePromises = components.agents.map(async (agent)=>{
+        await context.writeBuildArtifact(`agents/${agent.agentId}.json`, serializer.serializeToString(agent));
+    });
+    return Promise.all(writePromises);
+}
+export default writeAgents;

package/dist/build/writePluginImports/writeAgentImports.js

@@ -0,0 +1,22 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import generateImportFile from './generateImportFile.js';
+async function writeAgentImports({ components, context }) {
+    await context.writeBuildArtifact('plugins/agents.js', generateImportFile({
+        imports: components.imports.agents,
+        importPath: 'agents'
+    }));
+}
+export default writeAgentImports;

package/dist/build/writePluginImports/writePluginImports.js

@@ -14,6 +14,7 @@
   limitations under the License.
 */ import writeActionImports from './writeActionImports.js';
 import writeActionSchemaMap from './writeActionSchemaMap.js';
+import writeAgentImports from './writeAgentImports.js';
 import writeAuthImports from './writeAuthImports.js';
 import writeBlockImports from './writeBlockImports.js';
 import writeBlockSchemaMap from './writeBlockSchemaMap.js';
@@ -31,6 +32,10 @@ async function writePluginImports({ components, context }) {
         components,
         context
     });
+    await writeAgentImports({
+        components,
+        context
+    });
     await writeAuthImports({
         components,
         context

package/dist/createContext.js

@@ -23,6 +23,7 @@ import defaultTypesMap from './defaultTypesMap.js';
 function createContext({ customTypesMap, directories, logger, refResolver, stage = 'prod' }) {
     const context = {
         defaultPackageNames: new Set(defaultPackages),
+        agentIds: new Set(),
         connectionIds: new Set(),
         directories,
         errors: [],
@@ -42,6 +43,7 @@ function createContext({ customTypesMap, directories, logger, refResolver, stage
         stage,
         typeCounters: {
             actions: createCounter(),
+            agents: createCounter(),
             auth: {
                 adapters: createCounter(),
                 callbacks: createCounter(),

package/dist/defaultPackages.js

@@ -17,6 +17,7 @@
     '@lowdefy/actions-pdf-make',
     '@lowdefy/blocks-aggrid',
     '@lowdefy/blocks-antd',
+    '@lowdefy/blocks-antd-x',
     '@lowdefy/blocks-basic',
     '@lowdefy/blocks-diff',
     '@lowdefy/blocks-echarts',
@@ -25,7 +26,13 @@
     '@lowdefy/blocks-markdown',
     '@lowdefy/blocks-qr',
     '@lowdefy/blocks-tiptap',
+    '@lowdefy/ai-utils',
+    '@lowdefy/connection-ai-gateway',
+    '@lowdefy/connection-anthropic',
     '@lowdefy/connection-axios-http',
+    '@lowdefy/connection-google',
+    '@lowdefy/connection-mcp',
+    '@lowdefy/connection-openai',
     '@lowdefy/connection-elasticsearch',
     '@lowdefy/connection-test',
     '@lowdefy/connection-google-sheets',