eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,7 +3,7 @@ title: "Agent Configuration"
3
3
  description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
4
4
  ---
5
5
 
6
- An eve app's root agent uses files under `agent/` by default; a [flat layout](./reference/agent-files#flat-layout) places them directly in the app root instead. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
6
+ An agent's optional `agent.ts` calls `defineAgent` (from `eve`) to configure the model and other runtime behavior. The root agent's file lives at `agent/agent.ts`, or in the app root with a [flat layout](./reference/agent-files#flat-layout). Declared [subagents](./subagents) have their own `agent.ts` and accept the same configuration.
7
7
 
8
8
  ## Set the model
9
9
 
@@ -17,18 +17,17 @@ export default defineAgent({
17
17
  });
18
18
  ```
19
19
 
20
- For a static AI Gateway model ID, you can make the same source change from the
21
- project root with `eve set model anthropic/claude-opus-5.5` or from the local
22
- dev TUI with `/model anthropic/claude-opus-5.5`.
20
+ For a static AI Gateway model ID, make the same change with
21
+ `eve set model anthropic/claude-opus-5.5` from the project root or
22
+ `/model anthropic/claude-opus-5.5` in the local dev TUI.
23
23
 
24
- The root `agent.ts` can be omitted when no runtime config is needed. eve then selects its default `agent.ts` source at the same slot, configured with `openai/gpt-6-luna-fast` and `reasoning: "high"`; authoring the file replaces that source.
25
- When `agent.ts` is present, `model` is required.
24
+ Omit the root `agent.ts` to use `openai/gpt-6-luna-fast` with `reasoning: "high"`. When `agent.ts` is present, `model` is required.
26
25
 
27
- An `agent.ts` that configures a local agent, root or subagent, must export the value `defineAgent` returns, and a dynamic subagent resolver that selects a local agent must return one. The compiler rejects a plain object export with `Export defineAgent({...}) from "<path>".`
26
+ Every local `agent.ts`, root or subagent, must export the value `defineAgent` returns, and so must a dynamic subagent resolver that selects a local agent. The build rejects a plain object with `Export defineAgent({...}) from "<path>".`
28
27
 
29
- A config that selects a static Gateway model is compile-only. A config that contains a dynamic model or a direct-provider model instance remains a runtime entry because eve must resolve that authored value while the agent runs. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
28
+ A gateway model ID string routes through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). To call a provider directly and configure the model in code, pass a model instance. eve types it as `EveLanguageModel`, exported from `eve` and `eve/models`, and every AI SDK language model satisfies it.
30
29
 
31
- `model` accepts a gateway model id string, which routes through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). To call a provider directly and configure the model in code, pass a model instance. eve types it as `EveLanguageModel` (exported from `eve` and `eve/models`), which every AI SDK language model satisfies.
30
+ With a static Gateway model, `agent.ts` needs no code at runtime. A dynamic model or a model instance keeps `agent.ts` loaded at runtime, because eve resolves it while the agent runs. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
32
31
 
33
32
  Use eve's helpers for direct OpenAI or Anthropic access without installing another provider package:
34
33
 
@@ -41,42 +40,34 @@ export default defineAgent({
41
40
  });
42
41
  ```
43
42
 
44
- `openai()` from `eve/models/openai` defaults to `gpt-6-luna-fast`. Both helpers accept an optional native provider model ID and use `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. During local development they can also use credentials saved through `/login`. Deployments require their API key in the server environment.
43
+ `openai()` from `eve/models/openai` defaults to `gpt-6-luna-fast`. Both helpers accept an optional native provider model ID and read `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. In local development they can also use credentials saved through `/login`; deployments need the API key in the server environment.
45
44
 
46
- For a local ChatGPT subscription, use `chatgpt()` from `eve/models/openai` and sign in with `/login`. It defaults to `gpt-6-luna-fast` and cannot run in a deployment.
45
+ For a local ChatGPT subscription, use `chatgpt()` from `eve/models/openai` and sign in with `/login`. It defaults to `gpt-6-luna-fast` and can't run in a deployment.
47
46
 
48
- `/login` can switch a static Gateway string to an eve helper and manage its import. `/model` changes the selected model and settings immediately. Custom provider SDK calls and dynamic expressions retain their authored behavior and require manual source edits. You can still install an AI SDK provider package and pass its language model when you need provider-specific configuration.
47
+ `/login` can switch a static Gateway string to an eve helper and manage its import, and `/model` changes the selected model and settings immediately. Edit custom provider SDK calls and dynamic expressions by hand. For provider-specific configuration, install an AI SDK provider package and pass its language model.
49
48
 
50
49
  Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct model instance.
51
50
 
52
- For every OpenAI or Anthropic model call, eve fills the provider's end-user
53
- safety identifier from the active turn's
54
- [`auth.current`](./guides/auth-and-route-protection#what-reaches-ctxsessionauth)
55
- principal when you have not configured it. For OpenAI, the option is
56
- `providerOptions.openai.safetyIdentifier`; for Anthropic, it is
57
- `providerOptions.anthropic.metadata.userId`. The default value is a SHA-256
58
- fingerprint of the principal's authenticator, issuer, type, id, and subject;
59
- eve does not send the raw principal fields or attributes. The fingerprint
60
- follows the current caller when a later turn changes users. An authored value
61
- at either provider path takes precedence and is forwarded unchanged. When
62
- `auth.current` is `null`, eve does not add an identifier. The same rules apply
63
- to compaction calls.
64
-
65
- For AI Gateway model calls, eve sets `providerOptions.gateway.sessionId` to the
66
- `gen_ai.conversation.id` used by Agent Runs. By default, all turns in a
67
- conversation, including delegated subagents and compaction calls routed through
68
- Gateway, share that ID so their Gateway generations can be found together.
69
- Direct-provider calls do not receive the option. An authored `gateway.sessionId`
70
- takes precedence; AI Gateway hashes IDs longer than 256 characters.
71
-
72
- AI Gateway also uses this ID for
73
- [session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity),
74
- which tries the provider that served the session's previous call first, among
75
- the providers your routing settings allow, so that provider can read the prompt
76
- from its cache. The conversation
77
- appears as one session in the AI Gateway logs Sessions view. Affinity can move
78
- the pinned provider ahead of your `order`. To keep `order` exactly, set
79
- `sessionAffinity: false`:
51
+ eve fills some provider options by default. A value you set at the same path
52
+ wins and is sent unchanged.
53
+
54
+ | Option | Calls | Default value |
55
+ | -------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
56
+ | `providerOptions.openai.safetyIdentifier`, `providerOptions.anthropic.metadata.userId` | OpenAI and Anthropic model and compaction calls | SHA-256 fingerprint of the turn's [`auth.current`](./guides/auth-and-route-protection#what-reaches-ctxsessionauth) authenticator, issuer, type, id, and subject. Unset when `auth.current` is `null`. |
57
+ | `providerOptions.gateway.sessionId` | AI Gateway calls | The Agent Runs `gen_ai.conversation.id`, shared by every turn, delegated subagent, and compaction call in the conversation. |
58
+ | `providerOptions.openai.promptCacheKey` | Direct OpenAI and `chatgpt()` calls | SHA-256 hash of the session ID, unique per subagent session. |
59
+
60
+ The safety identifier never contains the caller's raw identity fields or attributes. It
61
+ follows the current caller when a later turn changes users. AI Gateway hashes
62
+ session IDs longer than 256 characters.
63
+
64
+ The Gateway session ID groups the conversation's generations into one session in
65
+ the AI Gateway logs Sessions view. It also drives
66
+ [session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity).
67
+ With affinity, AI Gateway first tries the provider that served the previous
68
+ call, so that provider can read the prompt from its cache. Affinity chooses only among the
69
+ providers your routing allows, but it can move one ahead of your `order`. To keep
70
+ `order` exactly, set `sessionAffinity: false`:
80
71
 
81
72
  ```ts title="agent/agent.ts"
82
73
  import { defineAgent } from "eve";
@@ -91,20 +82,12 @@ export default defineAgent({
91
82
  });
92
83
  ```
93
84
 
94
- For direct OpenAI and `chatgpt()` model calls, eve sets
95
- `providerOptions.openai.promptCacheKey` to a SHA-256 hash of the session ID,
96
- which helps OpenAI route a session's calls to the cache that holds its prompt
97
- prefix. Each subagent session gets its own key. An authored
98
- `openai.promptCacheKey` takes precedence. `chatgpt()` calls also send the key
99
- in the `session-id` header, which the Codex backend uses for cache routing.
100
- Gateway-routed calls do not receive the option.
101
-
102
85
  ### Use a local model
103
86
 
104
- To test against a model running on your own machine, point the AI SDK
105
- [OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
106
- at a local server. This works with any server that implements the OpenAI Chat
107
- Completions API, such as Ollama, LM Studio, llama.cpp, or vLLM. With
87
+ To test against a model on your own machine, use the AI SDK
88
+ [OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers).
89
+ It works with any local server that implements the OpenAI Chat Completions API,
90
+ such as Ollama, LM Studio, llama.cpp, or vLLM. With
108
91
  [Ollama](https://docs.ollama.com/api/openai-compatibility):
109
92
 
110
93
  ```bash
@@ -153,7 +136,7 @@ To select a model from the incoming prompt with an AI SDK decision model, use
153
136
  [`auto` from `eve/models`](./guides/decide).
154
137
 
155
138
  `model` also accepts `defineDynamic(fn)` from `eve/models` or `eve`. The function returns the
156
- model; a dynamic model has no compiled default.
139
+ model, and a dynamic model has no compiled default.
157
140
 
158
141
  ```ts title="agent/agent.ts"
159
142
  import { defineAgent } from "eve";
@@ -171,7 +154,7 @@ export default defineAgent({
171
154
  The function returns a Gateway model ID, a model instance such as an AI SDK language model, or a selection object. See
172
155
  [Dynamic capabilities](./guides/dynamic-capabilities) for the context and memo rules.
173
156
 
174
- - **When it changes.** eve evaluates before each ordinary model call. A memo keyed by
157
+ - **When it changes.** eve runs the function before each ordinary model call. A memo keyed by
175
158
  `ctx.turn?.id ?? null` keeps a choice for the turn; `ctx.session.id` keeps it until a deployment
176
159
  change. Switching models can reduce prompt-cache reuse.
177
160
  - **Failures stop the turn.** A thrown error or invalid selection fails the turn before the
@@ -179,10 +162,9 @@ The function returns a Gateway model ID, a model instance such as an AI SDK lang
179
162
  - **Serialization.** Only memo results must be JSON. The function can return a live provider
180
163
  instance built from those results. `ctx.model` is unavailable during model selection.
181
164
  - **Selection object.** `{ model, reasoning?, modelContextWindowTokens?, modelOptions? }`.
182
- When `modelContextWindowTokens` is omitted, eve reads it from the AI Gateway model catalog that
183
- `eve build` or `eve dev` recorded, so selecting a model makes no network request. A model that
184
- catalog doesn't list fails the turn: set `modelContextWindowTokens` for an unlisted, custom, or
185
- newly published model, or rebuild. Dynamic agents cannot set sibling `modelContextWindowTokens` or
165
+ Omit `modelContextWindowTokens` to read it from the AI Gateway model catalog that `eve build` or
166
+ `eve dev` recorded, without a network request. A model that catalog doesn't list fails the turn. Set
167
+ `modelContextWindowTokens` for an unlisted, custom, or newly published model, or rebuild. Dynamic agents cannot set sibling `modelContextWindowTokens` or
186
168
  `modelOptions` fields; return per-model values from the function.
187
169
 
188
170
  The `session.started` runtime identity does not include a model ID for a dynamic agent. Each public
@@ -190,10 +172,9 @@ The `session.started` runtime identity does not include a model ID for a dynamic
190
172
 
191
173
  ## Reasoning effort
192
174
 
193
- In an authored `agent.ts` with a static model, omitting `reasoning` uses the provider's default.
194
-
195
- Set `reasoning` to control the model's reasoning effort through AI SDK's
196
- provider-agnostic option:
175
+ `reasoning` sets the model's reasoning effort through AI SDK's provider-agnostic
176
+ option. In an authored `agent.ts` with a static model, omit `reasoning` to use
177
+ the provider's default.
197
178
 
198
179
  ```ts title="agent/agent.ts"
199
180
  export default defineAgent({
@@ -205,19 +186,18 @@ export default defineAgent({
205
186
  Supported values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`,
206
187
  `"medium"`, `"high"`, and `"xhigh"`. The selected model and provider determine
207
188
  which levels are available and how they map to provider-native settings. Use
208
- `modelOptions.providerOptions` when you need provider-specific reasoning controls.
209
- A dynamic model selection can return `reasoning` alongside `model` to override
210
- the agent-level setting for that selection. Omitting it inherits the agent setting;
211
- `"provider-default"` explicitly uses the provider's default.
189
+ `modelOptions.providerOptions` for provider-specific reasoning controls.
190
+ A dynamic model selection can return `reasoning` to override the agent setting;
191
+ omit it to inherit the agent setting.
212
192
 
213
193
  Run `eve set model --reasoning high` to update this field from the command line.
214
194
 
215
195
  ## Prompt caching
216
196
 
217
197
  eve caches prompts automatically for AI Gateway models and for Anthropic models
218
- it recognizes by provider or model id. Set `modelOptions.promptCache` on a
219
- directly called model to mark an unrecognized model as Anthropic (such as a
220
- Bedrock application inference profile) or to use a 1-hour cache:
198
+ it recognizes by provider or model id. On a directly called model, set
199
+ `modelOptions.promptCache` to use a 1-hour cache. It also marks an unrecognized
200
+ model as Anthropic, such as a Bedrock application inference profile:
221
201
 
222
202
  ```ts title="agent/agent.ts"
223
203
  import { bedrock } from "@ai-sdk/amazon-bedrock";
@@ -237,7 +217,7 @@ Gateway models; use `providerOptions.gateway.caching` instead.
237
217
 
238
218
  ## Compaction
239
219
 
240
- Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. eve adds the estimated fixed checkpoint-prompt envelope to the trigger count, so compaction starts sooner than the conversation-only estimate. Lower `compaction.threshold` (a fraction from 0 to 1) to compact sooner:
220
+ Compaction summarizes older turns as the conversation approaches the context window, and is on by default. The token count includes the fixed checkpoint prompt, so compaction starts before the conversation alone reaches the threshold. Lower `compaction.threshold`, a fraction from `0` to `1`, to compact sooner:
241
221
 
242
222
  ```ts title="agent/agent.ts"
243
223
  export default defineAgent({
@@ -252,9 +232,8 @@ See [Default harness](./concepts/default-harness#compaction) for how the loop ap
252
232
 
253
233
  ## Runtime limits
254
234
 
255
- Use `limits` for framework-owned runtime caps. `sessionUsage` decides when the
256
- current durable session must stop starting model calls. It receives the
257
- session's usage and returns `true` when the limit is reached:
235
+ `limits` sets eve's runtime caps. `sessionUsage` receives the session's usage
236
+ and returns `true` when the session must stop starting model calls:
258
237
 
259
238
  ```ts title="agent/agent.ts"
260
239
  export default defineAgent({
@@ -269,40 +248,40 @@ export default defineAgent({
269
248
  });
270
249
  ```
271
250
 
272
- `sessionTimeoutMs` sets how long a session may sit idle before eve completes it,
273
- for every session, including delegated sessions. It defaults to 30 days. The
274
- idle window starts at creation and restarts each time a turn settles, including
275
- turns that answer a message, clear or compact the context, or end in
276
- cancellation. A session never expires while a turn is open, including a turn
277
- held open while its [tasks](./tools/tasks) work or while it waits for a person
278
- to answer; the window restarts when that turn settles. Process restarts do not
279
- change the window. When the window elapses, eve emits `session.ended` with `outcome: "completed"` and
280
- releases every continuation address; the next qualifying channel message starts
281
- fresh. To carry an earlier conversation into the fresh session, pass it as
282
- [prior history](./channels/eve#start-from-prior-history). Set it to `false` to
283
- disable the timeout. Session expiration follows
284
- [run-data retention](#run-data-retention); a zero-retention session loses its
285
- stored payloads when it ends.
286
-
287
- `sessionUsage` gets two `TokenUsage` records (exported from `eve`) with
288
- `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and
289
- `costUsd`: `total` is everything
290
- the session has spent, and `window` is what it spent since the last approved
291
- continuation. `inputTokens` includes cache reads and writes. Subtract
292
- `cacheReadTokens` to count only new input; cache reads are the history a
293
- provider replays from its prompt cache on every step. `costUsd` is the model
294
- token cost in US dollars that AI Gateway reports with each step, not tool or
295
- infrastructure spend; it is unset when no step reported a cost.
296
-
297
- A window starts when the session's own budget prompt is accepted: `window` is
298
- `total` minus the session's
299
- [total](./concepts/sessions-runs-and-streaming#replies-and-narration) at that point. Before
300
- the first approval, `window` equals `total`. Accepting a budget prompt that a
301
- subagent relayed starts the subagent's window, not the parent's. The window
302
- stays the same across deployment handoffs and replays.
303
-
304
- When `sessionUsage` is omitted, the limit is `40_000_000` new input tokens per
305
- window:
251
+ `sessionTimeoutMs` sets how long any session, including a delegated session,
252
+ may sit idle before eve completes it. Omit it for 30 days, or set it to `false`
253
+ to disable the timeout. The idle window starts when the session is created. It
254
+ restarts each time a turn ends, including turns that clear or compact the
255
+ context or are cancelled. A session never expires while a turn is open, such as while its
256
+ [tasks](./tools/tasks) work or it waits for a person to answer. Process restarts
257
+ don't change the window.
258
+
259
+ When the window elapses, eve emits `session.ended` with `outcome: "completed"`
260
+ and releases the channel addresses, such as a Slack thread, that route messages
261
+ to the session. The next message at that address starts a new session. To carry the earlier conversation over, pass it as
262
+ [prior history](./channels/eve#start-from-prior-history). A session with
263
+ [zero retention](#run-data-retention) loses its stored payloads when it ends.
264
+
265
+ `sessionUsage` gets two `TokenUsage` records, a type exported from `eve`. `total` is everything the session has
266
+ spent, and `window` is what it spent since the last approved continuation. Each
267
+ record has these fields:
268
+
269
+ | Field | Meaning |
270
+ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
271
+ | `inputTokens` | All input, including cache reads and writes. |
272
+ | `cacheReadTokens` | History the provider replays from its prompt cache on every step. Subtract it from `inputTokens` to count only new input. |
273
+ | `cacheWriteTokens` | Input written to the prompt cache. |
274
+ | `outputTokens` | Generated output. |
275
+ | `costUsd` | Model token cost in US dollars that AI Gateway reports with each step. Excludes tool and infrastructure spend. Unset when no step reported a cost. |
276
+
277
+ `window` is `total` minus the session's
278
+ [total](./concepts/sessions-runs-and-streaming#replies-and-narration) when its
279
+ own budget prompt was last accepted. Before the first approval, it equals
280
+ `total`. Accepting a budget prompt that a subagent passed up starts the
281
+ subagent's window, not the parent's. The window survives redeploys and
282
+ replays.
283
+
284
+ Omit `sessionUsage` to stop at `40_000_000` new input tokens per window:
306
285
 
307
286
  ```ts
308
287
  ({ window }) => window.inputTokens - window.cacheReadTokens >= 40_000_000;
@@ -328,62 +307,65 @@ export default defineAgent({
328
307
  });
329
308
  ```
330
309
 
331
- Set `sessionUsage: false` to leave sessions uncapped. A callback that always
332
- returns `false` has the same effect. eve calls a configured callback before each model call once
333
- the window has usage. The model call that crosses a limit is allowed to finish
334
- because exact usage arrives after the call completes. Before the next model
335
- call, eve pauses the turn (`turn.paused`) and sends a deterministic
336
- continuation prompt with two options: **Continue** starts a new window and
337
- resumes the same turn, and **Stop** cancels the in-flight turn through the
338
- standard cancellation path (`turn.settled` with `outcome: "cancelled"`). Stop is a
339
- user decision, not an error. The session stays resumable; because it is still
340
- over budget after Stop, the next message raises a new prompt. Declining a
341
- delegated child's prompt cancels the root turn, which cascades to the whole
342
- delegation tree, so the delegating parent never receives an error result it
343
- could retry. A reply that answers neither option is queued while the existing
344
- prompt stays pending; eve does not raise another
345
- copy or start another turn. The reply waits unconsumed, and the held turn consumes it
346
- (`delivery.consumed`) once the budget is granted.
347
-
348
- For sessions already waiting on a continuation prompt from an older deployment,
349
- the previous turn has completed. A non-answer message still queues behind the
350
- existing prompt, but emits no event until Continue is chosen. Continue starts a
351
- new turn and receives the queued message once; it does not reopen the completed
352
- turn or duplicate the prompt.
353
-
354
- Sessions that cannot request input from a human, such as markdown schedules and
355
- delegated runs without input proxying, skip the prompt and fail the next model
356
- call with `SESSION_USAGE_LIMIT_REACHED`. Its details carry the `total` and
310
+ Set `sessionUsage: false`, or a callback that always returns `false`, to leave
311
+ sessions uncapped. eve calls a `sessionUsage` callback before each model call
312
+ once the window has usage. The model call that crosses a limit finishes, because
313
+ exact usage arrives after the call completes. Before the next model call, eve
314
+ pauses the turn (`turn.paused`) and sends a continuation prompt:
315
+
316
+ | Option | Result |
317
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
318
+ | **Continue** | Starts a new window and resumes the same turn. |
319
+ | **Stop** | Cancels the turn (`turn.settled` with `outcome: "cancelled"`), not an error. The session stays resumable, but because it is still over budget, the next message prompts again. |
320
+
321
+ Declining a delegated child's prompt cancels the root turn and the whole
322
+ delegation tree, so the parent never receives an error result it could retry.
323
+
324
+ A message that answers neither option waits behind the open prompt. It starts
325
+ no second prompt or turn. After **Continue**, the paused turn receives it
326
+ (`delivery.consumed`).
327
+
328
+ If an earlier deployment showed the continuation prompt, that turn has already
329
+ ended. A message that answers neither option waits behind the prompt and emits
330
+ no event until **Continue**. **Continue** starts a new turn that receives the
331
+ waiting message once.
332
+
333
+ Some sessions can't request input from a human, such as markdown schedules and
334
+ delegated runs without input proxying. They skip the prompt and fail the next
335
+ model call with `SESSION_USAGE_LIMIT_REACHED`. Its details carry the `total` and
357
336
  `window` usage the check saw.
358
337
 
359
338
  Each subagent session checks its own usage against its own `sessionUsage`, or
360
- the root agent's when it authors none. A dynamic subagent can't select
361
- `sessionUsage` at runtime and always uses the root agent's. Remote agents run
362
- under their own deployment's limits.
363
-
364
- A child's usage, including what the child's own subagents spent, also counts
365
- in the parent's usage. An agent task's usage counts with each reply it
366
- sends. A turn it doesn't reply to, such as one a cancel stopped, counts with
367
- the next reply, or when the turn ends if no call waits for a reply. Sessions
368
- that any other `serve` workflow tool opens with `ctx.agent` count the same
369
- way; those of an `execute` or `task` tool count when the tool finishes. Remote
370
- agents' reported usage counts the same way, cost included. Approving a
371
- continuation starts a new window without erasing `total`.
372
-
373
- Some delegated usage doesn't count against the parent: a `ctx.agent` turn
374
- still running when its workflow tool finishes or is cancelled; the `ctx.agent`
375
- usage of an `execute` tool whose parent turn is cancelled while it waits; and
376
- what a cancelled agent task's own subagents spend after the task reports its
377
- cancelled turn. A cancelled agent task ends and sends no further reply. Usage
378
- reported by the cancelled run up to that point still counts against the parent
379
- when its usage report or final outcome arrives.
339
+ the root agent's when it authors none. A dynamic subagent always uses the root
340
+ agent's. Remote agents run under their own deployment's limits.
341
+
342
+ A child's usage, including its own subagents', also counts in the parent's
343
+ usage. Approving a continuation starts a new window without erasing `total`.
344
+ The parent counts delegated usage at these points:
345
+
346
+ | Delegated work | Counts against the parent |
347
+ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
348
+ | Agent task | With each reply. A turn with no reply, such as a cancelled one, counts with the next reply, or when the turn ends if no call waits. |
349
+ | `ctx.agent` session from any other `serve` workflow tool | The same way as an agent task. |
350
+ | `ctx.agent` session from an `execute` or `task` tool | When the tool finishes. |
351
+ | Remote agent | The same way as an agent task, cost included. |
352
+
353
+ Some delegated usage doesn't count against the parent:
354
+
355
+ - A `ctx.agent` turn still running when its workflow tool finishes or is cancelled.
356
+ - The `ctx.agent` usage of an `execute` tool whose parent turn is cancelled while it waits.
357
+ - What a cancelled agent task's own subagents spend after the task reports its cancelled turn.
358
+
359
+ A cancelled agent task ends and sends no further reply. Usage the cancelled run
360
+ reported up to that point still counts against the parent when its usage report
361
+ or final outcome arrives.
380
362
 
381
363
  ## Workflow world
382
364
 
383
- By default, eve selects the Workflow SDK world for the host: Vercel Workflow on
384
- Vercel, and the SDK's local world in local development or `eve start`. Advanced
385
- self-hosted deployments can select the Workflow world package to use from the
386
- root `agent.ts`:
365
+ The Workflow world is the backend that stores and runs sessions, so they survive restarts and redeploys. Omit
366
+ `experimental.workflow.world` to use Vercel Workflow on Vercel and the SDK's
367
+ local world in local development or `eve start`. Self-hosted deployments can
368
+ select a world package in the root `agent.ts`:
387
369
 
388
370
  ```ts title="agent/agent.ts"
389
371
  import { defineAgent } from "eve";
@@ -398,27 +380,26 @@ export default defineAgent({
398
380
  });
399
381
  ```
400
382
 
401
- Install that package in your app. It should export a default factory or
402
- `createWorld()` function. Pin a version built against the same `@workflow/*`
403
- line as your eve release (currently the `5.0.0-beta` line):
383
+ Install the package in your app; it must export a default factory or a
384
+ `createWorld()` function. Install a version built against the same
385
+ `@workflow/*` major version as your eve release, currently `5.x`:
404
386
 
405
387
  ```bash
406
- pnpm add @workflow/world-postgres@5.0.0-beta.x
388
+ pnpm add @workflow/world-postgres
407
389
  ```
408
390
 
409
- The npm `latest` tag can lag behind that line, so an unpinned install may pull
410
- an incompatible protocol version that the Workflow SDK rejects during initialization.
391
+ eve fails at startup, naming the version to install, when the world targets a
392
+ different major version.
411
393
 
412
- Put credentials and host-specific options in runtime environment variables read
413
- by the world package, not in `agent.ts`. For the Postgres world, that means
414
- putting the connection string or credentials in the env vars it reads. If the
415
- installed package must stay external in hosted output, list it in
416
- `build.externalDependencies`.
394
+ Put credentials, such as the Postgres connection string, and host-specific
395
+ options in the environment variables the world package reads, not in
396
+ `agent.ts`. If the package must stay external in hosted output, list it in
397
+ `build.externalDependencies`. See [Workflow worlds](./guides/deployment/workflow-worlds)
398
+ to choose a world and set up the Postgres world's database.
417
399
 
418
400
  ## Workflow checkpoint batching
419
401
 
420
- By default, eve commits a durable Workflow step after every model call and its
421
- inline tool calls. You can experimentally let one Workflow step run several
402
+ eve saves a Workflow step after every model call and its inline tool calls. `experimental.workflow.modelCallsPerStep` lets one step run several
422
403
  sequential model calls:
423
404
 
424
405
  ```ts title="agent/agent.ts"
@@ -434,44 +415,41 @@ export default defineAgent({
434
415
  });
435
416
  ```
436
417
 
437
- `experimental.workflow.modelCallsPerStep` is a positive-integer ceiling. It defaults to
438
- `1` and applies independently to each root agent or declared subagent. A higher
439
- value can reduce Workflow checkpoint overhead in sequential tool loops, but it
440
- widens the replay unit: if the Workflow step is interrupted, its earlier model
441
- calls and inline tool executions can run again. That can repeat provider costs,
442
- events, and side effects. Use stable idempotency keys for non-idempotent tools.
443
-
444
- eve ends a batch before it waits for input, authorization, or blocking
445
- coordination. A batch can also
446
- end below the configured ceiling when the turn completes or steering arrives.
447
- Before assistant output begins, steering can interrupt pending model generation.
448
- Executing tools finish safely before the batch yields and applies the correction.
449
- This option is experimental and may change or
450
- disappear in any release. See [Execution model and
451
- durability](./concepts/execution-model-and-durability#resuming-after-a-crash)
418
+ The value is a positive-integer maximum. Omit it for `1`. It applies
419
+ separately to each root agent or declared subagent. A higher value can reduce
420
+ save overhead in sequential tool loops, but more work runs again after a crash.
421
+ If the step is interrupted, its earlier model calls and inline tool calls can
422
+ run again, repeating provider costs, events, and side effects. Use stable
423
+ idempotency keys for non-idempotent tools.
424
+
425
+ A batch ends before eve waits for input, authorization, or other blocking work.
426
+ It can end below the maximum when the turn completes or steering arrives. Before assistant output begins, steering can interrupt pending model
427
+ generation; running tools finish before the batch yields. This option is
428
+ experimental and may change or disappear in any release. See [Execution model
429
+ and durability](./concepts/execution-model-and-durability#resuming-after-a-crash)
452
430
  for the retry behavior.
453
431
 
454
432
  ## Run data retention
455
433
 
456
- By default, eve derives run-data retention from the session's resolved
457
- [OpenTelemetry trace policy](./observability/otel#configure-opentelemetry):
434
+ Run-data retention is how long the Workflow World keeps a session's run data.
435
+ Omit `experimental.workflow.retention` to derive it from the session's resolved
436
+ [OpenTelemetry trace policy](./observability/otel#configure-opentelemetry) when
437
+ the session starts:
458
438
 
459
439
  - When the policy allows both inputs and outputs, eve uses the World's default
460
440
  retention period.
461
441
  - When the policy drops the trace or excludes either content direction, eve
462
- requests deletion as soon as the run ends with Workflow's
463
- `experimental_retention: 0`. Workflow cannot delete inputs and outputs separately.
442
+ requests deletion when the run ends (Workflow's `experimental_retention: 0`).
443
+ Workflow can't delete inputs and outputs separately.
464
444
 
465
445
  Without a custom policy, public conversations and development sessions use the
466
- World's default. Private and unknown-audience sessions outside development request
467
- `0`, even when no OpenTelemetry destination is installed. This decision is made
468
- when the session starts; destination export filters and lifecycle-provider
469
- policies do not change it.
446
+ World's default. Private and unknown-audience sessions outside development
447
+ request `0`, even with no OpenTelemetry destination installed. Destination
448
+ export filters and lifecycle-provider policies don't change the decision.
470
449
 
471
- Set `experimental.workflow.retention` explicitly to override this behavior.
472
- This override is experimental and has no compatibility promise.
473
- Use `0` to request deletion regardless of the tracing policy, or `"default"` to
474
- keep run data for the World's default period regardless of the tracing policy:
450
+ Set `experimental.workflow.retention` to `0` to always request deletion, or to
451
+ `"default"` to always keep run data for the World's default period. This
452
+ override is experimental and has no compatibility promise:
475
453
 
476
454
  ```ts title="agent/agent.ts"
477
455
  import { defineAgent } from "eve";
@@ -486,46 +464,45 @@ export default defineAgent({
486
464
  });
487
465
  ```
488
466
 
489
- The resolved value applies to every run that owns the session, including successor owners
490
- started after a deployment handoff, and to the run that collects session
491
- activity. Runs eve starts for other purposes keep the world's default: session
492
- timeouts and [workflow tools](./tools/workflows).
467
+ The resolved value applies to every run of the session, including runs after a
468
+ redeploy. Session timeout and [workflow tool](./tools/workflows) runs keep the
469
+ World's default.
493
470
 
494
- The value applies per agent. A [subagent](./subagents) that runs its own session
495
- uses its own explicit value or derives retention from its resolved trace decision,
471
+ Retention applies per agent. A [subagent](./subagents) with its own session uses
472
+ its own explicit value or derives retention from its resolved trace decision,
496
473
  including any inherited content ceiling. `experimental.workflow.world` is root-only.
497
474
 
498
475
  At `0`, supporting Worlds delete run and step inputs, outputs, and errors;
499
476
  event payloads; and stream contents when the run reaches a terminal state. The
500
477
  data remains available while the session is active. Run, step, and event records
501
- remain for the World's default period, including IDs, timestamps, statuses,
502
- step names, and attributes. Attributes can contain content, including eve's
503
- session title. This option does not delete local traces, exported telemetry, or
504
- data stored by tools, channels, or model providers.
505
-
506
- The Workflow World enforces deletion, not eve or the SDK. A World older than
507
- spec version 4 rejects `0`; a spec version 4 World without retention support
508
- keeps the data. Confirm support with your World provider. See
478
+ remain for the World's default period. These records include IDs, timestamps,
479
+ statuses, step names, and attributes, which can contain content such as eve's
480
+ session title. Local traces, exported telemetry, and data stored by tools, channels, or
481
+ model providers are not deleted.
482
+
483
+ The Workflow World enforces deletion. A World older than spec version 4 rejects
484
+ `0`, and a spec version 4 World without retention support keeps the data.
485
+ Confirm support with your World provider. See
509
486
  [Workflow data retention](https://workflow-sdk.dev/docs/observability/retention).
510
487
 
511
488
  > ⚠️ **At `0`, completed session transcripts become unreadable.** Deletion races reads of finished runs. Depending on the World, reading deleted session history returns either an empty stream or `410` with `code: "session_expired"`. Persist anything you need to keep from inside a tool, or set `retention: "default"` to preserve completed-session reads independently of tracing.
512
489
 
513
490
  ## Other defineAgent fields
514
491
 
515
- `defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
492
+ All other `defineAgent` fields are optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
516
493
 
517
- | Field | Type | Default | Description |
518
- | -------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
519
- | `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |
520
- | `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call, and [`promptCache`](#prompt-caching) settings. |
521
- | `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. Sessions complete after 30 idle days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it. |
522
- | `experimental` | `AgentExperimentalDefinition` | unset | Unstable opt-ins. `workflow.world` selects the Workflow world package on the root agent; `workflow.modelCallsPerStep` batches sequential model calls into a wider replay unit; `workflow.retention` controls how long the durable runtime keeps run data. |
523
- | `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |
524
- | `tool` | `boolean \| "deferred"` | `true` | Exposes this agent to its parent model as a tool. `"deferred"` keeps it out of the model's tool list; the model finds it with `eve__search` and calls it with `eve__tool`. On the root agent, controls the built-in `agent` tool. A subagent with `tool: false` remains callable from authored workflow tools through `ctx.agent()`. |
494
+ | Field | Type | Default | Description |
495
+ | -------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
496
+ | `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |
497
+ | `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call, and [`promptCache`](#prompt-caching) settings. |
498
+ | `limits` | `AgentLimitsDefinition` | field-specific | eve's [runtime limits](#runtime-limits). |
499
+ | `experimental` | `AgentExperimentalDefinition` | unset | Unstable opt-ins: [`workflow.world`](#workflow-world), [`workflow.modelCallsPerStep`](#workflow-checkpoint-batching), and [`workflow.retention`](#run-data-retention). |
500
+ | `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages unbundled and includes them in the hosted output. |
501
+ | `tool` | `boolean \| "deferred"` | `true` | Exposes this agent to its parent model as a tool. `"deferred"` hides it from the tool list until the model finds it with `eve__search` and calls it with `eve__tool`. On the root agent, controls the built-in `agent` tool. With `false`, authored workflow tools can still call a subagent through `ctx.agent()`. |
525
502
 
526
- `externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
503
+ `externalDependencies` only controls packaging; it doesn't authorize, configure, or review any third-party service those packages call.
527
504
 
528
- During `eve dev`, ordinary dependencies are bundled into each retained runtime generation. Packages listed in `externalDependencies` keep normal Node.js resolution instead, so replacing one of those packages requires restarting the dev server.
505
+ During `eve dev`, packages listed in `externalDependencies` use normal Node.js resolution instead of being bundled, so restart the dev server after replacing one.
529
506
 
530
507
  ## Where adjacent settings live
531
508