eve 0.68.0 → 0.70.0

package/docs/guides/frontend/use-eve-agent-vue.mdx

@@ -61,23 +61,17 @@ Call `send(text)` for text or pass content parts for attachments. The API and tr
 
 ## Human-in-the-loop prompts
 
-Pending requests appear in `data.value.messages`. Use the Vue exports when narrowing message parts, then answer through `respond()`:
+Open requests appear in the `data.value.inputs` ledger. Read them with `openConversationInputs()`, then answer through `respond()`. An answered request leaves the list right away, so its buttons can't be pressed twice:
 
 ```vue
 <script setup lang="ts">
 import { computed } from "vue";
-import { useEveAgent } from "eve/vue";
+import { openConversationInputs, useEveAgent } from "eve/vue";
 
 const { data, respond } = useEveAgent();
 
 const pendingRequests = computed(() =>
-  data.value.messages.flatMap((message) =>
-    message.parts.flatMap((part) => {
-      if (part.type !== "dynamic-tool" || part.state !== "approval-requested") return [];
-      const request = part.toolMetadata?.eve?.inputRequest;
-      return request ? [request] : [];
-    }),
-  ),
+  openConversationInputs(data.value).map((input) => input.request),
 );
 </script>
 
@@ -130,7 +124,7 @@ Pass `onEvent`, `onError`, `onFinish`, or `onSessionChange` when the application
 
 ## Custom reducer
 
-Import `EveAgentReducer` from `eve/vue` when projecting events into application-specific state. The resulting `data` remains a `ComputedRef<TData>`. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
+Import `EveAgentReducer` from `eve/vue` when projecting events into application-specific state. The resulting `data` remains a `ComputedRef<TData>`; `conversation` remains a `ComputedRef<ConversationState>` regardless of your reducer. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
 
 ## What to read next
 

package/docs/guides/hooks.md

@@ -48,7 +48,7 @@ export default githubChannel({
 });
 ```
 
