eve 0.83.3 → 0.84.0

package/docs/tools/tasks.md

@@ -106,7 +106,7 @@ A workflow tool body receives its signals from its context or, in a `serve` body
 - **`ctx.ask(request)`** withdraws the question when the call's `abortSignal` aborts, and
   `ctx.ask(request, { signal })` also when `signal` does. In a `serve` body, `ctx.reply()` also
   withdraws the questions still pending for the calls it settles. The answer resolves as
-  `{ status: "cancelled" }`, and the stream reports `input.resolved` with `outcome: "cancelled"` so
+  `{ status: "cancelled" }`, and the stream reports `interaction.settled` with `outcome: "withdrawn"` so
   channels stop offering the question. A person's answer that reached the session first still wins:
   the ask resolves as `answered`, so branch on `status`, not on the signal.
 
@@ -135,21 +135,18 @@ provided `sleep` tool races its timer against the signal.
 ## What the model sees
 
 eve adds `eve__task_wait`, `eve__task_cancel`, and a short system prompt block that explains tasks whenever
-the agent has an agent tool or a `task` or `serve` workflow tool. The block tells the model to call
-`eve__task_wait` when it has nothing to say until a result arrives, and to reply when the person should
-hear from it first, such as a confirmation that work is underway. In a child session or a
-schedule's session, where only the final reply reaches the caller, it tells the model to call
-`eve__task_wait` instead of replying while tasks work.
+the agent has an agent tool or a `task` or `serve` workflow tool. The block depends on who reads the
+session:
 
-**Receipts.** A call that starts a task returns a receipt as its tool result. Task ids are the tool
-name and six characters. A resumable task's receipt tells the model how to reach it again, and a
-call that reaches it by `taskId` returns a short receipt of its own:
+- **Root sessions:** a person reads each reply, so the block tells the model to call
+  `eve__task_wait` when it has nothing to say until a result arrives, and to reply now when the
+  person should hear from it, such as to confirm that work is underway.
+- **Child sessions and a schedule's sessions:** only the turn's final reply reaches the caller, so
+  the block tells the model to call `eve__task_wait` instead of replying while tasks work. Text the
+  model writes while its turn holds for tasks is narration (`content.completed` with
+  `phase: "narration"`): clients that render the stream show it, and channels don't post it.
 
-```text
-Started task deploy-4hd8sa. Its result will arrive in a <task_result> message.
-Started task researcher-7k2m9q. Its result will arrive in a <task_result> message. To send it another message, call researcher again with taskId researcher-7k2m9q.
-Sent to task researcher-7k2m9q. Its reply will arrive in a <task_result> message.
-```
+**Receipts.** A task call returns a receipt with a `taskId`; a resumable task can be called again using that ID.
 
 **Results.** Each result arrives once, as a `<task_result>` block in a `task.result` message that
 eve appends at the next step boundary, right after `eve__task_wait` returns, or when a held turn
@@ -175,29 +172,18 @@ model reads which tasks settled and which are still working, for example:
 deploy-4hd8sa completed; its result follows. 1 task is still working: researcher-7k2m9q.
 ```
 
-**`eve__task_cancel({ taskId })`** stops a task's current work and says so. A resumable task's answer
-also tells the model how to give it new work. When the task has no work to stop, because it already
-finished or is an idle resumable task, `eve__task_cancel` says that instead:
+**`eve__task_cancel({ taskId })`** stops a task's current work and says so. A cancelled agent task
+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
+answer tells the model how to give them new work. When the task has no work to stop, because it
+already finished or is an idle resumable task, `eve__task_cancel` says that instead:
 
 ```text
 Stopped deploy-4hd8sa; it won't report back.
-Stopped researcher-7k2m9q's current work; it won't report back. To give it new work, call researcher again with taskId researcher-7k2m9q.
+Stopped researcher-7k2m9q; it won't report back.
 researcher-7k2m9q had no work to stop.
 ```
 
-**`[Tasks]` note.** When the session's tasks change, eve adds a note at the next step boundary that
-lists the working tasks and the 10 most recently used idle resumable tasks. The note returns after
-[compaction](/docs/concepts/default-harness#compaction), so the model can always find a task id:
-
-```text
-[Tasks]
-<tasks>
-<task id="deploy-4hd8sa" tool="deploy" status="working"/>
-</tasks>
-<idle>
-<task id="researcher-7k2m9q" tool="researcher"/>
-</idle>
-```
+**`[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).
 
 **Errors.** Two error codes are specific to tasks:
 
