@lowdefy/api 5.6.0 → 6.1.0

package/dist/routes/endpoints/control/controlLog.js

@@ -14,28 +14,20 @@
   limitations under the License.
 */ import { type } from '@lowdefy/helpers';
 import { ConfigError } from '@lowdefy/errors';
+import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
 async function controlLog(context, routineContext, { control }) {
-    const { endpointId, logger, evaluateOperators } = context;
-    const { items } = routineContext;
+    const { endpointId, logger } = context;
     const location = control['~k'] ?? ':log';
     logger.debug({
         event: 'debug_control_log'
     });
-    const log = evaluateOperators({
+    const log = evaluateRoutineOperators(context, routineContext, {
         input: control[':log'],
-        items,
-        location,
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location
     });
-    const logLevel = evaluateOperators({
+    const logLevel = evaluateRoutineOperators(context, routineContext, {
         input: control[':level'],
-        items,
-        location,
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location
     }) ?? 'info';
     if (!type.isString(logLevel)) {
         throw new ConfigError(`Invalid :log in endpoint "${endpointId}" - :level must be a string.`, {

package/dist/routes/endpoints/control/controlParallelFor.js

@@ -14,20 +14,17 @@
   limitations under the License.
 */ import { ConfigError } from '@lowdefy/errors';
 import runRoutine from '../runRoutine.js';
+import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
 async function controlParallelFor(context, routineContext, { control }) {
-    const { endpointId, logger, evaluateOperators } = context;
+    const { endpointId, logger } = context;
     const { items } = routineContext;
     const itemName = control[':parallel_for'];
     if (!itemName) {
         throw new Error(`Invalid :parallel_for in endpoint "${endpointId}" - missing variable name in :parallel_for.`);
     }
-    const array = evaluateOperators({
+    const array = evaluateRoutineOperators(context, routineContext, {
         input: control[':in'],
-        items,
-        location: control['~k'] ?? ':parallel_for',
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location: control['~k'] ?? ':parallel_for'
     });
     logger.debug({
         event: 'debug_control_parallel',

package/dist/routes/endpoints/control/controlReject.js

@@ -13,33 +13,33 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { UserError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+import createWireProjection from '../../../response/createWireProjection.js';
+import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
 async function controlReject(context, routineContext, { control }) {
-    const { evaluateOperators } = context;
-    const { items } = routineContext;
     const location = control['~k'] ?? ':reject';
-    const message = evaluateOperators({
+    const message = evaluateRoutineOperators(context, routineContext, {
         input: control[':reject'],
-        items,
-        location,
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location
     });
-    const cause = evaluateOperators({
+    const cause = evaluateRoutineOperators(context, routineContext, {
         input: control[':cause'],
-        items,
-        location,
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location
     });
-    const error = new UserError(message, {
+    // A reject is the author telling the user something, so it stays a UserError, whose message the
+    // wire passes through as written. An Error given as the message is reduced to what the wire
+    // would show for it - the author's text for a UserError, the generic message for a plugin error
+    // - rather than stringified with its library text; `{ _error: message }` opts into the real text.
+    const text = type.isError(message) ? createWireProjection(context)(message).message : message;
+    const error = new UserError(text, {
         cause,
         isReject: true
     });
+    // Log under `err` — see controlThrow: only the `err` key runs the pino error
+    // serializer, so `error` would drop the message from the log line.
     context.logger.warn({
         event: 'warn_control_reject',
-        error
+        err: error
     });
     return {
         status: 'reject',

package/dist/routes/endpoints/control/controlReturn.js

@@ -12,16 +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.
-*/ async function controlReturn(context, routineContext, { control }) {
-    const { evaluateOperators } = context;
-    const { items } = routineContext;
-    const response = evaluateOperators({
+*/ import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
+async function controlReturn(context, routineContext, { control }) {
+    const response = evaluateRoutineOperators(context, routineContext, {
         input: control[':return'],
-        items,
-        location: control['~k'] ?? ':return',
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location: control['~k'] ?? ':return'
     });
     context.logger.debug({
         event: 'debug_control_return',

package/dist/routes/endpoints/control/controlSetState.js

@@ -14,16 +14,12 @@
   limitations under the License.
 */ import { ConfigError } from '@lowdefy/errors';
 import { ReservedKeyError, set } from '@lowdefy/helpers';
+import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
 function controlSetState(context, routineContext, { control }) {
-    const { logger, evaluateOperators } = context;
-    const { items } = routineContext;
-    const evaluatedSetState = evaluateOperators({
+    const { logger } = context;
+    const evaluatedSetState = evaluateRoutineOperators(context, routineContext, {
         input: control[':set_state'],
-        items,
-        location: control['~k'] ?? ':set_state',
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
+        location: control['~k'] ?? ':set_state'
     });
     logger.debug({
         event: 'debug_control_set_state',

package/dist/routes/endpoints/control/controlSwitch.js

@@ -13,21 +13,17 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import runRoutine from '../runRoutine.js';
+import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
 async function controlSwitch(context, routineContext, { control }) {
-    const { endpointId, logger, evaluateOperators } = context;
-    const { items } = routineContext;
+    const { endpointId, logger } = context;
     const cases = control[':switch'];
     logger.debug({
         event: 'debug_control_switch'
     });
     for (const caseObj of cases){
-        const evaluatedCase = evaluateOperators({
+        const evaluatedCase = evaluateRoutineOperators(context, routineContext, {
             input: caseObj[':case'],
-            items,
-            location: caseObj['~k'] ?? control['~k'] ?? ':switch',
-            payload: routineContext.payload,
-            state: routineContext.state,
-            steps: routineContext.steps
+            location: caseObj['~k'] ?? control['~k'] ?? ':switch'
         });
         logger.debug({
             event: 'debug_control_switch_case',

package/dist/routes/endpoints/control/controlThrow.js

@@ -13,32 +13,33 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { UserError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+import evaluateRoutineOperators from '../evaluateRoutineOperators.js';
 async function controlThrow(context, routineContext, { control }) {
-    const { evaluateOperators } = context;
-    const { items } = routineContext;
     const location = control['~k'] ?? ':throw';
-    const message = evaluateOperators({
+    const message = evaluateRoutineOperators(context, routineContext, {
         input: control[':throw'],
-        items,
-        location,
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
-    });
-    const cause = evaluateOperators({
-        input: control[':cause'],
-        items,
-        location,
-        payload: routineContext.payload,
-        state: routineContext.state,
-        steps: routineContext.steps
-    });
-    const error = new UserError(message, {
-        cause
+        location
     });
+    // An Error, such as a rethrown `_error`, goes on unchanged. Wrapped in a UserError it would be
+    // stringified into the message, which the wire sends as author text; under its own class the
+    // wire makes it generic unless it was a UserError. It carries its own cause, so :cause is unused.
+    let error = message;
+    if (!type.isError(message)) {
+        const cause = evaluateRoutineOperators(context, routineContext, {
+            input: control[':cause'],
+            location
+        });
+        error = new UserError(message, {
+            cause
+        });
+    }
+    // Log under `err` — the pino error serializer (createNodeLogger) is registered
+    // for the `err` key only; an Error passed as `error` is JSON-dumped without its
+    // non-enumerable `message`/`stack`, producing a log line with no message.
     context.logger.error({
         event: 'error_control_throw',
-        error
+        err: error
     });
     return {
         status: 'error',

package/dist/routes/endpoints/control/controlTry.js

@@ -12,7 +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.
-*/ import runRoutine from '../runRoutine.js';
+*/ import { projectCaughtError } from '@lowdefy/helpers';
+import runRoutine from '../runRoutine.js';
 async function controlTry(context, routineContext, { control }) {
     context.logger.debug({
         event: 'debug_control_try'
@@ -20,15 +21,24 @@ async function controlTry(context, routineContext, { control }) {
     let res = await runRoutine(context, routineContext, {
         routine: control[':try']
     });
-    if (res.status === 'error') {
-        if (control[':catch']) {
-            context.logger.debug({
-                event: 'debug_control_catch'
-            });
-            res = await runRoutine(context, routineContext, {
-                routine: control[':catch']
-            });
-        }
+    if (res.status === 'error' && control[':catch']) {
+        context.logger.debug({
+            event: 'debug_control_catch'
+        });
+        // A child context rather than a field set on routineContext: the same object is handed to
+        // :try, :finally and every :parallel branch, so writing to it would let an inner :try clobber
+        // the outer catch's error and parallel branches read each other's. steps and state are still
+        // shared because routines mutate them in place. The projection is built once here, never the
+        // raw error, so no operator in the catch can read its received value or source.
+        const error = projectCaughtError(res.error, {
+            scrub: context.scrubSecrets
+        });
+        res = await runRoutine(context, {
+            ...routineContext,
+            error
+        }, {
+            routine: control[':catch']
+        });
     }
     if (control[':finally']) {
         context.logger.debug({

package/dist/routes/endpoints/evaluateRoutineOperators.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 operatorScope from './operatorScope.js';
+// Every routine step evaluates against the same frame. Taking the frame from routineContext in one
+// place means a step handler cannot drop part of it (state, items, loop indices).
+function evaluateRoutineOperators(context, routineContext, { input, location }) {
+    return context.evaluateOperators({
+        arrayIndices: routineContext.arrayIndices,
+        input,
+        location,
+        ...operatorScope(routineContext)
+    });
+}
+export default evaluateRoutineOperators;

package/dist/routes/endpoints/findSchedule.js

@@ -0,0 +1,35 @@
+/*
+  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 { ConfigError } from '@lowdefy/errors';
+// Vercel sends the firing expression in x-vercel-cron-schedule; cron expressions are unique per
+// endpoint and environment (enforced at build) so this is unambiguous. Without a cron (e.g. local
+// testing) fall back to the single schedule, otherwise require it to disambiguate the payload.
+function findSchedule({ schedules, cron, endpointId, environment }) {
+    const where = environment === undefined ? '' : ` for environment "${environment}"`;
+    if (!Array.isArray(schedules) || schedules.length === 0) {
+        throw new ConfigError(`API Endpoint "${endpointId}" is not scheduled${where}.`);
+    }
+    let schedule;
+    if (cron) {
+        schedule = schedules.find((s)=>s.cron === cron);
+    } else if (schedules.length === 1) {
+        schedule = schedules[0];
+    }
+    if (!schedule) {
+        throw new ConfigError(`No schedule matching cron "${cron}" for API Endpoint "${endpointId}"${where}.`);
+    }
+    return schedule;
+}
+export default findSchedule;

package/dist/routes/endpoints/forwardScheduledEndpoint.js

@@ -0,0 +1,111 @@
+/*
+  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 { serializer, type } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+import findSchedule from './findSchedule.js';
+import getEndpointConfig from './getEndpointConfig.js';
+import getEnvironmentSchedules from './getEnvironmentSchedules.js';
+import scheduleBackground from './scheduleBackground.js';
+// Vercel fires cron jobs only on the production deployment, so the schedules of every environment
+// with a cron.secret are registered there as /api/cron-forward/<environment>/<endpointId> jobs. When
+// one fires, this pings the environment's own /api/cron/<endpointId> at its url with that
+// environment's CRON_SECRET (the Lowdefy secret named by config.environments.<env>.cron.secret) so
+// the environment runs its own code, and answers Vercel immediately: the ping is fire-and-forget,
+// kept alive by scheduleBackground and bounded by the function duration, and its outcome exists only
+// in the logs.
+async function forwardScheduledEndpoint(context, { environment, endpointId, cron }) {
+    const { config, logger, secrets } = context;
+    const target = config?.environments?.[environment];
+    if (!type.isObject(target)) {
+        throw new ConfigError(`Cron environment "${environment}" is not declared in config.environments.`);
+    }
+    if (environment === config.environment) {
+        throw new ConfigError(`Cron environment "${environment}" is this deployment's own environment: its crons run here, not forwarded.`);
+    }
+    if (target.cron?.enabled === false) {
+        throw new ConfigError(`Cron environment "${environment}" is disabled.`);
+    }
+    const secretName = target.cron?.secret;
+    if (type.isUndefined(secretName)) {
+        throw new ConfigError(`Cron environment "${environment}" has no cron.secret: crons are only forwarded to environments with one.`);
+    }
+    const secret = secrets?.[secretName];
+    if (!type.isString(secret) || secret === '') {
+        throw new ConfigError(`Secret "${secretName}" holding the CRON_SECRET of cron environment "${environment}" is not set. Set the LOWDEFY_SECRET_${secretName} environment variable on this deployment.`);
+    }
+    // Every environment builds from the same config, so the local artifact says whether the target
+    // declares the firing schedule: fail here with a config error instead of having the target 500.
+    const endpointConfig = await getEndpointConfig(context, {
+        endpointId
+    });
+    const schedules = getEnvironmentSchedules({
+        endpointConfig,
+        environment
+    });
+    findSchedule({
+        schedules,
+        cron,
+        endpointId,
+        environment
+    });
+    // Trim trailing slashes with a loop rather than a regex: CodeQL flags `/\/+$/` on config input.
+    let origin = target.url;
+    while(origin.endsWith('/')){
+        origin = origin.slice(0, -1);
+    }
+    const url = `${origin}/api/cron/${endpointId}`;
+    const timeoutMs = (config?.vercel?.maxDuration ?? 60) * 1000;
+    const headers = {
+        authorization: `Bearer ${secret}`
+    };
+    if (cron) headers['x-vercel-cron-schedule'] = cron;
+    headers['x-lowdefy-cron-environment'] = environment;
+    logger.info({
+        event: 'forward_scheduled_endpoint',
+        endpointId,
+        environment,
+        cron,
+        url
+    });
+    scheduleBackground(context, {
+        event: 'forward_scheduled_endpoint',
+        endpointId
+    }, async ()=>{
+        const response = await fetch(url, {
+            method: 'GET',
+            headers,
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        // Drain the body so the connection is released; the target logs its own outcome.
+        await response.arrayBuffer();
+        if (!response.ok) {
+            throw new Error(`Forwarded cron for environment "${environment}" at ${url} responded ${response.status}.`);
+        }
+        return {
+            status: response.status
+        };
+    });
+    return {
+        error: null,
+        response: serializer.serialize({
+            accepted: true,
+            environment,
+            endpointId
+        }),
+        status: 'accepted',
+        success: true
+    };
+}
+export default forwardScheduledEndpoint;

package/dist/routes/endpoints/getEndpointConfig.js

@@ -12,11 +12,17 @@
   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 { ConfigError } from '@lowdefy/errors';
-async function getEndpointConfig({ logger, readConfigFile }, { endpointId }) {
+*/ import { AuthenticationError, ConfigError } from '@lowdefy/errors';
+import isUnauthenticatedHuman from './isUnauthenticatedHuman.js';
+// A missing endpoint answers the same as a protected one for an anonymous
+// caller on an auth'd app - the message is byte-identical to the one
+// authorizeApiEndpoint throws, so present and absent are indistinguishable
+// before authenticating. Every other caller keeps the opaque does-not-exist.
+async function getEndpointConfig(context, { endpointId }) {
+    const { logger, readConfigFile } = context;
     const endpoint = await readConfigFile(`api/${endpointId}.json`);
     if (!endpoint) {
-        const err = new ConfigError(`API Endpoint "${endpointId}" does not exist.`);
+        const err = await isUnauthenticatedHuman(context) ? new AuthenticationError(`Authentication required for API endpoint "${endpointId}".`) : new ConfigError(`API Endpoint "${endpointId}" does not exist.`);
         logger.debug({
             params: {
                 endpointId

package/dist/routes/endpoints/getEnvironmentSchedules.js

@@ -0,0 +1,27 @@
+/*
+  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';
+// With config.environments declared the build resolves `schedules` onto every environment
+// (schedules.<name>, defaults inherited, plus schedules.default), so an environment run reads its
+// own list and a deployment with no current environment reads the default; without environments
+// the endpoint carries a plain array.
+function getEnvironmentSchedules({ endpointConfig, environment }) {
+    const schedules = endpointConfig.schedules;
+    if (type.isArray(schedules)) {
+        return schedules;
+    }
+    return schedules?.[environment ?? 'default'] ?? [];
+}
+export default getEnvironmentSchedules;

package/dist/routes/endpoints/handleAgentCall.js

@@ -0,0 +1,80 @@
+/*
+  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 { ConfigError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+import addStepResult from './addStepResult.js';
+import prepareAgent from '../agent/prepareAgent.js';
+import evaluateRoutineOperators from './evaluateRoutineOperators.js';
+async function handleAgentCall(context, routineContext, { step }) {
+    const { logger } = context;
+    logger.debug({
+        event: 'debug_start_agent_call',
+        step
+    });
+    // Evaluate operators in step.properties (resolves agentId, prompt)
+    const evaluatedProperties = evaluateRoutineOperators(context, routineContext, {
+        input: step.properties,
+        location: step.stepId
+    });
+    const { agentId, prompt } = evaluatedProperties;
+    if (!type.isString(agentId)) {
+        throw new ConfigError(`CallAgent step "${step.stepId}" properties.agentId must evaluate to a string. Received ${JSON.stringify(agentId)}.`, {
+            configKey: step['~k']
+        });
+    }
+    if (!type.isString(prompt)) {
+        throw new ConfigError(`CallAgent step "${step.stepId}" properties.prompt must evaluate to a string. Received ${JSON.stringify(prompt)}.`, {
+            configKey: step['~k']
+        });
+    }
+    // Headless agent context — no page, no conversation, no sharedState (which
+    // also excludes the client-only update-page-state tool). userId is null
+    // under scheduled (system) context.
+    const agentContext = {
+        conversationId: null,
+        pageId: null,
+        sharedState: undefined,
+        urlQuery: {},
+        userId: context.user?.sub ?? context.user?.id ?? null
+    };
+    const { agentConfig, connectionInstance, agentType, resolverContext } = await prepareAgent(context, {
+        agentId,
+        agentContext,
+        endpointDepth: routineContext.endpointDepth,
+        mode: 'generate'
+    });
+    const { result } = await agentType.resolver({
+        connection: connectionInstance,
+        properties: {
+            agent: agentConfig,
+            prompt
+        },
+        context: resolverContext
+    });
+    addStepResult(context, routineContext, {
+        result,
+        stepId: step.stepId
+    });
+    logger.debug({
+        event: 'debug_end_agent_call',
+        stepId: step.stepId,
+        targetAgentId: agentId,
+        finishReason: result?.finishReason
+    });
+    return {
+        status: 'continue'
+    };
+}
+export default handleAgentCall;