The code operation

code runs a TypeScript function in an isolated sandbox. Use it to reshape a response, compute a value, or make a decision that one if comparison cannot express. For calling an API, prefer http: its request shows in the editor and in test runs.

{
  "kind": "code",
  "config": {
    "source_ts": "export default async function handler(input) {\n  const slots = input.tooldata.slots ?? [];\n  const morning = slots.filter((s) => Number(String(s.start).slice(0, 2)) < 12);\n  return { count: morning.length, spoken: morning.slice(0, 3).map((s) => s.label).join(\", \") };\n}\n",
    "timeout": 5
  },
  "silent": true,
  "publish_fields": [
    { "path": "count", "store": "tooldata" },
    { "path": "spoken", "store": "tooldata" }
  ]
}

The contract

source_ts must export default async function handler(input) and return an object or array. publish_fields read out of the return value exactly as they read an http response. Any other return value is wrapped, so return 42 publishes at the path result. input carries the same six roots the rest of the tree templates:

type Input = {
  args: Record<string, any>;           // what the model sent
  tooldata: Record<string, any>;       // published earlier in this run
  userdata: Record<string, any>;       // the session's state
  system_vars: Record<string, string>; // read-only
  vars: Record<string, string>;        // read-only
  secrets: Record<string, string>;     // only the names the script mentions; workspace and session secrets
};

There is no template syntax. Write input.system_vars.now, never {{system_vars.now}}; braces in the source are neither substituted nor checked.
Writing to input changes nothing. Return a value and publish it.
Name secrets literally: input.secrets.STRIPE_KEY or input.secrets["STRIPE_KEY"]. Only the names found in the source are sent to the sandbox, so a name built at run time is undefined. A session’s own secrets are merged over the workspace’s. A name that is not a workspace secret is a publish warning: every session must supply it.

Config

Field	Type	Default	Notes
`source_ts`	string	required	Must export the handler. Not blank
`timeout`	number, seconds	`10`	Above 0, at most 30
`compiled_js`	string	—	Written by the server at publish. Do not send it

The TypeScript is compiled at publish, so a script that does not compile is a publish error. Types are stripped, not checked.

The sandbox

Each run gets a fresh V8 isolate. Nothing persists between runs or between two code operations in one tree; pass values through tooldata. Available: the JavaScript built-ins (JSON, Math, Date, Promise, Map, Set, RegExp, Intl with timezone data), console and fetch. Not available: require, import and every Node API — no process, Buffer, URL, URLSearchParams, TextEncoder, crypto, atob, structuredClone or timers. Request signing (an HMAC) cannot be done here. The sandbox clock is UTC: new Date() is the right instant, but pass a timeZone to Intl.DateTimeFormat whenever you need a local hour or weekday. input.system_vars.now, .date and .time are absent when the calling agent has no timezone — publish does not check reads inside a script. A complete business-hours tool is in patterns.

`fetch`

A small shim, not the browser API:

const res = await fetch(url, { method, headers, body }); // a non-string body is JSON-encoded
res.status;        // number
res.ok;            // status is 2xx
res.headers;       // plain object
await res.text();  // string
await res.json();  // parsed

Redirects are not followed and nothing streams. The same public-address rule as http applies, checked at connection time; a refused request throws fetch failed: <reason>.

Limits

Limit	Value
Wall-clock time	The operation’s `timeout`, default 10 s, at most 30 s
Memory	128 MB
Script plus `input`	2 MB
`fetch` response body	1 MB
`fetch` timeout	10 s
`console` lines kept	100, each cut to 2,000 characters

A throw, a timeout (execution exceeded 10000ms) or running out of memory fails the operation as code operation failed: <message>, with the last ten console lines appended when there are any. on_error decides what happens next.

Where `console` output goes

On a test run, each code step shows its console lines beside its return value. On a live call they are not shown anywhere you can read, except the last ten lines appended to a failure’s error. Debug scripts in a test run.

Conditionals

Branch on what the script returned.

Patterns

Business hours and other complete trees.

Testing and publishing

Run the script against real data and read its output.

Get started

Build

Guides

The code operation

The contract

Config

The sandbox

`fetch`

Limits

Where `console` output goes

Next

Conditionals

Patterns

Testing and publishing

​The contract

​Config

​The sandbox

​fetch

​Limits

​Where console output goes

​Next

Conditionals

Patterns

Testing and publishing

The contract

Config

The sandbox

`fetch`

Limits

Where `console` output goes

Next