eve 0.67.2 → 0.69.0

package/docs/tools/workflows.mdx

@@ -8,14 +8,18 @@ A workflow tool is a static tool defined with `defineWorkflowTool` from `eve/too
 `"use workflow"` as the first statement of its executor. Each call starts a durable Workflow run. Use one when a tool must wait for a person, webhook, or timer,
 delegate work to subagents, or coordinate retryable steps over a long period.
 
-Durable suspension and background execution are independent. `defineWorkflowTool` lets the body
-suspend at durable waits without holding compute. `execution: "background"` determines whether
-the parent agent receives a task receipt and continues before the body finishes. A workflow can
-suspend in either execution mode; running in the background does not require a suspension.
+A workflow tool defines exactly one entry point, and the entry point decides how its calls run. A
+call to an `execute(input, ctx)` tool blocks its turn until the workflow settles, and the parent
+agent receives the workflow's output as the tool result. While the body waits durably, the turn
+parks without holding compute. A `task(input, ctx)` tool runs each call as a
+[task](#run-calls-as-tasks-task) instead: the model gets a receipt at once and the result arrives
+later. A `serve(receive, ctx)` tool runs a [resumable task](#resumable-tasks-serve), which the
+model can send more calls by its `taskId`. See [Tasks](/docs/tools/tasks) for choosing
+between them and for what the model sees while tasks work.
 
 Workflow tools use the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`, `"use step"`, `createHook`,
 `createWebhook`, `sleep`, retries, and replay. eve provides `ctx.ask` for questions answered through
-the session's channel, `ctx.agents` for effective callable-agent descriptions, and `ctx.agent` for durable agent delegation. Use `yield` to report
+the session's channel, `ctx.agents` for effective callable-agent descriptions, and `ctx.agent` for sessions with other agents. Use `yield` to report
 progress and `await` on a workflow operation to wait durably. Values needed after a durable wait
 stay in local variables in the workflow body.
 
@@ -67,18 +71,24 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
 
 ### Rules
 
-- Export `defineWorkflowTool({ ... })` as the default export. Its `execute` must be an async
-  function or async generator, written inline or referenced as a top-level `async function` in
-  the same module or an imported application module. Start the executor with `"use workflow"`
-  as its first statement. A missing
-  directive is a build error, even if another function in the module has one.
+- Export `defineWorkflowTool({ ... })` as the default export. Define exactly one entry point,
+  `execute`, `task`, or `serve`, written inline or referenced as a top-level `async function` in
+  the same module or an imported application module. `execute` and `task` can be async functions
+  or async generators; `serve` is an async function. Defining none, or more than one, throws at
+  definition time. Start the entry point with `"use workflow"` as its
+  first statement. A missing directive is a build error, even if another function in the module
+  has one.
 - `"use step"` marks a top-level `async function` in the tool module, or any module it imports, as a
   step. Side effects, clocks, randomness, `process.env`, and Node.js APIs belong in steps; the body
   is replayed and must stay deterministic.
 - Import `createHook`, `createWebhook`, `sleep`, and `FatalError` from `workflow` in the body.
   `start`, `getRun`, and `resumeHook` from `workflow/api` belong in steps. Your app does not install
   the SDK; for types, new projects list `eve/workflow-modules` in the tsconfig `types`.
-- In the body, `ctx` has `session`, `callId`, `toolName`, `abortSignal`, `agent`, `agents`, and `ask`.
+- In an `execute` or `task` body, `ctx` is a `WorkflowToolContext` with `session`, `callId`,
+  `toolName`, `abortSignal`, `agent`, `agents`, and `ask`. A `serve` body gets a
+  `WorkflowServeContext` with `session`, `toolName`,
+  `agent`, `agents`, `ask`, and `reply`; each call it receives carries its own `callId` and
+  `abortSignal`.
   A `"use step"` helper that receives `ctx` directly gets a restricted `WorkflowStepToolContext` with
   `session`, `callId`, `toolName`, `abortSignal`, `getToken`, and `requireAuth`. Read `ctx.agents`, call
   `ctx.agent()`, and call `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
@@ -86,7 +96,8 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
   not tools returned from `defineDynamic` resolvers.
 
-`ctx.agent`, `ctx.agents`, and `ctx.ask` are available only on `WorkflowToolContext` in the workflow body.
+`ctx.agent`, `ctx.agents`, and `ctx.ask` are available only on `WorkflowToolContext` and
+`WorkflowServeContext` in the workflow body.
 Ordinary tools, channel handlers, schedule handlers, and workflow steps do not receive these methods. Type
 step helpers with `WorkflowStepToolContext` from `eve/tools` when they need step-safe context capabilities.
 
@@ -112,8 +123,11 @@ import { workflow } from "eve/tools/workflow";
 export default workflow({ maxSubagents: 20 });
 ```
 
