eve 0.53.0 → 0.54.0

package/dist/src/tracing/agent-trace-state.d.ts

@@ -1,5 +1,5 @@
 import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationActionKind, InstrumentationTraceContext, InstrumentationTurnFailedEvent, InstrumentationTurnSettledEvent } from "#instrumentation/lifecycle.js";
+import type { InstrumentationActionKind, InstrumentationActionOutcome, InstrumentationParentLineage, InstrumentationPrincipalSummary, InstrumentationTraceContext, InstrumentationTurnFailedEvent, InstrumentationTurnSettledEvent, InstrumentationUsage } from "#instrumentation/lifecycle.js";
 import type { ChannelAudience } from "#shared/channel-audience.js";
 import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
 export interface AgentSessionTraceState {
@@ -8,16 +8,20 @@ export interface AgentSessionTraceState {
     readonly channelKind?: string;
     readonly context: SpanContext;
     readonly decision?: InstrumentationDecision;
+    readonly parentLineage?: InstrumentationParentLineage;
     readonly rootSessionId: string;
 }
 export interface AgentTurnTraceState {
+    readonly caller?: SpanContext;
+    readonly channelDelivery?: AgentTurnChannelDeliveryTraceState;
     readonly context: SpanContext;
+    readonly currentPrincipal?: InstrumentationPrincipalSummary;
+    readonly initiatorPrincipal?: InstrumentationPrincipalSummary;
+    readonly parentLineage?: InstrumentationParentLineage;
     readonly modelUsage?: {
         readonly inputTokens?: number;
         readonly outputTokens?: number;
     };
-    readonly parentIsRemote?: boolean;
-    readonly parentSpanId: string;
     readonly rootSessionId: string;
     readonly sequence: number;
     readonly startTimeMs: number;
@@ -29,6 +33,14 @@ export interface AgentTurnTraceState {
         readonly type: InstrumentationTurnSettledEvent["type"];
     };
 }
+export interface AgentTurnChannelDeliveryTraceState {
+    readonly channelKind: string;
+    readonly channelName: string;
+    readonly deliveryId: string;
+    readonly inputAttribute?: string;
+    readonly requestId?: string;
+    readonly requestTraceContext?: SpanContext;
+}
 export interface AgentActionTraceState {
     readonly attemptIndex: number;
     readonly callId: string;
@@ -44,17 +56,36 @@ export interface AgentActionTraceState {
     readonly stepIndex: number;
     readonly turnId: string;
 }
+export interface AgentInvocationTraceState extends Omit<AgentActionTraceState, "inputAttribute" | "kind"> {
+    readonly kind: "remote-agent-call" | "subagent-call";
+    readonly parentActionCallId: string;
+    readonly recordOutputs?: boolean;
+    readonly terminal?: AgentActionTraceTerminalState;
+}
+export interface AgentActionTraceTerminalState {
+    readonly acceptedAtMs?: number;
+    readonly error?: unknown;
+    readonly outcome: InstrumentationActionOutcome;
+    readonly usage?: InstrumentationUsage;
+}
 /** Provider-owned serializable storage for durable agent trace state. */
 export interface AgentTraceStateStore {
     deleteAction(idempotencyKey: string): void | PromiseLike<void>;
+    deleteActionAnchors(sessionId: string): void | PromiseLike<void>;
     deleteActions(sessionId: string, turnId?: string): void | PromiseLike<void>;
+    deleteInvocation(idempotencyKey: string): void | PromiseLike<void>;
+    deleteInvocations(sessionId: string, turnId?: string): void | PromiseLike<void>;
     deleteSession(sessionId: string): void | PromiseLike<void>;
     deleteTurn(sessionId: string, turnId: string): void | PromiseLike<void>;
     findAction(sessionId: string, callId: string): AgentActionTraceState | undefined | PromiseLike<AgentActionTraceState | undefined>;
+    findActionAnchor(sessionId: string, turnId: string, callId: string): AgentActionTraceState | undefined | PromiseLike<AgentActionTraceState | undefined>;
+    findInvocations(sessionId?: string, turnId?: string, parentActionCallId?: string): readonly AgentInvocationTraceState[] | PromiseLike<readonly AgentInvocationTraceState[]>;
     getAction(idempotencyKey: string): AgentActionTraceState | undefined | PromiseLike<AgentActionTraceState | undefined>;
     getSession(sessionId: string): AgentSessionTraceState | undefined | PromiseLike<AgentSessionTraceState | undefined>;
     getTurn(sessionId: string, turnId: string): AgentTurnTraceState | undefined | PromiseLike<AgentTurnTraceState | undefined>;
     setAction(idempotencyKey: string, state: AgentActionTraceState): void | PromiseLike<void>;
+    setActionAnchor(idempotencyKey: string, state: AgentActionTraceState): void | PromiseLike<void>;
+    setInvocation(idempotencyKey: string, state: AgentInvocationTraceState): void | PromiseLike<void>;
     setSession(sessionId: string, state: AgentSessionTraceState): void | PromiseLike<void>;
     setTurn(sessionId: string, turnId: string, state: AgentTurnTraceState): void | PromiseLike<void>;
     /** Atomically updates an existing turn and does nothing after that turn is deleted. */
@@ -64,14 +95,21 @@ export interface AgentTraceStateStore {
 export declare class InMemoryAgentTraceStateStore implements AgentTraceStateStore {
     #private;
     deleteAction(idempotencyKey: string): void;
+    deleteActionAnchors(sessionId: string): void;
     deleteActions(sessionId: string, turnId?: string): void;
+    deleteInvocation(idempotencyKey: string): void;
+    deleteInvocations(sessionId: string, turnId?: string): void;
     deleteSession(sessionId: string): void;
     deleteTurn(sessionId: string, turnId: string): void;
     findAction(sessionId: string, callId: string): AgentActionTraceState | undefined;
+    findActionAnchor(sessionId: string, turnId: string, callId: string): AgentActionTraceState | undefined;
+    findInvocations(sessionId?: string, turnId?: string, parentActionCallId?: string): readonly AgentInvocationTraceState[];
     getAction(idempotencyKey: string): AgentActionTraceState | undefined;
     getSession(sessionId: string): AgentSessionTraceState | undefined;
     getTurn(sessionId: string, turnId: string): AgentTurnTraceState | undefined;
     setAction(idempotencyKey: string, state: AgentActionTraceState): void;
+    setActionAnchor(idempotencyKey: string, state: AgentActionTraceState): void;
+    setInvocation(idempotencyKey: string, state: AgentInvocationTraceState): void;
     setSession(sessionId: string, state: AgentSessionTraceState): void;
     setTurn(sessionId: string, turnId: string, state: AgentTurnTraceState): void;
     updateTurn(sessionId: string, turnId: string, update: (state: AgentTurnTraceState) => AgentTurnTraceState): void;

package/dist/src/tracing/agent-trace-state.js

@@ -1 +1 @@
-var InMemoryAgentTraceStateStore=class{#e=new Map;#t=new Map;#n=new Map;deleteAction(e){this.#e.delete(e)}deleteActions(e,t){for(let[n,r]of this.#e)r.sessionId===e&&(t===void 0||r.turnId===t)&&this.#e.delete(n)}deleteSession(e){this.#t.delete(e)}deleteTurn(e,t){this.#n.delete(turnKey(e,t))}findAction(e,t){return[...this.#e.values()].find(n=>n.sessionId===e&&n.callId===t)}getAction(e){return this.#e.get(e)}getSession(e){return this.#t.get(e)}getTurn(e,t){return this.#n.get(turnKey(e,t))}setAction(e,t){this.#e.set(e,t)}setSession(e,t){this.#t.set(e,t)}setTurn(e,t,n){this.#n.set(turnKey(e,t),n)}updateTurn(e,t,n){let r=turnKey(e,t),i=this.#n.get(r);i!==void 0&&this.#n.set(r,n(i))}};function turnKey(e,t){return`${e}:${t}`}export{InMemoryAgentTraceStateStore,turnKey};
+var InMemoryAgentTraceStateStore=class{#e=new Map;#t=new Map;#n=new Map;#r=new Map;#i=new Map;deleteAction(e){this.#t.delete(e)}deleteActionAnchors(e){for(let[t,n]of this.#e)n.sessionId===e&&this.#e.delete(t)}deleteActions(e,t){for(let[n,r]of this.#t)r.sessionId===e&&(t===void 0||r.turnId===t)&&this.#t.delete(n)}deleteInvocation(e){this.#n.delete(e)}deleteInvocations(e,t){for(let[n,r]of this.#n)r.sessionId===e&&(t===void 0||r.turnId===t)&&this.#n.delete(n)}deleteSession(e){this.#r.delete(e)}deleteTurn(e,t){this.#i.delete(turnKey(e,t))}findAction(e,t){return[...this.#t.values()].find(n=>n.sessionId===e&&n.callId===t)}findActionAnchor(e,t,n){return[...this.#e.values()].find(r=>r.sessionId===e&&r.turnId===t&&r.callId===n)}findInvocations(e,t,n){return[...this.#n.values()].filter(r=>(e===void 0||r.sessionId===e)&&(t===void 0||r.turnId===t)&&(n===void 0||r.parentActionCallId===n))}getAction(e){return this.#t.get(e)}getSession(e){return this.#r.get(e)}getTurn(e,t){return this.#i.get(turnKey(e,t))}setAction(e,t){this.#t.set(e,t)}setActionAnchor(e,t){this.#e.set(e,t)}setInvocation(e,t){this.#n.set(e,t)}setSession(e,t){this.#r.set(e,t)}setTurn(e,t,n){this.#i.set(turnKey(e,t),n)}updateTurn(e,t,n){let r=turnKey(e,t),i=this.#i.get(r);i!==void 0&&this.#i.set(r,n(i))}};function turnKey(e,t){return`${e}:${t}`}export{InMemoryAgentTraceStateStore,turnKey};

package/dist/src/tracing/bounded-error.d.ts

@@ -0,0 +1 @@
+export declare function boundedTraceError(value: Error): Error;

package/dist/src/tracing/bounded-error.js

@@ -0,0 +1 @@
+import{truncateTelemetryText}from"#tracing/telemetry-budget.js";function boundedTraceError(e){let t=Error(truncateTelemetryText(e.message,4096));return t.name=truncateTelemetryText(e.name,128),t.stack=e.stack===void 0?void 0:truncateTelemetryText(e.stack,8192),t}export{boundedTraceError};

package/dist/src/tracing/content-span-processor.js

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{hasSessionRelease}from"#tracing/local-traces.js";import{channelAudienceFromContext}from"#tracing/channel-audience-context.js";import{withoutDeclinedContent}from"#tracing/content-attributes.js";import{contentRedactionForSpan,spanExportPolicyStages}from"#tracing/span-export-policy.js";function contentFilteringProcessor(e,t){if(t===void 0)return e;let n=e;for(let e of spanExportPolicyStages(t).toReversed())n=policyFilteringProcessor(n,e);return n}function policyFilteringProcessor(e,t){let n=new WeakMap,r=new WeakSet,i={forceFlush:()=>e.forceFlush(),onEnd:i=>{if(typeof i!=`object`||!i)return;let a=facadeFor(i,t,n);if(r.has(i)||!a.exported){r.delete(i),n.delete(i);return}a.refresh();try{e.onEnd(a.value)}finally{n.delete(i)}},onStart:(i,a)=>{if(typeof i!=`object`||!i)return;let o=facadeFor(i,t,n,channelAudienceFromContext(a));if(!o.exported){r.add(i);return}e.onStart(o.value,a)},shutdown:()=>e.shutdown()};return hasSessionRelease(e)?{...i,releaseSession:t=>e.releaseSession(t)}:i}function facadeFor(e,t,n,r){let i=n.get(e);if(i!==void 0)return i;let a=spanExportContext(e,r),o=contentForSpan(a,t),s={},c=[],l={},u=Object.create(Reflect.getPrototypeOf(e)),d=new Map,refresh=()=>{refreshAttributes(s,e,o,a,t),refreshEvents(c,e,o),refreshStatus(l,e,o)},f,readOriginal=t=>{let n=Reflect.get(e,t,e);if(typeof n!=`function`||t===`constructor`)return n;let r=d.get(t);if(r!==void 0)return r;let created=(...t)=>{let r=Reflect.apply(n,e,t);return refresh(),r===e?f:r};return d.set(t,created),created};Object.defineProperty(u,"attributes",{configurable:!0,enumerable:!0,value:s}),Object.defineProperty(u,"events",{configurable:!0,enumerable:!0,value:c}),Object.defineProperty(u,"status",{configurable:!0,enumerable:!0,value:l});for(let t of Reflect.ownKeys(e)){if(t===`attributes`||t===`events`||t===`status`)continue;let n=Reflect.getOwnPropertyDescriptor(e,t);Object.defineProperty(u,t,{configurable:!0,enumerable:n?.enumerable??!1,get:()=>readOriginal(t)})}f=new Proxy(u,{get:(e,t,n)=>Object.hasOwn(e,t)?Reflect.get(e,t,n):readOriginal(t)});let p={context:a,exported:shouldExport(a,t),refresh,value:f};return p.refresh(),n.set(e,p),p}function contentForSpan(e,t){let n=contentRedactionForSpan(t,e);return{recordInputs:!n.redactInputs,recordOutputs:!n.redactOutputs}}function refreshAttributes(e,t,n,r,i){for(let t of Object.keys(e))delete e[t];let a=t.attributes;if(typeof a!=`object`||!a)return;let o=withoutDeclinedContent(a,n)??a;for(let[t,n]of Object.entries(o)){let a=attributeDecision(i,{key:t,span:r,value:n});a.action===`keep`?e[t]=n:a.action===`replace`&&(e[t]=a.value)}}function spanExportContext(e,t=`unknown`){let n=e.attributes,r=typeof n==`object`&&n?n:{},i=[r[`agent.channel.audience`],r[`ai.settings.context.eve.channel.audience`]].filter(e=>e!==void 0).map(normalizeChannelAudience),a=i.length>0&&i.every(e=>e===i[0])?i[0]:i.length>0?`unknown`:t,o=e.spanContext?.(),s=typeof o==`object`&&o?o:{},c=e.name;return{attributes:r,audience:a,name:typeof c==`string`?c:``,spanId:typeof s.spanId==`string`?s.spanId:``,traceId:typeof s.traceId==`string`?s.traceId:``}}function shouldExport(e,t){if(t===void 0)return!0;try{return t.span?.(e)!==!1}catch{return!1}}function attributeDecision(e,t){if(e?.attribute===void 0)return{action:`keep`};try{return e.attribute(t)}catch{return{action:`drop`}}}function refreshEvents(e,t,n){e.length=0;let r=t.events;if(Array.isArray(r)){if(n.recordOutputs){e.push(...r);return}for(let t of r){if(typeof t!=`object`||!t)continue;let n=t;n.name!==`exception`&&e.push({...n,attributes:void 0})}}}function refreshStatus(e,t,n){for(let t of Object.keys(e))delete e[t];let r=t.status;if(typeof r!=`object`||!r)return;let i=r;i.code!==void 0&&(e.code=i.code),n.recordOutputs&&i.message!==void 0&&(e.message=i.message)}export{contentFilteringProcessor};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{hasConversationRelease}from"#tracing/local-traces.js";import{channelAudienceFromContext}from"#tracing/channel-audience-context.js";import{withoutDeclinedContent}from"#tracing/content-attributes.js";import{contentRedactionForSpan,spanExportPolicyStages}from"#tracing/span-export-policy.js";function contentFilteringProcessor(e,t){if(t===void 0)return e;let n=e;for(let e of spanExportPolicyStages(t).toReversed())n=policyFilteringProcessor(n,e);return n}function policyFilteringProcessor(e,t){let n=new WeakMap,r=new WeakSet,i={forceFlush:()=>e.forceFlush(),onEnd:i=>{if(typeof i!=`object`||!i)return;let a=facadeFor(i,t,n);if(r.has(i)||!a.exported){r.delete(i),n.delete(i);return}a.refresh();try{e.onEnd(a.value)}finally{n.delete(i)}},onStart:(i,a)=>{if(typeof i!=`object`||!i)return;let o=facadeFor(i,t,n,channelAudienceFromContext(a));if(!o.exported){r.add(i);return}e.onStart(o.value,a)},shutdown:()=>e.shutdown()};return hasConversationRelease(e)?{...i,releaseConversation:t=>e.releaseConversation(t)}:i}function facadeFor(e,t,n,r){let i=n.get(e);if(i!==void 0)return i;let a=spanExportContext(e,r),o=contentForSpan(a,t),s={},c=[],l={},u=Object.create(Reflect.getPrototypeOf(e)),d=new Map,refresh=()=>{refreshAttributes(s,e,o,a,t),refreshEvents(c,e,o),refreshStatus(l,e,o)},f,readOriginal=t=>{let n=Reflect.get(e,t,e);if(typeof n!=`function`||t===`constructor`)return n;let r=d.get(t);if(r!==void 0)return r;let created=(...t)=>{let r=Reflect.apply(n,e,t);return refresh(),r===e?f:r};return d.set(t,created),created};Object.defineProperty(u,"attributes",{configurable:!0,enumerable:!0,value:s}),Object.defineProperty(u,"events",{configurable:!0,enumerable:!0,value:c}),Object.defineProperty(u,"status",{configurable:!0,enumerable:!0,value:l});for(let t of Reflect.ownKeys(e)){if(t===`attributes`||t===`events`||t===`status`)continue;let n=Reflect.getOwnPropertyDescriptor(e,t);Object.defineProperty(u,t,{configurable:!0,enumerable:n?.enumerable??!1,get:()=>readOriginal(t)})}f=new Proxy(u,{get:(e,t,n)=>Object.hasOwn(e,t)?Reflect.get(e,t,n):readOriginal(t)});let p={context:a,exported:shouldExport(a,t),refresh,value:f};return p.refresh(),n.set(e,p),p}function contentForSpan(e,t){let n=contentRedactionForSpan(t,e);return{recordInputs:!n.redactInputs,recordOutputs:!n.redactOutputs}}function refreshAttributes(e,t,n,r,i){for(let t of Object.keys(e))delete e[t];let a=t.attributes;if(typeof a!=`object`||!a)return;let o=withoutDeclinedContent(a,n)??a;for(let[t,n]of Object.entries(o)){let a=attributeDecision(i,{key:t,span:r,value:n});a.action===`keep`?e[t]=n:a.action===`replace`&&(e[t]=a.value)}}function spanExportContext(e,t=`unknown`){let n=e.attributes,r=typeof n==`object`&&n?n:{},i=[r[`agent.channel.audience`],r[`ai.settings.context.eve.channel.audience`]].filter(e=>e!==void 0).map(normalizeChannelAudience),a=i.length>0&&i.every(e=>e===i[0])?i[0]:i.length>0?`unknown`:t,o=e.spanContext?.(),s=typeof o==`object`&&o?o:{},c=e.name;return{attributes:r,audience:a,name:typeof c==`string`?c:``,spanId:typeof s.spanId==`string`?s.spanId:``,traceId:typeof s.traceId==`string`?s.traceId:``}}function shouldExport(e,t){if(t===void 0)return!0;try{return t.span?.(e)!==!1}catch{return!1}}function attributeDecision(e,t){if(e?.attribute===void 0)return{action:`keep`};try{return e.attribute(t)}catch{return{action:`drop`}}}function refreshEvents(e,t,n){e.length=0;let r=t.events;if(Array.isArray(r)){if(n.recordOutputs){e.push(...r);return}for(let t of r){if(typeof t!=`object`||!t)continue;let n=t;n.name!==`exception`&&e.push({...n,attributes:void 0})}}}function refreshStatus(e,t,n){for(let t of Object.keys(e))delete e[t];let r=t.status;if(typeof r!=`object`||!r)return;let i=r;i.code!==void 0&&(e.code=i.code),n.recordOutputs&&i.message!==void 0&&(e.message=i.message)}export{contentFilteringProcessor};

package/dist/src/tracing/conversation-context.d.ts

@@ -0,0 +1,4 @@
+export declare function readConversationId(value: unknown): string | undefined;
+export declare function resolveConversationId(fallback: string): string;
+export declare function readConversationBaggage(value: string | null): string | undefined;
+export declare function writeConversationBaggage(value: string | undefined, conversationId: string | undefined): string | undefined;

package/dist/src/tracing/conversation-context.js

@@ -0,0 +1 @@
+import{contextStorage}from"#context/container.js";import{ConversationIdKey}from"#context/keys.js";import{readBaggageMember,replaceBaggageMember}from"#protocol/baggage.js";const BAGGAGE_KEY=`eve.conversation.id`,MAX_ID_BYTES=1024,encoder=new TextEncoder;function readConversationId(e){if(!(typeof e!=`string`||e.length===0||e.length>MAX_ID_BYTES||/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(e)||encoder.encode(e).byteLength>MAX_ID_BYTES))try{return e}catch{return}}function resolveConversationId(e){return readConversationId(contextStorage.getStore()?.get(ConversationIdKey))??e}function readConversationBaggage(e){let t=readBaggageMember(e,BAGGAGE_KEY);return typeof t==`string`?void 0:readConversationId(t.value)}function writeConversationBaggage(e,t){let n=readConversationId(t);return n===void 0?e:replaceBaggageMember(e,BAGGAGE_KEY,encodeURIComponent(n))}export{readConversationBaggage,readConversationId,resolveConversationId,writeConversationBaggage};

package/dist/src/tracing/error-content-context.d.ts

@@ -0,0 +1,3 @@
+import { type Context } from "#compiled/@opentelemetry/api/index.js";
+export declare function withErrorContent(context: Context, allowed: boolean): Context;
+export declare function capturesErrorContent(): boolean;

package/dist/src/tracing/error-content-context.js

@@ -0,0 +1 @@
+import{context,createContextKey}from"#compiled/@opentelemetry/api/index.js";const ERROR_CONTENT_KEY=createContextKey(`eve.trace.error-content`);function withErrorContent(e,t){return e.setValue(ERROR_CONTENT_KEY,t)}function capturesErrorContent(){return context.active().getValue(ERROR_CONTENT_KEY)!==!1}export{capturesErrorContent,withErrorContent};

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

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{ContextAgentTraceStateStore}from"#tracing/agent-trace-context-store.js";import{registerInstrumentationRuntime}from"#instrumentation/runtime.js";import{trace}from"#compiled/@opentelemetry/api/index.js";import{createInstrumentationHooks}from"#instrumentation/lifecycle.js";import{hasSessionRelease}from"#tracing/local-traces.js";import{AgentSpanIdGenerator}from"#tracing/agent-span-id-generator.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{registerOtelPipeline}from"#tracing/otel-registration.js";const log=createLogger(`tracing.install-instrumentation-runtime`);function installInstrumentationRuntime(e){let t=[],n=[],r,i,a,runInContext=(e,t)=>t();if(e.collected.declared){r=registerOtelPipeline({pipeline:e.collected.pipeline,serviceName:e.serviceName});let o=createAgentOtelInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:r.idGenerator,recordInputs:e.collected.settings.recordInputs,recordOutputs:e.collected.settings.recordOutputs,stateStore:new ContextAgentTraceStateStore,tracer:trace.getTracer(`eve.agent`,e.frameworkVersion),tracePolicy:e.collected.settings.tracePolicy});t.push({...o.hook,stateNamespace:`internal:otel`}),i=o.prepareSessionTrace,a=o.prepareTurnTrace,runInContext=o.runInContext;let s=e.collected.pipeline.spanProcessors.filter(isSpanProcessor).filter(hasSessionRelease);s.length>0&&n.push(sessionReleaseProvider(s))}let o=[...t,...e.providers,...n],s;return registerInstrumentationRuntime({forceFlush:()=>settleAll([...r===void 0?[]:[r.forceFlush],...o.map(e=>()=>e.flush?.())]),hooks:createInstrumentationHooks({parallel:e.providers,serialAfter:n,serialBefore:t}),idGenerator:r?.idGenerator??new AgentSpanIdGenerator,instrumentationProviders:e.instrumentationProviders,otelSettings:e.collected.declared?e.collected.settings:void 0,ownsAgentSpans:r!==void 0,prepareSessionTrace:i,prepareTurnTrace:a,runtimeContextResolvers:e.runtimeContextResolvers,runInContext,samplesTrace:r?.samplesTrace,shutdown:()=>(s??=settleAll([...r===void 0?[]:[r.shutdown],...o.map(e=>()=>e.shutdown?.())]),s)})}function isSpanProcessor(e){return e!==`auto`}function sessionReleaseProvider(e){let release=async t=>{await Promise.all(e.map(e=>e.releaseSession(t.sessionId)))};return{events:{"session.completed":release,"session.failed":release},name:`eve.session-release`,stateNamespace:`internal:session-release`}}async function settleAll(e){let t=await Promise.allSettled(e.map(async e=>e()));for(let e of t)e.status===`rejected`&&log.warn(`instrumentation drain failed`,{error:formatError(e.reason)})}export{installInstrumentationRuntime};
+import{createLogger,formatError}from"#internal/logging.js";import{contextStorage}from"#context/container.js";import{ConversationIdKey}from"#context/keys.js";import{readConversationId}from"#tracing/conversation-context.js";import{ContextAgentTraceStateStore}from"#tracing/agent-trace-context-store.js";import{registerInstrumentationRuntime}from"#instrumentation/runtime.js";import{trace}from"#compiled/@opentelemetry/api/index.js";import{createInstrumentationHooks}from"#instrumentation/lifecycle.js";import{AgentSpanIdGenerator}from"#tracing/agent-span-id-generator.js";import{hasConversationRelease}from"#tracing/local-traces.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{registerOtelPipeline}from"#tracing/otel-registration.js";const log=createLogger(`tracing.install-instrumentation-runtime`);function installInstrumentationRuntime(e){let t=[],n=[],r,flushSettledInvocations,i,a,runInContext=(e,t)=>t();if(e.collected.declared){r=registerOtelPipeline({pipeline:e.collected.pipeline,serviceName:e.serviceName});let o=createAgentOtelInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:r.idGenerator,recordInputs:e.collected.settings.recordInputs,recordOutputs:e.collected.settings.recordOutputs,samplesTrace:r.samplesTrace,stateStore:new ContextAgentTraceStateStore,tracer:trace.getTracer(`eve.agent`,e.frameworkVersion),tracePolicy:e.collected.settings.tracePolicy});t.push({...o.hook,stateNamespace:`internal:otel`}),flushSettledInvocations=async()=>{await o.hook.flush?.()},i=o.prepareSessionTrace,a=o.prepareTurnTrace,runInContext=o.runInContext;let s=e.collected.pipeline.spanProcessors.filter(isSpanProcessor).filter(hasConversationRelease);s.length>0&&n.push(sessionReleaseProvider(s))}let o=[...t,...e.providers,...n],s;return registerInstrumentationRuntime({flushSettledInvocations,forceFlush:async()=>{await settleAll(o.map(e=>()=>e.flush?.())),await settleAll(r===void 0?[]:[r.forceFlush])},hooks:createInstrumentationHooks({parallel:e.providers,serialAfter:n,serialBefore:t}),idGenerator:r?.idGenerator??new AgentSpanIdGenerator,instrumentationProviders:e.instrumentationProviders,otelSettings:e.collected.declared?e.collected.settings:void 0,ownsAgentSpans:r!==void 0,prepareSessionTrace:i,prepareTurnTrace:a,runtimeContextResolvers:e.runtimeContextResolvers,runInContext,samplesTrace:r?.samplesTrace,shutdown:()=>(s??=(async()=>{await settleAll(o.map(e=>()=>e.shutdown?.())),await settleAll(r===void 0?[]:[r.shutdown])})(),s)})}function isSpanProcessor(e){return e!==`auto`}function sessionReleaseProvider(e){let release=async t=>{let n=readConversationId(contextStorage.getStore()?.get(ConversationIdKey))??t.sessionId;n===t.sessionId&&await Promise.all(e.map(e=>e.releaseConversation(n)))};return{events:{"session.completed":release,"session.failed":release},name:`eve.conversation-release`,stateNamespace:`internal:conversation-release`}}async function settleAll(e){let t=await Promise.allSettled(e.map(async e=>e()));for(let e of t)e.status===`rejected`&&log.warn(`instrumentation drain failed`,{error:formatError(e.reason)})}export{installInstrumentationRuntime};

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

@@ -31,15 +31,15 @@ export interface LocalTraceSpan {
 export interface LocalTrace {
     readonly agentName?: string;
     readonly endTimeNs: bigint;
-    /** Session that opened the trace, which is the one the list shows. */
-    readonly sessionId?: string;
+    /** Conversation that owns the trace, which is the one the list shows. */
+    readonly conversationId?: string;
     /**
-     * Every session recorded in the trace, opener first.
+     * Every conversation identifier recorded in the trace.
      *
-     * A subagent child records into the trace its parent opened, so one
-     * trace can hold several sessions and any of their ids resolves to it.
+     * A logical conversation can contain separate root traces for the parent
+     * and child activations. Any matching conversation ID resolves to them.
      */
-    readonly sessionIds: readonly string[];
+    readonly conversationIds: readonly string[];
     readonly spans: readonly LocalTraceSpan[];
     readonly startTimeNs: bigint;
     readonly traceId: string;

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

@@ -1 +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 t;try{t=await readdir(resolveLocalTraceSchemaDirectory(e),{withFileTypes:!0})}catch(e){if(isMissing(e))return[];throw e}return t.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,t){let n;try{n=await readdir(resolveLocalTraceSegmentsDirectory(e,t),{withFileTypes:!0})}catch(e){if(isMissing(e))return;throw e}return n.filter(e=>e.isFile()&&SPAN_FILE_PATTERN.test(e.name)).map(e=>e.name).sort((e,t)=>e.localeCompare(t))}async function readLocalTraceSegment(e,t,n){let r=join(resolveLocalTraceSegmentsDirectory(e,t),n),i;try{if((await stat(r)).size>8388608)return[];i=await readFile(r,`utf8`)}catch{return[]}return parseLocalTraceSegment(i,t)}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}}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 isAgentTurnSpan(e)&&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 isAgentTurnSpan(e){return e.name===`agent.turn`||stringSpanAttribute(e,`gen_ai.operation.name`)===`invoke_agent`&&stringSpanAttribute(e,`agent.turn.id`)!==void 0}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,events:parseEvents(e.events),kind:typeof e.kind==`number`?e.kind:void 0,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),statusMessage:parseStatusMessage(e.status),traceId:t}}function parseEvents(e){if(!Array.isArray(e))return[];let t=[];for(let n of e){if(!isRecord(n)||typeof n.name!=`string`)continue;let e=parseNanos(n.timeUnixNano);e!==void 0&&t.push({attributes:parseAttributes(n.attributes),name:n.name,timeNs:e})}return t.sort((e,t)=>e.timeNs===t.timeNs?e.name.localeCompare(t.name):e.timeNs<t.timeNs?-1:1)}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 parseStatusMessage(e){if(isRecord(e)&&typeof e.message==`string`)return e.message.length===0?void 0:e.message}function firstAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`string`&&e.length>0)return 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,isAgentTurnSpan,listLocalTraceIds,listLocalTraceSegments,listLocalTraces,parseLocalTraceSegment,readLocalTraceActivityMs,readLocalTraceSegment};
+import{readFile,readdir,stat}from"node:fs/promises";import{join}from"node:path";import{isAgentActivationSpan}from"#tracing/agent-span-contract.js";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 t;try{t=await readdir(resolveLocalTraceSchemaDirectory(e),{withFileTypes:!0})}catch(e){if(isMissing(e))return[];throw e}return t.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,t){let n;try{n=await readdir(resolveLocalTraceSegmentsDirectory(e,t),{withFileTypes:!0})}catch(e){if(isMissing(e))return;throw e}return n.filter(e=>e.isFile()&&SPAN_FILE_PATTERN.test(e.name)).map(e=>e.name).sort((e,t)=>e.localeCompare(t))}async function readLocalTraceSegment(e,t,n){let r=join(resolveLocalTraceSegmentsDirectory(e,t),n),i;try{if((await stat(r)).size>8388608)return[];i=await readFile(r,`utf8`)}catch{return[]}return parseLocalTraceSegment(i,t)}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,`gen_ai.conversation.id`);return{agentName:firstAttribute(r,`agent.name`),endTimeNs:n.reduce((e,t)=>t.endTimeNs>e?t.endTimeNs:e,0n),conversationId:i[0],conversationIds:i,spans:n,startTimeNs:n.reduce((e,t)=>t.startTimeNs<e?t.startTimeNs:e,n[0].startTimeNs),traceId:e}}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 isAgentTurnSpan(e)&&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 isAgentTurnSpan(e){return isAgentActivationSpan(e)}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,events:parseEvents(e.events),kind:typeof e.kind==`number`?e.kind:void 0,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),statusMessage:parseStatusMessage(e.status),traceId:t}}function parseEvents(e){if(!Array.isArray(e))return[];let t=[];for(let n of e){if(!isRecord(n)||typeof n.name!=`string`)continue;let e=parseNanos(n.timeUnixNano);e!==void 0&&t.push({attributes:parseAttributes(n.attributes),name:n.name,timeNs:e})}return t.sort((e,t)=>e.timeNs===t.timeNs?e.name.localeCompare(t.name):e.timeNs<t.timeNs?-1:1)}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 parseStatusMessage(e){if(isRecord(e)&&typeof e.message==`string`)return e.message.length===0?void 0:e.message}function firstAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`string`&&e.length>0)return 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,isAgentTurnSpan,listLocalTraceIds,listLocalTraceSegments,listLocalTraces,parseLocalTraceSegment,readLocalTraceActivityMs,readLocalTraceSegment};

