eve 0.81.1 → 0.82.0

package/dist/src/tools/workflow-definition.d.ts

@@ -1,6 +1,7 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { ToolApproval } from "#approval/definition.js";
 import type { MessageResult, SendTurnOptions } from "#client/types.js";
+import type { AgentModelOptionsDefinition, AgentReasoningDefinition } from "#shared/agent-definition.js";
 import type { JsonObject } from "#shared/json.js";
 import { type PublicToolDefinition, type ToolContext, type ToolInputRequest, type ToolInputRequestOptions, type ToolInputResponse } from "#tools/definition.js";
 import type { ToolModelOutput } from "#tools/model-output.js";
@@ -9,6 +10,18 @@ export type { WorkflowToolEntryPoint };
 export interface WorkflowAgentMetadata {
     readonly description: string;
 }
+/** A serializable model selection for a local `ctx.agent` session. */
+export type AgentSessionModelSelection = string | {
+    readonly model: string;
+    readonly modelContextWindowTokens?: number;
+    readonly modelOptions?: AgentModelOptionsDefinition;
+    readonly reasoning?: AgentReasoningDefinition;
+};
+/** Options that bind to a `ctx.agent` session when it opens. */
+export interface AgentSessionOptions {
+    /** Override the model for every turn in this local agent session. */
+    readonly model?: AgentSessionModelSelection;
+}
 /** Context capabilities available inside an authored `"use step"` helper. */
 export type WorkflowStepToolContext = Pick<ToolContext, "abortSignal" | "callId" | "session" | "toolName" | "getToken" | "requireAuth">;
 /** Options for one message to a `ctx.agent` session. */
@@ -54,7 +67,7 @@ export type WorkflowSharedContext = Pick<ToolContext, "session" | "toolName" | "
      * Returns a new session with the agent of this invocation name. Nothing
      * starts until the first `send`.
      */