-The model supplies an async function body through the tool's `js` input. Its only host capability is
-`ctx.agent(name, { message, agentId?, outputSchema? })`. This can invoke subagents configured with `tool: false` or hidden by a same-named `disableTool()` file. Include those path-derived names in the workflow tool description or agent instructions when the model writes the program. For example:
+The `workflow` tool runs each call as a [task](#run-calls-as-tasks-task), so the program's return
+value reaches the model in a `task.result` message. The model supplies an async function body
+through the tool's `js` input. Its only host capability is
+`ctx.agent(name, { message, outputSchema? })`, which sends the message to a new session with that
+agent and resolves to its reply, or to the structured value when `outputSchema` is set. This can invoke subagents configured with `tool: false` or hidden by a same-named `disableTool()` file. Include those path-derived names in the workflow tool description or agent instructions when the model writes the program. For example:
 
 ```js
 const [triage, review] = await Promise.all([
@@ -125,12 +139,13 @@ return { triage, review };
 
 `maxSubagents` defaults to `100` and must be an integer from `1` through `128`. The generated
 program cannot access the workflow context, session state,
-credentials, imports, or ordinary tools. Agent authorization, questions, approvals, cancellation,
-and `agentId` continuation use the same owner-managed behavior as direct `ctx.agent` calls.
+credentials, imports, or ordinary tools. Each call starts a new child session; a program cannot
+continue a child from an earlier call. Agent authorization, questions, approvals, and cancellation
+behave as they do for sessions an authored workflow tool opens with `ctx.agent`.
 
 The sandbox resumes after every pending call in the current batch settles. `Promise.all` supports
 fan-out followed by fan-in, but `Promise.race` does not resume after only the first child settles.
-A child failure is thrown at the corresponding `ctx.agent` call, so generated code can catch it.
+A failed child turn throws at the corresponding `ctx.agent` call, so generated code can catch it.
 The program must return a JSON-serializable value.
 
 ### Migrate from `experimental_workflow`
@@ -159,27 +174,39 @@ an agent catalog. Calls use the same target resolution, availability, and author
 ### Migrate an authored workflow tool
 
 Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workflow"` directive,
-and replace `agent(ctx, input)` and `ask(ctx, request)` with `ctx.agent(target, input)` and
-`ctx.ask(request)`. The `eve/workflow` entry point has been removed. Import `WorkflowToolContext`,
-`AgentInput`, `ToolInputRequest`, and `ToolInputResponse` from `eve/tools` when you need explicit types.
+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
+need explicit types.
 
-## Wait or run in the background
+`ctx.ask` no longer accepts `dismissible`, and its `dismissed` status is now `cancelled`. A
+steering message withdraws a question an `execute` call asks, so drop the option. To keep a
+question open while the conversation continues, ask it from a [`task`](#run-calls-as-tasks-task).
 
-Both modes support the same durable waits. Choose the execution mode based on when the parent
-agent should receive a tool result:
+```diff
+-const answer = await ctx.ask({ prompt, dismissible: true });
++const answer = await ctx.ask({ prompt });
+```
+
+See [Upgrade to Tasks](/docs/tools/tasks-upgrade) for `task` replacing `execution: "background"`
+and the other changes in this release.
+
+## Wait for the result
+
+A call to an `execute` tool works like any other tool call from the model's point of view:
 
-|                              | Default execution                                   | `execution: "background"`                                            |
-| ---------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
-| Tool result                  | The workflow's output after it finishes.            | `{ status: "working", taskId }` before the body finishes.            |
-| Parent turn                  | Waits for this tool call to finish.                 | Continues after receiving the receipt.                               |
-| Durable wait inside the body | Suspends the workflow; the tool call stays pending. | Suspends the workflow; the parent can continue independently.        |
-| When the run ends            | Settles the pending tool call.                      | Sends a task completion or failure notification to the parent agent. |
-| Cancel                       | Cancelling the turn cancels the run.                | `task_cancel`, or the session ending.                                |
+- **Tool result:** the workflow's output after the body finishes.
+- **Parent turn:** waits for the call to settle, then continues with the result.
+- **Durable wait inside the body:** suspends the workflow while the tool call stays pending.
+- **Cancel:** cancelling the turn cancels the run.
+- **Steering:** a new message aborts the call's `ctx.abortSignal`, and the call settles with what
+  the body returns. See [Stop early for a new message](#stop-early-for-a-new-message).
 
-Use default execution when the model needs the answer to continue. Use background execution when
-the conversation should continue while the task is pending. Background tools need no root-agent
-flag. `defineTool` does not accept background execution. See the
-[tool execution comparison](/docs/tools#background-execution).
+To keep the conversation going while a call works, [define `task` instead](#run-calls-as-tasks-task).
+
+`defineWorkflowTool` does not accept an `execution` option. Passing one throws
+`"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.`
 
 ### How suspension works
 
@@ -201,15 +228,157 @@ async *execute(input, ctx) {
 ```
 
 The yield reports a snapshot, and eve advances the generator to `ctx.ask`. Awaiting the unanswered
-request is the durable wait. In default execution, the original tool call remains pending until
-the answer arrives and the body returns. With `execution: "background"`, the original call has
-already returned a task receipt, and the workflow can suspend while the conversation continues.
-Answering resumes the body in either mode.
+request is the durable wait. The original tool call remains pending until the answer arrives and
+the body returns.
 
-`yield` itself does not wait for approval or switch a tool into background execution. An ordinary
+`yield` itself does not wait for approval. An ordinary
 Promise or Node.js timer inside a step also does not create a durable workflow suspension; use
 the workflow operations for waits that must survive a restart.
 
+## Run calls as tasks: `task`
+
+Define `task(input, ctx)` in place of `execute` when the conversation should continue while a call
+works, such as a twenty-minute deploy or research the model may not need right away. An `execute`
+tool holds the conversation until each call settles, however long it runs. A question, a sleep, or
+an approval inside an `execute` call already parks durably and holds no compute, so waiting alone
+doesn't need a task.
+
+```ts title="agent/tools/deploy.ts"
+import { defineWorkflowTool } from "eve/tools";
+import { z } from "zod";
+import { runDeploy } from "../lib/deploy";
+
+export default defineWorkflowTool({
+  description: "Deploy a service.",
+  inputSchema: z.object({ service: z.string() }),
+  async task({ service }, ctx) {
+    "use workflow";
+    return await runDeploy(service, ctx.abortSignal);
+  },
+});
+```
+
+A `task` body is written like an `execute` body, with the same `WorkflowToolContext`: returning
+settles the call, a throw fails it, and an `async *task` generator can `yield` progress. A
+steering message never aborts a task's `abortSignal`.
+
+Each call is a task with its own id, `<tool>-<6 characters>`:
+
+- **Receipt:** the call's tool result is a receipt, such as
+  `Started task deploy-4hd8sa. Its result will arrive in a <task_result> message.`, and the model
+  continues at once.
+- **Result:** the body's return value or its error arrives later as a `<task_result>` block in a
+  `task.result` message, which eve appends at the next step boundary. `toModelOutput` projects the
+  result, not the receipt.
+
+The model waits for results with `task_wait` and stops a task with `task_cancel`, and a turn can't
+end while tasks are working. `task_cancel`, `session.cancel()`, a failed turn, and the
+end of the session abort the call's `abortSignal`; the run waits up to 30 seconds for the body to
+finish unwinding, then ends as cancelled. See [Tasks](/docs/tools/tasks) for what the model sees,
+how held turns look on the stream, steering, events, and limits.
+
+## Resumable tasks: `serve`
+
+Define `serve(receive, ctx)` when the model should be able to send a running task more input, such
+as a revision request. A `serve` body runs once per task and gets its calls from `receive()`
+instead of taking an input:
+
+```ts title="agent/tools/release-plan.ts"
+import { defineWorkflowTool } from "eve/tools";
+import { z } from "zod";
+import { revise, type Plan } from "../lib/release-plan";
+
+export default defineWorkflowTool({
+  description: "Draft a release plan and revise it on request.",
+  inputSchema: z.object({ request: z.string() }),
+  async serve(receive, ctx) {
+    "use workflow";
+    let plan: Plan | undefined;
+    for (;;) {
+      const { input, abortSignal } = await receive(); // the first call, then each by taskId
+      try {
+        plan = await revise(plan, input.request, { signal: abortSignal });
+        ctx.reply(plan); // a result; the task stays available
+      } catch (error) {
+        if (!abortSignal.aborted) throw error; // cancelled: wait for the next call
+      }
+    }
+  },
+});
+```
+
+A `serve` tool's calls are tasks, with the receipts and results
+[described above](#run-calls-as-tasks-task) and the waiting, turn rule, ownership, and limit
+described in [Tasks](/docs/tools/tasks). What differs:
+
+- **`receive()`:** resolves with the next call, `{ input, callId, abortSignal }`, with `input`
+  validated by `inputSchema`. The first `receive()` resolves at once with the call that started
+  the task, without a step or a durable wait, and replays deterministically. After that, it
+  resolves with each call made with the task's `taskId`, in arrival order. Calls that arrive while
+  the body isn't waiting are kept. A pending `receive()` is shared, so calling it again returns the
+  same promise. A call counts as received as soon as its promise resolves, even if that promise
+  lost a `Promise.race`, and the next `ctx.reply()` settles it. If you race `receive()`, keep its
+  promise until you read the call instead of calling `receive()` again.
+- **`taskId` on the model input:** eve adds an optional `taskId` to the tool's model input and
+  appends a sentence explaining it to the description. A call without `taskId` starts a new task,
+  whose receipt names it and ends with
+  `To send it another message, call release-plan again with taskId release-plan-7k2m9q.` A call
+  with `taskId` goes to that task and returns a receipt that starts
+  `Sent to task release-plan-7k2m9q.` The build fails if `inputSchema` declares its own
+  `taskId`.
+- **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
+  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
+  in a step use the current call's auth. `ctx.agents` lists the
+  agents the current call may open, including dynamic agents selected in its turn.
+- **Body state spans callers:** variables the body keeps between calls, such as `plan` in the
+  example, may hold what an earlier call from another caller produced. Key per-caller data on
+  the whole principal in `ctx.session.auth.current`: `authenticator`, `issuer`, `principalType`,
+  and `principalId` together, because a `principalId` is unique only within its authenticator and
+  issuer. Anonymous callers, whose `current` is `null` or whose `principalType` is `"anonymous"`,
+  share one identity, so don't keep per-person data for them. Any caller in the session can
+  continue or cancel the task; see [Tasks](/docs/tools/tasks#ownership-and-limits).
+- **Agents belong to the call that opened them:** a session the body opens with `ctx.agent` while
+  serving a call is that call's child. Its `session.parent` names the call's `callId` and turn, and
+  its trace continues from the call's tool span. The session keeps that lineage for its later
+  messages, even after the task receives another call. Auth belongs to each message instead: a
+  message carries the auth of the call being served when it's sent.
+- **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
+  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
+  their `abortSignal`, so work the body continues after replying keeps running.
+  Returning settles the calls still waiting and ends the task; a throw fails them. `serve` is not
+  a generator, so it can't `yield` progress.
+- **Working and idle:** a resumable task is working while one of its calls has no result, and idle
+  otherwise. An idle task doesn't hold the turn and doesn't count toward the limit of 32; a call
+  that makes it work again does. The `[Tasks]` note lists the 10 most recently used idle tasks
+  after the working ones, so the model can find them again.
+- **One `abortSignal` per stretch of work:** a stretch starts when a call reaches an idle task and
+  ends when a reply or a cancel settles its calls. Calls that arrive during a stretch share its
+  signal, and the next stretch gets a new one, so a task can be cancelled any number of times.
+- **Cancellation:** `task_cancel`, `session.cancel()`, and a failed turn settle the task's waiting
+  calls as `cancelled` and abort the stretch's `abortSignal`. The run keeps waiting for more calls,
+  so the task becomes idle and stays available. `task_cancel` on an idle task says the task had no
+  work to stop. To stay available, a body must catch its stretch's abort and
+  return to `receive()`, as the example does; an abort that escapes the body finishes the task. A
+  body that ignores the signal keeps working and its reply is dropped, but a body that doesn't
+  return to `receive()` within 30 seconds of a cancel ends, and the task finishes.
+- **Finishing:** the task finishes when its body returns or throws, or when the session ends,
+  which aborts the current stretch's signal and rejects a pending `receive()`.
+
+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.
+
 ## Authorize inside a step
 
 Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there. User-scoped providers
@@ -233,7 +402,7 @@ async function readRepository(ctx: WorkflowStepToolContext, repository: string)
 }
 ```
 
-Connections discovered through `connection_search`, ordinary tools, and workflow steps use the same
+Connection tools called through `connection_execute`, ordinary tools, and workflow steps use the same
 authorization machinery for requester identity, token caching, callback completion, and rejection
 after sign-in. The execution runtime owns the wait: an agent returns to its model after authorization,
 while a workflow retries the interrupted step and continues the authored body.
@@ -260,27 +429,23 @@ code. If that code later fails and the step retries, eve reads the token from th
 of exchanging the same callback again. The provider must persist the grant or token; the marker
 itself contains no credentials.
 
-A background task becomes `input_required` during sign-in. The callback resumes that task; it does
-not rely on the launching agent turn still being active. Cancelling an authorization wait withdraws
-its callback. Cancellation uses the existing turn or task cancellation path rather than a separate
-authorization completion event.
-
-Background workflow authorization requires a new session after upgrading. In older sessions,
-`ctx.getToken` and `ctx.requireAuth` fail immediately with an instruction to start a new session.
-Blocking workflows and background workflows without auth are unaffected.
+Cancelling an authorization wait withdraws its callback. Cancellation uses the existing turn
+cancellation path rather than a separate authorization completion event.
 
 ## Ask a human: `ctx.ask`
 
 ```ts
-const answer = await ctx.ask({
-  prompt: string,
-  display?: "confirmation" | "select" | "text",
-  options?: { id: string; label: string; description?: string; style?: "primary" | "danger" | "default" }[],
-  allowFreeform?: boolean,
-  dismissible?: boolean,
-});
+const answer = await ctx.ask(
+  {
+    prompt: string,
+    display?: "confirmation" | "select" | "text",
+    options?: { id: string; label: string; description?: string; style?: "primary" | "danger" | "default" }[],
+    allowFreeform?: boolean,
+  },
+  { signal?: AbortSignal },
+);
 // | { status: "answered"; optionId?: string; text?: string }
-// | { status: "dismissed" }
+// | { status: "cancelled" }
 // | { status: "unavailable" }
 ```
 
@@ -291,14 +456,16 @@ The `ask_question` tool is a workflow tool built on `ctx.ask`.
 The answer's `status` tells the body what happened:
 
 - `answered`: the person picked an option (`optionId`) or typed a reply (`text`).
-- `dismissed`: the request set `dismissible: true` and the person sent a message that did not answer
-  it. The message reaches the agent as a normal turn. Only blocking tools can be dismissed this way.
+- `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.
 - `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.
 
 A plain follow-up message answers the request when it is the only pending question and the message
-matches an option or the request allows free text. This applies to blocking tools only: answer a
-question from a background tool or a subagent with a structured response.
+matches an option or the request allows free text. Answer a question from a subagent with a
+structured response.
 
 `ctx.ask` composes with the SDK's own constructs; race it against a deadline:
 
@@ -308,8 +475,8 @@ const answer = await Promise.race([pending, sleep("4h")]);
 if (answer === undefined) return { deployed: false, reason: "timed out" };
 ```
 
-- The request belongs to the run, not the turn. It stays answerable until it is answered, dismissed,
-  or the run ends. In a background tool that means long after the turn that started it.
+- The request belongs to the run, not the turn. It stays answerable until it is answered, withdrawn,
+  or the run ends.
 - A request is answered once. Ask again for the next answer.
 - Choose option `id`s that read well on their own, such as `approve` or the option's label. A
   response carries only the `id`. If a person answers after the request has already resolved, for
@@ -317,31 +484,71 @@ if (answer === undefined) return { deployed: false, reason: "timed out" };
 - Ending the run, by returning, throwing, or cancellation, withdraws its pending requests.
 - Several requests may be outstanding at once.
 - A response never steers. A new human message that does not answer a pending request follows the
-  session's normal `turnPolicy`.
+  session's normal `turnPolicy`. A steering message aborts the `abortSignal` of each `execute` call
+  the turn waits on, which withdraws that call's questions, such as `ask_question`'s. A task's
+  questions stay open.
+- An aborted `signal` asks the session to withdraw the question, and the session decides. If a
+  person's answer reached the session first, the ask resolves as `answered` even though the signal
+  aborted, and the channel shows it answered. Branch on `status`, not on the signal.
 
 Compare the [`approval`](/docs/human-in-the-loop) policy, which gates the call before `execute` runs
 and can only show the model's input. Both compose: `approval` before the run, `ctx.ask` inside it.
 
 ## Delegate work: `ctx.agent`
 
-Workflow tools can call a subagent and wait for its result:
+`ctx.agent(name)` returns a session with an agent, shaped like the TypeScript client's session. The
+session opens on its first `send`, and each `response.result()` resolves when that message's turn
+ends:
 
 ```ts
-const result = await ctx.agent("reviewer", {
-  message: "Review the deployment plan for security risks.",
-  outputSchema: {
-    type: "object",
-    properties: {
-      findings: { type: "array", items: { type: "string" } },
-    },
-    required: ["findings"],
-  },
+import { z } from "zod";
+
+const reviewer = ctx.agent("reviewer");
+const response = await reviewer.send("Review the deployment plan for security risks.", {
+  outputSchema: z.object({ findings: z.array(z.string()) }),
+  signal: ctx.abortSignal,
 });
+const { data, message, status } = await response.result();
 ```
 
-The first argument is an available agent target. On the root agent, `"agent"` starts or continues a copy of the root agent. A declared subagent uses its path-derived name and remains callable when hidden with `tool: false` or `disableTool()`. Delegated root copies and declared subagent contexts do not expose the built-in root-copy target. The invocation name `agent` is reserved, so a declared subagent cannot shadow it. eve assigns each call a replay-stable invocation identity, including repeated and parallel calls to the same target. Pass `agentId` to
-continue an existing child. An inline `outputSchema` requires structured output and determines the
-return type, so `result` in the example is typed as `{ findings: string[] }`.
+The name is an available agent target. On the root agent, `"agent"` starts a copy of the root agent.
+A declared subagent uses its path-derived name and remains callable when hidden with `tool: false`
+or `disableTool()`. Delegated root copies and declared subagent contexts do not expose the built-in
+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:
+
+| Option         | Description                                                                                              |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `outputSchema` | Structured output for the turn, as a Standard JSON Schema such as a Zod schema, or a JSON Schema object. |
+| `signal`       | Aborting it cancels the turn the message started or joined. The turn still reports, as cancelled.        |
+
+A message sent while the session's turn is running joins that turn, and its response resolves with
+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:
+
+| 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"`.                                                                                                                            |
+
+Every `ctx.agent(name)` call returns a new session that only the workflow run can address. The model
+does not see it; it sees what the tool returns. The session runs as the caller's principal with the
+caller's capabilities, and a person answers its 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.
 
 ### Route to a hidden subagent with Jev
 
@@ -422,14 +629,17 @@ export default defineWorkflowTool({
       ctx.abortSignal,
     );
 
-    return ctx.agent(target, { message: task });
+    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;
   },
 });
 ```
 
-The evaluation runs in a step so workflow replay records its result instead of making the routing request again. The parent model receives `agent-router`, but not `researcher` or `operator`. Jev returns the typed `"researcher" | "operator"` choice, and the selected subagent's result becomes the `agent-router` tool result.
+The evaluation runs in a step so workflow replay records its result instead of making the routing request again. The parent model receives `agent-router`, but not `researcher` or `operator`. Jev returns the typed `"researcher" | "operator"` choice, and the selected subagent's reply becomes the `agent-router` tool result.
 
-`ctx.agents` is a replay-stable metadata snapshot taken when the workflow starts. In a top-level root workflow, `ctx.agents.agent` always represents the root-copy target and carries the root's authored `description` when provided. The snapshot also includes declared agents hidden from the parent model with `tool: false` or `disableTool()`, but exposes no model definitions, credentials, or callbacks. A delegated root copy omits `agent`, so `agentRouter()` cannot select another root copy recursively. Invocation still checks each target's availability through `ctx.agent()`.
+`ctx.agents` is a replay-stable metadata snapshot taken when the session admits the call. In a `serve` task, it follows the call being served. In a top-level root workflow, `ctx.agents.agent` always represents the root-copy target and carries the root's authored `description` when provided. The snapshot also includes declared agents hidden from the parent model with `tool: false` or `disableTool()`, but exposes no model definitions, credentials, or callbacks. A delegated root copy omits `agent`, so `agentRouter()` cannot select another root copy recursively. Invocation still checks each target's availability through `ctx.agent()`.
 
 #### Route across every agent target
 
@@ -441,7 +651,8 @@ import { agentRouter } from "eve/tools/agent-router";
 export default agentRouter();
 ```
 
-Its input is `{ message: string }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to Jev, then invokes the selected name through `ctx.agent()`. It invokes a sole target without evaluation. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
+Its input is `{ message: string }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to Jev, then sends the message to a new session with the selected agent through `ctx.agent()` and returns its reply. It invokes a sole target without evaluation. Each call
+runs as a [task](#run-calls-as-tasks-task), so the reply reaches the model as the task's result. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
 
 When an authored tool accepts a JSON Schema supplied by the model, represent that input with a permissive object such as `z.looseObject({})`. Avoid `z.record(z.string(), z.json())`: its generated JSON Schema uses `propertyNames`, which OpenAI does not support. Validate the supplied value at the point where your tool consumes it.
 
@@ -449,23 +660,21 @@ This pattern controls specialist selection, not whether the parent model delegat
 
 ## Report progress: `yield`
 
-A workflow body may be an async generator. In default execution, yields report progress.
-Background execution consumes yielded values without publishing them or retaining a task-progress
-stream. After processing a yield, eve advances the generator; use an awaited workflow operation
-when the body needs to suspend.
+A workflow body may be an async generator whose yields report progress. After processing a yield,
+eve advances the generator; use an awaited workflow operation when the body needs to suspend.
 
-| Operation       | Default execution                                                 | `execution: "background"`                                                         |
-| --------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `yield value`   | Emits an `action.partial` snapshot for the pending tool call.     | Consumes the value without publishing progress or requesting a parent-agent turn. |
-| `return value`  | Settles the tool call with its output.                            | Completes the task and contributes to its cohort's terminal report.               |
-| No return value | Uses the last yield as output, or `null` if there were no yields. | Completes with `null`; yielded progress is not the task output.                   |
+| Operation       | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `yield value`   | Emits an `action.partial` 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. |
 
-For default execution, an explicit `return null` also falls back to the last yield. Prefer an
+An explicit `return null` also falls back to the last yield. Prefer an
 explicit object return when progress snapshots and the final result have different shapes.
 Progress snapshots are last-write-wins by tool call id and do not enter model history as
 intermediate tool results. A snapshot used as the final output does enter history as the tool result.
 
-This background workflow consumes an intermediate yield, then suspends until its timer expires:
+This workflow reports progress, then suspends until its timer expires:
 
 ```ts title="agent/tools/remind_with_progress.ts"
 import { defineWorkflowTool } from "eve/tools";
@@ -475,27 +684,25 @@ import { z } from "zod";
 export default defineWorkflowTool({
   description: "Schedule a reminder.",
   inputSchema: z.object({ note: z.string(), delay: z.string() }),
-  execution: "background",
   async *execute({ note, delay }) {
     "use workflow";
-    yield { status: "preparing reminder" }; // Consumed without publishing progress in background mode.
+    yield { status: "preparing reminder" }; // Published as progress for the pending call.
     await sleep(delay); // Durable suspension while the timer is pending.
-    return { reminder: note }; // Task completion notification.
+    return { reminder: note }; // The tool result.
   },
 });
 ```
 
-Use [`ctx.ask`](#ask-a-human-ctxask) when the workflow needs a human answer. Removing
-`execution: "background"` makes the yield visible as progress and keeps the durable sleep; the model
-waits for the final reminder as the tool result. See [yield and return](/docs/tools#yield-and-return) for the
-final-output rules.
+Use [`ctx.ask`](#ask-a-human-ctxask) when the workflow needs a human answer. See
+[yield and return](/docs/tools#yield-and-return) for the final-output rules.
 
 ## Cancel and clean up: `ctx.abortSignal`
 
-`ctx.abortSignal` aborts when the run is cancelled: explicit turn cancellation for a waiting tool, `task_cancel`
-or the session ending for a background one. 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`:
+`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:
+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`:
 
 ```ts
 async execute({ projectId }, ctx) {
@@ -509,22 +716,58 @@ async execute({ projectId }, ctx) {
 }
 ```
 
-After the signal fires, the run waits up to 30 seconds for the body to finish unwinding, then ends
-as cancelled whether or not it did. A body parked on a hook or a `sleep` does not observe the signal;
-it is abandoned when the grace period ends. Steps that received the signal are how you clean up
-first.
+After a cancel aborts the signal, the run waits up to 30 seconds for the body to finish unwinding,
+then ends as cancelled whether or not it did. A body parked on a hook or a `sleep` does not observe
+the signal; it is abandoned when the grace period ends. Steps that received the signal are how you
+clean up first.
 
 The caller waits up to 35 seconds for a cooperatively cancelled run to settle before forcing it
-to stop. This includes time for the run to publish its outcome after body cleanup. A background
-task records its cancelled status before cleanup finishes, so that status alone does not mean
-its work has stopped.
+to stop. This includes time for the run to publish its outcome after body cleanup.
+
+## Stop early for a new message
+
+A steering message aborts the `ctx.abortSignal` of each `execute` call the turn waits on. A
+steering message is one sent with `turnPolicy: "steer"`, the default, that does not answer a pending
+question; a message that answers a question never stops a call. Steering never touches a
+[task](#run-calls-as-tasks-task).
+
+Steering does not cancel the call or end the turn. The call settles with what the body returns, and
+the model reads the new message after the step's workflow tool calls settle:
+
+- **Questions:** a pending `ctx.ask` question is withdrawn and resolves as `cancelled`, unless a
+  person's answer reached the session first.
+- **Rejections:** a body that rejects after the abort, such as one whose step received the signal,
+  settles as `{ interrupted: true }` instead of failing.
+- **No grace period:** a body that doesn't observe the signal, such as one parked on a hook or a
+  `sleep`, keeps the turn waiting until it finishes.
+
+The body doesn't need to tell a steering message from a cancel: in both cases, stop and return what
+you have. After a cancel, eve discards the result. The provided `sleep` tool races its timer
+against the signal:
+
+```ts
+import { sleep } from "workflow";
+
+async execute(input, ctx) {
+  "use workflow";
+  const stopped = new Promise<"stopped">((resolve) =>
+    ctx.abortSignal.addEventListener("abort", () => resolve("stopped"), { once: true }),
+  );
+  const elapsed = sleep(input.seconds * 1_000).then(() => "elapsed" as const);
+  const woke = await Promise.race([elapsed, stopped]);
+  return woke === "elapsed" ? { waitedSeconds: input.seconds } : { interrupted: true };
+}
+```
+
+To keep a question or long work going while the conversation continues, define
+[`task`](#run-calls-as-tasks-task) instead of `execute`.
 
 ## Workflow tool examples
 
 ### Approve with a deadline and an escalation
 
 ```ts
-async execute({ service }, ctx) {
+async task({ service }, ctx) {
   "use workflow";
   const plan = await planDeploy(service);
   const pending = ctx.ask({ prompt: `Deploy ${service}?`, display: "confirmation", options: APPROVE_OR_CANCEL });
@@ -543,8 +786,9 @@ async execute({ service }, ctx) {
 }
 ```
 
-One request stays on the channel the whole time. `sleep` is the deadline, `pageOnCall` is a step,
-and returning withdraws the request.
+One request stays on the channel the whole time. As a `task`, the call doesn't hold the
+conversation, and a steering message doesn't withdraw the request. `sleep` is the deadline,
+`pageOnCall` is a step, and returning withdraws the request.
 
 ### Wait for an external system to call back
 
@@ -585,7 +829,6 @@ import { issueRefund } from "../lib/refunds";
 export default defineWorkflowTool({
   description: "Request approval to refund an order, then issue the refund once approved.",
   inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
-  execution: "background",
   async execute({ orderId, amount }, ctx) {
     "use workflow";
     const decision = await ctx.ask({
@@ -605,58 +848,29 @@ export default defineWorkflowTool({
 });
 ```
 
-The model reports that approval is pending and the conversation continues. The approval card stays
-on the channel. When it is answered, the refund runs and the agent is woken with the outcome.
-
-### Remind me later
-
-```ts title="agent/tools/remind.ts"
-import { defineWorkflowTool } from "eve/tools";
-import { sleep } from "workflow";
-import { z } from "zod";
-
-export default defineWorkflowTool({
-  description: "Remind the user about something after a delay.",
-  inputSchema: z.object({ note: z.string(), delay: z.string() }),
-  execution: "background",
-  async execute({ note, delay }) {
-    "use workflow";
-    await sleep(delay);
-    return { reminder: note };
-  },
-});
-```
-
-The session parks between the receipt and the wake. The agent receives the return value and relays
-it.
+The turn parks while the approval card stays on the channel. When it is answered, the refund runs
+and the agent receives the outcome as the tool result.
 
 ## Semantics
 
-One call, one result. A waiting tool's call resolves once, with the return value, the error, or a
-cancellation. A background tool's call resolves once, with the receipt. Its terminal outcome arrives
-in one automatic report after every task in its cohort is terminal. A cohort includes overlapping
-background work in the same session, including tasks launched in later user turns while earlier
-work remains open.
-
-While a waiting tool runs, the turn is parked. A `queue` message waits for it. A `steer` message
-cancels the turn, which cancels the run, which withdraws its requests. Input responses never steer.
-
-Background runs belong to the session. They survive turn completion and cancellation, appear in the
-session's task index, can be cancelled with `task_cancel`, and are cancelled when the session ends.
+One call, one result. A workflow tool call resolves once, with the return value, the error, or a
+cancellation.
 
-The parent session records each background task's outcome when it processes the child's notification.
-The first terminal outcome it records is final: a late child result cannot replace a recorded
-cancellation. Task completion does not require the wrapper workflow to have exited.
+While an `execute` call runs, the turn is parked. A `queue` message waits for it. A `steer` message
+that answers no pending question aborts the call's `ctx.abortSignal` and reaches the model once the
+call settles; it never cancels the run. Input responses never steer. A task doesn't park the
+turn, and steering never touches it.
 
 Errors follow the SDK. A thrown error in a step retries per the step's policy; `FatalError` does
 not. An error that escapes the body fails the tool invocation.
 
-Starting a waiting workflow tool can also be retried. If dispatch is interrupted after starting a
+Starting a workflow tool can also be retried. If dispatch is interrupted after starting a
 run, its retry starts another run, and both may execute. The parent tracks the run returned by the
 successful dispatch attempt. Use an application idempotency key for side effects that must happen
 only once.
 
-The workflow id derives from the executor's module path and function name. Inline executors use
-the tool module and the name `execute`; imported executors use their declaring module and name.
+The workflow id derives from the entry point's module path and function name. Inline entry points
+use the tool module and the name `execute`, `task`, or `serve`; imported ones use their declaring module and
+name.
 Renaming or moving that function creates a new workflow. Runs in flight finish on the deployment that started them; a run that
 resumes on a deployment without its tool fails with an error naming the missing workflow.