eve 0.81.0 → 0.82.0

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

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

package/dist/src/tools/provided/ask-question-workflow.js

@@ -1 +1 @@
-async function executeAskQuestionTool(e,t){"use workflow";return toAskQuestionOutput(await t.ask(toAskQuestionRequest(e)))}function toAskQuestionRequest(e){let t=e.options?.map(e=>({description:e.description,id:e.label,label:e.label}));return{allowFreeform:!0,display:t===void 0?`text`:`select`,prompt:e.question,...t!==void 0&&{options:t}}}function toAskQuestionOutput(e){switch(e.status){case`answered`:return{answer:e.optionId??e.text??``,status:`answered`};case`cancelled`:return{interrupted:!0};case`unavailable`:return{status:`unavailable`}}}executeAskQuestionTool.workflowId=`workflow//eve@0.81.0//executeAskQuestionTool`;export{executeAskQuestionTool,toAskQuestionOutput,toAskQuestionRequest};
+async function executeAskQuestionTool(e,t){"use workflow";return toAskQuestionOutput(await t.ask(toAskQuestionRequest(e)))}function toAskQuestionRequest(e){let t=e.options?.map(e=>({description:e.description,id:e.label,label:e.label}));return{allowFreeform:!0,display:t===void 0?`text`:`select`,prompt:e.question,...t!==void 0&&{options:t}}}function toAskQuestionOutput(e){switch(e.status){case`answered`:return{answer:e.optionId??e.text??``,status:`answered`};case`cancelled`:return{interrupted:!0};case`unavailable`:return{status:`unavailable`}}}executeAskQuestionTool.workflowId=`workflow//eve@0.82.0//executeAskQuestionTool`;export{executeAskQuestionTool,toAskQuestionOutput,toAskQuestionRequest};

package/dist/src/tools/provided/sleep-workflow.js

@@ -1 +1 @@
-import{sleep}from"#compiled/@workflow/core/index.js";async function executeSleepTool(e,t){"use workflow";if(t.abortSignal.aborted)return{interrupted:!0};let n=new Promise(e=>t.abortSignal.addEventListener(`abort`,()=>e(`interrupted`),{once:!0})),r=sleep(Math.ceil(e.seconds*1e3)).then(()=>`elapsed`);return await Promise.race([r,n])===`elapsed`?{waitedSeconds:e.seconds}:{interrupted:!0}}executeSleepTool.workflowId=`workflow//eve@0.81.0//executeSleepTool`;export{executeSleepTool};
+import{sleep}from"#compiled/@workflow/core/index.js";async function executeSleepTool(e,t){"use workflow";if(t.abortSignal.aborted)return{interrupted:!0};let n=new Promise(e=>t.abortSignal.addEventListener(`abort`,()=>e(`interrupted`),{once:!0})),r=sleep(Math.ceil(e.seconds*1e3)).then(()=>`elapsed`);return await Promise.race([r,n])===`elapsed`?{waitedSeconds:e.seconds}:{interrupted:!0}}executeSleepTool.workflowId=`workflow//eve@0.82.0//executeSleepTool`;export{executeSleepTool};

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/agent-otel-provider.js

