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
@@ -4,27 +4,29 @@ description: "Define durable workflow tools that wait for people, webhooks, or t
4
4
  url: /tools/workflows
5
5
  ---
6
6
 
7
- A workflow tool is a static tool defined with `defineWorkflowTool` from `eve/tools`, with
8
- `"use workflow"` as the first statement of its executor. Each call starts a durable Workflow run. Use one when a tool must wait for a person, webhook, or timer,
9
- delegate work to subagents, or coordinate retryable steps over a long period.
10
-
11
- A workflow tool defines exactly one entry point, and the entry point decides how its calls run. A
12
- call to an `execute(input, ctx)` tool blocks its turn until the workflow settles, and the parent
13
- agent receives the workflow's output as the tool result. While the body waits durably, the turn
14
- parks without holding compute. A `task(input, ctx)` tool runs each call as a
15
- [task](#run-calls-as-tasks-task) instead: the model gets a receipt at once and the result arrives
16
- later. A `serve(receive, ctx)` tool runs a [resumable task](#resumable-tasks-serve), which the
17
- model can send more calls by its `taskId`. See [Tasks](/docs/tools/tasks) for choosing
18
- between them and for what the model sees while tasks work.
19
-
20
- Workflow tools use the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`, `"use step"`, `createHook`,
21
- `createWebhook`, `sleep`, retries, and replay. eve provides `ctx.ask` for questions answered through
22
- the session's channel, `ctx.agents` for effective callable-agent descriptions, and `ctx.agent` for sessions with other agents. Use `yield` to report
23
- progress and `await` on a workflow operation to wait durably. Values needed after a durable wait
24
- stay in local variables in the workflow body.
25
-
26
- A workflow tool runs code you wrote and appears to the model under its path-derived tool name, such
27
- as `deploy`.
7
+ A workflow tool is a tool whose calls can wait for a person, a webhook, or a timer without holding
8
+ compute. Define one with `defineWorkflowTool` from `eve/tools` under `agent/tools/`. The model sees
9
+ it under its path-derived name, such as `deploy`.
10
+
11
+ Use a workflow tool when a call must wait for input, delegate work to subagents, or run retryable
12
+ steps over a long period. Each call starts a Workflow run that survives restarts. For a tool that
13
+ returns in one step, use [`defineTool`](/docs/tools) instead.
14
+
15
+ A workflow tool defines exactly one entry point, which decides how its calls run:
16
+
17
+ | Entry point | How a call runs |
18
+ | --------------------- | ----------------------------------------------------------------------------------------------------------- |
19
+ | `execute(input, ctx)` | The turn waits until the workflow finishes, then gets its output as the tool result. Waits hold no compute. |
20
+ | `task(input, ctx)` | A [task](#run-calls-as-tasks-task): the model gets a receipt at once, and the result arrives later. |
21
+ | `serve(receive, ctx)` | A [resumable task](#resumable-tasks-serve) that the model can send more calls by its `taskId`. |
22
+
23
+ See [Tasks](/docs/tools/tasks) for choosing between them and for what the model sees while tasks
24
+ work.
25
+
26
+ Workflow tools use the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`, `"use step"`,
27
+ `createHook`, `createWebhook`, `sleep`, retries, and replay. eve adds `ctx.ask` to ask a person a
28
+ question and `ctx.agent` to open a session with another agent. `ctx.agents` lists the agents the
29
+ call can open.
28
30
 
29
31
  ## Define a workflow tool
30
32
 
@@ -66,215 +68,93 @@ async function applyDeploy(plan: DeployPlan) {
66
68
  }
67
69
  ```
68
70
 
69
- The model calls `deploy`. The turn parks while the human reads the plan. When they answer, minutes
70
- or days later, the run resumes, deploys, and returns. The model sees one tool result.
71
+ The turn waits while the person reads the plan. When they answer, minutes or days later, the run
72
+ continues, deploys, and returns one tool result.
71
73
 
72
74
  ### Rules
73
75
 
74
- - Export `defineWorkflowTool({ ... })` as the default export. Define exactly one entry point,
75
- `execute`, `task`, or `serve`, written inline or referenced as a top-level `async function` in
76
- the same module or an imported application module. `execute` and `task` can be async functions
77
- or async generators; `serve` is an async function. Defining none, or more than one, throws at
78
- definition time. Start the entry point with `"use workflow"` as its
79
- first statement. A missing directive is a build error, even if another function in the module
80
- has one.
76
+ - Default-export `defineWorkflowTool({ ... })` with exactly one entry point: `execute`, `task`, or
77
+ `serve`. Defining none, or more than one, throws when the tool is defined.
78
+ - Write the entry point inline, or reference a top-level `async function` in the same module or an
79
+ imported application module. `execute` and `task` can be async generators; `serve` can't.
80
+ - Start the entry point with `"use workflow"`. A missing directive is a build error, even if another
81
+ function in the module has one.
81
82
  - `"use step"` marks a top-level `async function` in the tool module, or any module it imports, as a
82
- step. Side effects, clocks, randomness, `process.env`, and Node.js APIs belong in steps; the body
83
- is replayed and must stay deterministic.
84
- - Import `createHook`, `createWebhook`, `sleep`, `FatalError`, `RetryableError`, and `getWorkflowMetadata` from
85
- `eve/workflow` in the body. Import `start`, `getRun`, and `resumeHook` from
86
- `eve/workflow/api` in routes or steps, not in replayed bodies. Both entries use eve's bundled
87
- SDK; no separate `workflow` dependency or ambient tsconfig `types` entry is needed.
88
- - In an `execute` or `task` body, `ctx` is a `WorkflowToolContext` with `session`, `callId`,
89
- `toolName`, `abortSignal`, `channel`, `agent`, `agents`, and `ask`. A `serve` body gets a
90
- `WorkflowServeContext` with `session`, `toolName`, `channel`,
91
- `agent`, `agents`, `ask`, and `reply`; each call it receives carries its own `callId` and
92
- `abortSignal`.
93
- A `"use step"` helper that receives `ctx` directly gets a restricted `WorkflowStepToolContext` with
94
- `session`, `callId`, `toolName`, `abortSignal`, `channel`, `getSandbox`, `getToken`, `requireAuth`, and `to`. Read `ctx.agents`, and call
95
- `ctx.agent()` and `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
96
- Call `getSandbox`, `getToken`, `requireAuth`, and `to` in a step: the workflow body throws when it calls them.
97
- - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
98
- not tools a `defineDynamic` function returns.
99
-
100
- `ctx.agent`, `ctx.agents`, and `ctx.ask` are available only on `WorkflowToolContext` and
101
- `WorkflowServeContext` in the workflow body.
102
- Ordinary tools, channel handlers, schedule handlers, and workflow steps do not receive these methods. Type
103
- step helpers with `WorkflowStepToolContext` from `eve/tools` when they need step-safe context capabilities.
104
-
105
- Workflow executors require `defineWorkflowTool`. Adding `"use workflow"` to `defineTool`, a bare
106
- tool object, a channel handler, or a schedule handler fails the build. To start a session from a
107
- channel or schedule, use the [channel operations](/docs/channels/custom#channel-operations-and-session-handles)
108
- or [schedule handler](/docs/schedules#handler-form-run) APIs.
109
-
110
- Workflow imports resolve `paths` aliases from your application's `tsconfig.json` or
111
- `jsconfig.json`, including when the application is a workspace package. A member of an
112
- [agent workspace](/docs/concepts/project-structure#several-root-agents) can also import
113
- workflow and step modules from the shared root package, such as a root `lib/` directory.
114
- eve includes only workflow and step modules reachable from the agent's runtime modules.
115
- Unrelated workflows in the host application stay outside the agent bundle. An unresolved
116
- workflow import fails the build with the missing import in the error.
83
+ step. The workflow body replays and must stay deterministic, so put side effects, clocks,
84
+ randomness, `process.env`, and Node.js APIs in steps. Keep values you need after a wait in local
85
+ variables in the body.
86
+ - Import durable primitives such as `createHook`, `sleep`, and `FatalError` from `eve/workflow` in
87
+ the body. Call `start`, `getRun`, and `resumeHook` from `eve/workflow/api` in routes or steps, not
88
+ in the body. Both use eve's bundled Workflow SDK, so your app needs no `workflow` dependency. See
89
+ [Workflow imports](#workflow-imports).
90
+ - The tool's input must be a JSON object.
91
+ - Workflow bodies are for static tools under `agent/tools/`, not tools a `defineDynamic` function
92
+ returns. `"use workflow"` in `defineTool`, a bare tool object, a channel handler, or a schedule
93
+ handler fails the build. To start a session from a channel or schedule, use the
94
+ [channel operations](/docs/channels/custom#channel-operations-and-session-handles) or
95
+ [schedule handler](/docs/schedules#handler-form-run) APIs.
96
+ - Workflow imports resolve `paths` aliases from `tsconfig.json` or `jsconfig.json`, including in a
97
+ workspace package. An [agent workspace](/docs/concepts/project-structure#several-root-agents)
98
+ member can import workflow and step modules from the shared root package, such as `lib/`. An
99
+ unresolved workflow import fails the build and names the missing import.
100
+
101
+ The context depends on where your code runs:
102
+
103
+ | Where | Type | Members |
104
+ | ----------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
105
+ | `execute` or `task` body | `WorkflowToolContext` | `session`, `callId`, `toolName`, `abortSignal`, `channel`, `agent`, `agents`, `ask` |
106
+ | `serve` body | `WorkflowServeContext` | `session`, `toolName`, `channel`, `agent`, `agents`, `ask`, `reply`; each received call carries `callId` and `abortSignal` |
107
+ | `"use step"` helper that gets `ctx` | `WorkflowStepToolContext` | `session`, `callId`, `toolName`, `abortSignal`, `channel`, `getSandbox`, `getToken`, `requireAuth`, `to` |
108
+
109
+ Call `ctx.agent()` and `ctx.ask()` and read `ctx.agents` in the workflow body. Pass a step only the
110
+ serializable values it needs. Call `getSandbox`, `getToken`, `requireAuth`, and `to` in a step, because
111
+ the workflow body throws when it calls them. Ordinary tools, channel handlers, and schedule handlers
112
+ don't receive `agent`, `agents`, or `ask`. Import `WorkflowStepToolContext` from `eve/tools` to type
113
+ step helpers.
117
114
 
118
115
  ### Workflow imports
119
116
 
120
- Use `eve/workflow` for durable primitives and `eve/workflow/api` for run and hook operations:
117
+ Import durable primitives from `eve/workflow`, and run and hook operations from `eve/workflow/api`:
121
118
 
122
119
  ```ts
123
120
  import { createHook, sleep } from "eve/workflow";
124
121
  import { resumeHook } from "eve/workflow/api";
125
122
  ```
126
123
 
127
- `eve/workflow` exports:
128
-
129
- - `createHook<T>({ token?, metadata? })` returns a `WorkflowHook<T>`. Await it for the next payload
130
- or iterate it with `for await`. Its `token` resumes it; `metadata` is JSON stored with the hook.
131
- `await hook.getConflict()` registers the hook before you hand out its token and resolves the run
132
- that already owns the token, or `null`. `dispose()`, or `using`, releases the token.
133
- - `createWebhook({ respondWith? })` returns a `WorkflowWebhook` whose `url` resumes it with the
134
- incoming `Request`. With `respondWith: "manual"`, each request is a `WorkflowWebhookRequest`
135
- that you answer with `request.respondWith(response)`.
136
- - `sleep(duration)` takes a duration such as `"1h"`, milliseconds, or a `Date` to wait until.
137
- - `getWorkflowMetadata()` returns the current run's `workflowName`, `workflowRunId`,
138
- `workflowStartedAt`, and `url`.
139
- - Throw `FatalError` to fail without retrying, or `RetryableError` with an optional
140
- `{ retryAfter }` to retry a step.
141
-
142
- Import `WorkflowHook`, `WorkflowHookOptions`, `WorkflowWebhook`, `WorkflowWebhookOptions`,
143
- `WorkflowWebhookRequest`, and `WorkflowMetadata` from `eve/workflow` when you need explicit types.
144
-
145
- `eve/workflow/api` exports:
146
-
147
- - `start(workflow, args)` starts a `"use workflow"` function; omit `args` when it takes none. eve
148
- routes the run to the agent's own workflow queue and deployment, so `start` takes no options.
149
- - `start` and `getRun(runId)` return a `WorkflowRun<T>` with `runId`, `status` (a promise of
150
- `WorkflowRunStatus`), `returnValue`, and `cancel()`.
151
- - `resumeHook(token, payload)` delivers a payload to the hook with that token. Pass a
152
- deterministic `token` to `createHook` when a route must find the hook later.
153
-
154
- Bare `workflow` and `workflow/*` imports in application modules fail the build with an error
155
- naming these entries. Only the exports listed above are public; other SDK subpaths, helpers, and
156
- options are not supported by these entries. Existing `"types": ["eve/workflow-modules"]` tsconfig entries and reference
157
- directives still resolve through 1.x, but the compatibility entry declares no ambient modules.
158
- You can remove those references when updating your imports.
159
-
160
- ### Add a runtime-generated workflow tool
161
-
162
- Create `agent/tools/workflow.ts` and export the provided `workflow` factory when the model should
163
- supply the JavaScript program at runtime:
164
-
165
- ```ts title="agent/tools/workflow.ts"
166
- import { workflow } from "eve/tools/workflow";
167
-
168
- export default workflow({ maxSubagents: 20 });
169
- ```
170
-
171
- The `workflow` tool runs each call as a [task](#run-calls-as-tasks-task), so the program's return
172
- value reaches the model in a `task.result` message. The model supplies an async function body
173
- through the tool's `js` input. Its only host capability is
174
- `ctx.agent(name, { message, outputSchema? })`, which sends the message to a new session with that
175
- agent and resolves to its reply, or to the structured value when `outputSchema` is set. This can invoke subagents configured with `tool: false` or hidden by a same-named `disableTool()` file. Include those path-derived names in the workflow tool description or agent instructions when the model writes the program. For example:
176
-
177
- ```js
178
- const [triage, review] = await Promise.all([
179
- ctx.agent("ticket-triage", { message: JSON.stringify(tickets) }),
180
- ctx.agent("ticket-review", { message: JSON.stringify(tickets) }),
181
- ]);
182
- return { triage, review };
183
- ```
184
-
185
- `maxSubagents` defaults to `100` and must be an integer from `1` through `128`. The generated
186
- program cannot access the workflow context, session state,
187
- credentials, imports, or ordinary tools. Each call starts a new child session; a program cannot
188
- continue a child from an earlier call. Agent authorization, questions, approvals, and cancellation
189
- behave as they do for sessions an authored workflow tool opens with `ctx.agent`.
190
-
191
- The sandbox resumes after every pending call in the current batch settles. `Promise.all` supports
192
- fan-out followed by fan-in. The program must await every `ctx.agent` call before it returns. A call
193
- that is still pending at that point, such as one that is never awaited or one that loses a
194
- `Promise.race` or `Promise.any`, fails the workflow.
124
+ | Export | Entry | What it does |
125
+ | -------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | `createHook<T>({ token?, metadata? })` | `eve/workflow` | Returns a `WorkflowHook<T>`. Await it for the next payload, or iterate it with `for await`. `metadata` is JSON stored with the hook. |
127
+ | `createWebhook({ respondWith? })` | `eve/workflow` | Returns a `WorkflowWebhook` whose `url` resumes it with the incoming `Request`. With `respondWith: "manual"`, answer each `WorkflowWebhookRequest` with `request.respondWith(response)`. |
128
+ | `sleep(duration)` | `eve/workflow` | Waits for a duration such as `"1h"` or a number of milliseconds, or until a `Date`. |
129
+ | `getWorkflowMetadata()` | `eve/workflow` | Returns the run's `workflowName`, `workflowRunId`, `workflowStartedAt`, and `url`. |
130
+ | `FatalError`, `RetryableError` | `eve/workflow` | Throw `FatalError` to fail without a retry. Throw `RetryableError`, with an optional `{ retryAfter }`, to retry a step. |
131
+ | `start(workflow, args)` | `eve/workflow/api` | Starts a `"use workflow"` function on the agent's own workflow queue and deployment. It takes no options; omit `args` when the function takes none. |
132
+ | `getRun(runId)` | `eve/workflow/api` | Returns a `WorkflowRun<T>` with `runId`, `status`, `returnValue`, and `cancel()`. `start` returns the same type. |
133
+ | `resumeHook(token, payload)` | `eve/workflow/api` | Sends a payload to the hook with that token. |
195
134
 
196
- A failed child turn, an invalid call, or a call over the `maxSubagents` budget throws a
197
- `WorkflowProgramAgentError` at that `ctx.agent` call, which the program can catch; the message
198
- says which.
135
+ A hook's `token` resumes it. Pass a fixed `token` to `createHook` when a route must find the hook later. `await hook.getConflict()` registers the hook before you hand out its token, and resolves to the run that already holds the token, or `null`. Call `dispose()`, or declare the hook with `using`, to release the token.
199
136
 
200
- The sandbox converts the program's return value and each `ctx.agent` input with `JSON.stringify`,
201
- so a `Date` becomes a string and functions and `undefined` members drop. A return value that
202
- converts to nothing, such as `undefined`, becomes `null`. Each converted value may be up to 1 MiB of
203
- JSON, each child reply up to 4 MiB of JSON, and the program source up to 256 KiB.
137
+ Import `WorkflowHook`, `WorkflowHookOptions`, `WorkflowWebhook`, `WorkflowWebhookOptions`, `WorkflowWebhookRequest`, and `WorkflowMetadata` from `eve/workflow` for explicit types.
204
138
 
205
- Each start or resume may spend up to 30 seconds running JavaScript and up to 5 minutes in total.
206
- Time spent waiting for child agents does not count toward either limit.
207
-
208
- ### Migrate from `experimental_workflow`
209
-
210
- The experimental uppercase `Workflow` framework tool and its exports have been removed. Replace the
211
- old sentinel:
212
-
213
- ```diff
214
- -import { experimental_workflow } from "eve/tools/workflow";
215
- -
216
- -export default experimental_workflow({ maxSubagents: 20 });
217
- ```
218
-
219
- with the lowercase factory:
220
-
221
- ```ts
222
- import { workflow } from "eve/tools/workflow";
223
-
224
- export default workflow({ maxSubagents: 20 });
225
- ```
226
-
227
- The path gives the authored tool the model-facing name `workflow`. eve does not discover or inject
228
- an agent catalog. Calls use the same target resolution, availability, and authorization checks as
229
- `ctx.agent` in any other authored workflow tool.
230
-
231
- ### Migrate an authored workflow tool
232
-
233
- Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workflow"` directive,
234
- and replace `agent(ctx, input)` and `ask(ctx, request)` with an agent session from
235
- [`ctx.agent(name)`](#delegate-work-ctxagent) and `ctx.ask(request)`. The old `agent` and `ask`
236
- helpers are not exported from `eve/workflow`; that entry exposes durable primitives instead.
237
- Import `WorkflowToolContext`, `AgentSession`,
238
- `ToolQuestion`, `ToolAskOptions`, and `ToolAnswer` from `eve/tools` when you
239
- need explicit types.
240
-
241
- `ctx.ask` no longer accepts `dismissible`, and its `dismissed` status is now `cancelled`. A
242
- steering message withdraws a question an `execute` call asks, so drop the option. To keep a
243
- question open while the conversation continues, ask it from a [`task`](#run-calls-as-tasks-task).
244
-
245
- ```diff
246
- -const answer = await ctx.ask({ prompt, dismissible: true });
247
- +const answer = await ctx.ask({ prompt });
248
- ```
249
-
250
- See [Upgrade to Tasks](/docs/tools/tasks-upgrade) for `task` replacing `execution: "background"`
251
- and the other changes in this release.
139
+ Only these exports are public. A bare `workflow` or `workflow/*` import in an application module fails the build with an error that names these entries.
252
140
 
253
141
  ## Wait for the result
254
142
 
255
- A call to an `execute` tool works like any other tool call from the model's point of view:
256
-
257
- - **Tool result:** the workflow's output after the body finishes.
258
- - **Parent turn:** waits for the call to settle, then continues with the result.
259
- - **Durable wait inside the body:** suspends the workflow while the tool call stays pending.
260
- - **Cancel:** cancelling the turn cancels the run.
261
- - **Steering:** a new message aborts the call's `ctx.abortSignal`, and the call settles with what
262
- the body returns. See [Stop early for a new message](#stop-early-for-a-new-message).
143
+ An `execute` call works like any other tool call. The turn waits for the body to finish and gets its
144
+ output as the tool result. A wait inside the body pauses the workflow while the call stays pending.
145
+ Cancelling the turn cancels the run, and a new message aborts `ctx.abortSignal`; see
146
+ [Stop early for a new message](#stop-early-for-a-new-message).
263
147
 
264
148
  To keep the conversation going while a call works, [define `task` instead](#run-calls-as-tasks-task).
265
149
 
266
- `defineWorkflowTool` does not accept an `execution` option. Passing one throws
267
- `"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.`
268
-
269
150
  ### How suspension works
270
151
 
271
- Suspension happens when a workflow must wait for an unresolved durable operation, such as
272
- `ctx.ask`, an awaited hook or webhook, or `sleep`. The runtime persists the wait and releases the
273
- workflow's compute. When the answer, event, or timer arrives, the runtime replays the workflow,
274
- reuses recorded step results, and continues past the wait. Put side effects in `"use step"`
275
- functions so replay does not repeat completed effects.
152
+ A workflow pauses, holding no compute, when it awaits an unresolved `ctx.ask`, hook, webhook, or
153
+ `sleep`. When the answer, event, or timer arrives, the workflow replays, reuses recorded step
154
+ results, and continues past the wait. Put side effects in `"use step"` functions so replay doesn't
155
+ repeat them.
276
156
 
277
- Consider a body that reports progress and then asks for approval:
157
+ In this body, the yield reports progress and the await pauses:
278
158
 
279
159
  ```ts
280
160
  async *execute(input, ctx) {
@@ -285,21 +165,15 @@ async *execute(input, ctx) {
285
165
  }
286
166
  ```
287
167
 
288
- The yield reports a snapshot, and eve advances the generator to `ctx.ask`. Awaiting the unanswered
289
- request is the durable wait. The original tool call remains pending until the answer arrives and
290
- the body returns.
291
-
292
- `yield` itself does not wait for approval. An ordinary
293
- Promise or Node.js timer inside a step also does not create a durable workflow suspension; use
294
- the workflow operations for waits that must survive a restart.
168
+ The tool call stays pending until the answer arrives and the body returns. An ordinary Promise or
169
+ Node.js timer inside a step doesn't pause the workflow or survive a restart.
295
170
 
296
171
  ## Run calls as tasks: `task`
297
172
 
298
173
  Define `task(input, ctx)` in place of `execute` when the conversation should continue while a call
299
- works, such as a twenty-minute deploy or research the model may not need right away. An `execute`
300
- tool holds the conversation until each call settles, however long it runs. A question, a sleep, or
301
- an approval inside an `execute` call already parks durably and holds no compute, so waiting alone
302
- doesn't need a task.
174
+ works. Examples are a twenty-minute deploy or research the model may not need right away. Waiting
175
+ alone doesn't need a task, because a question, sleep, or approval in an `execute` call already holds
176
+ no compute.
303
177
 
304
178
  ```ts title="agent/tools/deploy.ts"
305
179
  import { defineWorkflowTool } from "eve/tools";
@@ -316,9 +190,8 @@ export default defineWorkflowTool({
316
190
  });
317
191
  ```
318
192
 
319
- A `task` body is written like an `execute` body, with the same `WorkflowToolContext`: returning
320
- settles the call, a throw fails it, and an `async *task` generator can `yield` progress. A
321
- steering message never aborts a task's `abortSignal`.
193
+ A `task` body gets the same `WorkflowToolContext` as an `execute` body. Returning finishes the call,
194
+ a throw fails it, and an `async *task` generator can `yield` progress. Steering never aborts a task.
322
195
 
323
196
  Each call is a task with its own id, `<tool>-<6 characters>`:
324
197
 
@@ -326,20 +199,18 @@ Each call is a task with its own id, `<tool>-<6 characters>`:
326
199
  `Started task deploy-4hd8sa. Its result will arrive in a <task_result> message.`, and the model
327
200
  continues at once.
328
201
  - **Result:** the body's return value or its error arrives later as a `<task_result>` block in a
329
- `task.result` message, which eve appends at the next step boundary. `toModelOutput` projects the
330
- result, not the receipt.
202
+ `task.result` message. eve adds the message before the model's next step. `toModelOutput` applies
203
+ to the result, not the receipt.
331
204
 
332
- The model waits for results with `eve__task_wait` and stops a task with `eve__task_cancel`, and a turn can't
333
- end while tasks are working. `eve__task_cancel`, `session.cancel()`, a failed turn, and the
334
- end of the session abort the call's `abortSignal`; the run waits up to 30 seconds for the body to
335
- finish unwinding, then ends as cancelled. See [Tasks](/docs/tools/tasks) for what the model sees,
336
- how held turns look on the stream, steering, events, and limits.
205
+ The model waits for results with `eve__task_wait` and stops a task with `eve__task_cancel`. A turn
206
+ can't end while tasks are working. See [Cancel and clean up](#cancel-and-clean-up-ctxabortsignal)
207
+ for what aborts a task, and [Tasks](/docs/tools/tasks) for what the model sees, held turns, events,
208
+ and limits.
337
209
 
338
210
  ## Resumable tasks: `serve`
339
211
 
340
212
  Define `serve(receive, ctx)` when the model should be able to send a running task more input, such
341
- as a revision request. A `serve` body runs once per task and gets its calls from `receive()`
342
- instead of taking an input:
213
+ as a revision request. A `serve` body runs once per task and gets its calls from `receive()`:
343
214
 
344
215
  ```ts title="agent/tools/release-plan.ts"
345
216
  import { defineWorkflowTool } from "eve/tools";
@@ -366,190 +237,80 @@ export default defineWorkflowTool({
366
237
  ```
367
238
 
368
239
  A `serve` tool's calls are tasks, with the receipts and results
369
- [described above](#run-calls-as-tasks-task) and the waiting, turn rule, ownership, and limit
370
- described in [Tasks](/docs/tools/tasks). What differs:
371
-
372
- - **`receive()`:** resolves with the next call, `{ input, callId, abortSignal }`, with `input`
373
- validated by `inputSchema`. The first `receive()` resolves at once with the call that started
374
- the task, without a step or a durable wait, and replays deterministically. After that, it
375
- resolves with each call made with the task's `taskId`, in arrival order. Calls that arrive while
376
- the body isn't waiting are kept. A pending `receive()` is shared, so calling it again returns the
377
- same promise. A call counts as received as soon as its promise resolves, even if that promise
378
- lost a `Promise.race`, and the next `ctx.reply()` settles it. If you race `receive()`, keep its
379
- promise until you read the call instead of calling `receive()` again.
380
- - **`taskId` on the model input:** eve adds an optional `taskId` to the tool's model input and
381
- appends a sentence explaining it to the description. A call without `taskId` starts a new task,
382
- whose receipt names it and ends with
383
- `To send it another message, call release-plan again with taskId release-plan-7k2m9q.` A call
384
- with `taskId` goes to that task and returns a receipt that starts
385
- `Sent to task release-plan-7k2m9q.` The build fails if `inputSchema` declares its own
386
- `taskId`.
387
- - **Unknown tasks:** the id must name an unfinished task this tool started; otherwise the call
388
- fails with `UNKNOWN_TASK`. The call can come from any caller in the session.
389
- - **`ctx.session` and `ctx.agents` describe the call being served:** a later call can come in a
390
- later turn than the one that started the task. Its `call.started` and `call.settled` carry that
391
- call's `callId` and turn, and so do the questions and sign-ins the body opens while serving
392
- it. From the moment `receive()` resolves with a call, `ctx.session` is that call's view of
393
- the session, including in a step that receives `ctx`: `ctx.session.turn` is the call's turn, and
394
- `ctx.session.auth` is the auth the session admitted the call with, which may belong to a
395
- different caller than the one that started the task. `getToken`, `requireAuth`, and connections
396
- in a step use the current call's auth. `ctx.agents` lists the
397
- agents the current call may open, including dynamic agents selected in its turn.
398
- - **Body state spans callers:** variables the body keeps between calls, such as `plan` in the
399
- example, may hold what an earlier call from another caller produced. Key per-caller data on
400
- the whole principal in `ctx.session.auth.current`: `authenticator`, `issuer`, `principalType`,
401
- and `principalId` together, because a `principalId` is unique only within its authenticator and
402
- issuer. Anonymous callers, whose `current` is `null` or whose `principalType` is `"anonymous"`,
403
- share one identity, so don't keep per-person data for them. Any caller in the session can
404
- continue or cancel the task; see [Tasks](/docs/tools/tasks#ownership-and-limits).
405
- - **Agents belong to the call that opened them:** a session the body opens with `ctx.agent` while
406
- serving a call is that call's child. Its `session.parent` names the call's `callId` and turn.
407
- The first turn of a local child uses the call's tool span as its parent when trace context is
408
- available. A remote child starts its own trace; its first turn links to the call's tool span
409
- with `eve.link.type=agent.dispatch` when trace context is available. Later child turns start new
410
- traces. Parent session lineage stays tied to the opening call, even after the task receives
411
- another call; a remote receiver accepts that lineage only from a trusted forwarder. Each message
412
- uses the auth of the call being served; remote identity follows the
240
+ [described above](#run-calls-as-tasks-task). [Tasks](/docs/tools/tasks) covers waiting, the turn
241
+ rule, who can continue a task, and the task limit.
242
+
243
+ ### Receive calls and reply
244
+
245
+ eve adds an optional `taskId` to the tool's model input and explains it in the description. The
246
+ build fails if `inputSchema` declares its own `taskId`. A call without `taskId` starts a new task. Its
247
+ receipt ends with
248
+ `To send it another message, call release-plan again with taskId release-plan-7k2m9q.` A call with
249
+ `taskId` goes to that task. Its receipt starts `Sent to task release-plan-7k2m9q.` The
250
+ `taskId` must name an unfinished task this tool started, or the call fails with `UNKNOWN_TASK`.
251
+ Any caller in the session can send it.
252
+
253
+ - `receive()` resolves with the next call, `{ input, callId, abortSignal }`, with `input` validated
254
+ by `inputSchema`. The first call is the one that started the task. Later calls arrive in order.
255
+ - eve keeps calls that arrive while the body isn't waiting. A second `receive()` while one is
256
+ pending returns the same promise.
257
+ - A call counts as received once its promise resolves, even if it lost a `Promise.race`. The next
258
+ `ctx.reply()` answers it, so keep a raced `receive()` promise until you read the call.
259
+ - `ctx.reply(output)` answers every call received so far. Each call reports its own
260
+ `call.settled`, the model receives the reply once, and the task goes idle until its next call.
261
+ - A reply with no call waiting is dropped, and `ctx.ask` throws while no call is waiting.
262
+ - A reply withdraws the open questions of the calls it answers. It doesn't abort their
263
+ `abortSignal`, so work after the reply keeps running.
264
+ - Returning answers the calls still waiting and ends the task; a throw fails them. `serve` isn't a
265
+ generator, so it can't `yield` progress.
266
+
267
+ ### Working, idle, and cancelled tasks
268
+
269
+ - A resumable task is working while one of its calls has no result, and idle otherwise. Only a
270
+ working task holds the turn and counts toward the
271
+ [task limit](/docs/tools/tasks#ownership-and-limits).
272
+ - One stretch of work runs from a call reaching an idle task until a reply or cancel ends its
273
+ calls. Calls in a stretch share one `abortSignal`. The next stretch gets a new one, so a task can
274
+ be cancelled any number of times.
275
+ - `eve__task_cancel`, `session.cancel()`, and a failed turn end the waiting calls as `cancelled`,
276
+ abort the stretch's signal, and make the task idle.
277
+ - To stay available after a cancel, the body must catch the abort and return to `receive()` within
278
+ 30 seconds, as the example does. Otherwise the task finishes. A body that ignores the signal keeps
279
+ working, and its reply is dropped.
280
+ - The task finishes when its body returns or throws, or when the session ends. The end of the
281
+ session aborts the current signal and rejects a pending `receive()`.
282
+
283
+ ### Calls from several callers
284
+
285
+ A later call can come in a later turn, from a different caller than the one that started the task.
286
+ Once `receive()` resolves with a call, the context describes that call:
287
+
288
+ - `ctx.session.turn` is the call's turn, and `ctx.session.auth` is the auth the session accepted the
289
+ call with. Steps that receive `ctx` see the same values, so `getToken`, `requireAuth`, and
290
+ connections use that call's auth.
291
+ - `ctx.agents` lists the agents the call may open, including dynamic agents selected in its turn.
292
+ - The call's `call.started` and `call.settled` events carry its `callId` and turn. So do the
293
+ questions and sign-ins the body opens while serving it.
294
+ - A session the body opens with `ctx.agent` belongs to that call. Its `session.parent` names the
295
+ call's `callId` and turn, even after later calls. A remote receiver accepts that parent only from
296
+ a trusted forwarder.
297
+ - Each message to that child uses the call's auth. Remote identity follows the
413
298
  [forwarding rules](../guides/remote-agents#forwarding-the-caller-identity).
414
- - **Results:** `ctx.reply(output)` settles every call received so far with `output`, all at once.
415
- Each settled call reports its own `call.settled`, and the model receives the reply once. The task
416
- then goes idle until its next call. A reply with
417
- no call left to settle is dropped, and `ctx.ask` throws while no call is waiting for a result.
418
- A reply also withdraws the questions still pending for the calls it settles, but doesn't abort
419
- their `abortSignal`, so work the body continues after replying keeps running.
420
- Returning settles the calls still waiting and ends the task; a throw fails them. `serve` is not
421
- a generator, so it can't `yield` progress.
422
- - **Working and idle:** a resumable task is working while one of its calls has no result, and idle
423
- otherwise. An idle task doesn't hold the turn and doesn't count toward the limit of 32; a call
424
- that makes it work again does. The `[Tasks]` note lists the 10 most recently used idle tasks
425
- after the working ones, so the model can find them again.
426
- - **One `abortSignal` per stretch of work:** a stretch starts when a call reaches an idle task and
427
- ends when a reply or a cancel settles its calls. Calls that arrive during a stretch share its
428
- signal, and the next stretch gets a new one, so a task can be cancelled any number of times.
429
- - **Cancellation:** `eve__task_cancel`, `session.cancel()`, and a failed turn settle the task's waiting
430
- calls as `cancelled` and abort the stretch's `abortSignal`. The run keeps waiting for more calls,
431
- so the task becomes idle and stays available. `eve__task_cancel` on an idle task says the task had no
432
- work to stop. To stay available, a body must catch its stretch's abort and
433
- return to `receive()`, as the example does; an abort that escapes the body finishes the task. A
434
- body that ignores the signal keeps working and its reply is dropped, but a body that doesn't
435
- return to `receive()` within 30 seconds of a cancel ends, and the task finishes.
436
- - **Finishing:** the task finishes when its body returns or throws, or when the session ends,
437
- which aborts the current stretch's signal and rejects a pending `receive()`.
299
+ - When trace context is available, a local child's first turn uses the call's tool span as its
300
+ parent. A remote child's first turn starts its own trace, linked to that span with
301
+ `eve.link.type=agent.dispatch`. Later child turns start new traces.
438
302
 
439
- Every [agent tool](/docs/subagents), including the built-in `agent` tool and remote agents, is a
440
- `serve` tool that eve builds this way on public API: each task opens one session with
441
- [`ctx.agent`](#delegate-work-ctxagent), sends each call's `message` with that call's `abortSignal`,
442
- and replies with the final response of each agent turn. Unlike other `serve` tasks, cancelling an
443
- agent task ends it; start a new task to delegate again.
444
-
445
- ## Authorize inside a step
446
-
447
- Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there. User-scoped providers
448
- resolve as whoever launched this workflow tool, even if another person speaks in the session while it waits.
449
- The provider declaration and the API request both stay inside the step:
303
+ Variables the body keeps between calls, such as `plan`, can hold another caller's output. Key
304
+ per-caller data on these `ctx.session.auth.current` fields together: `authenticator`, `issuer`,
305
+ `principalType`, and `principalId`. A `principalId` is unique only within its authenticator and
306
+ issuer. Anonymous callers, whose `current` is `null` or whose `principalType` is `"anonymous"`,
307
+ share one identity, so don't keep per-person data for them. Any caller in the session can continue
308
+ or cancel the task; see [Tasks](/docs/tools/tasks#ownership-and-limits).
450
309
 
451
- ```ts
452
- import { connect } from "@vercel/connect/eve";
453
- import type { WorkflowStepToolContext } from "eve/tools";
454
-
455
- async function readRepository(ctx: WorkflowStepToolContext, repository: string) {
456
- "use step";
457
- const provider = connect("github/my-agent");
458
- const { token } = await ctx.getToken(provider);
459
- const response = await fetch(`https://api.github.com/repos/${repository}`, {
460
- headers: { Authorization: `Bearer ${token}` },
461
- });
462
- if (response.status === 401) ctx.requireAuth(provider);
463
- if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
464
- return response.json();
465
- }
466
- ```
467
-
468
- Connection tools, ordinary tools, and workflow steps use the same
469
- authorization machinery for requester identity, token caching, callback completion, and rejection
470
- after sign-in. The execution runtime owns the wait: an agent returns to its model after authorization,
471
- while a workflow retries the interrupted step and continues the authored body.
472
-
473
- The workflow body calls `await readRepository(ctx, repository)`.
474
-
475
- <Callout type="warning" title="Keep tokens out of step results">
476
- Step results enter the workflow's durable history, so do not return the token from the helper.
477
- eve's token cache stays inside the step. The step input is recorded too and, after sign-in,
478
- carries the provider's callback parameters, such as a one-time authorization code. This matches
479
- how agent turns record callbacks. Bearer tokens are never written.
480
- </Callout>
481
-
482
- When sign-in is required, the step attempt ends and the workflow waits on its own callback hook,
483
- without holding compute. The channel renders the sign-in challenge. After the callback, eve retries
484
- **the whole interrupted step**, resolves the token, and continues. Previously completed steps are
485
- not rerun. Resolve auth before other side effects in that step, and make operations before
486
- `requireAuth` safe to retry. A token rejected immediately after sign-in fails instead of prompting
487
- again. Provider declarations can be shared imports, but context must be passed directly, not nested
488
- inside another argument or captured in a closure.
489
-
490
- After a successful callback exchange, eve records a completion marker before returning to authored
491
- code. If that code later fails and the step retries, eve reads the token from the provider instead
492
- of exchanging the same callback again. The provider must persist the grant or token; the marker
493
- itself contains no credentials.
494
-
495
- Cancelling an authorization wait withdraws its callback. Cancellation uses the existing turn
496
- cancellation path rather than a separate authorization completion event.
497
-
498
- ## Use the session sandbox in a step
499
-
500
- Pass `ctx` directly to a step helper and call `ctx.getSandbox()` there. The step opens the
501
- [sandbox](/docs/sandbox) of the session that called the tool, the same sandbox that session's
502
- turns use. When the session shares its parent's sandbox, as a copy started by the built-in `agent`
503
- tool does, the step opens that shared sandbox. The step sees files the session wrote, and the
504
- session's later tool calls see files the step writes:
505
-
506
- ```ts title="agent/tools/analyze.ts"
507
- import { defineWorkflowTool, type WorkflowStepToolContext } from "eve/tools";
508
- import { z } from "zod";
509
-
510
- export default defineWorkflowTool({
511
- description: "Prepare the input file for an analysis run.",
512
- inputSchema: z.object({ value: z.string() }),
513
- async task(input, ctx) {
514
- "use workflow";
515
- await prepareInput(ctx, input);
516
- return { path: "/workspace/input.json" };
517
- },
518
- });
519
-
520
- async function prepareInput(ctx: WorkflowStepToolContext, input: { value: string }) {
521
- "use step";
522
- const sandbox = await ctx.getSandbox();
523
- await sandbox.writeTextFile({ path: "/workspace/input.json", content: JSON.stringify(input) });
524
- }
525
- ```
526
-
527
- - The workflow body cannot open the sandbox, because it replays. `ctx.getSandbox()` in the body
528
- throws and tells you to pass `ctx` to a step helper.
529
- - The step opens the sandbox directly, with any sandbox provider. If the session recorded its
530
- sandbox before it called the tool, the step resumes it. Otherwise, or if that sandbox is gone by
531
- the time the step runs, the step opens it the way the session's first turn would: it runs your
532
- `defineSandbox()` definition, and the provider finds or creates the sandbox by the session's id. The session's later turns open the same sandbox. Your
533
- definition can run once for each caller that opens the sandbox before the session records it,
534
- so make its initialization safe to repeat.
535
- - The step does not own the sandbox. When the step ends, even by throwing, eve lets go of the
536
- step's handle and leaves the sandbox running for the session. eve never stops or deletes the
537
- sandbox for a step, and `sandbox.stop()` and `sandbox.delete()` in a step fail without a retry,
538
- because the session's turns may be using the sandbox.
539
- - The session removes the sandbox when the session ends, even when only a step opened it. A step
540
- that is still running when the session ends can open the sandbox again after that cleanup, and
541
- nothing removes the new one.
542
- - When the eve server shuts down, it stops the sandboxes its sessions opened, but not one that
543
- only a step opened. With Docker, that container keeps running until the session ends or you
544
- stop it.
545
- - A step can use the sandbox while the session's turns use it too, as subagents that share a
546
- sandbox do. Give each one its own files to write.
547
- - Steps run at least once and retry after a failure, so make sandbox writes safe to repeat. Write
548
- whole files instead of appending to them, or check for earlier output first.
549
- - When the session shares its parent's sandbox, the step opens it by the parent's session id with
550
- the parent's sandbox definition, and the parent removes it when the parent ends.
551
- - A step runs wherever the workflow runs. A sandbox that lives on one machine, such as just-bash
552
- on the local disk, is reachable from a step only on that machine, as in local development.
310
+ Every [agent tool](/docs/subagents), including the built-in `agent` tool and remote agents, is a
311
+ `serve` tool. Each agent task holds one session with the agent and replies with the final response
312
+ of each agent turn. Unlike other `serve` tasks, cancelling an agent task ends it, so start a new
313
+ task to delegate again.
553
314
 
554
315
  ## Ask a human: `ctx.ask`
555
316
 
@@ -569,24 +330,21 @@ const answer = await ctx.ask(
569
330
  // | { status: "unavailable" }
570
331
  ```
571
332
 
572
- `ctx.ask` opens an interaction on the session (`interaction.opened`) — rendered the way channels
573
- render tool approvals — and returns an awaitable answer. Awaiting it suspends the run until a response arrives.
574
- The `ask_question` tool is a workflow tool built on `ctx.ask`.
333
+ `ctx.ask` opens a question on the session, reported as `interaction.opened`, and channels show it
334
+ like a tool approval. Awaiting the answer pauses the run. The provided `ask_question` tool is built
335
+ on `ctx.ask`.
575
336
 
576
- The answer's `status` tells the body what happened:
337
+ | `status` | Meaning |
338
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
339
+ | `answered` | The person picked an option (`optionId`) or typed a reply (`text`). |
340
+ | `cancelled` | The question was withdrawn before anyone answered, because `signal` or the call's `abortSignal` aborted or a `serve` body replied to the call. The stream reports `interaction.settled` as `withdrawn`, so clients stop offering it. |
341
+ | `unavailable` | The session cannot ask for input, such as a scheduled run. `ctx.ask` returns this immediately. |
577
342
 
578
- - `answered`: the person picked an option (`optionId`) or typed a reply (`text`).
579
- - `cancelled`: the request was withdrawn before anyone answered it, because the `signal` passed to
580
- `ctx.ask` or the call's `abortSignal` aborted, or because a `serve` body replied to the call. The
581
- session settles the interaction `withdrawn`, so clients stop offering the question.
582
- - `unavailable`: the session cannot request input, such as a scheduled run. `ctx.ask` returns this
583
- immediately instead of waiting for an answer no one can give.
343
+ A plain follow-up message answers the question when it is the only one open. The message must match
344
+ an option, or the question must allow free text. Answer a question from a subagent with a structured
345
+ response.
584
346
 
585
- A plain follow-up message answers the request when it is the only pending question and the message
586
- matches an option or the request allows free text. Answer a question from a subagent with a
587
- structured response.
588
-
589
- `ctx.ask` composes with the SDK's own constructs; race it against a deadline:
347
+ Race `ctx.ask` against `sleep` for a deadline:
590
348
 
591
349
  ```ts
592
350
  const pending = ctx.ask({ prompt: `Deploy ${service}?`, options: APPROVE_OR_CANCEL });
@@ -594,24 +352,23 @@ const answer = await Promise.race([pending, sleep("4h")]);
594
352
  if (answer === undefined) return { deployed: false, reason: "timed out" };
595
353
  ```
596
354
 
597
- - The request belongs to the run, not the turn. It stays answerable until it is answered, withdrawn,
598
- or the run ends.
599
- - A request is answered once. Ask again for the next answer.
600
- - Choose option `id`s that read well on their own, such as `approve` or the option's label. A
601
- response carries only the `id`. If a person answers after the request has already resolved, for
602
- example from an old Slack menu, the agent receives the `id` as a new message, not the label.
603
- - Ending the run, by returning, throwing, or cancellation, withdraws its pending requests.
604
- - Several requests may be outstanding at once.
605
- - A response never steers. A new human message that does not answer a pending request follows the
606
- session's normal `turnPolicy`. A steering message aborts the `abortSignal` of each `execute` call
607
- the turn waits on, which withdraws that call's questions, such as `ask_question`'s. A task's
608
- questions stay open.
609
- - An aborted `signal` asks the session to withdraw the question, and the session decides. If a
610
- person's answer reached the session first, the ask resolves as `answered` even though the signal
611
- aborted, and the channel shows it answered. Branch on `status`, not on the signal.
355
+ - The question belongs to the run, not the turn. It stays open until someone answers it, it is
356
+ withdrawn, or the run ends by returning, throwing, or cancellation.
357
+ - Each question is answered once, so ask again for the next answer. Several questions can be open
358
+ at once.
359
+ - A response carries only the option `id`, so choose ids that read well on their own, such as
360
+ `approve`. If a person answers after the question ended, for example from an old Slack menu, the
361
+ agent receives the `id` as a new message.
362
+ - A response never steers. A new message that answers no open question follows the session's
363
+ `turnPolicy`. Steering withdraws the questions of the `execute` calls the turn waits on, such as
364
+ `ask_question`'s, but not a task's. See [Stop early for a new message](#stop-early-for-a-new-message).
365
+ - An aborted `signal` asks the session to withdraw the question. If a person's answer reached the
366
+ session first, the ask resolves as `answered` and the channel shows it answered. Branch on
367
+ `status`, not on the signal.
612
368
 
613
369
  Compare the [`approval`](/docs/human-in-the-loop) policy, which gates the call before `execute` runs
614
- and can only show the model's input. Both compose: `approval` before the run, `ctx.ask` inside it.
370
+ and can only show the model's input. Use both together: `approval` before the run, `ctx.ask` inside
371
+ it.
615
372
 
616
373
  ## Delegate work: `ctx.agent`
617
374
 
@@ -630,8 +387,8 @@ const response = await reviewer.send("Review the deployment plan for security ri
630
387
  const { data, reply, status } = await response.result();
631
388
  ```
632
389
 
633
- Set `model` when the workflow should run a local child with a different AI Gateway model. The
634
- selection belongs to the returned session, so every message sent through that handle uses it:
390
+ Set `model` to run a local child on a different AI Gateway model. Every message sent through the
391
+ returned session uses it:
635
392
 
636
393
  ```ts
637
394
  const reviewer = ctx.agent("agent", {
@@ -657,24 +414,26 @@ const reviewer = ctx.agent("agent", {
657
414
  });
658
415
  ```
659
416
 
660
- Without `modelContextWindowTokens`, eve reads the model's context window from the AI Gateway model
661
- catalog recorded when the agent was built. Set it for a model that catalog doesn't list; otherwise
662
- the first `send` rejects.
417
+ Omit `modelContextWindowTokens` to read the context window from the AI Gateway model catalog
418
+ recorded at build time. Set it for a model the catalog doesn't list; otherwise the first `send`
419
+ rejects.
663
420
 
664
- The selection must contain an AI Gateway model id. A live AI SDK `LanguageModel` cannot cross the
665
- durable workflow boundary. A remote agent rejects the option because its deployment owns its model
421
+ The selection must contain an AI Gateway model id, because a live AI SDK `LanguageModel` can't be
422
+ saved across waits. A remote agent rejects `model`, because its deployment owns its model
666
423
  configuration.
667
424
 
668
- The name is an available agent target. On the root agent, `"agent"` starts a copy of the root agent.
669
- A declared subagent uses its path-derived name and remains callable when hidden with `tool: false`
670
- or `disableTool()`. Delegated root copies and declared subagent contexts do not expose the built-in
671
- root-copy target. The invocation name `agent` is reserved, so a declared subagent cannot shadow it.
672
- An unavailable name rejects the first `send`.
425
+ The name is an available agent target:
426
+
427
+ - On the root agent, `"agent"` starts a copy of the root agent. Delegated root copies and declared
428
+ subagents can't open that copy.
429
+ - A declared subagent uses its path-derived name, and stays callable when hidden with `tool: false`
430
+ or `disableTool()`.
431
+ - The name `agent` is reserved, so a declared subagent can't use it.
432
+ - An unavailable name rejects the first `send`.
673
433
 
674
- `send(message, options?)` accepts text or `MessageContent<string | URL>`: up to 64 text and
675
- file parts. File `data` must be an HTTP(S) URL, as a string or `URL` object. Inline bytes, base64,
676
- and `data:` URLs are rejected before dispatch so attachment bytes do not enter durable workflow
677
- inputs. Upload a local file first, then send its URL:
434
+ `send(message, options?)` accepts text or `MessageContent<string | URL>`: up to 64 text and file
435
+ parts. File `data` must be an HTTP(S) URL, as a string or `URL` object. eve rejects inline bytes,
436
+ base64, and `data:` URLs before sending, so upload a local file first and send its URL:
678
437
 
679
438
  ```ts
680
439
  await reviewer.send([
@@ -683,46 +442,50 @@ await reviewer.send([
683
442
  ]);
684
443
  ```
685
444
 
686
- The options are:
687
-
688
445
  | Option | Description |
689
446
  | -------------- | -------------------------------------------------------------------------------------------------------- |
690
447
  | `outputSchema` | Structured output for the turn, as a Standard JSON Schema such as a Zod schema, or a JSON Schema object. |
691
448
  | `signal` | Aborting it cancels the turn the message started or joined. The turn still reports, as cancelled. |
692
449
 
693
- A message sent while the session's turn is running joins that turn, and its response resolves with
694
- that turn's result. If the turn ends before the agent reads the message, the message starts the next
695
- turn instead, and its response resolves with that turn's result. The responses of earlier messages
696
- that are still waiting resolve with the same result. A message sent while the session is idle starts
697
- the next turn, and the session keeps its conversation between turns. `result()` returns:
450
+ A message sent while the child's turn is running joins that turn, and its response resolves with
451
+ that turn's result. If the turn ends before the agent reads the message, the message starts the
452
+ next turn. Its response, and those of earlier messages still waiting, resolve with that turn's
453
+ result. A message sent while the session is idle starts the next turn. The session keeps its
454
+ conversation between turns.
455
+
456
+ `result()` returns:
698
457
 
699
458
  | Field | Description |
700
459
  | -------------- | --------------------------------------------------------------------------------------------------------- |
701
460
  | `data` | The structured value, when the turn requested `outputSchema`. |
702
461
  | `reply` | The agent's final reply text, when available. |
703
462
  | `status` | `"completed"`, `"failed"`, or `"cancelled"`. Completion does not by itself mean the session ended. |
704
- | `sessionEnded` | Whether the session ended in the response's final commit. |
463
+ | `sessionEnded` | Whether the session ended with this turn. |
705
464
  | `error` | `{ message }` with the reason the turn failed. Required when `status` is `"failed"` and absent otherwise. |
706
465
 
707
- Every `ctx.agent(name, options?)` call returns a new session that only the workflow run can address.
708
- The model does not see it; it sees what the tool returns. A local child runs as the caller's principal with the
709
- caller's capabilities. A remote child does not inherit the caller's session principal by default;
710
- the receiving deployment determines its identity from the outbound request. To forward the caller's
711
- identity, set `forwardPrincipal: true` on the remote agent and configure the receiver's
712
- `trustedForwarders` (see [Forwarding the caller identity](../guides/remote-agents#forwarding-the-caller-identity)).
713
- A person answers the child's questions and sign-ins at the root session, as for any subagent.
714
- The session ends when the run finishes, which cancels any turn still running.
466
+ Each `ctx.agent(name, options?)` call returns a new session that only this workflow run can send to.
467
+ The model sees only what the tool returns. The session ends when the run finishes, which cancels any
468
+ turn still running.
469
+
470
+ - **Local child:** runs with the caller's auth.
471
+ - **Remote child:** its identity comes from the outbound request, not the caller's session. To
472
+ forward the caller's identity, set `forwardPrincipal: true` on the remote agent and configure the
473
+ receiver's `trustedForwarders`. See
474
+ [Forwarding the caller identity](../guides/remote-agents#forwarding-the-caller-identity).
475
+ - **Questions and sign-ins:** a person answers the child's questions and sign-ins at the root
476
+ session, as for any subagent.
715
477
 
716
- The parent stream announces each session with `child.opened`, which carries its `owner` (the
717
- task whose run opened the session, or the tool call when the call doesn't run as a task), the
718
- agent `name`, the child's `sessionId`, and its `stream` path. Pass the event to
719
- [`session.agent(opened).stream()`](/docs/guides/client/streaming#follow-a-subagent) to follow the child.
478
+ The parent stream announces each session with `child.opened`. The event carries the agent `name`,
479
+ the child's `sessionId`, its `stream` path, and its `owner`. `owner` is the task whose run opened
480
+ the session, or the tool call when the call doesn't run as a task. Pass the event to
481
+ [`session.agent(opened).stream()`](/docs/guides/client/streaming#follow-a-subagent) to follow the
482
+ child.
720
483
 
721
484
  ### Route to a hidden subagent with Jev
722
485
 
723
- Use an authored workflow tool when the parent model should decide to delegate, but [Jev](https://vercel.com/i/what-is-jev) should choose the specialist. Set `tool: false` on each specialist so the parent model sees only the routing tool. The specialists remain available through `ctx.agents` and callable through `ctx.agent()`.
486
+ Use an authored workflow tool when the parent model should decide to delegate, but [Jev](https://vercel.com/i/what-is-jev) should choose the specialist. Set `tool: false` on each specialist so the parent model sees only the routing tool. `ctx.agents` and `ctx.agent()` still reach the specialists.
724
487
 
725
- If the router may select the root-copy `agent`, author a root `description` that explains which work should stay with a copy of the root. `ctx.agents.agent` always exists in a top-level root workflow, but its `description` is an empty string when omitted from `agent.ts`. `agentRouter()` considers only entries with a non-empty description, so it does not route to an undescribed root copy.
488
+ If the router may select the root-copy `agent`, give the root a `description` that says which work should stay with a copy of the root. Without one, `ctx.agents.agent.description` is an empty string, which `agentRouter()` skips.
726
489
 
727
490
  ```ts title="agent/agent.ts"
728
491
  import { defineAgent } from "eve";
@@ -753,7 +516,7 @@ export default defineAgent({
753
516
  });
754
517
  ```
755
518
 
756
- Define the model-visible router under `agent/tools/`. Build the Jev criteria from the subagents' effective descriptions, then pass its typed choice directly to `ctx.agent()`:
519
+ Define the model-visible router under `agent/tools/`. Build the Jev criteria from the subagents' descriptions, then pass its typed choice to `ctx.agent()`:
757
520
 
758
521
  ```ts title="agent/tools/agent-router.ts"
759
522
  import { decide } from "eve/ai";
@@ -805,9 +568,9 @@ export default defineWorkflowTool({
805
568
  });
806
569
  ```
807
570
 
808
- The decision runs in a step so workflow replay records its result instead of making the routing request again. The parent model receives `agent-router`, but not `researcher` or `operator`. Jev returns the typed `"researcher" | "operator"` choice, and the selected subagent's reply becomes the `agent-router` tool result.
571
+ The decision runs in a step, so replay reuses it instead of repeating the routing request. The parent model sees only `agent-router`, and the selected subagent's reply becomes its tool result.
809
572
 
810
- `ctx.agents` is a replay-stable metadata snapshot taken when the session admits the call. In a `serve` task, it follows the call being served. In a top-level root workflow, `ctx.agents.agent` always represents the root-copy target and carries the root's authored `description` when provided. The snapshot also includes declared agents hidden from the parent model with `tool: false` or `disableTool()`, but exposes no model definitions, credentials, or callbacks. A delegated root copy omits `agent`, so `agentRouter()` cannot select another root copy recursively. Invocation still checks each target's availability through `ctx.agent()`.
573
+ `ctx.agents` holds agent metadata as it was when the session accepted the call, and replay doesn't change it. In a `serve` task, it follows the call being served. It includes agents hidden with `tool: false` or `disableTool()`, but no model definitions, credentials, or callbacks. In a top-level root workflow, `ctx.agents.agent` always exists as the root-copy target. A delegated root copy omits `agent`, so `agentRouter()` can't select another root copy. `ctx.agent()` still checks each target's availability.
811
574
 
812
575
  #### Route across every agent target
813
576
 
@@ -819,13 +582,68 @@ import { agentRouter } from "eve/tools/agent_router";
819
582
  export default agentRouter();
820
583
  ```
821
584
 
822
- Its input is `{ message: string }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to Jev, then sends the message to a new session with the selected agent through `ctx.agent()` and returns its reply. It invokes a sole target without decision. Each call
823
- runs as a [task](#run-calls-as-tasks-task), so the reply reaches the model as the task's result. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
585
+ Its input is `{ message: string }`. `agentRouter()` considers only targets with a non-empty description. With two or more, Jev picks one from the message and descriptions; a sole target gets the message directly. The router sends the message to a new session with that agent. Each call runs as a [task](#run-calls-as-tasks-task), so the reply reaches the model as the task's result. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
824
586
 
825
587
  When an authored tool accepts a JSON Schema supplied by the model, represent that input with a permissive object such as `z.looseObject({})`. Avoid `z.record(z.string(), z.json())`: its generated JSON Schema uses `propertyNames`, which OpenAI does not support. Validate the supplied value at the point where your tool consumes it.
826
588
 
827
589
  This pattern controls specialist selection, not whether the parent model delegates at all. Route before the parent model runs if every incoming request must go through Jev.
828
590
 
591
+ ## Add a runtime-generated workflow tool
592
+
593
+ Export the provided `workflow` factory from `agent/tools/workflow.ts` when the model should write the
594
+ JavaScript program at runtime:
595
+
596
+ ```ts title="agent/tools/workflow.ts"
597
+ import { workflow } from "eve/tools/workflow";
598
+
599
+ export default workflow({ maxSubagents: 20 });
600
+ ```
601
+
602
+ The model supplies an async function body through the tool's `js` input. Each call runs as a
603
+ [task](#run-calls-as-tasks-task), so the program's return value reaches the model in a
604
+ `task.result` message.
605
+
606
+ The program can only call `ctx.agent(name, { message, outputSchema? })`. It sends the message to a
607
+ new session with that agent, and resolves to the reply or, when `outputSchema` is set, to the
608
+ structured value. The program can call subagents hidden with `tool: false` or a same-named
609
+ `disableTool()` file, so list their path-derived names in the tool description or agent
610
+ instructions:
611
+
612
+ ```js
613
+ const [triage, review] = await Promise.all([
614
+ ctx.agent("ticket-triage", { message: JSON.stringify(tickets) }),
615
+ ctx.agent("ticket-review", { message: JSON.stringify(tickets) }),
616
+ ]);
617
+ return { triage, review };
618
+ ```
619
+
620
+ Omit `maxSubagents` to allow `100` agent calls; set an integer from `1` through `128`. The program
621
+ can't use the workflow context, session state, credentials, imports, or ordinary tools. Each
622
+ `ctx.agent` call starts a new child session, so a program can't continue a child from an earlier
623
+ call. Agent authorization, questions, approvals, and cancellation work as they do for sessions an
624
+ authored workflow tool opens with `ctx.agent`.
625
+
626
+ The program continues after every pending call in the current batch finishes, so `Promise.all`
627
+ supports fan-out followed by fan-in. A `ctx.agent` call still pending when the program returns
628
+ fails the workflow, such as one never awaited or one that loses a `Promise.race` or `Promise.any`.
629
+
630
+ A failed child turn, an invalid call, or a call over the `maxSubagents` budget throws a catchable
631
+ `WorkflowProgramAgentError` at that `ctx.agent` call. The error message names the cause.
632
+
633
+ The return value and each `ctx.agent` input pass through `JSON.stringify`, so a `Date` becomes a
634
+ string, and functions and `undefined` members drop. A return value that converts to nothing, such
635
+ as `undefined`, becomes `null`.
636
+
637
+ | Limit | Value |
638
+ | ----------------------------------------- | ---------- |
639
+ | Return value or `ctx.agent` input as JSON | 1 MiB |
640
+ | Child reply as JSON | 4 MiB |
641
+ | Program source | 256 KiB |
642
+ | JavaScript time per start or resume | 30 seconds |
643
+ | Total time per start or resume | 5 minutes |
644
+
645
+ Time spent waiting for child agents does not count toward either time limit.
646
+
829
647
  ## Start channel sessions: `ctx.to`
830
648
 
831
649
  A workflow tool reaches the agent's channels with [`ctx.to(channel, target)`](/docs/tools#start-channel-sessions-ctxto), as an ordinary tool does. Call it in a `"use step"` helper that receives `ctx`, like `ctx.getSandbox()`; the workflow body throws when it calls it:
@@ -864,27 +682,24 @@ async function openIncident(ctx: WorkflowStepToolContext, channelId: string, sum
864
682
  }
865
683
  ```
866
684
 
867
- A step that fails retries, so pass an `idempotencyKey` the retry repeats. The destination session dedupes keys from every sender, and `ctx.callId` is unique only within the calling session and is the same for every step of the call, so include `ctx.session.id` and add a label for each send. Create the channel in its own step: a retried send step then reuses the recorded `channelId` instead of creating another channel.
685
+ A failed step retries, so pass an `idempotencyKey` that the retry repeats. Include `ctx.session.id`, because the target session dedupes keys from every sender. Add a label for each send, because `ctx.callId` is the same for every step of the call. Create the channel in its own step, so a retried send step reuses the saved `channelId` instead of creating another channel.
868
686
 
869
687
  `ctx.channel` holds the `kind`, `continuationToken`, and `metadata` of the channel serving the calling session, in the workflow body and in steps, as in [ordinary tools](/docs/tools#the-ctx-parameter).
870
688
 
871
689
  ## Report progress: `yield`
872
690
 
873
- A workflow body may be an async generator whose yields report progress. After processing a yield,
874
- eve advances the generator; use an awaited workflow operation when the body needs to suspend.
691
+ A workflow body can be an async generator whose yields report progress. A yield doesn't pause the
692
+ body; await a workflow operation to pause.
875
693
 
876
694
  | Operation | Behavior |
877
695
  | --------------- | ----------------------------------------------------------------- |
878
696
  | `yield value` | Emits a `call.progress` snapshot for the pending tool call. |
879
- | `return value` | Settles the tool call with its output. |
697
+ | `return value` | Ends the tool call with its output. |
880
698
  | No return value | Uses the last yield as output, or `null` if there were no yields. |
881
699
 
882
- An explicit `return null` also falls back to the last yield. Prefer an
883
- explicit object return when progress snapshots and the final result have different shapes.
884
- Progress snapshots are last-write-wins by tool call id and do not enter model history as
885
- intermediate tool results. A snapshot used as the final output does enter history as the tool result.
886
-
887
- This workflow reports progress, then suspends until its timer expires:
700
+ An explicit `return null` also falls back to the last yield, so return an object when progress
701
+ snapshots and the final result have different shapes. Each snapshot replaces the previous one and
702
+ stays out of the model's history, unless it becomes the final output.
888
703
 
889
704
  ```ts title="agent/tools/remind_with_progress.ts"
890
705
  import { defineWorkflowTool } from "eve/tools";
@@ -903,16 +718,15 @@ export default defineWorkflowTool({
903
718
  });
904
719
  ```
905
720
 
906
- Use [`ctx.ask`](#ask-a-human-ctxask) when the workflow needs a human answer. See
907
- [yield and return](/docs/tools#yield-and-return) for the final-output rules.
721
+ See [yield and return](/docs/tools#yield-and-return) for the final-output rules.
908
722
 
909
723
  ## Cancel and clean up: `ctx.abortSignal`
910
724
 
911
- `ctx.abortSignal` aborts when the call is cancelled: by `session.cancel()`, or, for a task, by
912
- `eve__task_cancel`, a failed turn, or the end of the session. A steering message also aborts it for an
913
- `execute` call; see [Stop early for a new message](#stop-early-for-a-new-message). It is durable:
914
- it survives replay, and a step that receives it observes the abort. Pass it into the steps that
915
- should stop, and clean up in `try/finally`:
725
+ `ctx.abortSignal` aborts when the call is cancelled by `session.cancel()`. For a task, it also aborts
726
+ on `eve__task_cancel`, a failed turn, or the end of the session. For an `execute` call, a steering
727
+ message aborts it too; see [Stop early for a new message](#stop-early-for-a-new-message). The signal
728
+ survives replay, and a step that receives it sees the abort. Pass it into the steps that should
729
+ stop, and clean up in `try/finally`:
916
730
 
917
731
  ```ts
918
732
  async execute({ projectId }, ctx) {
@@ -926,34 +740,33 @@ async execute({ projectId }, ctx) {
926
740
  }
927
741
  ```
928
742
 
929
- After a cancel aborts the signal, the run waits up to 30 seconds for the body to finish unwinding,
930
- then ends as cancelled whether or not it did. A body parked on a hook or a `sleep` does not observe
931
- the signal; it is abandoned when the grace period ends. Steps that received the signal are how you
932
- clean up first.
743
+ After a cancel, the run waits up to 30 seconds for the body to stop, then ends as cancelled whether
744
+ or not it did. A body paused on a hook or a `sleep` doesn't see the signal. eve abandons it when
745
+ the 30 seconds end, so clean up in steps that received the signal.
933
746
 
934
- The caller waits up to 35 seconds for a cooperatively cancelled run to settle before forcing it
935
- to stop. This includes time for the run to publish its outcome after body cleanup.
747
+ The caller waits up to 35 seconds for a cancelled run to report its outcome, then forces the run to
748
+ stop.
936
749
 
937
750
  ## Stop early for a new message
938
751
 
939
- A steering message aborts the `ctx.abortSignal` of each `execute` call the turn waits on. A
940
- steering message is one sent with `turnPolicy: "steer"`, the default, that does not answer a pending
941
- question; a message that answers a question never stops a call. Steering never touches a
752
+ A steering message is one sent with `turnPolicy: "steer"` (the default) that answers no open
753
+ question. It aborts the `ctx.abortSignal` of each `execute` call the turn waits on. A message that
754
+ answers a question never stops a call, and steering never touches a
942
755
  [task](#run-calls-as-tasks-task).
943
756
 
944
- Steering does not cancel the call or end the turn. The call settles with what the body returns, and
945
- the model reads the new message after the step's workflow tool calls settle:
757
+ Steering does not cancel the call or end the turn. The call ends with what the body returns, and the
758
+ model reads the new message after the step's workflow tool calls finish:
946
759
 
947
- - **Questions:** a pending `ctx.ask` question is withdrawn and resolves as `cancelled`, unless a
760
+ - **Questions:** an open `ctx.ask` question is withdrawn and resolves as `cancelled`, unless a
948
761
  person's answer reached the session first.
949
762
  - **Rejections:** a body that rejects after the abort, such as one whose step received the signal,
950
- settles as `{ interrupted: true }` instead of failing.
951
- - **No grace period:** a body that doesn't observe the signal, such as one parked on a hook or a
952
- `sleep`, keeps the turn waiting until it finishes.
763
+ ends as `{ interrupted: true }` instead of failing.
764
+ - **Paused bodies:** a body paused on a hook or a `sleep` doesn't see the signal, and it keeps the
765
+ turn waiting until it finishes.
953
766
 
954
- The body doesn't need to tell a steering message from a cancel: in both cases, stop and return what
955
- you have. After a cancel, eve discards the result. The provided `sleep` tool races its timer
956
- against the signal:
767
+ The body doesn't need to tell a steering message from a cancel: stop and return what you have.
768
+ After a cancel, eve discards the result. The provided `sleep` tool races its timer against the
769
+ signal:
957
770
 
958
771
  ```ts
959
772
  import { sleep } from "eve/workflow";
@@ -972,6 +785,101 @@ async execute(input, ctx) {
972
785
  To keep a question or long work going while the conversation continues, define
973
786
  [`task`](#run-calls-as-tasks-task) instead of `execute`.
974
787
 
788
+ ## Authorize inside a step
789
+
790
+ Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there, with the provider
791
+ declaration and the API request inside the step. User-scoped providers resolve as the person whose
792
+ call started the workflow tool, even if another person speaks in the session while it waits:
793
+
794
+ ```ts
795
+ import { connect } from "@vercel/connect/eve";
796
+ import type { WorkflowStepToolContext } from "eve/tools";
797
+
798
+ async function readRepository(ctx: WorkflowStepToolContext, repository: string) {
799
+ "use step";
800
+ const provider = connect("github/my-agent");
801
+ const { token } = await ctx.getToken(provider);
802
+ const response = await fetch(`https://api.github.com/repos/${repository}`, {
803
+ headers: { Authorization: `Bearer ${token}` },
804
+ });
805
+ if (response.status === 401) ctx.requireAuth(provider);
806
+ if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
807
+ return response.json();
808
+ }
809
+ ```
810
+
811
+ The workflow body calls `await readRepository(ctx, repository)`.
812
+
813
+ <Callout type="warning" title="Keep tokens out of step results">
814
+ eve records step results in the workflow's history, so do not return the token from the helper.
815
+ The step input is recorded too and, after sign-in, carries the provider's callback parameters,
816
+ such as a one-time authorization code. Bearer tokens are never written.
817
+ </Callout>
818
+
819
+ When sign-in is required, the step attempt ends and the channel shows the sign-in prompt. The
820
+ workflow waits for the callback without holding compute. After the callback, eve retries **the whole
821
+ interrupted step**, resolves the token, and continues. Completed steps don't run again.
822
+
823
+ - Resolve auth before other side effects in that step, and make operations before `requireAuth`
824
+ safe to retry.
825
+ - A token rejected immediately after sign-in fails instead of prompting again.
826
+ - Provider declarations can be shared imports. Pass `ctx` directly, not nested inside another
827
+ argument or captured in a closure.
828
+ - If the step fails and retries after a successful sign-in, eve reads the token from the provider
829
+ instead of reusing the callback. The provider must therefore persist the grant or token.
830
+ - Cancelling an authorization wait withdraws its callback.
831
+
832
+ ## Use the session sandbox in a step
833
+
834
+ Pass `ctx` directly to a step helper and call `ctx.getSandbox()` there. The step opens the
835
+ [sandbox](/docs/sandbox) that the calling session's turns use. That includes a sandbox shared with
836
+ a parent session, as in a copy started by the built-in `agent` tool. The step and the session see
837
+ each other's files:
838
+
839
+ ```ts title="agent/tools/analyze.ts"
840
+ import { defineWorkflowTool, type WorkflowStepToolContext } from "eve/tools";
841
+ import { z } from "zod";
842
+
843
+ export default defineWorkflowTool({
844
+ description: "Prepare the input file for an analysis run.",
845
+ inputSchema: z.object({ value: z.string() }),
846
+ async task(input, ctx) {
847
+ "use workflow";
848
+ await prepareInput(ctx, input);
849
+ return { path: "/workspace/input.json" };
850
+ },
851
+ });
852
+
853
+ async function prepareInput(ctx: WorkflowStepToolContext, input: { value: string }) {
854
+ "use step";
855
+ const sandbox = await ctx.getSandbox();
856
+ await sandbox.writeTextFile({ path: "/workspace/input.json", content: JSON.stringify(input) });
857
+ }
858
+ ```
859
+
860
+ - The workflow body can't open the sandbox, because it replays. `ctx.getSandbox()` in the body
861
+ throws and tells you to pass `ctx` to a step helper.
862
+ - The step works with any sandbox provider. If the session recorded its sandbox before it called
863
+ the tool, the step resumes it. Otherwise, or if that sandbox is gone, the step runs your
864
+ `defineSandbox()` definition as the session's first turn would. Later turns open the same sandbox.
865
+ - Your definition can run once for each caller that opens the sandbox before the session records
866
+ it, so make its setup safe to repeat.
867
+ - The sandbox belongs to the session, not the step. When the step ends, even by throwing, the
868
+ sandbox keeps running. `sandbox.stop()` and `sandbox.delete()` in a step fail without a retry,
869
+ because the session's turns may be using the sandbox.
870
+ - The session removes the sandbox when it ends, even when only a step opened it. A step still
871
+ running at that point can open the sandbox again, and nothing removes the new one.
872
+ - When the eve server shuts down, it stops the sandboxes its sessions opened, but not one that only
873
+ a step opened. With Docker, that container keeps running until the session ends or you stop it.
874
+ - A step can use the sandbox while the session's turns use it, as subagents that share a sandbox
875
+ do. Give each one its own files to write.
876
+ - Steps run at least once and retry after a failure, so make sandbox writes safe to repeat. Write
877
+ whole files instead of appending, or check for earlier output first.
878
+ - When the session shares its parent's sandbox, the step opens it with the parent's sandbox
879
+ definition, and the parent removes it when the parent ends.
880
+ - A step runs wherever the workflow runs. A sandbox on one machine's disk, such as just-bash, is
881
+ reachable from a step only on that machine, as in local development.
882
+
975
883
  ## Workflow tool examples
976
884
 
977
885
  ### Approve with a deadline and an escalation
@@ -996,9 +904,9 @@ async task({ service }, ctx) {
996
904
  }
997
905
  ```
998
906
 
999
- One request stays on the channel the whole time. As a `task`, the call doesn't hold the
1000
- conversation, and a steering message doesn't withdraw the request. `sleep` is the deadline,
1001
- `pageOnCall` is a step, and returning withdraws the request.
907
+ One question stays on the channel the whole time. As a `task`, the call doesn't hold the
908
+ conversation, and steering doesn't withdraw the question. `pageOnCall` is a step, and returning
909
+ withdraws the question.
1002
910
 
1003
911
  ### Wait for an external system to call back
1004
912
 
@@ -1025,9 +933,9 @@ export default defineWorkflowTool({
1025
933
  ```
1026
934
 
1027
935
  `createWebhook` mints a URL under `/.well-known/workflow/v1/webhook/` that eve serves. The external
1028
- system posts to it when it is done. Nothing runs in between. Webhook tokens are generated for
1029
- you; use `createHook` with `resumeHook` if you need a deterministic token. To customize the HTTP
1030
- response, pass `respondWith: new Response(...)` to `createWebhook`.
936
+ system posts to it when it is done, and nothing runs in between. Use `createHook` with `resumeHook`
937
+ for a deterministic token. To customize the HTTP response, pass `respondWith: new Response(...)` to
938
+ `createWebhook`.
1031
939
 
1032
940
  ### Ask now, act when answered
1033
941
 
@@ -1058,29 +966,25 @@ export default defineWorkflowTool({
1058
966
  });
1059
967
  ```
1060
968
 
1061
- The turn parks while the approval card stays on the channel. When it is answered, the refund runs
969
+ The turn waits while the approval card stays on the channel. When someone answers, the refund runs
1062
970
  and the agent receives the outcome as the tool result.
1063
971
 
1064
972
  ## Semantics
1065
973
 
1066
- One call, one result. A workflow tool call resolves once, with the return value, the error, or a
1067
- cancellation.
974
+ A workflow tool call ends once, with the return value, the error, or a cancellation.
1068
975
 
1069
- While an `execute` call runs, the turn is parked. A `queue` message waits for it. A `steer` message
1070
- that answers no pending question aborts the call's `ctx.abortSignal` and reaches the model once the
1071
- call settles; it never cancels the run. Input responses never steer. A task doesn't park the
1072
- turn, and steering never touches it.
976
+ While an `execute` call runs, the turn waits, and a message sent with `turnPolicy: "queue"` waits
977
+ for it. A task doesn't hold the turn. See [Stop early for a new message](#stop-early-for-a-new-message)
978
+ for `steer` messages.
1073
979
 
1074
980
  Errors follow the SDK. A thrown error in a step retries per the step's policy; `FatalError` does
1075
- not. An error that escapes the body fails the tool invocation.
1076
-
1077
- Starting a workflow tool can also be retried. If dispatch is interrupted after starting a
1078
- run, its retry starts another run, and both may execute. The parent tracks the run returned by the
1079
- successful dispatch attempt. Use an application idempotency key for side effects that must happen
1080
- only once.
1081
-
1082
- The workflow id derives from the entry point's module path and function name. Inline entry points
1083
- use the tool module and the name `execute`, `task`, or `serve`; imported ones use their declaring module and
1084
- name.
1085
- Renaming or moving that function creates a new workflow. Runs in flight finish on the deployment that started them; a run that
1086
- resumes on a deployment without its tool fails with an error naming the missing workflow.
981
+ not. An error that escapes the body fails the tool call.
982
+
983
+ An interrupted dispatch can start a second run for the same call, and both runs may execute. Use an
984
+ application idempotency key for side effects that must happen only once.
985
+
986
+ The workflow id comes from the entry point's module path and function name. Inline entry points use
987
+ the tool module and the name `execute`, `task`, or `serve`. Imported ones use their declaring module
988
+ and name. Renaming or moving that function creates a new workflow. Runs in flight finish on the
989
+ deployment that started them. A run that resumes on a deployment without its tool fails with an
990
+ error naming the missing workflow.