@lowdefy/ai-utils 5.6.0 → 6.1.0

package/dist/GenerateObjectSchema.js

@@ -0,0 +1,155 @@
+/*
+  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 {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'Lowdefy Request Schema - GenerateObject',
+    type: 'object',
+    required: [
+        'model',
+        'schema'
+    ],
+    properties: {
+        model: {
+            type: 'string',
+            description: 'Model id to generate with.',
+            errorMessage: {
+                type: 'GenerateObject request property "model" should be a string.'
+            }
+        },
+        schema: {
+            type: 'object',
+            description: 'JSON Schema describing the object the model must generate.',
+            errorMessage: {
+                type: 'GenerateObject request property "schema" should be an object.'
+            }
+        },
+        schemaName: {
+            type: 'string',
+            description: 'Optional name for the output schema, passed to the model.',
+            errorMessage: {
+                type: 'GenerateObject request property "schemaName" should be a string.'
+            }
+        },
+        schemaDescription: {
+            type: 'string',
+            description: 'Optional description of the output schema, passed to the model.',
+            errorMessage: {
+                type: 'GenerateObject request property "schemaDescription" should be a string.'
+            }
+        },
+        prompt: {
+            type: 'string',
+            description: 'Text prompt. Use either "prompt" or "messages", not both.',
+            errorMessage: {
+                type: 'GenerateObject request property "prompt" should be a string.'
+            }
+        },
+        messages: {
+            type: 'array',
+            items: {
+                type: 'object'
+            },
+            description: 'Model messages ({ role, content }). Use either "prompt" or "messages", not both.',
+            errorMessage: {
+                type: 'GenerateObject request property "messages" should be an array of objects.'
+            }
+        },
+        system: {
+            type: 'string',
+            description: 'System prompt.',
+            errorMessage: {
+                type: 'GenerateObject request property "system" should be a string.'
+            }
+        },
+        maxOutputTokens: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Maximum number of tokens to generate.',
+            errorMessage: {
+                type: 'GenerateObject request property "maxOutputTokens" should be an integer.',
+                minimum: 'GenerateObject request property "maxOutputTokens" should be at least 1.'
+            }
+        },
+        temperature: {
+            type: 'number',
+            minimum: 0,
+            maximum: 2,
+            description: 'Sampling temperature.',
+            errorMessage: {
+                type: 'GenerateObject request property "temperature" should be a number.',
+                minimum: 'GenerateObject request property "temperature" should be at least 0.',
+                maximum: 'GenerateObject request property "temperature" should be at most 2.'
+            }
+        },
+        topP: {
+            type: 'number',
+            description: 'Nucleus sampling.',
+            errorMessage: {
+                type: 'GenerateObject request property "topP" should be a number.'
+            }
+        },
+        topK: {
+            type: 'number',
+            description: 'Only sample from the top K options for each subsequent token.',
+            errorMessage: {
+                type: 'GenerateObject request property "topK" should be a number.'
+            }
+        },
+        frequencyPenalty: {
+            type: 'number',
+            description: 'Penalize repeated tokens by frequency.',
+            errorMessage: {
+                type: 'GenerateObject request property "frequencyPenalty" should be a number.'
+            }
+        },
+        presencePenalty: {
+            type: 'number',
+            description: 'Penalize tokens that have already appeared.',
+            errorMessage: {
+                type: 'GenerateObject request property "presencePenalty" should be a number.'
+            }
+        },
+        seed: {
+            type: 'integer',
+            description: 'Seed for deterministic sampling, if supported by the model.',
+            errorMessage: {
+                type: 'GenerateObject request property "seed" should be an integer.'
+            }
+        },
+        maxRetries: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Maximum number of retries. Defaults to 2.',
+            errorMessage: {
+                type: 'GenerateObject request property "maxRetries" should be an integer.',
+                minimum: 'GenerateObject request property "maxRetries" should be at least 0.'
+            }
+        },
+        providerOptions: {
+            type: 'object',
+            description: 'Provider-specific options, keyed by provider.',
+            errorMessage: {
+                type: 'GenerateObject request property "providerOptions" should be an object.'
+            }
+        }
+    },
+    errorMessage: {
+        type: 'GenerateObject request properties should be an object.',
+        required: {
+            model: 'GenerateObject request should have required property "model".',
+            schema: 'GenerateObject request should have required property "schema".'
+        }
+    }
+};

package/dist/GenerateTextSchema.js

@@ -0,0 +1,142 @@
+/*
+  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 {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'Lowdefy Request Schema - GenerateText',
+    type: 'object',
+    required: [
+        'model'
+    ],
+    properties: {
+        model: {
+            type: 'string',
+            description: 'Model id to generate with.',
+            errorMessage: {
+                type: 'GenerateText request property "model" should be a string.'
+            }
+        },
+        prompt: {
+            type: 'string',
+            description: 'Text prompt. Use either "prompt" or "messages", not both.',
+            errorMessage: {
+                type: 'GenerateText request property "prompt" should be a string.'
+            }
+        },
+        messages: {
+            type: 'array',
+            items: {
+                type: 'object'
+            },
+            description: 'Model messages ({ role, content }). Use either "prompt" or "messages", not both.',
+            errorMessage: {
+                type: 'GenerateText request property "messages" should be an array of objects.'
+            }
+        },
+        system: {
+            type: 'string',
+            description: 'System prompt.',
+            errorMessage: {
+                type: 'GenerateText request property "system" should be a string.'
+            }
+        },
+        maxOutputTokens: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Maximum number of tokens to generate.',
+            errorMessage: {
+                type: 'GenerateText request property "maxOutputTokens" should be an integer.',
+                minimum: 'GenerateText request property "maxOutputTokens" should be at least 1.'
+            }
+        },
+        temperature: {
+            type: 'number',
+            minimum: 0,
+            maximum: 2,
+            description: 'Sampling temperature.',
+            errorMessage: {
+                type: 'GenerateText request property "temperature" should be a number.',
+                minimum: 'GenerateText request property "temperature" should be at least 0.',
+                maximum: 'GenerateText request property "temperature" should be at most 2.'
+            }
+        },
+        topP: {
+            type: 'number',
+            description: 'Nucleus sampling.',
+            errorMessage: {
+                type: 'GenerateText request property "topP" should be a number.'
+            }
+        },
+        topK: {
+            type: 'number',
+            description: 'Only sample from the top K options for each subsequent token.',
+            errorMessage: {
+                type: 'GenerateText request property "topK" should be a number.'
+            }
+        },
+        frequencyPenalty: {
+            type: 'number',
+            description: 'Penalize repeated tokens by frequency.',
+            errorMessage: {
+                type: 'GenerateText request property "frequencyPenalty" should be a number.'
+            }
+        },
+        presencePenalty: {
+            type: 'number',
+            description: 'Penalize tokens that have already appeared.',
+            errorMessage: {
+                type: 'GenerateText request property "presencePenalty" should be a number.'
+            }
+        },
+        seed: {
+            type: 'integer',
+            description: 'Seed for deterministic sampling, if supported by the model.',
+            errorMessage: {
+                type: 'GenerateText request property "seed" should be an integer.'
+            }
+        },
+        stopSequences: {
+            type: 'array',
+            items: {
+                type: 'string'
+            },
+            description: 'Sequences that stop generation.',
+            errorMessage: {
+                type: 'GenerateText request property "stopSequences" should be an array of strings.'
+            }
+        },
+        maxRetries: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Maximum number of retries. Defaults to 2.',
+            errorMessage: {
+                type: 'GenerateText request property "maxRetries" should be an integer.',
+                minimum: 'GenerateText request property "maxRetries" should be at least 0.'
+            }
+        },
+        providerOptions: {
+            type: 'object',
+            description: 'Provider-specific options, keyed by provider.',
+            errorMessage: {
+                type: 'GenerateText request property "providerOptions" should be an object.'
+            }
+        }
+    },
+    errorMessage: {
+        type: 'GenerateText request properties should be an object.',
+        required: {
+            model: 'GenerateText request should have required property "model".'
+        }
+    }
+};

package/dist/buildAgentTools.js

@@ -43,7 +43,9 @@ function assertNotPlatformToolName(name, kind, i18n) {
         }));
     }
 }
-async function buildAgentTools({ agent, context, depth = 0 }) {
+// autoApprove skips needsApproval on confirm tools — used by headless
+// run-to-completion agents, where no client exists to resolve an approval.
+async function buildAgentTools({ agent, context, depth = 0, autoApprove = false }) {
     const MAX_DEPTH = 5;
     if (depth > MAX_DEPTH) {
         throw new Error(translate({
@@ -56,26 +58,29 @@ async function buildAgentTools({ agent, context, depth = 0 }) {
     }
     const tools = {};
     const mcpClients = [];
-    // Build endpoint tools
+    // Build endpoint tools. The model-facing tool name is toolConfig.name
+    // (assigned by buildAgents — endpoint id with '/' → '__' unless overridden);
+    // execution still targets the endpointId.
     for (const toolConfig of agent.tools ?? []){
         const { endpointId, confirm } = toolConfig;
-        assertNotPlatformToolName(endpointId, 'Endpoint tool', context.i18n);
+        const toolName = toolConfig.name ?? endpointId;
+        assertNotPlatformToolName(toolName, 'Endpoint tool', context.i18n);
         // A second, disjoint list: RESERVED_PLATFORM_TOOL_NAMES are the tools Lowdefy itself registers,
         // isReserved are the prototype-pollution keys setKey refuses. A name can pass one gate and fail
         // the other, so both checks are needed. The build rejects reserved key names, so this only fires
         // for a stale or hand-edited build artifact. Skip the tool rather than fail the whole agent, as
         // the MCP name cases below do.
-        if (isReserved(endpointId)) {
-            console.warn(`Endpoint tool "${endpointId}" uses a reserved key name — skipped.`);
+        if (isReserved(toolName)) {
+            console.warn(`Endpoint tool "${toolName}" uses a reserved key name — skipped.`);
             continue;
         }
         const endpointConfig = await context.getEndpointConfig({
             endpointId
         });
-        setKey(tools, endpointId, tool({
+        setKey(tools, toolName, tool({
             description: endpointConfig.description,
             inputSchema: jsonSchema(cleanBuildArtifact(endpointConfig.payloadSchema)),
-            ...confirm ? {
+            ...confirm && !autoApprove ? {
                 needsApproval: true
             } : {},
             execute: async (input, { abortSignal } = {})=>{
@@ -151,7 +156,8 @@ async function buildAgentTools({ agent, context, depth = 0 }) {
                     console.warn(`MCP tool "${name}" from ${source.url ?? source.command} ` + `conflicts with endpoint tool — skipped.`);
                     continue;
                 }
-                setKey(tools, name, source.confirm ? {
+                const needsApproval = source.confirm && !autoApprove;
+                setKey(tools, name, needsApproval ? {
                     ...mcpTool,
                     needsApproval: true
                 } : mcpTool);
@@ -161,13 +167,15 @@ async function buildAgentTools({ agent, context, depth = 0 }) {
             console.warn(`MCP server "${label}" tool listing failed: ${err.message}`);
         }
     }
-    // Build sub-agent tools
+    // Build sub-agent tools — keyed by name for the same provider-rule reason
+    // as endpoint tools (scoped agent ids contain '/').
     for (const subAgentRef of agent.agents ?? []){
-        assertNotPlatformToolName(subAgentRef.agentId, 'Sub-agent', context.i18n);
+        const subAgentToolName = subAgentRef.name ?? subAgentRef.agentId;
+        assertNotPlatformToolName(subAgentToolName, 'Sub-agent', context.i18n);
         // Same policy as the endpoint tool name above: unreachable from valid config, so skip rather
         // than fail the whole agent.
-        if (isReserved(subAgentRef.agentId)) {
-            console.warn(`Sub-agent tool "${subAgentRef.agentId}" uses a reserved key name — skipped.`);
+        if (isReserved(subAgentToolName)) {
+            console.warn(`Sub-agent tool "${subAgentToolName}" uses a reserved key name — skipped.`);
             continue;
         }
         const subAgentConfig = await context.getAgentConfig({
@@ -183,7 +191,8 @@ async function buildAgentTools({ agent, context, depth = 0 }) {
         const { tools: subTools, mcpClients: subMcpClients } = await buildAgentTools({
             agent: subAgentConfig,
             context,
-            depth: depth + 1
+            depth: depth + 1,
+            autoApprove
         });
         const subModel = subConnection.provider(subAgentConfig.properties.model);
         const subAgent = new ToolLoopAgent({
@@ -209,7 +218,7 @@ async function buildAgentTools({ agent, context, depth = 0 }) {
                 'task'
             ]
         });
-        setKey(tools, subAgentRef.agentId, tool({
+        setKey(tools, subAgentToolName, tool({
             description,
             inputSchema,
             execute: async (input, { abortSignal })=>{

package/dist/buildGenerateCallOptions.js

@@ -0,0 +1,50 @@
+/*
+  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 } from '@lowdefy/helpers';
+const callSettings = [
+    'system',
+    'maxOutputTokens',
+    'temperature',
+    'topP',
+    'topK',
+    'frequencyPenalty',
+    'presencePenalty',
+    'seed',
+    'stopSequences',
+    'maxRetries',
+    'providerOptions'
+];
+function buildGenerateCallOptions({ request }) {
+    if (type.isNone(request.prompt) && type.isNone(request.messages)) {
+        throw new Error('Either "prompt" or "messages" must be provided.');
+    }
+    if (!type.isNone(request.prompt) && !type.isNone(request.messages)) {
+        throw new Error('Only one of "prompt" or "messages" may be provided, not both.');
+    }
+    const options = {};
+    if (!type.isNone(request.prompt)) {
+        options.prompt = request.prompt;
+    }
+    if (!type.isNone(request.messages)) {
+        options.messages = request.messages;
+    }
+    callSettings.forEach((setting)=>{
+        if (!type.isNone(request[setting])) {
+            options[setting] = request[setting];
+        }
+    });
+    return options;
+}
+export default buildGenerateCallOptions;

package/dist/createGenerateObject.js

@@ -0,0 +1,38 @@
+/*
+  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 handleGenerateObject from './handleGenerateObject.js';
+import schema from './GenerateObjectSchema.js';
+// Builds the GenerateObject request resolver for an AI provider connection.
+// createProvider is the only provider-specific piece — request resolvers
+// receive evaluated connection properties (not a provider instance) from the
+// request interface layer, so the resolver constructs the provider itself.
+function createGenerateObject({ createProvider }) {
+    async function GenerateObject({ connection, request }) {
+        const provider = createProvider({
+            connection
+        });
+        return handleGenerateObject({
+            model: provider(request.model),
+            request
+        });
+    }
+    GenerateObject.schema = schema;
+    GenerateObject.meta = {
+        checkRead: false,
+        checkWrite: false
+    };
+    return GenerateObject;
+}
+export default createGenerateObject;

package/dist/createGenerateText.js

@@ -0,0 +1,38 @@
+/*
+  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 handleGenerateText from './handleGenerateText.js';
+import schema from './GenerateTextSchema.js';
+// Builds the GenerateText request resolver for an AI provider connection.
+// createProvider is the only provider-specific piece — request resolvers
+// receive evaluated connection properties (not a provider instance) from the
+// request interface layer, so the resolver constructs the provider itself.
+function createGenerateText({ createProvider }) {
+    async function GenerateText({ connection, request }) {
+        const provider = createProvider({
+            connection
+        });
+        return handleGenerateText({
+            model: provider(request.model),
+            request
+        });
+    }
+    GenerateText.schema = schema;
+    GenerateText.meta = {
+        checkRead: false,
+        checkWrite: false
+    };
+    return GenerateText;
+}
+export default createGenerateText;

package/dist/createToolLoopAgent.js

@@ -0,0 +1,157 @@
+/*
+  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, stepCountIs, hasToolCall } from 'ai';
+import buildAgentTools from './buildAgentTools.js';
+import buildPrepareStep from './buildPrepareStep.js';
+import buildUpdatePageStateTool from './buildUpdatePageStateTool.js';
+// 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 by the callers (at the stream
+// level in handleAgentChat, after generate in handleAgentGenerate) so that hooks
+// are awaited.
+const hookMapping = {
+    onStart: 'experimental_onStart',
+    onStepStart: 'experimental_onStepStart',
+    onToolCallStart: 'experimental_onToolCallStart',
+    onToolCallFinish: 'experimental_onToolCallFinish',
+    onStepFinish: 'onStepFinish'
+};
+function createHookCallbacks({ hooks, callEndpoint, locale }) {
+    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),
+                locale
+            };
+            for (const endpointId of endpointIds){
+                callEndpoint(endpointId, {
+                    payload
+                }).catch(()=>{});
+            }
+        };
+    }
+    return callbacks;
+}
+// Shared agent assembly for the streaming chat path and the headless generate
+// path: tools, model, hook callbacks, instructions, stop conditions, and the
+// ToolLoopAgent instance.
+async function createToolLoopAgent({ connection, agent, context, autoApprove = false }) {
+    const { tools, mcpClients } = await buildAgentTools({
+        agent,
+        context,
+        autoApprove
+    });
+    const sharedState = context.agentContext?.sharedState;
+    const updatePageStateTool = buildUpdatePageStateTool({
+        sharedState
+    });
+    if (updatePageStateTool) {
+        tools['update-page-state'] = updatePageStateTool;
+    }
+    const model = connection.provider(agent.properties.model);
+    const locale = context.i18n?.active;
+    const hookCallbacks = createHookCallbacks({
+        hooks: agent.hooks,
+        callEndpoint: context.callEndpoint,
+        locale
+    });
+    // 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)}`);
+        }
+        if (ctx.sharedState && Object.keys(ctx.sharedState).length > 0) {
+            contextLines.push(`  sharedState: ${JSON.stringify(ctx.sharedState)}`);
+        }
+        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 timeoutConfig = agent.properties.timeout != null ? {
+        timeout: agent.properties.timeout
+    } : {};
+    return {
+        agentInstance,
+        mcpClients,
+        model,
+        timeoutConfig,
+        locale
+    };
+}
+export default createToolLoopAgent;

package/dist/createUsageAccumulator.js

@@ -0,0 +1,44 @@
+/*
+  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 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
+    };
+}
+export default createUsageAccumulator;

package/dist/handleAgentChat.js

@@ -12,83 +12,11 @@
   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, generateText, pruneMessages, stepCountIs, hasToolCall, validateUIMessages } from 'ai';
+*/ import { convertToModelMessages, createAgentUIStream, createUIMessageStream, createUIMessageStreamResponse, generateId, generateText, pruneMessages, validateUIMessages } from 'ai';
 import { serializer } from '@lowdefy/helpers';
-import buildAgentTools from './buildAgentTools.js';
-import buildPrepareStep from './buildPrepareStep.js';
-import buildUpdatePageStateTool from './buildUpdatePageStateTool.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, locale }) {
-    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),
-                locale
-            };
-            for (const endpointId of endpointIds){
-                callEndpoint(endpointId, {
-                    payload
-                }).catch(()=>{});
-            }
-        };
-    }
-    return callbacks;
-}
+import createToolLoopAgent from './createToolLoopAgent.js';
+import createUsageAccumulator from './createUsageAccumulator.js';
+import handleAgentGenerate from './handleAgentGenerate.js';
 // 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.
@@ -112,6 +40,27 @@ function convertDataUrlsToBase64(messages) {
         };
     });
 }
+// Drop messages that carry no parts. The AI SDK client pushes the assistant
+// message on the stream's `start` chunk, before any content arrives, so a
+// request that fails after that point leaves an assistant shell with
+// `parts: []` in the client's history. Sent back, that shell fails UIMessage
+// validation ("Message must contain at least one part") — and keeps failing on
+// every later turn, so one transient error would otherwise kill the
+// conversation until a reload. There is nothing in an empty message for the
+// model anyway.
+function dropEmptyMessages(messages) {
+    return messages.filter((msg)=>Array.isArray(msg.parts) && msg.parts.length > 0);
+}
+// What the client is told when a turn fails or a tool throws. The text reaches the end
+// user and AgentChat config (`_event: message`), so it takes the wire policy: the
+// author's message for a UserError or an auth refusal, the generic message otherwise. A
+// library's message can embed anything it saw - a TypeValidationError's embeds the whole
+// conversation. The full error is logged server-side.
+function createClientErrorText(context) {
+    return function clientErrorText(error) {
+        return context.wireErrorMessage(error);
+    };
+}
 // Concatenate the text parts of the first user message — used as the source
 // for generateTitle.
 function getFirstUserText(messages) {
@@ -120,96 +69,32 @@ function getFirstUserText(messages) {
     return (firstUser.parts ?? []).filter((part)=>part.type === 'text').map((part)=>part.text).join('');
 }
 async function handleAgentChat({ connection, properties, context }) {
+    // Headless run-to-completion mode (CallAgent routine step) — dispatched here
+    // so provider agent plugins delegate unchanged in both modes.
+    if (context.mode === 'generate') {
+        return handleAgentGenerate({
+            connection,
+            properties,
+            context
+        });
+    }
     const { agent, messages: rawMessages } = properties;
-    const messages = convertDataUrlsToBase64(rawMessages);
-    const { tools, mcpClients } = await buildAgentTools({
+    const messages = dropEmptyMessages(convertDataUrlsToBase64(rawMessages));
+    const { agentInstance, mcpClients, model, timeoutConfig, locale } = await createToolLoopAgent({
+        connection,
         agent,
         context
     });
-    const sharedState = context.agentContext?.sharedState;
-    const updatePageStateTool = buildUpdatePageStateTool({
-        sharedState
-    });
-    if (updatePageStateTool) {
-        tools['update-page-state'] = updatePageStateTool;
-    }
-    const model = connection.provider(agent.properties.model);
-    const locale = context.i18n?.active;
-    const hookCallbacks = createHookCallbacks({
-        hooks: agent.hooks,
-        callEndpoint: context.callEndpoint,
-        locale
-    });
-    // 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)}`);
-        }
-        if (ctx.sharedState && Object.keys(ctx.sharedState).length > 0) {
-            contextLines.push(`  sharedState: ${JSON.stringify(ctx.sharedState)}`);
-        }
-        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 titleEnabled = agent.properties.generateTitle === true;
+    const clientErrorText = createClientErrorText(context);
+    // Every stream gets clientErrorText: the AI SDK's default onError writes a tool error or
+    // an in-stream error to the client raw.
     const stream = createUIMessageStream({
+        onError: clientErrorText,
         execute: async ({ writer })=>{
             const usageAccumulator = createUsageAccumulator();
             const steps = [];
@@ -259,52 +144,76 @@ async function handleAgentChat({ connection, properties, context }) {
                     });
                 }
             }
-            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: collectStep
-                });
-                agentStream = result.toUIMessageStream({
-                    originalMessages: validatedMessages,
-                    onFinish: captureMessages
-                });
-            } 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: collectStep,
-                    onFinish: captureMessages
-                });
-            }
-            // Read the agent stream to completion before running onFinish hooks.
-            // writer.merge() is fire-and-forget (returns void in the AI SDK), so we
-            // manually read the stream to ensure hooks fire after the agent finishes.
-            const reader = agentStream.getReader();
+            // One try around validation, the agent run and the read: a UIMessage that
+            // fails validation throws from createAgentUIStream / validateUIMessages
+            // before any stream exists, and that fault has to be logged and redacted
+            // the same way as a fault mid-stream.
             try {
+                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: collectStep
+                    });
+                    agentStream = result.toUIMessageStream({
+                        originalMessages: validatedMessages,
+                        // Without a generator the assistant message reaches onFinish with
+                        // id: '' — see the createAgentUIStream call below.
+                        generateMessageId: generateId,
+                        onFinish: captureMessages,
+                        onError: clientErrorText
+                    });
+                } 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,
+                        // The AI SDK only ids the assistant message it builds when the caller
+                        // supplies a generator: toUIMessageStream derives responseMessageId
+                        // only if generateMessageId != null, and handleUIMessageStreamFinish
+                        // then seeds the streaming state with `messageId ?? ''`, with no
+                        // messageId on the start chunk to override it. Without this every
+                        // assistant message an onFinish hook persists carries id: '', so a
+                        // saved transcript has them all sharing one id — and a UI that keys
+                        // its bubbles by message id (AgentChat does) renders the last reply in
+                        // every assistant bubble when the conversation is reloaded. The client
+                        // generates its own id while streaming, so the damage only shows up
+                        // after a reload.
+                        generateMessageId: generateId,
+                        onStepFinish: collectStep,
+                        onFinish: captureMessages,
+                        onError: clientErrorText
+                    });
+                }
+                // Read the agent stream to completion before running onFinish hooks.
+                // writer.merge() is fire-and-forget (returns void in the AI SDK), so we
+                // manually read the stream to ensure hooks fire after the agent finishes.
+                const reader = agentStream.getReader();
                 while(true){
                     const { done, value } = await reader.read();
                     if (done) break;
                     writer.write(value);
                 }
             } catch (error) {
+                // The client only sees the (possibly redacted) error text, so the fault
+                // is logged server-side before it is written to the stream.
+                console.error(`Agent stream failed: ${error.message}`);
                 writer.write({
                     type: 'error',
                     errorText: writer.onError(error)

package/dist/handleAgentGenerate.js

@@ -0,0 +1,93 @@
+/*
+  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 createToolLoopAgent from './createToolLoopAgent.js';
+import createUsageAccumulator from './createUsageAccumulator.js';
+// Runs an agent headlessly to completion — no chat UI, no streaming. Used by
+// the CallAgent routine step. Confirm tools auto-execute (no client exists to
+// resolve an approval), update-page-state is excluded (callers pass no
+// sharedState), and no conversation title is generated.
+async function handleAgentGenerate({ connection, properties, context }) {
+    const { agent, prompt } = properties;
+    const { agentInstance, mcpClients, timeoutConfig, locale } = await createToolLoopAgent({
+        connection,
+        agent,
+        context,
+        autoApprove: true
+    });
+    const usageAccumulator = createUsageAccumulator();
+    let result;
+    try {
+        result = await agentInstance.generate({
+            prompt,
+            ...timeoutConfig,
+            onStepFinish: (stepResult)=>usageAccumulator.add(stepResult)
+        });
+    } finally{
+        await Promise.all(mcpClients.map(({ client })=>client.close().catch(()=>{})));
+    }
+    const toolCalls = result.steps.flatMap((step)=>step.toolCalls ?? []).map(({ toolCallId, toolName, input })=>({
+            toolCallId,
+            toolName,
+            input
+        }));
+    const toolResults = result.steps.flatMap((step)=>step.toolResults ?? []).map(({ toolCallId, toolName, output })=>({
+            toolCallId,
+            toolName,
+            output
+        }));
+    // JSON round-trip guards serializability — tool outputs can carry
+    // non-serializable provider values, and the summary lands in _step.
+    const summary = JSON.parse(JSON.stringify({
+        text: result.text,
+        finishReason: result.finishReason,
+        usage: usageAccumulator.usage,
+        toolCalls,
+        toolResults
+    }));
+    // Call onFinish hooks — awaited, mirroring the stream path, but any
+    // dataParts returned by hook endpoints are ignored (there is no stream).
+    const onFinishEndpointIds = agent.hooks?.onFinish;
+    if (onFinishEndpointIds && onFinishEndpointIds.length > 0) {
+        const finishPayload = {
+            messages: result.response.messages,
+            steps: result.steps.map(({ stepNumber, text, toolCalls: calls, toolResults: results, finishReason })=>({
+                    stepNumber,
+                    text,
+                    toolCalls: calls,
+                    toolResults: results,
+                    finishReason
+                })),
+            toolResults,
+            finishReason: result.finishReason,
+            isAborted: false,
+            ...context.agentContext ?? {},
+            usage: usageAccumulator.usage,
+            locale
+        };
+        for (const endpointId of onFinishEndpointIds){
+            try {
+                await context.callEndpoint(endpointId, {
+                    payload: finishPayload
+                });
+            } catch (error) {
+                console.warn(`onFinish hook "${endpointId}" failed: ${error.message}`);
+            }
+        }
+    }
+    return {
+        result: summary
+    };
+}
+export default handleAgentGenerate;

package/dist/handleGenerateObject.js

@@ -0,0 +1,40 @@
+/*
+  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 { generateText, jsonSchema, Output } from 'ai';
+import buildGenerateCallOptions from './buildGenerateCallOptions.js';
+// generateObject is deprecated in ai v6 — structured output is generateText
+// with an Output.object spec, which also keeps both handlers on one code path.
+async function handleGenerateObject({ model, request }) {
+    const result = await generateText({
+        model,
+        output: Output.object({
+            schema: jsonSchema(request.schema),
+            name: request.schemaName,
+            description: request.schemaDescription
+        }),
+        ...buildGenerateCallOptions({
+            request
+        })
+    });
+    return {
+        object: result.output,
+        reasoningText: result.reasoningText,
+        finishReason: result.finishReason,
+        usage: result.usage,
+        providerMetadata: result.providerMetadata,
+        warnings: result.warnings
+    };
+}
+export default handleGenerateObject;

package/dist/handleGenerateText.js

@@ -0,0 +1,33 @@
+/*
+  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 { generateText } from 'ai';
+import buildGenerateCallOptions from './buildGenerateCallOptions.js';
+async function handleGenerateText({ model, request }) {
+    const result = await generateText({
+        model,
+        ...buildGenerateCallOptions({
+            request
+        })
+    });
+    return {
+        text: result.text,
+        reasoningText: result.reasoningText,
+        finishReason: result.finishReason,
+        usage: result.usage,
+        providerMetadata: result.providerMetadata,
+        warnings: result.warnings
+    };
+}
+export default handleGenerateText;

package/dist/index.js

@@ -12,5 +12,8 @@
   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';
+*/ export { default as createGenerateObject } from './createGenerateObject.js';
+export { default as createGenerateText } from './createGenerateText.js';
+export { default as handleAgentChat } from './handleAgentChat.js';
+export { default as handleAgentGenerate } from './handleAgentGenerate.js';
 export { default as RESERVED_PLATFORM_TOOL_NAMES } from './reservedToolNames.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/ai-utils",
-  "version": "5.6.0",
+  "version": "6.1.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -17,15 +17,16 @@
   ],
   "dependencies": {
     "@ai-sdk/mcp": "1.0.41",
-    "@lowdefy/errors": "5.6.0",
-    "@lowdefy/helpers": "5.6.0",
+    "@lowdefy/errors": "6.1.0",
+    "@lowdefy/helpers": "6.1.0",
     "ai": "6.0.176",
     "glob": "13.0.6"
   },
   "devDependencies": {
     "@jest/globals": "28.1.3",
-    "@swc/cli": "0.8.0",
-    "@swc/core": "1.15.18",
+    "@lowdefy/ajv": "6.1.0",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.32",
     "@swc/jest": "0.2.39",
     "jest": "28.1.3"
   },