Execution contexts

​

What each context sees

import { LuaTool, User, Lua } from 'lua-cli';
import { z } from 'zod';

export default class GetGreetingTool implements LuaTool {
  name = 'get_greeting';
  description = 'Greet the current user by name, adapted to the channel.';
  inputSchema = z.object({});

  async execute() {
    const user = await User.get();
    const name = user?.data?.name ?? 'there';
    return Lua.request.channel === 'whatsapp' ? `Hi ${name}` : `Hello ${name}, how can I help today?`;
  }
}

​

Runtime constraints

​

A context and a channel

​

When it matters

• Sending a message from a webhook or job: look the end user up by ID first, then user.send(…) or Channels.send(…).
• Behavior that differs by channel: read Lua.request.channel in a tool, a processor, or the model resolver, not in a webhook.
• Work that needs more than a tool’s budget: return quickly and hand off to Jobs.create or Workflows.start.
• A tool that must be hidden for some end users: a condition, which runs in the conversation context and can read the end user.

​

Limits

• Time budgets are in the table; a job’s timeout must be an integer from 1 to 600 seconds. A tool that hits its budget is not retried; the call fails. A job attempt that hits its timeout counts as failed and is retried when the job has retry.
• A job is refused before execute runs when loading its bundle and preparing its context took more than 128 MB of heap: Memory limit exceeded before execution. Nothing execute allocates counts, so the lever on your side is bundle size: trim top-level imports. The check applies to jobs only, and the refused attempt is retried like any failed one.
• Tool results are capped at 300,000 characters; captured log lines at 256 KB per field.
• Trigger slots share a single 15-second budget, so keep signature checks and filtering cheap.

​

Next steps