-A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts.
+A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts. The [Slack channel](/docs/channels/slack#customize-rendering) takes renderers instead: a renderer's handler keeps Slack's default by calling `next()` and replaces it by skipping `next`.
 
 Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
 
@@ -87,10 +87,13 @@ handle can also automatically resume on later I/O. A hook failure, including a
 failed stop, follows the normal
 [hook failure behavior](#what-happens-when-a-hook-throws).
 
-For `subagent.called` and `subagent.completed`, `ctx.session.id` identifies the
-parent session. Typed handlers and `*` handlers receive this context even when
-the subagent event arrives between parent turns. These hooks can use
-`ctx.getSandbox()` against the parent session.
+For `task.started`, `task.settled`, and `agent.started`, `ctx.session.id`
+identifies the session that started the task or opened the subagent session.
+Typed handlers and `*` handlers receive this context even when the event
+arrives between turns. These hooks can use `ctx.getSandbox()` against that
+session. Session state and sandbox changes they make are kept for the
+session's next turn. `agent.started` appears when the child session opens, or
+when the parent's current model step ends if one is running.
 
 ### Narrowing tool results
 
@@ -172,11 +175,12 @@ See [the event envelope](../concepts/sessions-runs-and-streaming#the-event-envel
 
 ## Execution order
 
-When a stream event fires, three things happen in order:
+When a session publishes a stream event while it runs, the step that owns the session does four things in order:
 
-1. Emit. The channel adapter handler runs, the event is stamped with its `meta` envelope, then it is written to the durable stream.
-2. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
-3. Model preparation, for model lifecycle events. Dynamic resolvers subscribed to those events update the model context. Subagent notifications do not run model preparation.
+1. Channel delivery. The channel adapter handler runs.
+2. Write. The event is stamped with its `meta` envelope, then written to the durable stream.
+3. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
+4. Model preparation, for model lifecycle events. Dynamic resolvers subscribed to those events update the model context. Subagent notifications do not run model preparation.
 
 Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent. The persisted event and every hook observe the same `meta.id`.
 
@@ -184,7 +188,7 @@ Hooks always run after the event is durably recorded, so if a hook throws, the s
 
 eve logs a thrown or rejected handler with the hook slug, subscription, event type, event ID, and session ID, then runs the remaining subscribers in order. The current turn, subagent notification, and session continue. This applies to every stream-event hook, including `turn.started`, `step.started`, and failure events. Throwing from a hook does not reject work or veto a turn. To stop the running turn, call [`ctx.cancel()`](#cancel-the-running-turn-from-a-hook).
 
-A hook failure does not trigger a retry. State changes and external side effects made before the exception are not rolled back. If a side effect needs retries or compensation, handle that inside the hook. Runtime failures outside the authored handler, such as failures setting up context or persisting state, still propagate. If persisting state after a subagent notification fails, the workflow runtime retries the notification step, which can publish the event again.
+A hook failure does not trigger a retry. State changes and external side effects made before the exception are not rolled back. If a side effect needs retries or compensation, handle that inside the hook. Runtime failures outside the authored handler, such as failures setting up context or persisting state, still propagate. If persisting state after a `task.started`, `task.settled`, or `agent.started` event fails, the workflow runtime retries the publishing step, which can publish the event again.
 
 ## Cancel the running turn from a hook
 
@@ -215,13 +219,13 @@ The remaining subscribers for the event still run. Then eve cancels the turn the
 
 `ctx.cancel()` returns `void` rather than a promise. The turn stops after the hook returns, so there is nothing to await. Call it before the handler's promise settles: eve ignores a call from work the handler does not await and logs a warning.
 
-`ctx.cancel()` only stops a running turn. eve logs a warning and ignores the call on `step.failed`, `turn.completed`, `turn.failed`, `turn.cancelled`, `session.waiting`, `session.completed`, `session.failed`, `context.cleared`, and `subagent.*` events, and during clear or compact requests.
+`ctx.cancel()` only stops a running turn. eve logs a warning and ignores the call on `step.failed`, `turn.completed`, `turn.failed`, `turn.cancelled`, `turn.waiting`, `session.waiting`, `session.completed`, `session.failed`, `context.cleared`, `task.started`, `task.settled`, and `agent.started`, and during clear or compact requests.
 
 ## Subagent isolation
 
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
 
-Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. The accompanying parent `turn.completed` and `session.waiting` events also invoke parent hooks; they do not resolve pending input requests.
+Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
 
 ## Hook vs tool vs provider
 

package/docs/guides/instrumentation/instrumentation.mdx

@@ -169,6 +169,8 @@ operation key when upserting records across replays.
 
 An ordinary tool emits both `action.*` and `tool.call.*` events. Use `action.*` for eve's durable dispatch lifecycle, including tools, skills, subagents, and remote agents. Use `tool.call.*` only when you need the AI SDK's in-process tool execution boundary.
 
+For local and remote subagents, `action.completed` and `action.failed` include the child turn's `usage` directly. Token counts are always present when the child reports usage; `usage.costUsd` is present only when the model provider reports a price. Without the action-level usage, consumers would have to correlate child model events through trace lineage and sum their provider metadata, which is harder to do reliably across retries and parked turns.
+
 Handlers from different files run concurrently and are failure-isolated. Do
 not depend on execution order. Use `flush` to drain buffered records and
 `shutdown` to release resources.

package/docs/guides/instrumentation/otel.mdx

@@ -139,12 +139,30 @@ invoke_agent <agent>
               └── execute_tool <tool>
 ```
 
-Each turn starts a new trace. The first subagent trace links to its caller with
-`eve.link.type=agent.dispatch`; the link is not an authorization grant. For a
-remote agent, `trustedForwarders` lets the receiver accept the sender's session
-lineage and trace-content policy. See [Remote agents](../guides/remote-agents#preserving-trace-content).
-Use `gen_ai.conversation.id` to find the traces for one conversation in your
-destination's span-search surface.
+Each root agent turn starts a new trace. If eve receives a local caller's trace
+context, the first local subagent turn uses that trace. Its span is a
+child of the dispatch span and has a different span ID. Without caller trace
+context, the first subagent turn starts a new trace. Later turns in the child
+session start new traces. They do not use the original dispatch span as their
+parent.
+
+A remote child starts a separate trace with a root `invoke_agent` span. Its first
+turn links to the caller with `eve.link.type=agent.dispatch`. The receiving
+deployment applies its sampler. Queries for local dispatches must use
+`parentSpanId` or `agent.parent_run.id` and `agent.parent_call.id` instead of a
+dispatch link.
+
+Use `gen_ai.conversation.id` to find the root session and its child sessions
+across traces. eve adds this ID to spans created during model, tool, and memory
+execution. This includes spans from third-party instrumentation. `agent.run.id`
+identifies one agent session, not the full conversation.
+
+The shared conversation ID does not give access to message history, agent state,
+or credentials. It does not give authorization or require the same worker for
+each turn. Remote requests carry the conversation ID in W3C Baggage.
+`trustedForwarders` controls whether the receiver accepts parent session data
+and the trace-content policy. See
+[Remote agents](../guides/remote-agents#preserving-trace-content).
 
 ## Local traces
 

package/docs/guides/remote-agents.md

@@ -59,9 +59,16 @@ remain lazy and resolve before each outbound request without entering durable
 workflow state.
 
 Author `auth` and `headers` directly in the `defineRemoteAgent({ ... })` object
-and keep their functions self-contained with module imports or environment
-variables. They are rehydrated outside the event handler, so they cannot close
-over `_event`, `ctx`, or handler-local values.
+and keep their functions self-contained with module imports, module-level
+constants, or environment variables. They are rehydrated outside the event
+handler, so they cannot close over `_event`, `ctx`, or handler-local values. The
+build fails with an error that names the handler-local value when they do.
+
+eve compiles only `auth` and `headers` written directly in the
+`defineRemoteAgent({ ... })` object in the subagent file. When they arrive
+through a spread, a variable passed as the argument, or a definition built in
+another module, eve rejects the definition at runtime, logs the error, and runs
+the agent without that subagent.
 
 ## Runtime URLs
 
@@ -80,9 +87,9 @@ The function may be async and must return a non-empty string. `auth` and `header
 
 ## Calling a remote agent
 
-By default, a remote agent is another subagent tool to the model. The model calls it the same way it calls a local subagent, with a `message` and an optional `agentId`. Set `tool: false` when an authored workflow tool should be the only model-facing routing surface; the workflow can still call the remote agent by its path-derived name through `ctx.agent()`. The message must carry the full task, including any context the remote agent needs, because it never receives the parent's conversation history.
+By default, a remote agent is another subagent tool to the model. The model calls it the same way it calls a local subagent, with a `message` and an optional `taskId`. Set `tool: false` when an authored workflow tool should be the only model-facing routing surface; the workflow can still call the remote agent by its path-derived name through `ctx.agent()`. The message must carry the full task, including any context the remote agent needs, because it never receives the parent's conversation history.
 
-To require structured output, call the remote agent from an authored workflow tool with `ctx.agent(name, { message, outputSchema })`. The schema applies to that turn, the structured value is the call's result, and the remote child remains available for follow-up messages. See [Subagents](../subagents) for continuation behavior.
+To require structured output, open a session with the remote agent from an authored workflow tool with `ctx.agent(name)` and pass `outputSchema` to `send()`. The schema applies to that turn, the structured value is the response's `data`, and the session accepts follow-up messages until the workflow run finishes. See [Delegate work: `ctx.agent`](../tools/workflows#delegate-work-ctxagent).
 
 ## Outbound auth
 
@@ -131,9 +138,9 @@ export default defineRemoteAgent({
 });
 ```
 
-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.
+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`). A continuation by `taskId` carries the `session.auth.current` of the call that continues the task; 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.
 
-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.
+This makes caller authority turn-scoped even when the remote child session is persistent. If Alice starts the child and Bob later continues it with its `taskId`, 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.
 
@@ -141,16 +148,27 @@ Forwarding identity is explicit on both sides. The receiver names which deployme
 
 ## Trace propagation
 
-Each remote turn starts a new trace. eve links the child trace to the
-dispatching turn and carries `gen_ai.conversation.id` so you can find the
-traces for one conversation. Trace context is observability metadata, not an
-authorization grant. See [OpenTelemetry](../observability/otel#trace-topology)
-for the trace topology.
+A remote child starts its own trace with a root `invoke_agent` span. When caller
+trace context is available, the first turn links to the dispatch span with
+`eve.link.type=agent.dispatch`. The receiving deployment applies its sampler.
+Later turns start new traces without the original dispatch link. The first turn
+of a local child can use the remote agent's trace as a nested span.
+
+Use `gen_ai.conversation.id` to find all turns and child sessions for one
+conversation. The child has its own session ID, message history, and agent
+state. Trace context identifies related work. It does not give authorization.
+See [OpenTelemetry](../observability/otel#trace-topology) for the trace structure.
 
 eve carries parent session lineage separately. The receiver accepts it only
 when `trustedForwarders` approves the authenticated caller; otherwise, trace
 correlation continues without it.
 
+On Vercel, a remote agent's spans and its local subagents' spans carry the
+remote session's ID as `vercel.session_id`, so the receiving project groups
+them as their own session. `gen_ai.conversation.id` still names the sender's
+conversation, and the remote agent's `agent.parent_run.id` names the calling
+session.
+
 ## Preserving trace content
 
 With `forwardPrincipal: true`, a sampled remote dispatch forwards its original
@@ -183,23 +201,21 @@ widen capture and use metadata-only tracing.
 
 ## How remote dispatch and callbacks work
 
-A remote subagent runs as a durable background task in its own deployment:
+A remote subagent call runs a child session in the remote deployment as a task:
 
 1. The parent starts a persistent conversation session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
-2. The call returns `{ status: "working", taskId, agentId }` after the remote accepts the child.
-3. The callback later settles the task and sends a task notification to the parent.
-
-The parent stream carries the same `subagent.called`, `action.result`, and `subagent.completed` events as local delegation. For a remote call, `subagent.called.data.remote.url` records the target.
+2. The remote accepts the child and runs its turn while the task works.
+3. The callback delivers the child's reply, which becomes the task's result.
 
-Clients follow a remote child through the parent. [`session.streamSubagent()`](./client/streaming#follow-a-subagent) reads `subagent.called.data.childStreamPath`, a route on the parent deployment. The parent verifies that the child belongs to that session, resolves the remote agent's `auth` and `headers`, and relays the child's stream. A browser never calls the remote deployment or holds its credentials; it only needs access to the parent session.
+The parent stream carries the same `task.started`, `agent.started`, and `task.settled` events as local delegation. For a remote child, `agent.started.data.remote.url` records the target.
 
-An admitted task survives cancellation of the turn that started it; background work that has not yet been admitted is rejected with the cancelled step. Use `task_cancel` to stop an admitted task. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
+Clients follow a remote child through the parent. [`session.agent(started).stream()`](./client/streaming#follow-a-subagent) reads the `agent.started` event's `streamPath`, a route on the parent deployment. The parent verifies that its session recorded the child for that tool call, resolves the remote agent's `auth` and `headers`, and relays the child's stream. A browser never calls the remote deployment or holds its credentials; it only needs access to the parent session.
 
-You can also steer a running remote background child by calling its subagent tool with the same `agentId` and an updated `message`. eve cancels the old task and requests cancellation of the remote turn before continuing the same remote session under a new task ID. The remote must support the standard eve cancellation and session-message routes. See [Agent messaging](../subagents#agent-messaging) for the shared steering contract.
+Cancelling the parent turn or the agent task with `task_cancel` also cancels the remote child's current turn. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
 
-When the parent session ends, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for each remote child. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
+When the workflow run that opened a remote child finishes, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for it. An agent task's run finishes when the parent session ends. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
 
-A failed _start_ rejects admission before a task receipt is returned. After a remote starts, a terminal failure callback fails the task and notifies the parent with the remote's error. Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.
+The parent names its eve remote agent protocol version when it creates the child, and the remote answers with the version it serves. A remote also serves parents on protocol 1 (eve 0.66 through 0.68), including their approvals and sign-in requests, so upgrade remote agents before their callers; see [Upgrade remote agents before their callers](../tools/tasks-upgrade#upgrade-remote-agents-before-their-callers). Any other mismatch fails the call at start with an error naming both versions. A failed _start_ fails the call immediately. After a remote starts, a terminal failure callback fails the call with the remote's error. Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than completing the call, so the engine retries it.
 
 ## What to read next
 

package/docs/guides/self-modification.md

@@ -19,6 +19,16 @@ Add a tool that converts temperatures between Celsius and Fahrenheit.
 
 The self-modification subagent changes the authored files in your project. Review the diff and test the new behavior as you would for any other source change. `eve dev` reloads changes while you work.
 
+## Change the self-modification model
+
+The subagent uses your agent's model by default. To give it a different model or reasoning level, ask for it directly:
+
+```text
+Switch the self-modification subagent to openai/gpt-6-sol with low reasoning.
+```
+
+The first time, this creates `agent/extensions/self-modification/extension.ts` with those settings. After that file exists, later changes edit it. You can also edit the file yourself: it accepts `model` and `reasoning` options.
+
 ## Run without self-modification
 
 Pass `--no-default-extensions` when you do not want `eve dev` to mount bundled development extensions:

package/docs/instructions.mdx

@@ -86,7 +86,7 @@ See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failu
 
 [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-reset) treats user-role instructions like ordinary conversation history, so a summary may replace their original text. Clear removes them with the rest of model-message history and does not rerun static or dynamic instructions. System-role instructions remain because they are outside history.
 
-Keep system-role content stable and place it before frequently changing context when practical. That gives providers the best opportunity to reuse a prompt prefix, but cache behavior and billing remain provider-specific. User-role instructions preserve the normal append-only message prefix. Framework announcements about available skills and background tasks are retained in user-role history: changed snapshots append after earlier steps instead of replacing the context sent with those steps. Unchanged announcements are skipped until history is cleared or compacted. eve does not promise a cache hit.
+Keep system-role content stable and place it before frequently changing context when practical. That gives providers the best opportunity to reuse a prompt prefix, but cache behavior and billing remain provider-specific. User-role instructions preserve the normal append-only message prefix. Framework announcements about available skills and parked agents are retained in user-role history: changed snapshots append after earlier steps instead of replacing the context sent with those steps. Unchanged announcements are skipped until history is cleared or compacted. eve does not promise a cache hit.
 
 ## Disclaimer
 

package/docs/patterns/multi-tenant-approvals.md

@@ -190,6 +190,6 @@ An approval durably pauses the session and a later request resumes it. Your HTTP
 - `POST /eve/v1/session/:sessionId`, including `inputResponses`;
 - `GET /eve/v1/session/:sessionId/stream`.
 
-Built-in approval confirms that a human with access to the session approved the call. It is not a four-eyes workflow that proves a different person or role approved it. For that requirement, create an application-owned approval request, notify eligible approvers through a channel, and have policy return allow only after that request records an authorized decision.
+Built-in approval confirms that a human with access to the session approved the call. To restrict who may respond, add an [approval response policy](/docs/human-in-the-loop#authorizing-approval-responses): it receives who responded as `response.principal` and who asked for the call as `request.principal`, and runs for both Approve and Cancel. For a four-eyes workflow, where a different person or role must approve, branch on `response.decision`: allow `cancel` so the requester can still withdraw the call, and for `approve` reject a `response.principal` that matches `request.principal` and check the responder's role.
 
 The complete eve integration is one async adapter reused by tools and both connection protocols. The tenant's rule storage and governance model remain application concerns.

package/docs/protocols/ucp.mdx

@@ -13,20 +13,20 @@ With eve, you can support UCP in three steps:
 
 ## Author the profile
 
-Your profile is a plain JSON object that follows the [UCP spec](https://ucp.dev/). This spec outlines the `version`, `services`, `payment_handlers` and `capabilities` of your business. It also includes `signing_keys`, the public keys agents use to verify your business's signed messages.
+Your profile is a plain JSON object that follows the [UCP spec](https://ucp.dev/2026-08-25/specification/overview#profile-structure). The `ucp` object declares the `version`, `services`, `capabilities`, and `payment_handlers` of your business. The top-level `keys` array lists the public keys agents use to verify your business's signed messages. It's a standard JWK Set, so the same document also works as a key source for [Web Bot Auth](https://ucp.dev/2026-08-25/specification/overview#deployment-patterns-for-wba-interop).
 
 ```ts
 // agent/ucp-profile.ts
 export const profile = {
   ucp: {
-    version: "2026-04-08",
+    version: "2026-08-25",
     services: {
       "dev.ucp.shopping": [
         {
-          version: "2026-04-08",
-          spec: "https://ucp.dev/2026-04-08/specification/overview",
+          version: "2026-08-25",
+          spec: "https://ucp.dev/2026-08-25/specification/overview",
           transport: "rest",
-          schema: "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json",
+          schema: "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json",
           endpoint: "https://your_deployment_url_here/ucp/shopping",
         },
       ],
@@ -34,9 +34,9 @@ export const profile = {
     capabilities: {
       "dev.ucp.shopping.checkout": [
         {
-          version: "2026-04-08",
-          spec: "https://ucp.dev/2026-04-08/specification/checkout",
-          schema: "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+          version: "2026-08-25",
+          spec: "https://ucp.dev/2026-08-25/specification/shopping/checkout",
+          schema: "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json",
         },
       ],
     },
@@ -44,7 +44,7 @@ export const profile = {
       "dev.shopify.shop_pay": [
         {
           id: "shop_pay_1234",
-          version: "2026-04-08",
+          version: "2026-08-25",
           spec: "https://shopify.dev/ucp/shop-pay-handler",
           schema: "https://shopify.dev/ucp/schemas/shop-pay-config.json",
           available_instruments: [
@@ -57,14 +57,16 @@ export const profile = {
       "com.example.processor_tokenizer": [
         {
           id: "processor_tokenizer",
-          version: "2026-04-08",
+          version: "2026-08-25",
           spec: "https://example.com/specs/payments/processor_tokenizer-payment",
           schema: "https://example.com/schemas/payments/delegate-payment.json",
           available_instruments: [
             {
               type: "card",
               constraints: {
-                brands: ["visa", "mastercard"],
+                properties: {
+                  brand: { enum: ["visa", "mastercard"] },
+                },
               },
             },
           ],
@@ -72,7 +74,7 @@ export const profile = {
       ],
     },
   },
-  signing_keys: [
+  keys: [
     {
       kid: "business_2025",
       kty: "EC",
@@ -112,7 +114,7 @@ export default defineChannel({
 });
 ```
 
-- **Caching**: The spec requires `public` and a `max-age` of at least 60 seconds, and forbids `private`, `no-store`, and `no-cache`. See [Profile Requirements](https://ucp.dev/2026-04-08/specification/overview#hosting).
+- **Caching**: The spec requires `public` and a `max-age` of at least 60 seconds, and forbids `private`, `no-store`, and `no-cache`. See [Profile Requirements](https://ucp.dev/2026-08-25/specification/overview#hosting).
 - **CORS**: `cors: true` suits public discovery metadata. Pass a `cors` options object to narrow origins. See [CORS](../channels/custom#cors).
 - **HTTPS, no redirects**: The spec requires HTTPS and forbids 3xx responses on the profile endpoint.
 
@@ -130,13 +132,15 @@ export default defineChannel({
       const request = await req.json();
       // Create a checkout session per your published schema. Every UCP
       // response must carry the `ucp` envelope with the negotiated
-      // version and the capabilities active for this response.
+      // version and the capabilities active for this response. Checkout
+      // responses also require `payment_handlers`, even when empty.
       return Response.json({
         ucp: {
-          version: "2026-04-08",
+          version: "2026-08-25",
           capabilities: {
-            "dev.ucp.shopping.checkout": [{ version: "2026-04-08" }],
+            "dev.ucp.shopping.checkout": [{ version: "2026-08-25" }],
           },
+          payment_handlers: {},
         },
         id: "checkout_123",
         status: "incomplete",

package/docs/reference/cli.md

@@ -52,12 +52,12 @@ Existing packages do not need a target-selection prompt: run `eve init` from the
 
 After scaffolding in an interactive human terminal, eve opens the TUI directly. Pass `-n` or `--non-interactive` to return after scaffolding instead. It still installs dependencies and follows the normal Git setup behavior. Noninteractive and coding-agent invocations return without starting an interactive session. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
 
-| Flag                    | Type   | Default                  | Description                                                                                                              |
-| ----------------------- | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `--model <model>`       | string | `openai/gpt-6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
-| `--reasoning <effort>`  | enum   | provider default         | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
-| `--channel-web-nextjs`  | flag   | off                      | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
-| `-n, --non-interactive` | flag   | off                      | Scaffold and install dependencies without starting development.                                                          |
+| Flag                    | Type   | Default                                              | Description                                                                                                              |
+| ----------------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--model <model>`       | string | `openai/gpt-6-luna-fast`                             | Set the root agent's AI Gateway model ID.                                                                                |
+| `--reasoning <effort>`  | enum   | `high` without `--model`; otherwise provider default | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
+| `--channel-web-nextjs`  | flag   | off                                                  | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
+| `-n, --non-interactive` | flag   | off                                                  | Scaffold and install dependencies without starting development.                                                          |
 
 ## `eve extension`
 
@@ -148,6 +148,59 @@ eve info [--json]
 
 Run this first when something behaves unexpectedly. It confirms a file was discovered, lists the active surface, and surfaces discovery diagnostics, all faster than booting the dev server. Static instructions appear in source order with their `system` or `user` role. Dynamic instruction results are runtime-only and do not appear here.
 
+### JSON output
+
+`eve info --json` prints one JSON object. Scripts and CI checks can read it instead of the files under `.eve/`:
+
+| Field              | Type             | Description                                                                               |
+| ------------------ | ---------------- | ----------------------------------------------------------------------------------------- |
+| `appRoot`          | string           | Application root                                                                          |
+| `agentRoot`        | string or `null` | Agent directory, or `null` when the project could not be compiled                         |
+| `layout`           | string or `null` | Project layout                                                                            |
+| `status`           | string           | Compile status, such as `ready` or `failed`; `unavailable` when nothing compiled          |
+| `diagnostics`      | object or `null` | Discovery diagnostic counts: `{ errors, warnings }`                                       |
+| `model`            | string or `null` | Root agent model id                                                                       |
+| `instructions`     | string or `null` | Static instruction files with their roles                                                 |
+| `skills`           | string[]         | Static skill names                                                                        |
+| `tools`            | string[]         | Root agent tool names                                                                     |
+| `toolInputSchemas` | object           | Each tool's input schema as eve sends it to the model (see below)                         |
+| `subagents`        | string[]         | Declared subagent names                                                                   |
+| `schedules`        | string[]         | Schedule names                                                                            |
+| `channels`         | object[]         | Effective channel routes: `{ name, kind, method, urlPath }`                               |
+| `messaging`        | object           | Session route patterns: `{ create, messages, stream }`                                    |
+| `artifacts`        | object or `null` | Paths to the compiled manifest, discovery manifest, diagnostics, module map, and metadata |
+
+`toolInputSchemas.root` maps each root agent tool name to its JSON Schema, including tools from mounted extensions under their namespaced names. `toolInputSchemas.subagents` has one entry for each declared subagent, including nested subagents, and each value is the same kind of map for that subagent's own tools. Each key is the subagent's path of names from the root agent: `forecaster` for a subagent the root agent declares, and `forecaster/reviewer` for a `reviewer` subagent that `forecaster` declares. Subagents that share a name under different parents get separate entries. Each schema is the form eve sends to the model: schemas from a validation library such as Zod have `additionalProperties: false` on objects that allow no other keys, plain JSON Schema is kept as written, and tools whose calls run as `serve` tasks, including agent tools, include the optional `taskId` input eve adds.
+
+```json
+{
+  "tools": ["get_weather"],
+  "toolInputSchemas": {
+    "root": {
+      "get_weather": {
+        "type": "object",
+        "properties": { "city": { "type": "string" } },
+        "required": ["city"],
+        "additionalProperties": false
+      }
+    },
+    "subagents": {
+      "forecaster": {},
+      "forecaster/reviewer": {
+        "check_source": {
+          "type": "object",
+          "properties": { "url": { "type": "string" } },
+          "required": ["url"],
+          "additionalProperties": false
+        }
+      }
+    }
+  }
+}
+```
+
+`toolInputSchemas` covers only tools compiled from tool files. It does not include provider-managed tools such as `web_search`, dynamic tools, connection tools, the tools eve generates at runtime for each subagent and remote agent, or the `task_wait` and `task_cancel` tools. Model providers can also transform a schema before the model reads it; those changes are not reflected here. To compute the same form for an input schema in your own code, such as in a test, call `serializeModelInputSchema(schema)` from `eve/tools`; it returns JSON Schema data and does not add `taskId`.
+
 ## `eve build`
 
 ```bash
@@ -219,11 +272,11 @@ Starts a local development server and terminal UI. To connect the UI to an exist
 | `--input <text>`                    | string | none               | Pre-fill the prompt input                                       |
 | `--tools <mode>`                    | enum   | `auto-collapsed`   | Tool-call rendering                                             |
 | `--reasoning <mode>`                | enum   | `full`             | Reasoning rendering                                             |
-| `--subagents <mode>`                | enum   | `auto-collapsed`   | Subagent-section rendering                                      |
+| `--subagents <mode>`                | enum   | `collapsed`        | Subagent task rendering: `full`, `collapsed`, or `hidden`       |
 | `--connection-auth <mode>`          | enum   | `full`             | Connection-authorization rendering                              |
 | `--assistant-response-stats <mode>` | enum   | `tokensPerSecond`  | Assistant header statistic                                      |
 | `--context-size <tokens>`           | number | none               | Model context window size                                       |
-| `--logs <mode>`                     | enum   | `stderr`           | Server and agent logs to show                                   |
+| `--logs <mode>`                     | enum   | `error`            | Display `none`, `error`, `warn`, `debug`, or `all` logs         |
 
 Local development mounts bundled development extensions without adding files to your project. Pass `--no-default-extensions` to disable them. See [Self-Modification](../guides/self-modification) for details.
 
@@ -338,13 +391,13 @@ Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need
 
 Span rows carry inline metrics when the span recorded them — `↑input`/`↓output` token counts, gateway cost, and the tool name for `execute_tool` spans. The header lists models across the trace, sums token usage and cost from step spans, and counts all error-bearing spans. `--verbose` expands each span under its tree row: status (with the error message on failures), timing, ids, every attribute (prompts, responses, and tool payloads as transcripts or pretty-printed JSON), and every span event with its offset from span start. `--json` prints the same records as JSON, one object per selected trace.
 
-Every subagent activation starts its own trace. The first child's `invoke_agent` root links to the dispatching caller with `eve.link.type=agent.dispatch`; remote agents preserve that caller in W3C `tracestate` even when HTTP `traceparent` advances through platform ingress. Later turns also start fresh traces without repeating the initial caller link. All related sessions retain the same `gen_ai.conversation.id`, and `agent.subagent.name` labels the child invocation.
+With local caller trace context, the first local subagent turn uses the caller's trace. Its span is a child of the dispatch span. A remote child starts a separate root trace and links its first turn to the dispatch with `eve.link.type=agent.dispatch`. Remote requests use W3C `tracestate` to identify that dispatch span if platform HTTP handling changes `traceparent`. Later child turns start new traces. All related sessions have the same `gen_ai.conversation.id`. `agent.subagent.name` identifies the subagent.
 
-Each `agent()` call inside an authored workflow has its own `agent.action` caller span, including sequential, parallel, and background calls. A workflow tool that coordinates one of those calls has an enclosing `invoke_workflow <tool>` span; a workflow tool without agent calls remains `agent.action`. The tool also keeps its `execute_tool <tool>` span. Only agent execution uses `invoke_agent`.
+Each workflow tool call has an `agent.action` span and an `execute_tool <tool>` span. The first turn of each local session it opens with `ctx.agent` is a child of the call's `agent.action` span. A remote session links to that action from its own trace. An individual `ctx.agent` call does not create a separate dispatch span. Only agent execution uses `invoke_agent`.
 
 Outbound MCP `tools/call` requests add MCP semantic attributes to the matching `execute_tool` span. When eve has no tool span to enrich, it creates a `CLIENT` `tools/call <tool>` span. Each `tools/list` discovery also has a `CLIENT` span. Configured OpenTelemetry propagation fields are injected into MCP `params._meta` for JSON-RPC bodies up to 1 MiB and propagation metadata up to 8 KiB; larger requests are sent unchanged. eve removes its audience and session-lineage baggage before forwarding, and keeps the input/output content-capture policy local.
 
-A durable conversation produces one bounded trace per turn. Worker replacements reuse the prepared context for the same turn, while a later turn or an independently replayed attempt starts a fresh trace. Passing the conversation ID shows every trace it produced, oldest first.
+Each root agent turn starts a new trace. With local caller trace context, that trace includes the first turn of each local subagent it starts. Remote child turns and later local child turns start separate traces. If a worker is replaced, the new worker uses the prepared trace context for the same turn. Supply the conversation ID to show all related traces, oldest first.
 
 Every span carries a real duration. A turn's root `invoke_agent` span is written when the turn settles, so a running turn shows only its steps.