eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -7,19 +7,16 @@ url: /tools/tasks
7
7
  A task is a tool call that returns a receipt right away and keeps working while the conversation
8
8
  continues. Every call to an agent is a task, and so is every call to a
9
9
  [workflow tool](/docs/tools/workflows) that defines `task(input, ctx)` or `serve(receive, ctx)`.
10
- A task's result reaches the model later, in a `task.result` message, and a turn can't end while
11
- tasks are still working.
12
-
13
- This page covers when to use a task, how to order work that depends on a result, the signals a
14
- workflow tool body receives, and what the model and the stream see.
10
+ The result reaches the model later, in a `task.result` message. A turn can't end while tasks are
11
+ still working.
15
12
 
16
13
  ## Choose how a call runs
17
14
 
18
- A workflow tool defines exactly one entry point, and the entry point answers one question: should
19
- the conversation continue while the call works?
15
+ A workflow tool defines exactly one entry point, which decides whether the conversation continues
16
+ while the call works:
20
17
 
21
18
  ```ts
22
- defineWorkflowTool({ /* … */ async execute(input, ctx) {} }); // the turn waits until the call settles
19
+ defineWorkflowTool({ /* … */ async execute(input, ctx) {} }); // the turn waits until the call finishes
23
20
  defineWorkflowTool({ /* … */ async task(input, ctx) {} }); // a task: a receipt now, the result later
24
21
  defineWorkflowTool({ /* … */ async serve(receive, ctx) {} }); // a task that accepts more calls
25
22
  ```
@@ -31,19 +28,19 @@ Defining none of the three, or more than one, throws when the tool is defined.
31
28
  | `execute` workflow tool, including `sleep` and `ask_question` | Tool call; the turn waits | The tool result | Aborts the call's `abortSignal` |
32
29
  | `task` workflow tool, including `agentRouter()` and the `workflow` tool | Task | A receipt, then a `task.result` message | Nothing |
33
30
  | `serve` workflow tool, including every agent tool | Resumable task | A receipt, then a `task.result` message per reply | Nothing |
34
- | `eve__task_wait` | Wait inside the turn | Which tasks settled | Ends the wait |
31
+ | `eve__task_wait` | Wait inside the turn | Which tasks finished | Ends the wait |
35
32
  | Plain and MCP tools | Inside the model step | The tool result | Applied at the next step boundary |
36
33
 
37
34
  Waiting alone doesn't need a task. A question, a `sleep`, or an approval inside an `execute` call
38
- parks the turn durably and holds no compute, and a new message stops the wait. Use a task when the
39
- model should keep talking while the work runs, such as a twenty-minute deploy or research the model
40
- may not need right away, or when a question should stay open through new messages. A long
41
- `execute` tool holds the conversation until it settles or a new message stops it.
35
+ pauses the turn without holding compute, even across restarts. A new message stops the wait.
36
+ Use a task when the model should keep talking while the work runs, such as during a twenty-minute
37
+ deploy. A task also suits research the model may not need right away, or a question that should
38
+ stay open through new messages.
42
39
 
