eve 0.89.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 (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,11 +3,11 @@ title: "Built-in Tools"
3
3
  description: "The default and opt-in tools eve provides, including glob, grep, and sleep."
4
4
  ---
5
5
 
6
- eve provides a default tool set for every agent and additional tools you can add with one file. Each default occupies the same `agent/tools/<name>.ts` slot you would author yourself, so an authored definition replaces it and `disableTool()` removes it. Use this page to review what the model can call, opt into more capabilities, or override and disable defaults. For custom tools, see [Tools](../tools).
6
+ Built-in tools are framework tools eve provides: a default set every agent gets, and opt-in tools you add with one file. Each occupies the same `agent/tools/<name>.ts` slot you would author yourself, so an authored definition replaces it and `disableTool()` removes it. For custom tools, see [Tools](../tools).
7
7
 
8
8
  ## Default tools
9
9
 
10
- Default tools require no imports. The exact set depends on the agent and session, and the harness advertises only the tools available to the current session.
10
+ Default tools require no imports. The model sees only the defaults available to the current agent and session.
11
11
 
12
12
  ### Disable optional default tools
13
13
 
@@ -22,9 +22,7 @@ export default defineAgent({
22
22
  });
23
23
  ```
24
24
 
25
- This turns off the optional defaults described below. Add back only the tools the agent needs with the command in each tool's section. Existing files under `agent/tools/` remain available, including same-name replacements such as `agent/tools/bash.ts`.
26
-
27
- `defaultTools` doesn't affect [the catalog tools](#eve__search-eve__tool-and-eve__skill): eve adds them from what the session can reach, as listed in that section.
25
+ Add back only the tools the agent needs with the command in each tool's section. Files under `agent/tools/` stay available, including same-name replacements such as `agent/tools/bash.ts`. `defaultTools` doesn't affect [the catalog tools](#eve__search-eve__tool-and-eve__skill), which eve adds from what the session can reach.
28
26
 
29
27
  ### `bash`
30
28
 
@@ -45,7 +43,7 @@ export { default } from "eve/tools/bash";
45
43
  - `stdout`, `stderr`, and `truncated`: the output so far
46
44
  - `message`: instructions for the model
47
45
 
48
- The command keeps writing to `stdout` and `stderr` files in `outputDirectory` and writes its exit code to an `exit` file when it finishes. The model checks on or stops it with ordinary shell commands in later `bash` calls, so the tool's approval policy applies to them:
46
+ The command writes to `stdout` and `stderr` files in `outputDirectory`, and its exit code to an `exit` file when it finishes. The model checks on or stops it with shell commands in later `bash` calls, so the tool's approval policy applies to them:
49
47
 
50
48
  ```sh
51
49
  tail /tmp/.eve/jobs/3f9a1c2e/stdout # latest output
@@ -53,7 +51,7 @@ cat /tmp/.eve/jobs/3f9a1c2e/exit # exit code, once the command has finished
53
51
  kill -- -4312 # stop the command's whole process group
54
52
  ```
55
53
 
56
- The command keeps running across turns until it exits, the model stops it, or the sandbox stops. Its output files stay in the sandbox until the sandbox stops. Cancelling a turn stops a command that has not yet returned `running`. The `just-bash` provider has no background processes, so it runs every command to completion.
54
+ The command runs across turns until it exits, the model stops it, or the sandbox stops, and its output files last until the sandbox stops. Cancelling a turn stops a command that hasn't yet returned `running`. The `just-bash` provider has no background processes, so it runs every command to completion.
57
55
 
58
56
  Override its description, approval policy, or executor by wrapping the exported definition:
59
57
 
@@ -81,7 +79,14 @@ export default disableTool();
81
79
 
82
80
  ### `read_file`
83
81
 
84
- `read_file` reads text files from the sandbox with line-numbered output, and shows PNG, JPEG, GIF, and WebP images up to 3 MiB and 8000 pixels per side, and PDFs up to 20 MiB, to the model as files. Images and PDFs are detected from their bytes, so a missing or mismatched filename extension does not matter, and other text files are always read as text. It accepts absolute paths, paths relative to the workspace root where `bash` commands start, and paths beginning with `$HOME/`. Results and errors name the resolved absolute path.
82
+ `read_file` reads sandbox text files with line-numbered output. It also shows the model images and PDFs as files:
83
+
84
+ - PNG, JPEG, GIF, and WebP images up to 3 MiB and 8000 pixels per side
85
+ - PDFs up to 20 MiB
86
+
87
+ It detects images and PDFs from their bytes, so the filename extension doesn't matter.
88
+
89
+ It accepts absolute paths, paths relative to the workspace root where `bash` commands start, and paths beginning with `$HOME/`. Results and errors name the resolved absolute path.
85
90
 
86
91
  ```sh
87
92
  eve add tool/read_file
@@ -195,7 +200,7 @@ export default disableTool();
195
200
 
196
201
  ### `web_search`
197
202
 
198
- `web_search` uses provider-managed web search and appears only for supported model providers. AI Gateway models use Exa by default; direct provider models use their native search implementation.
203
+ `web_search` uses provider-managed web search and appears only for supported model providers. AI Gateway models use Exa unless you set `provider`; direct provider models use their native search.
199
204
 
200
205
  ```sh
201
206
  eve add tool/web_search
@@ -207,7 +212,7 @@ import { webSearch } from "eve/tools/web_search";
207
212
  export default webSearch({ provider: "exa" });
208
213
  ```
209
214
 
210
- Override the provider-managed configuration for AI Gateway:
215
+ Choose another AI Gateway search provider:
211
216
 
212
217
  ```ts title="agent/tools/web_search.ts"
213
218
  import { webSearch } from "eve/tools/web_search";
@@ -223,7 +228,7 @@ import { webSearch } from "eve/tools/web_search";
223
228
  export default webSearch({ provider: "browserbase" });
224
229
  ```
225
230
 
226
- Use a [Gateway model ID](../agent-config#set-the-model) to route searches through Browserbase. AI Gateway executes the search using `AI_GATEWAY_API_KEY` or Vercel project OIDC credentials; no `BROWSERBASE_API_KEY` is needed. See [Browserbase Search on AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers/web-search#using-browserbase-search).
231
+ Browserbase Search requires a [Gateway model ID](../agent-config#set-the-model). AI Gateway runs the search with `AI_GATEWAY_API_KEY` or Vercel project OIDC credentials, so no `BROWSERBASE_API_KEY` is needed. See [Browserbase Search on AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers/web-search#using-browserbase-search).
227
232
 
228
233
  Select the model vendor's own hosted search for a model routed through AI Gateway:
229
234
 
@@ -233,9 +238,19 @@ import { webSearch } from "eve/tools/web_search";
233
238
  export default webSearch({ provider: "native" });
234
239
  ```
235
240
 
236
- The vendor runs the search server-side and returns citations: OpenAI models use OpenAI web search, Anthropic models use Anthropic web search, and Gemini 3 and later models use Google Search grounding. AI Gateway uses its usual credentials, so no `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or Google key is needed. Every other Gateway model, including one picked by a dynamic model resolver, doesn't get `web_search`. That includes Gemini models before Gemini 3, which can't use Google Search alongside other tools.
241
+ The vendor runs the search server-side and returns citations:
242
+
243
+ | Model vendor | Search |
244
+ | -------------------------- | ----------------------- |
245
+ | OpenAI | OpenAI web search |
246
+ | Anthropic | Anthropic web search |
247
+ | Google, Gemini 3 and later | Google Search grounding |
248
+
249
+ AI Gateway uses its usual credentials, so no `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or Google key is needed. Every other Gateway model, including one picked by a dynamic model resolver and Gemini models before Gemini 3, doesn't get `web_search`.
250
+
251
+ eve picks the search tool from the requested model. A call that AI Gateway's `models` fallback serves with another vendor's model can therefore run without search.
237
252
 
238
- eve picks the search tool from the requested model, so when AI Gateway's own `models` fallback serves a call with a model from another vendor, that call can run without search. Anthropic web search runs only on Anthropic's own API. AI Gateway tries another host when Amazon Bedrock or Google Vertex AI rejects the tool. If no host accepts it, eve retries the step without `web_search`.
253
+ Anthropic web search runs only on Anthropic's own API. AI Gateway tries another host when Amazon Bedrock or Google Vertex AI rejects the tool. If no host accepts it, eve retries the step without `web_search`.
239
254
 
240
255
  Set `fallback` to give models without native search a provider that works with any Gateway model (`"exa"`, `"parallel"`, or `"browserbase"`):
241
256
 
@@ -247,7 +262,7 @@ export default webSearch({ provider: "native", fallback: "exa" });
247
262
 
248
263
  The `provider` setting applies only to AI Gateway models. Direct OpenAI, Anthropic, and Gemini 3 and later models always use their native search; other direct models omit `web_search`.
249
264
 
250
- eve identifies a direct model's vendor by its AI SDK provider name, so a `createOpenAI()` model pointed at an OpenAI-compatible endpoint, such as Amazon Bedrock's, gets OpenAI web search. When the endpoint rejects it, eve retries the step without `web_search`, so each step makes one rejected call first. To skip it, give the provider its own name:
265
+ eve identifies a direct model's vendor by its AI SDK provider name. A `createOpenAI()` model pointed at an OpenAI-compatible endpoint, such as Amazon Bedrock's, therefore gets OpenAI web search. When the endpoint rejects it, eve retries the step without `web_search`, so each step makes one rejected call first. To avoid that, give the provider its own name, so the agent gets no `web_search`:
251
266
 
252
267
  ```ts title="agent/agent.ts"
253
268
  import { createOpenAI } from "@ai-sdk/openai";
@@ -262,8 +277,6 @@ const mantle = createOpenAI({
262
277
  export default defineAgent({ model: mantle("openai.gpt-5.6-sol") });
263
278
  ```
264
279
 
265
- The agent then gets no `web_search`, the same as other direct models without native search.
266
-
267
280
  Replace provider-managed search with an authored implementation:
268
281
 
269
282
  ```ts title="agent/tools/web_search.ts"
@@ -304,7 +317,7 @@ To let the model choose an AI Gateway model for each root-copy task, export `age
304
317
  export { agentWithModel as default } from "eve/tools/agent";
305
318
  ```
306
319
 
307
- This is a separate workflow tool that calls `ctx.agent("agent", { model })`. The default `agent` tool remains unchanged and does not gain a `model` parameter. The opt-in definition accepts:
320
+ `agentWithModel` is a separate workflow tool that calls `ctx.agent("agent", { model })`; the default `agent` tool has no `model` parameter. It accepts:
308
321
 
309
322
  ```ts
310
323
  {
@@ -314,9 +327,9 @@ This is a separate workflow tool that calls `ctx.agent("agent", { model })`. The
314
327
  }
315
328
  ```
316
329
 
317
- It otherwise has the default tool's task behavior: a call returns a receipt, the result arrives later, and `taskId` continues the same root-copy session. The selected model applies to every turn in that session. A continuation must repeat the original model; start a new task to use another one. Because the parent model controls this value, use this tool only when it may choose among every model your AI Gateway credentials and policies allow.
330
+ It otherwise behaves like the default tool, and `taskId` continues the same root-copy session. The selected model applies to every turn in that session, so a continuation must repeat the original model; start a new task to use another. Because the parent model picks the value, use this tool only when it may choose any model your AI Gateway credentials and policies allow.
318
331
 
319
- An authored tool at `agent/tools/agent.ts` replaces the framework behavior. Re-export the default definition above to restore direct root-copy delegation, export `agentWithModel` to expose model selection, export another tool such as `agentRouter()` to change the model-facing behavior, or disable the slot. `agentRouter()` runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task), which adds `eve__task_wait` and `eve__task_cancel`:
332
+ An authored `agent/tools/agent.ts` replaces the framework tool. Re-export the default definition, export `agentWithModel`, export another tool such as `agentRouter()`, or disable the slot. `agentRouter()` runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task), which adds `eve__task_wait` and `eve__task_cancel`:
320
333
 
321
334
  ```ts title="agent/tools/agent.ts"
322
335
  import { disableTool } from "eve/tools";
@@ -326,46 +339,77 @@ export default disableTool();
326
339
 
327
340
  ### `eve__search`, `eve__tool`, and `eve__skill`
328
341
 
329
- These tools let the model reach what isn't in its tool list. `eve__search` finds tools defined with `deferred: true`, agents defined with `tool: "deferred"`, every tool from the agent's [connections](../connections), and deferred [skills](../skills). `eve__tool` calls a deferred tool, agent, or connection tool by name, and `eve__skill` loads a skill, deferred or not. There is no add command; eve adds each one when the session has something it reaches, even when `defaultTools` is `false`:
342
+ The catalog tools let the model reach what isn't in its tool list. `eve__search` finds tools defined with `deferred: true`, agents defined with `tool: "deferred"`, every tool from the agent's [connections](../connections), and deferred [skills](../skills). `eve__tool` calls a deferred tool, agent, or connection tool by name, and `eve__skill` loads a skill, deferred or not. There is no add command; eve adds each one when the session has something it reaches, even when `defaultTools` is `false`:
330
343
 
331
344
  - `eve__tool` comes with anything it can call: a deferred tool or agent, or a connection.
332
345
  - `eve__skill` comes with any skill, so an agent whose only catalog entries are listed skills gets `eve__skill` alone.
333
346
  - `eve__search` comes with anything it could find: whatever `eve__tool` can call, plus deferred skills.
334
347
  - A session with none of these gets no catalog tools.
335
348
 
336
- Entries the agent declares count from the session's first step. An entry a dynamic resolver returns counts from the step where it first appears, so a resolver in `agent/tools/` that returns only tools without `deferred: true` adds no catalog tools. Once a session's tool list includes a catalog tool, the session keeps it, even after a resolver stops returning the entry that brought it. The catalog tools change only when the session first reaches a new kind of entry, such as its first deferred tool or its first connection.
349
+ Declared entries count from the session's first step, and an entry a dynamic resolver returns counts from the step where it first appears. A resolver in `agent/tools/` that returns only non-deferred tools adds no catalog tools. Once a session has a catalog tool, it keeps it, even after a resolver stops returning the entry that brought it.
350
+
351
+ #### `eve__search`
352
+
353
+ `eve__search({ query, limit? })` returns the best matches, up to `limit` (default 10, at most 50). `query` is required and must contain a word. It isn't a regular expression, and eve ignores characters that can't appear in a name, such as a leading `^`.
354
+
355
+ | Match | Fields | Use with |
356
+ | -------------- | ------------------------------------------------------------------------------------------ | ------------ |
357
+ | Tool | `tool` name, `description`, and a TypeScript `signature` rendered from its schemas | `eve__tool` |
358
+ | Deferred skill | `skill` name, `description`, and the `path` of its `SKILL.md` when it has supporting files | `eve__skill` |
359
+
360
+ A very long signature drops its property descriptions before any property name. Next to `results`, `searched` counts the entries the query covered, and `remaining` counts the matches past `limit`. A connection behind sign-in counts as its one sign-in result, and an unavailable connection counts as none.
361
+
362
+ Tools and skills rank together, in tiers:
337
363
 
338
- - `eve__search({ query, limit? })` returns the best matches, up to `limit` (default 10, at most 50). `query` is required and must contain a word. A tool match has its exact `tool` name, its `description`, and a TypeScript `signature` rendered from its schemas. A very long signature drops its property descriptions before any property name. A deferred skill's match has its `skill` name, its `description`, and the `path` of its `SKILL.md` when it has supporting files. A result with `tool` is called with `eve__tool`, and one with `skill` is loaded with `eve__skill`. Next to `results`, `searched` counts the entries the query covered, the whole catalog or one namespace, and `remaining` counts the matches past `limit`. A connection behind sign-in counts as its one sign-in result until the user signs in, and an unavailable connection counts as none. Tools and skills rank together, in tiers: an entry whose name is exactly the query, then one whose name after its last `__` is the query, such as `linear__create_issue` or `sre__create_issue` for `create_issue`, then the tools of a connection named by the query, then entries whose names, or names after their last `__`, start with the query, then keyword matches in names, parameters, and descriptions. So `eve__search({ query: "linear" })` lists the `linear` connection's tools first. One-letter and filler words such as `a` and `the` don't count toward keyword matches unless the query has nothing else.
339
- - A query whose first word contains `__` searches one namespace: everything before its last `__`, without trailing underscores. The namespace only filters. `eve__search` keeps names under `<namespace>__` and anything named exactly the namespace, such as a connection's sign-in entry, then ranks them by the whole query, so `eve__search({ query: "linear__" })` returns only the `linear` connection's tools, or its sign-in result, and an exact name that contains `__` still ranks first. eve lists only the connections that can own names in that namespace, so other connections make no network call and don't appear in `unavailable`. A namespace that matches nothing fails with the closest connection names. Characters that can't appear in a name, such as a leading `^`, are ignored; `query` isn't a regular expression.
340
- - `eve__search` never asks the user to sign in. A connection whose server won't list its tools until the user signs in appears as one result named after the connection, such as `linear`; a connection whose server lists its tools without a token is searched like any other. A connection whose tools fail to load, or don't load within 10 seconds, appears under `unavailable` with its `error`, such as `"crm" did not list its tools within 10s. Try again later.` Matches from everything else are still returned, so a slow server doesn't hold up the search. An `eve__tool` call on that connection's tools fails with the same error.
341
- - `eve__tool({ name: "linear" })`, with a connection's own name, asks the user to sign in to that connection when its tools need it, and returns once they can be listed, so the next `eve__search` finds them. On a server that lists its tools without sign-in, it confirms the tools are available without asking.
342
- - `eve__tool({ name, input? })` calls the entry named `name` with `input`, which defaults to `{}`. A connection tool's name is `<connection>__<tool>`, such as `linear__list_issues`. eve checks `input` against the entry's input schema. An invalid input fails with the entry's signature, an unknown name fails with the closest names, and a skill's name fails with a reminder to load it with `eve__skill`. When the server asks for the user's authorization, the call asks the user to sign in and parks until sign-in completes. A connection tool call the server doesn't answer within 5 minutes is cancelled and fails with an error such as `"linear" did not answer list_issues within 5 minutes. It may still have run, so check before you retry.` The server may finish the call after eve stops waiting, so a tool that changes data may already have made the change.
343
- - `eve__skill({ name })` loads the named skill, deferred or not, and returns its instructions. An unknown name fails with the closest skill names, a tool's name fails with a reminder to call it with `eve__tool` or directly, and a name that matches a connection says to find its tools with `eve__search({ query: "<connection>__" })`.
364
+ 1. An entry whose name is exactly the query.
365
+ 2. An entry whose name after its last `__` is the query, such as `linear__create_issue` for `create_issue`.
366
+ 3. The tools of a connection named by the query, so `eve__search({ query: "linear" })` lists the `linear` connection's tools first.
367
+ 4. Entries whose names, or names after their last `__`, start with the query.
368
+ 5. Keyword matches in names, parameters, and descriptions. One-letter and filler words such as `a` and `the` don't count unless the query has nothing else.
344
369
 
345
- After `eve__tool` or `eve__skill` resolves its entry, the call runs exactly like a direct call to that entry. A skill load publishes `call.requested` with `capability: { kind: "skill", name }`, followed by `call.settled` for its outcome. Approval policies, workflow tools and tasks, agents, `endsTurn`, `toModelOutput`, hooks, and stream events all see the entry's own name and input, such as `linear__list_issues`. Only model history records the call as `eve__tool` or `eve__skill`.
370
+ A query whose first word contains `__` searches one namespace: everything before its last `__`, without trailing underscores. `eve__search` keeps names under `<namespace>__` and anything named exactly the namespace, such as a connection's sign-in entry, then ranks them by the whole query. `eve__search({ query: "linear__" })` returns only the `linear` connection's tools, or its sign-in result. Connections that can't own names in that namespace don't appear in `unavailable`. A namespace that matches nothing fails with the closest connection names.
346
371
 
347
- eve tells the model what it can reach in an append-only context message rather than in the system prompt: which kinds of deferred entries exist, up to 20 namespaces (the first `__` segment of deferred names, such as `sre` for `sre__list_alerts`), and up to 20 connections with their descriptions. It never names a deferred entry, so deferred entries stay out of context until `eve__search` finds them. A later step appends the listing again only when that changes; a deferred entry added to a listed namespace, or without one, changes nothing. After the session first reaches each kind of entry, adding or removing entries, signing in, or resolving more dynamic connections doesn't change the catalog tools, so the cached prompt prefix holds.
372
+ `eve__search` never asks the user to sign in. A connection whose server won't list its tools until sign-in appears as one result named after the connection, such as `linear`. A connection whose tools fail to load, or take longer than 10 seconds, appears under `unavailable`. Its `error` reads, for example, `"crm" did not list its tools within 10s. Try again later.` Matches from everything else still return. An `eve__tool` call on that connection's tools fails with the same error.
348
373
 
349
- The tools eve adds itself all live in the `eve` namespace: `eve__search`, `eve__tool`, `eve__skill`, `eve__task_wait`, `eve__task_cancel`, and `eve__reply`. Nothing you author or resolve may be named `eve` or start with `eve__`: tools, subagents, skills, connections, and extension mounts, static or dynamic, since a connection or mount named `eve` would own every `eve__` name. The compiler rejects an authored tool, skill, connection, or mount, such as `agent/tools/eve__search.ts`; eve rejects an authored subagent when the agent loads, and a dynamic entry when its resolver returns it. Any other name is free, including `search` and `execute`. A connection's own name is also the entry that signs the user in to it.
374
+ #### `eve__tool` and `eve__skill`
375
+
376
+ - `eve__tool({ name: "linear" })`, with a connection's own name, asks the user to sign in when the connection's tools need it. It returns once the tools can be listed, so the next `eve__search` finds them. If the server lists its tools without sign-in, it confirms they are available without asking.
377
+ - `eve__tool({ name, input? })` calls the entry named `name` with `input`, which defaults to `{}`. A connection tool's name is `<connection>__<tool>`, such as `linear__list_issues`. A call fails with the entry's signature when the input fails its schema, and with the closest names when the name is unknown. A skill's name fails with a reminder to use `eve__skill`. When the server asks for the user's authorization, the call asks the user to sign in and waits until sign-in completes.
378
+ - eve cancels a connection tool call that the server doesn't answer within 5 minutes. The call fails with an error such as `"linear" did not answer list_issues within 5 minutes. It may still have run, so check before you retry.` A tool that changes data may already have made the change.
379
+ - `eve__skill({ name })` loads the named skill, deferred or not, and returns its instructions. An unknown name fails with the closest skill names. A tool's name fails with a reminder to call it with `eve__tool` or directly. A connection's name says to find its tools with `eve__search({ query: "<connection>__" })`.
380
+
381
+ Once `eve__tool` or `eve__skill` resolves its entry, the call runs like a direct call. Approval policies, workflow tools and tasks, agents, `endsTurn`, `toModelOutput`, hooks, and stream events all see the entry's own name and input, such as `linear__list_issues`. Only model history records `eve__tool` or `eve__skill`. Loading a skill emits `call.requested` with `capability: { kind: "skill", name }`, then `call.settled`.
382
+
383
+ #### What the model is told
384
+
385
+ eve lists what the model can reach in an append-only context message, not the system prompt. The message lists:
386
+
387
+ - which kinds of deferred entries exist
388
+ - up to 20 namespaces, the first `__` segment of deferred names, such as `sre` for `sre__list_alerts`
389
+ - up to 20 connections with their descriptions
390
+
391
+ It never names a deferred entry, so deferred entries stay out of context until `eve__search` finds them. A later step appends the listing again only when it changes.
392
+
393
+ #### Reserved `eve` names
394
+
395
+ The tools eve adds itself live in the `eve` namespace: `eve__search`, `eve__tool`, `eve__skill`, `eve__task_wait`, `eve__task_cancel`, and `eve__reply`. No tool, subagent, skill, connection, or extension mount, static or dynamic, may be named `eve` or start with `eve__`. The compiler rejects an authored tool, skill, connection, or mount with such a name, such as `agent/tools/eve__search.ts`. eve rejects an authored subagent when the agent loads, and a dynamic entry when its resolver returns it. Any other name is free, including `search` and `execute`.
350
396
 
351
397
  ### `eve__task_wait` and `eve__task_cancel`
352
398
 
353
- eve adds `eve__task_wait` and `eve__task_cancel` when the agent has a tool that runs its calls as [tasks](/docs/tools/tasks): any agent tool, including the built-in `agent` tool, declared subagents, and remote agents, or a tool such as `agentRouter()`, the `workflow` tool, or an authored workflow tool that defines `task(input, ctx)` or `serve(receive, ctx)`. There is no add command, and the tools are not workflow tools. Like every `eve__` name, both are reserved.
399
+ eve adds `eve__task_wait` and `eve__task_cancel` when the agent has a tool that runs its calls as [tasks](/docs/tools/tasks). These are the built-in `agent` tool, declared subagents, remote agents, `agentRouter()`, the `workflow` tool, and authored workflow tools that define `task(input, ctx)` or `serve(receive, ctx)`. There is no add command.
354
400
 
355
- - `eve__task_wait({ timeoutSeconds? })` parks the turn until any task has a result, a new message arrives, or `timeoutSeconds` pass, and returns at once when a result is already waiting. While it waits, the turn stays running rather than pausing, since `turn.paused` only reports interactions. Results arrive in a `<task_result>` message right after it returns. Waiting never stops a task.
356
- - `eve__task_cancel({ taskId })` stops a task's current work and says so, or says the task had no work to stop when it already finished or is an idle [resumable task](/docs/tools/workflows#resumable-tasks-serve). An id that names no task fails with `UNKNOWN_TASK`. Cancelling an agent task ends it; other resumable tasks stay available after a cancel.
401
+ - `eve__task_wait({ timeoutSeconds? })` waits until any task has a result, a new message arrives, or `timeoutSeconds` pass. It returns at once when a result is already waiting. The turn stays running, not paused, because `turn.paused` only reports approvals, questions, and other requests for input. Results arrive in a `<task_result>` message right after it returns. Waiting never stops a task.
402
+ - `eve__task_cancel({ taskId })` stops a task's current work and says so. When the task already finished or is an idle [resumable task](/docs/tools/workflows#resumable-tasks-serve), it says the task had no work to stop. An id that names no task fails with `UNKNOWN_TASK`. Cancelling an agent task ends it; other resumable tasks stay available after a cancel.
357
403
 
358
404
  Review these tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
359
405
 
360
- You can also add the opt-in framework tools described below.
361
-
362
406
  ## Opt-in framework tools
363
407
 
364
- These framework-provided tools are not added by default. Add only the ones the agent needs.
408
+ These tools are not added by default. Add only the ones the agent needs, and remove the file to remove the tool; `disableTool()` is unnecessary.
365
409
 
366
410
  ### `ask_question`
367
411
 
368
- `ask_question` lets the model ask the user one question, then waits for the answer. The model can offer two or three options, each with a label and a short description, and the user can always type their own answer instead. Channels render the options as native UI, such as Slack select menus. Without the tool, the model can still ask in its reply text and the user answers with their next message. See [Human-in-the-loop](/docs/human-in-the-loop). Add it:
412
+ `ask_question` lets the model ask the user one question, optionally with two or three options, and waits for the answer. [Human-in-the-loop](/docs/human-in-the-loop#questions) covers its input, results, and how channels show it. Add it:
369
413
 
370
414
  ```sh
371
415
  eve add tool/ask_question
@@ -377,7 +421,7 @@ import { askQuestion } from "eve/tools/ask_question";
377
421
  export default askQuestion;
378
422
  ```
379
423
 
380
- `ask_question` is a [workflow tool](/docs/tools/workflows) that calls `ctx.ask()`. The model receives `{ status: "answered", answer }`, where `answer` is the chosen option's label or the user's own words. A plain follow-up message answers the question too when it is the first open request and the message matches an option or the question allows free text; see [Several requests at once](/docs/human-in-the-loop#several-requests-at-once). A steering message that doesn't answer it withdraws the question: `ask_question` resolves as `{ interrupted: true }`, which the model reads as `Stopped early because a new message arrived.`, and the model reads the message next. In a session that cannot request input, such as a [markdown schedule](/docs/schedules#markdown-form-fire-and-forget), the result is `{ status: "unavailable" }` and the model continues on its own judgment. Remove the file to remove the tool.
424
+ `ask_question` is a [workflow tool](/docs/tools/workflows) that calls `ctx.ask()`. A steering message that doesn't answer the question withdraws it, and the model reads `{ interrupted: true }` as `Stopped early because a new message arrived.`, then the message. In a session that cannot request input, such as a [markdown schedule](/docs/schedules#markdown-form-fire-and-forget), the result is `{ status: "unavailable" }` and the model continues on its own judgment.
381
425
 
382
426
  ### `glob`
383
427
 
@@ -403,11 +447,9 @@ export default defineTool({
403
447
  });
404
448
  ```
405
449
 
406
- Remove the file to remove the tool. `disableTool()` is unnecessary because `glob` is not added by default.
407
-
408
450
  ### `grep`
409
451
 
410
- `grep` searches file contents inside the sandbox workspace with a regular expression. It searches the workspace root unless the model passes a directory or file inside the workspace. It is also the implementation of the code extension's `code__grep` tool. Add it:
452
+ `grep` searches sandbox file contents with a regular expression. It searches the workspace root unless the model passes a directory or file inside the workspace. The code extension's `code__grep` tool behaves the same. Add it:
411
453
 
412
454
  ```sh
413
455
  eve add tool/grep
@@ -429,21 +471,13 @@ export default defineTool({
429
471
  });
430
472
  ```
431
473
 
432
- Remove the file to remove the tool. `disableTool()` is unnecessary because `grep` is not added by default.
433
-
434
- Inputs are `pattern`, optional `path`, `glob`, `ignoreCase`, `literal`, `context`, `limit`, and
435
- `outputMode`. `files_with_matches` is the default and lists paths; `content` returns matching
436
- lines and `count` returns per-file totals. Identifier-like patterns use literal matching unless
437
- `literal: false` is explicit. The default limit is 50 rows, capped at 200, with additional byte
438
- and line bounds. Relative paths resolve against the workspace root; `$HOME` paths, parent traversal, and symlinks
439
- outside it are rejected. Ripgrep respects `.gitignore`; the POSIX fallback does not.
474
+ Inputs are `pattern`, optional `path`, `glob`, `ignoreCase`, `literal`, `context`, `limit`, and `outputMode`. Omit `outputMode` to list matching paths (`files_with_matches`); `content` returns matching lines and `count` returns per-file totals. Identifier-like patterns match literally unless `literal: false` is explicit. The default limit is 50 rows, capped at 200, with additional byte and line bounds.
440
475
 
441
- Results contain `content`, `matchCount`, `outputMode`, `path`, and `truncated`. Use
442
- `outputMode: "content"` to return matching lines.
476
+ Relative paths resolve against the workspace root; `$HOME` paths, parent traversal, and symlinks outside it are rejected. When the sandbox has ripgrep, results respect `.gitignore`; otherwise they don't. Results contain `content`, `matchCount`, `outputMode`, `path`, and `truncated`.
443
477
 
444
478
  ### `no_reply`
445
479
 
446
- `no_reply` ends the turn without a reply. Use it when a scheduled check finds nothing to report, or when an action the agent already took is the whole answer. The model calls it with an optional `{ reason }`, which stays in the session history and traces and is never sent. The turn completes without a final message, so channels and schedule sends post nothing, and later turns see that the agent chose to stay quiet. Add it:
480
+ `no_reply` ends the turn without a reply. It fits a scheduled check that finds nothing to report, or an action the agent already took is the whole answer. The model calls it with an optional `{ reason }`, which stays in session history and traces and is never sent. Channels and schedule sends post nothing, and later turns see that the agent chose to stay quiet. Add it:
447
481
 
448
482
  ```sh
449
483
  eve add tool/no_reply
@@ -455,13 +489,13 @@ import { noReply } from "eve/tools/no_reply";
455
489
  export default noReply;
456
490
  ```
457
491
 
458
- `no_reply` is a `defineTool` tool with [`endsTurn: true`](/docs/tools#end-the-turn-after-a-tool-call), so the turn ends only when no other tool runs in the same step. Only root sessions receive it. Slack clears the thread status when the turn completes. Remove the file to remove the tool.
492
+ `no_reply` is a `defineTool` tool with [`endsTurn: true`](/docs/tools#end-the-turn-after-a-tool-call), so the turn ends only when no other tool runs in the same step. Only root sessions receive it. Slack clears the thread status when the turn completes.
459
493
 
460
- A root session also accepts a successful model call that returns no text with `finishReason: "stop"`, without retrying or reporting a model-call failure. A turn that settles with no text completes without a final message. Use `no_reply` when the agent should record an explicit choice to stay quiet, including an optional reason. Delegated sessions still retry an empty reply once and report a failure if it remains empty, so the caller can act on the failure.
494
+ Without `no_reply`, a root session also accepts an empty model reply with `finishReason: "stop"` and completes the turn without a final message. Use `no_reply` to record an explicit choice to stay quiet, with a reason. Delegated sessions retry an empty reply once and report a failure if it stays empty, so the caller can act on it.
461
495
 
462
496
  ### `sleep`
463
497
 
464
- `sleep` pauses and durably resumes the current turn. The model calls it with `{ seconds }`; the wait does not hold an application runtime open. Concurrent calls run in parallel, and the turn resumes after the longest wait. A steering message, the default for a new message, ends the wait early: `sleep` returns `{ interrupted: true }`, which the model reads as `Stopped early because a new message arrived.`, followed by the message. Add it:
498
+ `sleep` pauses the current turn and resumes it later, without keeping the application runtime running. The wait survives restarts. The model calls it with `{ seconds }`. Concurrent calls run in parallel, and the turn resumes after the longest wait. A steering message, the default for a new message, ends the wait early: the model reads `{ interrupted: true }` as `Stopped early because a new message arrived.`, then the message. Add it:
465
499
 
466
500
  ```sh
467
501
  eve add tool/sleep
@@ -485,8 +519,6 @@ export default defineWorkflowTool({
485
519
  });
486
520
  ```
487
521
 
488
- Remove the file to remove the tool. `disableTool()` is unnecessary because `sleep` is not added by default.
489
-
490
522
  ## What to read next
491
523
 
492
524
  - [Tools](../tools): define your own tools, gate them on approval, and shape their output with `toModelOutput`
@@ -3,20 +3,20 @@ title: "Context Control"
3
3
  description: "Choose what an eve agent's model sees and when, across instructions, skills, tools, the workspace, and subagents."
4
4
  ---
5
5
 
6
- Control context by putting information in the narrowest surface that needs it. Keep permanent rules in instructions, load optional procedures as skills, let the model inspect runtime files through sandbox tools, and delegate specialist work to a subagent.
6
+ Control context by putting information in the narrowest surface that needs it. Keep permanent rules in instructions and load optional procedures as skills. Let the model inspect runtime files through sandbox tools, and delegate specialist work to a subagent.
7
7
 
8
8
  ## Recommended context layout
9
9
 
10
- | Need | Use | What the model sees |
11
- | ---------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
12
- | Permanent identity, rules, or constraints | System-role [instructions](../instructions) | System context on every model call |
13
- | Durable application or retrieved context | User-role [instructions](../instructions) | A message added to conversation history at its lifecycle boundary |
14
- | A procedure needed only for some tasks | A [skill](../skills) | Its description until the model loads the full skill |
15
- | A typed action or external operation | A [tool](../tools) or [connection](../connections) | The callable schema and the result of each call |
16
- | Files or command execution | The [sandbox workspace](../sandbox) | A workspace hint, then files and command output the model requests through tools |
17
- | A specialist with a separate prompt and capabilities | A [subagent](../subagents) | The child's reply as the tool result |
18
- | Instructions or capabilities that vary by caller | A [dynamic capability](../guides/dynamic-capabilities) | The values resolved for the active session |
19
- | Scoped context retrieved from cross-session storage | [Memory](../memory) | Attributed user-role messages recalled before the current delivery |
10
+ | Need | Use | What the model sees |
11
+ | ---------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
12
+ | Permanent identity, rules, or constraints | System-role [instructions](../instructions) | System context on every model call |
13
+ | Application or retrieved context kept in history | User-role [instructions](../instructions) | A message in conversation history, added at session start or when it changes |
14
+ | A procedure needed only for some tasks | A [skill](../skills) | Its description until the model loads the full skill |
15
+ | A typed action or external operation | A [tool](../tools) or [connection](../connections) | The callable schema and the result of each call |
16
+ | Files or command execution | The [sandbox workspace](../sandbox) | A workspace hint, then files and command output the model requests through tools |
17
+ | A specialist with a separate prompt and tools | A [subagent](../subagents) | The child's reply as the tool result |
18
+ | Instructions, tools, or skills that vary by caller | A [dynamic value](../guides/dynamic-capabilities) | The values resolved for the active session |
19
+ | Context recalled from storage that outlives sessions | [Memory](../memory) | User-role messages labeled with their memory slot, placed before the turn input |
20
20
 
21
21
  ## Base identity with `instructions.md`
22
22
 
@@ -24,7 +24,7 @@ Use system-role instructions for stable behavior that should apply throughout a
24
24
 
25
25
  ### Compose instructions in TypeScript with `instructions.ts`
26
26
 
27
- Use `instructions.ts` when you need typed helpers, build-time composition, or a user-role message. User-role instructions become ordinary durable history rather than system context. See [Instructions](../instructions) for both formats, directory composition, and runtime resolution.
27
+ Use `instructions.ts` when you need typed helpers, build-time composition, or a user-role message. User-role instructions become ordinary conversation history rather than system context. See [Instructions](../instructions) for both formats, directory composition, and runtime resolution.
28
28
 
29
29
  ## Load procedures on demand with `skills/`
30
30
 
@@ -42,7 +42,7 @@ Use a directory with `SKILL.md` when the procedure also needs references, assets
42
42
 
43
43
  Do not paste a file tree or large working dataset into the prompt. Seed files into the sandbox workspace and let the model inspect them through `bash`, `read_file`, `glob`, and the other sandbox-backed tools. Skill package files use a separate runtime skill directory.
44
44
 
45
- See [Sandbox](../sandbox) for workspace seeding, runtime access, backends, and lifecycle behavior.
45
+ See [Sandbox](../sandbox) for workspace seeding, runtime access, backends, and how long a sandbox lives.
46
46
 
47
47
  ## Delegate to a specialist with a subagent
48
48
 
@@ -52,19 +52,19 @@ See [Subagents](../subagents) for the distinction between root-agent copies and
52
52
 
53
53
  ## Dynamic context with `defineDynamic`
54
54
 
55
- Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the active principal, tenant, channel, conversation, or feature state. The function reads the committed session and returns the capability or `null`. eve evaluates it before each ordinary model call; `ctx.memo(key, fn)` keeps JSON observations across evaluations.
55
+ Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the caller, tenant, channel, conversation, or feature state. The function reads the recorded session and returns the value or `null`. eve evaluates it before each ordinary model call, and `ctx.memo(key, fn)` keeps JSON observations across evaluations.
56
56
 
57
57
  See [Dynamic capabilities](../guides/dynamic-capabilities) for the context, memo rules, supported folders, and evaluation timing.
58
58
 
59
59
  ## Compaction and clear
60
60
 
61
- Before a model call, eve checks the projected history together with the effective system instructions and advertised tool schemas. The check runs after eve evaluates dynamic capabilities for that call. When the provider reports input usage, eve adds estimates for new messages and growth in the instructions and tool catalog to that count; unchanged schemas are not counted again.
61
+ Before each model call, eve measures the history together with the system instructions and advertised tool schemas against the compaction threshold. The measurement starts from the provider's last reported input usage when one exists.
62
62
 
63
- Compaction reserves space for those instructions and tools while reducing conversation history. It cannot shrink the instructions or tool catalog themselves, so keep them within the selected model's context window.
63
+ Compaction reserves space for those instructions and tools and reduces only conversation history. It can't shrink the instructions or tool catalog, so keep them within the selected model's context window.
64
64
 
65
- User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without reinserting unchanged instructions. System-role instructions remain outside history and continue to apply after either operation.
65
+ User-role instructions are part of history. Compaction can summarize them, and clear removes them without reinserting unchanged instructions. System-role instructions remain outside history and continue to apply after either operation.
66
66
 
67
- Recalled memory stays outside history too. eve recalls before the first model call of each turn, and every later model call reads that turn's recall just ahead of the turn's input. Compaction does not summarize it; a provider can capture before compaction rewrites history. Clear drops what earlier turns recalled, though not the provider's external data, and the next turn recalls again.
67
+ Recalled memory stays outside history too. eve recalls before the first model call of each turn, and every later model call reads that turn's recall just ahead of the turn's input. Compaction doesn't summarize it, and a provider can capture before compaction rewrites history. Clear drops what earlier turns recalled, though not the provider's external data, and the next turn recalls again.
68
68
 
69
69
  ## What to read next
70
70
 
@@ -72,5 +72,5 @@ Recalled memory stays outside history too. eve recalls before the first model ca
72
72
  - [Skills](../skills): provide procedures that load on demand.
73
73
  - [Sandbox](../sandbox): give the model files and command execution.
74
74
  - [Subagents](../subagents): isolate specialist work.
75
- - [Dynamic capabilities](../guides/dynamic-capabilities): vary context and capabilities by session.
76
- - [Memory](../memory): retrieve scoped context from storage that outlives a session.
75
+ - [Dynamic capabilities](../guides/dynamic-capabilities): vary instructions, tools, and skills by session.
76
+ - [Memory](../memory): recall context from storage that outlives a session.
@@ -3,11 +3,11 @@ title: "Default Harness"
3
3
  description: "How eve manages model context and compaction during an agent turn."
4
4
  ---
5
5
 
6
- The default harness is eve's built-in agent loop. It manages model calls, compaction, and tool execution. Review the model-facing defaults and available opt-ins in [Built-in tools](./built-in-tools). To see how turns checkpoint and resume, read [Execution model and durability](./execution-model-and-durability).
6
+ The default harness is eve's built-in agent loop. It manages model calls, compaction, and tool execution. See [Built-in tools](./built-in-tools) for its model-facing defaults and opt-ins, and [Execution model and durability](./execution-model-and-durability) for how turns checkpoint and resume.
7
7
 
8
8
  ## Compaction
9
9
 
10
- The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `compaction.threshold` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
10
+ Compaction keeps a long session from overflowing the model's context window. The harness compacts when the conversation, plus the compaction prompt's estimated size, reaches `compaction.threshold` of the window. It then summarizes the older turns into a checkpoint and keeps going. Omit `compaction.threshold` to compact at `0.9`. Tune it under [`compaction`](../agent-config#compaction) in `agent.ts`:
11
11
 
12
12
  ```ts title="agent/agent.ts"
13
13
  export default defineAgent({
@@ -18,43 +18,27 @@ export default defineAgent({
18
18
  });
19
19
  ```
20
20
 
21
- Before summarizing, eve tries to shorten oversized tool results in older history.
22
- It checks whether that reduction is sufficient using the last provider-reported
23
- input token count plus an estimate of new messages. A smaller character estimate
24
- alone cannot satisfy compaction triggered by a higher provider count. If trimming
25
- cannot free enough space, eve summarizes the older history.
26
-
27
- The summary call retries transient provider errors like any model call. If it
28
- still fails for any reason other than staying over the threshold, eve reports it
29
- as a failed model call: the turn fails with `MODEL_CALL_FAILED` and the history
30
- stays uncompacted. A transient error such as a 429 leaves the session waiting
31
- for the next message.
32
-
33
- First-class [memory](../memory) stays outside history, so the summarizer never
34
- sees it. eve asks providers to capture before compaction rewrites history, and
35
- what earlier turns recalled follows the checkpoint.
36
-
37
- Clients and channels can also request compaction between turns. Call
38
- `ClientSession.compact()`, a channel route's `compact(address)`, or
39
- `attachSession(sessionId).compact()`. The request does not append a user message;
40
- if a turn is running, eve queues it until that turn settles. A manual compaction is
41
- the same context change as automatic compaction: `context.started` and
42
- `context.settled` with `kind: "compaction"`.
43
-
44
- After either kind of compaction, eve moves the idle session to a fresh workflow
45
- run on the same deployment, so a long session's run history does not keep
46
- growing. See [Execution model and durability](./execution-model-and-durability#compaction-handoff).
47
-
48
- To discard model-message history instead of summarizing it, call the corresponding
49
- `clear()` method on any of those handles. Clearing preserves the session identity,
50
- system prompt, configured tools and skills, durable state, limits, and sandbox.
51
- It removes recalled memory records and framework memory bookkeeping, but it
52
- does not delete data from a memory provider's external store.
53
- On the stream it is a context change with `kind: "clear"`: `context.started`, then `context.settled`.
21
+ Before summarizing, eve tries to shorten oversized tool results in older history. If that can't free enough space, eve summarizes. eve measures the space against the provider's last reported input token count, plus an estimate for new messages.
22
+
23
+ The summary prompt asks the compaction model to separate completed progress and decisions from remaining work. It also asks the model to keep the constraints, preferences, data, and references needed to continue. A later compaction passes the previous summary in full and replaces it with an updated one. Omit `compaction.model` to summarize with the active turn model.
24
+
25
+ After compacting, the harness keeps the most recent messages word for word next to the summary. It keeps up to 20,000 tokens or half the threshold, whichever is smaller, and shortens their tool results to 2,000 characters. The current user message is always kept. When that message alone exceeds the budget, the harness keeps its start and end with a note at the cut. It summarizes the middle with the older turns.
26
+
27
+ If compaction can't bring the history under the threshold, the session fails with an error instead of compacting again, and the step isn't retried. Start a new session or send a smaller message.
28
+
29
+ The summary call retries transient provider errors like any model call. If it fails for another reason, the turn fails with `MODEL_CALL_FAILED` and the history stays uncompacted. After a transient error such as a 429, the session waits for the next message.
30
+
31
+ [Memory](../memory) stays outside history, so the summarizer never sees it. eve asks providers to capture before compaction rewrites history, and what earlier turns recalled follows the checkpoint.
32
+
33
+ Clients and channels can request compaction between turns with `ClientSession.compact()`, a channel route's `compact(address)`, or `attachSession(sessionId).compact()`. The request doesn't append a user message. If a turn is running, eve queues the request until that turn ends. On the stream, manual and automatic compaction are the same context change: `context.started` and `context.settled` with `kind: "compaction"`.
34
+
35
+ After either kind of compaction, eve moves the idle session to a fresh workflow run on the same deployment. This keeps a long session's run history from growing. See [Execution model and durability](./execution-model-and-durability#compaction-handoff).
36
+
37
+ To discard model-message history instead of summarizing it, call `clear()` on any of those handles. Clearing keeps the session identity, system prompt, configured tools and skills, [`defineState`](./state) values, limits, and sandbox. It removes recalled memory, but doesn't delete data from a memory provider's external store. On the stream, clear is a context change with `kind: "clear"`: `context.started`, then `context.settled`.
54
38
 
55
39
  ## What to read next
56
40
 
57
41
  - [Built-in tools](./built-in-tools): review the default and opt-in framework tools and configure the model-facing tool set
58
42
  - [Execution model and durability](./execution-model-and-durability): understand how turns checkpoint and resume
59
43
  - [Context control](./context-control): choose what the model sees and when
60
- - [Memory](../memory): connect scoped, cross-session context to the harness lifecycle
44
+ - [Memory](../memory): recall context from earlier sessions on every turn