@lowdefy/ai-utils 0.0.0-experimental-20260414134741

package/dist/buildAgentTools.js

@@ -0,0 +1,268 @@
+/*
+  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 { ToolLoopAgent, tool, jsonSchema, stepCountIs } from 'ai';
+import { createMCPClient } from '@ai-sdk/mcp';
+import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';
+import { serializer } from '@lowdefy/helpers';
+import listFiles from './fileSystem/listFiles.js';
+import readFile from './fileSystem/readFile.js';
+import searchFiles from './fileSystem/searchFiles.js';
+import statFile from './fileSystem/statFile.js';
+// Build artifacts contain serializer markers (~k, ~r, ~l) as non-enumerable
+// properties and ~arr wrappers for arrays. JSON.parse(JSON.stringify(obj))
+// strips non-enumerable props and produces a clean JSON Schema for the AI SDK.
+function cleanBuildArtifact(obj) {
+    return JSON.parse(JSON.stringify(obj, (key, value)=>{
+        if (key.startsWith('~')) return undefined;
+        return value;
+    }));
+}
+async function buildAgentTools({ agent, context, depth = 0 }) {
+    const MAX_DEPTH = 5;
+    if (depth > MAX_DEPTH) {
+        throw new Error(`Sub-agent nesting exceeds maximum depth of ${MAX_DEPTH}.`);
+    }
+    const tools = {};
+    const mcpClients = [];
+    // Build endpoint tools
+    for (const toolConfig of agent.tools ?? []){
+        const { endpointId, confirm } = toolConfig;
+        const endpointConfig = await context.getEndpointConfig({
+            endpointId
+        });
+        tools[endpointId] = tool({
+            description: endpointConfig.description,
+            inputSchema: jsonSchema(cleanBuildArtifact(endpointConfig.payloadSchema)),
+            ...confirm ? {
+                needsApproval: true
+            } : {},
+            execute: async (input, { abortSignal } = {})=>{
+                const result = await context.callEndpoint(endpointId, {
+                    payload: input,
+                    abortSignal
+                });
+                if (!result.success) {
+                    const err = serializer.deserialize(result.error);
+                    throw new Error(err?.message ?? 'Endpoint execution failed');
+                }
+                return cleanBuildArtifact(result.response);
+            }
+        });
+    }
+    // Build MCP clients and merge their tools
+    for (const mcpSource of agent.mcp ?? []){
+        const evaluatedSource = context.evaluateOperators(mcpSource);
+        try {
+            let transport;
+            if (evaluatedSource.transport === 'stdio') {
+                transport = new Experimental_StdioMCPTransport({
+                    command: evaluatedSource.command,
+                    args: evaluatedSource.args,
+                    env: {
+                        ...process.env,
+                        ...evaluatedSource.env ?? {}
+                    }
+                });
+            } else {
+                transport = {
+                    type: evaluatedSource.transport ?? 'http',
+                    url: evaluatedSource.url,
+                    ...evaluatedSource.headers ? {
+                        headers: evaluatedSource.headers
+                    } : {}
+                };
+            }
+            const client = await createMCPClient({
+                transport
+            });
+            mcpClients.push({
+                client,
+                source: evaluatedSource
+            });
+        } catch (err) {
+            const label = evaluatedSource.transport === 'stdio' ? evaluatedSource.command : evaluatedSource.url;
+            console.warn(`MCP server "${label}" unreachable: ${err.message}`);
+        }
+    }
+    // Merge MCP tools with endpoint tools
+    for (const { client, source } of mcpClients){
+        try {
+            const mcpTools = await client.tools();
+            for (const [name, mcpTool] of Object.entries(mcpTools)){
+                if (tools[name]) {
+                    console.warn(`MCP tool "${name}" from ${source.url ?? source.command} conflicts with endpoint tool — skipped.`);
+                    continue;
+                }
+                if (source.confirm) {
+                    tools[name] = {
+                        ...mcpTool,
+                        needsApproval: true
+                    };
+                } else {
+                    tools[name] = mcpTool;
+                }
+            }
+        } catch (err) {
+            const label = source.transport === 'stdio' ? source.command : source.url;
+            console.warn(`MCP server "${label}" tool listing failed: ${err.message}`);
+        }
+    }
+    // Build sub-agent tools
+    for (const subAgentRef of agent.agents ?? []){
+        const subAgentConfig = await context.getAgentConfig({
+            agentId: subAgentRef.agentId
+        });
+        const subConnection = await context.getConnectionForAgent({
+            agentConfig: subAgentConfig
+        });
+        subAgentConfig.mcp = await context.resolveMcpSources({
+            agentConfig: subAgentConfig
+        });
+        // Recursively build sub-agent's tools
+        const { tools: subTools, mcpClients: subMcpClients } = await buildAgentTools({
+            agent: subAgentConfig,
+            context,
+            depth: depth + 1
+        });
+        const subModel = subConnection.provider(subAgentConfig.properties.model);
+        const subAgent = new ToolLoopAgent({
+            model: subModel,
+            instructions: subAgentConfig.properties.instructions,
+            tools: subTools,
+            stopWhen: stepCountIs(subAgentConfig.properties.maxSteps ?? 10),
+            maxOutputTokens: subAgentConfig.properties.maxOutputTokens,
+            temperature: subAgentConfig.properties.temperature,
+            toolChoice: subAgentConfig.properties.toolChoice ?? 'auto',
+            providerOptions: subAgentConfig.properties.providerOptions
+        });
+        const description = subAgentRef.description ?? `Delegate task to the ${subAgentRef.agentId} agent`;
+        const inputSchema = subAgentRef.inputSchema ? jsonSchema(subAgentRef.inputSchema) : jsonSchema({
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'The task to delegate'
+                }
+            },
+            required: [
+                'task'
+            ]
+        });
+        tools[subAgentRef.agentId] = tool({
+            description,
+            inputSchema,
+            execute: async (input, { abortSignal })=>{
+                const prompt = input.task ?? JSON.stringify(input);
+                const result = await subAgent.generate({
+                    prompt,
+                    abortSignal
+                });
+                // Cleanup sub-agent's MCP clients
+                await Promise.all(subMcpClients.map(({ client })=>client.close().catch(()=>{})));
+                return {
+                    _subAgent: true,
+                    agentId: subAgentRef.agentId,
+                    text: result.text
+                };
+            },
+            toModelOutput: ({ output })=>({
+                    type: 'text',
+                    value: output.text ?? String(output)
+                })
+        });
+    }
+    // Build fileSystem tools
+    if (agent.properties?.fileSystem) {
+        const { basePath } = agent.properties.fileSystem;
+        tools['read-file'] = tool({
+            description: 'Read a file by path. Use list-files or search-files first to discover available paths.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'File path relative to the base directory.'
+                    }
+                },
+                required: [
+                    'path'
+                ]
+            }),
+            execute: async ({ path })=>readFile(basePath, {
+                    path
+                })
+        });
+        tools['list-files'] = tool({
+            description: 'List files and directories. Supports optional glob patterns for filtering.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Directory path to list. Omit for root.'
+                    },
+                    glob: {
+                        type: 'string',
+                        description: 'Glob pattern to filter results, e.g. "**/*.md".'
+                    }
+                }
+            }),
+            execute: async (params)=>listFiles(basePath, params)
+        });
+        tools['search-files'] = tool({
+            description: 'Search for text across files. Returns matching files with line numbers and context.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Text to search for.'
+                    },
+                    glob: {
+                        type: 'string',
+                        description: 'Glob pattern to limit which files are searched.'
+                    }
+                },
+                required: [
+                    'query'
+                ]
+            }),
+            execute: async (params)=>searchFiles(basePath, params)
+        });
+        tools['stat-file'] = tool({
+            description: 'Get metadata for a file or directory (size, type, modified date).',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'File or directory path relative to the base directory.'
+                    }
+                },
+                required: [
+                    'path'
+                ]
+            }),
+            execute: async ({ path })=>statFile(basePath, {
+                    path
+                })
+        });
+    }
+    return {
+        tools,
+        mcpClients
+    };
+}
+export default buildAgentTools;

