eve 0.53.0 → 0.54.0

package/docs/guides/instrumentation.md

@@ -56,6 +56,8 @@ Three more fields control what the AI SDK records inside those spans (see the AI
 
 eve records metadata without model or tool inputs and outputs by default. Enable either content category only after reviewing the exporter and its data-retention path.
 
+In the provider layout, eve stamps each span with `gen_ai.conversation.id`, which stays fixed across local and remote activations, including independent remote root workflows. Query this attribute to find the conversation's exported, retained traces; it does not grant access or control trace parenting. On Vercel, `vercel.session_id` additionally identifies the current Workflow run. See [Query exported traces](#query-exported-traces) for the cross-backend workflow.
+
 You are responsible for ensuring any observability or eval provider is approved for the data exported to it.
 
 The third configurable surface, [runtime context events](#runtime-context), attaches per-model-call values to these spans.
@@ -79,11 +81,9 @@ and outcome fields. Content providers additionally receive only eve's known
 message, context, input-response, and output-schema fields; adapter-specific
 payload fields are never projected.
 
-The built-in OpenTelemetry provider maps each pair to an
-`agent.channel.delivery` consumer span under the durable session window. When
-`traceChannelRequests: true` creates an inbound HTTP server span, the delivery
-span links to it with `eve.link.type=channel.request` rather than using the
-short-lived request span as its parent.
+For a single delivery that starts a turn, the built-in OpenTelemetry provider records the channel kind, channel name, delivery ID, optional request ID, and captured input on that turn's `invoke_agent` activation. The activation remains a root in its own trace and links to the active upstream request or function span with `eve.link.type=channel.request`. Set `traceChannelRequests: true` to create an eve-owned HTTP server span as that link target; when the option is false, an already-active upstream span remains the target.
+
+Deliveries that do not map one-to-one to an activation still produce instrumentation lifecycle events, but the built-in OpenTelemetry provider does not emit a separate delivery span.
 
 ## Callback delivery errors
 
@@ -103,12 +103,12 @@ not mark the active span as failed.
 The built-in OpenTelemetry provider preserves each span's OTel name and adds
 `operation.name` and `resource.name` for Datadog's operation/resource mapping:
 
-| OTel span name                                                                                                     | `operation.name`  | `resource.name`        |
-| ------------------------------------------------------------------------------------------------------------------ | ----------------- | ---------------------- |
-| `invoke_agent weather`                                                                                             | `invoke_agent`    | `invoke_agent weather` |
-| `execute_tool search`                                                                                              | `execute_tool`    | `execute_tool search`  |
-| `chat <model>`                                                                                                     | `chat`            | `chat <model>`         |
-| `agent.session`, `agent.step`, `agent.action`, `agent.approval`, `agent.channel.delivery`, `agent.channel.request` | Same as span name | Same as span name      |
+| OTel span name                                                          | `operation.name`  | `resource.name`        |
+| ----------------------------------------------------------------------- | ----------------- | ---------------------- |
+| `invoke_agent weather`                                                  | `invoke_agent`    | `invoke_agent weather` |
+| `execute_tool search`                                                   | `execute_tool`    | `execute_tool search`  |
+| `chat <model>`                                                          | `chat`            | `chat <model>`         |
+| `agent.step`, `agent.action`, `agent.approval`, `agent.channel.request` | Same as span name | Same as span name      |
 
 These attributes apply to eve-owned spans in local tracing and the
 [instrumentation provider layout](./instrumentation-providers). They do not
@@ -137,6 +137,136 @@ that discard span events, including Sentry's [direct OTLP
 intake](https://docs.sentry.io/concepts/otlp/direct/traces/). These attributes
 remain available when model and tool content is redacted.
 
+## Agent trace contract
+
+The provider layout and zero-config local tracing emit the following spans.
+The legacy `instrumentation.ts` layout still uses its authored OTel setup.
+
+| Span                    | Meaning                                                  |
+| ----------------------- | -------------------------------------------------------- |
+| `invoke_agent <agent>`  | One agent activation in its own trace                    |
+| `agent.step`            | One model attempt                                        |
+| `chat <model>`          | One model call beneath its step                          |
+| `agent.action`          | Durable action lifecycle, including dispatch and waiting |
+| `execute_tool <tool>`   | In-process tool execution beneath its action             |
+| `agent.approval`        | Approval waiting beneath its action                      |
+| `agent.channel.request` | Optional HTTP request span in the provider layout        |
+
+For background tools and subagents, the AI SDK's `execute_tool` span ends when
+the model receives the task receipt. The enclosing `agent.action` span remains
+open until the background task completes, fails, or is cancelled. Its duration,
+outcome, and usage describe the background task rather than the receipt.
+Background tool results follow the output-content policy. Recorded task failure
+details become bounded exception and status messages; redacted spans retain only
+the failure outcome, error status, and error type. The initiating turn can
+finish or be cancelled while the action remains open. Ending the session closes
+an action whose task never reported a terminal result.
+
+Schema v4 removes the session-long `agent.session` root and duplicate agent session and lineage attributes. Every eve span carries `agent.trace.schema.version=4` and `gen_ai.conversation.id`; Vercel deployments additionally carry `vercel.session_id`.
+Only activations use the `invoke_agent` operation. Dispatch lifecycle spans use
+`agent.action` with `agent.invocation.role=caller`; the built-in `agent` tool
+executes under `execute_tool agent`. Turn IDs such as `turn_0` are local to a session,
+so correlate turns by session ID and turn ID together.
+
+A conversation remains durable state; `gen_ai.conversation.id` joins the activations that operate on it.
+
+Each activation owns a fresh trace identity, including local and remote
+subagents. The first child activation links to its caller with
+`eve.link.type=agent.dispatch`; incoming `traceparent` provides that link, not
+the child trace ID. Later turns do not reuse the original caller link.
+Conversation baggage is independent of execution lineage and trace-policy
+ceilings, which remain in force across the boundary.
+
+Channel delivery does not allocate or replace the activation, and a later turn
+receives a new trace. Samplers
+see the activation name and attributes after its session coordinates are
+available. Sampling must be deterministic for the same trace and operation
+because durable reconstruction can evaluate it again.
+
+Use `agent.turn.outcome` to distinguish completed, failed, and cancelled activations. A failed action can be handled by the agent without failing its activation; see [Exported span names and outcomes](#exported-span-names-and-outcomes).
+
+Activation spans retain `gen_ai.usage.input_tokens` and
+`gen_ai.usage.output_tokens` alongside `agent.usage.*` totals for that activation.
+Model spans carry `gen_ai.usage.*`; step and dispatch spans report
+`agent.usage.*`. Activation totals summarize that activation's own model calls, while caller spans can summarize delegated usage. Do not sum usage across these levels.
+
+Nested dispatch spans are materialized when the child settles and handed to
+span processors; successful materialization removes their completed records
+from durable state. Settlement does not drain exporters or authored providers.
+Materialization failures are logged without failing settlement, and exporter
+draining follows the runtime's normal flush lifecycle.
+
+Cancelled or abandoned dispatches retain
+their outcome without error status. Error messages and stacks on eve spans count as
+output content, including errors reconstructed after a worker replacement.
+Metadata-only capture retains failure status without those details. Error logging
+outside eve's instrumented execution retains its existing exception content.
+
+Agent Runs activation metadata includes bounded principal summaries:
+
+- `agent.principal.current.type` and `agent.principal.current.id` describe the current caller.
+- `agent.principal.initiator.type` and `agent.principal.initiator.id` describe the authenticated principal that created the root session. The initiator remains fixed when later turns have a different caller.
+
+Types are limited to `user`, `service`, `runtime`, `app`, `anonymous`, `local-dev`, `unknown`, `none`, and `other`. Types are emitted for every audience when a principal is present. An absent type means no authentication context was set; `none` means an explicitly null principal and has no ID. The auth layer's `unknown` type stays `unknown`; unrecognized authored types become `other`.
+
+Principal IDs require a content-visible audience and a resolved trace decision that allows both `recordInputs` and `recordOutputs`. Public turns and unknown turns under `eve dev` can include IDs; private and hosted-unknown turns omit them. A user-configured trace policy or forwarded content ceiling that denies either direction omits both principal IDs before turn state is stored or sampled. Empty IDs and IDs larger than 1 KiB of UTF-8 data are omitted, not truncated; authentication records are unchanged. eve does not copy other authentication fields, such as claims, email attributes, issuers, or subjects, into these summaries.
+
+## Query exported traces
+
+Use a trace to investigate one activation's work. Use session and conversation attributes to find the other activations. Exporting to an OpenTelemetry backend does not turn a conversation into one continuous waterfall.
+
+This workflow applies to schema v4 from the [instrumentation provider layout](./instrumentation-providers). Configure third-party exporters through `otelIntegration()` so they receive the same framework spans as local tracing and Agent Runs. The legacy `instrumentation.ts` setup emits the [authored trace hierarchy](#authored-trace-hierarchy), not this contract.
+
+### Find an activation or conversation
+
+| Investigation            | Filter                                                                  |
+| ------------------------ | ----------------------------------------------------------------------- |
+| Agent activations        | `agent.trace.schema.version=4` and `gen_ai.operation.name=invoke_agent` |
+| One logical conversation | `gen_ai.conversation.id=<conversation ID>`                              |
+| One turn                 | Both `gen_ai.conversation.id` and `agent.turn.id`                       |
+| One Vercel Workflow run  | `vercel.session_id=<session ID>`                                        |
+| Delegated dispatches     | `agent.invocation.role=caller`                                          |
+
+Start with an activation filter for latency, failure, or turn-count dashboards. Every activation is a trace root. Within a conversation, group by trace ID, order activations by `agent.turn.sequence` or start time, and open the selected trace ID. Child activations link to their caller with `eve.link.type=agent.dispatch`; remote workflows keep their own execution lineage, so use conversation IDs and caller links for cross-deployment correlation.
+
+For example, the built-in `agent` tool dispatches research into a new workflow and trace, and the next user turn starts another trace:
+
+```text
+Trace A
+invoke_agent support                 session=S, turn=turn_0, conversation=S
+  agent.step
+    chat <model>
+    agent.action                     role=caller, action.call_id=C
+      execute_tool agent
+
+Trace B
+invoke_agent research                session=R, turn=turn_0, conversation=S
+  link: agent.dispatch -> Trace A's caller action C
+  agent.step
+    chat <model>
+
+Trace C
+invoke_agent support                 session=S, turn=turn_1, conversation=S
+  agent.step
+    chat <model>
+```
+
+The conversation filter finds all three retained traces. eve initializes the conversation ID once and carries it through the existing parent context for local dispatch and `eve.conversation.id` baggage for remote dispatch. Remote session creation does not carry execution lineage or add authorization requirements for tracing. Existing authentication, principal forwarding, and root-session limits remain unchanged.
+
+`traceparent` carries the caller's trace and span IDs for the causal link; adopting it as the child's parent would instead keep both in the same trace. Resolved trace-policy decisions and trusted remote content ceilings continue across this boundary independently of correlation, and an unsampled caller cannot be widened into a sampled child. No synthetic session span is needed.
+
+Activation duration is elapsed time for that activation, including waits inside it, not the lifetime of the conversation or CPU time. Idle time between ended activations is not part of their durations. For token totals, choose one level: filter to `chat` model spans and sum `gen_ai.usage.*`, or filter to activations and sum their `agent.usage.input_tokens` and `agent.usage.output_tokens`. Exclude caller summaries from the activation total. Query cache usage on model spans. Do not add model, step, activation, and caller counters together.
+
+### Search traces
+
+Use your destination's span-search surface to filter by the attributes in the table, group activations by session or trace ID, and open one activation's trace waterfall. Use the OTel span name and `gen_ai.operation.name` to identify the operation. Preserve eve's ownership of the OTel provider; do not register a second provider merely to add a destination.
+
+### Sampling and completeness
+
+A session can contain both retained and missing activation traces. Head sampling, backend retention, destination filtering, and exporter failures all affect what a conversation query returns. Preserve the schema and correlation attributes in Collector transforms and destination policies, and configure indexing and retention for the queries above.
+
+Do not interpret a missing activation as a missing execution, or sampled trace counts and token sums as an exact session ledger. A backend may receive descendants before the activation span finishes and exports; a temporarily missing root is not necessarily a broken parent ID. After deployment, verify a two-turn conversation and a delegation in the actual destination, including names, conversation grouping across services, separate trace roots, caller links, and outcome attributes.
+
 ## Runtime context
 
 _Runtime context_ is an [AI SDK concept](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text): a user-defined object that flows through a generation lifecycle. eve exposes it through `events["step.started"]`, a callback that runs once eve has assembled the model input for an attempt and returns `{ runtimeContext }`. Because eve registers the AI SDK's OpenTelemetry integration with runtime context enabled, those returned values ride onto the model-call span and its children. The field is named `runtimeContext`, not `metadata`, because AI SDK v7 carries per-call attributes on runtime context rather than a dedicated metadata field.
@@ -198,7 +328,7 @@ eve creates the `ai.eve.turn` parent span per turn and passes enriched telemetry
 
 This hierarchy applies when eve passes telemetry to the AI SDK. When the `otel()` provider layout is declared and eve owns the agent spans, eve names its invocation span `invoke_agent <agent>` and its model-attempt spans `agent.step`. Session, turn, step, and channel context is injected as the framework half of the runtime context (`eve.version`, `eve.session.id`, `eve.environment`, `eve.turn.id`, `eve.turn.sequence`, `eve.step.index`, `eve.channel.kind`) and rides onto the spans alongside any values your `events["step.started"]` callback returns under `runtimeContext`.
 
-Set `traceChannelRequests: true` on `defineInstrumentation` to also wrap each inbound channel HTTP request in a single OpenTelemetry `SERVER` span named for the registered route, which parents the turn tree above (and any `hook.resume` and outgoing HTTP spans):
+Set `traceChannelRequests: true` on `defineInstrumentation` to also wrap each inbound channel HTTP request in a single OpenTelemetry `SERVER` span named for the registered route. In the authored hierarchy above, this span parents the turn tree and any `hook.resume` or outgoing HTTP spans. In the provider layout, `invoke_agent` remains a separate trace root and links to the request span.
 
 ```text
 POST /eve/v1/session/:sessionId
@@ -224,7 +354,7 @@ Structural tags describe each run's place in the tree:
 - `$eve.trigger`: the channel kind that started the run
 - `$eve.schedule`: the authored schedule that created the session, including sessions started through a target channel
 - `$eve.title`: truncated title derived from the first user message
-- `$eve.trace_id`: trace id of the sampled agent trace containing the run, written on session, subagent, and turn rows so a dashboard run can be joined to its OpenTelemetry trace. Present only when the trace is sampled; absence means no exported OTEL trace exists.
+- `$eve.trace_id`: sampled trace seed available when tagging a session, subagent, or turn run. Use it as a trace link, not a conversation-wide trace identity. Later activations can use other trace IDs; query `gen_ai.conversation.id` for the history. The tag does not confirm that a destination retained the trace.
 
 Per-turn usage tags are written on each step of a turn, accumulating cumulative totals (last write wins):
 
@@ -238,7 +368,7 @@ These tags power the **Agent Runs** tab in the Vercel dashboard. When you deploy
 
 ## Local traces
 
-Without an `instrumentation.ts`, `eve dev` records spans to disk — one trace per session, with turns, model steps, and tool calls. Read them two ways:
+Without an `instrumentation.ts`, `eve dev` records spans to disk with one bounded trace per turn, including its model steps and tool calls. Read them two ways:
 
 - [`/traces`](dev-tui#logs-and-traces) in the dev TUI: a live trace viewer that replays captured content as a conversation.
 - [`eve traces`](../reference/cli#eve-traces): a span tree in the terminal, `eve traces ls` to list. Works after `eve dev` exits.

package/docs/guides/remote-agents.md

@@ -139,6 +139,17 @@ Identity forwarding does not make a persistent session private to one caller. Co
 
 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.
 
+Remote tracing uses ordinary `traceparent` propagation. Trace context is not an authorization grant: it cannot assert eve parent lineage, change `rootSessionId`, or remove the normal root-session token cap.
+
+eve also carries the original `gen_ai.conversation.id` in `eve.conversation.id` baggage so you can find related traces across local and remote agents. This observability identifier does not require principal forwarding or shared execution lineage; it grants no session access and does not change trace-content policy. Session execution establishes this ID even without an instrumentation runtime. Only session-create requests with a callback may supply this baggage; top-level requests ignore it and establish their own conversation ID. Callback metadata is caller-supplied correlation, not verified identity.
+
+eve replaces configured `traceparent` and conversation baggage only when it has a framework value to send. Incoming baggage has an 8 KiB limit; the audience and conversation readers share whitespace, percent-decoding, and duplicate-key validation. Conversation IDs are limited to 1 KiB and exclude control characters and line separators. If adding an audience assertion or conversation ID would exceed 8 KiB, eve rejects the dispatch before sending a request instead of dropping the member. Reduce `remote.headers.baggage` to leave room for these framework values.
+
+In the [provider trace contract](./instrumentation#agent-trace-contract), each
+child activation starts a separate trace. The first activation uses the incoming
+`traceparent` as an `agent.dispatch` span link rather than adopting the caller's
+trace ID.
+
 > ⚠️ **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.

package/docs/reference/cli.md

@@ -304,23 +304,25 @@ eve traces --verbose       # expand every span with all attributes and events
 eve traces --json          # dump the full trace as JSON
 ```
 
-Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need not be running. Accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed segments are skipped without hiding valid spans from the same trace.
+Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need not be running. Accepts a full trace id, a `gen_ai.conversation.id`, or an unambiguous prefix of either. Malformed segments are skipped without hiding valid spans from the same trace.
 
 Span rows carry inline metrics when the span recorded them — `↑input`/`↓output` token counts, gateway cost, and the tool name for `execute_tool` spans — and the header aggregates models, token totals, cost, and error count across the trace's step 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.
 
-A local subagent keeps its own session id but records into the parent trace. Its `invoke_agent` span is parented to the `agent.action` span that dispatched it, so the span tree carries the relationship without duplicate lineage attributes; `agent.subagent.name` remains on the child invocation as a standalone label. Either session id resolves to that trace. Remote agents propagate the parent trace context over `traceparent`.
+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 carry that caller context over `traceparent`. 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.
 
-A durable session keeps one persisted trace context across turns and worker resumptions. Independently replayed attempts can still produce another trace; passing the session id shows every trace it produced, oldest first.
+Each `agent()` call inside an authored workflow has its own `agent.action` caller span, including sequential, parallel, and background calls. The workflow tool keeps its own `agent.action` and `execute_tool` spans. Only agent execution uses `invoke_agent`.
 
-Every span carries a real duration except `agent.session`: an idle session never closes, so it is recorded as a zero-duration marker and the span tree shows its descendant extent instead. A turn's `invoke_agent` span is written when the turn settles, so a running turn shows only its steps.
+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.
+
+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.
 
 Model and `execute_tool` spans omit their inputs and outputs by default. Set `EVE_TRACES_CONTENT=on` to capture system prompts, prompt messages, and response text for models, plus call arguments and results for tools. Each captured value is capped at 32 KB.
 
-Step spans carry token counts, and cost when Vercel AI Gateway served the call. Both follow the [OTel GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai) (`gen_ai.usage.*`), so a third-party backend reads them without mapping.
+Step spans carry token counts under `agent.usage.*`, and cost when Vercel AI Gateway served the call. Model spans also expose `gen_ai.usage.*` token counters. The CLI sums step-level counters only, so model and delegated-call totals are not counted twice.
 
 ### Retention
 
-eve sweeps the store when a session finishes and when the dev server starts, evicting oldest-first past the bounds below — except that the newest traces and anything written in the last five minutes are always kept, so a sweep will exceed the size budget rather than drop a trace you just recorded. Set the bounds in `.env.local`, which `eve dev` loads automatically; each accepts `off` to disable it individually.
+eve sweeps the store when an activation's writes finish, when a session finishes, and when the dev server starts. An open conversation does not pin every completed turn's trace. Sweeps evict oldest-first past the bounds below, except that active traces, the newest traces, and anything written in the last five minutes are kept. A sweep can therefore exceed the size budget. Set the bounds in `.env.local`, which `eve dev` loads automatically; each accepts `off` to disable it individually.
 
 | Variable                     | Default              | Effect                                                                              |
 | ---------------------------- | -------------------- | ----------------------------------------------------------------------------------- |

package/docs/reference/typescript-api.md

@@ -57,7 +57,7 @@ export default defineTool({
 
 Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
 
-`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
+`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
 `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.
 

package/docs/sandbox.mdx

@@ -291,7 +291,7 @@ Session sandboxes are keyed per durable session, not per deployment, so redeploy
 
 For sandboxes with `bootstrap`, unrelated agent changes preserve the template and session sandbox keys even when there are no skill or workspace seed files. You do not need to add a seed file or `revalidationKey` solely to preserve reuse across those changes.
 
-Reattachment still depends on the backend retaining its physical sandbox state. If a persisted Vercel sandbox is no longer available, eve creates a replacement, using the current template when one is configured. Files and other changes made after the original sandbox was created are not restored automatically. Because the durable session still has the same sandbox key, `onSession` does not run again for this replacement. Persist important artifacts outside the sandbox, and do not rely on `onSession` as the only place that applies security-critical configuration.
+Reattachment still depends on the backend retaining its physical sandbox state. If a persisted Vercel sandbox is missing or its saved filesystem snapshot is no longer available, eve deletes the unusable record and creates a replacement from the current template when one is configured. Files and other changes made after the original sandbox was created are not restored automatically. Because the durable session still has the same sandbox key, `onSession` does not run again for this replacement. Persist important artifacts outside the sandbox, and do not rely on `onSession` as the only place that applies security-critical configuration.
 
 When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters implement `stop()` for authored runtime calls and `shutdown()` for server teardown. Both stop the underlying compute while keeping the session reattachable from persisted state where the backend supports it; authored `stop()` failures reject, while process-wide shutdown collects and logs failures without blocking teardown.
 

package/package.json

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