package/dist/src/tracing/local-traces.d.ts

@@ -8,29 +8,27 @@ import type { SpanProcessor } from "#compiled/@vercel/otel/index.js";
  */
 export interface LocalTracesProcessor extends SpanProcessor {
     /**
-     * Settles pending writes and drops one root session's liveness, then bounds
-     * the store. A subagent child owns no traces, so releasing one is a no-op
-     * and leaves the shared trace pinned until its root finishes.
+     * Settles pending writes and releases this conversation's active traces.
      */
-    releaseSession(sessionId: string): Promise<boolean>;
+    releaseConversation(conversationId: string): Promise<boolean>;
 }
 /**
- * Reports whether a processor tracks which session owns which trace, so eve can
- * tell it when that session is done.
+ * Reports whether a processor tracks which conversation owns which trace, so
+ * eve can tell it when that conversation is done.
  *
  * Anything standing between eve and the spool has to answer for the spool, so
  * this is the check a wrapper uses to decide whether it must forward the call.
  *
  * @internal
  */
-export declare function hasSessionRelease(processor: SpanProcessor): processor is LocalTracesProcessor;
+export declare function hasConversationRelease(processor: SpanProcessor): processor is LocalTracesProcessor;
 /**
  * Writes the OTLP/JSON spool under `.eve/traces/v1`.
  *
  * `EVE_TRACES=off` removes the writer but keeps the processor: eve still has
  * to observe spans to track which session owns which trace.
  *
- * Internal because of `releaseSession`, which eve's runtime drives off session
+ * Internal because of `releaseConversation`, which eve's runtime drives off session
  * lifecycle. The authored surface is `localTraces()`, which wraps this in an
  * `OtelIntegration`.
  */

