# gizai:agent/code

The agent's code mode: one tool call runs a JavaScript program the model wrote, which calls the thread's other tools as async functions (tools.NAME(input)) and returns one value. Many reads and joins cost the model one round instead of one each, which is what lets a small model finish a long job. The console runs the code with code/runner.js on the VM (vm/, no JIT), isolated from the machine (no file outside its folder, no network, no new machine code) and under memory, CPU and time limits. Each tool call comes back over the runner's pipes and runs here under the one Policy (the caller's).

```gizlang
import * as Code from "gizai:agent/code";
```

## Types

### `Engine`

```gizlang
type Engine = { sys: System; cli: string; toolchain: Vec<string>; vm: string; home: string; }
```

Where code runs: the host's CLI and the toolchain environment it builds with (apps.giz Fleet), the package's
sources (the VM entry package) and a folder of the host's own to keep the built runner in.

- `sys`: `gizlang_system.System`
- `cli`: `string`
- `toolchain`: `Vec<string>`
- `vm`: `string`
- `home`: `string`

### `Ran`

```gizlang
type Ran = { ok: bool; value: string; log: string; calls: i64; }
```

How a run ended: its value as JSON, or why it failed; what it printed; how many tool calls it made.

- `ok`: `bool`
- `value`: `string`
- `log`: `string`
- `calls`: `i64`

### `Call`

```gizlang
type Call = (name: string, input: string) => Answer
```

A tool the code called, by name with its input as JSON text: whether it succeeded and what it said.

### `Answer`

```gizlang
type Answer = { ok: bool; text: string; }
```

A tool's answer: whether it succeeded and its text.

- `ok`: `bool`
- `text`: `string`

## Functions

### `warm`

```gizlang
function warm(e: Engine): void
```

Builds the runner ahead of the first run (the host starts it): the first build of the VM takes minutes on a host
whose build store lacks its units, longer than a turn waits. It builds again even when the runner is there: its name
does not say which VM it holds, and a deploy that changes the VM restarts the host (cached units: seconds).

Effects: fail, read, write, io.

### `run`

```gizlang
function run(e: Engine, code: string, call: Call): Ran
```

Runs `code` with its tool calls answered by `call`: its value, log and call count, or why it did not run.

Effects: fail, read, write, console, io.

## Constants

### `MOST_MS`

```gizlang
const MOST_MS = 120000
```

One run's whole time, its tool calls included.

### `MOST_CALLS`

```gizlang
const MOST_CALLS = 100
```

The most tool calls one run makes.

### `MOST_CODE`

```gizlang
const MOST_CODE = 20000
```

The most characters of code, of its value and of what it printed.