eve 0.68.0 → 0.70.0

package/docs/tools/overview.mdx

@@ -60,6 +60,52 @@ The option defaults to `true` and works with `defineTool` and `defineWorkflowToo
 
 Compiled tools preserve Zod schema composition, including input and output schemas imported from helper modules. Durable replay metadata stays separate from the original schema, so adding it does not mutate shared schema objects.
 
+### End the turn after a tool call
+
+Set `endsTurn: true` when a successful call is the whole answer, such as reacting to a message. eve ends the turn after the call instead of calling the model again, so the turn completes without a final message and channels post no reply:
+
+```ts title="agent/tools/react.ts"
+export default defineTool({
+  description: "React to the current message. Use this when a reaction is the whole answer.",
+  endsTurn: true,
+  inputSchema: z.object({ emoji: z.string() }),
+  async execute({ emoji }) {
+    await addReaction(emoji);
+    return { emoji };
+  },
+});
+```
+
+With `endsTurn: true`, eve tells the model that the call ends its turn by appending this sentence, after a blank line, to the description the model sees:
+
+```text
+Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.
+```
+
+Write `description` for what the tool does and when to use it, and leave the turn-ending rule to eve. The appended sentence is not part of the tool definition, so `eve info` shows the description as you wrote it.
+
+To decide from the result instead, pass a function. eve calls it with the output of `execute` after each successful call, and the call ends the turn only when the function returns `true` or resolves to `true`. If the function throws or rejects, eve logs a warning and the turn continues as though it returned `false`:
+
+```ts title="agent/tools/react.ts"
+export default defineTool({
+  description:
+    "React to the current message. When the reaction posts, your turn ends; otherwise, reply in text.",
+  inputSchema: z.object({ emoji: z.string() }),
+  async execute({ emoji }) {
+    return { posted: await addReaction(emoji) };
+  },
+  endsTurn: (output) => output.posted,
+});
+```
+
+Declare `endsTurn` after `execute`, as above, so TypeScript infers `output` from what `execute` returns. With an `outputSchema`, `output` takes that schema's type wherever `endsTurn` appears.
+
+eve does not append the sentence for a function, because whether the call ends the turn is known only after it runs. Describe the behavior in `description` when the model needs to know it.
+
+The turn ends only when every tool call in the model's step can end the turn and succeeds, and every `endsTurn` function returns `true`. Otherwise the model receives the results and continues as usual. Text the model writes before the call is narration, so channels do not post it as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
+
+eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries accept `endsTurn: true` or `false`; eve rejects a function when the resolver returns the entry, because dynamic tool metadata is stored durably. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
+
 ### Label tool activity
 
 Use `label.start(input)` to describe a call in user-facing activity. The callback receives the validated tool input, so it can select the useful fields without exposing the full argument object:
@@ -80,13 +126,13 @@ export default defineTool({
 });
 ```
 
-The label is presentation only. It does not replace the path-derived tool name, enter model input, or change execution. eve records the bounded label on the corresponding public action event so activity renderers and other authorized stream consumers can use it without interpreting raw tool data. Built-in channel activity can show `Deploy storefront to production` instead of `deploy`; if the callback throws or returns an empty label, activity falls back to the tool name.
+The label is presentation only. It does not replace the path-derived tool name, enter model input, or change execution. eve records the bounded label on the corresponding public action event so activity renderers and other authorized stream consumers can use it without interpreting raw tool data. Built-in channel activity can show `Deploy storefront to production` instead of `Deploy`; if the callback throws or returns an empty label, activity falls back to a readable form of the tool name, such as `Sync accounts` for `sync_accounts`.
 
 Provided tools define labels for `bash`, `glob`, `grep`, `load_skill`, `read_file`, `web_fetch`, `web_search`, and `write_file`.
 
 ### Stream preliminary tool results
 
-For a `defineTool` executor with the default execution mode, an async generator streams complete
+For a `defineTool` executor, an async generator streams complete
 output snapshots before it finishes. Each `yield` replaces the previous snapshot; the final
 yield is the normal tool result the model receives:
 
