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.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/tools/tasks.md
CHANGED
|
@@ -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
|
-
|
|
11
|
-
|
|
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,
|
|
19
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
39
|
-
model should keep talking while the work runs, such as a twenty-minute
|
|
40
|
-
may not need right away, or
|
|
41
|
-
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
|
58
|
-
|
|
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
|
|
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
|
|
101
|
-
a cancelled or failed turn,
|
|
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
|
-
|
|
105
|
-
to the steps and `ctx.agent` sends that should stop.
|
|
106
|
-
- **`ctx.ask(request)`** withdraws the question when the call's `abortSignal` aborts
|
|
107
|
-
`ctx.ask(request, { signal })` also when `signal`
|
|
108
|
-
withdraws the questions
|
|
109
|
-
`{ status: "cancelled" }`, and the stream reports `interaction.settled` with
|
|
110
|
-
channels stop offering
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
-
|
|
133
|
-
|
|
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
|
-
|
|
138
|
-
|
|
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
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
- **Child sessions and a schedule's sessions:** only the turn's final reply reaches the caller
|
|
145
|
-
|
|
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"`)
|
|
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
|
|
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
|
|
152
|
-
|
|
153
|
-
resumes. The body is the tool's `toModelOutput
|
|
154
|
-
a failed call. All results in one message share a budget of 50 KB and 2,000 lines
|
|
155
|
-
|
|
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
|
|
162
|
-
|
|
163
|
-
|
|
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
|
|
167
|
-
|
|
168
|
-
|
|
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.
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
already finished or is
|
|
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.**
|
|
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
|
|
202
|
-
|
|
203
|
-
its own. An idle resumable task
|
|
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
|
|
206
|
-
|
|
207
|
-
|
|
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
|
|
217
|
-
|
|
218
|
-
|
|
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
|
|
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,
|
|
223
|
-
ends an `eve__task_wait
|
|
224
|
-
never interrupts a task. The model reads the message and decides
|
|
225
|
-
correct an agent by calling it again with its `taskId`, or stop
|
|
226
|
-
`"queue"` message, or a message from another caller, waits for the turn to
|
|
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.
|
|
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
|
-
|
|
|
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
|
|
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`
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
call
|
|
254
|
-
carries `
|
|
255
|
-
|
|
256
|
-
`
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
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
|
|
270
|
-
note cover every task in the session. Any later turn can continue an idle resumable task
|
|
271
|
-
`taskId`, and that call runs with its own caller's auth. Only the turn's own caller steers
|
|
272
|
-
anonymous callers share one identity.
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
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
|
|
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.
|