-    agent(name: string): AgentSession;
+    agent(name: string, options?: AgentSessionOptions): AgentSession;
     /** Metadata for agents callable by this workflow, including hidden agents. */
     agents: Readonly<Record<string, WorkflowAgentMetadata>>;
     /**

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

@@ -3,10 +3,13 @@ export declare function withConversationId(context: Context, conversationId: str
 interface OperationConversation {
     readonly rootSessionId?: string;
     readonly sessionId: string;
+    readonly traceSessionId?: string;
 }
+export declare function traceSessionIdOf(scope: OperationConversation): string;
 export declare function operationConversationId(input: OperationConversation): string;
-export declare function withOperationConversation(context: Context, input: OperationConversation): Context;
+export declare function withOperationTraceContext(context: Context, input: OperationConversation): Context;
 export declare function conversationIdFromContext(context: unknown): string | undefined;
+export declare function traceSessionIdFromContext(context: unknown): string | undefined;
 export declare function readConversationBaggage(value: string | null): string | undefined;
 export declare function writeConversationBaggage(value: string | undefined, conversationId: string | undefined): string | undefined;
 export {};

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

@@ -1 +1 @@
-import{readBaggageMember,replaceBaggageMember}from"#protocol/baggage.js";import{readConversationId,resolveConversationId}from"#shared/conversation-identity.js";import{createContextKey}from"#compiled/@opentelemetry/api/index.js";const BAGGAGE_KEY=`eve.conversation.id`,CONVERSATION_KEY=createContextKey(`eve.trace.conversation.id`);function withConversationId(e,t){return e.setValue(CONVERSATION_KEY,t)}function operationConversationId(e){return resolveConversationId(e.rootSessionId??e.sessionId)}function withOperationConversation(e,t){return withConversationId(e,operationConversationId(t))}function conversationIdFromContext(e){if(typeof e!=`object`||!e)return;let t=Reflect.get(e,`getValue`);return typeof t==`function`?readConversationId(Reflect.apply(t,e,[CONVERSATION_KEY])):void 0}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{conversationIdFromContext,operationConversationId,readConversationBaggage,withConversationId,withOperationConversation,writeConversationBaggage};
+import{readBaggageMember,replaceBaggageMember}from"#protocol/baggage.js";import{readConversationId,resolveConversationId}from"#shared/conversation-identity.js";import{createContextKey}from"#compiled/@opentelemetry/api/index.js";const BAGGAGE_KEY=`eve.conversation.id`,CONVERSATION_KEY=createContextKey(`eve.trace.conversation.id`),TRACE_SESSION_KEY=createContextKey(`eve.trace.session.id`);function withConversationId(e,t){return e.setValue(CONVERSATION_KEY,t)}function traceSessionIdOf(e){return e.traceSessionId??e.rootSessionId??e.sessionId}function operationConversationId(e){return resolveConversationId(e.rootSessionId??e.sessionId)}function withOperationTraceContext(e,t){return withConversationId(e,operationConversationId(t)).setValue(TRACE_SESSION_KEY,traceSessionIdOf(t))}function conversationIdFromContext(e){return readConversationId(readContextValue(e,CONVERSATION_KEY))}function traceSessionIdFromContext(e){let t=readContextValue(e,TRACE_SESSION_KEY);return typeof t==`string`&&t.length>0?t:void 0}function readContextValue(e,t){if(typeof e!=`object`||!e)return;let n=Reflect.get(e,`getValue`);if(typeof n==`function`)return Reflect.apply(n,e,[t])}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{conversationIdFromContext,operationConversationId,readConversationBaggage,traceSessionIdFromContext,traceSessionIdOf,withConversationId,withOperationTraceContext,writeConversationBaggage};

package/dist/src/tracing/eve/invoke-tool-span.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{applyLiveDeliveryAudienceCeiling}from"#shared/forwarded-trace-policy.js";import{DIRECT_TOOL_CALL_ATTRIBUTE,DIRECT_TOOL_CALL_VALUE}from"#tracing/local/inspection.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{operationConversationId}from"#tracing/eve/conversation-context.js";import{resolveTracePolicy}from"#shared/trace-policy.js";import{context}from"#compiled/@opentelemetry/api/index.js";import{buildConversationContext}from"#channel/conversation-context.js";import{markAgentTraceContext}from"#tracing/eve/agent-trace-context.js";import{toolCallIdempotencyKey}from"#instrumentation/lifecycle.js";import{contentAttribute,mcpLifecycle,withErrorContent}from"#compiled/@vercel/agent-runs/otel.js";import{otelTelemetry}from"#compiled/@vercel/agent-runs/index.js";import{getInstrumentationRuntime}from"#instrumentation/runtime-global.js";import{MCP_SERIALIZER}from"#tracing/eve/mcp.js";import{withChannelAudience}from"#tracing/eve/channel-audience-context.js";import{eveOutputMapping}from"#tracing/eve/profile.js";const log=createLogger(`invoke-tool`),agentTelemetry=()=>otelTelemetry({tracerName:`eve.agent`,mapping:eveOutputMapping()});async function withInvokeToolSpan(e,t){let n=withErrorContent(context.active(),!1);return await context.with(n,()=>traced(e,n,t))}async function traced(e,t,n){let r=getInstrumentationRuntime();if(r===void 0)return await n(silentObserver);let i=agentTelemetry(),a=buildConversationContext({adapter:e.origin?.adapter??{kind:`channel`},auth:e.auth,channelName:e.origin?.channelName},resolveInstrumentationEnvironment()),o=toolCallEvents(r.hooks.forTrace?.({agentName:e.agentName,...a})??r.hooks,{attemptId:e.callId,attemptIndex:0,channelAudience:a.audience,functionId:e.agentName,rootSessionId:e.sessionId,sessionId:e.sessionId,stepIndex:0,traceSessionId:e.sessionId,turnId:e.callId},e),s=r.otelSettings;if(s===void 0)return await n(o.observer(void 0));let c=resolveTracePolicy(s.tracePolicy,{agentName:e.agentName,...a},e=>log.warn(`tracePolicy threw; dropping the tool call's trace`,{error:formatError(e)}));if(c.action===`drop`)return await i.suppressed(()=>n(o.observer(void 0)));let l=applyLiveDeliveryAudienceCeiling({...c,recordInputs:s.recordInputs&&c.recordInputs,recordOutputs:s.recordOutputs&&c.recordOutputs},a.audience,void 0,a.environment),u=l.action===`record`&&l.recordInputs,d=l.action===`record`&&l.recordOutputs,f=`execute_tool ${e.toolName}`,p=withChannelAudience(t,a.audience),m={"agent.tool.is_framework":!1,"gen_ai.agent.name":e.agentName,"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":e.callId,"gen_ai.tool.name":e.toolName,"gen_ai.tool.type":`function`,[DIRECT_TOOL_CALL_ATTRIBUTE]:DIRECT_TOOL_CALL_VALUE,"operation.name":`execute_tool`,"resource.name":f,"agent.run.id":e.sessionId,"agent.trace.schema.version":4,"gen_ai.conversation.id":operationConversationId({sessionId:e.sessionId})};process.env.VERCEL_ENV!==void 0&&(m[`vercel.session_id`]=e.sessionId),e.origin!==void 0&&(m[`eve.channel.kind`]=a.channel.kind,m[`eve.channel.name`]=e.origin.channelName);let h=i.startSpan({type:`tool`,operationId:e.callId,name:f,kind:`INTERNAL`,attributes:m},{context:p}),g={emit:!0,recordInputs:u,recordOutputs:d},_=markAgentTraceContext(withErrorContent(p,d)),v=mcpLifecycle({serializer:MCP_SERIALIZER,...g,write:e=>setDefined(h,e),error:(e,t)=>h.fail(d?e:void 0,t)}),y,b=o.observer({failedWith:e=>{y={error:e}},recordInputs:u,span:h});try{let e=await i.run({type:`tool`,reference:h.reference,capture:g,mcp:v},()=>n(b),_);if(h.setAttribute(`eve.tool.outcome`,e.status),e.status===`completed`&&d){let t=contentAttribute(e.output);t!==void 0&&h.setAttribute(`gen_ai.tool.call.result`,t)}return e.status===`invalid-input`?h.fail(void 0,e.status):e.status===`failed`&&h.fail(d?y?.error:void 0,y===void 0?e.status:void 0),e}catch(e){throw h.fail(d?e:void 0),e}finally{h.end(),await r.forceFlush().catch(e=>{log.warn(`flushing a tool call's trace failed`,{error:formatError(e)})})}}const silentObserver={executed:async()=>{},executing:async()=>{},failedWith:()=>{}};function toolCallEvents(e,t,n){let r=e.capturesInputs??e.capturesContent,i=e.capturesOutputs??e.capturesContent,a=toolCallIdempotencyKey(t,n.callId,0);return{observer(o){return{async executing(i){if(o?.recordInputs){let e=contentAttribute(i);e!==void 0&&o.span.setAttribute(`gen_ai.tool.call.arguments`,e)}await e.publish(Object.freeze({callId:n.callId,idempotencyKey:a,input:r?i:void 0,scope:t,toolName:n.toolName,type:`tool.call.started`}))},async executed(n){o?.span.setAttribute(`gen_ai.execute_tool.duration`,n.durationMs/1e3);let r=n.type===`result`?i?{output:n.output,type:`result`}:{type:`result`}:i?{error:n.error,type:`error`}:{type:`error`};await e.publish(Object.freeze({durationMs:n.durationMs,idempotencyKey:a,output:Object.freeze(r),scope:t,type:`tool.call.completed`,outcome:n.type===`result`?`completed`:`failed`}))},failedWith(e){o?.failedWith(e)}}}}}function setDefined(e,t){for(let[n,r]of Object.entries(t))r!==void 0&&e.setAttribute(n,r)}export{withInvokeToolSpan};
+import{createLogger,formatError}from"#internal/logging.js";import{applyLiveDeliveryAudienceCeiling}from"#shared/forwarded-trace-policy.js";import{DIRECT_TOOL_CALL_ATTRIBUTE,DIRECT_TOOL_CALL_VALUE}from"#tracing/local/inspection.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{operationConversationId,withOperationTraceContext}from"#tracing/eve/conversation-context.js";import{resolveTracePolicy}from"#shared/trace-policy.js";import{context}from"#compiled/@opentelemetry/api/index.js";import{buildConversationContext}from"#channel/conversation-context.js";import{markAgentTraceContext}from"#tracing/eve/agent-trace-context.js";import{toolCallIdempotencyKey}from"#instrumentation/lifecycle.js";import{contentAttribute,mcpLifecycle,withErrorContent}from"#compiled/@vercel/agent-runs/otel.js";import{otelTelemetry}from"#compiled/@vercel/agent-runs/index.js";import{getInstrumentationRuntime}from"#instrumentation/runtime-global.js";import{MCP_SERIALIZER}from"#tracing/eve/mcp.js";import{withChannelAudience}from"#tracing/eve/channel-audience-context.js";import{eveOutputMapping}from"#tracing/eve/profile.js";const log=createLogger(`invoke-tool`),agentTelemetry=()=>otelTelemetry({tracerName:`eve.agent`,mapping:eveOutputMapping()});async function withInvokeToolSpan(e,t){let n=withErrorContent(context.active(),!1);return await context.with(n,()=>traced(e,n,t))}async function traced(e,t,n){let r=getInstrumentationRuntime();if(r===void 0)return await n(silentObserver);let i=agentTelemetry(),a=buildConversationContext({adapter:e.origin?.adapter??{kind:`channel`},auth:e.auth,channelName:e.origin?.channelName},resolveInstrumentationEnvironment()),o=r.hooks.forTrace?.({agentName:e.agentName,...a})??r.hooks,s={attemptId:e.callId,attemptIndex:0,channelAudience:a.audience,functionId:e.agentName,rootSessionId:e.sessionId,sessionId:e.sessionId,stepIndex:0,traceSessionId:e.sessionId,turnId:e.callId},c=toolCallEvents(o,s,e),l=r.otelSettings;if(l===void 0)return await n(c.observer(void 0));let u=resolveTracePolicy(l.tracePolicy,{agentName:e.agentName,...a},e=>log.warn(`tracePolicy threw; dropping the tool call's trace`,{error:formatError(e)}));if(u.action===`drop`)return await i.suppressed(()=>n(c.observer(void 0)));let d=applyLiveDeliveryAudienceCeiling({...u,recordInputs:l.recordInputs&&u.recordInputs,recordOutputs:l.recordOutputs&&u.recordOutputs},a.audience,void 0,a.environment),f=d.action===`record`&&d.recordInputs,p=d.action===`record`&&d.recordOutputs,m=`execute_tool ${e.toolName}`,h=withOperationTraceContext(withChannelAudience(t,a.audience),s),g={"agent.tool.is_framework":!1,"gen_ai.agent.name":e.agentName,"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":e.callId,"gen_ai.tool.name":e.toolName,"gen_ai.tool.type":`function`,[DIRECT_TOOL_CALL_ATTRIBUTE]:DIRECT_TOOL_CALL_VALUE,"operation.name":`execute_tool`,"resource.name":m,"agent.run.id":e.sessionId,"agent.trace.schema.version":4,"gen_ai.conversation.id":operationConversationId({sessionId:e.sessionId})};process.env.VERCEL_ENV!==void 0&&(g[`vercel.session_id`]=e.sessionId),e.origin!==void 0&&(g[`eve.channel.kind`]=a.channel.kind,g[`eve.channel.name`]=e.origin.channelName);let _=i.startSpan({type:`tool`,operationId:e.callId,name:m,kind:`INTERNAL`,attributes:g},{context:h}),v={emit:!0,recordInputs:f,recordOutputs:p},y=markAgentTraceContext(withErrorContent(h,p)),b=mcpLifecycle({serializer:MCP_SERIALIZER,...v,write:e=>setDefined(_,e),error:(e,t)=>_.fail(p?e:void 0,t)}),x,S=c.observer({failedWith:e=>{x={error:e}},recordInputs:f,span:_});try{let e=await i.run({type:`tool`,reference:_.reference,capture:v,mcp:b},()=>n(S),y);if(_.setAttribute(`eve.tool.outcome`,e.status),e.status===`completed`&&p){let t=contentAttribute(e.output);t!==void 0&&_.setAttribute(`gen_ai.tool.call.result`,t)}return e.status===`invalid-input`?_.fail(void 0,e.status):e.status===`failed`&&_.fail(p?x?.error:void 0,x===void 0?e.status:void 0),e}catch(e){throw _.fail(p?e:void 0),e}finally{_.end(),await r.forceFlush().catch(e=>{log.warn(`flushing a tool call's trace failed`,{error:formatError(e)})})}}const silentObserver={executed:async()=>{},executing:async()=>{},failedWith:()=>{}};function toolCallEvents(e,t,n){let r=e.capturesInputs??e.capturesContent,i=e.capturesOutputs??e.capturesContent,a=toolCallIdempotencyKey(t,n.callId,0);return{observer(o){return{async executing(i){if(o?.recordInputs){let e=contentAttribute(i);e!==void 0&&o.span.setAttribute(`gen_ai.tool.call.arguments`,e)}await e.publish(Object.freeze({callId:n.callId,idempotencyKey:a,input:r?i:void 0,scope:t,toolName:n.toolName,type:`tool.call.started`}))},async executed(n){o?.span.setAttribute(`gen_ai.execute_tool.duration`,n.durationMs/1e3);let r=n.type===`result`?i?{output:n.output,type:`result`}:{type:`result`}:i?{error:n.error,type:`error`}:{type:`error`};await e.publish(Object.freeze({durationMs:n.durationMs,idempotencyKey:a,output:Object.freeze(r),scope:t,type:`tool.call.completed`,outcome:n.type===`result`?`completed`:`failed`}))},failedWith(e){o?.failedWith(e)}}}}}function setDefined(e,t){for(let[n,r]of Object.entries(t))r!==void 0&&e.setAttribute(n,r)}export{withInvokeToolSpan};

package/dist/src/tracing/eve/operation-input.d.ts

@@ -1,10 +1,5 @@
 import type { AgentTraceStateStore } from "#tracing/eve/agent-trace-state.js";
 import { type AgentTelemetry, type AgentRun } from "#compiled/@vercel/agent-runs/index.js";
-export declare function traceSessionIdOf(scope: {
-    readonly traceSessionId?: string;
-    readonly rootSessionId?: string;
-    readonly sessionId: string;
-}): string;
 export declare function checkpointContent(value: string | undefined): unknown;
 /** Identity of one eve turn within the shared tracing library. */
 export declare function eveTurnIdentity(input: {

package/dist/src/tracing/eve/operation-input.js

@@ -1 +1 @@
-import{resolveConversationId}from"#shared/conversation-identity.js";import{createAgentRun}from"#compiled/@vercel/agent-runs/index.js";function traceSessionIdOf(e){return e.traceSessionId??e.rootSessionId??e.sessionId}function checkpointContent(e){if(e!==void 0)try{return JSON.parse(e)}catch{return}}function eveTurnIdentity(e){return{conversationId:resolveConversationId(e.rootSessionId??e.sessionId),runId:e.sessionId,turnId:e.turnId}}function createEveTracing(e){return createAgentRun({telemetry:e.telemetry,checkpointer:{get:t=>e.stateStore.get(`checkpoint`,t),set:(t,n)=>e.stateStore.set(`checkpoint`,t,n),delete:t=>e.stateStore.delete(`checkpoint`,t)}})}export{checkpointContent,createEveTracing,eveTurnIdentity,traceSessionIdOf};
+import{resolveConversationId}from"#shared/conversation-identity.js";import{createAgentRun}from"#compiled/@vercel/agent-runs/index.js";function checkpointContent(e){if(e!==void 0)try{return JSON.parse(e)}catch{return}}function eveTurnIdentity(e){return{conversationId:resolveConversationId(e.rootSessionId??e.sessionId),runId:e.sessionId,turnId:e.turnId}}function createEveTracing(e){return createAgentRun({telemetry:e.telemetry,checkpointer:{get:t=>e.stateStore.get(`checkpoint`,t),set:(t,n)=>e.stateStore.set(`checkpoint`,t,n),delete:t=>e.stateStore.delete(`checkpoint`,t)}})}export{checkpointContent,createEveTracing,eveTurnIdentity};

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

@@ -1 +1 @@
-import{createRequire}from"node:module";import{conversationIdFromContext}from"#tracing/eve/conversation-context.js";import{SpanKind,context,metrics,propagation,trace}from"#compiled/@opentelemetry/api/index.js";import{invocationName}from"#compiled/@vercel/agent-runs/otel.js";import{AgentSpanIdGenerator}from"#compiled/@vercel/agent-runs/index.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=conversationIdFromContext(t);n!==void 0&&e.attributes?.[`gen_ai.conversation.id`]===void 0&&e.setAttribute(`gen_ai.conversation.id`,n);let r=spanIdentity(e);r!==void 0&&addBounded(this.startedSpans,r);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 t=e.otel,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{provider:trace.getTracerProvider(),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}const registerOtel=registerOtelPipeline;function samplerAdmitsTrace(e,t,n={name:invocationName(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 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`}function captureOptionalPeerTracerProxy(){try{let e=require("@opentelemetry/api"),t=e.trace.getTracerProvider();return t instanceof e.ProxyTracerProvider?t:void 0}catch{return}}export{registerOtel,registerOtelPipeline};
+import{createRequire}from"node:module";import{conversationIdFromContext,traceSessionIdFromContext}from"#tracing/eve/conversation-context.js";import{SpanKind,context,metrics,propagation,trace}from"#compiled/@opentelemetry/api/index.js";import{invocationName}from"#compiled/@vercel/agent-runs/otel.js";import{AgentSpanIdGenerator}from"#compiled/@vercel/agent-runs/index.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=e,r=conversationIdFromContext(t);r!==void 0&&n.attributes?.[`gen_ai.conversation.id`]===void 0&&n.setAttribute(`gen_ai.conversation.id`,r);let i=traceSessionIdFromContext(t);process.env.VERCEL_ENV!==void 0&&i!==void 0&&n.attributes?.[`vercel.session_id`]===void 0&&n.setAttribute(`vercel.session_id`,i);let a=spanIdentity(e);a!==void 0&&addBounded(this.startedSpans,a);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 t=e.otel,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{provider:trace.getTracerProvider(),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}const registerOtel=registerOtelPipeline;function samplerAdmitsTrace(e,t,n={name:invocationName(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 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`}function captureOptionalPeerTracerProxy(){try{let e=require("@opentelemetry/api"),t=e.trace.getTracerProvider();return t instanceof e.ProxyTracerProvider?t:void 0}catch{return}}export{registerOtel,registerOtelPipeline};

package/dist/src/tracing/eve/session.d.ts

@@ -1,9 +1,10 @@
+import type { Context } from "#compiled/@opentelemetry/api/index.js";
 import { type InstrumentationSessionStartedEvent, type InstrumentationTraceSeed, type InstrumentationTurnStartedEvent, type InstrumentationTurnTerminalEvent, type InstrumentationSessionTransitionEvent } from "#instrumentation/lifecycle.js";
 import type { TraceCapturePolicy } from "#tracing/eve/otel-declaration.js";
 import type { AgentSessionTraceState, AgentTraceStateStore } from "#tracing/eve/agent-trace-state.js";
 import type { createEveCapturePolicy } from "#tracing/eve/policy.js";
 import type { ConversationEnvironment } from "#shared/conversation-context.js";
-import type { AgentSpanIdGenerator, AgentRun, ExecutionContext, TurnOperation } from "#compiled/@vercel/agent-runs/index.js";
+import type { AgentSpanIdGenerator, AgentRun, TurnOperation } from "#compiled/@vercel/agent-runs/index.js";
 interface EveSessionTracingInput {
     readonly tracing: AgentRun;
     readonly idGenerator: AgentSpanIdGenerator;
@@ -19,7 +20,7 @@ interface EveSessionTracing {
     readonly prepareSessionTrace: (event: InstrumentationSessionStartedEvent) => Promise<InstrumentationTraceSeed>;
     readonly prepareTurnTrace: (event: InstrumentationTurnStartedEvent) => Promise<InstrumentationTraceSeed>;
     /** Hydrates a turn this process or an earlier one started. */
-    turnFor(sessionId: string, turnId: string, context?: ExecutionContext): Promise<TurnOperation | undefined>;
+    turnFor(sessionId: string, turnId: string, context?: Context): Promise<TurnOperation | undefined>;
     /** Whether the trace policy dropped this turn, so its work must not record spans. */
     dropped(sessionId: string, turnId: string): Promise<boolean>;
     turnTerminal(event: InstrumentationTurnTerminalEvent): Promise<void>;

package/dist/src/tracing/eve/session.js

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{normalizeInstrumentationChannelKind}from"#internal/instrumentation.js";import{withOperationConversation}from"#tracing/eve/conversation-context.js";import{isSampledTrace,resolveTracePolicy,resolveTracePolicyDecision}from"#shared/trace-policy.js";import{ROOT_CONTEXT}from"#compiled/@opentelemetry/api/index.js";import"#instrumentation/lifecycle.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{applyPrincipalTraceDecision}from"#instrumentation/principal-summary.js";import{withChannelAudience}from"#tracing/eve/channel-audience-context.js";import{eveTurnIdentity,traceSessionIdOf}from"#tracing/eve/operation-input.js";import{eveActivationMetadata}from"#tracing/eve/metadata.js";function createEveSessionTracing(e){let ensureSessionContext=async t=>{let n=await e.stateStore.get(`session`,t.sessionId);if(n===void 0){let r=normalizeChannelAudience(t.channelAudience),i=resolveSessionTraceDecision(t,r,e.environment,e.tracePolicy);n={agentName:t.agentName,channelAudience:r,channelKind:t.channelKind,channelType:t.channelType,decision:i,context:initialSessionContext(e,t,i),parentLineage:t.parentLineage,rootSessionId:t.rootSessionId,traceSessionId:traceSessionIdOf(t),scheduleId:t.scheduleId,title:t.title},await e.stateStore.set(`session`,t.sessionId,n)}return n},prepareSessionTrace=async e=>{let t=await ensureSessionContext(e);return portableSpanContext(t.context,t.decision)},turnKey=(e,t)=>JSON.stringify([e,t]);async function turnFor(t,n,r){let i=await e.stateStore.get(`turn`,turnKey(t,n));if(i===void 0||!isSampledTrace(i.context))return;let a=await e.stateStore.get(`session`,t);return e.tracing.resume({identity:eveTurnIdentity({sessionId:t,rootSessionId:i.rootSessionId,turnId:n}),context:r??hostContext(a?.channelAudience,{sessionId:t,...i})})}async function dropped(t,n){let r=await e.stateStore.get(`turn`,turnKey(t,n));return r!==void 0&&!isSampledTrace(r.context)}let prepareTurnTrace=async t=>{let n=await e.stateStore.get(`turn`,turnKey(t.sessionId,t.turnId));if(n!==void 0){let r=await e.stateStore.get(`session`,t.sessionId);return portableSpanContext(n.context,r?.decision)}let r=await ensureSessionContext(t),i=t.sequence===0,a=i?t.parentTraceContext:void 0,o=r.decision?.action===`record`,s=a!==void 0&&!(`isRemote`in a&&a.isRemote===!0),c=i?{...r.context,traceId:s?a.traceId:r.context.traceId,isRemote:!1}:{traceId:e.idGenerator.deriveTraceId(`turn:${t.idempotencyKey}`),spanId:e.idGenerator.deriveSpanId(`turn:${t.idempotencyKey}`),traceFlags:+!!o,isRemote:!1},l=r.agentName??(t.parentLineage??r.parentLineage)?.subagentName,u={agentName:l,caller:a===void 0?void 0:adoptedSpanContext(a),context:c,currentPrincipal:applyPrincipalTraceDecision(t.currentPrincipal,r.decision),initiatorPrincipal:applyPrincipalTraceDecision(t.initiatorPrincipal,r.decision),parentLineage:t.parentLineage??r.parentLineage,rootSessionId:t.rootSessionId,traceSessionId:traceSessionIdOf(t),sequence:t.sequence,startTimeMs:Date.now(),subagentName:(t.parentLineage??r.parentLineage)?.subagentName};if(isSampledTrace(c)){let n=await e.tracing.turn({...eveActivationMetadata({session:r,turn:u,sessionId:t.sessionId}),agentName:l,identity:eveTurnIdentity({...t,sessionId:t.sessionId}),framework:{name:`eve`,version:e.frameworkVersion},capture:{emit:!0,...await e.capturePolicy.forOperation(t)},reference:c,parent:s?adoptedSpanContext(a):void 0,links:activationLinks(u),startTimeMs:u.startTimeMs,context:hostContext(r.channelAudience,t)});u={...u,context:{...c,traceFlags:n.reference.traceFlags}}}return await e.stateStore.set(`turn`,turnKey(t.sessionId,t.turnId),u),portableSpanContext(u.context,r.decision)};async function recordTerminal(t,n,r,i){await e.stateStore.update(`turn`,turnKey(t,n),e=>({...e,terminal:r.outcome===`failed`?{outcome:`failed`,errorName:i instanceof Error?i.name:void 0,errorMessage:i instanceof Error?i.message:void 0}:r}))}return{ensureSessionContext,prepareSessionTrace,prepareTurnTrace,turnFor,dropped,async turnTerminal(e){await recordTerminal(e.sessionId,e.turnId,{outcome:e.type===`turn.failed`?`failed`:e.type===`turn.cancelled`?`cancelled`:`completed`},e.type===`turn.failed`?e.error:void 0)},async sessionTransition(t){if(t.turnId===void 0)return;t.type===`session.failed`&&await recordTerminal(t.sessionId,t.turnId,{outcome:`failed`},t.error);let n=await e.stateStore.get(`turn`,turnKey(t.sessionId,t.turnId));if(n===void 0)return;let r=await e.stateStore.get(`session`,t.sessionId),i=await turnFor(t.sessionId,t.turnId);if(i!==void 0){let e=eveActivationMetadata({session:r,turn:n,sessionId:t.sessionId});i.attributes(e.attributes??{}),i.links(activationLinks(n)??[]);let a=n.terminal;if(a===void 0)await i.complete({outcomeUnknown:!0});else if(a.outcome===`failed`){let e=Error(a.errorMessage);e.name=a.errorName??`Error`,await i.complete({outcome:`failed`,failed:!0,error:e,errorType:a.errorName})}else await i.complete({outcome:a.outcome})}await e.stateStore.delete(`turn`,turnKey(t.sessionId,t.turnId))}}}function hostContext(e,t){return withOperationConversation(withChannelAudience(ROOT_CONTEXT,e),t)}function activationLinks(e){let t=[];return e.caller?.isRemote===!0&&t.push({context:e.caller,relationship:`agent.dispatch`}),e.channelDelivery?.requestTraceContext!==void 0&&t.push({context:e.channelDelivery.requestTraceContext,relationship:`channel.request`}),t.length===0?void 0:t}function portableSpanContext(e,t){return{decision:t,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function adoptedSpanContext(e){return{isRemote:`isRemote`in e&&e.isRemote===!0,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function initialSessionContext(e,t,n){let r=t.traceSeed;if(r!==void 0)return{...adoptedSpanContext(r),traceFlags:n.action===`drop`?0:r.traceFlags};let i=`session:${t.sessionId}`,a=t.parentTraceContext;return{traceId:a!==void 0&&!(`isRemote`in a&&a.isRemote===!0)?a.traceId:e.idGenerator.deriveTraceId(i),spanId:e.idGenerator.deriveSpanId(i),traceFlags:+(n.action===`record`)}}function resolveSessionTraceDecision(e,t,n,r){let i={audience:t,environment:n};return e.parentTraceContext!==void 0&&!isSampledTrace(e.parentTraceContext)?{action:`drop`}:e.traceSeed?.decision===void 0?e.traceSeed===void 0?e.parentTraceContext===void 0?e.agentName===void 0?r===void 0?resolveTracePolicyDecision(!0,i):{action:`drop`}:resolveTracePolicy(r,{agentName:e.agentName,audience:t,channel:{kind:normalizeInstrumentationChannelKind(e.channelKind??e.channelType)},environment:n,principalType:`unknown`}):resolveTracePolicyDecision(isSampledTrace(e.parentTraceContext),i):resolveTracePolicyDecision(isSampledTrace(e.traceSeed),i):readInstrumentationDecision(e.traceSeed.decision)??{action:`drop`}}export{createEveSessionTracing};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{normalizeInstrumentationChannelKind}from"#internal/instrumentation.js";import{traceSessionIdOf,withOperationTraceContext}from"#tracing/eve/conversation-context.js";import{isSampledTrace,resolveTracePolicy,resolveTracePolicyDecision}from"#shared/trace-policy.js";import{ROOT_CONTEXT}from"#compiled/@opentelemetry/api/index.js";import"#instrumentation/lifecycle.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{applyPrincipalTraceDecision}from"#instrumentation/principal-summary.js";import{withChannelAudience}from"#tracing/eve/channel-audience-context.js";import{eveTurnIdentity}from"#tracing/eve/operation-input.js";import{eveActivationMetadata}from"#tracing/eve/metadata.js";function createEveSessionTracing(e){let ensureSessionContext=async t=>{let n=await e.stateStore.get(`session`,t.sessionId);if(n===void 0){let r=normalizeChannelAudience(t.channelAudience),i=resolveSessionTraceDecision(t,r,e.environment,e.tracePolicy);n={agentName:t.agentName,channelAudience:r,channelKind:t.channelKind,channelType:t.channelType,decision:i,context:initialSessionContext(e,t,i),parentLineage:t.parentLineage,rootSessionId:t.rootSessionId,traceSessionId:traceSessionIdOf(t),scheduleId:t.scheduleId,title:t.title},await e.stateStore.set(`session`,t.sessionId,n)}return n},prepareSessionTrace=async e=>{let t=await ensureSessionContext(e);return portableSpanContext(t.context,t.decision)},turnKey=(e,t)=>JSON.stringify([e,t]);async function turnFor(t,n,r){let i=await e.stateStore.get(`turn`,turnKey(t,n));if(i===void 0||!isSampledTrace(i.context))return;let a=await e.stateStore.get(`session`,t);return e.tracing.resume({identity:eveTurnIdentity({sessionId:t,rootSessionId:i.rootSessionId,turnId:n}),context:withOperationTraceContext(r??withChannelAudience(ROOT_CONTEXT,a?.channelAudience),{sessionId:t,...i})})}async function dropped(t,n){let r=await e.stateStore.get(`turn`,turnKey(t,n));return r!==void 0&&!isSampledTrace(r.context)}let prepareTurnTrace=async t=>{let n=await e.stateStore.get(`turn`,turnKey(t.sessionId,t.turnId));if(n!==void 0){let r=await e.stateStore.get(`session`,t.sessionId);return portableSpanContext(n.context,r?.decision)}let r=await ensureSessionContext(t),i=t.sequence===0,a=i?t.parentTraceContext:void 0,o=r.decision?.action===`record`,s=a!==void 0&&!(`isRemote`in a&&a.isRemote===!0),c=i?{...r.context,traceId:s?a.traceId:r.context.traceId,isRemote:!1}:{traceId:e.idGenerator.deriveTraceId(`turn:${t.idempotencyKey}`),spanId:e.idGenerator.deriveSpanId(`turn:${t.idempotencyKey}`),traceFlags:+!!o,isRemote:!1},l=r.agentName??(t.parentLineage??r.parentLineage)?.subagentName,u={agentName:l,caller:a===void 0?void 0:adoptedSpanContext(a),context:c,currentPrincipal:applyPrincipalTraceDecision(t.currentPrincipal,r.decision),initiatorPrincipal:applyPrincipalTraceDecision(t.initiatorPrincipal,r.decision),parentLineage:t.parentLineage??r.parentLineage,rootSessionId:t.rootSessionId,traceSessionId:traceSessionIdOf(t),sequence:t.sequence,startTimeMs:Date.now(),subagentName:(t.parentLineage??r.parentLineage)?.subagentName};if(isSampledTrace(c)){let n=await e.tracing.turn({...eveActivationMetadata({session:r,turn:u,sessionId:t.sessionId}),agentName:l,identity:eveTurnIdentity({...t,sessionId:t.sessionId}),framework:{name:`eve`,version:e.frameworkVersion},capture:{emit:!0,...await e.capturePolicy.forOperation(t)},reference:c,parent:s?adoptedSpanContext(a):void 0,links:activationLinks(u),startTimeMs:u.startTimeMs,context:hostContext(r.channelAudience,t)});u={...u,context:{...c,traceFlags:n.reference.traceFlags}}}return await e.stateStore.set(`turn`,turnKey(t.sessionId,t.turnId),u),portableSpanContext(u.context,r.decision)};async function recordTerminal(t,n,r,i){await e.stateStore.update(`turn`,turnKey(t,n),e=>({...e,terminal:r.outcome===`failed`?{outcome:`failed`,errorName:i instanceof Error?i.name:void 0,errorMessage:i instanceof Error?i.message:void 0}:r}))}return{ensureSessionContext,prepareSessionTrace,prepareTurnTrace,turnFor,dropped,async turnTerminal(e){await recordTerminal(e.sessionId,e.turnId,{outcome:e.type===`turn.failed`?`failed`:e.type===`turn.cancelled`?`cancelled`:`completed`},e.type===`turn.failed`?e.error:void 0)},async sessionTransition(t){if(t.turnId===void 0)return;t.type===`session.failed`&&await recordTerminal(t.sessionId,t.turnId,{outcome:`failed`},t.error);let n=await e.stateStore.get(`turn`,turnKey(t.sessionId,t.turnId));if(n===void 0)return;let r=await e.stateStore.get(`session`,t.sessionId),i=await turnFor(t.sessionId,t.turnId);if(i!==void 0){let e=eveActivationMetadata({session:r,turn:n,sessionId:t.sessionId});i.attributes(e.attributes??{}),i.links(activationLinks(n)??[]);let a=n.terminal;if(a===void 0)await i.complete({outcomeUnknown:!0});else if(a.outcome===`failed`){let e=Error(a.errorMessage);e.name=a.errorName??`Error`,await i.complete({outcome:`failed`,failed:!0,error:e,errorType:a.errorName})}else await i.complete({outcome:a.outcome})}await e.stateStore.delete(`turn`,turnKey(t.sessionId,t.turnId))}}}function hostContext(e,t){return withOperationTraceContext(withChannelAudience(ROOT_CONTEXT,e),t)}function activationLinks(e){let t=[];return e.caller?.isRemote===!0&&t.push({context:e.caller,relationship:`agent.dispatch`}),e.channelDelivery?.requestTraceContext!==void 0&&t.push({context:e.channelDelivery.requestTraceContext,relationship:`channel.request`}),t.length===0?void 0:t}function portableSpanContext(e,t){return{decision:t,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function adoptedSpanContext(e){return{isRemote:`isRemote`in e&&e.isRemote===!0,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function initialSessionContext(e,t,n){let r=t.traceSeed;if(r!==void 0)return{...adoptedSpanContext(r),traceFlags:n.action===`drop`?0:r.traceFlags};let i=`session:${t.sessionId}`,a=t.parentTraceContext;return{traceId:a!==void 0&&!(`isRemote`in a&&a.isRemote===!0)?a.traceId:e.idGenerator.deriveTraceId(i),spanId:e.idGenerator.deriveSpanId(i),traceFlags:+(n.action===`record`)}}function resolveSessionTraceDecision(e,t,n,r){let i={audience:t,environment:n};return e.parentTraceContext!==void 0&&!isSampledTrace(e.parentTraceContext)?{action:`drop`}:e.traceSeed?.decision===void 0?e.traceSeed===void 0?e.parentTraceContext===void 0?e.agentName===void 0?r===void 0?resolveTracePolicyDecision(!0,i):{action:`drop`}:resolveTracePolicy(r,{agentName:e.agentName,audience:t,channel:{kind:normalizeInstrumentationChannelKind(e.channelKind??e.channelType)},environment:n,principalType:`unknown`}):resolveTracePolicyDecision(isSampledTrace(e.parentTraceContext),i):resolveTracePolicyDecision(isSampledTrace(e.traceSeed),i):readInstrumentationDecision(e.traceSeed.decision)??{action:`drop`}}export{createEveSessionTracing};

package/dist/src/vue/index.js

@@ -1,4 +1,4 @@
-import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-Bp6nbhfV.js";
+import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DTu78IAF.js";
 
 //#region src/client/tool-call-state.ts
 function toolCallState(conversation, callId, options = {}) {

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

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

package/docs/agent-config.md

@@ -3,7 +3,7 @@ title: "Agent Configuration"
 description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
 ---
 
-An eve app has one root agent assembled from the files under `agent/`. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
+An eve app's root agent uses files under `agent/` by default; a [flat layout](./reference/agent-files#flat-layout) places them directly in the app root instead. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
 
 ## Set the model
 
@@ -137,7 +137,7 @@ export default defineAgent({
   starting points on Ollama.
 - **Usage.** `includeUsage: true` lets token usage reach eve's
   [session limits](#runtime-limits). Local models report no cost, so
-  `maxTokenCostUsdPerSession` does not apply.
+  `costUsd` stays unset in a `sessionUsage` check.
 - **Other servers.** Change `baseURL`, for example to
   `http://localhost:1234/v1` for LM Studio. Pass `apiKey` for a remote
   OpenAI-compatible server that requires one.
@@ -262,45 +262,88 @@ See [Default harness](./concepts/default-harness#compaction) for how the loop ap
 
 ## Runtime limits
 
-Use `limits` for framework-owned runtime caps. Session usage limits stop the
-current durable session from starting another model call after accumulated
-provider-reported tokens or model token cost reaches a configured limit:
+Use `limits` for framework-owned runtime caps. `sessionUsage` decides when the
+current durable session must stop starting model calls. It receives the
+session's usage and returns `true` when the limit is reached:
 
 ```ts title="agent/agent.ts"
 export default defineAgent({
   model: "anthropic/claude-opus-5.5",
   limits: {
-    maxInputTokensPerSession: 200_000,
-    maxOutputTokensPerSession: 20_000,
-    maxTokenCostUsdPerSession: 1.5,
+    sessionUsage: ({ window }) =>
+      window.inputTokens - window.cacheReadTokens >= 200_000 ||
+      window.outputTokens >= 20_000 ||
+      (window.costUsd ?? 0) >= 1.5,
     sessionTimeoutMs: 7 * 24 * 60 * 60 * 1_000,
   },
 });
 ```
 
-`sessionTimeoutMs` sets the lifetime for every session, including delegated
-sessions. It defaults to 30 days and starts at creation. Each successful
-deployment handoff or legacy-session import restarts the original configured
-duration. Process restarts, ordinary messages, compaction handoffs, and failed
-or skipped handoffs keep the existing deadline. At the deadline, eve lets an active turn settle,
-then emits `session.completed` and releases every continuation address; the next
-qualifying channel message starts fresh. Set it to `false` to disable the
-timeout. Session expiration follows [run-data retention](#run-data-retention);
-a zero-retention session loses its stored payloads when it ends.
-
-Input tokens, output tokens, and model token cost are checked independently.
-The model call that crosses a limit is allowed to finish because exact usage
-arrives after the call completes. Before the next model call, eve pauses the
-turn (`turn.waiting`) and sends a deterministic continuation prompt with two options:
-**Continue** grants a fresh window of each configured size and resumes the same
-turn, and **Stop**
-cancels the in-flight turn through the standard cancellation path
-(`turn.cancelled` → `session.waiting`) — a user decision, not an error. The session stays resumable; because it is
-still over budget after Stop, the next message raises a new prompt. Declining a
+`sessionTimeoutMs` sets how long a session may sit idle before eve completes it,
+for every session, including delegated sessions. It defaults to 30 days. The
+idle window starts at creation and restarts each time a turn settles, including
+turns that answer a message, clear or compact the context, or end in
+cancellation. A session never expires while a turn is open, including a turn
+held open while its [tasks](./tools/tasks) work or while it waits for a person
+to answer; the window restarts when that turn settles. Process restarts do not
+change the window. When the window elapses, eve emits `session.completed` and
+releases every continuation address; the next qualifying channel message starts
+fresh. To carry an earlier conversation into the fresh session, pass it as
+[prior history](./channels/eve#start-from-prior-history). Set it to `false` to
+disable the timeout. Session expiration follows
+[run-data retention](#run-data-retention); a zero-retention session loses its
+stored payloads when it ends.
+
+`sessionUsage` gets two usage records with `inputTokens`, `outputTokens`,
+`cacheReadTokens`, `cacheWriteTokens`, and `costUsd`: `total` is everything
+the session has spent, and `window` is what it spent since the last approved
+continuation. `inputTokens` includes cache reads and writes. Subtract
+`cacheReadTokens` to count only new input; cache reads are the history a
+provider replays from its prompt cache on every step. `costUsd` is the model
+token cost in US dollars that AI Gateway reports with each step, not tool or
+infrastructure spend; it is unset when no step reported a cost.
+
+When `sessionUsage` is omitted, the limit is `40_000_000` new input tokens per
+window:
+
+```ts
+({ window }) => window.inputTokens - window.cacheReadTokens >= 40_000_000;
+```
+
+`sessionUsage` can raise its threshold after each approval. This limit asks
+at 20,000 new input tokens, then at 40,000, 80,000, and so on:
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
+  limits: {
+    sessionUsage: ({ total, window }) => {
+      const used = total.inputTokens - total.cacheReadTokens;
+      // Usage when the last continuation was approved; 0 before the first.
+      const approvedAt = used - (window.inputTokens - window.cacheReadTokens);
+      // Double past it, so each approval allows twice the usage before the next prompt.
+      let next = 20_000;
+      while (next <= approvedAt) next *= 2;
+      return used >= next;
+    },
+  },
+});
+```
+
+Set `sessionUsage: () => false` to leave sessions uncapped; `sessionUsage:
+false` is not accepted. eve calls `sessionUsage` before each model call once
+the window has usage. The model call that crosses a limit is allowed to finish
+because exact usage arrives after the call completes. Before the next model
+call, eve pauses the turn (`turn.waiting`) and sends a deterministic
+continuation prompt with two options: **Continue** starts a new window and
+resumes the same turn, and **Stop** cancels the in-flight turn through the
+standard cancellation path (`turn.cancelled` → `session.waiting`). Stop is a
+user decision, not an error. The session stays resumable; because it is still
+over budget after Stop, the next message raises a new prompt. Declining a
 delegated child's prompt cancels the root turn, which cascades to the whole
-delegation tree — the delegating parent never receives an error result it
-could retry against a fresh quota share. A reply that answers neither option
-is queued while the existing prompt stays pending; eve does not raise another
+delegation tree, so the delegating parent never receives an error result it
+could retry. A reply that answers neither option is queued while the existing
+prompt stays pending; eve does not raise another
 copy or start another turn. The reply is received (`message.received`) and
 processed in the held turn once the budget is granted.
 
@@ -312,44 +355,22 @@ turn or duplicate the prompt.
 
 Sessions that cannot request input from a human, such as markdown schedules and
 delegated runs without input proxying, skip the prompt and fail the next model
-call with `SESSION_TOKEN_LIMIT_REACHED` for token budgets or
-`SESSION_TOKEN_COST_LIMIT_REACHED` for model token cost. A delegated task with
-no inherited quota also fails instead of raising a continuation prompt that
-could only grant another zero-value window.
-
-When `maxInputTokensPerSession` is omitted, root sessions apply a default
-input budget of `40_000_000` provider-reported input tokens.
-`maxOutputTokensPerSession` and `maxTokenCostUsdPerSession` are unset by
-default. `maxTokenCostUsdPerSession` is a US-dollar limit on model token cost,
-not tool or infrastructure spend. It uses the cost reported with each model
-step; AI Gateway supplies this value, while model steps without reported cost
-do not add to the limit. Set any usage limit to `false` to uncap that axis.
-
-Delegated subagent sessions have no fixed default. Each child receives a share
-of the delegating parent's remaining quota when it starts: the remainder in
-the current budget window split evenly across the agent tasks that one model
-step starts. A session that a workflow tool opens with `ctx.agent` receives
-the share of the model step that called the tool, or the whole remainder when
-that step starts no agent tasks; eve does not divide that share among several
-sessions one call opens. A child keeps its grant for its whole session,
-including turns that later calls with `taskId` start. Remote agent tasks count
-toward the split but receive no grant: they run under their own deployment's
-limits.
-
-A child's usage, including what the child's own subagents spent, counts
-against the parent's quota. An agent task's usage counts with each reply it
+call with `SESSION_USAGE_LIMIT_REACHED`. Its details carry the `total` and
+`window` usage the check saw.
+
+Each subagent session checks its own usage against its own `sessionUsage`, or
+the root agent's when it authors none. A dynamic subagent can't select
+`sessionUsage` at runtime and always uses the root agent's. Remote agents run
+under their own deployment's limits.
+
+A child's usage, including what the child's own subagents spent, also counts
+in the parent's usage. An agent task's usage counts with each reply it
 sends. A turn it doesn't reply to, such as one a cancel stopped, counts with
 the next reply, or when the turn ends if no call waits for a reply. Sessions
 that any other `serve` workflow tool opens with `ctx.agent` count the same
 way; those of an `execute` or `task` tool count when the tool finishes. Remote
-agents' reported usage counts the same way. Later children draw from what
-remains, and the parent's own limit and continuation prompt include delegated
-spend. Token-cost budgets follow the same rules, including splitting the
-remaining US-dollar budget and adding child cost back to the parent. Approving
-a continuation opens a fresh parent window for later child grants without
-erasing lifetime usage. An authored child limit applies only when it is
-tighter than the parent's grant; an uncapped parent delegates uncapped
-children.
+agents' reported usage counts the same way, cost included. Approving a
+continuation starts a new window without erasing `total`.
 
 Some delegated usage doesn't count against the parent: a `ctx.agent` turn
 still running when its workflow tool finishes or is cancelled; the `ctx.agent`
@@ -496,7 +517,7 @@ keeps the data. Confirm support with your World provider. See
 | -------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `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, and [`promptCache`](#prompt-caching) settings.                                                                                                                                                                                                                                |
-| `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.                                                                                                                                                          |
+| `limits`       | `AgentLimitsDefinition`               | field-specific   | Framework-owned runtime limits. Sessions complete after 30 idle 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.                                                                            |
 | `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.                                                                                                                             |
 | `tool`         | `boolean \| "deferred"`               | `true`           | Exposes this agent to its parent model as a tool. `"deferred"` keeps it out of the model's tool list; the model finds it with `eve__search` and calls it with `eve__tool`. On the root agent, controls the built-in `agent` tool. A subagent with `tool: false` remains callable from authored workflow tools through `ctx.agent()`. |

package/docs/channels/chat-sdk.mdx

@@ -53,6 +53,11 @@ export default channel;
 
 `adapters` is a map of adapter name to adapter instance; each entry mounts its own webhook (see below). `state` takes any Chat SDK state adapter: `createMemoryState()` is fine for local development, but use a durable adapter (Redis, Upstash, etc.) in production so thread subscriptions and inbound deduplication survive restarts. `send` accepts a plain string or an AI SDK `UserContent` array, and must be called from inside a Chat SDK handler — it dispatches the turn on the webhook that is currently running.
 
+Pass `idempotencyKey: message.id` to `send` to prevent duplicate agent input
+within the session's [recent-key window](./custom#retried-deliveries). Chat SDK's
+separate duplicate check can mark a message as seen before eve accepts it, so
+a shared state adapter alone does not guarantee delivery.
+
 Deploy once the channel file is in place:
 
 ```bash
@@ -104,7 +109,7 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, and `turnPolicy`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn. `auth` defaults to `null`.
+`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, `turnPolicy`, and `idempotencyKey`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn. `auth` defaults to `null`.
 
 To answer pending input requests from a handler you render yourself, call `respond(inputResponses, { thread, auth?, context? })`. Like a channel's `respond()`, it never creates a session. This example answers a custom button whose `value` carries the eve request id:
 

package/docs/channels/custom.mdx

@@ -104,11 +104,11 @@ part of the authored channel API.
 ## Channel operations and session handles
 
 Channel operations are dynamic: every call targets whichever session currently
-owns the address. Only `send()` can create a session when the address is unowned.
-Cold-start sends return their accepted candidate without waiting for address
-ownership. If simultaneous sends race, eve forwards the losing candidate's
-message to the winner; resolve the address after startup when you need a fixed
-handle to the canonical owner.
+owns the address. `create()` and `send()` can create a session when the address is unowned.
+Without an [idempotency key](#retried-deliveries), a new session's handle can
+return before it claims the address. If another send wins the address, eve
+forwards the message to that session. Call `resolveSession(address)` after
+startup to get the winning session's handle.
 
 ```ts
 const source = from(threadId);
@@ -206,6 +206,38 @@ Attaching does no lookup. The first operation reports whether the ID is active.
 Call `resolveSession(address)` only when you explicitly need to snapshot an
 address's current owner as a fixed handle.
 
+## Retried deliveries
+
+After verifying a webhook, pass its stable event ID as `idempotencyKey`. Reuse the key
+when retrying a failed or timed-out send:
+
+```ts
+const session = await from(conversationId).send(message, {
+  auth,
+  idempotencyKey: providerEventId,
+});
+```
+
+Channel and fixed-session `send()` and `respond()` calls accept this option,
+as does the Chat SDK bridge. Keys must contain 1–256 characters and identify one
+delivery. Prefix IDs with the provider or event type if they can overlap.
+Reusing a retained key ignores the new input, even if the message changed.
+
+Each session remembers its last 1,024 distinct keys. Retries do not extend
+retention and can run again after eviction. Aliases share this window; replay
+and owner handoffs preserve it. Other sessions have separate windows, including
+those created after reset, expiration, or replacement. Replicas must share the
+same durable Workflow World.
+
+A known duplicate does not interrupt generation, call `deliver`, or start a
+turn. A keyed send that creates a session waits up to 30 seconds for the winning
+session's handle. Sends to existing sessions return after eve stores the
+delivery, without waiting for a turn or reporting whether it was a duplicate.
+
+Await `send()` before acknowledging a webhook when the provider allows it.
+Acknowledging sooner can lose work. This does not make tool calls, outbound
+posts, or work done before `send()` exactly once.
+
 ## Wrap an existing channel's routes
 
 A channel value can be spread into a new object with replaced `routes`. eve keeps the channel's adapter, events, and build metadata (such as the Slack app manifest) on the spread copy, so `{ ...channel, routes }` compiles and runs like the original.
@@ -374,7 +406,7 @@ Before sending:
 
 - Verify the provider's signature and validate the payload, including size limits. Derive `event.source` from the verified sender, not an untrusted payload field.
 - Filter out events that should not reach the agent.
-- Deduplicate retried events in your application if duplicates would cause unwanted sessions or posts. `send(...)` does not deduplicate them.
+- Deduplicate retries in your application unless the destination's `receive` hook passes a [delivery key](#retried-deliveries) to `from(address).send()`.
 
 The supplied `auth` identifies who started the session, available to tools and event handlers as `session.auth.initiator`.
 

package/docs/channels/eve.mdx

@@ -368,6 +368,52 @@ export default eveChannel({
 - eve labels client-supplied entries `Client context:` for the model. Returned context is sent without the label.
 - `onMessage` runs only for requests with a message. An input response keeps the context its request sent.
 
+### Start from prior history
+
+Pass `history` to bring in conversation eve did not produce, such as a transcript your app stored, a conversation moving from another system, or a branch of an earlier exchange. The model sees each entry as a real user or assistant turn, not as a transcript inside one message.
+
+Create a session that starts from stored history and waits for its first message with `create()` on a channel address. No turn runs until a message arrives:
+
+```ts title="agent/channels/app.ts"
+import { defineChannel, POST } from "eve/channels";
+
+export default defineChannel({
+  routes: [
+    POST("/conversations/:id/session", async (req, { from, params }) => {
+      const auth = await authenticate(req);
+      // Load only conversations this caller may read.
+      const conversation = await db.conversations.findForUser(params.id!, auth);
+      const { created, session } = await from(`conversation:${conversation.id}`).create({
+        auth,
+        history: conversation.messages.map((message) => ({
+          id: message.id,
+          role: message.role, // "user" | "assistant"
+          text: message.body,
+        })),
+      });
+      if (!created) {
+        return Response.json({ error: "Conversation already has a session." }, { status: 409 });
+      }
+      return Response.json({ sessionId: session.id });
+    }),
+  ],
+});
+```
+
+The client then resumes that session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when a session already owned the address, or another `create()` or `send()` claimed it first. That session comes back unchanged and your `history` was not added, so check `created` before treating the session as seeded. Use a new address for each new conversation or branch.
+
+When the session at the address is [stranded](../concepts/execution-model-and-durability#stranded-sessions), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `reset()` on the address, then `create()` again.
+
+`create()` returns once the new session claims its address, so a `send()` right after it reaches that session. It throws if no session claims the address within 15 seconds.
+
+`send()` accepts the same `history` option. The entries are added right before that message and its `context`, whether the send creates the session or continues it. The eve channel's `onMessage` can return `history` the same way. It applies to every message it is returned for, so return it only when the message should carry those turns.
+
+Each entry has a `role` of `"user"` or `"assistant"`, non-empty `text`, and an optional `id` that is unique within the call. Invalid history throws an `InvalidSessionHistoryError`, exported from `eve/channels`, that names the entry and the rule it broke. eve doesn't cap how many entries or how much text one call carries. Your route decides how much stored conversation to load, so trim long conversations there, for example to the newest messages. Tool calls, files, and reasoning are not supported.
+
+eve never accepts `history` from a client request body. Resolve it on the server and authorize the caller against the stored conversation.
+
+The stream publishes added entries in `history.imported`, right before the `message.received` of the turn they join. Each event message has the same `role`, `text`, and `id` you passed. `transcriptReducer()` from `eve/client` includes them, so its `{ role, text }` messages can be passed straight back as `history` to branch a session. The default client reducer renders them ahead of that turn's message with `metadata.imported` set and your `id` in `metadata.historyId`, so you can rejoin your own annotations. Message ids stay unique even when a later call reuses an `id`. After that, the entries are ordinary history: compaction, `clear()`, and handoffs treat them like any other turn.
+
 ## Clients
 
 The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.