eve 0.53.1 → 0.54.2

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,31 +304,33 @@ 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. 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`.
 
-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.
 
-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.
+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.
 
-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.
+Model, `execute_tool`, and memory spans omit their content by default. Set `EVE_TRACES_CONTENT=on` to capture system prompts, prompt messages, and response text for models; call arguments and results for tools; and recalled memory records. Each captured value is capped at 32 KB.
+
+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                                                                              |
-| ---------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
-| `EVE_TRACES`                 | on                   | `off` stops writing traces and stops sweeping                                       |
-| `EVE_TRACES_CONTENT`         | off                  | `on` captures model prompt/response and tool input/output attributes on local spans |
-| `EVE_TRACES_MAX_AGE_MS`      | `604800000` (7d)     | Age after which a trace may be evicted                                              |
-| `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store                                                     |
-| `EVE_TRACES_RETAIN_COUNT`    | `20`                 | Newest traces kept regardless of age or size                                        |
+| Variable                     | Default              | Effect                                                                                              |
+| ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
+| `EVE_TRACES`                 | on                   | `off` stops writing traces and stops sweeping                                                       |
+| `EVE_TRACES_CONTENT`         | off                  | `on` captures model prompt/response, tool input/output, and memory-record attributes on local spans |
+| `EVE_TRACES_MAX_AGE_MS`      | `604800000` (7d)     | Age after which a trace may be evicted                                                              |
+| `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store                                                                     |
+| `EVE_TRACES_RETAIN_COUNT`    | `20`                 | Newest traces kept regardless of age or size                                                        |
 
 ## `eve link`
 

package/docs/subagents/index.mdx

@@ -7,13 +7,18 @@ eve supports two ways to delegate work: the root-only built-in `agent` tool, whi
 
 ## Completion batching
 
-eve automatically combines adjacent successful completions already queued from
-tasks launched in the same parent turn. Every result is retained, and the parent
-responds to the batch in one turn. No configuration is required.
-
-There is no debounce timer or waiting for unfinished tasks. Failures, input
-requests, explicit updates, user messages, and different task cohorts remain
-separate delivery boundaries.
+Overlapping background work owned by a session forms a cohort. Tasks launched in
+later user turns join the open cohort while earlier work is still pending or its
+successful results await delivery. eve holds successful completion notifications
+until every task in that cohort has completed, failed, or been cancelled, then
+delivers the successful results together in one parent turn. Partial completions
+do not invoke the parent model. Work started after the cohort settles forms a new
+cohort. No configuration or debounce timer is required.
+
+User messages, input requests, authorization events, failures, and cancellation
+are handled without waiting for the cohort. Child lifecycle events are processed
+before completion delivery so usage accounting and handle cleanup stay ordered.
+To follow work in progress, subscribe to the child session streams.
 
 ## The built-in `agent` tool
 
@@ -27,7 +32,7 @@ The root session receives `agent` by default. The model calls it to delegate a t
 }
 ```
 
-The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` always runs in the background and needs no configuration: each call returns `{ status: "working", taskId, agentId }`, then task notifications wake the parent with updates or the final result. Give parallel children non-overlapping write scopes.
+The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` always runs in the background and needs no configuration: each call returns `{ status: "working", taskId, agentId }`, then task notifications wake the parent with completion, failure, or cancellation. Give parallel children non-overlapping write scopes.
 
 `agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
 
@@ -56,9 +61,9 @@ export default defineAgent({
 });
 ```
 
-`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out. Every declared local or remote subagent runs as a durable background task: the call returns `{ status: "working", taskId, agentId }` immediately, then task notifications wake the parent with updates, completion, failure, or cancellation. Human input requests surface separately on the parent session.
+`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out. Every declared local or remote subagent runs as a durable background task: the call returns `{ status: "working", taskId, agentId }` immediately, then task notifications wake the parent with completion, failure, or cancellation. Human input requests surface separately on the parent session.
 
-A child running as a background task receives the framework `task_update` tool. It uses `task_update` to report progress to its parent. `task_cancel` is available to sessions that own background tasks, including a child that starts nested background work.
+`task_cancel` is available to sessions that own background tasks, including a child that starts nested background work.
 
 A mounted extension can also contribute declared subagents from `extension/subagents/`. The mount namespace prefixes the subagent visible to the consuming agent node: mounting an extension as `crm` exposes its `reviewer` subagent as `crm__reviewer`. The contributed subagent keeps its own isolated tools, connections, skills, hooks, instructions, sandbox, and nested subagents, and its modules can read configuration from the extension handle. See [Extensions](./extensions#add-a-subagent) for the authoring and override behavior.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.53.1",
+  "version": "0.54.2",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -186,11 +186,6 @@
       "import": "./dist/src/public/tools/task-cancel.js",
       "default": "./dist/src/public/tools/task-cancel.js"
     },
-    "./tools/task_update": {
-      "types": "./dist/src/public/tools/task-update.d.ts",
-      "import": "./dist/src/public/tools/task-update.js",
-      "default": "./dist/src/public/tools/task-update.js"
-    },
     "./tools/glob": {
       "types": "./dist/src/public/tools/glob.d.ts",
       "import": "./dist/src/public/tools/glob.js",

package/dist/src/execution/tasks/child/update-step.d.ts

@@ -1,6 +0,0 @@
-import type { TaskInboundUpdate } from "#tasks/types.js";
-/** Forwards a local task-owned child's progress update to its active parent hook. */
-export declare function forwardLocalTaskUpdateStep(input: {
-    readonly parentContinuationToken: string;
-    readonly update: TaskInboundUpdate;
-}): Promise<void>;

package/dist/src/execution/tasks/child/update-step.js

@@ -1 +0,0 @@
-import{resumeHook}from"#internal/workflow/runtime.js";async function forwardLocalTaskUpdateStep(e){"use step";await resumeHook(e.parentContinuationToken,e.update)}export{forwardLocalTaskUpdateStep};

package/dist/src/execution/tasks/child/update.d.ts

@@ -1,8 +0,0 @@
-import type { ChannelAdapter } from "#channel/adapter.js";
-import type { TaskInboundUpdate } from "#tasks/types.js";
-/** Delivers a task update through the local child adapter or remote callback. */
-export declare function deliverTaskUpdate(input: {
-    readonly adapter?: ChannelAdapter;
-    readonly callback: unknown;
-    readonly update: TaskInboundUpdate;
-}): Promise<string | undefined>;

package/dist/src/execution/tasks/child/update.js

@@ -1 +0,0 @@
-import{fireTaskUpdateCallbackStep}from"#subagents/callback-step.js";import{forwardLocalTaskUpdateStep}from"#execution/tasks/child/update-step.js";import{SUBAGENT_ADAPTER_KIND,isSubagentAdapterState}from"#subagents/adapter-state.js";async function deliverTaskUpdate(e){let t=e.adapter?.state;return e.adapter?.kind===SUBAGENT_ADAPTER_KIND&&isSubagentAdapterState(t)&&t.taskId!==void 0?(await forwardLocalTaskUpdateStep({parentContinuationToken:t.parentContinuationToken,update:e.update}),t.taskId):await fireTaskUpdateCallbackStep({callback:e.callback,callId:e.update.callId,message:e.update.message,updateEpoch:e.update.updateEpoch,updateIndex:e.update.updateIndex})}export{deliverTaskUpdate};

package/dist/src/public/tools/task-update.d.ts

@@ -1 +0,0 @@
-export { taskUpdate, taskUpdate as default } from "#tools/framework/task-update.js";

package/dist/src/public/tools/task-update.js

@@ -1 +0,0 @@
-import{taskUpdate,taskUpdate as task_update_default}from"#tools/framework/task-update.js";export{task_update_default as default,taskUpdate};

package/dist/src/tools/framework/task-update.d.ts

@@ -1,5 +0,0 @@
-export declare const TASK_UPDATE_SESSION_INSTRUCTION = "Background task updates\nYou are running as a background task. For multi-step work, use `task_update` at meaningful milestones to briefly state what you are currently doing. Keep updates terse and activity-focused; do not include preliminary findings or results. Do not wait for a response, and return your final result normally.";
-export declare const taskUpdate: import("#tools/native-definition.js").NativeToolDefinition<{
-    message: string;
-}, unknown>;
-export default taskUpdate;

package/dist/src/tools/framework/task-update.js

@@ -1 +0,0 @@
-import{TASK_UPDATE_INPUT_SCHEMA}from"#tools/framework/task-contract.js";import{defineNativeTool}from"#tools/native-definition.js";const TASK_UPDATE_SESSION_INSTRUCTION="Background task updates\nYou are running as a background task. For multi-step work, use `task_update` at meaningful milestones to briefly state what you are currently doing. Keep updates terse and activity-focused; do not include preliminary findings or results. Do not wait for a response, and return your final result normally.",taskUpdate=defineNativeTool({description:`Briefly tell the parent agent what this background task is currently doing. Report activity, not preliminary findings or results.`,inputSchema:TASK_UPDATE_INPUT_SCHEMA},{availability:[`delegated-task-child`],handling:{action:`task-update`,kind:`dispatch`}});export{TASK_UPDATE_SESSION_INSTRUCTION,taskUpdate as default,taskUpdate};