The run_code tool

run_code runs a small program in which DataMind Oda calls its other tools. This page covers the tool itself: what a call carries, how a run is bounded and approved, and how the result reads. How a run looks in a chat is on Programs Oda runs, and the form in which a chat is given this tool is on Tools and how they are offered.

What a call carries

Item	What it is	Required
`code`	The program itself: the body of an async function. Top-level `await` and `return` both work, and the returned value comes back with the run.	Yes
`description`	Five to ten words in active voice, saying what the program does; it appears as the title of the run in the chat.	Yes
`timeoutMs`	A longer time budget in milliseconds: a positive number, capped at the maximum. Omitted, the default applies.	No
`sandbox_permissions`	A wider file-access mode for this complete program run.	No
`justification`	A one-sentence reason why this run needs wider access; it is shown to you before the program starts.	With `sandbox_permissions`

The run keeps the program itself, so you can read what ran; the description is what you see on the run.
A call that does not fit is refused before the program starts; the refusals are listed below.

When the request is refused

Refusal	What it means
`invalid description: expected a non-empty string`	The description is missing or empty.
`invalid timeoutMs: expected a positive finite number`	The time budget is not a positive number.
`invalid escalation: sandbox_permissions requires a justification`	A wider mode was asked for without a reason.
`invalid escalation: justification is only valid together with sandbox_permissions`	A reason was given without a wider mode.
`invalid justification: expected a non-empty sentence`	The reason is empty.
`timeoutMs is not available for this PTC runtime` / `sandbox_permissions is not available for this PTC runtime`	This setup's program runtime cannot honour that control, so the request is refused.

How a run works

Fresh each time. Each run works in its own process and ends; nothing is kept from one run to the next.
Calls from inside. The program calls the tools the chat may use as ordinary calls. Each call keeps its own approvals and limits, so a call that needs your answer still asks.
Only run_code is called directly. Where a chat works in code-call mode, a direct call that names any other tool fails, and the answer tells Oda to reach that tool from inside a program instead.
Plain names for calls. The names a program uses to call tools must be plain identifiers. One that is not a plain identifier, that the language reserves, or that the run's own environment keeps is refused before the run starts; $tools, lambda and console are refused.
Unfinished calls. When the program returns, calls that had already started settle before the run closes; a call that never started is dropped instead of run.
An empty environment. Apart from a few system names it needs to start other programs, the run starts with an empty environment: it cannot read the variables you have set on your computer.
Five log levels. A program prints at five levels: log, info, warn, error and debug. The lines are captured as they are printed and come back with the run.
Output arrives at the end. Nothing the program prints is shown while it runs; the printed lines and the returned value come back together when the run settles.

Time and output limits

What	The limit
Default budget	120,000 ms (about two minutes).
Ceiling	600,000 ms (ten minutes); a longer request is capped, and a lower ceiling can apply in some setups.
The request	Only a positive number of milliseconds; zero does not switch the deadline off.
What the budget covers	The whole run, including the time it spends waiting for the calls it makes and for your answers. It counts elapsed time, not processor time.
Output	The printed lines and the returned value share a cap of 67,108,864 bytes (64 MiB). Past the cap, the fitting part of the output is kept.
Memory	The program's own heap ceiling is 512 MiB; it is not a total memory cap for everything the run starts.

When the budget runs out, the run ends as a timeout failure reading execution deadline reached (120000ms) when the default expired; the output produced before the deadline is kept.
Every run started from a chat has a deadline; a run that another part of Oda starts, such as a workflow, can be given none. run_code itself accepts only a positive number.

Wider access for one run

When the program tries to change files the chat's mode does not allow, the change is denied, and Oda can ask to run the same program once more with wider access.

The ask. The request carries a wider mode and a one-sentence reason, and nothing runs before you answer. The card and your choices are on When Oda needs more access.
That run only. If you allow it, the wider mode covers that complete program run: the chat keeps its mode, and the calls the program makes keep their own policies and approvals.
After a denial. Oda asks only after the run was denied. Before retrying, it checks what the earlier attempt already did, because earlier effects may have completed.
Never on its own. A program is never repeated automatically; a new attempt needs a new call, and a new wider request needs a new answer.

How the result reads

A finished run returns the printed lines and the value the program returned, and two texts stand in for special outcomes:

Nothing printed, nothing returned. (run_code completed with no output).
A failed run. code run failed (<kind>): <message>; when the program printed anything before it failed, the fitting part of that output follows under Captured output:. A failed run also keeps the file-limit facts it ran under: File sandbox enforcement is partial on this host. says the limits could only be applied partly on this computer, and when the sandbox denied an operation, the failure text says so and names the mode the run used, as in File sandbox: <mode>; enforcement: <e>; operation denied.

The word in the parentheses names what ended the run:

Kind	What it means
`exception`	The program hit an error, or it could not be understood and did not run.
`timeout`	The run reached its time budget.
`abort`	The run was stopped; a stopped run reports as an abort.
`worker-exit`	The run's process ended early, or its cleanup did not finish cleanly.
`invalid-output`	The value the program returned cannot be carried as plain data.
`output-limit`	The run produced more output than the cap allows, so the fitting part is kept.
`protocol`	The run's own communication became malformed or too heavy, so the run was stopped.
`sandbox-unavailable`	The limits the run asked for could not be applied on this computer, so the run did not start rather than run without them.

Values must be plain data. Values cross between the program and Oda as text, numbers, true or false, lists and objects, with no gaps or special values. A value that cannot make the trip fails the run and is reported with a standard line, such as program completion must be lossless JSON, program threw an unrenderable value, binding arguments must be lossless JSON, binding resolution must be lossless JSON or cannot encode a sparse JSON array.
The calls stay on the run. The tools the program calls are recorded with the run and never become messages of their own; only the run's printed lines and returned value continue the chat. Tool catalog and session events covers what the record keeps.
A stopped run keeps its output. The lines produced before a stop are kept, and the failure kind is abort. What a stop leaves behind is on Stopping Oda and queued messages.

Questions, answered

What does Oda send when it calls `run_code`?

The program and a short description of it. The program is the body of an async function, and the description says what it does in five to ten words. A call may also add a longer time budget and, for a run that needs it, a wider file-access mode with a one-sentence reason. A request that does not fit is refused before anything runs.

What is the run's short description for?

It says what the program does, in five to ten words in active voice, and it is what the run shows as its title in the chat. Every call carries one.

How is a run's time budget counted?

As elapsed time for the whole run, including the time it spends waiting for the calls it makes and for your answers. It is not a measure of processor time, so a run that mostly waits still reaches its deadline.

Can a run have no time limit?

Not a run started from a chat: run_code accepts only a positive number of milliseconds, the number is capped at the maximum, and zero does not switch the deadline off. Runs that other parts of Oda start, such as a workflow, can be requested without a deadline; the chat's tool cannot.

What does the `justification` do?

It is the one-sentence reason for asking wider file access. It is required together with a wider mode, and it is shown to you before the program starts. The widening covers that complete program run only.

Which console methods can a program print with?

Five: log, info, warn, error and debug. The lines are captured as the program prints them and come back with the run when it ends.

What happens to a call that is still waiting when the program ends?

It does not run. The run closes after the calls that had already started settle, and a call that never started is dropped. Nothing is retried on its own: before a new attempt, Oda checks what the earlier run already did.

What does a failed run keep from what it printed?

The fitting part of the lines printed before the failure, under Captured output:. The run also keeps the file-limit facts it ran under, including File sandbox enforcement is partial on this host. when the limits could only be applied partly on your computer.