@@ -1 +1 @@
-import{isObject}from"#shared/guards.js";import{isUserMessageKind}from"#harness/messages.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{isSampledTrace}from"#shared/trace-policy.js";import{ROOT_CONTEXT,context,trace}from"#compiled/@opentelemetry/api/index.js";import{gatewayCostAttributes,readGatewayCostData}from"#tracing/eve/gateway.js";import{createAgentToolInstrumentation}from"#tracing/eve/agent-tool-instrumentation.js";import{withChannelAudience}from"#tracing/eve/channel-audience-context.js";import{createEveTracing}from"#tracing/eve/operation-input.js";import{createAgentApprovalInstrumentation}from"#tracing/eve/agent-approval-instrumentation.js";import{createAgentChannelDeliveryInstrumentation}from"#tracing/eve/agent-channel-delivery-instrumentation.js";import{eveActivationMetadata}from"#tracing/eve/metadata.js";import{createAgentMemoryInstrumentation}from"#tracing/eve/agent-memory-instrumentation.js";import{createEveSessionTracing}from"#tracing/eve/session.js";import{createEveCapturePolicy}from"#tracing/eve/policy.js";function createAgentOtelInstrumentation(e){let t=e.environment??resolveInstrumentationEnvironment(),n=e.recordInputs??!1,r=e.recordOutputs??!1,i=createEveTracing(e),a=new Map,o=new Map,s=createEveSessionTracing({...e,environment:t,tracing:i}),{prepareSessionTrace:c,prepareTurnTrace:l}=s;async function attemptFor(e){let t=a.get(e.attemptId);if(t!==void 0)return t;let n=await s.turnFor(e.sessionId,e.turnId,withChannelAudience(ROOT_CONTEXT,e.channelAudience)),r={stepIndex:e.stepIndex,attempt:e.attemptIndex};return n?.findAttempt(r)??(n?.finished===!1?n.attempt(r):void 0)}let u=createAgentToolInstrumentation({tracing:i,attemptFor,stepFor:e=>a.get(e.attemptId),recordInputs:n,recordOutputs:r,stateStore:e.stateStore}),d=createAgentApprovalInstrumentation({tracing:i,actionStateFor:u.stateFor}),f=createAgentMemoryInstrumentation({...e,environment:t,tracing:i}),p=createEveCapturePolicy({stateStore:e.stateStore,environment:t,recordInputs:n,recordOutputs:r});function turnState(t){return e.stateStore.get(`turn`,JSON.stringify([t.sessionId,t.turnId]))}let onSessionStarted=async e=>{await c(e)},onTurnStarted=async e=>{await l(e)},onStepStarted=async t=>{let n=await turnState(t.scope);if(n===void 0||!isSampledTrace(n.context))return;let r=await e.stateStore.get(`session`,t.scope.sessionId),i=await s.turnFor(t.scope.sessionId,t.scope.turnId,withChannelAudience(ROOT_CONTEXT,t.scope.channelAudience));if(i===void 0||i.finished)return;let o=trace.getSpan(context.active())?.spanContext(),c=await i.attempt({stepIndex:t.scope.stepIndex,attempt:t.scope.attemptIndex,runtimeContext:t.runtimeContext,channel:eveActivationMetadata({session:r,turn:n,sessionId:t.scope.sessionId}).channel,links:o===void 0||o.traceId===n.context.traceId?void 0:[{relationship:`execution.delivery`,context:o}]});a.set(t.scope.attemptId,c)},onStepTerminal=async e=>{let t=e.type===`step.attempt.failed`?{error:e.error}:void 0;await drainOpenSpans(e),await u.drain(e.scope.attemptId,t);let n=a.get(e.scope.attemptId)??await attemptFor(e.scope);a.delete(e.scope.attemptId),t===void 0?await n?.complete():(await n?.fail(t.error),await u.forgetAttempt(e.scope))},onSessionTransition=async t=>{await s.sessionTransition(t),(t.type===`session.completed`||t.type===`session.failed`)&&(await u.deleteForSession(t.sessionId),await e.stateStore.delete(`session`,t.sessionId))},onModelCallStarted=async e=>{let t=a.get(e.scope.attemptId);if(t===void 0)return;let r=await t.modelCall({provider:e.model.provider,modelId:e.model.modelId,messages:n?e.input?.messages.map(e=>isObject(e)&&e.role===`user`?{...e,kind:isUserMessageKind(e.kind)?e.kind:void 0}:e):void 0,instructions:n?e.input?.instructions:void 0,tools:n?e.input?.tools:void 0,runtimeContext:e.runtimeContext},e.idempotencyKey),i=o.get(e.scope.attemptId);i===void 0&&o.set(e.scope.attemptId,i=new Map),i.set(e.idempotencyKey,r)},onModelCallTerminal=async e=>{let t=o.get(e.scope.attemptId),n=t?.get(e.idempotencyKey);t?.delete(e.idempotencyKey),n!==void 0&&(e.type===`model.call.failed`?await n.fail(e.error):await n.complete({outcome:`completed`,result:{...e,content:r?e.content:void 0}}))},m=createAgentChannelDeliveryInstrumentation({recordInputs:n,stateStore:e.stateStore}),onStepMetadata=e=>{let t=a.get(e.scope.attemptId);if(t===void 0)return;let n=readGatewayCostData(e.providerMetadata);n!==void 0&&t.attributes(gatewayCostAttributes(n))};return{hook:{events:{...m,...d,"step.attempt.completed":onStepTerminal,"step.attempt.failed":onStepTerminal,"step.attempt.metadata":onStepMetadata,"step.attempt.started":onStepStarted,"model.call.completed":onModelCallTerminal,"model.call.failed":onModelCallTerminal,"model.call.started":onModelCallStarted,"session.completed":onSessionTransition,"session.failed":onSessionTransition,"session.started":onSessionStarted,"session.waiting":onSessionTransition,...u.events,"turn.cancelled":s.turnTerminal,"turn.completed":s.turnTerminal,"turn.failed":s.turnTerminal,"turn.started":onTurnStarted},name:`eve.otel`,projectEvent:p.projectEvent,tracePolicy:()=>({emit:!0,recordInputs:n,recordOutputs:r})},prepareSessionTrace:c,prepareTurnTrace:l,async runInContext(t,n){if(t.type===`memory.operation`)return f.runInContext(t,n);let r={emit:!0,...await p.forOperation(t.scope)},inTurn=async()=>{let i=await s.turnFor(t.scope.sessionId,t.scope.turnId,withChannelAudience(ROOT_CONTEXT,t.scope.channelAudience));if(i!==void 0&&!i.finished)return i.run(n,r);let{sessionId:a,turnId:o}=t.scope;return e.telemetry.suppressed!==void 0&&await s.dropped(a,o)?e.telemetry.suppressed(n):n()};if(t.type===`tool.call`)return u.runInContext(t,n,r,inTurn);let i=o.get(t.scope.attemptId)?.get(t.idempotencyKey);return i!==void 0&&!i.finished?i.run(n,r):inTurn()}};async function drainOpenSpans(e){for(let t of o.get(e.scope.attemptId)?.values()??[])e.type===`step.attempt.failed`?await t.fail(e.error):await t.complete({outcome:`completed`,result:{finishReason:`unknown`,usage:{}}});o.delete(e.scope.attemptId)}}export{createAgentOtelInstrumentation};
+import{isObject}from"#shared/guards.js";import{isUserMessageKind}from"#harness/messages.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{isSampledTrace}from"#shared/trace-policy.js";import{ROOT_CONTEXT,context,trace}from"#compiled/@opentelemetry/api/index.js";import{gatewayCostAttributes,gatewayRoutingAttributes,readGatewayCostData}from"#tracing/eve/gateway.js";import{createAgentToolInstrumentation}from"#tracing/eve/agent-tool-instrumentation.js";import{withChannelAudience}from"#tracing/eve/channel-audience-context.js";import{createEveTracing}from"#tracing/eve/operation-input.js";import{createAgentApprovalInstrumentation}from"#tracing/eve/agent-approval-instrumentation.js";import{createAgentChannelDeliveryInstrumentation}from"#tracing/eve/agent-channel-delivery-instrumentation.js";import{eveActivationMetadata}from"#tracing/eve/metadata.js";import{createAgentMemoryInstrumentation}from"#tracing/eve/agent-memory-instrumentation.js";import{createEveSessionTracing}from"#tracing/eve/session.js";import{createEveCapturePolicy}from"#tracing/eve/policy.js";function createAgentOtelInstrumentation(e){let t=e.environment??resolveInstrumentationEnvironment(),n=e.recordInputs??!1,r=e.recordOutputs??!1,i=createEveTracing(e),a=createEveCapturePolicy({stateStore:e.stateStore,environment:t,recordInputs:n,recordOutputs:r}),o=new Map,s=new Map,c=createEveSessionTracing({...e,environment:t,tracing:i,capturePolicy:a}),{prepareSessionTrace:l,prepareTurnTrace:u}=c;async function attemptFor(e){let t=o.get(e.attemptId);if(t!==void 0)return t;let n=await c.turnFor(e.sessionId,e.turnId,withChannelAudience(ROOT_CONTEXT,e.channelAudience)),r={stepIndex:e.stepIndex,attempt:e.attemptIndex};return n?.findAttempt(r)??(n?.finished===!1?n.attempt(r):void 0)}let d=createAgentToolInstrumentation({tracing:i,attemptFor,stepFor:e=>o.get(e.attemptId),recordInputs:n,recordOutputs:r,stateStore:e.stateStore}),f=createAgentApprovalInstrumentation({tracing:i,actionStateFor:d.stateFor}),p=createAgentMemoryInstrumentation({...e,environment:t,tracing:i});function turnState(t){return e.stateStore.get(`turn`,JSON.stringify([t.sessionId,t.turnId]))}let onSessionStarted=async e=>{await l(e)},onTurnStarted=async e=>{await u(e)},onStepStarted=async t=>{let n=await turnState(t.scope);if(n===void 0||!isSampledTrace(n.context))return;let r=await e.stateStore.get(`session`,t.scope.sessionId),i=await c.turnFor(t.scope.sessionId,t.scope.turnId,withChannelAudience(ROOT_CONTEXT,t.scope.channelAudience));if(i===void 0||i.finished)return;let a=trace.getSpan(context.active())?.spanContext(),s=await i.attempt({stepIndex:t.scope.stepIndex,attempt:t.scope.attemptIndex,runtimeContext:t.runtimeContext,channel:eveActivationMetadata({session:r,turn:n,sessionId:t.scope.sessionId}).channel,links:a===void 0||a.traceId===n.context.traceId?void 0:[{relationship:`execution.delivery`,context:a}]});o.set(t.scope.attemptId,s)},onStepTerminal=async e=>{let t=e.type===`step.attempt.failed`?{error:e.error}:void 0;await drainOpenSpans(e),await d.drain(e.scope.attemptId,t);let n=o.get(e.scope.attemptId)??await attemptFor(e.scope);o.delete(e.scope.attemptId),t===void 0?await n?.complete():(await n?.fail(t.error),await d.forgetAttempt(e.scope))},onSessionTransition=async t=>{await c.sessionTransition(t),(t.type===`session.completed`||t.type===`session.failed`)&&(await d.deleteForSession(t.sessionId),await e.stateStore.delete(`session`,t.sessionId))},onModelCallStarted=async e=>{let t=o.get(e.scope.attemptId);if(t===void 0)return;let r=await t.modelCall({provider:e.model.provider,modelId:e.model.modelId,messages:n?e.input?.messages.map(e=>isObject(e)&&e.role===`user`?{...e,kind:isUserMessageKind(e.kind)?e.kind:void 0}:e):void 0,instructions:n?e.input?.instructions:void 0,tools:n?e.input?.tools:void 0,runtimeContext:e.runtimeContext},e.idempotencyKey),i=s.get(e.scope.attemptId);i===void 0&&s.set(e.scope.attemptId,i=new Map),i.set(e.idempotencyKey,r)},onModelCallTerminal=async e=>{let t=s.get(e.scope.attemptId),n=t?.get(e.idempotencyKey);t?.delete(e.idempotencyKey),n!==void 0&&(e.type===`model.call.failed`?await n.fail(e.error):await n.complete({outcome:`completed`,result:{...e,content:r?e.content:void 0}}))},m=createAgentChannelDeliveryInstrumentation({recordInputs:n,stateStore:e.stateStore}),onStepMetadata=e=>{let t=o.get(e.scope.attemptId);if(t===void 0)return;let n=readGatewayCostData(e.providerMetadata);n!==void 0&&t.attributes(gatewayCostAttributes(n));let r=gatewayRoutingAttributes(e.providerMetadata);r!==void 0&&t.attributes(r)};return{hook:{events:{...m,...f,"step.attempt.completed":onStepTerminal,"step.attempt.failed":onStepTerminal,"step.attempt.metadata":onStepMetadata,"step.attempt.started":onStepStarted,"model.call.completed":onModelCallTerminal,"model.call.failed":onModelCallTerminal,"model.call.started":onModelCallStarted,"session.completed":onSessionTransition,"session.failed":onSessionTransition,"session.started":onSessionStarted,"session.waiting":onSessionTransition,...d.events,"turn.cancelled":c.turnTerminal,"turn.completed":c.turnTerminal,"turn.failed":c.turnTerminal,"turn.started":onTurnStarted},name:`eve.otel`,projectEvent:a.projectEvent,tracePolicy:()=>({emit:!0,recordInputs:n,recordOutputs:r})},prepareSessionTrace:l,prepareTurnTrace:u,async runInContext(t,n){if(t.type===`memory.operation`)return p.runInContext(t,n);let r={emit:!0,...await a.forOperation(t.scope)},inTurn=async()=>{let i=await c.turnFor(t.scope.sessionId,t.scope.turnId,withChannelAudience(ROOT_CONTEXT,t.scope.channelAudience));if(i!==void 0&&!i.finished)return i.run(n,r);let{sessionId:a,turnId:o}=t.scope;return e.telemetry.suppressed!==void 0&&await c.dropped(a,o)?e.telemetry.suppressed(n):n()};if(t.type===`tool.call`)return d.runInContext(t,n,r,inTurn);let i=s.get(t.scope.attemptId)?.get(t.idempotencyKey);return i!==void 0&&!i.finished?i.run(n,r):inTurn()}};async function drainOpenSpans(e){for(let t of s.get(e.scope.attemptId)?.values()??[])e.type===`step.attempt.failed`?await t.fail(e.error):await t.complete({outcome:`completed`,result:{finishReason:`unknown`,usage:{}}});s.delete(e.scope.attemptId)}}export{createAgentOtelInstrumentation};

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/gateway.d.ts

@@ -15,3 +15,8 @@ export declare function readGatewayCostData(providerMetadata: Readonly<Record<st
     outputCost: number | undefined;
     generationId: string | undefined;
 } | undefined;
+/**
+ * Converts Gateway session affinity metadata to span attributes, so a step can
+ * be matched to its session in the Gateway logs Sessions view.
+ */
+export declare function gatewayRoutingAttributes(providerMetadata: Readonly<Record<string, unknown>> | undefined): Attributes | undefined;

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

@@ -1 +1 @@
-import{stripEveTraceBaggage}from"#protocol/baggage.js";import{context,createContextKey,propagation,trace}from"#compiled/@opentelemetry/api/index.js";const SUPPRESS_TRACING_KEY=createContextKey(`OpenTelemetry SDK Context Key SUPPRESS_TRACING`),traceContextSetter={set(e,t,n){e[t]=n}};function createGatewayTraceContextHeaders(){let e=context.active();if(e.getValue(SUPPRESS_TRACING_KEY)===!0||trace.getSpan(e)===void 0)return;let t={};return propagation.inject(e,t,traceContextSetter),stripEveTraceBaggage(t),Object.keys(t).length===0?void 0:t}function gatewayCostAttributes(e){return{"gen_ai.usage.cost":e.cost,"gen_ai.usage.gateway_cost":e.gatewayCost,"gen_ai.usage.input_cost":e.inputCost,"gen_ai.usage.output_cost":e.outputCost,"gen_ai.generation.id":e.generationId}}function readGatewayCostData(e){if(e===void 0)return;let t=e.gateway;if(typeof t!=`object`||!t||Array.isArray(t))return;let n=t;return{cost:readUsd(n.cost),gatewayCost:readUsd(n.gatewayCost),inputCost:readUsd(n.inputInferenceCost),outputCost:readUsd(n.outputInferenceCost),generationId:typeof n.generationId==`string`&&n.generationId.length>0?n.generationId:void 0}}function readUsd(e){if(typeof e!=`string`||e.trim()===``)return;let t=Number(e);return Number.isFinite(t)?t:void 0}export{createGatewayTraceContextHeaders,gatewayCostAttributes,readGatewayCostData};
+import{isObject}from"#shared/guards.js";import{stripEveTraceBaggage}from"#protocol/baggage.js";import{context,createContextKey,propagation,trace}from"#compiled/@opentelemetry/api/index.js";import{readGatewayRouting}from"#shared/gateway-routing.js";const SUPPRESS_TRACING_KEY=createContextKey(`OpenTelemetry SDK Context Key SUPPRESS_TRACING`),traceContextSetter={set(e,t,n){e[t]=n}};function createGatewayTraceContextHeaders(){let e=context.active();if(e.getValue(SUPPRESS_TRACING_KEY)===!0||trace.getSpan(e)===void 0)return;let t={};return propagation.inject(e,t,traceContextSetter),stripEveTraceBaggage(t),Object.keys(t).length===0?void 0:t}function gatewayCostAttributes(e){return{"gen_ai.usage.cost":e.cost,"gen_ai.usage.gateway_cost":e.gatewayCost,"gen_ai.usage.input_cost":e.inputCost,"gen_ai.usage.output_cost":e.outputCost,"gen_ai.generation.id":e.generationId}}function readGatewayCostData(e){if(e===void 0)return;let t=e.gateway;if(typeof t!=`object`||!t||Array.isArray(t))return;let n=t;return{cost:readUsd(n.cost),gatewayCost:readUsd(n.gatewayCost),inputCost:readUsd(n.inputInferenceCost),outputCost:readUsd(n.outputInferenceCost),generationId:typeof n.generationId==`string`&&n.generationId.length>0?n.generationId:void 0}}function gatewayRoutingAttributes(e){let t=e?.gateway,n=readGatewayRouting(isObject(t)?t.routing:void 0);if(n!==void 0)return{"vercel.ai_gateway.client_session_id":n.clientSessionId,"vercel.ai_gateway.client_session_id_source":n.clientSessionIdSource,"vercel.ai_gateway.affinity.outcome":n.affinity?.outcome,"vercel.ai_gateway.affinity.pinned_provider":n.affinity?.pinnedProvider,"vercel.ai_gateway.affinity.displaced_provider":n.affinity?.displacedProvider}}function readUsd(e){if(typeof e!=`string`||e.trim()===``)return;let t=Number(e);return Number.isFinite(t)?t:void 0}export{createGatewayTraceContextHeaders,gatewayCostAttributes,gatewayRoutingAttributes,readGatewayCostData};

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,11 +1,5 @@
-import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
 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: {
@@ -17,12 +11,6 @@ export declare function eveTurnIdentity(input: {
     runId: string;
     turnId: string;
 };
-/** Content flags are recorded by eve's content processor, not withheld by the library. */
-export declare function eveCapture(reference: SpanContext | undefined): {
-    emit: boolean;
-    recordInputs: boolean;
-    recordOutputs: boolean;
-};
 /** eve's agent tracing, checkpointed in its workflow-context trace state. */
 export declare function createEveTracing(input: {
     readonly telemetry: AgentTelemetry;

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 eveCapture(e){return{emit:!!((e?.traceFlags??1)&1),recordInputs:!0,recordOutputs:!0}}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,eveCapture,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/policy.d.ts

@@ -8,7 +8,7 @@ export declare function createEveCapturePolicy(input: {
     readonly recordOutputs: boolean;
 }): {
     projectEvent(event: InstrumentationEvent): Promise<InstrumentationEvent>;
-    forOperation(scope: InstrumentationAttemptScope): Promise<{
+    forOperation(scope: Pick<InstrumentationAttemptScope, "sessionId" | "channelAudience">): Promise<{
         recordInputs: boolean;
         recordOutputs: boolean;
     }>;

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

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{applyLiveDeliveryAudienceCeiling,resolveForwardedTraceSeed}from"#shared/forwarded-trace-policy.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{isSampledTrace,resolveTracePolicyDecision}from"#shared/trace-policy.js";import{withoutInstrumentationContent}from"#instrumentation/content.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{instrumentationEventForTraceDecision}from"#instrumentation/content-policy.js";function createEveCapturePolicy(e){return{async projectEvent(t){let n=await e.stateStore.get(`session`,`scope`in t?t.scope.sessionId:t.sessionId),r=audienceForEvent(t,n?.channelAudience),i=`traceSeed`in t?t.traceSeed:void 0,a=contextStorage.getStore()?.get(SessionTraceSeedKey),o=resolveForwardedTraceSeed(a),s=resolveForwardedTraceSeed(i,o?.forwardedTracePolicy),decisionForTrace=t=>t===void 0?void 0:resolveTracePolicyDecision(isSampledTrace(t),{audience:r,environment:e.environment}),c=s?.decision??o?.decision??readInstrumentationDecision(n?.decision)??decisionForTrace(i)??decisionForTrace(a)??decisionForTrace(n?.context);if(c===void 0)return withoutInstrumentationContent(t);let l=s===void 0||!(`traceSeed`in t)||t.traceSeed===void 0?t:{...t,traceSeed:{...t.traceSeed,decision:s.decision,traceFlags:s.traceFlags}};return instrumentationEventForTraceDecision(l,applyLiveDeliveryAudienceCeiling(c.action===`drop`?c:{...c,recordInputs:e.recordInputs&&c.recordInputs,recordOutputs:e.recordOutputs&&c.recordOutputs},r,s?.forwardedTracePolicy??o?.forwardedTracePolicy,e.environment),{audience:r,environment:e.environment},{applyAudienceCeiling:!1})},async forOperation(t){let n=await e.stateStore.get(`session`,t.sessionId),r=resolveForwardedTraceSeed(contextStorage.getStore()?.get(SessionTraceSeedKey)),i=r?.decision??n?.decision,a=i===void 0?void 0:applyLiveDeliveryAudienceCeiling(i,normalizeChannelAudience(t.channelAudience),r?.forwardedTracePolicy,e.environment);return{recordInputs:e.recordInputs&&a?.action===`record`&&a.recordInputs,recordOutputs:e.recordOutputs&&a?.action===`record`&&a.recordOutputs}}}}function audienceForEvent(e,t){return`delivery`in e?normalizeChannelAudience(e.delivery.channelAudience):`scope`in e&&e.scope.channelAudience!==void 0?normalizeChannelAudience(e.scope.channelAudience):e.type===`session.started`?normalizeChannelAudience(e.channelAudience):normalizeChannelAudience(t)}export{createEveCapturePolicy};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{ConversationContextKey}from"#shared/conversation-context.js";import{applyLiveDeliveryAudienceCeiling,resolveForwardedTraceSeed}from"#shared/forwarded-trace-policy.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{isSampledTrace,resolveTracePolicyDecision}from"#shared/trace-policy.js";import{withoutInstrumentationContent}from"#instrumentation/content.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{instrumentationEventForTraceDecision}from"#instrumentation/content-policy.js";function createEveCapturePolicy(e){return{async projectEvent(t){let n=await e.stateStore.get(`session`,`scope`in t?t.scope.sessionId:t.sessionId),r=audienceForEvent(t,n?.channelAudience),i=`traceSeed`in t?t.traceSeed:void 0,a=contextStorage.getStore()?.get(SessionTraceSeedKey),o=resolveForwardedTraceSeed(a),s=resolveForwardedTraceSeed(i,o?.forwardedTracePolicy),decisionForTrace=t=>t===void 0?void 0:resolveTracePolicyDecision(isSampledTrace(t),{audience:r,environment:e.environment}),c=s?.decision??o?.decision??readInstrumentationDecision(n?.decision)??decisionForTrace(i)??decisionForTrace(a)??decisionForTrace(n?.context);if(c===void 0)return withoutInstrumentationContent(t);let l=s===void 0||!(`traceSeed`in t)||t.traceSeed===void 0?t:{...t,traceSeed:{...t.traceSeed,decision:s.decision,traceFlags:s.traceFlags}};return instrumentationEventForTraceDecision(l,applyLiveDeliveryAudienceCeiling(c.action===`drop`?c:{...c,recordInputs:e.recordInputs&&c.recordInputs,recordOutputs:e.recordOutputs&&c.recordOutputs},r,s?.forwardedTracePolicy??o?.forwardedTracePolicy,e.environment),{audience:r,environment:e.environment},{applyAudienceCeiling:!1})},async forOperation(t){let n=await e.stateStore.get(`session`,t.sessionId),r=contextStorage.getStore(),i=resolveForwardedTraceSeed(r?.get(SessionTraceSeedKey)),a=i?.decision??n?.decision,o=a===void 0?void 0:applyLiveDeliveryAudienceCeiling(a,normalizeChannelAudience(t.channelAudience??r?.get(ConversationContextKey)?.audience??n?.channelAudience),i?.forwardedTracePolicy,e.environment);return{recordInputs:e.recordInputs&&o?.action===`record`&&o.recordInputs,recordOutputs:e.recordOutputs&&o?.action===`record`&&o.recordOutputs}}}}function audienceForEvent(e,t){return`delivery`in e?normalizeChannelAudience(e.delivery.channelAudience):`scope`in e&&e.scope.channelAudience!==void 0?normalizeChannelAudience(e.scope.channelAudience):e.type===`session.started`?normalizeChannelAudience(e.channelAudience):normalizeChannelAudience(t)}export{createEveCapturePolicy};

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

@@ -1,8 +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;
@@ -10,6 +12,7 @@ interface EveSessionTracingInput {
     readonly frameworkVersion: string;
     readonly stateStore: AgentTraceStateStore;
     readonly tracePolicy?: TraceCapturePolicy;
+    readonly capturePolicy: ReturnType<typeof createEveCapturePolicy>;
 }
 type SessionMetadata = Omit<InstrumentationSessionStartedEvent, "idempotencyKey" | "type">;
 interface EveSessionTracing {
@@ -17,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{eveCapture,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:eveCapture(c),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/README.md

@@ -25,6 +25,7 @@ Important naming note:
 | Package a procedure the agent loads only when it applies | [Skills](./skills.mdx)                                                                 |
 | Carry state across turns, or shape what the model sees   | [State](./concepts/state.md), [Context Control](./concepts/context-control.md)         |
 | Run commands or untrusted code in isolation              | [Sandboxes](./sandbox/index.mdx)                                                       |
+| Answer voice notes and other audio attachments           | [Voice Notes](./patterns/voice-notes.md)                                               |
 | Delegate work to a specialist child agent                | [Subagents](./subagents/index.mdx)                                                     |
 | Run work on a recurring schedule                         | [Schedules](./schedules.mdx)                                                           |
 | Install an existing integration instead of writing one   | [Add Integrations](./install-integrations.mdx)                                         |

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
 
@@ -67,6 +67,28 @@ Gateway, share that ID so their Gateway generations can be found together.
 Direct-provider calls do not receive the option. An authored `gateway.sessionId`
 takes precedence; AI Gateway hashes IDs longer than 256 characters.
 
+AI Gateway also uses this ID for
+[session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity),
+which tries the provider that served the session's previous call first, among
+the providers your routing settings allow, so that provider can read the prompt
+from its cache. The conversation
+appears as one session in the AI Gateway logs Sessions view. Affinity can move
+the pinned provider ahead of your `order`. To keep `order` exactly, set
+`sessionAffinity: false`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
+  modelOptions: {
+    providerOptions: {
+      gateway: { order: ["bedrock", "anthropic"], sessionAffinity: false },
+    },
+  },
+});
+```
+
 For direct OpenAI and `chatgpt()` model calls, eve sets
 `providerOptions.openai.promptCacheKey` to a SHA-256 hash of the session ID,
 which helps OpenAI route a session's calls to the cache that holds its prompt
@@ -115,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.
@@ -240,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.
 
@@ -290,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`
@@ -474,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()`. |