@@ -112,8 +158,8 @@ snapshot is visible to channels, hooks, and clients but never enters model
 history or `toModelOutput`; only the final yield does. Treat snapshots as
 last-write-wins by tool call id, not append-only progress. The durable runtime
 can retry a step and replay overlapping snapshots. A generator `return` value is not used as
-the result in this mode; yield the final output. Workflow and background generators have
-different result rules, described under [yield and return](#yield-and-return).
+the result in this mode; yield the final output. Workflow generators have different result
+rules, described under [yield and return](#yield-and-return).
 
 Use `label.delta(input, partial)` to project preliminary snapshots into
 user-facing activity, and `label.complete(input, output)` to describe successful
@@ -128,69 +174,42 @@ label. `label.complete` does not run for failed or rejected tool calls. The
 full values remain available in `action.partial` and `action.result`; renderers
 receive only the projected text.
 
-### Background execution
-
-Background execution controls how a workflow tool delivers its result to the parent agent.
-Set `execution: "background"` on `defineWorkflowTool`; ordinary `defineTool` calls always finish
-inside the initiating step.
-
-| Definition                                       | Durable waits inside `execute`                           | Result delivered to the model                                                                          |
-| ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `defineTool`                                     | No; the executor runs inside the initiating step.        | Executor output after it finishes.                                                                     |
-| `defineWorkflowTool`                             | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes.                                                                     |
-| `defineWorkflowTool` + `execution: "background"` | Yes; the workflow body can outlive the initiating step.  | Task receipt before the body finishes; one combined report after all tasks in its cohort are terminal. |
-
-A background workflow tool's result is the receipt `{ status: "working", taskId }`; its eventual
-output belongs to the task. Use this mode when the conversation should continue while the body
-waits for a person, webhook, or timer.
-
-For background tools, `outputSchema` and `toModelOutput` describe the fixed receipt. The body's
-return value is available through the completed task's output.
-
-The `TaskExec` argument and `task.postMessage` have been removed. Return the terminal result;
-background yields are consumed without publishing progress or retaining a task-progress stream. In a workflow body, keep values needed after a wait in local variables; workflow replay
-reconstructs them across durable waits.
-Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an answer from the human.
-Background tools are a normal execution mode and need no root-agent flag. Built-in, declared local,
-and remote subagents use this task lifecycle automatically.
-
-After the initiating turn accepts background tasks, eve supplies runtime-authored state for that
-cohort and instructs the model to acknowledge that the work started without waiting for results.
-[Schedule](/docs/schedules)-initiated turns are the exception: no user prompted them, so their
-launches keep conditional delivery and send no acknowledgement.
-Channel sessions default to `taskDeliveryPolicy: "auto"`: ready results can invoke
-the parent while other tasks continue. The parent reports independently useful
-results and can stay silent until related work settles. Each reporting context
-includes the whole cohort and available outputs, including previously withheld
-results. Ready results may share a turn.
-Schedules default to `"cohort"`: terminal outcomes wait for overlapping tasks
-to settle, then arrive together. Pass `taskDeliveryPolicy` to `send(...)` to select
-or update the session policy. See
-[Background task results](/docs/channels/overview#background-task-results) and
-[Schedules](/docs/schedules#background-task-results).
-User questions, input requests, and explicit task messages do not wait for the
-cohort under either policy. Failure and cancellation update lifecycle state
-immediately; their automatic reports follow the selected policy.
-See [Completion batching](/docs/subagents#completion-batching).
+### Durable waits
+
+Every tool call finishes before its turn continues. The definition decides whether the executor
+can wait durably while the call is pending:
+
+| Definition           | Durable waits inside `execute`                           | Result delivered to the model      |
+| -------------------- | -------------------------------------------------------- | ---------------------------------- |
+| `defineTool`         | No; the executor runs inside the initiating step.        | Executor output after it finishes. |
+| `defineWorkflowTool` | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes. |
+
+A workflow tool that defines `task(input, ctx)` in place of `execute` runs each call as a
+[task](/docs/tools/workflows#run-calls-as-tasks-task):
+the call returns a receipt at once, and the workflow's output reaches the model later in a
+`task.result` message. One that defines `serve(receive, ctx)` runs a
+[resumable task](/docs/tools/workflows#resumable-tasks-serve), which the model can send more calls
+by its `taskId`.
+
+The `TaskExec` argument and `task.postMessage` have been removed. Return the result. In a workflow
+body, keep values needed after a wait in local variables; workflow replay reconstructs them across
+durable waits. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an
+answer from the human. Built-in, declared local, and remote subagent calls also block: each call
+returns the child's reply as its tool result.
 
 ### Yield and return
 
 `yield` hands a value to eve's generator consumer, which processes it and advances the generator.
 It does not by itself create a durable wait for a person, timer, or external event. The value's
-meaning depends on the tool's execution mode:
-
-| Executor                                            | Ordinary `yield value`                                                                  | Final output                                                                                                      |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `defineTool`, default execution                     | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                        |
-| `defineWorkflowTool`, default execution             | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`.       |
-| `defineWorkflowTool` with `execution: "background"` | Consumed without publishing progress or requesting a parent-agent turn.                 | Explicit return value becomes the task output; no return completes with `null`. The last yield is not a fallback. |
+meaning depends on the executor:
 
-For a background workflow tool, return completes the task and throw fails it. The automatic
-cohort report is separate from the original tool call's receipt.
+| Executor             | Ordinary `yield value`                                                                  | Final output                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `defineTool`         | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                  |
+| `defineWorkflowTool` | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`. |
 
-Progress snapshots do not enter model history as intermediate tool results. For a default
-executor, the final output selected by the rules above becomes the tool result. For a background
-executor, the terminal cohort report provides input to a later parent-agent turn.
+Progress snapshots do not enter model history as intermediate tool results. The final output
+selected by the rules above becomes the tool result.
 
 ### Workflows as tools
 
@@ -206,6 +225,7 @@ examples.
 - `ctx.session`: session metadata, turn, auth, parent lineage.
 - `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
 - `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
+- `ctx.messages`: the model input for the step that requested this call, the same messages a `step.started` [dynamic resolver](/docs/guides/dynamic-capabilities) reads.
 - `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
 - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
 

package/docs/tools/tasks-upgrade.md

@@ -0,0 +1,201 @@
+---
+title: "Upgrade to Tasks"
+description: "Move workflow tools, agent calls, clients, hooks, and evals from background tasks to tasks."
+url: /tools/tasks-upgrade
+---
+
+This release replaces background tasks with [tasks](/docs/tools/tasks). Every change below breaks
+the previous API. Work through the sections that apply to your agent. A workflow tool that uses
+none of `execution: "background"`, `dismissible`, or `ctx.agent` keeps its code: `execute(input,
+ctx)` keeps its signature, and `ctx.abortSignal` and `ctx.callId` are where they were. One behavior
+changes for every `execute` tool: a steering message now aborts its `ctx.abortSignal`. See
+[Drop `dismissible`](#drop-dismissible-a-new-message-stops-an-execute-call).
+Type-checking flags most of the code changes, such as the removed `execution` and `dismissible`
+options and the old `ctx.agent` call.
+
+## Replace `execution: "background"` with `task(input, ctx)`
+
+Rename `execute` to `task` and remove `execution`. The body doesn't change:
+
+```diff
+ export default defineWorkflowTool({
+   description: "Deploy a service.",
+   inputSchema: z.object({ service: z.string() }),
+-  execution: "background",
+-  async execute({ service }, ctx) {
++  async task({ service }, ctx) {
+     "use workflow";
+     return await deploy(service, ctx.abortSignal);
+   },
+ });
+```
+
+`defineWorkflowTool` rejects `execution` with
+`"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.` A
+`task` body gets the same `WorkflowToolContext` as an `execute` body, and steering never aborts a
+task's `abortSignal`. An `execute` tool is an ordinary tool call: the turn waits for its result. See
+[Choose how a call runs](/docs/tools/tasks#choose-how-a-call-runs).
+
+A tool that the model should be able to send more input while it works, such as a plan it revises
+on request, defines [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve) instead.
+
+## Drop `dismissible`: a new message stops an `execute` call
+
+`ctx.ask` no longer accepts `dismissible`. A steering message now aborts the `ctx.abortSignal` of
+each `execute` call the turn waits on, which withdraws every question the call asked, as
+`dismissible: true` did:
+
+```diff
+-const answer = await ctx.ask({ prompt, dismissible: true });
++const answer = await ctx.ask({ prompt });
+```
+
+To keep a question open through new messages, ask it from a
+[`task`](#replace-execution-background-with-taskinput-ctx) instead. Other work that
+receives `ctx.abortSignal`, such as a step or a `ctx.agent` send, stops too. The call settles with
+what the body returns, or with `{ interrupted: true }` if the body rejects, and the model reads the
+message next.
+
+A withdrawn question resolves as `{ status: "cancelled" }` instead of `dismissed`, and the
+`input.resolved` outcome `"dismissed"` is now `"cancelled"`. Update clients and channels that
+match on the old value. See [Pass signals to the work](/docs/tools/tasks#pass-signals-to-the-work).
+
+## Open agent sessions with `ctx.agent(name)`
+
+`ctx.agent(name, { message, agentId })`, which returned the agent's output, is now
+`ctx.agent(name)`, which returns a session. Send a message and read the turn's result:
+
+```diff
+-const review = await ctx.agent("reviewer", { message: plan });
++const response = await ctx.agent("reviewer").send(plan, { signal: ctx.abortSignal });
++const { message: review, status } = await response.result();
++if (status === "failed") throw new Error("The review failed.");
+```
+
+`agentId` is removed. Each `ctx.agent(name)` call returns a new session, and later `send` calls on
+the same handle continue its conversation until the workflow run finishes. See
+[Delegate work](/docs/tools/workflows#delegate-work-ctxagent). The `workflow` tool's generated
+programs keep their `ctx.agent(name, { message, outputSchema? })` capability.
+
+## Continue agents by `taskId`
+
+Every agent tool is now a `serve` tool, so every agent call is a resumable task. The model's agent
+tools take `taskId` instead of `agentId`:
+
+```diff
+-{ "message": "Check the Q2 numbers too.", "agentId": "…" }
++{ "message": "Check the Q2 numbers too.", "taskId": "researcher-7k2m9q" }
+```
+
+An agent call returns a receipt at once, and the agent's reply arrives later in a `task.result`
+message. Update instructions, prompts, and evals that mention `agentId` or expect the reply as
+the tool result. `agentRouter()` and the `workflow` tool now run each call as a task too.
+
+The removed codes `AGENT_BUSY`, `AGENT_MISMATCH`, `AGENT_UNREACHABLE`, and
+`AGENT_INVOCATION_NOT_ADMITTED` have no replacement. A `taskId` that names no unfinished task of
+that tool fails with `UNKNOWN_TASK`, and a call past the limit of 32 working tasks fails with
+`TOO_MANY_TASKS`.
+
+## Remove background delivery options
+
+Results reach the model one way: a `task.result` message at a step boundary. Remove these:
+
+- `taskDeliveryPolicy` and delivery cohorts.
+- The `tasks` option of `session.cancel()`. `session.cancel()` now cancels the turn, the `execute`
+  calls it waits on, and every working task; it still accepts `turnId` and `signal`.
+
+The model no longer sees `[Task state]` or `[Agents]` notes, prose task notifications,
+`<eve-empty-delivery/>`, or result turns. A `[Tasks]` note lists its working and idle tasks
+instead. The `BACKGROUND_TASK_FAILED` and `BACKGROUND_TASK_CANCELLED` codes are removed; a
+failed task reports its error in `task.settled` and in its `task.result` block.
+
+## Read task events instead of `subagent.*` events
+
+The `subagent.called`, `subagent.started`, `subagent.completed`, and `subagent.event` events are
+removed. Use these instead:
+
+| Event           | Replaces             | Data                                                                                             |
+| --------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
+| `task.started`  | `subagent.called`    | `taskId`, `callId`, `turnId`, `name`, `kind`                                                     |
+| `task.settled`  | `subagent.completed` | `taskId`, `callId`, `turnId`, `name`, `kind`, `status`, and `output` or `error` unless cancelled |
+| `agent.started` | `subagent.started`   | `callId`, `turnId`, `taskId`, `name`, `sessionId`, `streamPath`                                  |
+
+Follow a child's own events, which `subagent.event` used to relay, on its stream:
+`session.streamSubagent()` is now `session.agent(started).stream()`, and it takes the `agent.started` event.
+
+```diff
+ for await (const event of session.stream()) {
+-  if (event.type !== "subagent.called") continue;
++  if (event.type !== "agent.started") continue;
+-  for await (const childEvent of session.streamSubagent(event)) {
++  for await (const childEvent of session.agent(event).stream()) {
+```
+
+Hooks subscribe the same way:
+
+```diff
+ export default defineHook({
+   events: {
+-    async "subagent.completed"(event, ctx) {
++    async "task.settled"(event, ctx) {
++      if (event.data.status !== "completed") return;
+```
+
+The eval assertion `t.calledSubagent(name, { status })` keeps its API and reads task events.
+
+## Handle open turns in clients
+
+A turn doesn't end while tasks are working, so one turn can span a wait. The stream
+reports each wait with the new `turn.waiting` event, which carries the open turn's `turnId`:
+
+- **Held turns.** When the model ends its text while its tasks work, and when `task_wait` has no
+  result yet, the stream emits `turn.waiting`. The next `step.started` for the same `turnId` means
+  the turn resumed. In a root session, the text before the wait completes as a normal
+  `message.completed`; in child sessions and a schedule's sessions, that step reports
+  `finishReason: "tool-calls"`.
+- **Questions and sign-ins inside a call no longer end the turn.** Previously, a question or
+  sign-in from inside a running call, such as a workflow tool's `ctx.ask()`, `ask_question`, or a
+  subagent's question, emitted `turn.completed` and `session.waiting` in the middle of the turn.
+  It now emits `input.requested` or `authorization.required`, then `turn.waiting`, and the turn
+  resumes under the same `turnId` after the answer. The session you answer on emits
+  `input.resolved` for every question it routes an answer to. A tool approval the turn itself
+  requests still ends the turn with `turn.completed` and `session.waiting`.
+- **`turn.completed` comes only when the turn really ends,** and `session.waiting` always means
+  the turn has ended.
+
+The TypeScript client's `send(...).result()` reads past `turn.waiting` and returns the final reply
+of a held turn, not the text written before the wait. It stops at `turn.waiting` only while a
+question is pending, and returns `status: "waiting"` with that question; `respond()` then reads the
+same turn to its end. A custom client that ends a response at `turn.completed` or
+`session.waiting` mid-turn, or that shows the first completed message as the reply, should follow
+the same rule. See [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn).
+
+Task results aren't stream events. Background task results used to appear as `message.received`
+with `data.kind: "execution.background_task"`; `message.received` no longer has `kind`, and a task
+result reaches only the model. Read each call's outcome from `task.settled` instead.
+
+The message stream version is now 26. The TypeScript client accepts versions 21 through 26. A
+client that accepts only versions up to 25 fails the stream with an unsupported-version error. See
+[Turns wait for their tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
+
+## Upgrade remote agents before their callers
+
+The remote agent protocol is now version 2. Deploy each [remote agent](/docs/guides/remote-agents)
+before the deployments that call it. A remote agent on this release still serves callers on eve 0.66
+through 0.68, which speak protocol 1. It runs their turns, sends each result to their callback, and
+accepts their follow-up and reset requests. It also sends the remote agent's tool approvals and
+sign-in requests to the caller, and accepts the caller's answers, the same way a 0.66–0.68 remote
+agent does. As in 0.66–0.68, this covers agents the caller's model calls, which run as background
+tasks. When the caller's own workflow tool code calls an agent, its approvals and sign-in requests
+stay on the remote agent's channel.
+
+Two things differ from a remote agent on the caller's own release:
+
+- The caller's channel doesn't show the remote agent's live tool activity nested under the call.
+- `ctx.ask()` in the remote agent returns `unavailable`, because protocol-1 callers don't grant the
+  remote agent input. That's unchanged from 0.66–0.68.
+
+Each protocol-1 create logs `serving a remote agent protocol 1 caller` with the caller's origin.
+
+Upgrade a caller after every remote agent it calls. A caller on this release fails a call at start,
+with an error that names both versions, when the remote agent's deployment speaks protocol 1.