package/dist/src/tracing/local-traces.js

@@ -1 +1 @@
-import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";function hasSessionRelease(e){return typeof e.releaseSession==`function`}function createLocalTracesProcessor(e={}){let t=e.appRoot??process.env.EVE_DEV_WORKER_APP_ROOT;if(t===void 0)return inertLocalTracesProcessor();let n=resolveLocalTraceRetentionSettings(),r=new AgentTraceSpanProcessor(n.enabled?[new LocalTraceSpanProcessor(t)]:[]),requestPrune=()=>{n.enabled&&requestLocalTraceStorePrune({activeTraceIds:r.activeTraceIds(),appRoot:t,maxAgeMs:n.maxAgeMs,maxTotalBytes:n.maxTotalBytes,retainCount:n.retainCount})};return requestPrune(),{forceFlush:()=>r.forceFlush(),onEnd:e=>r.onEnd(e),onStart:(e,t)=>r.onStart(e,t),async releaseSession(e){return await r.forceFlush(),r.releaseSession(e)?(requestPrune(),!0):!1},shutdown:()=>r.shutdown()}}function resolveLocalTracesContent(e={}){return process.env.EVE_TRACES_CONTENT===`off`?{recordInputs:!1,recordOutputs:!1}:{recordInputs:e.recordInputs!==!1,recordOutputs:e.recordOutputs!==!1}}function inertLocalTracesProcessor(){return{forceFlush:async()=>void 0,onEnd:()=>void 0,onStart:()=>void 0,releaseSession:async()=>!1,shutdown:async()=>void 0}}export{createLocalTracesProcessor,hasSessionRelease,resolveLocalTracesContent};
+import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";function hasConversationRelease(e){return typeof e.releaseConversation==`function`}function createLocalTracesProcessor(e={}){let t=e.appRoot??process.env.EVE_DEV_WORKER_APP_ROOT;if(t===void 0)return inertLocalTracesProcessor();let n=resolveLocalTraceRetentionSettings(),r=new AgentTraceSpanProcessor(n.enabled?[new LocalTraceSpanProcessor(t)]:[]),requestPrune=()=>{n.enabled&&requestLocalTraceStorePrune({activeTraceIds:r.activeTraceIds(),appRoot:t,maxAgeMs:n.maxAgeMs,maxTotalBytes:n.maxTotalBytes,retainCount:n.retainCount})};requestPrune();let forceFlush=async()=>{await r.forceFlush(),r.releaseCompletedTraces()&&requestPrune()};return{forceFlush,onEnd:e=>r.onEnd(e),onStart:(e,t)=>r.onStart(e,t),async releaseConversation(e){return await forceFlush(),r.releaseConversation(e)?(requestPrune(),!0):!1},shutdown:()=>r.shutdown()}}function resolveLocalTracesContent(e={}){return process.env.EVE_TRACES_CONTENT===`off`?{recordInputs:!1,recordOutputs:!1}:{recordInputs:e.recordInputs!==!1,recordOutputs:e.recordOutputs!==!1}}function inertLocalTracesProcessor(){return{forceFlush:async()=>void 0,onEnd:()=>void 0,onStart:()=>void 0,releaseConversation:async()=>!1,shutdown:async()=>void 0}}export{createLocalTracesProcessor,hasConversationRelease,resolveLocalTracesContent};

package/dist/src/tracing/otel-declaration.d.ts

@@ -28,9 +28,11 @@ export interface OtelOptions {
      */
     readonly functionId?: string;
     /**
-     * Whether to emit the inbound HTTP `SERVER` span that wraps each channel
-     * request — the parent of the turn trace and of any `hook.resume` or
-     * outgoing HTTP spans. Defaults to `false`.
+     * Whether to emit an eve-owned HTTP `SERVER` span around each channel
+     * request. For a one-to-one delivery, the activation remains a separate
+     * trace root and links to this span; when disabled, it links to any
+     * already-active upstream request or function span instead. Defaults to
+     * `false`.
      */
     readonly traceChannelRequests?: boolean;
     /**
@@ -150,7 +152,7 @@ export declare function otel(options?: OtelOptions): OtelDeclaration;
 export declare function otelIntegration(options?: OtelIntegrationOptions): OtelIntegration;
 /** @internal Local and Agent Runs destination declaration. */
 export declare function managedOtelIntegration(options?: OtelIntegrationOptions & ManagedTraceOptions): OtelIntegration;
-/** Vercel Agent Runs through the production request-context transport. @internal */
+/** Vercel Agent Runs through the hosted request-context transport. @internal */
 export declare function agentRunsIntegration(options?: ManagedTraceOptions): OtelIntegration;
 export declare function resolveContentOptions(options: ContentOptions): ResolvedContentOptions;
 export declare function isOtelDeclaration(value: unknown): value is OtelDeclaration;

package/dist/src/tracing/otel-registration.d.ts

@@ -1,5 +1,6 @@
 import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
 import type { OtelPipeline } from "#tracing/otel-declaration.js";
+import { type AgentSamplingOperation } from "#tracing/agent-span-contract.js";
 /**
  * Builds the process's one OpenTelemetry tracer provider from a merged
  * declaration, then proves it took the global slot.
@@ -18,6 +19,6 @@ export interface RegisteredOtelPipeline {
     readonly forceFlush: () => Promise<void>;
     readonly idGenerator: AgentSpanIdGenerator;
     /** Whether the installed sampler would record a trace with this id. */
-    readonly samplesTrace: (traceId: string) => boolean;
+    readonly samplesTrace: (traceId: string, operation?: AgentSamplingOperation) => boolean;
     readonly shutdown: () => Promise<void>;
 }

package/dist/src/tracing/otel-registration.js

@@ -1 +1 @@
-import{createRequire}from"node:module";import{context,metrics,propagation,trace}from"#compiled/@opentelemetry/api/index.js";import{AgentSpanIdGenerator}from"#tracing/agent-span-id-generator.js";import{registerOTel}from"#compiled/@vercel/otel/index.js";const REGISTRATION_SPAN_NAME=`eve.otel.registration`,REPLAY_DEDUPLICATION_LIMIT=1e5,require=createRequire(import.meta.url);var RegistrationMarkerPropagator=class{#e=!1;extract(e){return e}fields(){return[]}inject(){this.#e=!0}isInstalled(){return this.#e=!1,propagation.inject(context.active(),{},{set:()=>{}}),this.#e}},PrivateSpanFilteringProcessor=class{endedSpans=new Set;forwardedSpans=new Set;pendingByParent=new Map;pendingSpanCount=0;processors;startedSpans=new Set;constructor(e){this.processors=e}async forceFlush(){this.drainPendingSpans(),await Promise.all(this.processors.map(e=>e.forceFlush()))}onEnd(e){if(isRegistrationSpan(e))return;let t=spanIdentity(e);if(t!==void 0){if(this.endedSpans.has(t))return;if(this.endedSpans.size>=REPLAY_DEDUPLICATION_LIMIT){let e=this.endedSpans.values().next().value;e!==void 0&&this.endedSpans.delete(e)}this.endedSpans.add(t)}let n=parentIdentity(e);if(n!==void 0&&this.startedSpans.has(n)&&!this.forwardedSpans.has(n)){let t=this.pendingByParent.get(n)??[];t.push(e),this.pendingByParent.set(n,t),this.pendingSpanCount+=1,this.pendingSpanCount>1e4&&this.releaseOldestPendingParent();return}this.forward(e,t)}onStart(e,t){if(isRegistrationSpan(e))return;let n=spanIdentity(e);n!==void 0&&addBounded(this.startedSpans,n);for(let n of this.processors)n.onStart(e,t)}async shutdown(){this.drainPendingSpans(),await Promise.all(this.processors.map(e=>e.shutdown()))}drainPendingSpans(){for(;this.pendingByParent.size>0;)this.releaseOldestPendingParent()}releaseOldestPendingParent(){let e=this.pendingByParent.keys().next().value;e!==void 0&&this.releaseChildren(e)}releaseChildren(e){let t=this.pendingByParent.get(e);if(t!==void 0){this.pendingByParent.delete(e),this.pendingSpanCount-=t.length;for(let e of t)this.forward(e,spanIdentity(e))}}forward(e,t){for(let t of this.processors)t.onEnd(e);t!==void 0&&(addBounded(this.forwardedSpans,t),this.releaseChildren(t))}};function registerOtelPipeline(e){let{pipeline:t}=e,n=captureOptionalPeerTracerProxy(),r=new AgentSpanIdGenerator,i=new RegistrationMarkerPropagator,a={attributes:t.resource,autoDetectResources:!1,idGenerator:r,instrumentations:t.instrumentations??[],metricReaders:t.metricReaders,propagators:[...t.propagators??[`auto`],i],serviceName:e.serviceName,spanProcessors:t.spanProcessors.map(e=>isSpanProcessor(e)?new PrivateSpanFilteringProcessor([e]):e)};registerOTel(t.sampler===void 0?a:{...a,traceSampler:t.sampler});let o=globalTracerUses(r),s=i.isInstalled();if((!o||!s)&&rollbackRegistration({ownsPropagator:s,ownsTracer:o}),!o)throw Error("eve could not register OpenTelemetry because another runtime already owns the global tracer provider. Remove the other `registerOTel` call, or move its exporters into eve's `otelIntegration({ spanProcessors: [...] })`.");if(!s)throw Error("eve could not register OpenTelemetry because another runtime already owns the global propagator. Remove the other global propagator registration and declare propagators through eve's `otel()` instead.");let c=runtimeTracerProvider();if(typeof c.forceFlush!=`function`||typeof c.shutdown!=`function`)throw rollbackRegistration({ownsPropagator:s,ownsTracer:o}),Error(`The registered OpenTelemetry tracer provider has no lifecycle methods.`);n?.setDelegate(c);let l=runtimeMeterProvider();return{forceFlush:async()=>{await Promise.all([c.forceFlush(),l.forceFlush?.()])},idGenerator:r,samplesTrace:e=>samplerAdmitsTrace(r,e),shutdown:async()=>{disableInstrumentations(t.instrumentations),await Promise.all([c.shutdown(),l.shutdown?.()])}}}function samplerAdmitsTrace(e,t){return(e.withTraceId(t,()=>trace.getTracer(`eve.registration`).startSpan(REGISTRATION_SPAN_NAME,{root:!0})).spanContext().traceFlags&1)==1}function captureOptionalPeerTracerProxy(){try{let e=require("@opentelemetry/api"),t=e.trace.getTracerProvider();return t instanceof e.ProxyTracerProvider?t:void 0}catch{return}}function rollbackRegistration(e){if(e.ownsPropagator&&propagation.disable(),!e.ownsTracer)return;let t=runtimeTracerProvider();if(typeof t.shutdown==`function`)try{t.shutdown().catch(()=>{})}catch{}trace.disable()}function runtimeTracerProvider(){let e=trace.getTracerProvider();return e.getDelegate?.()??e}function runtimeMeterProvider(){let e=metrics.getMeterProvider();return{forceFlush:typeof e?.forceFlush==`function`?()=>e.forceFlush():void 0,shutdown:typeof e?.shutdown==`function`?()=>e.shutdown():void 0}}function disableInstrumentations(e){for(let t of e??[]){let e=t?.disable;if(typeof e==`function`)try{e.call(t)}catch{}}}function globalTracerUses(e){let t=e.allocateSpanId();return e.withSpanId(t,()=>trace.getTracer(`eve.registration`).startSpan(REGISTRATION_SPAN_NAME)).spanContext().spanId===t}function isRegistrationSpan(e){return typeof e==`object`&&!!e&&`name`in e&&e.name===REGISTRATION_SPAN_NAME}function spanIdentity(e){if(typeof e!=`object`||!e||!(`spanContext`in e)||typeof e.spanContext!=`function`)return;let t=e.spanContext();return typeof t.traceId==`string`&&typeof t.spanId==`string`?`${t.traceId}:${t.spanId}`:void 0}function parentIdentity(e){if(typeof e!=`object`||!e||!(`parentSpanContext`in e))return;let t=e.parentSpanContext;return typeof t?.traceId==`string`&&typeof t.spanId==`string`?`${t.traceId}:${t.spanId}`:void 0}function addBounded(e,t){if(e.size>=REPLAY_DEDUPLICATION_LIMIT){let t=e.values().next().value;t!==void 0&&e.delete(t)}e.add(t)}function isSpanProcessor(e){return e!==`auto`}export{registerOtelPipeline};
+import{createRequire}from"node:module";import{agentInvocationSpanName}from"#tracing/agent-span-contract.js";import{SpanKind,context,metrics,propagation,trace}from"#compiled/@opentelemetry/api/index.js";import{AgentSpanIdGenerator}from"#tracing/agent-span-id-generator.js";import{registerOTel}from"#compiled/@vercel/otel/index.js";const REGISTRATION_SPAN_NAME=`eve.otel.registration`,REPLAY_DEDUPLICATION_LIMIT=1e5,REPLAY_DEDUPLICATION_KEY=Symbol.for(`eve.otel.replay-deduplication`),require=createRequire(import.meta.url),replayDeduplicationGlobal=globalThis;var RegistrationMarkerPropagator=class{#e=!1;extract(e){return e}fields(){return[]}inject(){this.#e=!0}isInstalled(){return this.#e=!1,propagation.inject(context.active(),{},{set:()=>{}}),this.#e}},PrivateSpanFilteringProcessor=class{endedSpans;forwardedSpans=new Set;pendingByParent=new Map;pendingSpanCount=0;processors;startedSpans=new Set;constructor(e,t){this.processors=e,this.endedSpans=t}async forceFlush(){this.drainPendingSpans(),await Promise.all(this.processors.map(e=>e.forceFlush()))}onEnd(e){if(isRegistrationSpan(e))return;let t=spanIdentity(e);if(t!==void 0){if(this.endedSpans.has(t))return;if(this.endedSpans.size>=REPLAY_DEDUPLICATION_LIMIT){let e=this.endedSpans.values().next().value;e!==void 0&&this.endedSpans.delete(e)}this.endedSpans.add(t)}let n=parentIdentity(e);if(n!==void 0&&this.startedSpans.has(n)&&!this.forwardedSpans.has(n)){let t=this.pendingByParent.get(n)??[];t.push(e),this.pendingByParent.set(n,t),this.pendingSpanCount+=1,this.pendingSpanCount>1e4&&this.releaseOldestPendingParent();return}this.forward(e,t)}onStart(e,t){if(isRegistrationSpan(e))return;let n=spanIdentity(e);n!==void 0&&addBounded(this.startedSpans,n);for(let n of this.processors)n.onStart(e,t)}async shutdown(){this.drainPendingSpans(),await Promise.all(this.processors.map(e=>e.shutdown()))}drainPendingSpans(){for(;this.pendingByParent.size>0;)this.releaseOldestPendingParent()}releaseOldestPendingParent(){let e=this.pendingByParent.keys().next().value;e!==void 0&&this.releaseChildren(e)}releaseChildren(e){let t=this.pendingByParent.get(e);if(t!==void 0){this.pendingByParent.delete(e),this.pendingSpanCount-=t.length;for(let e of t)this.forward(e,spanIdentity(e))}}forward(e,t){for(let t of this.processors)t.onEnd(e);t!==void 0&&(addBounded(this.forwardedSpans,t),this.releaseChildren(t))}};function registerOtelPipeline(e){let{pipeline:t}=e,n=captureOptionalPeerTracerProxy(),r=new AgentSpanIdGenerator,i=new RegistrationMarkerPropagator,a=privateSpanProcessors(t.spanProcessors),o={attributes:t.resource,autoDetectResources:!1,idGenerator:r,instrumentations:t.instrumentations??[],metricReaders:t.metricReaders,propagators:[...t.propagators??[`auto`],i],serviceName:e.serviceName,spanProcessors:a};registerOTel(t.sampler===void 0?o:{...o,traceSampler:t.sampler});let s=globalTracerUses(r),c=i.isInstalled();if((!s||!c)&&rollbackRegistration({ownsPropagator:c,ownsTracer:s}),!s)throw Error("eve could not register OpenTelemetry because another runtime already owns the global tracer provider. Remove the other `registerOTel` call, or move its exporters into eve's `otelIntegration({ spanProcessors: [...] })`.");if(!c)throw Error("eve could not register OpenTelemetry because another runtime already owns the global propagator. Remove the other global propagator registration and declare propagators through eve's `otel()` instead.");let l=runtimeTracerProvider();if(typeof l.forceFlush!=`function`||typeof l.shutdown!=`function`)throw rollbackRegistration({ownsPropagator:c,ownsTracer:s}),Error(`The registered OpenTelemetry tracer provider has no lifecycle methods.`);n?.setDelegate(l);let u=runtimeMeterProvider();return{forceFlush:async()=>{await Promise.all([l.forceFlush(),u.forceFlush?.()])},idGenerator:r,samplesTrace:(e,t)=>samplerAdmitsTrace(r,e,t),shutdown:async()=>{disableInstrumentations(t.instrumentations),await Promise.all([l.shutdown(),u.shutdown?.()])}}}function privateSpanProcessors(e){let t=e.filter(isSpanProcessor);if(t.length===0)return[...e];let n=new PrivateSpanFilteringProcessor(t,replayDeduplicationRegistry()),r=[],i=!1;for(let t of e){if(!isSpanProcessor(t)){r.push(t);continue}i||(i=!0,r.push(n))}return r}function replayDeduplicationRegistry(){let e=replayDeduplicationGlobal[REPLAY_DEDUPLICATION_KEY];if(e!==void 0)return e;let t=new Set;return replayDeduplicationGlobal[REPLAY_DEDUPLICATION_KEY]=t,t}function samplerAdmitsTrace(e,t,n={name:agentInvocationSpanName(void 0)}){return(e.withTraceId(t,()=>trace.getTracer(`eve.registration`).startSpan(n.name,{attributes:n.attributes,kind:SpanKind.INTERNAL,root:!0})).spanContext().traceFlags&1)==1}function captureOptionalPeerTracerProxy(){try{let e=require("@opentelemetry/api"),t=e.trace.getTracerProvider();return t instanceof e.ProxyTracerProvider?t:void 0}catch{return}}function rollbackRegistration(e){if(e.ownsPropagator&&propagation.disable(),!e.ownsTracer)return;let t=runtimeTracerProvider();if(typeof t.shutdown==`function`)try{t.shutdown().catch(()=>{})}catch{}trace.disable()}function runtimeTracerProvider(){let e=trace.getTracerProvider();return e.getDelegate?.()??e}function runtimeMeterProvider(){let e=metrics.getMeterProvider();return{forceFlush:typeof e?.forceFlush==`function`?()=>e.forceFlush():void 0,shutdown:typeof e?.shutdown==`function`?()=>e.shutdown():void 0}}function disableInstrumentations(e){for(let t of e??[]){let e=t?.disable;if(typeof e==`function`)try{e.call(t)}catch{}}}function globalTracerUses(e){let t=e.allocateSpanId();return e.withSpanId(t,()=>trace.getTracer(`eve.registration`).startSpan(REGISTRATION_SPAN_NAME)).spanContext().spanId===t}function isRegistrationSpan(e){return typeof e==`object`&&!!e&&(`name`in e&&e.name===REGISTRATION_SPAN_NAME||`instrumentationScope`in e&&e.instrumentationScope?.name===`eve.registration`)}function spanIdentity(e){if(typeof e!=`object`||!e||!(`spanContext`in e)||typeof e.spanContext!=`function`)return;let t=e.spanContext();return typeof t.traceId==`string`&&typeof t.spanId==`string`?`${t.traceId}:${t.spanId}`:void 0}function parentIdentity(e){if(typeof e!=`object`||!e||!(`parentSpanContext`in e))return;let t=e.parentSpanContext;return typeof t?.traceId==`string`&&typeof t.spanId==`string`?`${t.traceId}:${t.spanId}`:void 0}function addBounded(e,t){if(e.size>=REPLAY_DEDUPLICATION_LIMIT){let t=e.values().next().value;t!==void 0&&e.delete(t)}e.add(t)}function isSpanProcessor(e){return e!==`auto`}export{registerOtelPipeline};

package/dist/src/tracing/telemetry-budget.d.ts

@@ -0,0 +1,4 @@
+export declare const TELEMETRY_PRINCIPAL_ID_BYTES = 1024;
+export declare function boundedPrincipalId(value: unknown): string | undefined;
+export declare function telemetryByteLength(text: string): number;
+export declare function truncateTelemetryText(text: string, maxBytes: number): string;

package/dist/src/tracing/telemetry-budget.js

@@ -0,0 +1 @@
+const TELEMETRY_PRINCIPAL_ID_BYTES=1024;function boundedPrincipalId(e){return typeof e==`string`&&e.length>0&&e.length<=1024&&telemetryByteLength(e)<=1024?e:void 0}const encoder=new TextEncoder,decoder=new TextDecoder;function telemetryByteLength(e){return encoder.encode(e).length}function truncateTelemetryText(e,t){let n=e.slice(0,t+1),r=encoder.encode(n);if(n.length===e.length&&r.length<=t)return e;let i=`... [truncated]`.slice(0,t),a=Math.max(0,t-i.length);for(;a>0&&(r[a]&192)==128;)--a;return decoder.decode(r.subarray(0,a))+i}export{TELEMETRY_PRINCIPAL_ID_BYTES,boundedPrincipalId,telemetryByteLength,truncateTelemetryText};

package/docs/agent-config.md

@@ -283,18 +283,52 @@ disappear in any release. See [Execution model and
 durability](./concepts/execution-model-and-durability#resuming-after-a-crash)
 for the retry behavior.
 
+## Run data retention
+
+The runtime keeps each run's data after the run finishes: model and tool
+payloads, streamed output, and the event log eve replays from. How long it keeps
+them is the World's decision, and on Vercel that follows your team's plan. Set
+`experimental.workflow.retention` to `0` to have it deleted as soon as the run
+finishes instead:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-4.8",
+  experimental: {
+    workflow: {
+      retention: 0,
+    },
+  },
+});
+```
+
+This will be applied to the session run and every turn run the session
+dispatches, as well as the run that collects session activity. Runs eve
+starts for other purposes keep the world's default: session timeouts,
+background tasks, and [workflow tools](./tools/workflows).
+
+The value applies per agent. A [subagent](./subagents) that runs its own session
+uses its own value, unlike `experimental.workflow.world`, which is root-only.
+
+Custom Worlds used with eve might not support this feature, in which case
+it falls back to the World's default retention period.
+
+> ⚠️ **At `0`, a finished session's output is usually gone before you can read it.** Since data is deleted immediately before it can be read back, results and transcripts become unreadable and a client polling for a finished session's output can see it disappear.
+
 ## Other defineAgent fields
 
 `defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
 
-| Field          | Type                                    | Default          | Description                                                                                                                                                                                              |
-| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                            |
-| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                   |
-| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                              |
-| `experimental` | `AgentExperimentalDefinition`           | unset            | Unstable opt-ins. `workflow.world` selects the Workflow world package on the root agent; `workflow.modelCallsPerStep` batches sequential model calls into a wider replay unit.                           |
-| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for function-like invocations such as a subagent turn, schedule, or remote job. Ordinary interactive turns ignore it unless the client supplies a per-message schema.             |
-| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |
+| Field          | Type                                    | Default          | Description                                                                                                                                                                                                                                               |
+| -------------- | --------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                                                             |
+| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                                                                    |
+| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                                                               |
+| `experimental` | `AgentExperimentalDefinition`           | unset            | Unstable opt-ins. `workflow.world` selects the Workflow world package on the root agent; `workflow.modelCallsPerStep` batches sequential model calls into a wider replay unit; `workflow.retention` controls how long the durable runtime keeps run data. |
+| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for function-like invocations such as a subagent turn, schedule, or remote job. Ordinary interactive turns ignore it unless the client supplies a per-message schema.                                                              |
+| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                  |
 
 `externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
 

package/docs/channels/slack.mdx

@@ -53,7 +53,7 @@ Use this fallback when the agent does not run on Vercel or Vercel Connect is una
 
 This option does not create or install the Slack app. Configure it in [Slack app settings](https://api.slack.com/apps):
 
-1. Add the `app_mentions:read` and `chat:write` bot scopes. Add `im:history` for DMs, `files:read` for inbound attachments, and `files:write` when the agent uploads files.
+1. Add the `app_mentions:read` and `chat:write` bot scopes. Add `im:history` for DMs, `files:read` for inbound attachments, and `files:write` for explicit uploads and automatic long-response snippets.
 2. Install or reinstall the app, copy its Bot User OAuth Token to `SLACK_BOT_TOKEN`, and copy the signing secret from **Basic Information** to `SLACK_SIGNING_SECRET`.
 3. Set both values in `.env.local` for local development or in the target runtime's environment, then start or deploy the agent at a public URL.
 4. Under **Event Subscriptions**, set the Request URL to `https://your-agent.example/eve/v1/slack`. Subscribe to `app_mention`, plus `message.im` for DMs.
@@ -133,6 +133,7 @@ Check the delivery path in order so you can identify where a Slack event stops:
 | Setup says it could not remove an existing trigger destination        | Check the connector's destinations in the Connect dashboard. `vercel connect detach` removes project token access, not trigger destinations.                                           | Edit or remove the stale destination in the dashboard, then register `/eve/v1/slack` with `vercel connect attach`.                                                   |
 | Mentions never reach the deployment                                   | Confirm that the connector trigger destination uses the intended project and branch, enables triggers, and points to `/eve/v1/slack`.                                                  | Edit or remove stale destinations in the Connect dashboard, then register the intended destination with `vercel connect attach`.                                     |
 | Mentions work but DMs or thread replies do not                        | Check the Slack app's Event Subscriptions and OAuth scopes. DMs require `message.im` and `im:history`; channel replies require the matching message event and history scope.           | Add the missing events or scopes, then reinstall the Slack app if Slack requires it.                                                                                 |
+| A long response cannot be uploaded as a snippet                       | Check whether the installed Slack app has the `files:write` bot scope.                                                                                                                 | Add `files:write`, then reinstall the Slack app so the new scope takes effect.                                                                                       |
 | A preview request receives an authentication page or protection error | Check whether the branch domain is exempt or the direct Slack request URL includes `x-vercel-protection-bypass`. Slack cannot complete an interactive Vercel Authentication challenge. | Add a Deployment Protection Exception for the branch domain, or add the automation bypass query parameter to a Slack app that uses environment-variable credentials. |
 | The webhook reaches the deployment but the agent does not reply       | Open the project's Vercel runtime logs, then inspect the session in **Agent Runs** when your team has access.                                                                          | Use the first missing or failed stage to narrow the issue to channel dispatch, the agent run, or outbound Slack delivery.                                            |
 
@@ -414,11 +415,13 @@ when you need the bearer token itself.
 
 The default handlers reply in-thread and show activity. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and an action label on `actions.requested` — the tool name plus its most telling argument (`grep useEveAgent`, `read_file agent/agent.ts`), the subagent or remote-agent name for dispatched calls, and `+N more` when the model requests several actions at once. The model's own pre-tool narration, when present, takes precedence over the derived label. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use the five-second refresh interval to avoid one Slack request per token. Override `events["reasoning.appended"]` if you prefer generic wording. Override an inbound handler or the `events` handlers to customize.
 
+The built-in `message.completed` handler renders responses up to 12,000 characters inline. Longer responses are uploaded unchanged as a Markdown snippet named `eve-response.md` with a short in-thread note, which requires the `files:write` bot scope. Upload failures are logged by the channel dispatcher; they do not trigger a model retry. An authored `events["message.completed"]` handler replaces this behavior and owns its own delivery limits.
+
 Outbound text preserves bare `@` tokens as literal text. To mention a user, embed Slack's `<@USER_ID>` syntax directly or use `channel.thread.mentionUser(userId)`.
 
 When a session starts without a `threadTs` (say, from a schedule's `to(slack, target).send(...)`), eve gives it a unique temporary continuation token. The first agent post anchors the session to the Slack message timestamp, and later posts and mentions resume that same session. Pass `initialMessage` with a `Card` to land a structured anchor first instead. `threadTs` and `initialMessage` are mutually exclusive.
 
-The example below overrides `onAppMention` to gate on an authored message and posts the completed reply to the thread. Event handlers receive `(eventData, channel, ctx)`, with Slack platform handles on `channel.thread` and `channel.slack`:
+The example below overrides `onAppMention` to gate on an authored message. The built-in completion handler still posts the reply and uploads long responses as snippets. Event handlers receive `(eventData, channel, ctx)`, with Slack platform handles on `channel.thread` and `channel.slack`:
 
 ```ts
 import { defaultSlackAuth, slackChannel } from "eve/channels/slack";
@@ -428,12 +431,6 @@ export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
   onAppMention: (ctx, message) =>
     message.author ? { auth: defaultSlackAuth(message, ctx) } : null,
-  events: {
-    "message.completed"(eventData, channel, ctx) {
-      if (eventData.finishReason === "tool-calls") return;
-      if (eventData.message) channel.thread.post(eventData.message);
-    },
-  },
 });
 ```
 

package/docs/guides/instrumentation-providers.md

@@ -153,6 +153,8 @@ export default otelIntegration({
 });
 ```
 
+Custom destinations receive the schema v4 agent trace contract. Follow [Query exported traces](./instrumentation#query-exported-traces) to find activations and join sessions across traces.
+
 Add `agent/instrumentation/otel.ts` when you need process-wide settings or want to control which content eve writes to OpenTelemetry spans:
 
 ```ts title="agent/instrumentation/otel.ts"
@@ -217,7 +219,7 @@ Policies run in declaration order. A later policy sees the filtered span produce
 The provider layout adds two environment-specific defaults:
 
 - `local` records local traces during `eve dev`.
-- `agent-runs` exports to Vercel Agent Runs in production.
+- `agent-runs` exports to Vercel Agent Runs in preview and production deployments.
 
 Omitting these files preserves the defaults. Reconfigure a slot by exporting `localTraces()` or `agentRuns()` from the matching file. Disable one explicitly:
 
@@ -235,6 +237,9 @@ An ordinary tool emits both `action.*` and `tool.call.*` events. Use `action.*`
 
 Handlers for different providers run concurrently and are failure-isolated. Do not depend on provider execution order. Use `flush` to drain buffered records and `shutdown` to release resources.
 
+The [agent trace contract](./instrumentation#agent-trace-contract) defines span
+names, identities, and usage counters shared by the exporters and local viewers.
+
 ## What to read next
 
 - [Observability](./instrumentation): the default `instrumentation.ts` API and trace hierarchy