@lowdefy/build 5.2.0 → 5.4.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/buildApi/buildRoutine/countStepTypes.js

@@ -13,7 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ function countStepTypes(step, { typeCounters }) {
-    if (step.type === 'CallApi') {
+    if (step.type === 'CallApi' || step.type === 'ValidateSchema') {
         return;
     }
     typeCounters.requests.increment(step.type, step['~k']);

package/dist/build/buildApi/buildRoutine/setStepId.js

@@ -12,10 +12,14 @@
   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.
-*/ function setStepId(step, { endpointId }) {
+*/ const prefixByType = {
+    CallApi: 'endpoint',
+    ValidateSchema: 'validate'
+};
+function setStepId(step, { endpointId }) {
     step.stepId = step.id;
     step.endpointId = endpointId;
-    const prefix = step.type === 'CallApi' ? 'endpoint' : 'request';
+    const prefix = prefixByType[step.type] ?? 'request';
     step.id = `${prefix}:${endpointId}:${step.stepId}`;
 }
 export default setStepId;

package/dist/build/buildApi/buildRoutine/validateStep.js

@@ -69,6 +69,24 @@ function validateStep(step, { endpointId }) {
         }
         return;
     }
+    if (step.type === 'ValidateSchema') {
+        if (type.isNone(step.properties?.schema)) {
+            throw new ConfigError(`ValidateSchema step "${step.id}" at endpoint "${endpointId}" requires properties.schema.`, {
+                configKey
+            });
+        }
+        if (type.isNone(step.properties?.data)) {
+            throw new ConfigError(`ValidateSchema step "${step.id}" at endpoint "${endpointId}" requires properties.data.`, {
+                configKey
+            });
+        }
+        if (!type.isNone(step.connectionId)) {
+            throw new ConfigError(`ValidateSchema step "${step.id}" at endpoint "${endpointId}" should not have a connectionId.`, {
+                configKey
+            });
+        }
+        return;
+    }
     if (type.isUndefined(step.connectionId)) {
         throw new ConfigError(`Step connectionId missing at endpoint "${endpointId}".`, {
             configKey

package/dist/build/buildApp.js

@@ -14,6 +14,15 @@
   limitations under the License.
 */ import { execSync } from 'child_process';
 import { type } from '@lowdefy/helpers';
+function computeGitSha() {
+    const fromEnv = process.env.LOWDEFY_GIT_SHA?.trim();
+    if (fromEnv) return fromEnv;
+    try {
+        return execSync('git rev-parse HEAD').toString().trim();
+    } catch (_) {
+        return null;
+    }
+}
 function buildApp({ components }) {
     if (type.isNone(components.app)) {
         components.app = {};
@@ -30,11 +39,15 @@ function buildApp({ components }) {
     if (type.isNone(components.app.html.appendHead)) {
         components.app.html.appendHead = '';
     }
-    try {
-        components.app.git_sha = execSync('git rev-parse HEAD').toString().trim();
-    } catch (_) {
-    //pass
-    }
+    components.appMeta = {
+        slug: components.slug ?? null,
+        name: components.name ?? null,
+        version: components.version ?? null,
+        description: components.description ?? null,
+        license: components.license ?? null,
+        lowdefyVersion: components.lowdefy ?? null,
+        gitSha: computeGitSha()
+    };
     return components;
 }
 export default buildApp;

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/buildJs/writeJs.js

@@ -16,11 +16,11 @@
 async function writeJs({ context }) {
     await context.writeBuildArtifact('plugins/operators/clientJsMap.js', generateJsFile({
         map: context.jsMap.client,
-        functionPrototype: `{ actions, args, event, input, location, lowdefyGlobal, request, state, urlQuery, user }`
+        functionPrototype: `{ actions, args, event, input, location, lowdefyApp, lowdefyGlobal, request, state, urlQuery, user }`
     }));
     await context.writeBuildArtifact('plugins/operators/serverJsMap.js', generateJsFile({
         map: context.jsMap.server,
-        functionPrototype: `{ args, item, payload, secrets, state, step, user }`
+        functionPrototype: `{ args, item, lowdefyApp, payload, secret, state, step, user }`
     }));
 }
 export default writeJs;

package/dist/build/buildMenu.js

@@ -103,6 +103,11 @@ function loopItems({ parent, menuId, pages, missingPageWarnings, checkDuplicateM
                     public: true
                 };
             }
+            if (menuItem.type === 'MenuDivider') {
+                menuItem.auth = {
+                    public: true
+                };
+            }
             checkDuplicateMenuItemId({
                 id: menuItem.id,
                 menuId,

package/dist/build/buildModuleDefs.js

@@ -20,7 +20,7 @@ import evaluateStaticOperators from './buildRefs/evaluateStaticOperators.js';
 import collectDynamicIdentifiers from './collectDynamicIdentifiers.js';
 import validateOperatorsDynamic from './validateOperatorsDynamic.js';
 import fetchModules from './fetchModules.js';
-import { resolveLocalManifest, resolveFullManifest } from './registerModules.js';
+import { resolveLocalManifest, resolveFullManifest, validateRequiredVars } from './registerModules.js';
 import resolveModuleDependencies from './resolveModuleDependencies.js';
 validateOperatorsDynamic({
     operators
@@ -30,6 +30,9 @@ const dynamicIdentifiers = collectDynamicIdentifiers({
 });
 async function parseLowdefyYaml({ context }) {
     const refDef = makeRefDefinition('lowdefy.yaml', null, context.refMap);
+    // Stash for Phase 2.5 — consumer vars come from lowdefy.yaml, so refs
+    // within them must be parented to lowdefy.yaml's refDef.
+    context.lowdefyYamlRefDef = refDef;
     const content = await getRefContent({
         context,
         refDef,
@@ -49,6 +52,10 @@ async function parseLowdefyYaml({ context }) {
         env: process.env,
         dynamicIdentifiers,
         shouldStop: (path)=>{
+            // Defer entry vars and connections: they may contain cross-module
+            // refs that require modules to be registered first.
+            if (/^modules\.\d+\.vars$/.test(path)) return 'preserve';
+            if (/^modules\.\d+\.connections$/.test(path)) return 'preserve';
             if (path.startsWith('modules')) return false;
             return 'preserve';
         }
@@ -61,6 +68,42 @@ async function parseLowdefyYaml({ context }) {
     });
     return config ?? {};
 }
+async function resolveEntryConfig({ entry, context }) {
+    const moduleEntry = context.modules[entry.id];
+    const lowdefyYamlRefDef = context.lowdefyYamlRefDef;
+    function makeAppLevelCtx() {
+        return new WalkContext({
+            buildContext: context,
+            refId: lowdefyYamlRefDef.id,
+            sourceRefId: null,
+            vars: {},
+            path: '',
+            currentFile: lowdefyYamlRefDef.path,
+            refChain: new Set(lowdefyYamlRefDef.path ? [
+                lowdefyYamlRefDef.path
+            ] : []),
+            operators,
+            env: process.env,
+            dynamicIdentifiers
+        });
+    }
+    const refDef = lowdefyYamlRefDef;
+    let resolvedVars = await resolve(moduleEntry.consumerVars, makeAppLevelCtx());
+    resolvedVars = evaluateStaticOperators({
+        context,
+        input: resolvedVars,
+        refDef
+    });
+    moduleEntry.consumerVars = resolvedVars ?? {};
+    let resolvedConnections = await resolve(moduleEntry.connections, makeAppLevelCtx());
+    resolvedConnections = evaluateStaticOperators({
+        context,
+        input: resolvedConnections,
+        refDef
+    });
+    moduleEntry.connections = resolvedConnections ?? {};
+    validateRequiredVars(moduleEntry.varDefs, moduleEntry.consumerVars, entry.id, entry.source);
+}
 async function buildModuleDefs({ context }) {
     const lowdefyConfig = await parseLowdefyYaml({
         context
@@ -86,6 +129,14 @@ async function buildModuleDefs({ context }) {
     resolveModuleDependencies({
         context
     });
+    // Step 2.5: Resolve deferred entry vars and connections at app level,
+    // then validate required vars against the resolved values.
+    for (const entry of moduleEntries){
+        await resolveEntryConfig({
+            entry,
+            context
+        });
+    }
     // Step 3: Full resolve — cross-module refs, preserved content
     for (const entryId of Object.keys(context.modules)){
         await resolveFullManifest({

package/dist/build/buildModules.js

@@ -45,7 +45,7 @@ function buildModules({ components, context }) {
         const moduleConnIds = new Set((manifest.connections ?? []).map((c)=>c.id));
         for (const remapKey of Object.keys(remapping)){
             if (!moduleConnIds.has(remapKey)) {
-                throw new ConfigError(`Module "${entry.id}" connection remapping references "${remapKey}", ` + `but the module does not export a connection with that id.`);
+                throw new ConfigError(`Module "${entry.id}" connection remapping references "${remapKey}", ` + `but the module has no connection with that id.`);
             }
         }
         // Validate secret whitelist on non-remapped content

package/dist/build/buildPages/validateCallApiRefs.js

@@ -14,11 +14,20 @@
   limitations under the License.
 */ import { ConfigWarning } from '@lowdefy/errors';
 function validateCallApiRefs({ callApiActionRefs, endpointConfigs, context }) {
+    const existingEndpointIds = new Set(endpointConfigs.map((config)=>config.endpointId));
     const internalEndpoints = new Set(endpointConfigs.filter((config)=>config.type === 'InternalApi').map((config)=>config.endpointId));
     callApiActionRefs.forEach(({ endpointId, action, sourcePageId })=>{
         if (action.skip === true) {
             return;
         }
+        if (!existingEndpointIds.has(endpointId)) {
+            context.handleWarning(new ConfigWarning(`CallAPI action on page "${sourcePageId}" references non-existent endpoint "${endpointId}".`, {
+                configKey: action['~k'],
+                prodError: true,
+                checkSlug: 'callapi-refs'
+            }));
+            return;
+        }
         if (internalEndpoints.has(endpointId)) {
             context.handleWarning(new ConfigWarning(`CallAPI action on page "${sourcePageId}" targets InternalApi endpoint "${endpointId}". InternalApi endpoints are not accessible from client pages.`, {
                 configKey: action['~k'],

package/dist/build/buildRefs/getUserJavascriptFunction.js

@@ -15,20 +15,17 @@
 */ import path from 'path';
 import { pathToFileURL } from 'url';
 import { ConfigError } from '@lowdefy/errors';
-// Create a native import() that survives webpack bundling. When this module is
-// bundled by Next.js webpack for server-dev API routes, webpack transforms
-// import() into __webpack_require__() which can't handle file:// URLs for
-// loading user-provided resolver and transformer JS files from the config
-// directory. The Function constructor creates the import call at runtime,
-// bypassing webpack's static analysis.
-const nativeImport = new Function('specifier', 'return import(specifier)');
 async function getUserJavascriptFunction({ context, filePath }) {
     try {
-        const fileUrl = pathToFileURL(path.join(context.directories.config, filePath));
+        const fileUrl = pathToFileURL(path.resolve(context.directories.config, filePath));
         // Bust Node.js module cache so edits to resolver/transformer JS files are
         // picked up during dev rebuilds. Each import gets a unique URL.
         fileUrl.searchParams.set('t', Date.now());
-        return (await nativeImport(fileUrl.href)).default;
+        // webpackIgnore tells Next.js webpack to leave this dynamic import alone
+        // when bundling server-dev API routes — otherwise webpack rewrites import()
+        // into __webpack_require__() which can't handle file:// URLs for loading
+        // user-provided resolver/transformer JS files from the config directory.
+        return (await import(/* webpackIgnore: true */ fileUrl.href)).default;
     } catch (error) {
         throw new ConfigError(`Error importing ${filePath}.`, {
             cause: error,

package/dist/build/buildRefs/runTransformer.js

@@ -14,7 +14,7 @@
   limitations under the License.
 */ import { ConfigError } from '@lowdefy/errors';
 import getUserJavascriptFunction from './getUserJavascriptFunction.js';
-async function runTransformer({ context, input, refDef }) {
+async function runTransformer({ context, input, refDef, referencedFrom }) {
     if (refDef.transformer) {
         const transformerFn = await getUserJavascriptFunction({
             context,
@@ -25,7 +25,8 @@ async function runTransformer({ context, input, refDef }) {
         } catch (error) {
             throw new ConfigError(`Error calling transformer "${refDef.transformer}" from "${refDef.path}".`, {
                 cause: error,
-                filePath: refDef.transformer
+                filePath: referencedFrom,
+                lineNumber: refDef.lineNumber
             });
         }
     }