@@ -216,31 +202,22 @@ No turn ends while any task is working. When the model ends a turn early, eve wa
 appends the results, and calls the model again in the same turn. No result ever starts a turn on
 its own. An idle resumable task isn't working, so it doesn't hold the turn.
 
-A held turn stays open. Each time it parks, when eve holds it or when `eve__task_wait` has no result
-yet, the stream emits `turn.waiting` with the turn's `turnId`. The next `step.started` for the
-same `turnId` means the turn resumed, and `session.waiting` comes only after the turn ends. The
-model's text before the wait depends on the session:
-
-- **Root sessions:** the text completes as an ordinary message, including text written before
-  `eve__task_wait` in the same step. The person can keep writing, and the turn resumes under the same id.
-- **Child sessions and a schedule's sessions:** the held text step reports
-  `finishReason: "tool-calls"` on `message.completed`, so channels post only the final reply.
-
-A question or sign-in from a task, such as an agent's question, parks the turn the same way: the
-stream emits `input.requested` or `authorization.required`, then `turn.waiting`, and the turn
-continues once the person answers or signs in.
-
-In every session, `turn.completed` comes only when the turn really ends. The TypeScript client's
-`send(...).result()` and the MCP channel's `agent_get` read past `turn.waiting` and report the
-final reply rather than the text written before the wait. At `turn.waiting`, an unanswered input
-request (a question, approval, or `session-limit` prompt) makes `result()` return
-`status: "waiting"`; use `respond()` to answer it and continue reading the same turn.
-A sign-in keeps the response attached while its authorization callback is pending. Render the
-sign-in prompt from the live `authorization.required` event rather than waiting for `result()`.
-See [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn).
-Channels such as [Slack](/docs/channels/slack) post a root session's text before the wait as an
-ordinary reply, then post the reply after the results as another message. Slack also shows each
-turn's tasks in a live [task card](/docs/channels/slack#task-card).
+A held turn stays open. While it waits on its tasks, when eve holds it or when `eve__task_wait` has no
+result yet, the turn keeps running: it pauses only for interactions. The next `model.requested` for the
+same `turnId` means the turn took its results, and `turn.settled` comes only when the turn really
+ends. The model's text before the wait depends on the session:
+
+- **Root sessions:** the text completes as an ordinary reply part (`phase: "reply"`), including text
+  written before `eve__task_wait` in the same step. The person can keep writing, and the turn resumes
+  under the same id.
+- **Child sessions and a schedule's sessions:** the held text completes as `phase: "narration"`, so
+  channels post only the final reply.
+
+A question or sign-in from a task, such as an agent's question, pauses the turn on that interaction:
+the stream emits `interaction.opened`, then `turn.paused` awaiting it, and the turn continues once
+the question is answered or sign-in completes.
+
+`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.
 
 A steering message from the turn's own caller, one sent with `turnPolicy: "steer"`, the default,
 ends an `eve__task_wait` and aborts the `abortSignal` of any `execute` call the turn waits on, but it
@@ -256,42 +233,34 @@ correct an agent by calling it again with its `taskId`, or stop a task with `eve
 - **A failed turn** cancels every working task.
 - **The end of the session** ends every task.
 
-Cancelled work never reports back. A `task` tool's task is then finished; its run waits up to 30
-seconds for the body to finish unwinding, then ends as cancelled. A `serve` tool's task stays
-available instead: its waiting calls settle as `cancelled`, the stretch's `abortSignal` aborts, and
-the task becomes idle, as long as the body catches that abort and returns to `receive()`. For an
-agent, that cancels the agent's current turn and keeps its conversation, so a later call with the
-same `taskId` continues where it left off. A `serve` body that doesn't return to `receive()` within
-30 seconds of a cancel ends, and the task finishes.
+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.
 
 ## Stream events
 
