eve 0.42.0 → 0.44.0

package/docs/getting-started.mdx

@@ -24,13 +24,7 @@ Run `eve init` with a project name:
 npx eve@latest init my-agent
 ```
 
-The command creates the project, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
-
-Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
-
-```bash
-npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
-```
+The command creates the project, installs dependencies, and initializes Git. After scaffolding, eve offers to start the development server or, if a supported coding agent is installed, to open the project in the coding agent.
 
 To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
 
@@ -40,15 +34,23 @@ npx eve@latest init .
 
 eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
 
+### Customize initialization
+
+To initialize the agent with a different AI Gateway model or reasoning effort, pass `--model` or `--reasoning`:
+
+```bash
+npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
+```
+
 ## Run the agent
 
-If the development server is not already running, start it from the project root:
+Choose **Start eve dev** after scaffolding, or run this from the project root:
 
 ```bash
 npm run dev
 ```
 
-The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command.
+This starts an interactive session where you can send messages to your agent.
 
 ## Project layout
 
@@ -56,7 +58,7 @@ eve builds an agent by walking the filesystem under `agent/`. Each directory is
 
 ### Naming from paths
 
-Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
+eve derives names from file paths, so you do not configure them separately.
 
 | Path                                  | Resolves to           |
 | ------------------------------------- | --------------------- |
@@ -65,7 +67,7 @@ Identity comes from the path. You never write a `name` or `id` field on a `defin
 | `agent/skills/summarize.md`           | skill `summarize`     |
 | `agent/subagents/researcher/agent.ts` | subagent `researcher` |
 
-The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory.
+The root agent uses its `package.json` `name`, or its app directory name if none is set. A subagent uses its directory name.
 
 ### Recommended layout
 
@@ -93,31 +95,29 @@ my-agent/
 
 Evals live beside `agent/`, not inside it.
 
