CodeRunnerToolOptions
Interface: CodeRunnerToolOptions
Defined in: src/core/codeRunnerTool.ts:67
Properties
checkIn?
readonlyoptionalcheckIn?:CheckInDemand<{code:string; }>
Defined in: src/core/codeRunnerTool.ts:97
Demand a human check-in before code runs — 'always', or a predicate over
the code string. A pause here does NOT tear the session down.
description?
readonlyoptionaldescription?:string
Defined in: src/core/codeRunnerTool.ts:75
Description the model sees. A sensible one is composed from scope +
language when you do not pass one.
language?
readonlyoptionallanguage?:string
Defined in: src/core/codeRunnerTool.ts:89
Default language for the code the model writes. Default 'python'.
maxOutputChars?
readonlyoptionalmaxOutputChars?:number
Defined in: src/core/codeRunnerTool.ts:92
Per-stream ceiling for what reaches the model, in characters. Default 4000. Anything cut is STATED in the result, never dropped quietly.
name?
readonlyoptionalname?:string
Defined in: src/core/codeRunnerTool.ts:72
Tool name the model sees. Default 'run_code'.
needs?
readonlyoptionalneeds?:CredentialNeed
Defined in: src/core/codeRunnerTool.ts:100
A credential this tool needs (declare-and-push). Resolved before execute. Do NOT cache it past the call: a session outliving a run outlives its token.
runner
readonlyrunner:CodeRunner
Defined in: src/core/codeRunnerTool.ts:70
The backend. localCodeRunner() for a dev loop, agentCoreCodeRunner(...)
for a real sandbox — the tool is identical across the swap.
scope?
readonlyoptionalscope?:CodeRunnerToolScope
Defined in: src/core/codeRunnerTool.ts:87
How long one session lives. Default 'run' — a turn's worth of work shares
one interpreter, and nothing outlives the turn.
'session' keeps the interpreter across the turns of one hosted
conversation (variables persist, files persist) and REQUIRES a
session-bound run plus a composition root that calls
agent.closeToolSessions({ sessionId }).
'call' starts and stops per invocation — the safest and the slowest.
timeoutMs?
readonlyoptionaltimeoutMs?:number
Defined in: src/core/codeRunnerTool.ts:94
Per-execution ceiling handed to the runner.
wants?
readonlyoptionalwants?:Readonly<Record<string,string>>
Defined in: src/core/codeRunnerTool.ts:130
Artifact arguments, declared exactly as any other tool declares them
(9.26.0): wants: { dataset: 'dataset/rows' }.
The model passes the art_… ref as the argument, the framework resolves
it before execute under the run's own scope — the same wants machinery,
with the same teaching refusals for a stale, unknown or wrong-kind ref —
and then this tool STAGES the resolved payload into the code session as a
file. The data reaches the interpreter without ever entering the context
window, which is the whole doctrine this tool exists for, now with an
inbound leg to match the outbound one.
── What the model's code reads ─────────────────────────────────────────
The staged files are named in the AF_STAGED_INPUTS environment variable,
a JSON object of argument name → path. The composed tool description
states it with a one-line example in the tool's language, so a model needs
nothing beyond the description to use it.
── Refused rather than degraded ────────────────────────────────────────
Declaring wants on a runner whose sessions cannot accept staged inputs
(stageInputs absent — agentCoreCodeRunner today) refuses BY NAME at
dispatch. Running the code without the data it declared would leave the
model reasoning about a file that is not there, which is the exact silent
failure this library refuses to ship.
Omitted, nothing changes: no schema properties are added, no session is ever asked to stage, and the description is the one earlier releases composed.