Cloudflare Workers

​

What works and what does not

​

Providers and tools

• providers: mock, openai, anthropic and openrouter. The real providers are built on the Vercel ai SDK’s generateText/streamText plus @ai-sdk/openai/@ai-sdk/anthropic (openrouter is @ai-sdk/openai pointed at https://openrouter.ai/api/v1), which are pure fetch()/Web-standard implementations with no node:* imports, so they bundle and run on Workers cleanly; the build’s leak check verifies every bundle. ollama is not supported here: it defaults to a local http://localhost:11434 endpoint that a Worker can’t reach; use node-server or docker for it;
• tools: current-date, day-name and http. web-fetch is not supported. On Node, http and web-fetch refuse private destinations with a DNS lookup of their own (node:dns inside an undici Agent) that checks every address a host resolves to and connects to the address it checked, so DNS rebinding cannot get past the check. A Worker has neither: its fetch() resolves names inside Cloudflare’s network and gives no hook to see or pin the address. What a Worker can check is the URL (scheme, host name, an IP-literal host); what it cannot guarantee is where a host name connects, so a name that resolves to an internal address would not be caught. So the Worker’s http (the same http_request tool name and input as on Node) is a different tool: it reaches only the host names you list. On the first URL and on every redirect it refuses:
  • any scheme but http: and https:;
  • an IP-address host (http://10.0.0.1/, http://[::1]/), even a listed one: there is no address check, so only names are allowed;
  • a host that does not match the LOUSHO_HTTP_ALLOW binding, a comma-separated list of host names (api.github.com) and *. wildcards (*.example.com, which matches subdomains only, not example.com). Unset or empty, every request is refused (fail closed); an entry that is not a host name fails every request with an error naming it.
  A model therefore cannot pick an arbitrary host, or a DNS-rebinding one, because only the names you listed pass; a listed name is trusted wherever it resolves, so list only hosts you control or trust. TLS is always validated (there is no validateSSL option) and the tool runs without a sandbox. A tool of your own that calls fetch() in a Worker gets no SSRF protection from the SDK.

​

Build and deploy

cd .lousho/build/cloudflare-worker
npx wrangler dev       # local workerd runtime
npx wrangler deploy    # requires a Cloudflare account (`wrangler login`)

npx lousho build ./my-agent --target=cloudflare-worker
cd .lousho/build/cloudflare-worker && npx wrangler deploy

• The config’s model must name a provider of the table above ("model": "openai/gpt-4o-mini"), with its key in the OPENAI_API_KEY binding; or agent.ts sets provider to an instance. There is no environment to pick a default model from, so a directory without either is rejected.
• A JSON/YAML config is checked by lousho build; an agent.ts config is checked when the Worker starts, so wrangler deploy reports the problem.
• subagents/, schedules/, channels/, memory/ and projectInstructions are rejected, naming the folder or key. Use node-server or docker for them.
• Tool files are bundled from where they are, so their relative imports and their node_modules resolve as in development. A tool that imports a Node builtin fails the build’s leak check, which names the file.
• In a tool or agent.ts, @lousho/build-ai-agent is a Worker-safe subset of the package: defineTool, isDefinedTool, always, never, once, defineSkill, createMockProvider, MockLLMProvider, OpenAIProvider, AnthropicProvider, OpenRouterProvider, fromAiSdk, LLMProviderRegistry, textOf, SDKError, ConfigurationError, ToolExecutionError and ValidationError. Importing another name fails the build with this list; type-only imports work for every type.

​

Bindings

[vars]
LOUSHO_HTTP_ALLOW = "api.github.com,*.example.com"

cd .lousho/build/cloudflare-worker
npx wrangler secret put LOUSHO_API_TOKEN
npx wrangler secret put OPENAI_API_KEY
npx wrangler deploy
curl -N https://<your-worker>.workers.dev/chat \
  -H "Authorization: Bearer $LOUSHO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "sessionId": "alice", "input": "Hello" }'

​

Sessions, checkpoints and approvals

import { createAgent } from '@lousho/build-ai-agent';
import { KVStore, type KVBinding } from '@lousho/build-ai-agent/kv';

interface Env {
  AGENT_KV: KVBinding;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const agent = createAgent({ provider, store: new KVStore(env.AGENT_KV) });
    const { sessionId, input } = (await request.json()) as { sessionId: string; input: string };
    const { text } = await agent.session({ id: sessionId }).send(input);
    return Response.json({ text });
  },
};

​

Scheduled runs

import { createAgent, createMockProvider, defineSchedule, handleScheduled } from '@lousho/build-ai-agent';
import type { ScheduledContext, ScheduledController } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
const schedules = [defineSchedule({ name: 'weekly', cron: '0 9 * * MON', prompt: 'Summarise last week.' })];

export default {
  scheduled: (controller: ScheduledController, _env: unknown, ctx: ScheduledContext) =>
    handleScheduled(agent, schedules, controller, ctx),
};

​

Consistency

​

Bundle size and Node builtins