eve 0.66.0 → 0.66.2

package/dist/src/tracing/local-trace-analysis.d.ts

@@ -0,0 +1,51 @@
+import type { LocalTraceSpan } from "#tracing/local-trace-reader.js";
+import { type LocalTraceSummary } from "#tracing/local-trace-summary.js";
+export interface TraceAnalysisSelector {
+    readonly excludeSessionId?: string;
+    readonly fromMs?: number;
+    readonly sessionId?: string;
+    readonly toMs?: number;
+    readonly turnId?: string;
+}
+export interface TraceTokenUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+export interface TraceTimelineRecord {
+    readonly actionDurationMs?: number;
+    readonly actionName?: string;
+    readonly callId?: string;
+    readonly category: "model" | "other" | "tool";
+    readonly durationMs: number;
+    readonly endOffsetMs: number;
+    readonly error?: string;
+    readonly model?: string;
+    readonly outcome: "completed" | "failed";
+    readonly parentSpanId?: string;
+    readonly sessionId?: string;
+    readonly spanId: string;
+    readonly startOffsetMs: number;
+    readonly toolName?: string;
+    readonly turnId?: string;
+    readonly usage?: TraceTokenUsage;
+}
+export interface TraceAnalysis {
+    readonly summary: LocalTraceSummary;
+    readonly groups: readonly TraceAnalysisGroup[];
+    /** Accumulated operation time, not elapsed time; parallel calls can overlap. */
+    readonly modelWorkMs: number;
+    readonly toolWorkMs: number;
+    readonly records: readonly TraceTimelineRecord[];
+}
+export interface TraceAnalysisGroup {
+    readonly modelWorkMs: number;
+    readonly modelCalls: number;
+    readonly sessionId?: string;
+    readonly toolWorkMs: number;
+    readonly toolCalls: number;
+    readonly turnId?: string;
+}
+/** Builds the detailed timeline only when inspection, rather than search, needs it. */
+export declare function analyzeLocalTrace(traceId: string, spans: readonly LocalTraceSpan[], selector?: TraceAnalysisSelector): TraceAnalysis;

package/dist/src/tracing/local-trace-analysis.js

@@ -0,0 +1 @@
+import{summarizeLocalTrace}from"#tracing/local-trace-summary.js";import{localTraceOperations,traceModelName,traceSessionId,traceStringAttribute,traceToolName,uniqueLocalTraceSpans}from"#tracing/local-trace-operations.js";function analyzeLocalTrace(e,t,n={}){let r=uniqueLocalTraceSpans(t),i=new Map(localTraceOperations(r).map(({span:e})=>[e.spanId,e])),a=r.filter(e=>matches(i.get(e.spanId)??e,n)),o=a.reduce((e,t)=>t.startTimeNs<e?t.startTimeNs:e,a[0]?.startTimeNs??0n),s=localTraceOperations(a).map(e=>recordFor(e,o)).sort((e,t)=>e.startOffsetMs-t.startOffsetMs||e.endOffsetMs-t.endOffsetMs||e.spanId.localeCompare(t.spanId));return{summary:summarizeLocalTrace(e,a),groups:groups(s),modelWorkMs:sum(s,`model`),toolWorkMs:sum(s,`tool`),records:s}}function matches(e,t){let n=traceSessionId(e),r=traceStringAttribute(e,`agent.turn.id`);if(t.excludeSessionId!==void 0&&n===t.excludeSessionId||t.sessionId!==void 0&&n!==t.sessionId||t.turnId!==void 0&&r!==t.turnId)return!1;let i=Number(e.startTimeNs/1000000n);return(t.fromMs===void 0||i>=t.fromMs)&&(t.toMs===void 0||i<=t.toMs)}function recordFor(e,t){let{span:n,category:r}=e,i={category:r,durationMs:Number(n.endTimeNs-n.startTimeNs)/1e6,endOffsetMs:Number(n.endTimeNs-t)/1e6,outcome:n.statusCode===2?`failed`:`completed`,spanId:n.spanId,startOffsetMs:Number(n.startTimeNs-t)/1e6},a=traceStringAttribute(n,`agent.action.call_id`),o=traceModelName(n),s=traceSessionId(n),c=traceToolName(n),l=traceStringAttribute(n,`agent.turn.id`);if(a!==void 0&&(i.callId=a),n.statusMessage!==void 0&&(i.error=n.statusMessage),o!==void 0&&(i.model=o),n.parentSpanId!==void 0&&(i.parentSpanId=n.parentSpanId),s!==void 0&&(i.sessionId=s),c!==void 0&&r===`tool`&&(i.toolName=c),c!==void 0&&r===`other`&&(i.actionName=c),l!==void 0&&(i.turnId=l),e.actionDurationMs!==void 0&&(i.actionDurationMs=e.actionDurationMs),r===`model`){let e={};for(let[t,r]of Object.entries({inputTokens:`agent.usage.input_tokens`,outputTokens:`agent.usage.output_tokens`,cacheReadTokens:`agent.usage.cache_read_tokens`,cacheWriteTokens:`agent.usage.cache_write_tokens`})){let i=n.attributes[r];typeof i==`number`&&Number.isFinite(i)&&i>=0&&(e[t]=i)}Object.keys(e).length>0&&(i.usage=e)}return i}function groups(e){let t=new Map;for(let n of e){let e=JSON.stringify([n.sessionId,n.turnId]),r=t.get(e);r===void 0&&(r={modelCalls:0,modelWorkMs:0,toolCalls:0,toolWorkMs:0},n.sessionId!==void 0&&(r.sessionId=n.sessionId),n.turnId!==void 0&&(r.turnId=n.turnId),t.set(e,r)),n.category===`model`&&(r.modelCalls+=1,r.modelWorkMs+=n.durationMs),n.category===`tool`&&(r.toolCalls+=1,r.toolWorkMs+=n.durationMs)}return[...t.values()]}function sum(e,t){return e.reduce((e,n)=>e+(n.category===t?n.durationMs:0),0)}export{analyzeLocalTrace};

package/dist/src/tracing/local-trace-discovery-index.d.ts

@@ -0,0 +1,15 @@
+/** A path-safe, non-reversible key for one recorded conversation identifier. */
+export declare function localTraceConversationIndexKey(conversationId: string): string;
+/** Marker path relative to one trace directory. */
+export declare function localTraceConversationMarker(conversationId: string): string;
+/** Marker proving that a trace was written by an index-aware writer. */
+export declare function localTraceIndexedMarker(): string;
+/**
+ * Records conversation membership without rewriting shared state. Empty marker
+ * creation is idempotent, so overlapping dev workers cannot lose each other's
+ * conversation entries.
+ */
+export declare function indexLocalTraceConversation(input: {
+    readonly conversationId: string;
+    readonly traceDirectory: string;
+}): Promise<void>;

package/dist/src/tracing/local-trace-discovery-index.js

@@ -0,0 +1 @@
+import{createHash}from"node:crypto";import{mkdir,writeFile}from"node:fs/promises";import{join}from"node:path";const INDEX_DIRECTORY=`index/v1`,CONVERSATIONS_DIRECTORY=`${INDEX_DIRECTORY}/conversations`,INDEXED_MARKER=`${INDEX_DIRECTORY}/indexed`;function localTraceConversationIndexKey(e){return createHash(`sha256`).update(e).digest(`hex`)}function localTraceConversationMarker(e){return`${CONVERSATIONS_DIRECTORY}/${localTraceConversationIndexKey(e)}`}function localTraceIndexedMarker(){return INDEXED_MARKER}async function indexLocalTraceConversation(e){let t=join(e.traceDirectory,localTraceConversationMarker(e.conversationId));await mkdir(join(e.traceDirectory,CONVERSATIONS_DIRECTORY),{recursive:!0}),await createMarker(t),await createMarker(join(e.traceDirectory,INDEXED_MARKER))}async function createMarker(e){try{await writeFile(e,``,{flag:`wx`})}catch(e){if(!isAlreadyPresent(e))throw e}}function isAlreadyPresent(e){return e instanceof Error&&`code`in e&&e.code===`EEXIST`}export{indexLocalTraceConversation,localTraceConversationIndexKey,localTraceConversationMarker,localTraceIndexedMarker};

package/dist/src/tracing/local-trace-operations.d.ts

@@ -0,0 +1,13 @@
+import type { LocalTraceSpan } from "#tracing/local-trace-reader.js";
+export interface LocalTraceOperation {
+    readonly span: LocalTraceSpan;
+    readonly category: "model" | "other" | "tool";
+    readonly actionDurationMs?: number;
+}
+export declare function uniqueLocalTraceSpans(spans: readonly LocalTraceSpan[]): LocalTraceSpan[];
+/** Pairs action wrappers with execution spans without constructing a sorted timeline. */
+export declare function localTraceOperations(spans: readonly LocalTraceSpan[]): LocalTraceOperation[];
+export declare function traceModelName(span: LocalTraceSpan): string | undefined;
+export declare function traceToolName(span: LocalTraceSpan): string | undefined;
+export declare function traceSessionId(span: LocalTraceSpan): string | undefined;
+export declare function traceStringAttribute(span: LocalTraceSpan, key: string): string | undefined;

package/dist/src/tracing/local-trace-operations.js

@@ -0,0 +1 @@
+function uniqueLocalTraceSpans(e){let t=new Map;for(let n of e)t.has(n.spanId)||t.set(n.spanId,n);return[...t.values()]}function localTraceOperations(e){let t=new Map(e.map(e=>[e.spanId,e])),n=new Set,r=[];for(let i of e){let e=categoryFor(i);if(e===void 0)continue;let a=i.parentSpanId===void 0?void 0:t.get(i.parentSpanId);i.attributes[`gen_ai.operation.name`]===`execute_tool`&&a?.name===`agent.action`&&traceToolName(a)===traceToolName(i)?(n.add(a.spanId),r.push({category:e,span:{...i,attributes:{...a.attributes,...i.attributes},parentSpanId:a.parentSpanId,statusCode:a.statusCode===2?a.statusCode:i.statusCode,statusMessage:a.statusCode===2?a.statusMessage:i.statusMessage},...a.attributes[`agent.action.kind`]===`subagent-call`?{actionDurationMs:Number(a.endTimeNs-a.startTimeNs)/1e6}:{}})):r.push({category:e,span:i})}return r.filter(({span:e})=>!n.has(e.spanId))}function categoryFor(e){if(e.attributes[`gen_ai.operation.name`]===`chat`)return`model`;if(e.attributes[`gen_ai.operation.name`]===`execute_tool`)return`tool`;if(e.name===`agent.action`)return e.attributes[`agent.action.kind`]===`tool-call`?`tool`:`other`}function traceModelName(e){return traceStringAttribute(e,`agent.model.id`)??traceStringAttribute(e,`gen_ai.request.model`)}function traceToolName(e){return traceStringAttribute(e,`gen_ai.tool.name`)??traceStringAttribute(e,`agent.action.name`)}function traceSessionId(e){return traceStringAttribute(e,`agent.run.id`)??traceStringAttribute(e,`agent.session.id`)}function traceStringAttribute(e,t){let n=e.attributes[t];return typeof n==`string`&&n.length>0?n:void 0}export{localTraceOperations,traceModelName,traceSessionId,traceStringAttribute,traceToolName,uniqueLocalTraceSpans};

package/dist/src/tracing/local-trace-query.d.ts

@@ -0,0 +1,17 @@
+import type { LocalTraceSummary } from "#tracing/local-trace-summary.js";
+export type LocalTraceSortBy = "duration" | "failures" | "inputTokens" | "latest";
+export interface LocalTraceQueryFilter {
+    readonly agentName?: string;
+    /** Selects traces containing error spans, not necessarily failed activations. */
+    readonly failedOnly?: boolean;
+    readonly sessionId?: string;
+    readonly toolName?: string;
+}
+/** Filters whole traces without restricting their totals to matching spans. */
+export declare function queryLocalTraceSummaries(summaries: readonly LocalTraceSummary[], options: LocalTraceQueryFilter & {
+    readonly limit: number;
+    readonly sortBy: LocalTraceSortBy;
+}): {
+    readonly matches: readonly LocalTraceSummary[];
+    readonly truncated: boolean;
+};

package/dist/src/tracing/local-trace-query.js

@@ -0,0 +1 @@
+function queryLocalTraceSummaries(e,t){let n=e.filter(e=>matchesFilter(e,t));return n.sort((e,n)=>compareSummaries(e,n,t.sortBy)),{matches:n.slice(0,t.limit),truncated:n.length>t.limit}}function matchesFilter(e,t){return(t.agentName===void 0||e.agentNames.includes(t.agentName))&&(t.sessionId===void 0||e.sessionIds.includes(t.sessionId))&&(t.toolName===void 0||e.toolNames.includes(t.toolName))&&(t.failedOnly!==!0||e.errorSpanCount>0)}function compareSummaries(e,t,n){return(n===`duration`?t.durationMs-e.durationMs:n===`failures`?t.errorSpanCount-e.errorSpanCount:n===`inputTokens`?t.inputTokens-e.inputTokens:Date.parse(t.startedAt)-Date.parse(e.startedAt))||e.traceId.localeCompare(t.traceId)}export{queryLocalTraceSummaries};

package/dist/src/tracing/local-trace-span-processor.js

@@ -1 +1 @@
-import{mkdir}from"node:fs/promises";import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{atomicWriteFile}from"#shared/atomic-write-file.js";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";const log=createLogger(`harness.local-trace-span-processor`);function resolveLocalTraceStoreDirectory(e){return join(e,`.eve`,`traces`)}function resolveLocalTraceSchemaDirectory(e){return join(resolveLocalTraceStoreDirectory(e),`v1`)}function resolveLocalTraceSegmentsDirectory(e,t){return join(resolveLocalTraceSchemaDirectory(e),t,`segments`)}var LocalTraceSpanProcessor=class{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}forceFlush(){return this.#t}onStart(){}onEnd(e){if(!isReadableSpan(e))return;let{spanId:t,traceId:n}=e.spanContext();if(!isHexId(n,32)||!isHexId(t,16))return;let r=JsonTraceSerializer.serializeRequest([e]);r!==void 0&&(this.#t=this.#t.then(async()=>{let e=resolveLocalTraceSegmentsDirectory(this.#e,n);await mkdir(e,{recursive:!0}),await atomicWriteFile(join(e,`${t}.otlp.json`),r)}).catch(e=>{this.#n||(this.#n=!0,log.warn(`local trace persistence failed`,{error:formatError(e)}))}))}shutdown(){return this.forceFlush()}};function isReadableSpan(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}function isHexId(e,t){return e.length===t&&/^[0-9a-f]+$/u.test(e)}export{LocalTraceSpanProcessor,resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory};
+import{mkdir}from"node:fs/promises";import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{atomicWriteFile}from"#shared/atomic-write-file.js";import{indexLocalTraceConversation}from"#tracing/local-trace-discovery-index.js";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";const log=createLogger(`harness.local-trace-span-processor`);function resolveLocalTraceStoreDirectory(e){return join(e,`.eve`,`traces`)}function resolveLocalTraceSchemaDirectory(e){return join(resolveLocalTraceStoreDirectory(e),`v1`)}function resolveLocalTraceDirectory(e,t){return join(resolveLocalTraceSchemaDirectory(e),t)}function resolveLocalTraceSegmentsDirectory(e,t){return join(resolveLocalTraceDirectory(e,t),`segments`)}var LocalTraceSpanProcessor=class{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}forceFlush(){return this.#t}onStart(){}onEnd(e){if(!isReadableSpan(e))return;let{spanId:t,traceId:n}=e.spanContext();if(!isHexId(n,32)||!isHexId(t,16))return;let r=JsonTraceSerializer.serializeRequest([e]);if(r===void 0)return;let i=e.attributes[`gen_ai.conversation.id`],a=typeof i==`string`&&i.length>0?i:void 0;this.#t=this.#t.then(async()=>{let e=resolveLocalTraceDirectory(this.#e,n),i=resolveLocalTraceSegmentsDirectory(this.#e,n);await mkdir(i,{recursive:!0}),await atomicWriteFile(join(i,`${t}.otlp.json`),r),a!==void 0&&await indexLocalTraceConversation({conversationId:a,traceDirectory:e})}).catch(e=>{this.#n||(this.#n=!0,log.warn(`local trace persistence failed`,{error:formatError(e)}))})}shutdown(){return this.forceFlush()}};function isReadableSpan(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}function isHexId(e,t){return e.length===t&&/^[0-9a-f]+$/u.test(e)}export{LocalTraceSpanProcessor,resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory};

package/dist/src/tracing/local-trace-summary.d.ts

@@ -0,0 +1,31 @@
+import type { LocalTraceSpan } from "#tracing/local-trace-reader.js";
+/** Structural metadata and totals for one retained trace, not its final outcome. */
+export interface LocalTraceSummary {
+    readonly traceId: string;
+    readonly startedAt: string;
+    /** Elapsed time from the earliest span start to the latest span end. */
+    readonly durationMs: number;
+    readonly spanCount: number;
+    readonly agentNames: readonly string[];
+    readonly conversationIds: readonly string[];
+    readonly sessionIds: readonly string[];
+    readonly models: readonly string[];
+    readonly toolNames: readonly string[];
+    readonly modelCalls: number;
+    readonly toolCalls: number;
+    /** Error-bearing spans; one failure can be recorded on multiple ancestors. */
+    readonly errorSpanCount: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    /** Total gateway cost in USD; undefined when no step reported cost. */
+    readonly costUsd?: number;
+}
+/**
+ * Only agent.step spans contribute usage: model spans repeat the same counters.
+ * Operation counts collapse action/execution pairs, but error counts retain all
+ * error-bearing spans so summaries agree with the raw trace tree.
+ */
+export declare function summarizeLocalTrace(traceId: string, spans: readonly LocalTraceSpan[]): LocalTraceSummary;
+export declare function localTraceSpanCostUsd(span: LocalTraceSpan): number | undefined;

package/dist/src/tracing/local-trace-summary.js

@@ -0,0 +1 @@
+import{AGENT_USAGE_ATTRIBUTES}from"#tracing/agent-span-contract.js";import{localTraceOperations,traceModelName,traceSessionId,traceStringAttribute,traceToolName,uniqueLocalTraceSpans}from"#tracing/local-trace-operations.js";function summarizeLocalTrace(e,t){let n=uniqueLocalTraceSpans(t),r=new Set,i=new Set,a=new Set,o=new Set,s=n[0]?.startTimeNs??0n,c=s,l=0,u=0,d,f=0,p=0,m=0;for(let e of n){if(e.startTimeNs<s&&(s=e.startTimeNs),e.endTimeNs>c&&(c=e.endTimeNs),add(r,traceModelName(e)),add(i,traceStringAttribute(e,`agent.name`)),add(a,traceStringAttribute(e,`gen_ai.conversation.id`)),add(o,traceSessionId(e)),e.statusCode===2&&(f+=1),e.name!==`agent.step`)continue;p+=numberAttribute(e,`agent.usage.input_tokens`)??0,m+=numberAttribute(e,`agent.usage.output_tokens`)??0,l+=numberAttribute(e,AGENT_USAGE_ATTRIBUTES.cacheReadTokens)??numberAttribute(e,`gen_ai.usage.cache_read.input_tokens`)??0,u+=numberAttribute(e,AGENT_USAGE_ATTRIBUTES.cacheWriteTokens)??numberAttribute(e,`gen_ai.usage.cache_creation.input_tokens`)??0;let t=localTraceSpanCostUsd(e);t!==void 0&&(d=(d??0)+t)}let h=new Set,g=0,_=0;for(let e of localTraceOperations(n))e.category===`model`&&(g+=1),e.category===`tool`&&(_+=1,add(h,traceToolName(e.span)));return{traceId:e,startedAt:new Date(Number(s/1000000n)).toISOString(),durationMs:Number(c-s)/1e6,spanCount:n.length,agentNames:[...i].sort(),conversationIds:[...a].sort(),sessionIds:[...o].sort(),models:[...r].sort(),toolNames:[...h].sort(),modelCalls:g,toolCalls:_,errorSpanCount:f,cacheReadTokens:l,cacheWriteTokens:u,costUsd:d,inputTokens:p,outputTokens:m}}function localTraceSpanCostUsd(e){return numberAttribute(e,`gen_ai.usage.gateway_cost`)??numberAttribute(e,`gen_ai.usage.cost`)}function numberAttribute(e,t){let n=e.attributes[t];if(typeof n==`number`)return Number.isFinite(n)&&n>=0?n:void 0;if(typeof n==`string`&&n.trim()!==``){let e=Number(n);return Number.isFinite(e)&&e>=0?e:void 0}}function add(e,t){t!==void 0&&e.add(t)}export{localTraceSpanCostUsd,summarizeLocalTrace};

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-BUeSjwIk.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-Di1u2zKu.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-BUeSjwIk.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-Di1u2zKu.js";
 
 export { useEveAgent };

package/docs/concepts/project-structure.mdx

@@ -74,14 +74,12 @@ Use separate packages or projects when agents need independent dependencies or r
 
 Choose how the frontend and agents run together independently of how many agents you have:
 
-- **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) in `next.config.ts`. Next.js owns the application lifecycle; the integration starts agent processes and proxies requests locally, and contributes separate agent services on Vercel. A root Next.js app can sit beside either `agent/` or `agents/`; workspace members are discovered automatically.
+- **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) in `next.config.ts`. Next.js owns the application lifecycle; the integration starts agent processes and proxies requests locally, and contributes separate agent services on Vercel. A root Next.js app can sit beside either `agent/` or `agents/`; workspace members are discovered automatically. A peer app such as `apps/web/` can select its eve project with `eveRoot: "../.."`.
 - **Add a frontend to an agent workspace:** keep the frontend as a peer application, for example under `apps/web/`. On Vercel, use [`eve/vercel` in root `vercel.ts`](/docs/guides/deployment/vercel#compose-agents-with-other-vercel-services) to contribute the agents alongside the frontend service. For [self-hosting](/docs/guides/deployment/self-hosting#run-workspace-members), run the services with your process manager and configure a reverse proxy. The frontend does not need `eve/next`.
 
 `apps/web/` is an organizational convention, not an eve filesystem slot. Deployment configuration owns peer services; eve discovers only the agents. Both Vercel integrations deploy the services together, not as independent releases.
 
-The generated Web Chat installer does not support agent workspaces. Create the frontend and its agent-selection UI yourself, using the [React chat example](/docs/guides/frontend/overview#basic-chat-react). Develop a peer Next.js frontend with `next dev` separately from the agents. For an authored Vercel service graph, use `vercel dev --local` to run the composition without linking a Vercel project.
-
-For a single `agent/` project, `eve add channel/web` currently generates a root Next.js app using `eve/next`. `eve/vercel` currently requires an `agents/` workspace; it cannot compose a standalone root `agent/`.
+Run `eve add channel/web` from a standalone agent or select a workspace agent with `--agent <name>`. The installer creates a Next.js frontend under `apps/web/`. Choose **Vercel** to configure separate Vercel services and run them with `pnpm dev:services`, or **Other** to let Next.js host the agents and run the application with `pnpm dev:web`. Use `pnpm dev` or `pnpm dev:eve` when you only want one agent and the eve terminal UI.
 
 ## Add a second root agent
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -79,7 +79,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | `action.result`           | A tool call returned.                                                                                                                              |
 | `input.requested`         | The run paused for human input ([HITL](/docs/human-in-the-loop) approval or a `ctx.ask()` question); carries `requests`.                           |
 | `input.resolved`          | The server accepted terminal human-input outcomes; carries `resolutions` with responses when provided.                                             |
-| `subagent.called`         | A subagent was delegated; carries `childSessionId` to attach to.                                                                                   |
+| `subagent.called`         | A subagent was delegated; carries `childSessionId` and the `childStreamPath` that `session.streamSubagent()` follows.                              |
 | `subagent.completed`      | The parent recorded a successful subagent invocation result; carries the actual output.                                                            |
 | `reasoning.appended`      | A reasoning text delta.                                                                                                                            |
 | `reasoning.completed`     | The finalized reasoning block.                                                                                                                     |
@@ -119,7 +119,7 @@ Note: consider the privacy, confidentiality, and user-experience implications fo
 
 When a task explicitly requires conditional delivery and there is nothing new to report, the agent can finish with exactly `<eve-empty-delivery/>`. eve emits `message.completed` with `message: null` for that intentional silence. The marker must be the entire response, apart from surrounding whitespace; the HTML-escaped form `&lt;eve-empty-delivery/&gt;` is also accepted. A response that quotes the marker in prose or code is delivered normally.
 
-A delegated subagent publishes progress on its own child-session stream. The parent emits `subagent.called` with a `childSessionId`, which a client uses to attach. Both blocking and background calls emit `subagent.completed` with the actual output after the parent records a successful outcome. A background working receipt is an `action.result` tool output; it does not emit completion. Older streams can contain receipt-bearing completion events marked by `data.backgroundTask`; those are admission only. Completion does not mean that the reusable child session has ended. Background task terminal outcomes also arrive as task-triggered `message.received` notifications with `data.kind: "execution.background_task"`. The default frontend reducer retains these events in `events` but does not project their runtime-authored text as participant messages.
+A delegated subagent publishes progress on its own child-session stream. The parent emits `subagent.called` with a `childSessionId` and a `childStreamPath`, which a client follows with `session.streamSubagent()`. Both blocking and background calls emit `subagent.completed` with the actual output after the parent records a successful outcome. A background working receipt is an `action.result` tool output; it does not emit completion. Older streams can contain receipt-bearing completion events marked by `data.backgroundTask`; those are admission only. Completion does not mean that the reusable child session has ended. Background task terminal outcomes also arrive as task-triggered `message.received` notifications with `data.kind: "execution.background_task"`. The default frontend reducer retains these events in `events` but does not project their runtime-authored text as participant messages.
 
 `step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, but discards incomplete assistant output and unfinished tool state. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`).
 

package/docs/evals/cases.mdx

@@ -111,6 +111,7 @@ Every `t.session()` or `t.send()` creates a new independent conversation. Contin
 - `session.start(message, options?)` starts a text turn and returns as soon as the server accepts it. The live turn exposes `.session`, `.sessionId`, `.waitForEvent(...)`, `.cancel()`, and `.result()`.
 - `session.cancel()` requests cooperative cancellation of that session's active turn. Both `accepted` and `no_active_turn` are successful outcomes.
 - `session.sendFile(text, path, mediaType?)` attaches a local file as a data URL.
+- `session.streamSubagent(called, options?)` follows a delegated child's stream through the parent with the eval client's credentials. Pass a `subagent.called` event from that session. It also reaches children on another deployment, which `t.target.watchTurn(...)` cannot address.
 - `session.requireInputRequest(filter?)` records a gate, requires exactly one pending request, and returns it. Filters match tool name, action input, prompt, display, and option ids.
 - `session.respond(responses, options?)` answers specific pending input requests and sends them as the next turn. `session.startRespond(...)` returns a live turn for the same operation.
 - `session.respondAll(optionId)` answers every pending input request with the same option and sends the responses as the next turn.

package/docs/extensions.md

@@ -273,7 +273,9 @@ The mount is intentionally per agent. Each consumer chooses its own mount namesp
 
 When `eve dev` starts a consuming agent, it builds mounted, source-backed extensions found inside the same workspace before compiling the agent. It watches the extension source and relevant package and TypeScript configuration, then rebuilds only the affected extension. If an extension edit fails to build, the previous successful development generation keeps running.
 
-Production `eve build` expects the extension distribution to exist already. Keep `eve extension build` in the extension package's `build` and `prepare` scripts, as the scaffold does, and run workspace builds in dependency order so extensions build before their consuming agents.
+Production builds build the same extensions from source. `eve build` builds each mounted, source-backed workspace extension before it compiles the agent, and `withEve` does the same for its agents during `next build`. Production builds therefore do not depend on the extension package's `prepare` script, which package managers skip for no-op installs and with `--ignore-scripts`. eve skips an extension whose distribution was built by the same eve version and is newer than the extension's source, `package.json`, and TypeScript configuration.
+
+If an extension fails to build, the agent build stops with an error that names the extension package and its directory. Fix the reported error, or run `eve extension build` in that package directory to build it on its own.
 
 ### Override a contribution
 

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

@@ -239,9 +239,41 @@ export default eveChannel({
 
 `trustedForwarders` authorizes the verified forwarder to supply eve delegation context: principal identity, parent session lineage, and, with principal forwarding, trace-content constraints. Match it precisely: `() => true` grants this authority to every caller that passes route auth, including preview deployments accepted by `vercelOidc()`. The framework default channel rejects forwarded principals and ignores the other context.
 
+### Limiting what a forwarder may assert
+
+A forwarder accepted on its identity alone can assert any principal, including identities your tools trust directly, such as a Slack user or an app principal. When a forwarder should speak only for its own users, check what it asserts with the predicate's second argument:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+import type { SessionAuthContext } from "eve/context";
+
+const router = vercelSubject({ teamSlug: "acme", projectName: "router" });
+
+/** The router forwards only users signed in through its own identity provider. */
+function isRouterUser(context: SessionAuthContext): boolean {
+  return (
+    context.authenticator === "router-sso" &&
+    context.issuer === "router" &&
+    context.principalType === "user"
+  );
+}
+
+export default eveChannel({
+  auth: [vercelOidc()],
+  trustedForwarders: (forwarder, assertion) =>
+    forwarder.subject === router &&
+    assertion.principal !== undefined &&
+    isRouterUser(assertion.principal.current) &&
+    isRouterUser(assertion.principal.initiator),
+});
+```
+
+`assertion.principal` holds the `current` and `initiator` contexts the forwarder asserts, already stamped with `eve:forwarded-by`. `initiator` equals `current` when the sender omits it. `initiator` takes effect only on session creation; on continuation the predicate still sees the asserted `initiator`, but the session keeps its original initiator, so checking it does not constrain that pinned value. Attributes are asserted too, so check any attribute your tools trust. `assertion.principal` is absent when the predicate decides parent session lineage for a request that forwards no principal; a predicate that requires it accepts that forwarder's lineage only alongside a principal it accepts. The `ForwardedAssertion` and `TrustedForwarders` types are exported from `eve/channels/eve` for named predicates.
+
 When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller.
 
-The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Forwarded identity rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Forwarded identity rejections fail loud: a forwarded body without `trustedForwarders` configured, or with a forwarder or assertion the predicate refuses, is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
 
 Trusted parent session lineage populates `ctx.session.parent` and preserves the root session across the delegation chain. Untrusted lineage is ignored, and accepted lineage does not remove the normal root-session token cap.
 

package/docs/guides/client/streaming.mdx

@@ -241,6 +241,32 @@ Unlike `stream()`, `snapshot()` does not advance the originating
 `ClientSession`. Its returned cursor contains the fixed session ID and the exact
 stream index after the captured prefix.
 
+## Follow a subagent
+
+A delegated subagent reports its progress on its own child session. The parent stream announces each dispatch with a `subagent.called` event. Pass that event to `streamSubagent()` on the parent's session handle to follow the child:
+
+```ts
+import { isCurrentTurnBoundaryEvent } from "eve/client";
+
+const session = client.sessions.attach(parentSessionId);
+const { events } = await session.snapshot();
+const called = events.find((event) => event.type === "subagent.called");
+
+if (called?.type === "subagent.called") {
+  for await (const event of session.streamSubagent(called)) {
+    console.log(called.data.name, event.type);
+    if (isCurrentTurnBoundaryEvent(event)) break;
+  }
+}
+```
+
+`streamSubagent()` reads the event's `childStreamPath` with the parent session's host and credentials, so the same client works for local and [remote](../remote-agents) children:
+
+- A local child's path is its own session stream route on the same deployment. The channel's usual session authorization applies.
+- A remote child's path is a proxy route on the parent deployment. The parent checks that the child belongs to this session, then relays the remote child's stream with the remote agent's authored `auth` and `headers`. The client never needs the remote URL or its credentials.
+
+The child has its own cursor, starting at `0`, and reading it never advances the parent's `streamIndex`. Pass `startIndex` to resume, `follow: false` for a bounded read, and `signal` to detach. A child parks after answering and can be continued later, so stop at a turn boundary with `isCurrentTurnBoundaryEvent` when you only need the current turn. Passing a `subagent.called` event from a different session throws.
+
 ## Abort a request
 
 Pass an `AbortSignal` to cancel the POST or stream. Aborting is local transport cancellation: turns are resumable across disconnects, so detaching never stops server-side work. Use `session.cancel()` to stop the active turn, or `session.cancel({ tasks: true })` to also stop background tasks owned by the session. Cancellation is asynchronous; watch the stream for `turn.cancelled` followed by `session.waiting`, and inspect task state in a later turn to confirm task cancellation.

package/docs/guides/deployment/vercel.mdx

@@ -57,9 +57,7 @@ A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/next
 
 Use `withEve` from `eve/vercel` when the agents and other applications are peer services. The helper contributes workspace agents to a Vercel service graph; it does not manage or require a particular frontend framework. Unlike `eve/next`, this keeps the project lifecycle separate from Next.js. Both integrations deploy the agent services together in one Vercel project.
 
-`eve/vercel` currently requires an `agents/` workspace, even if it has only one member. It does not support a standalone root `agent/`.
-
-For a workspace with a peer Next.js frontend under `apps/web/`, replace `vercel.json` with a root `vercel.ts`. The frontend uses an ordinary Next.js config without `eve/next`:
+For a standalone agent or workspace with a peer Next.js frontend under `apps/web/`, replace `vercel.json` with a root `vercel.ts`. The frontend uses an ordinary Next.js config without `eve/next`:
 
 ```typescript title="vercel.ts"
 import { withEve } from "eve/vercel";
@@ -82,9 +80,9 @@ export default await withEve({
 
 Vercel evaluates `vercel.ts` before resolving the service graph. `withEve` adds the root agent, or every direct workspace member, as an independently built service and returns a plain Vercel configuration. Named workspace agents mount at `/eve/<name>/v1/*`; a root agent mounts at `/eve/v1/*`. Vercel then builds the frontend and each eve agent separately. The frontend does not need `withEve` in its framework configuration or a build script that builds the agents.
 
-The Web Chat installer does not support agent workspaces. Create the frontend using the [React chat example](../frontend/overview#basic-chat-react), and configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosting#run-workspace-members).
+The Web Chat installer can generate this composition for a standalone agent or a selected workspace agent. Configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosting#run-workspace-members).
 
-Run Vercel CLI 59.16.0 or newer with `vercel dev --local` to start the complete service graph locally. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials. Run `eve dev` instead when you only need one agent and the eve terminal UI.
+Run Vercel CLI 59.16.0 or newer with `vercel dev` to start the complete service graph locally. A generated Vercel Web Chat project exposes this as `pnpm dev:services`; the first run links the directory when needed and linked projects load their development environment and settings. Use `pnpm dev` or `pnpm dev:eve` when you want one agent and the eve terminal UI, or `pnpm dev:web` when you want the frontend without its agent services. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials.
 
 Generated transport routes are inserted before a filesystem handler or, when no filesystem handler exists, before authored routes. `withEve` throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove the authored route, and remove or rename the authored service; `withEve` adds both automatically. Names in the array form of `services` must also be unique. Other service names, routes, bindings, and Cron Jobs remain authored in `vercel.ts`.
 
@@ -124,6 +122,8 @@ eve deploy
 
 `eve deploy` installs dependencies, runs `vercel deploy --prod`, and pulls the project environment after deployment. You can also push to a Git-connected Vercel project. Hosted Vercel builds set `VERCEL`, so `eve build` writes the deployment bundle under `.vercel/output`.
 
+When `eve deploy` creates a new Vercel project, it configures trace sampling so traces appear in Agent Runs automatically. See [Agent Runs](../../observability/agent-runs) for details. Pass `--no-trace-sampling` to skip this setting.
+
 For non-interactive use, confirm the production deploy up front. `--project` links first, so a new project needs no separate `eve link`:
 
 ```bash

package/docs/guides/frontend/nextjs.mdx

@@ -80,13 +80,26 @@ Generated agent services build with `EVE_PUBLIC_ROUTE_PREFIX` set to the agent's
 
 All fields are optional.
 
-| Option               | Type                  | Default                  | Purpose                                                                                                                                                                                                                                          |
-| -------------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `eveRoot`            | `string`              | Next.js app root         | Path to one unnamed eve app root, relative to `process.cwd()` unless absolute. Do not combine with `agents`.                                                                                                                                     |
-| `agents`             | `Record<string, ...>` | inferred for a workspace | Named eve agents to mount under `/eve/<name>/v1/*`. `withEve()` discovers project-level `agents/<name>/` members when neither `agents` nor `eveRoot` is set; otherwise each value is a root string or `{ root, buildCommand?, servicePrefix? }`. |
-| `eveBuildCommand`    | `string`              | generated                | Build command for generated eve Vercel services. In multi-agent mode this is the default for agents without their own `buildCommand`.                                                                                                            |
-| `servicePrefix`      | `string`              | `"/_eve_internal/eve"`   | Private route namespace for legacy manual Vercel service configs and non-Vercel production proxying. Named agents derive unique defaults from this prefix.                                                                                       |
-| `devServerTimeoutMs` | `number`              | `180000`                 | Maximum time to wait for each eve development server to become available.                                                                                                                                                                        |
+| Option               | Type                  | Default                  | Purpose                                                                                                                                                                                                                                     |
+| -------------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eveRoot`            | `string`              | Next.js app root         | Eve project root, relative to the Next.js app root unless absolute. It may contain either one `agent/` or an `agents/` workspace. Do not combine with `agents`.                                                                             |
+| `agents`             | `Record<string, ...>` | inferred for a workspace | Named eve agents to mount under `/eve/<name>/v1/*`. `withEve()` discovers project-level `agents/<name>/` members when `agents` and `eveRoot` are unset; otherwise each value is a root string or `{ root, buildCommand?, servicePrefix? }`. |
+| `eveBuildCommand`    | `string`              | generated                | Build command for generated eve Vercel services. In multi-agent mode this is the default for agents without their own `buildCommand`.                                                                                                       |
+| `servicePrefix`      | `string`              | `"/_eve_internal/eve"`   | Private route namespace for legacy manual Vercel service configs and non-Vercel production proxying. Named agents derive unique defaults from this prefix.                                                                                  |
+| `devServerTimeoutMs` | `number`              | `180000`                 | Maximum time to wait for each eve development server to become available.                                                                                                                                                                   |
+
+When the Next.js app is a peer of an eve project, select its root without repeating every agent path. The root may contain either one `agent/` or an `agents/` workspace:
+
+```ts title="apps/web/next.config.ts"
+import type { NextConfig } from "next";
+import { withEve } from "eve/next";
+
+const nextConfig: NextConfig = {};
+
+export default withEve(nextConfig, {
+  eveRoot: "../..",
+});
+```
 
 For slow cold starts, increase the development timeout:
 

package/docs/guides/frontend/overview.mdx

@@ -172,7 +172,7 @@ supplied `session` remains externally owned and is never replaced by prewarming
 
 `data.messages` are eve-owned `EveMessage[]`. Common text, reasoning, file, and dynamic-tool parts follow the [AI SDK `UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) rendering convention, but the types are not interchangeable. eve also exposes authorization and HITL metadata, and a file part's URL can be absent. Adapt those parts before passing messages to an API typed as `UIMessage[]`.
 
-When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` when the parent records a successful result, for both blocking and background invocations. A background working receipt appears in `action.result`, without a completion event. The child session can remain available for reuse. Task notifications wake the parent with completion, failure, or cancellation. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. Use the lower-level [TypeScript client](../client/overview#sessions) to attach to that ID when your UI needs live subagent activity. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
+When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` when the parent records a successful result, for both blocking and background invocations. A background working receipt appears in `action.result`, without a completion event. The child session can remain available for reuse. Task notifications wake the parent with completion, failure, or cancellation. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. When your UI needs live subagent activity, attach a [client session](../client/overview#sessions) to the parent and pass the `subagent.called` event from `events` to [`streamSubagent()`](../client/streaming#follow-a-subagent). It follows local and remote children through the parent, so the browser never calls a remote deployment directly. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
 
 ## Sending and streaming
 

package/docs/guides/instrumentation/agent-runs.mdx

@@ -28,10 +28,10 @@ Omitting `agent/instrumentation/agent-runs.ts` preserves that default. Export
 
 ## Enable tracing on Vercel
 
-New eve deployments automatically sample 100% of requests. Existing eve
-deployments need a sampling rule configured for the Vercel project to collect
-traces. To enable tracing for an existing deployment, select your team and
-project, then open
+When `eve deploy` creates a new Vercel project, it configures 100% trace
+sampling for all environments. Existing Vercel projects need a sampling rule
+configured to collect traces. To enable tracing for an existing project, select
+your team and project, then open
 [**Settings → Tracing**](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Ftracing&title=Go+to+Tracing+settings):
 
 1. Select **Add Sampling Rule**.

package/docs/guides/remote-agents.md

@@ -138,7 +138,7 @@ This makes caller authority turn-scoped even when the remote child session is pe
 
 Identity forwarding does not make a persistent session private to one caller. Conversation history, tool outputs, and other child-session state still persist. If those values must not be visible across users, give each user a distinct child session or enforce that ownership at the application boundary.
 
-Forwarding identity is explicit on both sides. The receiver names which deployments it trusts with `eveChannel({ trustedForwarders })` (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); refusing the forwarder rejects a forwarded principal with a 403. The same trust decision covers parent session lineage and, with principal forwarding, trace-content constraints.
+Forwarding identity is explicit on both sides. The receiver names which deployments it trusts with `eveChannel({ trustedForwarders })` and can limit each one to the principals it may assert (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); refusing the forwarder or what it asserts rejects a forwarded principal with a 403. The same trust decision covers parent session lineage and, with principal forwarding, trace-content constraints.
 
 ## Trace propagation
 
@@ -192,6 +192,8 @@ A remote subagent runs as a durable background task in its own deployment:
 
 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.
 
+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.
+
 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.
 
 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.

package/docs/install-integrations.mdx

@@ -19,7 +19,7 @@ eve add memory/file
 
 If an item is not found, `eve add` searches the available catalogs and prints close matches without installing anything.
 
-Web Chat installs a project-level Next.js application. It cannot be added to an eve agent workspace; eve rejects the installation before writing files. See [Project Structure](./concepts/project-structure) for browser-app placement and [Next.js](./guides/frontend/nextjs) for manual integration.
+Web Chat installs a shared Next.js application at `apps/web` for either a standalone agent or a selected member of an agent workspace. Choose **Vercel services** (recommended) to deploy Web Chat and agents as separate services, or **Next.js** to serve Web Chat and route agent requests through one Next.js app. Existing authored Next.js or Vercel configuration is preserved, and eve stops with manual composition guidance instead of overwriting it. See [Project Structure](./concepts/project-structure) for browser-app placement and [Next.js](./guides/frontend/nextjs) for Next.js-owned integration.
 
 If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search <query>`.
 

package/docs/reference/agent-files.md

@@ -64,6 +64,22 @@ Paths below are relative to the agent directory. Root agents can use every path;
 | `schedules/`                                            | Recurring jobs                            | No                     | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported.                                   |
 | `subagents/`                                            | Specialist child agents                   | Yes                    | Local directories or remote-agent definitions; nested subagents are supported.                                                          |
 
+## Colocated tests
+
+eve ignores JavaScript and TypeScript modules named `*.test.*` or `*.spec.*`,
+along with `__tests__/` directories, during automatic discovery and when choosing
+extension runtime entries.
+
+```text
+agent/tools/
+├── get_weather.ts          # registered as get_weather
+├── get_weather.test.ts     # excluded from discovery
+└── __tests__/              # excluded from discovery
+    └── fixtures.json
+```
+
+Explicit imports, sandbox workspace files, and packaged skill resources are unaffected.
+
 ## Files available in the sandbox
 
 Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's `/workspace/` under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).

package/docs/reference/cli.md

@@ -311,7 +311,7 @@ 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, 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.
+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.
 

package/docs/subagents/index.mdx

@@ -9,6 +9,12 @@ Use a subagent to run independent work in parallel, narrow the available tools,
 - Use a [declared local subagent](#declared-subagents) for a specialist with its own directory and authored capabilities, rather than inheriting the root's.
 - Use a [remote agent](./guides/remote-agents) to delegate to a separately deployed eve agent, with its own configuration and authentication.
 
+A subagent can finish a model turn while background tasks started in that turn are still running.
+That turn yields; its interim reply does not complete the caller's delegated task. Background work started by an earlier turn does not hold the reply, and a turn that ends with an error always answers the caller. If the child session expires, resets, or closes before replying, the delegated task fails and reports the usage accumulated since its previous settlement.
+After the nested tasks finish, the subagent resumes and returns its final result to
+the caller. This applies to root-agent copies, declared local subagents, and remote
+subagents. The subagent session remains available for later calls.
+
 ## Completion batching
 
 Overlapping background work owned by a session forms a cohort. Tasks launched in
@@ -99,7 +105,7 @@ The parent can alternatively export `disableTool()` from a same-named tool path,
 
 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.
 
-`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. Cancelling a delegated agent task also requests cancellation of its child's nested background tasks, even after that child's model turn has yielded. The child does not start another model turn for notifications from that cancelled work. This applies to self, local, and remote delegation. The calling model receives the cancellation receipt in the `task_cancel` result; a later report of that same outcome does not start another model turn.
 
 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.
 
@@ -253,7 +259,7 @@ By default, a subagent named `researcher` collides with an authored tool named `
 
 Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 
-Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events `subagent.called` and `subagent.completed`, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
+Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events `subagent.called` and `subagent.completed`, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, pass the `subagent.called` event to [`session.streamSubagent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent. It reads `subagent.called.data.childStreamPath`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
 
 Both blocking and background invocations emit `subagent.called` after dispatch and `subagent.completed` after the parent records successful completion. Completion carries the actual output and identifies the same invocation by `callId`; the child session can remain available for reuse. A background working receipt is returned as an `action.result` tool output and does not emit completion. Background completion events do not wait for the cohort report. Failure and cancellation are not successful completion; task notifications retain those outcomes.
 

package/package.json

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

package/dist/src/internal/nitro/host/dev-workspace-extensions.d.ts

@@ -1,18 +0,0 @@
-import { type ExtensionBuildConfig } from "#internal/nitro/host/build-extension.js";
-/** Build inputs retained with a prepared dev host for path-scoped extension HMR. */
-export interface DevelopmentWorkspaceExtension {
-    readonly config: ExtensionBuildConfig;
-    /** Canonical package root, with workspace links resolved. */
-    readonly packageRoot: string;
-    /** Non-source inputs that affect publisher output, such as tsconfig files. */
-    readonly buildConfigPaths: readonly string[];
-}
-/**
- * Builds mounted source-backed workspace extensions before the consuming agent
- * compiles and returns the inputs needed to scope the next development rebuild.
- */
-export declare function prepareDevelopmentWorkspaceExtensions(input: {
-    readonly appRoot: string;
-    readonly changedPaths?: readonly string[];
-    readonly previousExtensions?: readonly DevelopmentWorkspaceExtension[];
-}): Promise<readonly DevelopmentWorkspaceExtension[]>;