The Open Framework for Building Agents
docs(eve): correct task event and pause docs before release (#3952)
Andrew Barbaa751eaee4566
diff --git a/.changeset/agent-sessions.md b/.changeset/agent-sessions.mdindex 3a1d77151..f546d8c53 100644--- a/.changeset/agent-sessions.md+++ b/.changeset/agent-sessions.md@@ -2,4 +2,4 @@"eve": minor----`ctx.agent(name)` in a workflow tool now returns a session with that agent: `send(message, { outputSchema, signal })` returns a response whose `result()` resolves the turn's `{ data, message, status }`, and the parent stream announces each session with `agent.started`, carrying the opening call's `callId` and `turnId`, which `session.streamSubagent()` accepts. `ctx.agent(name, { message, agentId })` is removed, sessions end when the workflow run finishes, and remote agents now check a protocol version, so upgrade both deployments together.+`ctx.agent(name)` in a workflow tool now returns a session with that agent: `send(message, { outputSchema, signal })` returns a response whose `result()` resolves the turn's `{ data, message, status }`, and the parent stream announces each session with `agent.started`, carrying the opening call's `callId` and `turnId`, which `session.agent(started).stream()` follows. `ctx.agent(name, { message, agentId })` is removed, sessions end when the workflow run finishes, and remote agents now check a protocol version, so upgrade both deployments together.diff --git a/.changeset/agents-as-tasks.md b/.changeset/agents-as-tasks.mdindex 526259993..7ae5dfb4e 100644--- a/.changeset/agents-as-tasks.md+++ b/.changeset/agents-as-tasks.md@@ -2,4 +2,4 @@"eve": minor----Every agent tool is now a `serve(receive, ctx)` tool built on `ctx.agent`, so every subagent call is a resumable task: the call returns a receipt, the agent's reply arrives as a task result, and the model continues the same agent by passing `taskId` (replacing `agentId`) or stops its current turn with `task_cancel`. The `subagent.called`, `subagent.started`, `subagent.event`, and `subagent.completed` events, their hooks, the `[Agents]` note, and the `AGENT_*` errors are removed; clients, hooks, and evals read `task.started`, `task.settled`, and `agent.started` instead, and `session.streamSubagent()` takes only an `agent.started` event. `task.started` carries `kind: "agent"` for an agent tool's call and `"tool"` otherwise, so `t.calledSubagent` also sees an agent call that failed before its session opened. The default message reducer behind `useEveAgent()` settles a task call's tool part from `task.settled` (output, error, or cancellation).+Every agent tool is now a `serve(receive, ctx)` tool built on `ctx.agent`, so every subagent call is a resumable task: the call returns a receipt, the agent's reply arrives as a task result, and the model continues the same agent by passing `taskId` (replacing `agentId`) or stops its current turn with `task_cancel`. The `subagent.called`, `subagent.started`, `subagent.event`, and `subagent.completed` events, their hooks, the `[Agents]` note, and the `AGENT_*` errors are removed; clients, hooks, and evals read `task.started`, `task.settled`, and `agent.started` instead, and `session.agent(started).stream()` follows a child from its `agent.started` event. `task.started` carries `kind: "agent"` for an agent tool's call and `"tool"` otherwise, so `t.calledSubagent` also sees an agent call that failed before its session opened. The default message reducer behind `useEveAgent()` settles a task call's tool part from `task.settled` (output, error, or cancellation).diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.mdindex f62b8f30e..4fdf1c549 100644--- a/docs/concepts/sessions-runs-and-streaming.md+++ b/docs/concepts/sessions-runs-and-streaming.md@@ -81,7 +81,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:| `input.resolved` | The server accepted terminal human-input outcomes; carries `resolutions` with responses when provided. || `agent.started` | A workflow run opened a session with `ctx.agent`, such as an agent tool's; carries `taskId` when the run is a task, `sessionId`, and the `streamPath` that `session.agent(started).stream()` follows. || `task.started` | A tool call started a [task](#task-events); carries `taskId`, `callId`, `turnId`, the tool `name`, and `kind`: `"agent"` for an agent tool, `"tool"` otherwise. |-| `task.settled` | A task's call settled; carries `taskId`, `callId`, `turnId`, `status`, and `output` or `error.message`. |+| `task.settled` | A task's call settled; carries `taskId`, `callId`, `turnId`, `status`, and `output` or `error.message`; a cancelled call carries neither. || `reasoning.appended` | A reasoning text delta. || `reasoning.completed` | The finalized reasoning block. || `message.appended` | An assistant text delta. |diff --git a/docs/guides/hooks.md b/docs/guides/hooks.mdindex 5a457139e..e7dfba381 100644--- a/docs/guides/hooks.md+++ b/docs/guides/hooks.md@@ -91,7 +91,12 @@ For `task.started`, `task.settled`, and `agent.started`, `ctx.session.id`identifies the session that started the task or opened the subagent session.Typed handlers and `*` handlers receive this context even when the eventarrives between turns. These hooks can use `ctx.getSandbox()` against that-session, and sandbox changes they make are kept for its next turn.+session. For `task.started` and `task.settled`, sandbox changes they make are+kept for its next turn. eve publishes `agent.started` as soon as the child+session opens, even while the parent's model step is still running, and+changes an `agent.started` hook makes to session state at that point are not+kept. Use `agent.started` hooks to observe the event, not to change session+state.### Narrowing tool resultsdiff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.mdindex c5c6cd0c0..916c65b91 100644--- a/docs/tools/human-in-the-loop.md+++ b/docs/tools/human-in-the-loop.md@@ -9,7 +9,7 @@ Human-in-the-loop (HITL) is any point where the agent durably pauses and waits f- **Approvals** — a tool policy allows, denies, or pauses a call for a person to review. The agent decides to call the tool; the policy decides whether it runs automatically or needs a human decision.- **Questions** — the agent itself asks the user a clarifying question or a choice mid-turn, and parks until they answer.-Either way the run parks at `session.waiting`, durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.+An approval ends the turn and the session parks at `session.waiting`. A question keeps the turn open, and the stream reports `turn.waiting`. Either way the run waits durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.## Approvals@@ -177,7 +177,7 @@ Approvals and questions share one protocol:1. A tool call needs approval, or a workflow tool such as `ask_question` calls `ctx.ask()`.2. eve emits an `input.requested` stream event carrying the pending requests.-3. The turn parks at `session.waiting`, durably, for as long as it takes.+3. The run parks durably, for as long as it takes. An approval ends the turn with `turn.completed`, then `session.waiting`. A question keeps the turn open: the stream emits `turn.waiting`, and after the answer the turn resumes under the same `turnId`.4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `cancel`.For `ctx.ask()` questions from tools, a follow-up message answers the question only when exactly one question is pending. The message must match an option, or the question must allow free text. Otherwise the message follows the session's `turnPolicy`. A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call the turn waits on, so a question such a call asked, such as `ask_question`'s, is withdrawn and resolves as `cancelled`. The model reads the message once those calls settle. Questions from subagents need a structured response.diff --git a/docs/tools/tasks-upgrade.md b/docs/tools/tasks-upgrade.mdindex 514b05996..77e538cb9 100644--- a/docs/tools/tasks-upgrade.md+++ b/docs/tools/tasks-upgrade.md@@ -114,11 +114,11 @@ failed task reports its error in `task.settled` and in its `task.result` block.The `subagent.called`, `subagent.started`, `subagent.completed`, and `subagent.event` events areremoved. Use these instead:-| Event | Replaces | Data |-| --------------- | -------------------- | --------------------------------------------------------------- |-| `task.started` | `subagent.called` | `taskId`, `callId`, `turnId`, `name` |-| `task.settled` | `subagent.completed` | `taskId`, `callId`, `turnId`, `status`, and `output` or `error` |-| `agent.started` | `subagent.started` | `callId`, `turnId`, `taskId`, `name`, `sessionId`, `streamPath` |+| Event | Replaces | Data |+| --------------- | -------------------- | -------------------------------------------------------------------------------- |+| `task.started` | `subagent.called` | `taskId`, `callId`, `turnId`, `name`, `kind` |+| `task.settled` | `subagent.completed` | `taskId`, `callId`, `turnId`, `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 --git a/docs/tools/tasks.md b/docs/tools/tasks.mdindex 8f310f3c3..dcc36cae6 100644--- a/docs/tools/tasks.md+++ b/docs/tools/tasks.md@@ -256,16 +256,18 @@ same `taskId` continues where it left off. A `serve` body that doesn't return to## Stream events-| Event | When | Data |-| --------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------- |-| `task.started` | A call starts a task, or reaches a resumable task by its `taskId` | `taskId`, `callId`, `turnId`, and the tool `name` |-| `task.settled` | A reply, return, failure, or cancel settles one call | `taskId`, `callId`, `turnId`, `status`, and `output` or `error` |-| `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, a `task_wait`, a question, or a sign-in | `turnId` and `sequence` |+| 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`, `status`, and `output` or `error` unless cancelled |+| `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, a `task_wait`, a question, or a sign-in | `turnId` and `sequence` |`task.started` and `task.settled` come once each per call, and `(taskId, callId)` identifies thecall. 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. `status` is `"completed"`, `"failed"`, or `"cancelled"`.+than the one that started the task. `kind` is `"agent"` for an agent tool's call and `"tool"`+otherwise. `status` is `"completed"`, `"failed"`, or `"cancelled"`. A completed call carries+`output`, a failed call carries `error`, and a cancelled call carries neither.`agent.started` names the call and turn whose run opened the session, and its `taskId` is absentwhen an `execute` call opened it. Results reach the model as a message in its history, not as astream event, so read outcomes from `task.settled`. An `input.requested`,diff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdxindex cd9d76f24..4d3c39838 100644--- a/docs/tools/workflows.mdx+++ b/docs/tools/workflows.mdx@@ -690,7 +690,7 @@ Use [`ctx.ask`](#ask-a-human-ctxask) when the workflow needs a human answer. See`ctx.abortSignal` aborts when the call is cancelled: by `session.cancel()`, or, for a task, by`task_cancel`, a failed turn, or the end of the session. A steering message also aborts it for an-`execute` call; see [Stop early for a new message](#stop-early-for-a-new-message). It is durable —+`execute` call; see [Stop early for a new message](#stop-early-for-a-new-message). It is durable:it survives replay, and a step that receives it observes the abort. Pass it into the steps thatshould stop, and clean up in `try/finally`: