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
@@ -4,130 +4,180 @@ description: "Define typed actions the agent can call, and gate sensitive ones o
4
4
  url: /tools
5
5
  ---
6
6
 
7
- A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file. Define a tool when you implement the action in code you control. To give the model tools published by an external MCP or OpenAPI service, use a [connection](/docs/connections) instead. Authored tools run in your app runtime with full access to `process.env`, not in the [sandbox](/docs/sandbox).
7
+ A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file. Each tool is a file under `agent/tools/`, and the filename is the tool name the model sees. Define a tool when you implement the action in code you control.
8
8
 
9
9
  ## Define a tool
10
10
 
11
- The filename is the tool name the model sees. A file at `agent/tools/get_weather.ts` is exposed as `get_weather`.
11
+ ```text
12
+ agent/
13
+ ├── agent.ts
14
+ └── tools/
15
+ └── get_weather.ts # the model calls this tool `get_weather`
16
+ ```
12
17
 
13
18
  ```ts title="agent/tools/get_weather.ts"
14
19
  import { defineTool } from "eve/tools";
15
20
  import { z } from "zod";
16
21
 
17
22
  export default defineTool({
23
+ // required: what the tool does, written for the model
18
24
  description: "Get the current weather for a city.",
25
+ // required: use z.object({}) for a tool with no input
19
26
  inputSchema: z.object({ city: z.string().min(1) }),
27
+ // required: may be sync, async, or an async generator
20
28
  async execute({ city }, ctx) {
21
29
  return { city, condition: "Sunny", temperatureF: 72 };
22
30
  },
23
31
  });
24
32
  ```
25
33
 
26
- A tool definition needs:
34
+ - Tools run in your app runtime, not in the [sandbox](/docs/sandbox). They can read `process.env` and import shared code from `lib/`.
35
+ - `inputSchema` is a Zod schema, any Standard Schema, or a plain JSON Schema object. Zod and Standard Schema infer the `input` type, and a plain JSON Schema types it as `Record<string, unknown>`.
36
+ - eve validates the input before `execute` runs. Zod and Standard Schema use their own library, so any installed Zod version works.
37
+ - eve sends a plain JSON Schema to the model without its `$schema` keyword. It validates with JSON Schema 2020-12 rules, which cover draft-07 keywords.
38
+ - For a JSON Schema, eve fills omitted properties from their `default` values. `format` is an annotation only.
39
+ - An unknown `type` name or an unresolvable `$ref` stops eve from checking a JSON Schema. The model still receives the schema, and `execute` gets the input unchecked.
40
+ - Optional input fields stay optional, because eve turns off provider strict mode for function tools.
41
+ - Tool outputs must be JSON-serializable. Convert `Date`, `Map`, `Set`, `NaN`, and cyclic values before you return them.
42
+ - Add an `outputSchema` for structured output. With Zod or Standard Schema, it also types the `execute` return.
43
+ - Schemas can come from helper modules and be composed with Zod.
27
44
 
28
- - a filename slug under `agent/tools/`, the model-facing name.
29
- - a `description`: what the tool does, written for the model.
30
- - an `inputSchema`: a Zod schema (or any Standard Schema, or a plain JSON Schema object). Required. For no input, pass `z.object({})`. Zod and Standard Schema infer the `input` type in `execute`. Plain JSON Schema types it as `Record<string, unknown>`.
31
- - an `execute(input, ctx)`: the implementation. May be sync, async, or an async generator.
45
+ ### The `ctx` parameter
32
46
 
33
- When a tool returns structured data, add an optional `outputSchema`. With Zod or Standard Schema it also types the `execute` return.
47
+ `execute` gets a `ctx` with these accessors:
34
48
 
