@lowdefy/ai-utils 0.0.0-experimental-20260414134741

package/dist/handleAgentChat.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, convertToModelMessages, createAgentUIStream, createUIMessageStream, createUIMessageStreamResponse, pruneMessages, stepCountIs, hasToolCall, validateUIMessages } from 'ai';
+import { serializer } from '@lowdefy/helpers';
+import buildAgentTools from './buildAgentTools.js';
+import buildPrepareStep from './buildPrepareStep.js';
+function createUsageAccumulator() {
+    const usage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        reasoningTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0
+    };
+    let finishReason = 'stop';
+    function add(stepResult) {
+        const stepUsage = stepResult?.usage ?? stepResult;
+        if (stepResult?.finishReason) {
+            finishReason = stepResult.finishReason;
+        }
+        if (!stepUsage) return;
+        usage.inputTokens += stepUsage.inputTokens ?? 0;
+        usage.outputTokens += stepUsage.outputTokens ?? 0;
+        usage.totalTokens += stepUsage.totalTokens ?? 0;
+        usage.reasoningTokens += stepUsage.outputTokenDetails?.reasoningTokens ?? 0;
+        usage.cacheReadTokens += stepUsage.inputTokenDetails?.cacheReadTokens ?? 0;
+        usage.cacheWriteTokens += stepUsage.inputTokenDetails?.cacheWriteTokens ?? 0;
+    }
+    return {
+        usage,
+        add,
+        getFinishReason: ()=>finishReason
+    };
+}
+// Strip non-serializable fields from agent-level hook events before sending as payload.
+// messages excluded here — the stream-level onFinish sends UIMessage[] directly.
+function cleanHookEvent(event) {
+    const clean = {};
+    for (const [key, value] of Object.entries(event)){
+        if (key === 'abortSignal') continue;
+        if (key === 'messages') continue;
+        if (typeof value === 'function') continue;
+        clean[key] = value;
+    }
+    return clean;
+}
+// Maps YAML hook names to AI SDK callback names and creates fire-and-forget callbacks.
+// onFinish is intentionally excluded — it is handled at the stream level inside the
+// createUIMessageStream execute function so that hooks are awaited and can return
+// dataParts to be written to the response stream.
+const hookMapping = {
+    onStart: 'experimental_onStart',
+    onStepStart: 'experimental_onStepStart',
+    onToolCallStart: 'experimental_onToolCallStart',
+    onToolCallFinish: 'experimental_onToolCallFinish',
+    onStepFinish: 'onStepFinish'
+};
+function createHookCallbacks({ hooks, callEndpoint }) {
+    if (!hooks) return {};
+    const callbacks = {};
+    for (const [yamlKey, sdkKey] of Object.entries(hookMapping)){
+        const endpointIds = hooks[yamlKey];
+        if (!endpointIds || endpointIds.length === 0) continue;
+        callbacks[sdkKey] = (event)=>{
+            const payload = cleanHookEvent(event);
+            for (const endpointId of endpointIds){
+                callEndpoint(endpointId, {
+                    payload
+                }).catch(()=>{});
+            }
+        };
+    }
+    return callbacks;
+}
+// Convert data: URLs in file parts to raw base64 so the AI SDK does not attempt
+// to download them (it only supports http/https).  The mediaType field already
+// carries the MIME type, so nothing is lost.
+function convertDataUrlsToBase64(messages) {
+    return messages.map((msg)=>{
+        if (!msg.parts) return msg;
+        const converted = msg.parts.map((part)=>{
+            if (part.type !== 'file' || typeof part.url !== 'string' || !part.url.startsWith('data:')) {
+                return part;
+            }
+            const commaIndex = part.url.indexOf(',');
+            if (commaIndex === -1) return part;
+            return {
+                ...part,
+                url: part.url.slice(commaIndex + 1)
+            };
+        });
+        return {
+            ...msg,
+            parts: converted
+        };
+    });
+}
+async function handleAgentChat({ connection, properties, context }) {
+    const { agent, messages: rawMessages } = properties;
+    const messages = convertDataUrlsToBase64(rawMessages);
+    const { tools, mcpClients } = await buildAgentTools({
+        agent,
+        context
+    });
+    const model = connection.provider(agent.properties.model);
+    const hookCallbacks = createHookCallbacks({
+        hooks: agent.hooks,
+        callEndpoint: context.callEndpoint
+    });
+    // Prepend page context to instructions when pageContext is enabled
+    let instructions = agent.properties.instructions;
+    if (agent.properties.pageContext && context.agentContext) {
+        const ctx = context.agentContext;
+        const contextLines = [
+            '<context>'
+        ];
+        if (ctx.pageId) contextLines.push(`  pageId: ${ctx.pageId}`);
+        if (ctx.userId) contextLines.push(`  userId: ${ctx.userId}`);
+        if (ctx.conversationId) contextLines.push(`  conversationId: ${ctx.conversationId}`);
+        if (ctx.urlQuery && Object.keys(ctx.urlQuery).length > 0) {
+            contextLines.push(`  urlQuery: ${JSON.stringify(ctx.urlQuery)}`);
+        }
+        contextLines.push('</context>');
+        instructions = `${contextLines.join('\n')}\n\n${instructions ?? ''}`;
+    }
+    // Build stop conditions
+    const stopConditions = [
+        stepCountIs(agent.properties.maxSteps ?? 10)
+    ];
+    const stopOnToolCall = agent.properties.stopOnToolCall;
+    if (stopOnToolCall) {
+        const toolNames = Array.isArray(stopOnToolCall) ? stopOnToolCall : [
+            stopOnToolCall
+        ];
+        for (const name of toolNames){
+            stopConditions.push(hasToolCall(name));
+        }
+    }
+    const agentInstance = new ToolLoopAgent({
+        model,
+        instructions,
+        tools,
+        stopWhen: stopConditions.length === 1 ? stopConditions[0] : stopConditions,
+        maxOutputTokens: agent.properties.maxOutputTokens,
+        temperature: agent.properties.temperature,
+        toolChoice: agent.properties.toolChoice ?? 'auto',
+        providerOptions: agent.properties.providerOptions,
+        activeTools: agent.properties.activeTools,
+        topP: agent.properties.topP,
+        topK: agent.properties.topK,
+        frequencyPenalty: agent.properties.frequencyPenalty,
+        presencePenalty: agent.properties.presencePenalty,
+        seed: agent.properties.seed,
+        stopSequences: agent.properties.stopSequences,
+        maxRetries: agent.properties.maxRetries,
+        ...agent.properties.prepareStep ? {
+            prepareStep: buildPrepareStep(agent.properties.prepareStep)
+        } : {},
+        ...hookCallbacks,
+        ...agent.properties.repairToolCall ? {
+            experimental_repairToolCall: async ({ toolCall })=>{
+                return {
+                    ...toolCall
+                };
+            }
+        } : {}
+    });
+    const onFinishEndpointIds = agent.hooks?.onFinish;
+    const hasOnFinishHooks = onFinishEndpointIds && onFinishEndpointIds.length > 0;
+    const hasMcpClients = mcpClients.length > 0;
+    const pruneConfig = agent.properties.prune;
+    const timeoutConfig = agent.properties.timeout != null ? {
+        timeout: agent.properties.timeout
+    } : {};
+    const stream = createUIMessageStream({
+        execute: async ({ writer })=>{
+            const usageAccumulator = createUsageAccumulator();
+            let agentStream;
+            if (pruneConfig) {
+                // Decompose createAgentUIStream so we can insert pruneMessages
+                // between the UIMessage→ModelMessage conversion and agent execution.
+                const validatedMessages = await validateUIMessages({
+                    messages,
+                    tools: agentInstance.tools
+                });
+                const modelMessages = await convertToModelMessages(validatedMessages, {
+                    tools: agentInstance.tools
+                });
+                const prunedMessages = pruneMessages({
+                    messages: modelMessages,
+                    ...pruneConfig
+                });
+                const result = await agentInstance.stream({
+                    prompt: prunedMessages,
+                    ...timeoutConfig,
+                    onStepFinish: (stepResult)=>{
+                        usageAccumulator.add(stepResult);
+                    }
+                });
+                agentStream = result.toUIMessageStream({
+                    originalMessages: validatedMessages
+                });
+            } else {
+                // createAgentUIStream validates UIMessages, converts to ModelMessages,
+                // runs the agent, and returns a UIMessageStream — handling the full
+                // UI→model→UI conversion that ToolLoopAgent.stream() does not.
+                agentStream = await createAgentUIStream({
+                    agent: agentInstance,
+                    uiMessages: messages,
+                    ...timeoutConfig,
+                    onStepFinish: (stepResult)=>{
+                        usageAccumulator.add(stepResult);
+                    }
+                });
+            }
+            writer.merge(agentStream);
+            // After merge resolves the agent stream is complete.
+            // Call onFinish hooks — awaited so dataParts can be written to stream.
+            if (hasOnFinishHooks) {
+                const finishPayload = {
+                    messages,
+                    finishReason: usageAccumulator.getFinishReason(),
+                    isAborted: false,
+                    ...context.agentContext ?? {},
+                    usage: usageAccumulator.usage
+                };
+                for (const endpointId of onFinishEndpointIds){
+                    try {
+                        const hookResponse = await context.callEndpoint(endpointId, {
+                            payload: finishPayload
+                        });
+                        const responseData = serializer.deserialize(hookResponse?.response);
+                        if (Array.isArray(responseData?.dataParts)) {
+                            for (const part of responseData.dataParts){
+                                writer.write(part);
+                            }
+                        }
+                    } catch (error) {
+                        console.warn(`onFinish hook "${endpointId}" failed: ${error.message}`);
+                    }
+                }
+            }
+            if (hasMcpClients) {
+                await Promise.all(mcpClients.map(({ client })=>client.close().catch(()=>{})));
+            }
+        }
+    });
+    const response = createUIMessageStreamResponse({
+        stream
+    });
+    return {
+        response
+    };
+}
+export default handleAgentChat;

package/dist/index.js

@@ -0,0 +1,15 @@
+/*
+  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.
+*/ export { default as handleAgentChat } from './handleAgentChat.js';

package/dist/types.js

@@ -0,0 +1,19 @@
+/*
+  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.
+*/ export default {
+    agents: [
+        'AISDKAgent'
+    ]
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lowdefy/ai-utils",
+  "version": "0.0.0-experimental-20260414134741",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./agents": "./dist/agents.js",
+    "./types": "./dist/types.js"
+  },
+  "files": [
+    "dist/*"
+  ],
+  "dependencies": {
+    "@ai-sdk/mcp": "1.0.30",
+    "ai": "6.0.116",
+    "glob": "11.0.2",
+    "@lowdefy/helpers": "0.0.0-experimental-20260414134741"
+  },
+  "devDependencies": {
+    "@jest/globals": "28.1.3",
+    "@swc/cli": "0.8.0",
+    "@swc/core": "1.15.18",
+    "@swc/jest": "0.2.39",
+    "jest": "28.1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "swc src --out-dir dist --config-file ../../../.swcrc --cli-config-file ../../../.swc-cli.json",
+    "clean": "rm -rf dist",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  }
+}