eve 0.74.0 → 0.75.0

package/docs/guides/frontend/nextjs.mdx

@@ -11,21 +11,34 @@ Use this integration when Next.js owns the application's development and deploym
 
 - The `eve` package installed in your project (`npm install eve@latest`).
 - An existing eve agent directory. If you don't have one, start from [Getting Started](../../getting-started).
-- A Next.js app, or a single-agent project where you want to generate one below.
+- A Next.js app, or an eve project where you want to generate one below.
 
 ## Add the generated Web Chat app
 
-For a single-agent project, install the generated Next.js Web Chat app:
+Install the generated Next.js Web Chat app from a standalone agent project:
 
 ```bash
 eve add channel/web
 ```
 
-The installer adds a Next.js application and wraps `next.config.ts` with `withEve()`. The generated chat calls the unnamed agent through same-origin `/eve/v1/*` routes.
+For an agent workspace, select the member the chat should call:
+
+```bash
+eve add channel/web --agent support
+```
+
+The installer configures the chat for the selected agent. By default, it adds a shared Next.js
+application under `apps/web`; if a root Web Chat app already exists, it configures that app instead.
+For Next.js hosting, the installer wraps `next.config.ts` with `withEve()`. When setting up a new
+app, choose **Next.js** to host the integration. The generated chat uses same-origin `/eve/v1/*`
+routes for a standalone agent or `/eve/<name>/v1/*` routes for a workspace member. Running the
+installer from a workspace root without selecting a member is not supported.
 
 Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).
 