35
- eve validates the model's input against `inputSchema` before `execute` runs:
49
+ - `ctx.session`: session metadata, turn, auth, and parent agent.
50
+ - `ctx.callId`: the call's id, also on its [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
51
+ - `ctx.toolName`: the name the model called, with any namespace prefix.
52
+ - `ctx.messages`: the model input for the step that requested this call, as a [dynamic tool's](/docs/guides/dynamic-capabilities) `ctx.messages()` sees it.
53
+ - `ctx.abortSignal`: aborts when the turn is cancelled. Pass it to work that supports cancellation. Sandbox sessions from `ctx.getSandbox()` already use it.
54
+ - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
55
+ - `ctx.channel`: the channel serving the session, as [hooks](/docs/guides/hooks) and [dynamic resolvers](/docs/guides/dynamic-capabilities) see it: `kind`, `continuationToken`, and `metadata`. `metadata` is what the channel's `metadata(state)` hook returns, such as a Slack thread's `channelId` and `threadTs`.
56
+ - `ctx.to(channel, target)`: starts or continues a session on one of the agent's channels. See [Start channel sessions](#start-channel-sessions-ctxto).
36
57
 
37
- - A Zod or Standard Schema validates with its own library, so tools work with whichever Zod version your app installs.
38
- - A plain JSON Schema object reaches the model as written, without its `$schema` keyword. eve validates input against it with JSON Schema 2020-12 rules, which also cover draft-07 keywords, then fills omitted properties from their `default` values.
39
- - eve treats `format` as an annotation and does not reject input for it.
40
- - When eve cannot evaluate a JSON Schema locally, for example because of an unknown `type` name or a `$ref` it cannot resolve, the model still receives the schema and eve passes the input to `execute` unvalidated.
58
+ ## Options
59
+
60
+ | Field | Default | What it does |
61
+ | ---------------------- | ------------------ | ----------------------------------------------------------------------------- |
62
+ | `description` | required | Tells the model what the tool does. |
63
+ | `inputSchema` | required | Validates and types the model's input. |
64
+ | `execute` | required | Runs the tool. |
65
+ | `outputSchema` | none | Describes and types the return value. |
66
+ | `approval` | `never()` | [Asks a person to approve calls](#gate-a-tool-on-human-approval). |
67
+ | `toModelOutput` | full return | [Changes what the model sees](#shape-what-the-model-sees-with-tomodeloutput). |
68
+ | `label` | readable tool name | [Sets activity text](#label-tool-activity). |
69
+ | `endsTurn` | `false` | [Ends the turn after success](#end-the-turn-after-a-tool-call). |
70
+ | `deferred` | `false` | [Leaves the tool out of the tool list](#keep-a-tool-out-of-the-tool-list). |
71
+ | `availableInSubagents` | `true` | [Offers the tool in delegated sessions](#hide-a-tool-from-delegated-agents). |
41
72
 
42
- Optional input fields remain optional for authored tools and connection tools. eve explicitly disables provider strict mode for function tools so providers such as OpenAI Responses do not implicitly require every property. Local input validation still follows the tool's schema.
73
+ ## When a tool throws
43
74
 
44
- ### Hide a tool from delegated agents
75
+ If `execute` throws, the call ends with `call.settled` `outcome: "failed"`, and the model gets the error. It can respond, try something else, or call the tool again. eve never retries a tool itself, whatever the exception type, HTTP status, or `retryable` property.
45
76
 
46
- Set `availableInSubagents: false` when a tool should be callable only in a top-level root session:
77
+ Retry inside the tool when the operation is safe to repeat. Otherwise, return or throw an error that tells the model what to do. In-tool retries don't protect a write, because the model can make a fresh call with a new tool-call ID. Authored workflow steps have their own retries.
78
+
79
+ Protect non-idempotent operations, such as charges or emails, with the strongest mechanism the service supports:
80
+
81
+ 1. Pass a stable idempotency key to the upstream API.
82
+ 2. Otherwise, record a unique application operation before writing, and check it on every attempt.
83
+ 3. Use human approval when a person must authorize each execution. Approval doesn't replace deduplication after an unclear network result.
84
+
85
+ After a crash, completed steps replay their saved result, and an interrupted step runs again. A call that the step already started doesn't run again. The model reads that the call may have taken effect and decides whether to repeat it. See [Crash recovery](/docs/concepts/execution-model-and-durability#resuming-after-a-crash).
86
+
87
+ For one-way provider notifications, see [Durable cross-channel notifications](/docs/patterns/durable-cross-channel-notifications).
88
+
89
+ ## Gate a tool on human approval
90
+
91
+ A tool can require a person to approve each call before it runs. Set `approval` with the helpers from `eve/tools/approval`:
92
+
93
+ ```ts title="agent/tools/refund_charge.ts"
94
+ import { defineTool } from "eve/tools";
95
+ import { always } from "eve/tools/approval";
96
+ import { z } from "zod";
47
97
 
48
- ```ts title="agent/tools/coordinator.ts"
49
98
  export default defineTool({
50
- availableInSubagents: false,
51
- description: "Coordinate work that only the top-level root agent should start.",
52
- inputSchema: z.object({ task: z.string() }),
53
- execute({ task }) {
54
- return coordinate(task);
99
+ description: "Refund a charge.",
100
+ inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
101
+ approval: always(), // or auto() / once() / never() / a policy
102
+ async execute(input) {
103
+ return refund(input);
55
104
  },
56
105
  });
57
106
  ```
58
107
 
59
- The option defaults to `true` and works with `defineTool` and `defineWorkflowTool`. A root copy does not receive a tool with this option, and a tool authored inside a declared subagent is unavailable because that agent runs in a delegated session. This controls tool availability only; it does not add or remove entries from a workflow's `ctx.agents` registry.
108
+ See [Human-in-the-loop](./human-in-the-loop) for the `auto`, `always`, `once`, and `never` helpers, input-dependent policies, and how a call waits for approval.
60
109
 
61
- ### Keep a tool out of the tool list
110
+ ## Shape what the model sees with `toModelOutput`
62
111
 
63
- Set `deferred: true` when the model needs a tool only occasionally, or when an agent has more tools than you want in every model request:
112
+ Omit `toModelOutput` to give the model the full `execute` return. When a channel needs rich data but the model needs only the gist, return a smaller value:
64
113
 
65
- ```ts title="agent/tools/export_report.ts"
66
- export default defineTool({
67
- deferred: true,
68
- description: "Export a finished report as a PDF.",
69
- inputSchema: z.object({ reportId: z.string() }),
70
- execute({ reportId }) {
71
- return exportReport(reportId);
72
- },
73
- });
114
+ ```ts
115
+ toModelOutput(output) {
116
+ return { type: "text", value: `Report for ${output.domain}: score ${output.score}.` };
117
+ },
74
118
  ```
75
119
 
76
- A deferred tool is not in the model's tool list, and eve doesn't name it in context. The model finds its name, description, and signature with [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and calls it with `eve__tool({ name: "export_report", input })`. After that, the call runs exactly like a direct call: approvals, `endsTurn`, `toModelOutput`, hooks, and stream events see `export_report`, not `execute`.
120
+ `toModelOutput` receives the typed `execute` return and changes only what the model sees. Channel handlers and hooks still get the full output on `call.settled`, so a channel can render Slack Block Kit the model never sees.
77
121
 
78
- The option works with `defineTool`, `defineWorkflowTool`, and dynamic tool entries. Provider tools such as `webSearch()` cannot be deferred, because the provider has to see their definition; the compiler rejects `deferred` on them. To defer an agent, set [`tool: "deferred"`](/docs/subagents#declared-subagents) on its `defineAgent` definition.
122
+ Return `{ type: "text", value }` for a summary or `{ type: "json", value }` for a smaller, JSON-serializable object.
79
123
 
80
- Compiled tools preserve Zod schema composition, including input and output schemas imported from helper modules. Durable replay metadata stays separate from the original schema, so adding it does not mutate shared schema objects.
124
+ Do not return secrets, credentials, unnecessary personal data, or unbounded sensitive content from tools. Filter, minimize, and redact tool outputs before you return them.
81
125
 
82
- ### End the turn after a tool call
126
+ ### Send images to the model with content parts
83
127
 
84
- Set `endsTurn: true` when a successful call is the whole answer, such as reacting to a message. eve ends the turn after the call instead of calling the model again, so the turn completes without a final message and channels post no reply:
128
+ To give a vision-capable model an image, such as a screenshot or chart, return a `content` output from `toModelOutput`. Build outputs with `toolOutput` and parts with `toolOutputPart`, both from `eve/tools`:
129
+
130
+ ```ts
131
+ import { defineTool, toolOutput, toolOutputPart } from "eve/tools";
85
132
 
86
- ```ts title="agent/tools/react.ts"
87
133
  export default defineTool({
88
- description: "React to the current message. Use this when a reaction is the whole answer.",
89
- endsTurn: true,
90
- inputSchema: z.object({ emoji: z.string() }),
91
- async execute({ emoji }) {
92
- await addReaction(emoji);
93
- return { emoji };
134
+ description: "Capture a screenshot of the current page",
135
+ inputSchema: z.object({ url: z.string() }),
136
+ async execute(input) {
137
+ const png = await captureScreenshot(input.url);
138
+ return { path: png.path, screenshotBase64: png.base64 };
139
+ },
140
+ toModelOutput(output) {
141
+ return toolOutput.content([
142
+ toolOutputPart.text(`Screenshot of ${output.path}:`),
143
+ // file payloads must be base64 strings
144
+ toolOutputPart.file(output.screenshotBase64, { mediaType: "image/png" }),
145
+ ]);
94
146
  },
95
147
  });
96
148
  ```
97
149
 
98
- With `endsTurn: true`, eve tells the model that the call ends its turn by appending this sentence, after a blank line, to the description the model sees:
150
+ `toolOutput.text` and `toolOutput.json` build the other two shapes, and hand-written literals also work. eve warns above 3 MiB. A model without vision support fails with its provider's error.
99
151
 
100
- ```text
101
- Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.
102
- ```
152
+ eve writes each returned file to the session sandbox and keeps a reference in session history. Every later model call sends the file again, so it stays visible on later turns. See [Inbound attachments](/docs/sandbox#inbound-attachments).
103
153
 
104
- Write `description` for what the tool does and when to use it, and leave the turn-ending rule to eve. The appended sentence is not part of the tool definition, so `eve info` shows the description as you wrote it.
154
+ When compaction drops older tool results, each file becomes a text reference such as `Attached file /workspace/.eve/attachments/<hash>/chart.png (image/png)`. The built-in `read_file` tool can open it again. It shows the model PNG, JPEG, GIF, and WebP images up to 3 MiB and PDFs up to 20 MiB.
105
155
 
106
- To decide from the result instead, pass a function. eve calls it with the output of `execute` after each successful call, and the call ends the turn only when the function returns `true` or resolves to `true`. If the function throws or rejects, eve logs a warning and the turn continues as though it returned `false`:
156
+ #### Send a file by URL
107
157
 
108
- ```ts title="agent/tools/react.ts"
109
- export default defineTool({
110
- description:
111
- "React to the current message. When the reaction posts, your turn ends; otherwise, reply in text.",
112
- inputSchema: z.object({ emoji: z.string() }),
113
- async execute({ emoji }) {
114
- return { posted: await addReaction(emoji) };
115
- },
116
- endsTurn: (output) => output.posted,
117
- });
158
+ For a large file in object storage, such as a PDF behind a presigned S3 link, return its URL with `toolOutputPart.fileUrl`:
159
+
160
+ ```ts
161
+ toModelOutput(output) {
162
+ return toolOutput.content([
163
+ toolOutputPart.text(`Contract ${output.id}:`),
164
+ // only https: URLs are accepted
165
+ toolOutputPart.fileUrl(output.signedUrl, { mediaType: "application/pdf" }),
166
+ ]);
167
+ },
118
168
  ```
119
169
 
120
- Declare `endsTurn` after `execute`, as above, so TypeScript infers `output` from what `execute` returns. With an `outputSchema`, `output` takes that schema's type wherever `endsTurn` appears.
170
+ eve keeps only the URL in session history and doesn't write the file to the sandbox. The provider fetches the URL when it supports that file type. Otherwise, your app runtime downloads the file before the call.
121
171
 
122
- eve does not append the sentence for a function, because whether the call ends the turn is known only after it runs. Describe the behavior in `description` when the model needs to know it.
172
+ Every later model call sends the URL again, so it must stay readable for the whole session. The provider counts the file's input tokens on each call, as for an inline file.
123
173
 
124
- The turn ends only when every tool call in the model's step can end the turn and succeeds, and every `endsTurn` function returns `true`. Otherwise the model receives the results and continues as usual. Text the model writes before the call is narration, so channels do not post it as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
174
+ When compaction drops the tool result, the file becomes `Attached file <filename> (<mediaType>)`, and the URL is gone. Also return a text part with an id or path, so the tool can fetch the file again later.
125
175
 
126
- eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries also accept `endsTurn`, including the function form. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
176
+ ## More tool options
127
177
 
128
178
  ### Label tool activity
129
179
 
130
- Use `label.start(input)` to describe a call in user-facing activity. The callback receives the validated tool input, so it can select the useful fields without exposing the full argument object:
180
+ Use `label.start(input)` to describe a call in the activity users see. The callback receives the validated input:
131
181
 
132
182
  ```ts title="agent/tools/deploy.ts"
133
183
  export default defineTool({
@@ -145,17 +195,17 @@ export default defineTool({
145
195
  });
146
196
  ```
147
197
 
148
- The label is presentation only. It does not replace the path-derived tool name, enter model input, or change execution. eve records the bounded label on the corresponding public action event so activity renderers and other authorized stream consumers can use it without interpreting raw tool data. Built-in channel activity can show `Deploy storefront to production` instead of `Deploy`; if the callback throws or returns an empty label, activity falls back to a readable form of the tool name, such as `Sync accounts` for `sync_accounts`.
198
+ The label changes only what users see, not the tool name, input, or behavior. eve records it on the call's public action event, so channels show `Deploy storefront to production` and stream consumers can read it. If the callback throws or returns an empty label, activity shows the tool name in readable form, such as `Sync accounts` for `sync_accounts`.
149
199
 
150
- Provided tools define labels for `bash`, `glob`, `grep`, `read_file`, `web_fetch`, `web_search`, and `write_file`.
200
+ The provided `bash`, `glob`, `grep`, `read_file`, `web_fetch`, `web_search`, and `write_file` tools define labels. A deferred tool, agent, or connection tool called through [`eve__tool`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) shows its own label. Other built-in labels:
151
201
 
152
- Calls the model makes through the [catalog](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) read the same way. A deferred tool, agent, or connection tool called through `eve__tool` shows its own label, exactly as a direct call would. An `eve__search` call shows `Search tools for “linear issues”`, then `Searched tools for “linear issues”, found 5` when it returns. A skill load shows `Load skill release-notes`, then `Loaded skill release-notes`, and a connection's sign-in entry shows `Sign in to Linear`.
202
+ - An `eve__search` call shows `Search tools for “linear issues”`, then `Searched tools for “linear issues”, found 5`.
203
+ - A skill load shows `Load skill release-notes`, then `Loaded skill release-notes`.
204
+ - A connection's sign-in entry shows `Sign in to Linear`.
153
205
 
154
206
  ### Stream preliminary tool results
155
207
 
156
- For a `defineTool` executor, an async generator streams complete
157
- output snapshots before it finishes. Each `yield` replaces the previous snapshot; the final
158
- yield is the normal tool result the model receives:
208
+ A `defineTool` executor written as an async generator sends complete output snapshots before it finishes. Each `yield` replaces the previous snapshot, and the final yield is the tool result:
159
209
 
160
210
  ```ts title="agent/tools/build_report.ts"
161
211
  export default defineTool({
@@ -163,243 +213,185 @@ export default defineTool({
163
213
  inputSchema: z.object({ project: z.string() }),
164
214
  label: {
165
215
  start: ({ project }) => `Build report for ${project}`,
166
- delta: (_input, partial) => partial.phase,
216
+ delta: (_input, partial) => partial.phase, // runs for each snapshot
167
217
  complete: (_input, output) => `Report ready with ${output.report.sections.length} sections`,
168
218
  },
169
219
  async *execute({ project }) {
170
220
  yield { phase: "Collecting sources", report: null };
171
221
  const report = await buildReport(project);
172
- yield { phase: "Complete", report };
222
+ yield { phase: "Complete", report }; // the tool result
173
223
  },
174
224
  });
175
225
  ```
176
226
 
177
- eve publishes earlier yields as `call.progress` stream records. When the durable
178
- writer is busy, eve may keep only the newest adjacent snapshot for a call. The
179
- snapshot is visible to channels, hooks, and clients but never enters model
180
- history or `toModelOutput`; only the final yield does. Treat snapshots as
181
- last-write-wins by tool call id, not append-only progress. The durable runtime
182
- can retry a step and replay overlapping snapshots. A generator `return` value is not used as
183
- the result in this mode; yield the final output. Workflow generators have different result
184
- rules, described under [yield and return](#yield-and-return).
185
-
186
- Use `label.delta(input, partial)` to project preliminary snapshots into
187
- user-facing activity, and `label.complete(input, output)` to describe successful
188
- settlement differently. Both callbacks receive the validated input first and the typed value yielded by
189
- `execute` second. Each non-empty update replaces the previous activity label; the
190
- result projection replaces the latest update immediately before eve marks the
191
- action complete.
192
-
193
- eve normalizes and bounds projected text before rendering it. If either
194
- callback throws or returns an empty string, eve keeps the existing activity
195
- label. `label.complete` does not run for failed or rejected tool calls. The
196
- full values remain available in `call.progress` and `call.settled`; renderers
197
- receive only the projected text.
198
-
199
- ### Durable waits
200
-
201
- A tool call with an `execute` entry point finishes before the model continues. The definition
202
- decides whether the executor can wait durably while the call is pending:
203
-
204
- | Definition | Durable waits inside `execute` | Result delivered to the model |
205
- | -------------------- | -------------------------------------------------------- | ---------------------------------- |
206
- | `defineTool` | No; the executor runs inside the initiating step. | Executor output after it finishes. |
207
- | `defineWorkflowTool` | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes. |
227
+ Channels, hooks, and clients see earlier yields as `call.progress` stream records. Only the final yield reaches model history and `toModelOutput`. eve ignores a generator's `return` value; see [Yield and return](#yield-and-return).
208
228
 
209
- A workflow tool that defines `task(input, ctx)` in place of `execute` runs each call as a
210
- [task](/docs/tools/workflows#run-calls-as-tasks-task):
211
- the call returns a receipt at once, and the workflow's output reaches the model later in a
212
- `task.result` message. One that defines `serve(receive, ctx)` runs a
213
- [resumable task](/docs/tools/workflows#resumable-tasks-serve), which the model can send more calls
214
- by its `taskId`.
229
+ Keep the latest snapshot for each tool call id. eve may skip snapshots, and a retried step can send some again.
215
230
 
216
- Built-in, declared local, and remote subagent tools run as resumable tasks: each call returns a
217
- receipt at once, and the child's reply reaches the model later in a `task.result` message.
218
- Inside an authored workflow, awaiting a [`ctx.agent` session's `response.result()`](/docs/tools/workflows#delegate-work-ctxagent)
219
- waits for the child's turn to end instead.
231
+ `label.delta(input, partial)` turns a snapshot into activity text, and `label.complete(input, output)` describes success. Each non-empty result replaces the current label. If a callback throws or returns an empty string, the label stays as it was. `label.complete` doesn't run for failed or rejected calls.
220
232
 
221
- The `TaskExec` argument and `task.postMessage` have been removed. Return the result. In a workflow
222
- body, keep values needed after a wait in local variables; workflow replay reconstructs them across
223
- durable waits. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an
224
- answer from the human.
233
+ Renderers receive only the label text. The full values stay in `call.progress` and `call.settled`.
225
234
 
226
235
  ### Yield and return
227
236
 
228
- `yield` hands a value to eve's generator consumer, which processes it and advances the generator.
229
- It does not by itself create a durable wait for a person, timer, or external event. The value's
230
- meaning depends on the executor:
237
+ `yield` doesn't make the tool wait for a person, timer, or external event. What a yielded value means depends on the executor:
231
238
 
232
239
  | Executor | Ordinary `yield value` | Final output |
233
240
  | -------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
234
241
  | `defineTool` | Earlier values are `call.progress` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored. |
235
242
  | `defineWorkflowTool` | Every yield is a `call.progress` snapshot. | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`. |
236
243
 
237
- Progress snapshots do not enter model history as intermediate tool results. The final output
238
- selected by the rules above becomes the tool result.
239
-
240
- ### Workflows as tools
241
-
242
- Use `defineWorkflowTool` from `eve/tools` to run each call as a durable Workflow run. Its
243
- executor must start with `"use workflow"` and receives `ctx.agent` and `ctx.ask`. The tool can
244
- wait for a person, webhook, or timer without holding compute, then return its result to the model. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and
245
- examples.
244
+ Progress snapshots never enter model history. Only the final output does.
246
245
 
247
- ### The `ctx` parameter
248
-
249
- `execute` gets a `ctx` carrying the runtime accessors:
250
-
251
- - `ctx.session`: session metadata, turn, auth, parent lineage.
252
- - `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
253
- - `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
254
- - `ctx.messages`: the model input for the step that requested this call, the same messages a [dynamic capability's](/docs/guides/dynamic-capabilities) `ctx.messages()` returns before that call.
255
- - `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
256
- - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
257
- - `ctx.channel`: the channel serving the session, as [hooks](/docs/guides/hooks) and [dynamic resolvers](/docs/guides/dynamic-capabilities) read it: `kind`, `continuationToken`, and `metadata`, what the channel's `metadata(state)` hook projects, such as a Slack thread's `channelId` and `threadTs`.
258
- - `ctx.to(channel, target)`: starts or continues a session on one of the agent's channels. See [Start channel sessions](#start-channel-sessions-ctxto).
259
-
260
- Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in eve’s durable pause/resume model.
261
-
262
- eve never runs authored tools during discovery. The model sees descriptors first, and only what it calls gets executed. Completed steps replay their recorded result. An interrupted step runs again from its checkpoint, but a call it already started does not run again: the model reads that the call may have taken effect, and decides whether to call it again.
263
-
264
- Use operation-specific idempotency keys for external writes such as charges or emails. Approval records consent; it does not deduplicate an operation. See [Crash recovery](/docs/concepts/execution-model-and-durability#resuming-after-a-crash).
265
-
266
- ### Start channel sessions: `ctx.to`
267
-
268
- `ctx.to(channel, target).send(message, options)` starts a session on one of the agent's channels, or continues the one at that target, through the channel's `receive` hook. It's the same call as a route handler's [cross-channel hand-off](/docs/channels/custom#cross-channel-hand-off), with the same [options](/docs/channels/custom#cross-channel-hand-off), and returns the delivery, whose `sessionId` names the session. Use it when the model decides that work should continue somewhere people can follow it, such as a new Slack thread:
246
+ ### End the turn after a tool call
269
247
 
270
- ```ts title="agent/tools/escalate.ts"
271
- import { defineTool } from "eve/tools";
272
- import { z } from "zod";
273
- import slack from "../channels/slack";
248
+ Set `endsTurn: true` when a successful call is the whole answer, such as reacting to a message. eve ends the turn without calling the model again, so channels post no reply:
274
249
 
250
+ ```ts title="agent/tools/react.ts"
275
251
  export default defineTool({
276
- description: "Hand this investigation to the on-call channel in Slack.",
277
- inputSchema: z.object({ summary: z.string() }),
278
- async execute({ summary }, ctx) {
279
- const delivery = await ctx
280
- .to(slack, { channelId: "C0123ABC" })
281
- .send("Take over this investigation.", {
282
- auth: ctx.session.auth.current,
283
- history: [{ role: "user", text: summary }],
284
- idempotencyKey: `${ctx.session.id}:${ctx.callId}`,
285
- });
286
- return { sessionId: delivery.sessionId };
252
+ description: "React to the current message. Use this when a reaction is the whole answer.",
253
+ endsTurn: true,
254
+ inputSchema: z.object({ emoji: z.string() }),
255
+ async execute({ emoji }) {
256
+ await addReaction(emoji);
257
+ return { emoji };
287
258
  },
288
259
  });
289
260
  ```
290
261
 
291
- - The session belongs to the channel. People on that channel continue it, it has no parent, and it keeps running after the tool returns.
292
- - It runs the root agent with the `auth` you pass. Pass `ctx.session.auth.current` to start it as the caller.
293
- - A tool call that retries runs the tool again. Pass `` idempotencyKey: `${ctx.session.id}:${ctx.callId}` ``, and the session at the target gets the message once. The destination session dedupes keys from every sender, and `ctx.callId` alone is unique only within the calling session, so include the session id. Built-in channels map a retry to the same session, including a Slack target with only a `channelId`. A platform post made before the session exists, such as an `initialMessage`, repeats.
294
- - `ctx.to()` throws in a delegated session: a subagent, a root copy, or a remote agent call. A session it started would outlive the delegation and act for the caller, so return the result and send from a tool on the root agent.
262
+ eve adds this sentence, after a blank line, to the description the model sees:
295
263
 
296
- See [Fork conversations into a new thread](/docs/patterns/fork-conversations-into-new-threads) for a tool that copies the current conversation into a new Slack thread.
264
+ ```text
265
+ Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.
266
+ ```
297
267
 
298
- ## When a tool throws
268
+ Leave the turn-ending rule out of `description`. `eve info` shows the description as you wrote it, without the added sentence.
299
269
 
300
- If an authored tool's `execute` function throws, eve records the call as `call.settled` with `outcome: "failed"` and gives the error to the model as a tool error. The model can respond, choose another action, or call the tool again. eve does not automatically call the tool again based on the exception type, an upstream HTTP status, or a `retryable` property.
270
+ To decide from the result, pass a function. eve calls it with the output of `execute` after each successful call, and the turn ends only when it returns or resolves to `true`:
301
271
 
302
- Authored tools have no public terminal-error class or retry policy for thrown exceptions. Handle retry policy inside the tool when the operation is safe to retry, and return or throw an actionable error when it is not. Do not rely on that distinction to protect a write: the model can issue a fresh call, and authored workflow steps have their own durable retries. A tool-call ID does not deduplicate an application operation across fresh calls.
272
+ ```ts title="agent/tools/react.ts"
273
+ export default defineTool({
274
+ description:
275
+ "React to the current message. When the reaction posts, your turn ends; otherwise, reply in text.",
276
+ inputSchema: z.object({ emoji: z.string() }),
277
+ async execute({ emoji }) {
278
+ return { posted: await addReaction(emoji) };
279
+ },
280
+ // declare after execute so TypeScript infers `output`
281
+ endsTurn: (output) => output.posted,
282
+ });
283
+ ```
303
284
 
304
- Protect non-idempotent operations with the strongest mechanism the service supports:
285
+ If the function throws or rejects, eve logs a warning and treats the result as `false`. With an `outputSchema`, `output` takes that schema's type wherever `endsTurn` appears. eve doesn't add the sentence for a function, so say in `description` when the call ends the turn.
305
286
 
306
- 1. Pass a stable idempotency key to the upstream API.
307
- 2. Otherwise, record a unique application operation before writing and check it on every attempt.
308
- 3. Use human approval when a person must authorize each execution, not as a substitute for deduplication after an ambiguous network result.
287
+ The turn ends only when every tool call in the step can end the turn, succeeds, and passes any `endsTurn` function. Otherwise, the model gets the results and continues. Channels don't post text the model wrote before the call as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
309
288
 
310
- See [Execution model and durability](/docs/concepts/execution-model-and-durability#resuming-after-a-crash) for step replay semantics. For one-way provider notifications, see [Durable cross-channel notifications](/docs/patterns/durable-cross-channel-notifications).
289
+ eve ignores `endsTurn` in delegated sessions, which must reply to their caller, and on turns that request structured output. There, the model doesn't see the sentence, and eve doesn't call the function.
311
290
 
312
- ## Gate a tool on human approval
291
+ Dynamic tool entries accept both forms of `endsTurn`. `defineWorkflowTool` rejects it at build time. To end a turn without any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
313
292
 
314
- A tool can require a person to sign off before it runs. Set `approval` with the helpers from `eve/tools/approval`:
293
+ ### Keep a tool out of the tool list
315
294
 
316
- ```ts title="agent/tools/refund_charge.ts"
317
- import { defineTool } from "eve/tools";
318
- import { always } from "eve/tools/approval";
319
- import { z } from "zod";
295
+ Set `deferred: true` for a tool the model rarely needs, or when an agent has too many tools to send in every request:
320
296
 
297
+ ```ts title="agent/tools/export_report.ts"
321
298
  export default defineTool({
322
- description: "Refund a charge.",
323
- inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
324
- approval: always(), // or auto() / once() / never() / a policy
325
- async execute(input) {
326
- return refund(input);
299
+ deferred: true,
300
+ description: "Export a finished report as a PDF.",
301
+ inputSchema: z.object({ reportId: z.string() }),
302
+ execute({ reportId }) {
303
+ return exportReport(reportId);
327
304
  },
328
305
  });
329
306
  ```
330
307
 
331
- Approval is one half of eve's [human-in-the-loop](./human-in-the-loop) model — the page covers the `auto`/`always`/`once`/`never` helpers, input-dependent policies, and how a gated call pauses and resumes durably.
308
+ eve leaves a deferred tool out of the tool list and doesn't name it in context. The model finds it with [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and calls it with `eve__tool({ name: "export_report", input })`. Approvals, `endsTurn`, `toModelOutput`, hooks, and stream events then see `export_report`, as for a direct call.
332
309
 
333
- ## Shape what the model sees with `toModelOutput`
310
+ The option works with `defineTool`, `defineWorkflowTool`, and dynamic tool entries. To defer an agent, set [`tool: "deferred"`](/docs/subagents#declared-subagents) on its `defineAgent` definition.
334
311
 
335
- By default the model sees the full `execute` return. When a tool returns rich data a channel needs for rendering but the model only needs the gist, project it down with `toModelOutput`:
312
+ ### Hide a tool from delegated agents
336
313
 
337
- ```ts
338
- toModelOutput(output) {
339
- return { type: "text", value: `Report for ${output.domain}: score ${output.score}.` };
340
- },
341
- ```
314
+ Set `availableInSubagents: false` when only a top-level root session should call a tool:
342
315
 
343
- `toModelOutput` receives the final, typed `execute` return and only affects the model. Channel event handlers and hooks still get the full output on `call.settled`, so a channel can render rich platform output (Slack Block Kit, say) the model never sees. Return `{ type: "text", value }` for a summary, or `{ type: "json", value }` for a smaller object.
316
+ ```ts title="agent/tools/coordinator.ts"
317
+ export default defineTool({
318
+ availableInSubagents: false, // omit to offer the tool in every session
319
+ description: "Coordinate work that only the top-level root agent should start.",
320
+ inputSchema: z.object({ task: z.string() }),
321
+ execute({ task }) {
322
+ return coordinate(task);
323
+ },
324
+ });
325
+ ```
344
326
 
345
- Tool outputs must be JSON-serializable. Return plain objects, arrays, strings, numbers, booleans, or `null`; convert values like `Date`, `Map`, `Set`, `NaN`, and cyclic objects before returning them from `execute` or from a `{ type: "json" }` `toModelOutput`.
327
+ The option works with `defineTool` and `defineWorkflowTool`. Copies of the root agent from the built-in `agent` tool don't get the tool. A declared subagent's own tool with this option is never offered, because a subagent always runs delegated. The option doesn't change a workflow's `ctx.agents` registry.
346
328
 
347
- ### Send images to the model with content parts
329
+ ### Start channel sessions: `ctx.to`
348
330
 
349
- A tool that produces an image — a screenshot, a rendered chart — can hand the pixels to a vision-capable model by returning a `content` output from `toModelOutput`. Build outputs with the `toolOutput` helpers and parts with the `toolOutputPart` helpers, both from `eve/tools`:
331
+ `ctx.to(channel, target).send(message, options)` starts a session on one of the agent's channels, or continues the session at that target. It's the same call, with the same options, as a route handler's [cross-channel hand-off](/docs/channels/custom#cross-channel-hand-off). It returns the delivery, whose `sessionId` names the session. Use it when work should continue where people can follow it, such as a new Slack thread:
350
332
 
351
- ```ts
352
- import { defineTool, toolOutput, toolOutputPart } from "eve/tools";
333
+ ```ts title="agent/tools/escalate.ts"
334
+ import { defineTool } from "eve/tools";
335
+ import { z } from "zod";
336
+ import slack from "../channels/slack";
353
337
 
354
338
  export default defineTool({
355
- description: "Capture a screenshot of the current page",
356
- inputSchema: z.object({ url: z.string() }),
357
- async execute(input) {
358
- const png = await captureScreenshot(input.url);
359
- return { path: png.path, screenshotBase64: png.base64 };
360
- },
361
- toModelOutput(output) {
362
- return toolOutput.content([
363
- toolOutputPart.text(`Screenshot of ${output.path}:`),
364
- toolOutputPart.file(output.screenshotBase64, { mediaType: "image/png" }),
365
- ]);
339
+ description: "Hand this investigation to the on-call channel in Slack.",
340
+ inputSchema: z.object({ summary: z.string() }),
341
+ async execute({ summary }, ctx) {
342
+ const delivery = await ctx
343
+ .to(slack, { channelId: "C0123ABC" })
344
+ .send("Take over this investigation.", {
345
+ auth: ctx.session.auth.current, // start the session as the caller
346
+ history: [{ role: "user", text: summary }],
347
+ idempotencyKey: `${ctx.session.id}:${ctx.callId}`, // a retried call sends once
348
+ });
349
+ return { sessionId: delivery.sessionId };
366
350
  },
367
351
  });
368
352
  ```
369
353
 
370
- The `toolOutput.text` and `toolOutput.json` builders construct the other two output shapes; hand-written literals remain valid everywhere.
354
+ - The new session belongs to the channel. People on that channel continue it, it has no parent, and it keeps running after the tool returns.
355
+ - It runs the root agent with the `auth` you pass.
356
+ - A retried tool call runs the tool again, so pass an `idempotencyKey` and the target session gets the message once. Include the session id, because the target session dedupes keys from every sender and `ctx.callId` is unique only within the calling session. Built-in channels map a retry to the same session, including a Slack target with only a `channelId`. A platform post made before the session exists, such as an `initialMessage`, repeats.
357
+ - `ctx.to()` throws in a delegated session, such as a subagent, a root copy, or a remote agent call. A session it started would outlive the delegation and act for the caller. Return the result instead, and send from a tool on the root agent.
371
358
 
372
- File payloads must be base64 strings — raw bytes (`Uint8Array`, `Buffer`) are rejected because they do not survive eve's durable JSON boundary. eve warns above 3 MiB. Sending image parts to a model without vision support fails with that provider's error, the same as image parts in user messages.
359
+ See [Fork conversations into a new thread](/docs/patterns/fork-conversations-into-new-threads) for a tool that copies the current conversation into a new Slack thread.
373
360
 
374
- eve writes each returned file to the session sandbox and keeps only a reference in session history, so the file's bytes are not stored again on every workflow step. Every later model call sends the same file, which keeps it visible on later turns and keeps the provider's prompt cache valid. See [Inbound attachments](/docs/sandbox#inbound-attachments). Compaction counts an image at roughly what providers bill for it rather than its base64 length.
361
+ ### Workflows as tools
375
362
 
376
- When compaction drops older tool results, each file becomes a text reference such as `Attached file /workspace/.eve/attachments/<hash>/chart.png (image/png)`. The built-in `read_file` tool shows PNG, JPEG, GIF, and WebP images up to 3 MiB and PDFs up to 20 MiB to the model as files, so the agent can open a compacted image or PDF again.
363
+ `defineWorkflowTool` from `eve/tools` runs each call as a Workflow run that survives restarts and redeploys. Its executor starts with `"use workflow"` and receives `ctx.agent` and `ctx.ask`. It can wait for a person, webhook, or timer without holding compute. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and examples.
377
364
 
378
- #### Send a file by URL
365
+ ### Durable waits
379
366
 
380
- For large files that already live in object storage, such as PDFs behind a presigned S3 link, return the URL instead of the bytes with `toolOutputPart.fileUrl`:
367
+ A tool call with an `execute` function finishes before the model continues. The definition decides whether the executor can pause and wait:
381
368
 
382
- ```ts
383
- toModelOutput(output) {
384
- return toolOutput.content([
385
- toolOutputPart.text(`Contract ${output.id}:`),
386
- toolOutputPart.fileUrl(output.signedUrl, { mediaType: "application/pdf" }),
387
- ]);
388
- },
389
- ```
369
+ | Definition | Can wait inside `execute` | What the model receives |
370
+ | -------------------- | -------------------------------------------------------- | ---------------------------------- |
371
+ | `defineTool` | No; the executor runs inside the step that started it. | Executor output after it finishes. |
372
+ | `defineWorkflowTool` | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes. |
373
+
374
+ A workflow tool that defines `task(input, ctx)` instead runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task). The call returns a receipt at once, and the output arrives later in a `task.result` message. One that defines `serve(receive, ctx)` runs a [resumable task](/docs/tools/workflows#resumable-tasks-serve), which takes more calls by its `taskId`.
375
+
376
+ Subagent tools, whether built-in, declared, or remote, run as resumable tasks, so the child's reply also arrives in `task.result`. In an authored workflow, awaiting a [`ctx.agent` session's `response.result()`](/docs/tools/workflows#delegate-work-ctxagent) waits for the child's turn to end instead.
377
+
378
+ In a workflow body, keep values needed after a wait in local variables, because workflow replay rebuilds them. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an answer from a person.
390
379
 
391
- eve keeps only the URL in session history and does not write the file to the sandbox. The model provider fetches the URL itself when it supports that for the file's type; otherwise the AI SDK downloads the file before the call. Only `https:` URLs are accepted.
380
+ ## Troubleshooting
392
381
 
393
- Every later model call sends the same URL again, so it must stay readable for the rest of the session. A presigned URL that expires mid-session makes later model calls fail. The provider still counts the file's input tokens on each call, the same as an inline file.
382
+ | What you see | What to do |
383
+ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
384
+ | The build rejects `deferred` on a tool | Remove it from provider tools such as `webSearch()`, because the provider has to see their definition. |
385
+ | eve rejects a file part | Pass the file as a base64 string. Raw bytes (`Uint8Array`, `Buffer`) can't be saved as JSON. |
386
+ | Later model calls fail after a `fileUrl` part | Use a URL that stays readable for the whole session. A presigned URL that expires makes later calls fail. |
394
387
 
395
- Unlike a staged file, a URL part has no sandbox path to fall back on. When compaction drops the tool result, the file becomes `Attached file <filename> (<mediaType>)` and the URL is gone. If the agent may need the file again later, also return a text part with an id or path the tool can fetch it by.
388
+ ## When to use a connection or skill instead
396
389
 
397
- Do not return secrets, credentials, unnecessary personal data, or unbounded sensitive content from tools. Filter, minimize, and redact tool outputs before returning them.
390
+ To give the model tools from an external MCP or OpenAPI service, use a [connection](/docs/connections). For a written procedure the model loads only when needed, use a [skill](/docs/skills).
398
391
 
399
392
  ## What to read next
400
393
 
401
394
  - [Human-in-the-loop](./human-in-the-loop): gate a tool on approval, or have the agent ask a question
402
- - [Skills](/docs/skills): on-demand procedures the model loads when relevant
403
395
  - [Built-in tools](/docs/concepts/built-in-tools): the default and opt-in framework tools and how to override or disable them
404
396
  - [Dynamic capabilities](/docs/guides/dynamic-capabilities): tools whose set is resolved per session with `defineDynamic`
405
397
  - [Authentication](/docs/guides/auth-and-route-protection): authenticate a tool to an external service