The Open Framework for Building Agents
issue: TBD status: proposed last_updated: "2026-10-21"
Native code mode
Summary
Deferred tools and skills (#4400) gave every agent one
catalog of tools, agents, connection tools, and skills, reached through fixed
tools that never change the tools array. That work reserved one more name
for code mode. This doc fills it in.
eve__execute(opts: { code: string }): Promise<{
result?: unknown; // the program's JSON return value
error?: string; // why the program failed, when it did
logs?: string[]; // console output
calls: Array<{ tool: string; status: "completed" | "failed" | "denied" | "cancelled" }>;
}>;
The model writes a JavaScript program. The program calls catalog entries and direct tools by name, composes their results, and returns one value. Only that value and a short call summary go back to the model, so intermediate data never enters the conversation.
const issues = await tools.linear__list_issues({ teamId: "ENG", first: 50 });
const stale = issues.nodes.filter((issue) => issue.state.type === "started");
const reviews = await Promise.all(
stale.map((issue) =>
tools.billing_specialist({ message: `Check whether ${issue.identifier} blocks a refund.` }),
),
);
return stale.map((issue, i) => ({ id: issue.identifier, review: reviews[i] }));
- Opt-in per agent.
defineAgent({ codeMode: true })addseve__execute. The setting is fixed for each deployment, so thetoolsarray never changes within a session. Everything else in the catalog design stays as it is:eve__search,eve__tool, andeve__skillkeep their behavior. - A program is a batch of
eve__toolcalls. Eachtools.<name>(input)call resolves through the step catalog and runs on the same dispatch path as a model-issued call. That covers input validation, approval, connection sign-in, workflow runs, child sessions, stubs, hooks, labels, and eval facts.eve__tool({ name, input })is a one-call program. - One name everywhere. Programs call entries by their flat catalog names,
such as
tools.linear__list_issuesandtools.crm__api__list_issues. These are the names used ineve__search,eve__tool, protocol actions, approvals, and evals. There is no second, nested naming scheme. - Inline first, park only to wait. Calls run inline inside the program.
The program interrupts only for a call that must wait: an approval, a
sign-in, a workflow tool, an agent, or a question. The
eve__executecall then parks durably and holds no compute. It resumes from a signed replay ledger, so completed calls never run again. - Agents are awaited, not tasked. Inside a program, an agent call resolves to the agent's reply. The execute call owns the child sessions, so they never appear in the model's task table.
workflow()is removed.eve__executedoes everything theworkflowprogram tool does and more, soeve/tools/workflowgoes away in the same release.- Cache stable. The
eve__executedefinition never changes within a deployment and names no tool. A program never adds a definition. The only listing change is one fixed sentence in the existingcatalogannouncement.
Why now
- The catalog exists. #4400 shipped a step catalog that resolves any name
to its entry and dispatches it like a direct call (
execution/catalog/,harness/execute-call.ts). Code mode needs nothing else for discovery or routing. All it adds is a runtime that issues many calls per model call. - Composition is where round trips go. Reconciling, filtering, fanning out, and joining across tools all cost one model step per call today, and every intermediate result stays in history for the rest of the session. Programs remove both costs.
- Prior art converged. pi and opencode v2 both shipped code mode in the last month, with signatures rendered from schemas and budgeted catalogs. Neither can pause a program mid-flight. Durable pause and resume is what eve adds.
- The runtime is vendored. eve already runs model-written JavaScript in
QuickJS through
@ai-sdk/code-mode1.0.94 for theworkflowtool, with signed continuations whose key comes from a durable step. The vendor script bundles it withrun, whose version comes from the exactrun2.1.2 devDependency pin inpackages/eve/package.json.
Current state
What #4400 left on main:
- Step catalog.
buildStepCatalog(execution/catalog/step-catalog.ts) builds one table per step from authored, dynamic, and subagent entries, split intoadvertisedanddeferredmaps. Connection tools resolve by prefix ownership (connectionEntryNamed). The catalog'sresolveturns aneve__tooloreve__skillcall into the call to its entry. - Which listed tools
eve__toolwill run.callableByNameaccepts deferred entries and any listed tool eve runs itself. It rejectseve__*tools and provider-run or client-run tools. - Dispatch path. After resolution, a call to an inline entry runs its
execute. A call to a workflow tool or agent returns aDISPATCHEDmarker from inside the AI SDK.toEntryStepandtoEntryStreamdrop the marker and rewrite the step so the harness sees the call as a call to its entry (harness/execute-call.ts). Only model history keepseve__tool. - Nested actions are gone.
harness/nested-actions.tsand the tool-call action'sparentCallIdwere deleted. The deferred-tools doc says code mode adds the field back.parentCallIdsurvives only in subagentsession.startedmetadata (protocol/message.ts). - Signatures.
renderToolSignature(tools/signature.ts) renders input and output JSON Schema as TypeScript, capped at 4,000 characters, withPromise<unknown>when there is no output schema.eve__searchreturns these signatures. - Connection results.
toConnectionToolResultalready describes itself as "what the model receives for the call and what a code mode program receives later". MCP results arrive asstructuredContent, otherwise as text, which is parsed as JSON when the tool declares no output schema. OpenAPI results arrive as untyped{ status, statusText, body }, because OpenAPI tools declare no output schema. - Tasks. Every agent tool is a
servetool, and theworkflowtool is atasktool. Each call returns a receipt, and the result arrives later in atask.resultmessage (docs/tools/tasks.md). workflow().tools/provided/workflow.tsruns{ js }in a durable workflow. The program step is pure QuickJS (execution/dynamic-workflow/program-step.ts). Eachctx.agent()call is a parking host call (createParkingHostToolinshared/workflow-sandbox.ts) that resumes from a signed continuation. Agent calls are capped bymaxSubagents, which defaults to 100 and allows 1 through 128. The tool can call agents hidden withtool: false.- Reserved name.
eve__executeis reserved, and eval assertions reject it with "reserved for code mode" (evals/reported-tool-name.ts).
Prior art
Read at pi
4ac0bd8
(code mode shipped in 0.99.0; PR #10040 was closed without merging) and
opencode
v2@4617210.
Both were read from source, not run.
| pi | opencode v2 | eve (proposed) | |
|---|---|---|---|
| Tool | codemode, off by default; auto-enabled by code-mode MCP servers |
execute, on by default |
eve__execute, per-agent codeMode: true |
| Input | JSON { code }, plus a Lark grammar for raw JavaScript on OpenAI |
JSON { code } |
JSON { code }; grammar form later, gated by evals |
| Callable from code | Active direct tools, plus every code-mode or deferred tool | Only tools with codemode !== false; direct and code tools are disjoint |
Every catalog entry, plus every listed tool eve__tool accepts |
| Built-in coding tools | Declared and callable | Direct only | Declared and callable |
| Names in code | Flat (tools.mcp__server__tool) |
Nested by namespace | Flat catalog names |
| Catalog | Tool description, budgeted at 3,000 tokens; deferred MCP tools never listed | System prompt baseline plus appended deltas, budgeted at 2,000 tokens; invariant description | Existing catalog announcement, unchanged; no inline signatures |
| Discovery in code | Async searchTools, describeTool, describeNamespace, ALL_TOOLS |
Synchronous search() with paging |
Async search(), same result as eve__search |
| Untyped outputs | string; MCP tools return the full CallToolResult |
string | null; MCP tools without a schema return unknown |
unknown |
| Nested calls | Same hooks; child ids <parent>/<n>; parentToolCallId events; record on parent |
Same before and after hooks; share the parent's call id; progress rows | Standard actions with parentCallId |
| Permissions | Extension tool_call hooks |
Each leaf calls permission.assert and waits in memory |
Entry approval policies; the program parks durably |
| Sign-in mid-program | Throws "Run /mcp to sign in" | Throws "Sign in from /mcps" | Parks until sign-in completes, then resumes |
| Runtime | QuickJS WASM in a worker thread, 256 MB heap, no default timeout | In-process acorn interpreter, no default limits | QuickJS (@ai-sdk/code-mode) in the app runtime, eve-set limits |
| Network | None | fetch, with no SSRF guard, permission check, or size cap |
None; HTTP goes through tools |
| Extras | store/load, models.*, image() |
File parts from child results | None at ship |
What we take
- From both: a fixed tool description with runtime rules only, TypeScript
signatures rendered from schemas,
unknownfor missing output types,consolecapture, and errors returned as data. - From pi: direct tools stay direct and are also callable from code, with no exposure enum. Flat names. Nested calls run every hook a direct call runs, and each carries a parent call id. The model learns direct tools' output types through their own definitions, not through the code tool. Failures list the calls that ran before them, with "they are not undone".
- From opencode:
executeas the name, catalog changes delivered as appended messages, and MCP result handling (structuredContent, otherwise text parsed as JSON, andisErrorthrows), which eve already matches.
What we don't take
- Catalog in the tool description (pi). Its listing changes whenever a server connects. eve's catalog stays in the append-only announcement.
- Budgeted inline signatures (both). #4400 decided the listing never names
a deferred entry. Deferring a tool is the author's choice to keep it out of
context, and code mode does not override that choice.
search()andeve__searchreturn signatures on demand. - Disjoint direct and code tools (opencode). It forces the model to pick a
surface for each tool. In eve,
deferredalready decides what is declared. fetchwithout policy (opencode). HTTP goes throughweb_fetchor connections, which enforce SSRF checks and authorization.- Failing on sign-in or approval (both). eve's harness can park, so a program parks too.
store,load, andmodels.*(pi). Session state and model calls already have eve surfaces (memory, Jev). Adding them to programs is a separate decision.
Principles
- One dispatch path. A nested call is a model call that a program
issued. It shares everything after name resolution with
eve__tool. No tool runs differently because a program called it. - One name per entry. The program, search results, protocol, approvals, stubs, and evals all use the catalog name, so deferring a tool, calling it directly, or calling it from code never renames it.
- Code mode composes; it does not decide visibility.
deferreddecides what the model sees.codeModedecides only whether the model can script calls. Programs reach exactly whateve__toolreaches. - Park, never fail, for waits. Anything that waits for a person, a sign-in, a workflow run, or an agent parks the program durably, exactly as it parks a direct call.
- Fixed per deployment. Whether
eve__executeexists, its schema, and its description depend only on agent config and eve version.
Design
Authoring API
import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.6-luna",
codeMode: true,
});
codeMode?: boolean, which defaults tofalse.- It applies to the agent that declares it, root or subagent. A root copy
started by the
agenttool follows the root. - It is static. Dynamic agent configuration can't set it, because that
would let the
toolsarray change between sessions of one deployment. defaultTools: falsedoesn't removeeve__execute.- An authored
agent/tools/eve__execute.tsis already a compile error under theevenamespace rule.
- It applies to the agent that declares it, root or subagent. A root copy
started by the
- Output schemas are the authoring lever. There is no per-tool code mode
setting. A tool's
outputSchemagives programs a typed result. See Output types. - Hidden agents. Programs reach what
eve__toolreaches, so an agent withtool: falsecan't be called from code. Settool: "deferred"to keep an agent out of the tool list while letting programs call it. This replacesworkflow()'s ability to call hidden agents.
Model surface
eve__execute
Input. One JSON schema,
{ code: string }, withrequired: ["code"]andadditionalProperties: false. The code is the body of an async function, so top-levelawaitandreturnwork.Description. Fixed for each deployment. It states runtime rules and names no tool. It mentions
eve__searchonly when the agent haseve__search, the same wayeve__tooladds its connections clause. A draft:Run a JavaScript program that calls your tools and returns one JSON value. Use it to chain, loop over, filter, or combine tool calls so intermediate data stays out of the conversation. Call any tool you can use as
await tools.<name>(input), using its exact name (tools["name"]when the name isn't an identifier), including tools found with eve__search.await search({ query })searches the same way inside the program. Calls resolve to the tool's output; a failed or denied call throws. There is no fetch, file system, timers, or imports.console.logoutput is returned with the result.Presence. The tool is present exactly when
codeModeistrue. It goes in the tool list after the other catalog tools.Label. People see
Run code, thenRan code, <n> calls. Nested calls have their own labels.
Listing. The catalog announcement keeps its rules: kinds, capped
namespaces, capped connections, no deferred names, and appended only on
change. With code mode on, its first sentence adds one fixed clause: "or call
several from eve__execute as tools.<name>(input)". The clause is fixed per
deployment, so it adds no churn.
Direct tools' output types. A model writing a program needs to know what
a direct tool returns, and the provider tool definition carries no output
type. With code mode on, each direct tool a program can call, and that has an
output schema, gets one appended line, the same way the endsTurn note is
appended (describeEntry):
In eve__execute, tools.read_file(input) resolves to: { content: string; path: string; totalLines: number; truncated: boolean; nextOffset?: number; image?: { ... } }
The line is a pure function of the schema, capped at 1,000 characters, and
omitted when the output is unknown. Deferred entries get their output types
from the signature in search results.
Programs
Globals
declare const tools: Record<string, (input?: object) => Promise<unknown>>;
declare function search(opts: { query: string; limit?: number }): Promise<{
results: Array<
| { tool: string; description: string; signature: string }
| { skill: string; description: string; path?: string }
>;
unavailable?: Array<{ connection: string; error: string }>;
}>;
declare const console: Pick<Console, "log" | "info" | "warn" | "error">;
tools.<name>(input)calls the entry with that exact catalog name.inputdefaults to{}. A connection's own name is its sign-in entry, soawait tools.linear()signs the user in and parks until they finish, aseve__tool({ name: "linear" })does.search()iseve__search, with the same input, ranking, namespace queries, 10-second listing bound, and result. It is an async host call, so searches can run concurrently and a search can count toward the call limit. Skill hits tell the model what to load witheve__skill; programs don't load skills.- Nothing else. There is no
fetch, file system, timers, imports, or ambient state. GuestDateandMath.random()are deterministic across replay.
What programs can call: whatever eve__tool can call
(callableByName), minus tools that end the turn:
| Entry | From code | Why |
|---|---|---|
| Deferred tools, workflow tools, agents | Yes | Catalog entries |
| Connection tools and connection sign-in entries | Yes | Catalog entries |
Listed tools eve runs (bash, read_file, …) |
Yes | eve__tool accepts them |
ask_question, sleep, and other workflow tools |
Yes | They park the program like any workflow tool |
eve__* (search, tool, skill, task, reply, execute) |
No | eve's own surface; search() replaces eve__search inside programs |
Provider-run and client-run tools (web_search) |
No | eve never runs them, so it can't return their result to a program |
endsTurn tools (no_reply) and the final output |
No | They end the turn, which only the model may do |
A name a program can't call fails the same way eve__tool fails: with the
closest names, or with "<name>" is in your tool list; call it directly.
Agents in programs
- Awaited. An agent call resolves to the agent's reply text, or to its
structured value when
outputSchemais given. It never returns a task receipt. Theeve__executecall parks durably while the child runs. - Input. The input is the agent tool's input without
taskId, plus an optionaloutputSchema. The program is a caller, likectx.agent, andoutputSchemastays a caller-side option, as tasks requires. Every call starts a new child session, asworkflow()does today. - Owned by the call. Child sessions belong to the
eve__executecall, not to the model's task table.eve__task_waitdoesn't see them, and they end when the call settles. Cancelling the call or the turn cancels them. - Failures throw. A failed child turn rejects at its call, so the program can catch it.
- The same rule covers
taskandserveworkflow tools. From code they resolve to their first result instead of a receipt.
Result
- Completed. The model receives
{ result, logs?, calls }.resultis the JSON return value.callslists each nested call's catalog name and final status, bounded at 256 entries. - Failed. The model receives
{ error, logs?, calls }, with the error message and the guest stack location.callsshows what ran before the failure, with the note that completed calls are not undone. The tool result is an error result. - Size. What reaches the model is capped at 10,000 estimated tokens, keeping the head and tail with a truncation note, as pi does. Programs should return only what the model needs.
- Raw values in programs. Programs receive each call's raw output, never
its
toModelOutputprojection. MCP media results arrive as content blocks. Forwarding media from a program to the model is out of scope at ship.
Execution and parking
model step ── eve__execute({ code }) ── program runs (QuickJS, app runtime)
│ tools.x(input)
▼
step catalog: resolve → validate input
┌──────────────────────┴───────────────────────┐
inline entry, approval not approval asks, sign-in needed,
needed: runs now, result in ledger workflow tool, agent, question
│ │ interrupt
▼ ▼
program completes → tool result execute call parks; harness dispatches
in the same model step the batch on the direct-call path
(one action per call, parentCallId)
│ batch settles
▼
program resumes from the continuation; the
ledger replays completed calls without
running them → completes or parks again
Where it runs. Programs run in the app runtime, never the sandbox, so credentials stay app-side. Sandbox tools reach the sandbox through their normal executors.
Inline first.
eve__executeis an inline tool. Its program runs inside the model step, and calls to inline entries that need no approval run immediately. Crash semantics match today's inline tools: a crashed step re-runs its program, and the idempotency guidance fordefineToolapplies.Parking. A call that must wait raises a code-mode interrupt. Concurrent calls that interrupt together form one batch. The step ends with the
eve__executecall pending. The harness stores the continuation in session state and dispatches each pending call exactly as if the model had called it:- an approval request for the nested action;
- a sign-in through the shared connection helper;
- a workflow run;
- a child session.
When every call in the batch settles, a program step resumes with their resolutions. Calls first reached after the replay frontier run normally, and may park again.
Resolutions. A completed call resolves with its raw output. A failed call, a denied approval (with the denial note), a failed sign-in, or a cancelled call rejects with an error the program can catch.
Continuation key. The signing key comes from a durable step, reusing
createWorkflowProgramContinuationSecurityStep, and is bound to the call. Continuations carry every recorded result in plaintext base64. They live in session state and the workflow event log, which already hold the same results.Steering. A new message while the program runs inline applies at the next step boundary, as it does for any inline tool. A new message while the call is parked aborts it the way it aborts an
executeworkflow tool. eve withdraws pending approvals and questions, cancels owned child sessions, and settles the call with{ error: "Stopped early because a new message arrived.", calls }.Turn cancellation cancels the call and everything it owns.
Limits. These are fixed, and there are no settings at ship:
| Limit | Value | Notes |
|---|---|---|
| Nested calls per execute call | 256 | The maxBridgeRequests default. Agent calls and searches count toward it |
| In-flight nested calls | 32 | The AI SDK default |
| Guest compute per program step | 30 s of guest execution (cpuTimeoutMs) |
Excludes time spent waiting on nested calls; replay counts, see below |
| Wall clock per program step | 5 min (timeoutMs) |
Includes inline nested calls; parked calls don't count. An estimate to tune |
| Memory, stack, source, console | AI SDK defaults (64 MiB, 2 MiB, 256 KiB, 64 KiB) | |
| Nested input and output | 1 MiB input, 4 MiB output per call | |
| Continuation size | 8 MiB | Over the cap, the call fails and tells the model to return less |
| Model-facing result | 10,000 estimated tokens | Head and tail kept |
Errors over a limit name the limit, such as
EXECUTE_CALL_LIMIT_REACHED: a program may make at most 256 calls; "linear__get_issue" was not called.
Compute and wall-clock time. run 2.1.8 added cpuTimeoutMs
(vercel-labs/run#78, which closed
vercel-labs/run#76). It counts
only guest execution, so time spent waiting on nested calls is free, and it
replaces the hidden 10,000-check interrupt cap. @ai-sdk/code-mode exposes it
as executionPolicy.cpuTimeoutMs and throws CodeModeCpuTimeoutError
(vercel/ai#23812). eve sets both
limits:
- The CPU limit needs a higher wall clock. Guest time never exceeds wall
time, so
runonly appliescpuTimeoutMswhen it is lower thantimeoutMs. Under the AI SDK's 30 s wall-clock default, a 30 s CPU limit would never trigger. The 5 min wall clock leaves room for inline nested calls, such as sandbox commands, on top of 30 s of guest compute. - Each program step starts a fresh budget. Each resume gets a new CPU budget, but it replays the guest source from the start. Replayed guest work counts toward that resume's 30 s, so the budget must cover the replayed prefix plus the new work.
- Over the limit, the program fails instead of parking.
runnever lets a pending interruption hide an exceeded budget. The execute call returns an error that names the limit.
Nested calls on the protocol
- Standard actions. Each nested call emits the standard action events
under its catalog name, with a restored optional
parentCallIdthat points to itseve__executecall.eve__executeis itself an action. - Child call ids are
<executeCallId>/<n>, in the order calls start. That order is deterministic across replay. Child sessions record the nested call id as theirparentCallId. - Everything keyed by name keeps working: approval policies,
approvalKey, recorded approve-always decisions, labels, display titles, hooks, audience policy, tool stubs (matched as direct calls, throughstubbedCall), andt.calledTool(...). - Replay. Resuming from a continuation doesn't re-emit events for completed calls. A crashed step re-emits them under the same ids, because the ids derive from program order.
- Clients may group actions by
parentCallId. Clients that ignore the field render them flat. The TUI, task card, and framework templates show nested calls under the execute row. - Model history holds only the
eve__executecall and its result. - Evals.
t.calledTool("eve__execute")becomes valid for agents with code mode on.reported-tool-name.tsstops rejecting the name.
parentCallId on actions is an additive protocol change. It ships with
protocol docs.
Output types
- No schema. Callable, and typed
Promise<unknown>. The description tells the model to narrow at runtime, or to return the value and read it in the next step. - Validation. When an entry declares an output schema, its output is
validated before a program sees it. A mismatch rejects with
InvalidToolOutput, so a signature never advertises a shape the tool doesn't return. Direct andeve__toolcalls are unchanged. - OpenAPI. Each operation derives
outputSchemafrom its success response schema, sobodyis typed. This also improveseve__searchsignatures for agents without code mode. - Build warning. For agents with
codeMode: true,eve buildandeve devwarn once for each authored tool without anoutputSchema, and name the tool file.
Cache invariants
These extend the six in deferred tools:
- Fixed tools. The presence, schema, and description of
eve__executedepend only oncodeModeand the eve version. - Deterministic notes. The output-type line on direct tools is a pure function of the schema.
- Programs add nothing. A nested call, park, sign-in, child session, or resume never adds a definition or a system message.
- Listing unchanged. The only difference is the fixed code-mode clause.
Removing workflow()
eve__execute covers everything workflow() does: fan-out and fan-in over
agents, structured output, catchable failures, and durable parking. It also
calls tools and connections. Keeping both would give models two JavaScript
tools.
- Removed.
workflow(),eve/tools/workflow, andexecution/dynamic-workflow/tool.ts. An agent that imports it fails to compile with:workflow() was removed. Set codeMode: true in agent.ts; programs call agents as tools.<name>({ message }). - Survives, generalized. The program step, the continuation security
step, and
shared/workflow-sandbox.tsmove behindeve__execute. The parking host tool becomes the interrupt for every waiting call kind. - Behavior differences to document in the migration:
- The call holds the turn instead of running as a task.
- Hidden agents need
tool: "deferred". - The 100-agent default becomes the 256-call limit.
- The program's input is
code, notjs.
Rollout
Pull requests
Stacked, following the #4400 shape.
A dependency PR lands first, while workflow() still exists. It bumps the
@ai-sdk/code-mode catalog entry to the release that includes
vercel/ai#23812, bumps the run pin
to 2.1.10, re-vendors, and sets cpuTimeoutMs and timeoutMs in
createWorkflowSandboxOptions. Both bumps go in the same PR: from run 2.1.8
on, a 10 s CPU limit applies by default, and without #23812 it surfaces as a
raw RunError. run is not in minimumReleaseAgeExclude, so 2.1.10 can be
installed from 2026-10-22 23:00 UTC. @ai-sdk/* is excluded and can be
installed as soon as it publishes.
| PR | Scope |
|---|---|
| [1/3] Runtime | codeMode on defineAgent; eve__execute and its description; programs on the generalized program step; nested resolution through the step catalog; inline runs, interrupts, and the program state in session state; nested approval, sign-in, workflow, and agent dispatch; steering and cancellation; parentCallId; labels and client grouping; removal of workflow() |
| [2/3] Types | Output-type notes on direct tools; output validation for program calls; OpenAPI output schemas; the build warning |
| [3/3] Tests | Every new test, below |
Docs and a minor changeset go with [1/3]: it adds a public option, changes
the protocol, and removes eve/tools/workflow. [2/3] carries a patch.
Tests
Captured-request unit test. One session with code mode on drives programs through:
- an inline tool, a deferred tool, and a connection tool in one program;
- an approval mid-program, both approved and denied;
- a sign-in mid-program;
- a foreground workflow tool;
- parallel agents with
outputSchema; search()followed by a call in the same program;- a call limit hit;
- a steering message while parked;
- compaction between programs.
It asserts the cache invariants and that nested calls never reach history.
Replay. After a resume, completed calls aren't re-invoked, events aren't re-emitted, and child ids are stable.
E2E.
- Extend
agent-deferred-toolswith a code-mode agent. Its world suites run on the mock model, which must calleve__execute. They cover approval keyed to the nested entry, the workflow tool parking and resuming, an agent fan-out, andt.calledToolon nested calls. - Its real-model suite covers cache reads after programs.
- Move the
workflow()evals inagent-subagentsandagent-cancellationtoeve__execute, written fresh against the new surface.
- Extend
New real-model evals, written as process narratives:
- Alice reconciles orders against payments and support tickets across two connections.
- Bob reads an export with
read_fileand checks each row against a connection. - A fan-out to parallel agents, combined with connection data.
- An MCP server with untyped outputs.
Measurements and ship gate
Run one task set in two arms, code mode off and code mode on, at a moderate and a large tool count. Measure task success, model calls, input tokens, cache read ratio, and latency.
- Composition tasks. Code mode must cut model calls and input tokens with no loss in success.
- Single-call tasks. No regression in success or latency.
- Cache. No regression in cache reads after programs or after discovery.
- World suites. No new nondeterminism.
- Recorded, not gated: whether agents with code mode still call
eve__tool. If they almost never do, a follow-up dropseve__toolfor those agents.
Defaulting codeMode to true is a separate decision, made after shipping
with this data.
Docs
agent-config:codeMode.concepts/built-in-tools: aneve__executesection, and the reserved-name list.tools/overview: why output schemas matter.tools/workflows: remove theworkflowtool section and add the migration.tools/tasks: agent and task calls inside programs.subagents:tool: "deferred"for agents only programs should call.connections/overview: connections in programs, and sign-in mid-program.evals/assertions: nested calls andeve__execute.- Protocol docs:
parentCallId.
Decisions and alternatives considered
| Decision | Chosen | Rejected |
|---|---|---|
| Name | eve__execute, reserved by #4400 |
execute (an ordinary authored name since #4400); codemode |
| Enablement | codeMode: true on defineAgent, fixed per deployment, off by default until measured |
Always on (unmeasured, and costs tokens for agents that never compose); derived from declarations (nothing in declarations signals intent); a dynamic setting (flips tools) |
| Relation to the catalog tools | Added beside eve__search, eve__tool, and eve__skill |
Replacing eve__tool at ship (one-call JSON calls are cheaper and well trained; revisit with data); search only inside code (opencode) |
| Dispatch | Every nested call resolves through the step catalog and runs on the direct-call path | A workflow-tool program like workflow(), re-implementing approval, sign-in, and dispatch inside a workflow run (a second path for every job) |
| Execution | Inline first; interrupt only to wait; ledger replay | Interrupt on every call (one durable step per call, with latency on every sequential await); a program that can't pause (pi, opencode) |
| Names in code | Flat catalog names | Nested owner paths such as tools.crm.api.list_issues (sketched in #4400; needs owner records and a second naming scheme) |
| What code can call | Whatever eve__tool accepts, minus turn-ending tools |
Per-tool codemode flags (opencode); pi's exposure enum; deferred entries only |
| Skills | Found by search(), loaded by the model with eve__skill |
Loading from a program (a skill instructs the model, not a program; neither pi nor opencode does it) |
| Agents in code | Awaited replies owned by the execute call; outputSchema allowed; a new child per call |
Task receipts in programs; continuing a child by taskId at ship |
| Catalog presentation | Existing listing plus one fixed clause; output types on direct tools; signatures from search | Budgeted inline signatures (overrides deferred); catalog in the tool description (pi) |
| Untyped outputs | Promise<unknown>; build warning when code mode is on |
Requiring output schemas; string (pi) |
| Input form | JSON { code } at ship |
Lark grammar at ship (provider-specific declaration, history normalization, and unverified on AI Gateway); see open questions |
workflow() |
Removed in the same release | Keeping a second JavaScript tool; a transition period |
| Network | None in programs | fetch (opencode has no SSRF guard or permission check) |
| Limits | Fixed AI SDK defaults plus eve CPU, wall-clock, continuation, and result-size caps | Settings on codeMode at ship |
Open questions
@ai-sdk/code-moderelease. The compute limit depends on vercel/ai#23812 merging and publishing. Until then, eve can't setcpuTimeoutMsthroughexecutionPolicy.- Raw JavaScript input. pi declares a Lark grammar for OpenAI models so
the model writes source instead of a JSON-escaped string. eve's
@ai-sdk/openai4.0.84 exposescustomTool. Shipping it means a provider-specific declaration, and normalizing calls to{ code }in history so a session can switch providers. It is worth one eval arm, after ship. - Continuing an agent from code.
workflow()can't, and neither can this design at ship. If evals show programs re-briefing the same agent, add a returned handle, not a rawtaskId. - Background programs.
workflow()ran as a task. Programs here hold the turn. If long fan-outs need the conversation to continue, a later option can run aneve__executecall as a task. - Media out of programs. Images from
read_fileor MCP content can't reach the model through a program at ship. opencode attaches them, and pi hasimage(). - Default on. Revisit after the ship gate.
Evidence limits
- Prior art is from source reading. pi
4ac0bd8and opencodev2@4617210were read, not run. Neither publishes cache-hit measurements. - Nothing is measured yet. Cache, cost, and success numbers come from the measurement arms above.
- Inline-first is unproven at scale. Its performance assumes most nested calls don't park. Programs that park on every call get one program step per call. That is no worse than one model step per call, but it isn't free.
- Continuation growth. The ledger re-serializes every recorded result on each resume. The 8 MiB cap is an estimate to tune against real programs.
- Time limits are estimates. The 30 s CPU and 5 min wall-clock limits aren't measured. Programs that park often spend more of each resume's CPU budget on replay.