Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
index 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.md
index 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.md
index 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.md
index 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 event
arrives 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 results
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.md
index 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.md
index 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 are
removed. 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.md
index 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 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. `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 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`,
diff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdx
index 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 that
should stop, and clean up in `try/finally`: