eve 0.29.2 → 0.29.4

package/dist/src/{harness → tracing}/agent-otel-provider.d.ts

@@ -1,11 +1,14 @@
 import { type SpanContext, type Tracer } from "#compiled/@opentelemetry/api/index.js";
 import type { InstrumentationContextRunner, InstrumentationProviderDefinition, InstrumentationTurnTerminalEvent } from "#harness/instrumentation-lifecycle.js";
+/** Sized so an ordinary session stays one trace and only an outsized one rolls. */
+export declare const SESSION_WINDOW_TURN_LIMIT = 200;
 export interface AgentSessionTraceState {
     readonly agentName?: string;
     readonly channelKind?: string;
     readonly context: SpanContext;
-    readonly pendingStarted: boolean;
     readonly rootSessionId: string;
+    readonly turnsInWindow: number;
+    readonly window: number;
 }
 export interface AgentTurnTraceState {
     readonly context: SpanContext;
@@ -36,6 +39,12 @@ export declare class InMemoryAgentTraceStateStore implements AgentTraceStateStor
     setTurn(sessionId: string, turnId: string, state: AgentTurnTraceState): void;
 }
 export interface AgentOtelInstrumentationInput {
+    /**
+     * Capture model prompts/responses and tool call inputs/outputs as span
+     * attributes. Content stays on the local machine — this provider only
+     * wires the dev-time local spool — but can be turned off per project.
+     */
+    readonly captureContent?: boolean;
     readonly frameworkVersion: string;
     readonly stateStore: AgentTraceStateStore;
     readonly tracer: Tracer;

package/dist/src/tracing/agent-otel-provider.js

@@ -0,0 +1,2 @@
+import{ROOT_CONTEXT,SpanStatusCode,context,trace}from"#compiled/@opentelemetry/api/index.js";import{contentAttribute,messagesContentAttribute,systemPromptAttribute,textContentAttribute,toolResultsContentAttribute}from"#tracing/agent-otel-content.js";const SESSION_WINDOW_TURN_LIMIT=200;var InMemoryAgentTraceStateStore=class{#e=new Map;#t=new Map;deleteSession(e){this.#e.delete(e)}deleteTurn(e,t){this.#t.delete(turnKey(e,t))}getSession(e){return this.#e.get(e)}getTurn(e,t){return this.#t.get(turnKey(e,t))}setSession(e,t){this.#e.set(e,t)}setTurn(e,t,n){this.#t.set(turnKey(e,t),n)}};function createAgentOtelInstrumentation(e){let t=e.captureContent??!0,l=new WeakMap,u=new WeakMap,onSessionStarted=async e=>{await ensureSessionContext(e)},onTurnStarted=async t=>{let n=advanceSessionWindow(t.sessionId,await ensureSessionContext({agentName:void 0,channelKind:void 0,parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId,sessionId:t.sessionId,type:`session.started`})),r=e.tracer.startSpan(`agent.turn`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":n.agentName,...parentLineageAttributes(t.parentLineage),"agent.root.session.id":t.rootSessionId,"agent.session.id":t.sessionId,"agent.session.window":n.window,"agent.turn.id":t.turnId,"agent.turn.sequence":t.sequence}},contextFromSpanContext(n.context));r.addEvent(`turn.started`),await e.stateStore.setSession(t.sessionId,{...n,turnsInWindow:n.turnsInWindow+1}),await e.stateStore.setTurn(t.sessionId,t.turnId,{context:r.spanContext(),rootSessionId:t.rootSessionId,sequence:t.sequence}),r.end()},onAttemptStarted=async t=>{let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);if(n===void 0)return;let i=contextFromSpanContext(n.context),a=e.tracer.startSpan(`agent.step`,{attributes:{"agent.session.id":t.scope.sessionId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.root.session.id":t.scope.rootSessionId??t.scope.sessionId,"agent.step.attempt":t.scope.attemptIndex,"agent.step.index":t.scope.stepIndex,"agent.turn.id":t.scope.turnId,"agent.name":t.scope.functionId}},i);a.addEvent(`step.started`);let o=trace.setSpan(i,a),s=t.operation.operationId,c=e.tracer.startSpan(s,{attributes:{"gen_ai.operation.name":s,"gen_ai.provider.name":t.operation.provider,"gen_ai.request.model":t.operation.modelId}},o);u.set(t.scope,{operation:{context:trace.setSpan(o,c),name:s,span:c},step:{context:o,span:a}})},onAttemptTerminal=e=>{l.delete(e.scope);let t=u.get(e.scope);t!==void 0&&(t.step.span.addEvent(e.type===`attempt.completed`?`step.completed`:`step.failed`),e.type===`attempt.failed`&&(recordError(t.operation.span,e.error),recordError(t.step.span,e.error)),t.operation.span.end(),t.step.span.end(),u.delete(e.scope))},onTurnTerminal=async t=>{let n=await e.stateStore.getTurn(t.sessionId,t.turnId);n!==void 0&&await e.stateStore.setTurn(t.sessionId,t.turnId,{...n,terminal:{error:t.error,type:t.type}})},onSessionTransition=async t=>{if(t.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0){let r=e.tracer.startSpan(`agent.turn.terminal`,{attributes:{"agent.root.session.id":n.rootSessionId,"agent.session.id":t.sessionId,"agent.turn.id":t.turnId,"agent.turn.sequence":n.sequence}},contextFromSpanContext(n.context));n.terminal!==void 0&&(r.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordError(r,n.terminal.error)),r.addEvent(t.type),r.end(),await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&await e.stateStore.deleteSession(t.sessionId)},beforeModelCall=n=>{let i=u.get(n.scope);if(i===void 0)return;i.step.span.setAttribute(`agent.model.id`,n.source.modelId),i.step.span.setAttribute(`agent.model.provider`,n.source.provider);let s=e.tracer.startSpan(modelSpanName(i.operation.name),{attributes:{"gen_ai.operation.name":i.operation.name,"gen_ai.provider.name":n.source.provider,"gen_ai.request.model":n.source.modelId}},i.operation.context);if(t){let e=messagesContentAttribute(n.source.messages);e!==void 0&&s.setAttribute(`ai.prompt.messages`,e);let t=systemPromptAttribute(n.source.instructions);t!==void 0&&s.setAttribute(`ai.prompt.system`,t)}let c={context:trace.setSpan(i.operation.context,s),span:s};return getExecutionContexts(n.scope).models.set(n.id,c.context),c},afterModelCall=(e,n)=>{if(l.get(e.scope)?.models.delete(e.id),isSpanState(n)){if(e.type===`model.call.failed`)recordError(n.span,e.error);else{setUsage(n.span,e.source.usage);let r=u.get(e.scope);if(r!==void 0&&setUsage(r.step.span,e.source.usage),t){n.span.setAttribute(`ai.response.finish_reason`,e.source.finishReason);let t=textContentAttribute(e.source.content.filter(e=>e.type===`reasoning`).map(e=>e.text).filter(e=>e.trim().length>0).join(`
+`));t!==void 0&&n.span.setAttribute(`ai.response.reasoning`,t);let r=textContentAttribute(e.source.content.filter(e=>e.type===`text`).map(e=>e.text).join(``));r!==void 0&&n.span.setAttribute(`ai.response.text`,r);let a=e.source.content.filter(e=>e.type===`tool-call`).map(e=>({input:e.input,toolName:e.toolName}));if(a.length>0){let e=contentAttribute(a,!1);e!==void 0&&n.span.setAttribute(`ai.response.tool_calls`,e)}let o=e.source.content.filter(e=>e.type===`tool-result`||e.type===`tool-error`).map(e=>e.type===`tool-result`?{input:e.input,output:e.output,toolName:e.toolName}:{error:errorText(e.error),input:e.input,toolName:e.toolName});if(o.length>0){let e=toolResultsContentAttribute(o);e!==void 0&&n.span.setAttribute(`ai.response.tool_results`,e)}}}n.span.end()}},beforeToolCall=n=>{let a=u.get(n.scope);if(a===void 0)return;let o=e.tracer.startSpan(`agent.action`,{attributes:{"agent.action.call_id":n.source.toolCall.toolCallId,"agent.action.kind":`tool`,"agent.action.name":n.source.toolCall.toolName,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.root.session.id":n.scope.rootSessionId??n.scope.sessionId,"agent.session.id":n.scope.sessionId,"agent.step.attempt":n.scope.attemptIndex,"agent.step.index":n.scope.stepIndex,"agent.turn.id":n.scope.turnId}},a.step.context),s=trace.setSpan(a.step.context,o),c=e.tracer.startSpan(`ai.toolCall`,{attributes:{"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":n.source.toolCall.toolCallId,"gen_ai.tool.name":n.source.toolCall.toolName}},s);if(t){let e=contentAttribute(n.source.toolCall.input,!1);e!==void 0&&c.setAttribute(`gen_ai.tool.call.arguments`,e)}let l={context:trace.setSpan(s,c),span:o,toolSpan:c};return getExecutionContexts(n.scope).tools.set(n.id,l.context),l},afterToolCall=(e,n)=>{if(l.get(e.scope)?.tools.delete(e.id),isToolSpanState(n)){if(e.type===`tool.call.failed`)recordError(n.toolSpan,e.error),recordError(n.span,e.error);else if(e.source.toolOutput.type!==`tool-result`)recordError(n.toolSpan,e.source.toolOutput.error),recordError(n.span,e.source.toolOutput.error);else if(t){let t=contentAttribute(e.source.toolOutput.output,!1);t!==void 0&&n.toolSpan.setAttribute(`gen_ai.tool.call.result`,t)}n.toolSpan.end(),n.span.end()}},openSessionWindow=t=>{let n=e.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":t.agentName,"agent.root.session.id":t.rootSessionId,"agent.session.id":t.sessionId,"agent.session.window":t.index,...t.previousTraceId===void 0?{}:{"agent.session.window.previous.trace.id":t.previousTraceId}},root:!0});return n.addEvent(t.index===0?`session.started`:`session.window.opened`),n.end(),n.spanContext()},ensureSessionContext=async t=>{let n=await e.stateStore.getSession(t.sessionId);return n===void 0&&(n={agentName:t.agentName,channelKind:t.channelKind,context:t.parentTraceContext===void 0?openSessionWindow({agentName:t.agentName,index:0,rootSessionId:t.rootSessionId,sessionId:t.sessionId}):adoptedSpanContext(t.parentTraceContext),rootSessionId:t.rootSessionId,turnsInWindow:0,window:0},await e.stateStore.setSession(t.sessionId,n)),n},advanceSessionWindow=(e,t)=>{if(t.turnsInWindow<200)return t;let n=t.window+1;return{...t,context:openSessionWindow({agentName:t.agentName,index:n,previousTraceId:t.context.traceId,rootSessionId:t.rootSessionId,sessionId:e}),turnsInWindow:0,window:n}};return{hook:{events:{"attempt.completed":onAttemptTerminal,"attempt.failed":onAttemptTerminal,"attempt.metadata":e=>{let t=u.get(e.scope);if(t===void 0)return;let n=readGatewayCost(e.providerMetadata);if(n!==void 0)for(let[e,r]of Object.entries(n))t.step.span.setAttribute(e,r)},"attempt.started":onAttemptStarted,"model.call":{after:afterModelCall,before:beforeModelCall},"session.completed":onSessionTransition,"session.failed":onSessionTransition,"session.started":onSessionStarted,"session.waiting":onSessionTransition,"tool.call":{after:afterToolCall,before:beforeToolCall},"turn.cancelled":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted}},runInContext(e,t){let r=l.get(e.scope),i=e.type===`model.call`?r?.models.get(e.id):r?.tools.get(e.id);return i===void 0?t():context.with(i,t)}};function getExecutionContexts(e){let t=l.get(e);return t===void 0&&(t={models:new Map,tools:new Map},l.set(e,t)),t}}function turnKey(e,t){return`${e}:${t}`}function parentLineageAttributes(e){if(e===void 0)return{};let t={"agent.parent.call_id":e.callId,"agent.parent.session.id":e.sessionId,"agent.parent.turn.id":e.turnId};return e.subagentName!==void 0&&(t[`agent.subagent.name`]=e.subagentName),t}function adoptedSpanContext(e){return{isRemote:!1,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function contextFromSpanContext(t){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t))}function readGatewayCost(e){let t=e.gateway;if(!isRecord(t))return;let n={},r=readUsd(t.cost);r!==void 0&&(n[`gen_ai.usage.cost`]=r);let i=readUsd(t.gatewayCost);i!==void 0&&(n[`gen_ai.usage.gateway_cost`]=i);let a=readUsd(t.inputInferenceCost);a!==void 0&&(n[`gen_ai.usage.input_cost`]=a);let o=readUsd(t.outputInferenceCost);return o!==void 0&&(n[`gen_ai.usage.output_cost`]=o),typeof t.generationId==`string`&&t.generationId.length>0&&(n[`gen_ai.generation.id`]=t.generationId),Object.keys(n).length===0?void 0:n}function readUsd(e){if(typeof e!=`string`)return;let t=Number(e);return Number.isFinite(t)?t:void 0}function isSpanState(e){return typeof e==`object`&&!!e&&`context`in e&&`span`in e}function isToolSpanState(e){return isSpanState(e)&&`toolSpan`in e}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function modelSpanName(e){return e===`ai.generateText`?`ai.generateText.doGenerate`:`ai.streamText.doStream`}function setUsage(e,t){t.inputTokens!==void 0&&e.setAttribute(`agent.usage.input_tokens`,t.inputTokens),t.outputTokens!==void 0&&e.setAttribute(`agent.usage.output_tokens`,t.outputTokens);let n=t.inputTokenDetails;n?.cacheReadTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_read.input_tokens`,n.cacheReadTokens),n?.cacheWriteTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_creation.input_tokens`,n.cacheWriteTokens)}function errorText(e){return e instanceof Error?e.message:e}function recordError(e,n){n instanceof Error?(e.recordException(n),e.setStatus({code:SpanStatusCode.ERROR,message:n.message})):e.setStatus({code:SpanStatusCode.ERROR})}export{InMemoryAgentTraceStateStore,SESSION_WINDOW_TURN_LIMIT,createAgentOtelInstrumentation};

package/dist/src/{harness → tracing}/agent-trace-context-store.d.ts

@@ -1,6 +1,13 @@
-import type { AgentSessionTraceState, AgentTraceStateStore, AgentTurnTraceState } from "#harness/agent-otel-provider.js";
+import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
+import type { AgentSessionTraceState, AgentTraceStateStore, AgentTurnTraceState } from "#tracing/agent-otel-provider.js";
 /** Keeps only framework trace state from an interrupted step's context changes. */
 export declare function preserveSerializedAgentTraceState(original: Record<string, unknown>, interrupted: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Reads a named session's trace window straight out of a serialized context,
+ * which {@link ContextAgentTraceStateStore} cannot do — its reads are scoped
+ * to the ambient session.
+ */
+export declare function readSessionTraceContext(serializedContext: Readonly<Record<string, unknown>>, sessionId: string): SpanContext | undefined;
 /** Durable trace state backed by eve's serialized Workflow context. */
 export declare class ContextAgentTraceStateStore implements AgentTraceStateStore {
     deleteSession(sessionId: string): void;

package/dist/src/tracing/agent-trace-context-store.js

@@ -0,0 +1 @@
+import{contextStorage,loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";const AgentTraceContextKey=new ContextKey(`eve.harness.agentTrace`,{codec:{deserialize:deserializeState,serialize:serializeState}});function preserveSerializedAgentTraceState(e,t){let n=t[AgentTraceContextKey.name];return n===void 0?e:{...e,[AgentTraceContextKey.name]:n}}function readSessionTraceContext(e,t){let n=e[AgentTraceContextKey.name];if(n!==void 0)return deserializeState(n).sessions[t]?.context}var ContextAgentTraceStateStore=class{deleteSession(e){updateState(t=>{let n={...t.sessions};return delete n[e],{...t,sessions:n}})}deleteTurn(e,t){updateState(n=>{let r={...n.turns};return delete r[turnKey(e,t)],{...n,turns:r}})}getSession(t){return contextStorage.getStore()?.get(AgentTraceContextKey)?.sessions[t]}getTurn(t,n){return contextStorage.getStore()?.get(AgentTraceContextKey)?.turns[turnKey(t,n)]}setSession(e,t){updateState(n=>({...n,sessions:{...n.sessions,[e]:t}}))}setTurn(e,t,n){updateState(r=>({...r,turns:{...r.turns,[turnKey(e,t)]:n}}))}};function updateState(e){loadContext().set(AgentTraceContextKey,t=>e(t??{sessions:{},turns:{}}))}function turnKey(e,t){return`${e}\0${t}`}function serializeState(e){return{sessions:Object.fromEntries(Object.entries(e.sessions).map(([e,t])=>[e,{...t,context:serializeSpanContext(t.context)}])),turns:Object.fromEntries(Object.entries(e.turns).map(([e,t])=>[e,{...t,context:serializeSpanContext(t.context),terminal:t.terminal===void 0?void 0:{error:serializeError(t.terminal.error),type:t.terminal.type}}]))}}function deserializeState(e){return isRecord(e)?{sessions:deserializeRecord(e.sessions,e=>{if(!(!isRecord(e)||!isSpanContext(e.context)))return{agentName:typeof e.agentName==`string`?e.agentName:void 0,channelKind:typeof e.channelKind==`string`?e.channelKind:void 0,context:e.context,rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,turnsInWindow:typeof e.turnsInWindow==`number`?e.turnsInWindow:0,window:typeof e.window==`number`?e.window:0}}),turns:deserializeRecord(e.turns,e=>{if(!(!isRecord(e)||!isSpanContext(e.context)))return{context:e.context,rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,sequence:typeof e.sequence==`number`?e.sequence:0,terminal:deserializeTerminal(e.terminal)}})}:{sessions:{},turns:{}}}function deserializeRecord(e,t){if(!isRecord(e))return{};let n={};for(let[r,i]of Object.entries(e)){let e=t(i);e!==void 0&&(n[r]=e)}return n}function deserializeTerminal(e){if(!isRecord(e)||typeof e.type!=`string`)return;let t=e.type;if(isTurnTerminalType(t))return{error:deserializeError(e.error),type:t}}function serializeSpanContext(e){return{isRemote:e.isRemote,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function isSpanContext(e){return isRecord(e)&&typeof e.spanId==`string`&&typeof e.traceFlags==`number`&&typeof e.traceId==`string`}function serializeError(e){return e instanceof Error?{message:e.message,name:e.name,stack:e.stack}:void 0}function deserializeError(e){if(!isRecord(e)||typeof e.message!=`string`)return;let t=Error(e.message);return typeof e.name==`string`&&(t.name=e.name),typeof e.stack==`string`&&(t.stack=e.stack),t}function isTurnTerminalType(e){return e===`turn.cancelled`||e===`turn.completed`||e===`turn.failed`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{ContextAgentTraceStateStore,preserveSerializedAgentTraceState,readSessionTraceContext};

package/dist/src/{harness → tracing}/agent-trace-span-processor.d.ts

@@ -9,7 +9,11 @@ export declare class AgentTraceSpanProcessor implements SpanProcessor {
     onEnd(span: unknown): void;
     /** Trace ids whose session is still open, so retention never evicts them. */
     activeTraceIds(): ReadonlySet<string>;
-    /** Forgets one session's trace, reporting whether it owned one. */
+    /**
+     * Forgets every trace one root session owned, reporting whether it owned any.
+     * A subagent child owns none, so releasing one reports `false` and leaves the
+     * shared trace pinned until its root finishes.
+     */
     releaseSession(sessionId: string): boolean;
     shutdown(): Promise<void>;
 }

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

@@ -0,0 +1 @@
+var AgentTraceSpanProcessor=class{#e;#t=new Set;#n=new Map;#r=!1;constructor(e){this.#e=e}async forceFlush(){await Promise.all(this.#e.map(e=>e.forceFlush()))}isAttached(){return this.#r}onStart(e,t){if(this.#r=!0,!isSpanLike(e))return;let n=e.attributes[`agent.session.id`];if(typeof n==`string`){let t=e.attributes[`agent.root.session.id`],r=typeof t==`string`?t:n,i=e.spanContext().traceId;this.#t.add(i);let a=this.#n.get(r)??new Set;a.add(i),this.#n.set(r,a)}if(this.#i(e))for(let n of this.#e)n.onStart(e,t)}onEnd(e){if(!(!isSpanLike(e)||!this.#i(e)))for(let t of this.#e)t.onEnd(e)}activeTraceIds(){return this.#t}releaseSession(e){let t=this.#n.get(e);if(t===void 0)return!1;for(let e of t)this.#t.delete(e);return this.#n.delete(e),!0}async shutdown(){await Promise.all(this.#e.map(e=>e.shutdown()))}#i(e){return e.instrumentationScope?.name!==`workflow`&&this.#t.has(e.spanContext().traceId)}};function isSpanLike(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}export{AgentTraceSpanProcessor};

package/dist/src/tracing/local-instrumentation-runtime.js

@@ -0,0 +1 @@
+import{ContextAgentTraceStateStore}from"#tracing/agent-trace-context-store.js";import{getInstrumentationRuntime,registerInstrumentationRuntime}from"#harness/instrumentation-runtime.js";import{context,trace}from"#compiled/@opentelemetry/api/index.js";import{registerOTel}from"#compiled/@vercel/otel/index.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{createInstrumentationHooks}from"#harness/instrumentation-lifecycle.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";function installLocalInstrumentationRuntime(t){let n=getInstrumentationRuntime();if(n!==void 0)return n;let r=resolveLocalTraceRetentionSettings(),i=new AgentTraceSpanProcessor(r.enabled?[new LocalTraceSpanProcessor(t.appRoot)]:[]);registerOTel({autoDetectResources:!1,instrumentations:[],propagators:[`none`],serviceName:t.serviceName,spanProcessors:[i]});let a=trace.getTracer(`eve.registration`).startSpan(`eve.otel.registration`),o=trace.setSpan(context.active(),a),s=context.with(o,()=>trace.getActiveSpan()===a);if(a.end(),!i.isAttached()||!s)throw Error(`eve could not register OpenTelemetry because another runtime already exists.`);let c=createAgentOtelInstrumentation({captureContent:process.env.EVE_TRACES_CONTENT!==`off`,frameworkVersion:t.frameworkVersion,stateStore:new ContextAgentTraceStateStore,tracer:trace.getTracer(`eve.agent`,t.frameworkVersion)}),l={events:{"session.completed":releaseSessionTrace,"session.failed":releaseSessionTrace}};return requestPrune(),registerInstrumentationRuntime({forceFlush:()=>i.forceFlush(),hooks:createInstrumentationHooks([c.hook,l]),runInContext:c.runInContext});async function releaseSessionTrace(e){await i.forceFlush(),i.releaseSession(e.sessionId)&&requestPrune()}function requestPrune(){r.enabled&&requestLocalTraceStorePrune({activeTraceIds:i.activeTraceIds(),appRoot:t.appRoot,maxAgeMs:r.maxAgeMs,maxTotalBytes:r.maxTotalBytes,retainCount:r.retainCount})}}export{installLocalInstrumentationRuntime};

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

@@ -0,0 +1,74 @@
+/**
+ * Reads the local trace spool written by {@link LocalTraceSpanProcessor}.
+ *
+ * The spool is the contract between the dev-time writer and every viewer
+ * (`eve traces`, the TUI trace viewer): one directory per trace under
+ * `.eve/traces/v1/<traceId>/segments/`, one immutable OTLP/JSON file per
+ * span. Parsing is defensive end to end — malformed or oversized segments
+ * are skipped so a partial write never breaks a view.
+ */
+export interface LocalTraceSpan {
+    readonly attributes: Readonly<Record<string, unknown>>;
+    readonly endTimeNs: bigint;
+    readonly name: string;
+    readonly parentSpanId?: string;
+    readonly scope?: string;
+    readonly spanId: string;
+    readonly startTimeNs: bigint;
+    readonly statusCode: number;
+    readonly traceId: string;
+}
+export interface LocalTrace {
+    readonly agentName?: string;
+    readonly endTimeNs: bigint;
+    /** Session that opened the trace, which is the one the list shows. */
+    readonly sessionId?: string;
+    /**
+     * Every session recorded in the trace, opener first.
+     *
+     * A subagent child records into the window its parent had open, so one
+     * trace can hold several sessions and any of their ids resolves to it.
+     */
+    readonly sessionIds: readonly string[];
+    readonly spans: readonly LocalTraceSpan[];
+    readonly startTimeNs: bigint;
+    readonly traceId: string;
+    /** Zero-based session window this trace holds, when the spans record one. */
+    readonly window?: number;
+}
+/**
+ * Trace ids held by the spool, unordered. Empty when nothing has been written
+ * yet; any other read fault propagates.
+ */
+export declare function listLocalTraceIds(appRoot: string): Promise<string[]>;
+/**
+ * Instant one trace last received a span, or `undefined` once retention has
+ * pruned it. Reads the segments directory's mtime, so it stays cheap enough to
+ * poll a large spool without parsing any span.
+ */
+export declare function readLocalTraceActivityMs(appRoot: string, traceId: string): Promise<number | undefined>;
+/**
+ * Segment file names of one trace in read order, or `undefined` when the trace
+ * is gone. Segments are immutable and named for their span, so the order is
+ * stable across reads and a caller can treat names it has seen as parsed.
+ */
+export declare function listLocalTraceSegments(appRoot: string, traceId: string): Promise<string[] | undefined>;
+/**
+ * Spans held by one segment file. An oversized, unreadable, or malformed
+ * segment yields none, so a partial write never breaks a view.
+ */
+export declare function readLocalTraceSegment(appRoot: string, traceId: string, fileName: string): Promise<LocalTraceSpan[]>;
+/** Reads valid local traces, newest first, while ignoring malformed segments. */
+export declare function listLocalTraces(appRoot: string): Promise<LocalTrace[]>;
+/** Sorts spans into timeline order: start, then end, then a stable tiebreak. */
+export declare function compareLocalTraceSpans(left: LocalTraceSpan, right: LocalTraceSpan): number;
+/** Builds a trace from already-parsed spans, deriving summary fields. */
+export declare function assembleLocalTrace(traceId: string, spans: readonly LocalTraceSpan[]): LocalTrace;
+/**
+ * Extracts short human-facing details from a span's structural attributes
+ * (turn id, step index/attempt, action kind/name, model id) for one-line
+ * span labels. Raw values — callers sanitize for their output surface.
+ */
+export declare function describeLocalTraceSpan(span: LocalTraceSpan): string[];
+/** Parses one OTLP/JSON segment file into spans belonging to `expectedTraceId`. */
+export declare function parseLocalTraceSegment(content: string, expectedTraceId: string): LocalTraceSpan[];

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

@@ -0,0 +1 @@
+import{readFile,readdir,stat}from"node:fs/promises";import{join}from"node:path";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#tracing/local-trace-span-processor.js";const TRACE_ID_PATTERN=/^[0-9a-f]{32}$/u,SPAN_FILE_PATTERN=/^[0-9a-f]{16}\.otlp\.json$/u;async function listLocalTraceIds(e){let n;try{n=await readdir(resolveLocalTraceSchemaDirectory(e),{withFileTypes:!0})}catch(e){if(isMissing(e))return[];throw e}return n.filter(e=>e.isDirectory()&&TRACE_ID_PATTERN.test(e.name)).map(e=>e.name)}async function readLocalTraceActivityMs(e,t){try{return(await stat(resolveLocalTraceSegmentsDirectory(e,t))).mtimeMs}catch(e){if(isMissing(e))return;throw e}}async function listLocalTraceSegments(e,n){let r;try{r=await readdir(resolveLocalTraceSegmentsDirectory(e,n),{withFileTypes:!0})}catch(e){if(isMissing(e))return;throw e}return r.filter(e=>e.isFile()&&SPAN_FILE_PATTERN.test(e.name)).map(e=>e.name).sort((e,t)=>e.localeCompare(t))}async function readLocalTraceSegment(t,i,o){let s=join(resolveLocalTraceSegmentsDirectory(t,i),o),c;try{if((await stat(s)).size>8388608)return[];c=await readFile(s,`utf8`)}catch{return[]}return parseLocalTraceSegment(c,i)}async function listLocalTraces(e){let t=[];for(let n of await listLocalTraceIds(e)){let r=await readLocalTrace(e,n).catch(()=>void 0);r!==void 0&&t.push(r)}return t.sort((e,t)=>e.startTimeNs===t.startTimeNs?e.traceId.localeCompare(t.traceId):e.startTimeNs>t.startTimeNs?-1:1)}async function readLocalTrace(e,t){let n=await listLocalTraceSegments(e,t);if(n===void 0)return;let r=new Map;for(let i of n)for(let n of await readLocalTraceSegment(e,t,i))r.has(n.spanId)||r.set(n.spanId,n);if(r.size!==0)return assembleLocalTrace(t,[...r.values()])}function compareLocalTraceSpans(e,t){return e.startTimeNs===t.startTimeNs?e.endTimeNs===t.endTimeNs?e.name.localeCompare(t.name)||e.spanId.localeCompare(t.spanId):e.endTimeNs<t.endTimeNs?-1:1:e.startTimeNs<t.startTimeNs?-1:1}function assembleLocalTrace(e,t){let n=[...t].sort(compareLocalTraceSpans),r=n.map(e=>e.attributes),i=distinctAttributes(r,`agent.session.id`);return{agentName:firstAttribute(r,`agent.name`),endTimeNs:n.reduce((e,t)=>t.endTimeNs>e?t.endTimeNs:e,0n),sessionId:i[0],sessionIds:i,spans:n,startTimeNs:n.reduce((e,t)=>t.startTimeNs<e?t.startTimeNs:e,n[0].startTimeNs),traceId:e,window:firstNumberAttribute(r,`agent.session.window`)}}function describeLocalTraceSpan(e){let t=[],n=stringSpanAttribute(e,`agent.turn.id`),r=valueSpanAttribute(e,`agent.step.index`),i=valueSpanAttribute(e,`agent.step.attempt`),a=stringSpanAttribute(e,`agent.action.kind`),o=stringSpanAttribute(e,`agent.action.name`),s=stringSpanAttribute(e,`agent.model.id`)??stringSpanAttribute(e,`gen_ai.request.model`);return e.name===`agent.turn`&&n!==void 0&&t.push(n),e.name===`agent.step`&&r!==void 0&&t.push(`step ${String(r)}${i===void 0?``:`, attempt ${String(i)}`}`),e.name===`agent.action`&&o!==void 0&&t.push(`${a??`action`}: ${o}`),s!==void 0&&e.name.includes(`do`)&&t.push(`model ${s}`),t}function parseLocalTraceSegment(e,t){try{let n=JSON.parse(e);if(!isRecord(n)||!Array.isArray(n.resourceSpans))return[];let r=[];for(let e of n.resourceSpans)if(!(!isRecord(e)||!Array.isArray(e.scopeSpans)))for(let n of e.scopeSpans){if(!isRecord(n)||!Array.isArray(n.spans))continue;let e=isRecord(n.scope)&&typeof n.scope.name==`string`?n.scope.name:void 0;for(let i of n.spans){let n=parseLocalTraceSpan(i,t,e);n!==void 0&&r.push(n)}}return r}catch{return[]}}function parseLocalTraceSpan(e,t,n){if(!isRecord(e)||e.traceId!==t||typeof e.spanId!=`string`||!/^[0-9a-f]{16}$/u.test(e.spanId)||typeof e.name!=`string`)return;let r=parseNanos(e.startTimeUnixNano),i=parseNanos(e.endTimeUnixNano);if(!(r===void 0||i===void 0||i<r))return{attributes:parseAttributes(e.attributes),endTimeNs:i,name:e.name,parentSpanId:typeof e.parentSpanId==`string`&&/^[0-9a-f]{16}$/u.test(e.parentSpanId)?e.parentSpanId:void 0,scope:n,spanId:e.spanId,startTimeNs:r,statusCode:parseStatusCode(e.status),traceId:t}}function parseAttributes(e){if(!Array.isArray(e))return{};let t={};for(let n of e){if(!isRecord(n)||typeof n.key!=`string`||!isRecord(n.value))continue;let e=parseAnyValue(n.value);e!==void 0&&(t[n.key]=e)}return t}function parseAnyValue(e){for(let t of[`stringValue`,`boolValue`,`intValue`,`doubleValue`])if(t in e)return e[t];if(isRecord(e.arrayValue)&&Array.isArray(e.arrayValue.values))return e.arrayValue.values.filter(isRecord).map(e=>parseAnyValue(e))}function parseNanos(e){if(!(typeof e!=`string`&&typeof e!=`number`))try{let t=BigInt(e);return t>=0n&&t<=18446744073709551615n?t:void 0}catch{return}}function parseStatusCode(e){return isRecord(e)?typeof e.code==`number`?e.code:e.code===`STATUS_CODE_ERROR`?2:0:0}function firstAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`string`&&e.length>0)return e}}function firstNumberAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`number`)return e;if(typeof e==`bigint`)return Number(e)}}function distinctAttributes(e,t){let n=new Set;for(let r of e){let e=r[t];typeof e==`string`&&e.length>0&&n.add(e)}return[...n]}function stringSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`?n:void 0}function valueSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`||typeof n==`number`?n:void 0}function isMissing(e){return e.code===`ENOENT`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{assembleLocalTrace,compareLocalTraceSpans,describeLocalTraceSpan,listLocalTraceIds,listLocalTraceSegments,listLocalTraces,parseLocalTraceSegment,readLocalTraceActivityMs,readLocalTraceSegment};

package/dist/src/{harness → tracing}/local-trace-retention.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{readdir,rm,stat}from"node:fs/promises";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#harness/local-trace-span-processor.js";const log=createLogger(`harness.local-trace-retention`),LOCAL_TRACE_QUIESCENCE_MS=300*1e3,LOCAL_TRACE_MAX_AGE_MS=10080*60*1e3,LOCAL_TRACE_MAX_TOTAL_BYTES=512*1024*1024;function resolveLocalTraceRetentionSettings(e=process.env){return{enabled:!isDisabled(e.EVE_TRACES),maxAgeMs:readBound(e,`EVE_TRACES_MAX_AGE_MS`,LOCAL_TRACE_MAX_AGE_MS),maxTotalBytes:readBound(e,`EVE_TRACES_MAX_TOTAL_BYTES`,LOCAL_TRACE_MAX_TOTAL_BYTES),retainCount:readBound(e,`EVE_TRACES_RETAIN_COUNT`,20)}}async function pruneLocalTraceStore(e){let t=e.now??Date.now(),n=clampBound(e.maxAgeMs??LOCAL_TRACE_MAX_AGE_MS),r=clampBound(e.maxTotalBytes??LOCAL_TRACE_MAX_TOTAL_BYTES),a=clampCount(e.retainCount??20),o=await readStoredTraces(e.appRoot,t),s=[...o].sort((e,t)=>t.modifiedAtMs-e.modifiedAtMs),c=new Set(s.slice(0,a===!1?0:a)),l=new Set,u=o.reduce((e,t)=>e+t.byteSize,0),d=0,f=0,p=0;for(let a of s.toReversed()){let o=t-a.modifiedAtMs,s=e.activeTraceIds.has(a.traceId)||c.has(a)||o<=LOCAL_TRACE_QUIESCENCE_MS?void 0:n!==!1&&o>n?`maxAgeMs`:r!==!1&&u>r?`maxTotalBytes`:void 0;if(s===void 0){p+=1;continue}await rm(a.path,{force:!0,recursive:!0}),u-=a.byteSize,d+=a.byteSize,f+=1,l.add(s)}return{reasons:[...l],reclaimedBytes:d,removedTraces:f,retainedTraces:p}}const pruneRequest={input:{activeTraceIds:new Set,appRoot:``},requested:!1,running:void 0};function requestLocalTraceStorePrune(e){pruneRequest.input=e,pruneRequest.requested=!0,pruneRequest.running===void 0&&startPruning()}function startPruning(){pruneRequest.running=(async()=>{for(;pruneRequest.requested;)pruneRequest.requested=!1,report(await pruneLocalTraceStore(pruneRequest.input))})().catch(e=>{log.warn(`local trace retention failed`,{error:formatError(e)})}).finally(()=>{pruneRequest.running=void 0,pruneRequest.requested&&startPruning()})}function report(e){e.removedTraces!==0&&log.info(`pruned local traces`,{reasons:e.reasons.join(`,`),reclaimedBytes:e.reclaimedBytes,removedTraces:e.removedTraces,retainedTraces:e.retainedTraces})}async function readStoredTraces(e,t){let r=resolveLocalTraceSchemaDirectory(e),i=await readDirectoryEntries(r);return i===void 0?[]:(await Promise.all(i.filter(e=>e.isDirectory()).map(async i=>{let a=join(r,i.name),o=resolveLocalTraceSegmentsDirectory(e,i.name);await reapAbandonedTemporaryFiles(o,t);let c=await directoryMtime(o)??await directoryMtime(a);if(c!==void 0)return{byteSize:await directorySize(a),modifiedAtMs:c,path:a,traceId:i.name}}))).filter(e=>e!==void 0)}async function reapAbandonedTemporaryFiles(e,t){let r=await readDirectoryEntries(e);if(r!==void 0)for(let o of r){if(!o.isFile()||!o.name.includes(`.tmp-`))continue;let r=join(e,o.name);try{if(t-(await stat(r)).mtimeMs<=LOCAL_TRACE_QUIESCENCE_MS)continue;await rm(r,{force:!0})}catch{}}}async function directoryMtime(e){try{return(await stat(e)).mtimeMs}catch{return}}async function directorySize(e){let t=await readDirectoryEntries(e);if(t===void 0)return 0;let r=0;for(let i of t){let t=join(e,i.name);if(i.isDirectory()){r+=await directorySize(t);continue}try{r+=(await stat(t)).size}catch{}}return r}async function readDirectoryEntries(e){try{return await readdir(e,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&(e.code===`ENOENT`||e.code===`ENOTDIR`))return;throw e}}function isDisabled(e){if(e===void 0)return!1;let t=e.trim().toLowerCase();return t===`off`||t===`false`||t===`0`}function readBound(e,t,n){let r=e[t];if(r===void 0)return n;let i=r.trim().toLowerCase();if(i===`off`||i===`false`)return!1;let a=Number(i);return!Number.isFinite(a)||a<0?(log.warn(`ignoring invalid local trace retention value`,{fallback:n,name:t,value:r}),n):a}function clampBound(e){return e!==!1&&Math.max(0,e)}function clampCount(e){return e!==!1&&Math.max(0,Math.trunc(e))}export{pruneLocalTraceStore,requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings};
+import{readdir,rm,stat}from"node:fs/promises";import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#tracing/local-trace-span-processor.js";const log=createLogger(`harness.local-trace-retention`),LOCAL_TRACE_QUIESCENCE_MS=300*1e3,LOCAL_TRACE_MAX_AGE_MS=10080*60*1e3,LOCAL_TRACE_MAX_TOTAL_BYTES=512*1024*1024;function resolveLocalTraceRetentionSettings(e=process.env){return{enabled:!isDisabled(e.EVE_TRACES),maxAgeMs:readBound(e,`EVE_TRACES_MAX_AGE_MS`,LOCAL_TRACE_MAX_AGE_MS),maxTotalBytes:readBound(e,`EVE_TRACES_MAX_TOTAL_BYTES`,LOCAL_TRACE_MAX_TOTAL_BYTES),retainCount:readBound(e,`EVE_TRACES_RETAIN_COUNT`,20)}}async function pruneLocalTraceStore(e){let n=e.now??Date.now(),r=clampBound(e.maxAgeMs??LOCAL_TRACE_MAX_AGE_MS),i=clampBound(e.maxTotalBytes??LOCAL_TRACE_MAX_TOTAL_BYTES),a=clampCount(e.retainCount??20),o=await readStoredTraces(e.appRoot,n),s=[...o].sort((e,t)=>t.modifiedAtMs-e.modifiedAtMs),c=new Set(s.slice(0,a===!1?0:a)),l=new Set,u=o.reduce((e,t)=>e+t.byteSize,0),d=0,f=0,p=0;for(let a of s.toReversed()){let o=n-a.modifiedAtMs,s=e.activeTraceIds.has(a.traceId)||c.has(a)||o<=LOCAL_TRACE_QUIESCENCE_MS?void 0:r!==!1&&o>r?`maxAgeMs`:i!==!1&&u>i?`maxTotalBytes`:void 0;if(s===void 0){p+=1;continue}await rm(a.path,{force:!0,recursive:!0}),u-=a.byteSize,d+=a.byteSize,f+=1,l.add(s)}return{reasons:[...l],reclaimedBytes:d,removedTraces:f,retainedTraces:p}}const pruneRequest={input:{activeTraceIds:new Set,appRoot:``},requested:!1,running:void 0};function requestLocalTraceStorePrune(e){pruneRequest.input=e,pruneRequest.requested=!0,pruneRequest.running===void 0&&startPruning()}function startPruning(){pruneRequest.running=(async()=>{for(;pruneRequest.requested;)pruneRequest.requested=!1,report(await pruneLocalTraceStore(pruneRequest.input))})().catch(e=>{log.warn(`local trace retention failed`,{error:formatError(e)})}).finally(()=>{pruneRequest.running=void 0,pruneRequest.requested&&startPruning()})}function report(e){e.removedTraces!==0&&log.info(`pruned local traces`,{reasons:e.reasons.join(`,`),reclaimedBytes:e.reclaimedBytes,removedTraces:e.removedTraces,retainedTraces:e.retainedTraces})}async function readStoredTraces(e,t){let n=resolveLocalTraceSchemaDirectory(e),r=await readDirectoryEntries(n);return r===void 0?[]:(await Promise.all(r.filter(e=>e.isDirectory()).map(async r=>{let i=join(n,r.name),o=resolveLocalTraceSegmentsDirectory(e,r.name);await reapAbandonedTemporaryFiles(o,t);let c=await directoryMtime(o)??await directoryMtime(i);if(c!==void 0)return{byteSize:await directorySize(i),modifiedAtMs:c,path:i,traceId:r.name}}))).filter(e=>e!==void 0)}async function reapAbandonedTemporaryFiles(e,r){let i=await readDirectoryEntries(e);if(i!==void 0)for(let o of i){if(!o.isFile()||!o.name.includes(`.tmp-`))continue;let i=join(e,o.name);try{if(r-(await stat(i)).mtimeMs<=LOCAL_TRACE_QUIESCENCE_MS)continue;await rm(i,{force:!0})}catch{}}}async function directoryMtime(e){try{return(await stat(e)).mtimeMs}catch{return}}async function directorySize(e){let t=await readDirectoryEntries(e);if(t===void 0)return 0;let r=0;for(let i of t){let t=join(e,i.name);if(i.isDirectory()){r+=await directorySize(t);continue}try{r+=(await stat(t)).size}catch{}}return r}async function readDirectoryEntries(t){try{return await readdir(t,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&(e.code===`ENOENT`||e.code===`ENOTDIR`))return;throw e}}function isDisabled(e){if(e===void 0)return!1;let t=e.trim().toLowerCase();return t===`off`||t===`false`||t===`0`}function readBound(e,t,n){let r=e[t];if(r===void 0)return n;let i=r.trim().toLowerCase();if(i===`off`||i===`false`)return!1;let a=Number(i);return!Number.isFinite(a)||a<0?(log.warn(`ignoring invalid local trace retention value`,{fallback:n,name:t,value:r}),n):a}function clampBound(e){return e!==!1&&Math.max(0,e)}function clampCount(e){return e!==!1&&Math.max(0,Math.trunc(e))}export{pruneLocalTraceStore,requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings};

package/dist/src/{harness → tracing}/local-trace-span-processor.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{mkdir}from"node:fs/promises";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";import{atomicWriteFile}from"#shared/atomic-write-file.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:n,traceId:r}=e.spanContext();if(!isHexId(r,32)||!isHexId(n,16))return;let i=JsonTraceSerializer.serializeRequest([e]);i!==void 0&&(this.#t=this.#t.then(async()=>{let e=resolveLocalTraceSegmentsDirectory(this.#e,r);await mkdir(e,{recursive:!0}),await atomicWriteFile(join(e,`${n}.otlp.json`),i)}).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{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(t){if(!isReadableSpan(t))return;let{spanId:n,traceId:r}=t.spanContext();if(!isHexId(r,32)||!isHexId(n,16))return;let i=JsonTraceSerializer.serializeRequest([t]);i!==void 0&&(this.#t=this.#t.then(async()=>{let t=resolveLocalTraceSegmentsDirectory(this.#e,r);await mkdir(t,{recursive:!0}),await atomicWriteFile(join(t,`${n}.otlp.json`),i)}).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/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CyDt3Lny.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-bKJbH0k4.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-CyDt3Lny.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-bKJbH0k4.js";
 
 export { useEveAgent };

package/docs/channels/chat-sdk.mdx

@@ -97,7 +97,24 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-`options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
+`options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName?, turnPolicy? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
+
+### Experimental steering
+
+By default, a message sent while an eve turn is active waits for the next turn. Pass `turnPolicy: "experimental-steer"` to cancel the active turn before sending the new message:
+
+```ts
+bot.onSubscribedMessage(async (thread, message) => {
+  await send(message.text, {
+    thread,
+    turnPolicy: "experimental-steer",
+  });
+});
+```
+
+This is cancellation-backed steering: the interrupted turn emits `turn.cancelled`, and the replacement message starts a new turn with a new turn ID. Partial output and completed side effects from the interrupted turn are not rolled back. If no turn is active, the message is sent normally. Use the default `turnPolicy: "queue"` when every turn should finish in order.
+
+This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the experimental steering path immediately.
 
 ### Delivery
 

package/docs/channels/discord.mdx

@@ -4,27 +4,43 @@ description: "Reach your agent from Discord HTTP Interactions, including slash c
 type: integration
 ---
 
-The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel verifies the Ed25519 signature headers, acknowledges the command right away, and runs the eve work in the background. See [Channels](./overview) for the contract this builds on.
+The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel acknowledges the command right away and runs the eve work in the background. Credentials and inbound request verification run through [Vercel Connect](../guides/auth-and-route-protection), so Discord's bot token stays out of your environment and Connect verifies Discord's signature before forwarding an interaction to eve. See [Channels](./overview) for the contract this builds on.
 
-## Add the channel
+## Set up Discord
 
-```ts title="agent/channels/discord.ts"
-import { discordChannel } from "eve/channels/discord";
+Run the guided setup from your eve project:
 
-export default discordChannel();
+```bash
+pnpm eve add channel/discord
 ```
 
-```bash
-DISCORD_PUBLIC_KEY=...      # verifies X-Signature-Ed25519 + X-Signature-Timestamp
-DISCORD_APPLICATION_ID=...  # edits the deferred response and sends followups
-DISCORD_BOT_TOKEN=...       # proactive messages + fallback + typing indicators
+The setup guides you through creating a Discord application and bot, then:
+
+- validates the bot token;
+- creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
+- registers an application command with a required `message` option;
+- configures the Discord application's Interactions Endpoint URL;
+- scaffolds the channel with Connect-managed credentials; and
+- prints the bot installation URL.
+
+The command defaults to `/ask` with the description **Ask the eve agent**. You can edit both during setup. Discord global commands can take up to an hour to appear after registration.
+
+The generated channel looks like this:
+
+```ts title="agent/channels/discord.ts"
+import { connectDiscordCredentials } from "@vercel/connect/eve";
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  credentials: connectDiscordCredentials("discord/my-agent"),
+});
 ```
 
-To skip env vars, pass the same values through `credentials: { applicationId, botToken, publicKey }`. The route is `POST /eve/v1/discord` by default. Paste that public URL into your Discord application's Interactions Endpoint URL.
+The route is `POST /eve/v1/discord` by default. Connect resolves the application ID and bot token lazily and verifies forwarded interactions with same-project Vercel OIDC.
 
-## Register a command
+### Configure Discord manually
 
-Registering commands is on you, not the channel. Use Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction:
+If you do not use the guided Connect setup, register a command with Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction:
 
 ```bash
 curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \
@@ -33,7 +49,7 @@ curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/co
     "options":[{"name":"message","description":"What should the agent do?","type":3,"required":true}]}]'
 ```
 
-Use guild commands during development for faster propagation.
+Then configure the public `https://…/eve/v1/discord` route as the application's Interactions Endpoint URL. Pass `credentials: { applicationId, botToken, publicKey }` to `discordChannel`, or set the corresponding `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, and `DISCORD_PUBLIC_KEY` environment variables.
 
 ## How the channel handles messages
 
@@ -74,7 +90,7 @@ HITL renders as Discord components. Confirmations and options become buttons, `d
 
 ### Proactive sessions
 
-Start a session without an inbound interaction through `receive(discord, { message, target, auth })` from a schedule `run` handler, or `args.receive(discord, ...)` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs `DISCORD_BOT_TOKEN`.
+Start a session without an inbound interaction through `receive(discord, { message, target, auth })` from a schedule `run` handler, or `args.receive(discord, ...)` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs a bot token, supplied by Connect or `DISCORD_BOT_TOKEN`.
 
 ### Attachments
 

package/docs/channels/meta.json

@@ -4,6 +4,7 @@
     "overview",
     "eve",
     "slack",
+    "photon",
     "discord",
     "teams",
     "telegram",

package/docs/channels/overview.mdx

@@ -28,7 +28,7 @@ agent/
     intake.ts
 ```
 
-Install a built-in channel with `eve add channel/slack` or `eve add channel/web`. You can also author the file by hand.
+Install a channel from the registry with `eve add channel/photon-imessage`, `eve add channel/slack`, or `eve add channel/web`. You can also author the file by hand.
 
 ## The eve HTTP channel (default)
 

package/docs/channels/photon.mdx

@@ -0,0 +1,78 @@
+---
+title: Photon
+description: Connect an eve agent to iMessage through Photon.
+---
+
+Use `photonIMessageChannel` to receive and reply to iMessages through a Photon project.
+
+Run `eve add channel/photon-imessage` to create or use a Photon project and register
+your phone number. It then asks whether to configure Vercel Connect or portable
+credentials. With Vercel Connect, eve creates the connector and configures
+Photon’s webhook through Connect. The channel resolves credentials lazily when
+the adapter first initializes:
+
+```ts title="agent/channels/photon.ts"
+import { connectPhotonCredentials } from "@vercel/connect/eve";
+import { photonIMessageChannel } from "eve/channels/photon";
+
+export default photonIMessageChannel({
+  credentials: connectPhotonCredentials("photon/my-agent"),
+});
+```
+
+The default webhook route is `/eve/v1/photon`. The channel verifies forwarded
+webhooks with same-project Vercel OIDC by default, marks accepted messages as
+read, and continues the same eve session for every message in an iMessage
+conversation. A new accepted message cooperatively cancels an active turn and
+steers its replacement turn.
+
+Customize inbound dispatch with `onMessage`. Return `null` to ignore a message:
+
+```ts
+export default photonIMessageChannel({
+  credentials: connectPhotonCredentials("photon/my-agent"),
+  onMessage(_ctx, message) {
+    if (message.author.isBot) return null;
+    return {
+      auth: null,
+      context: [`The sender is ${message.author.fullName}.`],
+    };
+  },
+});
+```
+
+Set `route` to override the webhook path or `webhookVerifier` to use a different
+trusted-forwarder verifier.
+
+## Other hosts
+
+For a host without Vercel Connect, choose **Use portable credentials** during
+`eve add channel/photon-imessage`. eve scaffolds the channel and writes
+`IMESSAGE_PROJECT_ID` and `IMESSAGE_PROJECT_SECRET` to `.env.local`.
+
+After deploying the agent:
+
+1. Create a Photon webhook for your public `https://…/eve/v1/photon` URL.
+2. Copy its signing secret into `IMESSAGE_WEBHOOK_SECRET`.
+3. Set `IMESSAGE_PROJECT_ID`, `IMESSAGE_PROJECT_SECRET`, and
+   `IMESSAGE_WEBHOOK_SECRET` in the host’s encrypted environment variables.
+
+To configure the channel by hand, use lazy environment-backed credentials:
+
+```ts title="agent/channels/photon.ts"
+import { photonIMessageChannel } from "eve/channels/photon";
+
+export default photonIMessageChannel({
+  async credentials() {
+    const projectId = process.env.IMESSAGE_PROJECT_ID;
+    const projectSecret = process.env.IMESSAGE_PROJECT_SECRET;
+    if (!projectId || !projectSecret) throw new Error("Photon project credentials are required.");
+    return { projectId, projectSecret };
+  },
+  webhookSecret: process.env.IMESSAGE_WEBHOOK_SECRET,
+});
+```
+
+For direct Photon webhooks, pass `webhookSecret` or set
+`IMESSAGE_WEBHOOK_SECRET`; the signing secret takes precedence over the default
+OIDC verifier.

package/docs/concepts/default-harness.md

@@ -41,6 +41,8 @@ The shell and file tools (`bash`, `read_file`, `write_file`, `glob`, `grep`) run
 | `load_skill`        | Pull an on-demand [skill](../skills)'s instructions into the current turn. Present only when the agent declares skills.                                                                                             | App runtime   |
 | `connection_search` | Discover tools across declared [connections](../connections); matched tools become directly callable. Present only when the agent declares connections.                                                             | App runtime   |
 
+The model-facing file tools accept absolute paths and paths beginning with `$HOME/`. eve resolves `$HOME` against the sandbox before invoking non-shell file operations, so packaged skill references such as `$HOME/.agents/skills/<skill>/references/...` work consistently across `read_file`, `write_file`, `glob`, and `grep`.
+
 Notes:
 
 - **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](../guides/state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).

package/docs/guides/acp.md

@@ -0,0 +1,91 @@
+---
+title: "Use eve through ACP"
+description: "Use local or deployed eve agents from Agent Client Protocol clients."
+---
+
+Agent Client Protocol (ACP) clients can launch an authored eve application as a local subprocess. eve serves stable ACP v1 over stdio while its normal development server remains the execution runtime.
+
+```sh
+eve acp
+```
+
+Without a URL, the client starts one process from the eve application root. It supervises a local development server, and closing the ACP connection stops that owned server. To bridge ACP to a deployed eve agent, pass its URL:
+
+```sh
+eve acp https://agent.example.com
+```
+
+For a recognized Vercel deployment, eve verifies the exact origin and resolves a short-lived project-scoped OIDC token from the local Vercel session. If login or a Trusted Sources change is required, run `eve dev <url>` and complete `/vc:login` before launching ACP. `VERCEL_AUTOMATION_BYPASS_SECRET` remains available for deployments configured with a Protection Bypass for Automation token.
+
+## Configure Zed
+
+Open the eve application root as the Zed workspace. In **Agent Settings → External Agents**, add a custom agent:
+
+```json
+{
+  "agent_servers": {
+    "eve-local": {
+      "type": "custom",
+      "command": "pnpm",
+      "args": ["exec", "eve", "acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Use an absolute command path if Zed cannot find `pnpm` in its environment. The workspace must be the same directory as the eve application root; eve rejects a different `session/new.cwd` instead of running the wrong application.
+
+Disable Zed project MCP servers for this agent. The initial eve adapter does not accept client-provided MCP servers.
+
+## Supported behavior
+
+ACP clients receive:
+
+- streamed assistant text and reasoning;
+- tool-call requests and results;
+- one-time tool approval and denial requests;
+- fixed-choice and freeform questions when the client supports ACP form elicitation;
+- cooperative turn cancellation;
+- independent concurrent ACP sessions;
+- session closure and process cleanup.
+
+Development rebuilds retain normal eve semantics. In-flight work stays pinned to its generation, and the next turn uses the newest successful generation.
+
+## Security and capability limits
+
+ACP mode does not give the agent access to the editor's host filesystem or terminal. `session/new.cwd` identifies the eve application being launched; it is not mounted into the agent sandbox.
+
+The initial adapter does not support:
+
+- a deployed ACP HTTP or WebSocket endpoint;
+- ACP authentication (remote bridges use the deployed eve agent's existing HTTP authentication);
+- ACP v2;
+- client filesystem or terminal methods;
+- client-provided MCP servers;
+- images, audio, files, or embedded resources in prompts;
+- session loading, listing, resumption, or durable ACP IDs across process restarts;
+- ACP model or mode configuration.
+
+The agent continues to use the connections, tools, credentials, and sandbox policy authored in the eve application. Prompt text and ACP metadata never establish an authenticated end-user principal.
+
+## Diagnose a connection
+
+ACP reserves stdout for newline-delimited JSON-RPC. eve sends compilation output, server logs, and diagnostics to stderr so they cannot corrupt the protocol stream.
+
+For a quick headless smoke test, run an ACP client such as `acpx` from the application root. `acpx` launches the ACP process itself; do not start `eve acp` separately.
+
+```sh
+npx acpx@latest \
+  --agent 'pnpm exec eve acp' \
+  exec 'Reply with exactly: ACP works'
+```
+
+When testing from the eve source checkout, use an authored fixture rather than the monorepo root, which does not provide an `eve` executable:
+
+```sh
+cd apps/fixtures/weather-agent
+npx acpx@latest --agent 'pnpm exec eve acp' exec 'Reply with exactly: ACP works'
+```
+
+If startup fails, inspect the ACP client's logs together with eve's stderr. A non-empty client MCP configuration, a mismatched working directory, and unsupported prompt content produce explicit protocol errors before model work begins.

package/docs/guides/client/streaming.mdx

@@ -180,6 +180,30 @@ Because a tail-relative cursor cannot be bounded, `follow: false` throws when co
 
 `stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
 
+## Snapshot a session
+
+Use `snapshot()` when you need the complete event prefix and its matching cursor
+as one value, such as when hydrating a server-rendered chat:
+
+```ts
+const session = client.session({ sessionId, streamIndex: 0 });
+const snapshot = await session.snapshot();
+
+// snapshot.events contains event indexes 0 through snapshot.session.streamIndex - 1.
+```
+
+The read pins the durable tail when it opens, just like
+`stream({ follow: false })`. Events written afterward are not included, and
+`snapshot.session.streamIndex` is the exact index from which a live consumer can
+continue. `snapshot()` always reads from index `0`; use a bounded stream directly
+when you only need the unread suffix from an existing cursor.
+
+Unlike `stream()`, `snapshot()` does not advance or reset the originating
+`ClientSession`. Its returned session includes a continuation token only when
+the captured prefix ends in `session.waiting`, or when completed sessions are
+explicitly preserved by the client. Active and terminal snapshots remain
+inspectable at their returned stream cursor but cannot accept another turn.
+
 ## 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 the server-side turn — it keeps running and remains attachable by index. To stop the turn itself, POST the session's [cancel route](../../channels/eve#routes) and watch the stream settle with `turn.cancelled` followed by `session.waiting`.