package/dist/buildPrepareStep.js

@@ -0,0 +1,42 @@
+/*
+  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.
+*/ function matchesRule(rule, stepNumber) {
+    if (rule.steps) {
+        return rule.steps.includes(stepNumber);
+    }
+    if (rule.from != null) {
+        const fromOk = stepNumber >= rule.from;
+        const toOk = rule.to == null || stepNumber <= rule.to;
+        return fromOk && toOk;
+    }
+    return false;
+}
+function buildPrepareStep(rules) {
+    if (!rules || rules.length === 0) return undefined;
+    return async function prepareStep({ stepNumber }) {
+        for (const rule of rules){
+            if (matchesRule(rule, stepNumber)) {
+                const config = {};
+                if (rule.activeTools) config.activeTools = rule.activeTools;
+                if (rule.toolChoice) config.toolChoice = rule.toolChoice;
+                if (rule.maxOutputTokens) config.maxOutputTokens = rule.maxOutputTokens;
+                if (rule.temperature != null) config.temperature = rule.temperature;
+                return config;
+            }
+        }
+        return {};
+    };
+}
+export default buildPrepareStep;

package/dist/fileSystem/listFiles.js

@@ -0,0 +1,62 @@
+/*
+  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 fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+import resolvePath from './resolvePath.js';
+async function listFiles(basePath, { path: dirPath, glob: globPattern } = {}) {
+    const absoluteBase = path.resolve(basePath);
+    const resolved = resolvePath(basePath, dirPath);
+    if (globPattern) {
+        const matches = await glob(globPattern, {
+            cwd: resolved,
+            dot: true
+        });
+        const safeMatches = matches.filter((match)=>{
+            const abs = path.resolve(resolved, match);
+            return abs === absoluteBase || abs.startsWith(absoluteBase + path.sep);
+        });
+        const results = [];
+        for (const match of safeMatches.sort()){
+            const absoluteMatch = path.resolve(resolved, match);
+            const relativePath = path.relative(absoluteBase, absoluteMatch);
+            const stats = await fs.stat(absoluteMatch);
+            results.push({
+                name: path.basename(match),
+                path: relativePath,
+                type: stats.isDirectory() ? 'directory' : 'file',
+                size: stats.size
+            });
+        }
+        return results;
+    }
+    const entries = await fs.readdir(resolved, {
+        withFileTypes: true
+    });
+    const results = [];
+    for (const entry of entries.sort((a, b)=>a.name.localeCompare(b.name))){
+        const absoluteEntry = path.join(resolved, entry.name);
+        const relativePath = path.relative(absoluteBase, absoluteEntry);
+        const stats = await fs.stat(absoluteEntry);
+        results.push({
+            name: entry.name,
+            path: relativePath,
+            type: entry.isDirectory() ? 'directory' : 'file',
+            size: stats.size
+        });
+    }
+    return results;
+}
+export default listFiles;

package/dist/fileSystem/readFile.js

@@ -0,0 +1,36 @@
+/*
+  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 fs from 'fs/promises';
+import resolvePath from './resolvePath.js';
+const MAX_FILE_SIZE = 512 * 1024; // 512KB
+async function readFile(basePath, { path: filePath }) {
+    const resolved = resolvePath(basePath, filePath);
+    const stats = await fs.stat(resolved);
+    if (stats.size <= MAX_FILE_SIZE) {
+        return await fs.readFile(resolved, 'utf-8');
+    }
+    const handle = await fs.open(resolved, 'r');
+    try {
+        const buffer = Buffer.alloc(MAX_FILE_SIZE);
+        await handle.read(buffer, 0, MAX_FILE_SIZE, 0);
+        const content = buffer.toString('utf-8');
+        const shownKB = Math.round(MAX_FILE_SIZE / 1024);
+        const totalKB = Math.round(stats.size / 1024);
+        return `${content}\n\n[File truncated — showing first ${shownKB}KB of ${totalKB}KB. Use search-files to find specific content.]`;
+    } finally{
+        await handle.close();
+    }
+}
+export default readFile;

package/dist/fileSystem/resolvePath.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 path from 'path';
+function resolvePath(basePath, requestPath) {
+    const normalizedRequest = (requestPath ?? '').replace(/^\/+/, '');
+    const absoluteBase = path.resolve(basePath);
+    const absoluteTarget = path.resolve(absoluteBase, normalizedRequest || '.');
+    const baseWithSep = absoluteBase + path.sep;
+    if (absoluteTarget !== absoluteBase && !absoluteTarget.startsWith(baseWithSep)) {
+        throw new Error(`Path "${requestPath}" resolves outside the base directory.`);
+    }
+    return absoluteTarget;
+}
+export default resolvePath;

package/dist/fileSystem/searchFiles.js

@@ -0,0 +1,69 @@
+/*
+  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 fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+const MAX_FILE_SIZE = 1024 * 1024; // 1MB
+const MAX_TOTAL_MATCHES = 200;
+async function searchFiles(basePath, { query, glob: globPattern }) {
+    const absoluteBase = path.resolve(basePath);
+    const baseWithSep = absoluteBase + path.sep;
+    const pattern = globPattern ?? '**/*';
+    const files = await glob(pattern, {
+        cwd: absoluteBase,
+        nodir: true,
+        dot: true,
+        absolute: true
+    });
+    const safeFiles = files.filter((file)=>file.startsWith(baseWithSep));
+    const results = [];
+    let totalMatches = 0;
+    const queryLower = query.toLowerCase();
+    for (const file of safeFiles.sort()){
+        if (totalMatches >= MAX_TOTAL_MATCHES) break;
+        const stats = await fs.stat(file);
+        if (stats.size > MAX_FILE_SIZE) continue;
+        let content;
+        try {
+            content = await fs.readFile(file, 'utf-8');
+        } catch  {
+            continue;
+        }
+        const lines = content.split('\n');
+        const matches = [];
+        for(let i = 0; i < lines.length; i++){
+            if (totalMatches >= MAX_TOTAL_MATCHES) break;
+            if (lines[i].toLowerCase().includes(queryLower)) {
+                matches.push({
+                    lineNumber: i + 1,
+                    line: lines[i],
+                    context: {
+                        before: i > 0 ? lines[i - 1] : null,
+                        after: i < lines.length - 1 ? lines[i + 1] : null
+                    }
+                });
+                totalMatches += 1;
+            }
+        }
+        if (matches.length > 0) {
+            results.push({
+                path: path.relative(absoluteBase, file),
+                matches
+            });
+        }
+    }
+    return results;
+}
+export default searchFiles;

package/dist/fileSystem/statFile.js

@@ -0,0 +1,30 @@
+/*
+  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 fs from 'fs/promises';
+import path from 'path';
+import resolvePath from './resolvePath.js';
+async function statFile(basePath, { path: filePath }) {
+    const resolved = resolvePath(basePath, filePath);
+    const stats = await fs.stat(resolved);
+    return {
+        name: path.basename(resolved),
+        path: filePath,
+        size: stats.size,
+        type: stats.isDirectory() ? 'directory' : 'file',
+        modified: stats.mtime.toISOString(),
+        created: stats.birthtime.toISOString()
+    };
+}
+export default statFile;