-### Authored slots
-
-The Subagents column states whether a local subagent (`subagents/<id>/`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots.
-
-| Path                                                    | Description                               | Subagents | Notes                                                                                                                                                                             |
-| ------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent.ts`                                              | Runtime config                            | Yes       | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config).                                                                                 |
-| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Optional  | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents.         |
-| `instrumentation.ts`                                    | Telemetry config                          | No        | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only.                                                                                     |
-| `channels/`                                             | HTTP and messaging entry points           | No        | Root-only.                                                                                                                                                                        |
-| `connections/`                                          | External MCP and OpenAPI services         | Yes       | One connection per file; its name comes from the filename.                                                                                                                        |
-| `hooks/`                                                | Lifecycle and stream-event subscribers    | Yes       | Module-backed only. Recursive directories are supported.                                                                                                                          |
-| `skills/`                                               | On-demand procedures and capability packs | Yes       | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback.                         |
-| `lib/`                                                  | Shared authored helper code               | Yes       | Import-only; not mounted into the workspace.                                                                                                                                      |
-| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                | Yes       | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
-| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes       | Mirrored into `/workspace/` when a session starts.                                                                                                                                |
-| `tools/`                                                | Typed executable integrations             | Yes       | Module-backed only.                                                                                                                                                               |
-| `schedules/`                                            | Recurring jobs                            | No        | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only.                              |
-| `subagents/`                                            | Specialist child agents                   | Yes       | Each child is a local package under `subagents/<id>/`. Nested subagents are supported.                                                                                            |
-
-### Runtime files and source files
-
-eve does not mount the whole authored tree into the runtime sandbox. Files under `agent/sandbox/workspace/**` land in `/workspace/` when a session starts.
-
-Skill package files land outside the workspace under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback when `$HOME` is unavailable. Everything in `lib/` remains import-only source code.
+### Agent files and directories
+
+Each path under `agent/` has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked **Yes**.
+
+| Path                                                    | Use                                       | Available to subagents | Notes                                                                                                                                                                             |
+| ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts`                                              | Runtime config                            | Yes                    | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config).                                                                                 |
+| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Optional               | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents.         |
+| `instrumentation.ts`                                    | Telemetry config                          | No                     | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only.                                                                                     |
+| `channels/`                                             | HTTP and messaging entry points           | No                     | Root-only.                                                                                                                                                                        |
+| `connections/`                                          | External MCP and OpenAPI services         | Yes                    | One connection per file; its name comes from the filename.                                                                                                                        |
+| `hooks/`                                                | Lifecycle and stream-event subscribers    | Yes                    | Module-backed only. Recursive directories are supported.                                                                                                                          |
+| `skills/`                                               | On-demand procedures and capability packs | Yes                    | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback.                         |
+| `lib/`                                                  | Shared authored helper code               | Yes                    | Import-only; not mounted into the workspace.                                                                                                                                      |
+| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                | Yes                    | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
+| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes                    | Mirrored into `/workspace/` when a session starts.                                                                                                                                |
+| `tools/`                                                | Typed executable integrations             | Yes                    | Module-backed only.                                                                                                                                                               |
+| `schedules/`                                            | Recurring jobs                            | No                     | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only.                              |
+| `subagents/`                                            | Specialist child agents                   | Yes                    | Each child is a local package under `subagents/<id>/`. Nested subagents are supported.                                                                                            |
+
+### Files available in the sandbox
+
+Files under `agent/` define your agent; only files in `agent/sandbox/workspace/` are copied to `/workspace/` when a session starts.
 
 ### Local subagents
 

package/docs/guides/auth-and-route-protection.md

@@ -223,7 +223,7 @@ Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment va
 
 ## Accepting forwarded identity from another deployment
 
-A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) asserts its end user's principal on the create-session request as a `forwardedPrincipal` body field. By default every such assertion is rejected with `403` — accepting someone else's word for who the user is requires naming exactly which forwarders you trust. Do that with `trustedForwarders` on `eveChannel`:
+A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) asserts its end user's principal on create and continuation requests as a `forwardedPrincipal` body field. By default every such assertion is rejected with `403` — accepting someone else's word for who the user is requires naming exactly which forwarders you trust. Do that with `trustedForwarders` on `eveChannel`:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
@@ -239,7 +239,11 @@ export default eveChannel({
 
 The predicate authorizes the _forwarder_ (the verified route-auth principal — who is asserting), not the forwarded principal (what is asserted). Match it precisely: a permissive predicate like `() => true` lets any caller that passes route auth assert any principal, including preview deployments of your own project when `vercelOidc()` is in the walk. `trustedForwarders` exists only on your authored channel — the framework default channel never accepts a forwarded principal, so a receiving deployment must author `agent/channels/eve.ts`.
 
-When the predicate accepts, the forwarded principal replaces the session principal: `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly, so user-scoped connections, local subagents, and further `forwardPrincipal` hops all see that user. The forwarder is recorded on the accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller. The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+
+> ⚠️ Both deployments must support continuation forwarding before you resume persistent remote sessions. A create-only receiver rejects a forwarded continuation with HTTP 400; the sender does not fall back to service authority. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity) for the upgrade behavior.
+
+Persistent sessions do not preserve caller authority between turns. Every accepted follow-up replaces `auth.current`, including replacing it with no authenticated caller on internal local delivery; per-user connection lookup is then keyed from that current principal. This prevents a later caller from resolving a prior caller's OAuth grant. It does not hide the persistent session's conversation history or artifacts from a caller who is otherwise allowed to continue that session; session ownership remains an application policy.
 
 ## What reaches `ctx.session.auth`
 

package/docs/guides/dynamic-capabilities.md

@@ -132,7 +132,7 @@ approval checks.
 
 ## Dynamic tools
 
-Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. The wrapper stamps them so their `execute` functions survive workflow step boundaries.
+Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. eve records durable descriptors for `execute`, approval request and response policies, and `toModelOutput`, so a parked call can reconstruct the same callbacks in a fresh process.
 
 Dynamic tool executors receive the same `ToolContext` as static authored tools, including inline provider auth through `ctx.getToken(provider)` and `ctx.requireAuth(provider)`.
 
@@ -160,11 +160,13 @@ export default defineDynamic({
 });
 ```
 
-### Prefer an inline `execute` function
+### Author replayable callbacks
 
-Write `execute` as an inline function expression, arrow, or method shorthand placed directly as the property value. The bundler transform stores the function and its closure variables for durable replay without rerunning the resolver.
+Write callback properties as inline function expressions, arrows, method shorthand, or module-level function references. eve transforms authored modules that import `defineTool`, including helper modules outside `agent/tools/`, and stores each callback's referenced closure values independently.
 
-The transform does not detect `execute: myFn`, `execute: makeFn()`, or executors created inside an imported dependency. For a `session.started` tool, eve can reconstruct these live functions by rerunning the owning resolver after a durable resume. Keep session resolvers idempotent and avoid unnecessary side effects. A `turn.started` tool still requires an inline executor to survive a fresh runtime.
+Closure values must be JSON-serializable. Plain objects, arrays, strings, finite numbers, booleans, and `null` are supported; `undefined` object properties are omitted. Functions, class instances, `Date`, `Map`, symbols, non-finite numbers, and cyclic values fail resolution with the tool name and callback phase instead of being serialized lossily.
+
+Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve-provided factories may also supply pre-registered callbacks. eve rejects a dynamic tool if any present callback lacks durable metadata, and replay never reruns the current resolver to recover one.
 
 ### Naming
 
@@ -181,13 +183,13 @@ A dynamic tool or skill whose name matches an **authored** one **overrides** it
 
 ### Events
 
-| Event             | Resolver runs                              | Tools available for             |
-| ----------------- | ------------------------------------------ | ------------------------------- |
-| `session.started` | At session start; sometimes after a pause¹ | Every model call in the session |
-| `turn.started`    | Once per turn                              | Every model call in the turn    |
-| `step.started`    | Before each model call                     | That model call                 |
+| Event             | Resolver runs                                         | Tools available for             |
+| ----------------- | ----------------------------------------------------- | ------------------------------- |
+| `session.started` | At session start; may be redelivered during recovery¹ | Every model call in the session |
+| `turn.started`    | Once per turn                                         | Every model call in the turn    |
+| `step.started`    | Before each model call                                | That model call                 |
 
-¹ If a session pauses to wait for approval or other input, eve may run the resolver again when the session continues. Design session resolvers so they can safely run more than once. They do not run before every model call.
+¹ Workflow recovery can redeliver a resolver event, so keep resolvers idempotent. Replaying a parked callback does not depend on running the resolver again.
 
 ### Execution order
 

package/docs/guides/instrumentation.md

@@ -58,6 +58,8 @@ You are responsible for ensuring any observability or eval provider is approved
 
 The third configurable surface, [runtime context events](#runtime-context), attaches per-model-call values to these spans.
 
+Built-in messaging channels classify their instrumentation metadata with an `audience`: `public`, `private`, or `unknown`. Slack public channels and Chat SDK workspace-visible threads are public; direct and private conversations are private; platform surfaces without enough visibility evidence remain unknown.
+
 ## Channel delivery traces
 
 Instrumentation providers receive `channel.delivery.started` followed by

package/docs/guides/remote-agents.md

@@ -114,9 +114,17 @@ export default defineRemoteAgent({
 });
 ```
 
-The create-session request then carries the parent turn's `session.auth.current` and `session.auth.initiator` as a `forwardedPrincipal` body field (`initiator` is optional on the wire; when absent, the receiver seeds both from `current`). Only principal metadata crosses the wire — never tokens or credentials. The receiving deployment mints its own per-user credentials through its own connections.
+The create-session request carries the parent turn's `session.auth.current` and `session.auth.initiator` as a `forwardedPrincipal` body field (`initiator` is optional on the wire; when absent, the receiver seeds both from `current`). Every continuation carries only that turn's `session.auth.current`; the remote session keeps its original `auth.initiator`. Only principal metadata crosses the wire — never tokens or credentials. The receiving deployment resolves its own per-user credentials through its own connections.
 
-Forwarding is explicit on both sides. The receiver names which forwarders it trusts with `eveChannel({ trustedForwarders })` (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); a receiver that refuses the forwarder — or has no `trustedForwarders` at all — rejects with a 403 and the dispatch fails. One caveat: a receiver on an eve version that predates principal forwarding drops the unknown field and runs the session as your app's service identity (per-user connections there fail with `principal_required`), so upgrade both deployments together when enabling forwarding. When the dispatching turn has no auth at all, the field is omitted and the call proceeds on transport trust alone.
+This makes caller authority turn-scoped even when the remote child session is persistent. If Alice starts the child and Bob later continues it, the follow-up runs with Bob as `auth.current`, not Alice. If the parent turn's auth is `null`, a local child clears `auth.current`, while a remote child uses the freshly verified transport principal; neither inherits Alice. eve's in-step bearer cache is also keyed by the resolved principal and is not serialized across steps. The external authorization provider may preserve each user's server-side OAuth grant, but a later turn can resolve only the grant belonging to its own `auth.current` principal.
+
+Identity forwarding does not make a persistent session private to one caller. Conversation history, tool outputs, and other child-session state still persist. If those values must not be visible across users, give each user a distinct child session or enforce that ownership at the application boundary.
+
+Forwarding is explicit on both sides. The receiver names which forwarders it trusts with `eveChannel({ trustedForwarders })` (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); a receiver that refuses the forwarder — or has no `trustedForwarders` at all — rejects with a 403 and the dispatch fails.
+
+> ⚠️ **Upgrade both deployments before resuming persistent remote sessions.** A sender with continuation forwarding includes `forwardedPrincipal` on each authenticated follow-up. A receiver that supports forwarding only on session creation rejects that continuation with HTTP 400. eve does not retry without the field because that would run the follow-up as the transport service principal and silently change caller authority. The parent retains the child handle after this failure, so you can retry the same session after upgrading the receiver.
+
+A receiver on an eve version that predates all principal forwarding may instead drop the unknown field and run the session as your app's service identity; per-user connections there fail with `principal_required`. On remote requests where the dispatching turn has no auth, the field is omitted and the call proceeds on transport trust alone.
 
 ## How remote dispatch and callbacks work
 

package/docs/tools/overview.mdx

@@ -56,6 +56,25 @@ history or `toModelOutput`; only the final yield does. Treat snapshots as
 last-write-wins by tool call id, not append-only progress. The durable runtime
 can retry a step and replay overlapping snapshots.
 
+### Experimental background execution
+
+`defineTool({ execution: "background" })` receives a third `task` argument. Returning a normal
+value completes the durable task with that value. Returning `task.delegated({ executor, receipt })`
+returns a `working` receipt immediately while an external executor continues the task.
+The root agent must enable `experimental.tasks`; eve rejects background tools at build time otherwise.
+
+This contract currently supports framework-owned task executors, including local and remote
+subagents when `experimental.tasks` is enabled. After delegating, an in-process executor reports
+progress with `task.send({ kind: "update", message })` and the terminal result with
+`task.send({ kind: "complete", data })` (or `fail` / `cancel`). `send` is not restart-safe — an
+in-memory callback dies with the process — so the cross-process executor wire remains
+framework-owned and is not yet a stable authored-tool API.
+
+Each task-triggered parent turn includes runtime-authored state for tasks started by the same
+parent turn. The model is instructed to keep related intermediate results silent while that state
+contains pending tasks. Once every related task is terminal, the state includes their outputs so
+the model can combine the useful results.
+
 ### The `ctx` parameter
 
 `execute` gets a `ctx` carrying the runtime accessors:

package/docs/tutorial/ship-it.mdx

@@ -73,7 +73,7 @@ export default function Page() {
 }
 ```
 
-`agent.data.messages` and `agent.status` cover most chat UIs. The hook also surfaces HITL prompts (the spend approval from [Step 8](./guard-the-spend)), so the dashboard can render approve/cancel controls. For the full API, see [Frontend](../guides/frontend/overview).
+`agent.data.messages` and `agent.status` cover most chat UIs. The generated Web Chat renders HITL prompts directly in the conversation: approvals get action controls, and `ask_question` gets a visible form with vertical choices, a text field, or both. The spend approval from [Step 8](./guard-the-spend) uses the same response path. For the full API, see [Frontend](../guides/frontend/overview).
 
 ## Replace `placeholderAuth`
 

package/package.json

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