43
- Agents have no choice to make: every agent tool is a `serve` tool, so every agent call is a
44
- resumable task, because only the model can tell from the conversation whether it needs an agent's
45
- answer now. The [turn rule](#turns-wait-for-their-tasks) guarantees the answer reaches the model
46
- before the turn ends.
40
+ Every agent tool is a `serve` tool, so every agent call is a resumable task. The model decides from
41
+ the conversation whether it needs an agent's answer now. The
42
+ [turn rule](#turns-wait-for-their-tasks) guarantees the answer reaches the model before the turn
43
+ ends.
47
44
 
48
45
  See [Run calls as tasks](/docs/tools/workflows#run-calls-as-tasks-task) for writing a `task` body
49
46
  and [Resumable tasks](/docs/tools/workflows#resumable-tasks-serve) for `serve` bodies,
@@ -54,8 +51,8 @@ and [Resumable tasks](/docs/tools/workflows#resumable-tasks-serve) for `serve` b
54
51
  Because agent calls are tasks, the model decides when to wait for them. An instruction such as
55
52
  "publish only after the review approves" holds only as long as the model follows it. When an order
56
53
  must always hold, write a workflow tool that runs the first step through
57
- [`ctx.agent`](/docs/tools/workflows#delegate-work-ctxagent) and then acts, and don't expose the
58
- side effect as a separate tool:
54
+ [`ctx.agent`](/docs/tools/workflows#delegate-work-ctxagent) and then acts. Don't expose the side
55
+ effect as a separate tool:
59
56
 
60
57
  ```ts title="agent/tools/publish_reviewed_notes.ts"
61
58
  import { defineWorkflowTool } from "eve/tools";
@@ -89,7 +86,7 @@ async function publish(notes: string) {
89
86
  ```
90
87
 
91
88
  The publish step can only run after the review returns. Set `tool: false` on the `reviewer`
92
- subagent if the model shouldn't call it directly, and define `task` in place of `execute` if the
89
+ subagent if the model shouldn't call it directly. Define `task` in place of `execute` if the
93
90
  conversation should continue while the review runs.
94
91
 
95
92
  ## Pass signals to the work
@@ -97,24 +94,23 @@ conversation should continue while the review runs.
97
94
  A workflow tool body receives its signals from its context or, in a `serve` body, from each call
98
95
  `receive()` resolves:
99
96
 
100
- - **`abortSignal`** aborts when the call's work should stop: by `eve__task_cancel`, `session.cancel()`,
101
- a cancelled or failed turn, or the end of the session, and, for an `execute` call, by a steering
102
- message that arrives while the turn waits on it. `execute` and `task` bodies read it as
103
- `ctx.abortSignal`. In a `serve` body, each call from `receive()` carries its own `abortSignal`;
104
- every call in one stretch of work shares one signal, and the next stretch gets a new one. Pass it
105
- to the steps and `ctx.agent` sends that should stop.
106
- - **`ctx.ask(request)`** withdraws the question when the call's `abortSignal` aborts, and
107
- `ctx.ask(request, { signal })` also when `signal` does. In a `serve` body, `ctx.reply()` also
108
- withdraws the questions still pending for the calls it settles. The answer resolves as
109
- `{ status: "cancelled" }`, and the stream reports `interaction.settled` with `outcome: "withdrawn"` so
110
- channels stop offering the question. A person's answer that reached the session first still wins:
111
- the ask resolves as `answered`, so branch on `status`, not on the signal.
112
-
113
- A body doesn't need to tell a steering message from a cancel: in both cases, stop and return what
114
- you have. After a steering message the call settles with what the body returns, or with
115
- `{ interrupted: true }` if the body rejects, and the model reads the message next. After a cancel,
116
- eve discards the result. So a question in an `execute` call lapses once the conversation moves on,
117
- as the provided `ask_question` tool's does, while a question in a task stays open:
97
+ - **`abortSignal`** aborts when the call's work should stop. `eve__task_cancel`, `session.cancel()`,
98
+ `session.clear()`, a cancelled or failed turn, and the end of the session abort it. For an `execute` call, so does a
99
+ steering message that arrives while the turn waits on it. `execute` and `task` bodies read it as
100
+ `ctx.abortSignal`. In a `serve` body, each call from `receive()` carries its own `abortSignal`.
101
+ Calls in one stretch of work share one signal, and the next stretch gets a new one. Pass the
102
+ signal to the steps and `ctx.agent` sends that should stop.
103
+ - **`ctx.ask(request)`** withdraws the question when the call's `abortSignal` aborts.
104
+ `ctx.ask(request, { signal })` also withdraws it when `signal` aborts. In a `serve` body,
105
+ `ctx.reply()` withdraws the open questions of the calls it answers. A withdrawn question resolves
106
+ as `{ status: "cancelled" }`, and the stream reports `interaction.settled` with
107
+ `outcome: "withdrawn"` so channels stop offering it. A person's answer that reached the session
108
+ first still wins, so branch on `status`, not on the signal.
109
+
110
+ After a steering message, the call ends with what the body returns. See
111
+ [Stop early for a new message](/docs/tools/workflows#stop-early-for-a-new-message). A
112
+ question in an `execute` call lapses once the conversation moves on, as `ask_question`'s does. A
113
+ question in a task stays open:
118
114
 
119
115
  ```ts
120
116
  async execute({ service }, ctx) {
@@ -129,53 +125,51 @@ async execute({ service }, ctx) {
129
125
  }
130
126
  ```
131
127
 
132
- See [Stop early for a new message](/docs/tools/workflows#stop-early-for-a-new-message) for how the
133
- provided `sleep` tool races its timer against the signal.
128
+ The provided `sleep` tool races its timer against the signal; see the example in
129
+ [Stop early for a new message](/docs/tools/workflows#stop-early-for-a-new-message).
134
130
 
135
131
  ## What the model sees
136
132
 
137
- eve adds `eve__task_wait`, `eve__task_cancel`, and a short system prompt block that explains tasks whenever
138
- the agent has an agent tool or a `task` or `serve` workflow tool. The block depends on who reads the
139
- session:
133
+ When the agent has an agent tool or a `task` or `serve` workflow tool, eve adds `eve__task_wait`
134
+ and `eve__task_cancel`. It also adds a short system prompt block about tasks, which depends on who
135
+ reads the session:
140
136
 
141
- - **Root sessions:** a person reads each reply, so the block tells the model to call
142
- `eve__task_wait` when it has nothing to say until a result arrives, and to reply now when the
143
- person should hear from it, such as to confirm that work is underway.
144
- - **Child sessions and a schedule's sessions:** only the turn's final reply reaches the caller, so
145
- the block tells the model to call `eve__task_wait` instead of replying while tasks work. Text the
137
+ - **Root sessions:** a person reads each reply. The block tells the model to call `eve__task_wait`
138
+ when it has nothing to say until a result arrives. It tells the model to reply now when the person
139
+ should hear from it, such as to confirm that work is underway.
140
+ - **Child sessions and a schedule's sessions:** only the turn's final reply reaches the caller. The
141
+ block tells the model to call `eve__task_wait` instead of replying while tasks work. Text the
146
142
  model writes while its turn holds for tasks is narration (`content.completed` with
147
- `phase: "narration"`): clients that render the stream show it, and channels don't post it.
143
+ `phase: "narration"`). Clients that render the stream show it, and channels don't post it.
148
144
 
149
- **Receipts.** A task call returns a receipt with a `taskId`; a resumable task can be called again using that ID.
145
+ **Receipts.** A task call returns a receipt with a `taskId`; call a resumable task again with that ID.
150
146
 
151
- **Results.** Each result arrives once, as a `<task_result>` block in a `task.result` message that
152
- eve appends at the next step boundary, right after `eve__task_wait` returns, or when a held turn
153
- resumes. The body is the tool's `toModelOutput` projection of the output, or the error message for
154
- a failed call. All results in one message share a budget of 50 KB and 2,000 lines, after which the
155
- text is cut and marked `[truncated]`.
147
+ **Results.** Each result arrives once, as a `<task_result>` block in a `task.result` message. eve
148
+ adds the message before the model's next step, right after `eve__task_wait` returns, or when a held
149
+ turn resumes. The body is the output as shaped by the tool's `toModelOutput`, or the error message
150
+ for a failed call. All results in one message share a budget of 50 KB and 2,000 lines. Text past
151
+ the budget is cut and marked `[truncated]`.
156
152
 
157
153
  ```text
158
154
  <task_result id="deploy-4hd8sa" tool="deploy" status="completed">{"url":"https://…"}</task_result>
159
155
  ```
160
156
 
161
- **`eve__task_wait({ timeoutSeconds? })`** controls when the model replies. The model should call it
162
- sparingly, only when it deliberately wants to withhold a message from the user while waiting for
163
- a task result. Tasks keep running and their results reach the model without this call; the model
164
- can reply now if the user should hear from it.
157
+ **`eve__task_wait({ timeoutSeconds? })`** controls when the model replies. The model calls it only
158
+ to withhold a message from the user while waiting for a result. Tasks keep running, and their
159
+ results reach the model without it.
165
160
 
166
- The call parks the turn until any task has a result, a new message arrives, or `timeoutSeconds`
167
- pass. `timeoutSeconds` is a whole number of at least 1, in seconds like `sleep`. It returns at once
168
- when a result is already waiting. Waiting never stops a task. The
169
- model reads which tasks settled and which are still working, for example:
161
+ The call pauses the turn until any task has a result, a new message arrives, or `timeoutSeconds`
162
+ (a whole number of at least 1) pass. It returns at once when a result is already waiting, and it
163
+ never stops a task. The model reads which tasks finished and which are still working:
170
164
 
171
165
  ```text
172
166
  deploy-4hd8sa completed; its result follows. 1 task is still working: researcher-7k2m9q.
173
167
  ```
174
168
 
175
- **`eve__task_cancel({ taskId })`** stops a task's current work and says so. A cancelled agent task
176
- ends; to delegate again, start a new agent task. The task stops reporting immediately. If a local child's opening request completes after cancellation, eve asks it to end without holding the next parent turn. Cleanup is best effort: failures are logged, and a child whose inbox is unavailable may remain running. Other resumable tasks stay available, and their
177
- answer tells the model how to give them new work. When the task has no work to stop, because it
178
- already finished or is an idle resumable task, `eve__task_cancel` says that instead:
169
+ **`eve__task_cancel({ taskId })`** stops a task's current work and says so. The task stops
170
+ reporting immediately. A cancelled agent task ends, so start a new one to delegate again. Ending a
171
+ local child is best effort: a failure is logged, and the child may keep running. Other resumable
172
+ tasks stay available, and the answer tells the model how to give them new work. When a task already finished or is idle, `eve__task_cancel` says it had no work to stop:
179
173
 
180
174
  ```text
181
175
  Stopped deploy-4hd8sa; it won't report back.
@@ -183,7 +177,9 @@ Stopped researcher-7k2m9q; it won't report back.
183
177
  researcher-7k2m9q had no work to stop.
184
178
  ```
185
179
 
186
- **`[Tasks]` note.** At the next step boundary, eve tells the model which tasks are working and lists recent idle resumable tasks. The note returns after [compaction](/docs/concepts/default-harness#compaction).
180
+ **`[Tasks]` note.** Before the model's next step, eve tells the model which tasks are working. The
181
+ note then lists the 10 most recently used idle resumable tasks, so the model can find them again.
182
+ The note returns after [compaction](/docs/concepts/default-harness#compaction).
187
183
 
188
184
  **Errors.** Two error codes are specific to tasks:
189
185
 
@@ -198,14 +194,13 @@ An `eve__reply` call made while tasks are working returns an error that names th
198
194
  ## Turns wait for their tasks
199
195
 
200
196
  No turn ends while any task is working. When the model ends a turn early, eve waits as
201
- `eve__task_wait` does: it parks until one of the tasks settles or the turn's own caller steers it,
202
- appends the results, and calls the model again in the same turn. No result ever starts a turn on
203
- its own. An idle resumable task isn't working, so it doesn't hold the turn.
197
+ `eve__task_wait` does. The turn waits until a task finishes or the turn's own caller steers it. eve
198
+ then adds the results and calls the model again in the same turn. No result ever starts a turn on
199
+ its own. An idle resumable task doesn't hold the turn.
204
200
 
205
- A held turn stays open. While it waits on its tasks, when eve holds it or when `eve__task_wait` has no
206
- result yet, the turn keeps running: it pauses only for interactions. The next `model.requested` for the
207
- same `turnId` means the turn took its results, and `turn.settled` comes only when the turn really
208
- ends. The model's text before the wait depends on the session:
201
+ A held turn keeps running while it waits on its tasks, and pauses only for questions and sign-ins. The next
202
+ `model.requested` for the same `turnId` means the turn took its results, and `turn.settled` comes
203
+ only when the turn ends. The model's text before the wait depends on the session:
209
204
 
210
205
  - **Root sessions:** the text completes as an ordinary reply part (`phase: "reply"`), including text
211
206
  written before `eve__task_wait` in the same step. The person can keep writing, and the turn resumes
@@ -213,76 +208,82 @@ ends. The model's text before the wait depends on the session:
213
208
  - **Child sessions and a schedule's sessions:** the held text completes as `phase: "narration"`, so
214
209
  channels post only the final reply.
215
210
 
216
- A question or sign-in from a task, such as an agent's question, pauses the turn on that interaction:
217
- the stream emits `interaction.opened`, then `turn.paused` awaiting it, and the turn continues once
218
- the question is answered or sign-in completes.
211
+ A question or sign-in from a task, such as an agent's question, pauses the turn on that request.
212
+ The stream emits `interaction.opened`, then `turn.paused` awaiting it. The turn continues once the
213
+ question is answered or sign-in completes.
219
214
 
220
- `send(...).result()` waits through task work for the final reply, but stops at an interaction with `status: "awaiting-input"`. Answer through `respond()`; see [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn). [Slack](/docs/channels/slack#task-card) also displays task activity.
215
+ `send(...).result()` waits through task work for the final reply, but stops at a question or sign-in
216
+ with `status: "awaiting-input"`. Answer through `respond()`; see
217
+ [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn).
218
+ [Slack](/docs/channels/slack#task-card) also shows task activity.
221
219
 
222
- A steering message from the turn's own caller, one sent with `turnPolicy: "steer"`, the default,
223
- ends an `eve__task_wait` and aborts the `abortSignal` of any `execute` call the turn waits on, but it
224
- never interrupts a task. The model reads the message and decides whether to keep each task,
225
- correct an agent by calling it again with its `taskId`, or stop a task with `eve__task_cancel`. A
226
- `"queue"` message, or a message from another caller, waits for the turn to end.
220
+ A steering message from the turn's own caller, sent with `turnPolicy: "steer"` (the default),
221
+ ends an `eve__task_wait`. It also aborts the `abortSignal` of any `execute` call the turn waits on,
222
+ but it never interrupts a task. The model reads the message and decides what to do with each task.
223
+ It can keep the task, correct an agent by calling it again with its `taskId`, or stop the task with
224
+ `eve__task_cancel`. A `"queue"` message, or a message from another caller, waits for the turn to
225
+ end.
227
226
 
228
227
  ## Cancel a task
229
228
 
230
229
  - **`eve__task_cancel`** stops one task's current work.
231
230
  - **`session.cancel()`** cancels the turn, the `execute` calls it waits on, and every working task
232
231
  in the session.
232
+ - **`session.clear()`** cancels the running turn and every working task in the session, then clears
233
+ history.
233
234
  - **A failed turn** cancels every working task.
234
235
  - **The end of the session** ends every task.
235
236
 
236
- Cancelled agent and one-shot tasks end immediately. Cancelled work's usage still counts toward session limits. A `serve` task stays available if its body catches the abort and returns to `receive()` within 30 seconds; otherwise it ends.
237
+ Cancelled agent and one-shot tasks end immediately. A `serve` task stays available if its body
238
+ catches the abort and returns to `receive()` within 30 seconds; otherwise it ends. Usage from
239
+ cancelled work still counts toward session limits.
237
240
 
238
241
  ## Stream events
239
242
 
240
- | Fact | When | Data |
243
+ | Event | When | Data |
241
244
  | -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
242
245
  | `task.started` | A call starts a task | `taskId`, `name`, `kind`, and `startedBy: { callId }` |
243
246
  | `call.started` | A call reaches its task, including a later call to a resumable task | `callId` and `taskId` |
244
- | `call.settled` | A reply, return, failure, or cancel settles one call | `callId`, `outcome`, and `output`, `outputOf`, or `error` |
247
+ | `call.settled` | A reply, return, failure, or cancel ends one call | `callId`, `outcome`, and `output`, `outputOf`, or `error` |
245
248
  | `task.ended` | The task ends; agent and one-shot tasks end immediately on cancellation | `taskId`, `outcome`, and `reason` or `error` |
246
249
  | `child.opened` | A workflow run, including an agent tool's, opens a session with an agent | `sessionId`, `name`, `stream`, and `owner` |
247
250
 
248
- `task.started` comes once per task, and `task.ended` once when it ends. Each call the task
249
- serves has its own `call.started` with the `taskId` and its own `call.settled`, whose scope names
250
- that call's turn, which for a resumable task's later call can be a later turn than the one that
251
- started the task. `kind` is `"agent"` for an agent tool's task and `"tool"` otherwise. A call's
252
- `outcome` is `"completed"`, `"failed"`, or `"interrupted"` when the call was cancelled. A completed
253
- call carries `output`, or `outputOf` naming the earlier call whose output it shares; a failed call
254
- carries `error`. A task ends `"cancelled"` with a `reason` when it was cancelled, and `"failed"` with
255
- an `error` when its run failed.
256
- `child.opened` is owned by the call when an agent tool's call opened the session, and by the task
257
- when a task's run opened it with `ctx.agent`. Results reach the model as a message in its history,
258
- not as a stream event, so read outcomes from `call.settled`. An `interaction.opened` from a task's
259
- run carries the task in its `scope`. Hooks subscribe to the same facts. The stream also carries the
260
- model's `eve__task_wait` and `eve__task_cancel` calls as ordinary `call.requested` tool calls, so
261
- evals can assert on them. The `eve dev` terminal UI, channel activity such as Slack's status line,
262
- and ACP clients leave those calls out; the terminal UI shows each task's start and end instead. See
251
+ `task.started` and `task.ended` come once per task. Each call the task serves has its own
252
+ `call.started` and `call.settled`. Both belong to that call's turn, which can be a later turn for a
253
+ resumable task's later call. `kind` is `"agent"` for an agent tool's task and `"tool"`
254
+ otherwise.
255
+
256
+ A call's `outcome` is `"completed"`, `"failed"`, or `"interrupted"` when the call was cancelled. A
257
+ completed call carries `output`, or `outputOf` naming the earlier call whose output it shares; a
258
+ failed call carries `error`. A task ends `"cancelled"` with a `reason`, or `"failed"` with an
259
+ `error` when its run failed.
260
+
261
+ A `child.opened` event's `owner` is the call when an agent tool's call opened the session. It is the
262
+ task when a task's run opened the session with `ctx.agent`. An `interaction.opened` from a task's
263
+ run names the task in its `scope`. Results reach the model as a message in its history, not as a
264
+ stream event, so read outcomes from `call.settled`. Hooks subscribe to the same events.
265
+
266
+ The stream carries the model's `eve__task_wait` and `eve__task_cancel` calls as ordinary
267
+ `call.requested` tool calls, so evals can assert on them. The `eve dev` terminal UI, channel
268
+ activity such as Slack's status line, and ACP clients leave those calls out. The terminal UI shows
269
+ each task's start and end instead. See
263
270
  [Sessions, runs, and streaming](/docs/concepts/sessions-runs-and-streaming#task-facts) and
264
271
  [Follow a subagent](/docs/guides/client/streaming#follow-a-subagent).
265
272
 
266
273
  ## Ownership and limits
267
274
 
268
275
  - **Ownership.** Tasks belong to the session's open turn, not to the caller that started them. A
269
- session has at most one open turn, so `eve__task_wait`, `eve__task_cancel`, task results, and the `[Tasks]`
270
- note cover every task in the session. Any later turn can continue an idle resumable task by its
271
- `taskId`, and that call runs with its own caller's auth. Only the turn's own caller steers it;
272
- anonymous callers share one identity.
273
- eve doesn't check which caller started a task: in a session with several people, such as a
274
- shared Slack thread, the model working for one person can continue or `eve__task_cancel` a task
275
- another person started. A continued `serve` task keeps the state its body built for earlier
276
- calls, so [key per-caller data on the principal](/docs/tools/workflows#resumable-tasks-serve)
277
- and enforce per-person access inside the tool.
276
+ session has at most one open turn, so `eve__task_wait`, `eve__task_cancel`, task results, and the
277
+ `[Tasks]` note cover every task in the session. Any later turn can continue an idle resumable task
278
+ by its `taskId`, and that call runs with its own caller's auth. Only the turn's own caller steers
279
+ it; anonymous callers share one identity. eve doesn't check which caller started a task. In a session with several people, such as a
280
+ shared Slack thread, the model working for one person can continue or `eve__task_cancel` another
281
+ person's task. A continued `serve` task keeps the state its body built for earlier calls.
282
+ [Key per-caller data on the caller's identity](/docs/tools/workflows#resumable-tasks-serve) and enforce
283
+ per-person access inside the tool.
278
284
  - **Working tasks.** A session runs at most 32 working tasks at once. An idle resumable task doesn't
279
285
  count, and a call that makes it work again does.
280
286
  - **No time limits.** Tasks have no timeout of their own, and the session timeout does not bound
281
287
  them. A turn held open while its tasks work keeps the session open, and
282
- `limits.sessionTimeoutMs` (30 idle days by default) counts from when that turn settles. A body
288
+ `limits.sessionTimeoutMs` (30 idle days by default) counts from when that turn ends. A body
283
289
  that needs a deadline races `sleep` against its work.
284
-
285
- ## Upgrade from background tasks
286
-
287
- Tasks replace background tasks, `execution: "background"`, and `agentId` continuation. See
288
- [Upgrade to Tasks](/docs/tools/tasks-upgrade) for every breaking change.