-| Event           | When                                                                                        | Data                                                                                       |
-| --------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `task.started`  | A call starts a task, or reaches a resumable task by its `taskId`                           | `taskId`, `callId`, `turnId`, the tool `name`, and `kind`                                  |
-| `task.settled`  | A reply, return, failure, or cancel settles one call                                        | `taskId`, `callId`, `turnId`, `name`, `kind`, `status`, and `output`, `error`, or `cancel` |
-| `agent.started` | A workflow run, including an agent tool's, opens a session with an agent                    | `callId`, `turnId`, `taskId`, `name`, `sessionId`, `streamPath`                            |
-| `turn.waiting`  | An open turn parks on its tasks, an `eve__task_wait`, a question, a sign-in, or an approval | `turnId`, `sequence`, and `on`: `"input"` when a person must act, otherwise `"tasks"`      |
-
-`task.started` and `task.settled` come once each per call, and `(taskId, callId)` identifies the
-call. Both carry that call's `turnId`, which for a resumable task's later call can be a later turn
-than the one that started the task, and the task's tool `name` and `kind`. `kind` is `"agent"` for
-an agent tool's call and `"tool"` otherwise. Events recorded by earlier eve versions omit `name`
-and `kind` on `task.settled`; match those to their `task.started` by `callId`. `status` is `"completed"`, `"failed"`, or `"cancelled"`. A completed call carries
-`output`, a failed call carries `error`, and a cancelled call carries `cancel.reason`:
-`"task_cancel"` when the model called `eve__task_cancel`, `"turn_cancelled"` when someone cancelled
-the turn, or the working tasks between turns, or `"turn_ended"` when the turn ended, such as by
-failing, while the task still worked. `cancel` is absent when the task's run stopped on its own, and on events recorded by
-earlier eve versions.
-`agent.started` names the call and turn whose run opened the session, and its `taskId` is absent
-when an `execute` call opened it. Results reach the model as a message in its history, not as a
-stream event, so read outcomes from `task.settled`. An `input.requested`,
-`authorization.required`, or `authorization.completed` event from a task's run carries its
-`taskId`. Hooks subscribe to the same events. The stream also carries the model's `eve__task_wait` and
-`eve__task_cancel` calls as ordinary `actions.requested` tool calls, so evals can assert on them. The
-`eve dev` terminal UI, channel activity such as Slack's status line, and ACP clients leave those calls out; the terminal UI shows each
-task's start and end instead. See
-[Sessions, runs, and streaming](/docs/concepts/sessions-runs-and-streaming#task-events) and
+| Fact           | When                                                                     | Data                                                      |
+| -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| `task.started` | A call starts a task                                                     | `taskId`, `name`, `kind`, and `startedBy: { callId }`     |
+| `call.started` | A call reaches its task, including a later call to a resumable task      | `callId` and `taskId`                                     |
+| `call.settled` | A reply, return, failure, or cancel settles one call                     | `callId`, `outcome`, and `output`, `outputOf`, or `error` |
+| `task.ended`   | The task ends; agent and one-shot tasks end immediately on cancellation  | `taskId`, `outcome`, and `reason` or `error`              |
+| `child.opened` | A workflow run, including an agent tool's, opens a session with an agent | `sessionId`, `name`, `stream`, and `owner`                |
+
+`task.started` comes once per task, and `task.ended` once when it ends. Each call the task
+serves has its own `call.started` with the `taskId` and its own `call.settled`, whose scope names
+that call's turn, which for a resumable task's later call can be a later turn than the one that
+started the task. `kind` is `"agent"` for an agent tool's task and `"tool"` otherwise. A call's
+`outcome` is `"completed"`, `"failed"`, or `"interrupted"` when the call was cancelled. A completed
+call carries `output`, or `outputOf` naming the earlier call whose output it shares; a failed call
+carries `error`. A task ends `"cancelled"` with a `reason` when it was cancelled, and `"failed"` with
+an `error` when its run failed.
+`child.opened` is owned by the call when an agent tool's call opened the session, and by the task
+when a task's run opened it with `ctx.agent`. Results reach the model as a message in its history,
+not as a stream event, so read outcomes from `call.settled`. An `interaction.opened` from a task's
+run carries the task in its `scope`. Hooks subscribe to the same facts. The stream also carries the
+model's `eve__task_wait` and `eve__task_cancel` calls as ordinary `call.requested` tool calls, so
+evals can assert on them. The `eve dev` terminal UI, channel activity such as Slack's status line,
+and ACP clients leave those calls out; the terminal UI shows each task's start and end instead. See
+[Sessions, runs, and streaming](/docs/concepts/sessions-runs-and-streaming#task-facts) and
 [Follow a subagent](/docs/guides/client/streaming#follow-a-subagent).
 
 ## Ownership and limits

package/docs/tools/workflows.mdx

@@ -94,7 +94,7 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
   `ctx.agent()`, and call `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
   Call `getSandbox`, `getToken`, and `requireAuth` in a step: the workflow body throws when it calls them.
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
-  not tools returned from `defineDynamic` resolvers.
+  not tools a `defineDynamic` function returns.
 
 `ctx.agent`, `ctx.agents`, and `ctx.ask` are available only on `WorkflowToolContext` and
 `WorkflowServeContext` in the workflow body.
@@ -191,7 +191,7 @@ Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workfl
 and replace `agent(ctx, input)` and `ask(ctx, request)` with an agent session from
 [`ctx.agent(name)`](#delegate-work-ctxagent) and `ctx.ask(request)`. The `eve/workflow` entry point
 has been removed. Import `WorkflowToolContext`, `AgentSession`,
-`ToolInputRequest`, `ToolInputRequestOptions`, and `ToolInputResponse` from `eve/tools` when you
+`ToolQuestion`, `ToolAskOptions`, and `ToolAnswer` from `eve/tools` when you
 need explicit types.
 
 `ctx.ask` no longer accepts `dismissible`, and its `dismissed` status is now `cancelled`. A
@@ -343,9 +343,9 @@ described in [Tasks](/docs/tools/tasks). What differs:
 - **Unknown tasks:** the id must name an unfinished task this tool started; otherwise the call
   fails with `UNKNOWN_TASK`. The call can come from any caller in the session.
 - **`ctx.session` and `ctx.agents` describe the call being served:** a later call can come in a
-  later turn than the one that started the task. Its `task.started` and `task.settled` carry that
-  call's `callId` and `turnId`, and so do the questions, sign-ins, and `agent.started` events the
-  body causes while serving it. From the moment `receive()` resolves with a call, `ctx.session` is that call's view of
+  later turn than the one that started the task. Its `call.started` and `call.settled` carry that
+  call's `callId` and turn, and so do the questions and sign-ins the body opens while serving
+  it. From the moment `receive()` resolves with a call, `ctx.session` is that call's view of
   the session, including in a step that receives `ctx`: `ctx.session.turn` is the call's turn, and
   `ctx.session.auth` is the auth the session admitted the call with, which may belong to a
   different caller than the one that started the task. `getToken`, `requireAuth`, and connections
@@ -368,7 +368,7 @@ described in [Tasks](/docs/tools/tasks). What differs:
   uses the auth of the call being served; remote identity follows the
   [forwarding rules](../guides/remote-agents#forwarding-the-caller-identity).
 - **Results:** `ctx.reply(output)` settles every call received so far with `output`, all at once.
-  Each settled call reports its own `task.settled`, and the model receives the reply once. The task
+  Each settled call reports its own `call.settled`, and the model receives the reply once. The task
   then goes idle until its next call. A reply with
   no call left to settle is dropped, and `ctx.ask` throws while no call is waiting for a result.
   A reply also withdraws the questions still pending for the calls it settles, but doesn't abort
@@ -395,7 +395,8 @@ described in [Tasks](/docs/tools/tasks). What differs:
 Every [agent tool](/docs/subagents), including the built-in `agent` tool and remote agents, is a
 `serve` tool that eve builds this way on public API: each task opens one session with
 [`ctx.agent`](#delegate-work-ctxagent), sends each call's `message` with that call's `abortSignal`,
-and replies with the final response of each agent turn.
+and replies with the final response of each agent turn. Unlike other `serve` tasks, cancelling an
+agent task ends it; start a new task to delegate again.
 
 ## Authorize inside a step
 
@@ -512,6 +513,7 @@ async function prepareInput(ctx: WorkflowStepToolContext, input: { value: string
 const answer = await ctx.ask(
   {
     prompt: string,
+    title?: string,
     display?: "confirmation" | "select" | "text",
     options?: { id: string; label: string; description?: string; style?: "primary" | "danger" | "default" }[],
     allowFreeform?: boolean,
@@ -523,8 +525,8 @@ const answer = await ctx.ask(
 // | { status: "unavailable" }
 ```
 
-`ctx.ask` publishes an `input.requested` event on the session — rendered the way channels render
-tool approvals — and returns an awaitable answer. Awaiting it suspends the run until a response arrives.
+`ctx.ask` opens an interaction on the session (`interaction.opened`) — rendered the way channels
+render tool approvals — and returns an awaitable answer. Awaiting it suspends the run until a response arrives.
 The `ask_question` tool is a workflow tool built on `ctx.ask`.
 
 The answer's `status` tells the body what happened:
@@ -532,8 +534,7 @@ The answer's `status` tells the body what happened:
 - `answered`: the person picked an option (`optionId`) or typed a reply (`text`).
 - `cancelled`: the request was withdrawn before anyone answered it, because the `signal` passed to
   `ctx.ask` or the call's `abortSignal` aborted, or because a `serve` body replied to the call. The
-  session emits `input.resolved` with
-  `outcome: "cancelled"`, so clients stop offering the question.
+  session settles the interaction `withdrawn`, so clients stop offering the question.
 - `unavailable`: the session cannot request input, such as a scheduled run. `ctx.ask` returns this
   immediately instead of waiting for an answer no one can give.
 
@@ -582,7 +583,7 @@ const response = await reviewer.send("Review the deployment plan for security ri
   outputSchema: z.object({ findings: z.array(z.string()) }),
   signal: ctx.abortSignal,
 });
-const { data, message, status } = await response.result();
+const { data, reply, status } = await response.result();
 ```
 
 Set `model` when the workflow should run a local child with a different AI Gateway model. The
@@ -622,7 +623,19 @@ or `disableTool()`. Delegated root copies and declared subagent contexts do not
 root-copy target. The invocation name `agent` is reserved, so a declared subagent cannot shadow it.
 An unavailable name rejects the first `send`.
 
-`send(message, options?)` accepts:
+`send(message, options?)` accepts text or `MessageContent<string | URL>`: up to 64 text and
+file parts. File `data` must be an HTTP(S) URL, as a string or `URL` object. Inline bytes, base64,
+and `data:` URLs are rejected before dispatch so attachment bytes do not enter durable workflow
+inputs. Upload a local file first, then send its URL:
+
+```ts
+await reviewer.send([
+  { type: "text", text: "Review Alice's report." },
+  { type: "file", data: "https://files.example/report.pdf", mediaType: "application/pdf" },
+]);
+```
+
+The options are:
 
 | Option         | Description                                                                                              |
 | -------------- | -------------------------------------------------------------------------------------------------------- |
@@ -633,15 +646,15 @@ A message sent while the session's turn is running joins that turn, and its resp
 that turn's result. If the turn ends before the agent reads the message, the message starts the next
 turn instead, and its response resolves with that turn's result. The responses of earlier messages
 that are still waiting resolve with the same result. A message sent while the session is idle starts
-the next turn, and the session keeps its conversation between turns. `result()` returns the
-client's `MessageResult` fields, plus `error` when the turn failed:
+the next turn, and the session keeps its conversation between turns. `result()` returns:
 
-| Field     | Description                                                                                                                                                                                                         |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data`    | The structured value, when the turn requested `outputSchema`.                                                                                                                                                       |
-| `message` | The agent's final reply text, when the turn did not request `outputSchema`.                                                                                                                                         |
-| `status`  | `"waiting"` when the session waits for its next message, `"completed"` when the session ended with the turn, or `"failed"` when the turn failed. A cancelled turn is `"waiting"` with neither `data` nor `message`. |
-| `error`   | `{ message }` with the reason the turn failed, present only when `status` is `"failed"`.                                                                                                                            |
+| Field          | Description                                                                                               |
+| -------------- | --------------------------------------------------------------------------------------------------------- |
+| `data`         | The structured value, when the turn requested `outputSchema`.                                             |
+| `reply`        | The agent's final reply text, when available.                                                             |
+| `status`       | `"completed"`, `"failed"`, or `"cancelled"`. Completion does not by itself mean the session ended.        |
+| `sessionEnded` | Whether the session ended in the response's final commit.                                                 |
+| `error`        | `{ message }` with the reason the turn failed. Required when `status` is `"failed"` and absent otherwise. |
 
 Every `ctx.agent(name, options?)` call returns a new session that only the workflow run can address.
 The model does not see it; it sees what the tool returns. A local child runs as the caller's principal with the
@@ -652,12 +665,10 @@ identity, set `forwardPrincipal: true` on the remote agent and configure the rec
 A person answers the child's questions and sign-ins at the root session, as for any subagent.
 The session ends when the run finishes, which cancels any turn still running.
 
-The parent stream announces each session with `agent.started`, which carries the `callId` and
-`turnId` of the tool call the run is serving when it opens the session (for a `serve` task, the
-latest call it received), the
-`taskId` when the call runs as a task, the agent `name`, the child's `sessionId`, and a
-`streamPath`. Pass the event to
-[`session.agent(started).stream()`](/docs/guides/client/streaming#follow-a-subagent) to follow the child.
+The parent stream announces each session with `child.opened`, which carries its `owner` (the
+task whose run opened the session, or the tool call when the call doesn't run as a task), the
+agent `name`, the child's `sessionId`, and its `stream` path. Pass the event to
+[`session.agent(opened).stream()`](/docs/guides/client/streaming#follow-a-subagent) to follow the child.
 
 ### Route to a hidden subagent with Jev
 
@@ -709,7 +720,7 @@ async function chooseTarget(
   "use step";
 
   const result = await decide({
-    abortSignal,
+    signal: abortSignal,
     state: { task },
     questions: {
       route: {
@@ -739,9 +750,9 @@ export default defineWorkflowTool({
     );
 
     const response = await ctx.agent(target).send(task, { signal: ctx.abortSignal });
-    const { error, message, status } = await response.result();
-    if (status === "failed") throw new Error(`${target} failed: ${error?.message}`);
-    return message ?? null;
+    const { error, reply, status } = await response.result();
+    if (status === "failed") throw new Error(`${target} failed: ${error.message}`);
+    return reply ?? null;
   },
 });
 ```
@@ -755,7 +766,7 @@ The decision runs in a step so workflow replay records its result instead of mak
 To replace the model-facing `agent` tool with a router across every target in `ctx.agents`, export `agentRouter()` from the `agent` slot:
 
 ```ts title="agent/tools/agent.ts"
-import { agentRouter } from "eve/tools/agent-router";
+import { agentRouter } from "eve/tools/agent_router";
 
 export default agentRouter();
 ```
@@ -774,7 +785,7 @@ eve advances the generator; use an awaited workflow operation when the body need
 
 | Operation       | Behavior                                                          |
 | --------------- | ----------------------------------------------------------------- |
-| `yield value`   | Emits an `action.partial` snapshot for the pending tool call.     |
+| `yield value`   | Emits a `call.progress` snapshot for the pending tool call.       |
 | `return value`  | Settles the tool call with its output.                            |
 | No return value | Uses the last yield as output, or `null` if there were no yields. |
 

package/docs/tutorial/guard-the-spend.mdx

@@ -51,7 +51,7 @@ Ask for something that forces a large unfiltered scan:
 Total revenue across all customers, all time, broken out by day.
 ```
 
-The model proposes the query, `approval` returns `"user-approval"`, and the turn parks. The stream emits `input.requested`, then `turn.waiting` with `on: "input"`, and the turn stays open until someone answers. How the prompt looks depends on the channel, whether buttons in the TUI, Block Kit in Slack, or a UI control on the web. Approve it and the run resumes from exactly that step, then the query runs. Deny it and the tool is skipped, with the model told why.
+The model proposes the query, `approval` returns `"user-approval"`, and the turn parks. The stream emits `interaction.opened`, then `turn.paused` awaiting it, and the turn stays open until someone answers. How the prompt looks depends on the channel, whether buttons in the TUI, Block Kit in Slack, or a UI control on the web. Approve it and the run resumes from exactly that step, then the query runs. Deny it and the tool is skipped, with the model told why.
 
 Each session has exactly one active continuation. Answer an approval against a stale handle and it's rejected, so there's no way to double-resume the same parked turn.
 

package/docs/tutorial/run-analysis.mdx

@@ -162,14 +162,14 @@ import { z } from "zod";
 const host = process.argv[2];
 if (!host) throw new Error("Usage: node save-chart.ts <dev-server-url>");
 
-const client = new Client({ host });
-const { response } = await client.sessions.create({
+const client = new Client({ baseUrl: host });
+const { delivery } = await client.sessions.create({
   message: "Use run_sql and chart_series to plot daily order revenue in May 2026.",
 });
-const turn = await response.result();
+const turn = await delivery.result();
 if (turn.status === "failed") throw new Error("The agent turn failed. Check the dev server logs.");
-if (turn.inputRequests.length > 0) {
-  const prompts = turn.inputRequests.map((request) => request.prompt).join("\n");
+if (turn.interactions.length > 0) {
+  const prompts = turn.interactions.map((interaction) => interaction.request.prompt).join("\n");
   throw new Error(
     `Session ${turn.sessionId} needs your input before it can create the chart:\n${prompts}`,
   );
@@ -177,13 +177,16 @@ if (turn.inputRequests.length > 0) {
 
 const chartOutput = z.object({ pngBase64: z.string().min(1).max(1_398_104) });
 let saved = false;
-for (const event of turn.events) {
-  if (event.type !== "action.result") continue;
-  const result = event.data.result;
-  if (result.kind !== "tool-result" || result.toolName !== "chart_series" || result.isError)
+const charts = new Set<string>();
+for await (const event of delivery.stream()) {
+  if (event.type === "call.requested" && event.data.capability.name === "chart_series") {
+    charts.add(event.data.callId);
     continue;
+  }
+  if (event.type !== "call.settled" || !charts.has(event.data.callId)) continue;
+  if (event.data.outcome !== "completed") continue;
 
-  const { pngBase64 } = chartOutput.parse(result.output);
+  const { pngBase64 } = chartOutput.parse(event.data.output);
   const png = Buffer.from(pngBase64, "base64");
   if (
     png.byteLength > 1024 * 1024 ||
@@ -195,7 +198,7 @@ for (const event of turn.events) {
   saved = true;
 }
 if (!saved) {
-  console.error(turn.message ?? "The agent returned no explanation.");
+  console.error(turn.reply ?? "The agent returned no explanation.");
   throw new Error("No chart was returned. Check the agent's response above and sandbox setup.");
 }
 console.log(`Saved ${resolve("chart.png")}`);
@@ -211,7 +214,7 @@ Open the saved `chart.png` in your image viewer. This creates a separate session
 
 This step does not require approvals. If you return after adding the approval gate in [Guard the spend](./guard-the-spend), the script reports any pending request with its session ID. [Respond through the client](../guides/client/messages#answer-human-input-requests) before collecting that session's chart result.
 
-The same client can save a chart from a hosted agent: pass the deployment URL and configure [client authentication](../guides/client/overview#authentication) for that deployment. The file is saved on the computer running the script. In a web UI, consume the same `action.result` output to build an image preview or download control. Returning bytes from a tool does not add that UI automatically.
+The same client can save a chart from a hosted agent: pass the deployment URL and configure [client authentication](../guides/client/overview#authentication) for that deployment. The file is saved on the computer running the script. In a web UI, consume the same `call.settled` output to build an image preview or download control. Returning bytes from a tool does not add that UI automatically.
 
 This example caps charts at 1 MiB because tool outputs are persisted with session events. For larger files, copy the bytes to your application's file storage and return an authorized download URL instead. Sandbox files themselves are not permanent artifact storage.
 

package/docs/tutorial/team-playbooks.mdx

@@ -5,11 +5,11 @@ description: "Part 6 of the Build an Agent tutorial. Load the caller's team play
 
 The glossary from [Step 5](./remember-definitions) is per-session. But your teams have standing analysis conventions for the analytics assistant (Growth groups revenue by date, Finance reconciles customer totals), and those shouldn't bleed across tenants. Load the right team's playbook for whoever is asking.
 
-A skill is an on-demand procedure. The model pulls it in with `eve__skill({ name })` only when a turn needs it. Make it dynamic and the skill gets decided at runtime instead of baked in. A `defineDynamic` resolver reads the session and returns a `defineSkill` (or nothing). Here you key that decision on the caller's identity in `ctx.session.auth`.
+A skill is an on-demand procedure. The model pulls it in with `eve__skill({ name })` only when a turn needs it. Make it dynamic and the skill gets decided at runtime instead of baked in. A `defineDynamic` function reads the session and returns a `defineSkill` or `null`. Here the caller's identity in `ctx.session.auth` decides which playbook is available.
 
 ## A playbook per principal
 
-`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the claims your auth layer stamped on, including the team. Read the team, look up that team's playbook, and emit a skill for it:
+`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the claims your auth layer stamped on, including the team. Select the team, then return that team's playbook as a skill:
 
 ```ts title="agent/skills/team-playbook.ts"
 import { defineDynamic, defineSkill } from "eve/skills";
@@ -29,36 +29,32 @@ const PLAYBOOKS: Record<string, { title: string; markdown: string }> = {
   },
 };
 
-export default defineDynamic({
-  events: {
-    "session.started": async (_event, ctx) => {
-      const team = ctx.session.auth.current?.attributes.team;
-      const key = Array.isArray(team) ? team[0] : team;
-      const playbook = key ? PLAYBOOKS[key] : undefined;
-      if (!playbook) return null;
-
-      return defineSkill({
-        description:
-          `Use when answering analysis questions for the ${key} team. ` +
-          `Contains that team's standing conventions.`,
-        markdown: `# ${playbook.title}\n\n${playbook.markdown}`,
-      });
-    },
-  },
+export default defineDynamic((ctx) => {
+  const team = ctx.session.auth.current?.attributes.team;
+  const key = Array.isArray(team) ? team[0] : team;
+  const playbook = typeof key === "string" ? PLAYBOOKS[key] : undefined;
+  if (!playbook) return null;
+
+  return defineSkill({
+    description:
+      `Use when answering analysis questions for the ${key} team. ` +
+      `Contains that team's standing conventions.`,
+    content: `# ${playbook.title}\n\n${playbook.markdown}`,
+  });
 });
 ```
 
-`session.started` fires once per session. The resolver reads the team once, and the resulting skill stays available for every turn that follows. Returning `null` produces no skill, so a caller with no team gets no playbook.
+The function reads the caller's team and returns its skill before each model call, so later caller changes update the playbook. Returning `null` produces no skill, so a caller with no team gets no playbook.
 
 ## See it route
 
-The team comes from authenticated claims, which the auth layer stamps on in [Step 8](./ship-it). Until then `ctx.session.auth.current` has no `team`, so the resolver returns `null` and no playbook loads. To verify routing now, stamp a team in local dev. Add a dev-only entry to `agent/channels/eve.ts` ahead of `localDev()`, and remove it before Step 8 wires real auth:
+The team comes from authenticated claims, which the auth layer stamps on in [Step 8](./ship-it). Until then `ctx.session.auth.current` has no `team`, so the function returns `null` and no playbook loads. To verify routing now, stamp a team in local dev. Add a dev-only entry to `agent/channels/eve.ts` ahead of `localDev()`, and remove it before Step 8 wires real auth:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
 import { localDev, placeholderAuth, vercelOidc, type AuthFn } from "eve/channels/auth";
 
-// Dev-only: stamp a team so Step 6's playbook resolver has something to read.
+// Dev-only: stamp a team so Step 6's playbook has something to select.
 // Remove before Step 8.
 const devTeam: AuthFn<Request> = () =>
   process.env.NODE_ENV === "production"
@@ -75,11 +71,11 @@ export default eveChannel({
 });
 ```
 
-Restart with `npm run dev` and ask "Summarize May 2026 revenue using our team's playbook." The model loads the skill with `eve__skill`, queries the sample data, and applies Growth's daily and plan groupings. Switch `team` to `"finance"`, restart, and start a new session before asking again. The resolver runs at `session.started`, so changing the team does not replace the playbook in an existing session. The same question in the new session uses Finance's reconciliation rules.
+Restart with `npm run dev` and ask "Summarize May 2026 revenue using our team's playbook." The model loads the skill with `eve__skill`, queries the sample data, and applies Growth's daily and plan groupings. Switch `team` to `"finance"`, restart, and ask again. The selected team changed, so eve offers Finance's playbook before the next model call, and the same question uses Finance's reconciliation rules.
 
 Because the team comes from authenticated claims, not from the message, one tenant can't borrow another's playbook through the message content.
 
-The same `defineDynamic` resolver drives dynamic tools and instructions too. For the full mechanism, see [Dynamic capabilities](../guides/dynamic-capabilities).
+The same `defineDynamic` form drives dynamic tools and instructions too. For the full mechanism, see [Dynamic capabilities](../guides/dynamic-capabilities).
 
 → Next: [Guard the spend](./guard-the-spend)