-The Web Chat installer does not support eve agent workspaces. If you want Next.js to host the integration, create a root Next.js application and follow the steps below; `withEve(nextConfig)` discovers workspace members but does not generate a chat UI. To keep the frontend as a peer application instead, follow the [workspace layout guidance](/docs/concepts/project-structure#configure-a-web-deployment).
+To integrate an existing Next.js application without generating a chat UI, follow the steps below.
+To deploy the frontend and agents as separate Vercel services, choose **Vercel services** during
+setup instead; see the [workspace layout guidance](/docs/concepts/project-structure#configure-a-web-deployment).
 
 ## Wrap the Next.js config
 

package/docs/sandbox/index.mdx

@@ -182,6 +182,10 @@ export const AcmeSandbox = defineSandboxProvider<
     const client = createAcmeClient(options);
 
     return {
+      async onSessionEnd(_ctx, _artifact, state, { reason }) {
+        await client.delete({ id: state.remoteId, reason });
+      },
+
       async prepare(ctx) {
         const temporary = await client.createTemporary({
           files: await ctx.files.list(),
@@ -213,7 +217,11 @@ export const AcmeSandbox = defineSandboxProvider<
 });
 ```
 
-`prepare()` returns the complete JSON-serializable artifact. Core calls `start()` once for a new durable sandbox session and persists its minimal JSON-compatible state. Process restarts call `resume()` with only the current context, that state, and the target deployment's exact artifact. Provider handles implement `onSessionStop()`, `onRuntimeShutdown()`, and `onSessionDelete()`.
+`prepare()` returns the complete JSON-serializable artifact. Core calls `start()` once for a new durable sandbox session and persists its minimal JSON-compatible state. Process restarts call `resume()` with only the current context, that state, and the target deployment's exact artifact.
+
+`onSessionEnd()` is invoked when the durable session reaches a completed, expired, or failed terminal outcome. It receives the exact prepared artifact, persisted provider state, and a `reason` of `"completed"`, `"expired"`, or `"failed"`. Implement idempotent permanent cleanup from those values rather than depending on a live handle. eve retries the cleanup step and logs an exhausted failure without replacing the session's terminal outcome. A session that never opened a sandbox and a child that borrows its parent's sandbox do not call the hook.
+
+Provider handles implement `onSandboxStop()`, `onRuntimeShutdown()`, and `onSandboxDelete()`. These handle-level methods cover authored stop or delete calls, process shutdown, and failed initialization; `onSessionEnd()` is the single provider hook for durable terminal session cleanup.
 
 Open options belong to `start()` and are not serialized or passed to `resume()`. A provider must put any immutable option-derived data needed for reconnection in its session state. With the current immutable-state contract, `resume()` reconnects existing native state and fails if it is gone rather than recreating callback side effects. A custom provider may define start-only callback fields, but built-in providers initialize the sandbox in `defineSandbox()` after `open()`.
 
@@ -231,7 +239,7 @@ Preparation discovers authored files through `ctx.files`; core keeps project lay
 
 ## Lifecycle
 
-Session-owned sandboxes persist across turns and deployments while their provider state remains available. `sandbox.stop()` stops compute without deleting persisted state; a later access resumes that state directly. `sandbox.delete()` clears provider state, so the next `ctx.getSandbox()` reruns the selector and starts a fresh sandbox from the current environment.
+Session-owned sandboxes persist across turns and deployments while their provider state remains available. `sandbox.stop()` stops compute without deleting persisted state; a later access resumes that state directly. `sandbox.delete()` clears provider state, so the next `ctx.getSandbox()` reruns the selector and starts a fresh sandbox from the current environment. When the durable session reaches a terminal outcome, eve calls the provider's `onSessionEnd()` hook to release any remaining session-owned resources.
 
 Changing sandbox source, preparation code, Dockerfile content, environment options, workspace resources, or skills produces a new environment generation. Existing durable sessions retain their recorded sandbox state; new sessions use the current generation.
 

package/docs/subagents/index.mdx

@@ -229,7 +229,7 @@ By default, a subagent named `researcher` collides with an authored tool named `
 
 Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 
-Each delegated subagent spins up its own child session and stream. The parent stream carries the call's `task.started` and `task.settled` events, `agent.started` when the child session opens, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. The parent emits `input.resolved` when it routes an answer back down to the descendant that asked. `task.settled` carries the child's reply as `output` when the call completes, or `error.message` when it fails, along with the same tool `name` and `kind: "agent"` as the call's `task.started`. To follow the child's other progress, pass the `agent.started` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent and follow the child with `stream()`. It reads `agent.started.data.streamPath`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
+Each delegated subagent spins up its own child session and stream. The parent stream carries the call's `task.started` and `task.settled` events, `agent.started` when the child session opens, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. The parent emits `input.resolved` when it routes an answer back down to the descendant that asked. A tool approval is the exception: the descendant decides it, since its response policy can refuse the person who answered, so the approval stays open on the parent until the descendant settles or resolves it. The parent relays the descendant's `approval.settled` and `input.resolved` for it. On text-only channels, a typed reply that matches an option of the first open prompt, such as `approve` for a tool approval or `continue` for a session limit, answers it as the person who typed it, so a person answers several proxied prompts one message at a time. `task.settled` carries the child's reply as `output` when the call completes, or `error.message` when it fails, along with the same tool `name` and `kind: "agent"` as the call's `task.started`. To follow the child's other progress, pass the `agent.started` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent and follow the child with `stream()`. It reads `agent.started.data.streamPath`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
 
 `agent.started` carries the `callId` and `turnId` of the call that opened the session, the call's `taskId`, the agent `name`, and the child's `sessionId`. Later calls with the same `taskId` reach the same session and do not announce it again, so match a child to its calls by `taskId`. A session an authored workflow tool opens with `ctx.agent` is announced the same way, with its `taskId` only when the workflow tool call runs as a task.
 

package/docs/tools/human-in-the-loop.md

@@ -219,7 +219,7 @@ Approvals and questions share one protocol:
 3. The run parks durably, for as long as it takes. The turn stays open: the stream emits `turn.waiting`, and after the answer the turn resumes under the same `turnId`. That `turn.waiting` carries `on: "input"`, since a person must act.
 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 first open request, as described in [Several requests at once](#several-requests-at-once). 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.
+For `ctx.ask()` questions from tools and prompts proxied from subagents, a follow-up message answers the first open request, as described in [Several requests at once](#several-requests-at-once). 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.
 
 Each request includes a `kind` discriminator: `tool-approval`, `question`, or
 `session-limit`. Clients should use `kind` to choose behavior and presentation.

package/docs/tools/overview.mdx

@@ -176,8 +176,8 @@ receive only the projected text.
 
 ### Durable waits
 
-Every tool call finishes before its turn continues. The definition decides whether the executor
-can wait durably while the call is pending:
+A tool call with an `execute` entry point finishes before the model continues. The definition
+decides whether the executor can wait durably while the call is pending:
 
 | Definition           | Durable waits inside `execute`                           | Result delivered to the model      |
 | -------------------- | -------------------------------------------------------- | ---------------------------------- |
@@ -191,11 +191,15 @@ the call returns a receipt at once, and the workflow's output reaches the model
 [resumable task](/docs/tools/workflows#resumable-tasks-serve), which the model can send more calls
 by its `taskId`.
 
+Built-in, declared local, and remote subagent tools run as resumable tasks: each call returns a
+receipt at once, and the child's reply reaches the model later in a `task.result` message.
+Inside an authored workflow, awaiting a [`ctx.agent` session's `response.result()`](/docs/tools/workflows#delegate-work-ctxagent)
+waits for the child's turn to end instead.
+
 The `TaskExec` argument and `task.postMessage` have been removed. Return the result. In a workflow
 body, keep values needed after a wait in local variables; workflow replay reconstructs them across
 durable waits. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an
-answer from the human. Built-in, declared local, and remote subagent calls also block: each call
-returns the child's reply as its tool result.
+answer from the human.
 
 ### Yield and return
 

package/docs/tools/workflows.mdx

@@ -347,10 +347,14 @@ described in [Tasks](/docs/tools/tasks). What differs:
   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.
+  serving a call is that call's child. Its `session.parent` names the call's `callId` and turn.
+  The first turn of a local child uses the call's tool span as its parent when trace context is
+  available. A remote child starts its own trace; its first turn links to the call's tool span
+  with `eve.link.type=agent.dispatch` when trace context is available. Later child turns start new
+  traces. Parent session lineage stays tied to the opening call, even after the task receives
+  another call; a remote receiver accepts that lineage only from a trusted forwarder. Each message
+  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
   then goes idle until its next call. A reply with
@@ -541,9 +545,13 @@ client's `MessageResult` fields, plus `error` when the turn failed:
 | `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.
+does not see it; it sees what the tool returns. A local child runs as the caller's principal with the
+caller's capabilities. A remote child does not inherit the caller's session principal by default;
+the receiving deployment determines its identity from the outbound request. To forward the caller's
+identity, set `forwardPrincipal: true` on the remote agent and configure the receiver's
+`trustedForwarders` (see [Forwarding the caller identity](../guides/remote-agents#forwarding-the-caller-identity)).
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [