Programs Oda runs

Some tasks go better as one small program. DataMind Oda writes a program that calls its usual tools as ordinary steps, runs it, and the run appears in the chat as a step of its own. This page covers that run: what it shows, where it happens, what it may touch, and the limits and failure messages that come with it.

What a run is

One program and a short description. For each run, Oda writes the program and a description of it in five to ten words. The description appears on the step, and the step keeps the program itself, so you can read what ran.
Tools called from inside. The program calls the tools the chat may use, as ordinary calls. A call that needs your answer still asks, exactly as it would outside a program.
The only tool called directly in code-call mode. Where a chat works in code-call mode, this tool is the only one Oda calls directly; everything else is reached from inside the program. Tools and how they are offered explains the forms.
Plain names for calls. The names a program uses to call tools must be ordinary identifiers. A name that a language reserves, or that the program's environment keeps for itself, is refused before the run starts; $tools, lambda and console are refused.

What a run shows in the chat

The step's title is Oda's description. The short description is what you see on the run while it works and after it ends.
The calls, as they happen. The tools the program calls appear with the run as it works, each keeping its own record; Tool calls in the chat covers how call cards behave.
The output, when the run ends. The program's printed lines are not shown while it runs; they come back when it ends, together with the value it returned.
Nothing printed, nothing returned. A run that printed nothing and returned nothing says (run_code completed with no output).

Where a run happens

Its own process, fresh each time. Each run works on its own and ends; nothing is kept from one run to the next.
Under the chat's access mode. File changes follow the mode, like any other step: in Read Only the run may not change files, in Workspace Write it may change files inside the workspace folder, and in Full access no limits are applied. The tools the program calls keep their own approvals and limits.
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 can print at five levels: log, info, warn, error and debug. The lines are captured in the order they were printed and come back with the run.

Time and output limits

What	The limit
Time budget	120,000 ms (about two minutes) by default. Every run from a chat has a deadline, and it cannot be switched off; Oda can ask for a longer budget, and anything above the ceiling is capped at 600,000 ms (ten minutes).
What the budget covers	The whole run, including time spent 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 64 MiB (67,108,864 bytes). Past the cap, the fitting part of the output is kept and the run ends as an `output-limit` failure.
Memory	The program's own memory has a ceiling (a heap limit of 512 MiB by default). It is not a total memory cap for everything the run starts.

Approving a wider run

Denied first, then asked. When a program tries to change files the mode does not allow, the change is denied. Oda can then ask to run that one program once with wider access; nothing runs before you answer.
The reason is shown. The request carries the one-sentence reason Oda wrote for it, shown to you before the program starts. When Oda needs more access covers the card and your choices.
That run only. The widening covers that complete run: the chat keeps its mode, and the tools the program calls keep their own approvals and limits.
Never replayed on its own. A program is never repeated automatically; before trying again, Oda checks what the earlier attempt already did, because earlier effects may have completed.
How the limits were applied. The result reports how the file limits were applied on this computer, including File sandbox enforcement is partial on this host. when they could only be applied partly.

When a run fails

A failed run is not a broken chat: it comes back to Oda as an ordinary result, and Oda can adjust the work. The failure reads:

code run failed (<kind>): <message>

The word in the parentheses names the failure kind, and the detail after the colon says what happened. When the program printed anything before it failed, the fitting part of that output follows under Captured output:. A run out of time reads, for example, code run failed (timeout): execution deadline reached (120000ms).

Values must be plain data. Values cross between the program and Oda as plain data: text, numbers, true or false, lists and objects, with no gaps or special values. When a value cannot cross, the detail uses a standard line, such as program completion must be lossless JSON, program threw an unrenderable value, binding arguments must be lossless JSON or cannot encode a sparse JSON array.

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; 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 could not be applied on this computer, so the run did not start; Oda never runs a program without its limits.

Questions, answered

Why does Oda sometimes write a program?

Some tasks go faster as one program: it calls the tools it needs as ordinary steps and returns one result, instead of a long line of separate calls. Whether a chat works this way is decided when its agent is set up; Tools and how they are offered explains the forms.

Where does a program run?

On your computer, in its own fresh process, under the chat's access mode. File changes follow the mode like any other step, the run starts with an empty environment, and nothing is kept from one run to the next.

Which tools can a program call?

The tools the chat may use. It calls them as ordinary calls, and each call keeps its own approvals and limits, so a call that needs your answer still asks.

Why did a run ask to run with wider access?

The program tried to change files the chat's mode does not allow, so the change was denied and Oda asked to run that one program once with wider access. The request carries Oda's one-sentence reason and covers that complete run only. When Oda needs more access covers the card and how to answer it.

What happens if I stop the work while a program runs?

The run stops and reports as a stopped run: its failure kind is abort, and the output it produced before the stop is kept. What a stop leaves behind is on Stopping Oda and queued messages.

Can I read the program that ran?

Yes. The step keeps the program itself, so you can read the code that ran; its title is the short description Oda wrote for it.

What does `(run_code completed with no output)` mean?

The run finished cleanly, but the program printed nothing and returned nothing. What it did is recorded in the calls it made; the note stands in place of an empty output.

What do the failure kinds mean?

The word in the parentheses names what ended the run: exception, timeout, abort, worker-exit, invalid-output, output-limit, protocol or sandbox-unavailable. The table under When a run fails gives each meaning, and the detail after the colon says what happened.

What does a run leave in the chat?

The run's printed lines and its returned value come back when it ends, and the calls the program made stay recorded with the run. Only the run's own output and value continue the conversation; the calls inside the program do not become messages of their own. Tool catalog and session events covers what the record keeps.