eve 0.71.2 → 0.72.0

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

@@ -1,2 +1,2 @@
-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{AGENT_SPAN_NAMES,agentInvocationSpanName,modelSpanName}from"#tracing/agent-span-contract.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{withOperationConversation}from"#tracing/conversation-context.js";import{isSampledTrace,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,context,trace}from"#compiled/@opentelemetry/api/index.js";import{markAgentTraceContext}from"#tracing/agent-trace-context.js";import{attemptIdempotencyKey}from"#instrumentation/lifecycle.js";import{withoutInstrumentationContent}from"#instrumentation/content.js";import{withErrorContent}from"#tracing/error-content-context.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute,genAiInputMessagesAttribute,genAiOutputMessagesAttribute,genAiSystemInstructionsAttribute,textContentAttribute,toolResultsContentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{withAgentToolContentPolicy}from"#tracing/agent-tool-span-context.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{readGatewayCost,setAgentInvocationUsage,setAgentUsage,setGenAiUsage}from"#tracing/agent-otel-usage.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";import{instrumentationEventForTraceDecision}from"#instrumentation/content-policy.js";import{createAgentActionInstrumentation}from"#tracing/agent-action-instrumentation.js";import{createAgentApprovalInstrumentation}from"#tracing/agent-approval-instrumentation.js";import{createAgentChannelDeliveryInstrumentation}from"#tracing/agent-channel-delivery-instrumentation.js";import{createAgentToolInstrumentation}from"#tracing/agent-tool-instrumentation.js";import*as runtimeAttributes from"#tracing/agent-otel-runtime-context.js";import{createAgentMemoryInstrumentation}from"#tracing/agent-memory-instrumentation.js";import{createAgentOtelSessionContext}from"#tracing/agent-otel-session-context.js";function createAgentOtelInstrumentation(e){let t=e.environment??resolveInstrumentationEnvironment(),n=e.recordInputs??!1,r=e.recordOutputs??!1,i=new WeakMap,a=new Map,o=new WeakMap,s=new WeakMap,c=createAgentActionInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:n,recordOutputs:r,resolveTraceContext:async t=>(await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId))?.context,stateStore:e.stateStore,tracer:e.tracer}),l=createAgentApprovalInstrumentation({actionContextFor:c.contextFor,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,tracer:e.tracer}),u=createAgentToolInstrumentation({actionContextFor:c.contextFor,idGenerator:e.idGenerator,recordInputs:n,recordOutputs:r,resolveFallback:e=>{let t=a.get(e.scope.attemptId)??e.scope,n=o.get(t);return n===void 0?void 0:{context:n.context,spanContext:n.span.spanContext()}},tracer:e.tracer}),d=createAgentMemoryInstrumentation({...e,environment:t}),{prepareSessionTrace:f,prepareTurnTrace:p}=createAgentOtelSessionContext({...e,environment:t}),projectEvent=async i=>{let a=await e.stateStore.getSession(sessionIdForEvent(i)),o=audienceForEvent(i,a?.channelAudience),s=`traceSeed`in i?i.traceSeed:void 0,c=contextStorage.getStore()?.get(SessionTraceSeedKey),l=resolveForwardedTraceSeed(c),u=resolveForwardedTraceSeed(s,l?.forwardedTracePolicy),decisionForTrace=e=>e===void 0?void 0:resolveTracePolicyDecision(isSampledTrace(e),{audience:o,environment:t}),d=u?.decision??l?.decision??readInstrumentationDecision(a?.decision)??decisionForTrace(s)??decisionForTrace(c)??decisionForTrace(a?.context);if(d===void 0)return withoutInstrumentationContent(i);let f=u===void 0||!(`traceSeed`in i)||i.traceSeed===void 0?i:{...i,traceSeed:{...i.traceSeed,decision:u.decision,traceFlags:u.traceFlags}};return instrumentationEventForTraceDecision(f,applyLiveDeliveryAudienceCeiling(d.action===`drop`?d:{action:`record`,recordInputs:n&&d.recordInputs,recordOutputs:r&&d.recordOutputs},o,u?.forwardedTracePolicy??l?.forwardedTracePolicy,t),{audience:o,environment:t},{applyAudienceCeiling:!1})},onSessionStarted=async e=>{await f(e)},onTurnStarted=async e=>{await p(e)},onStepStarted=async t=>{let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);if(n===void 0||!isSampledTrace(n.context))return;let r=await e.stateStore.getSession(t.scope.sessionId),i=withChannelAudience(contextFromSpanContext(n.context),t.scope.channelAudience),s=trace.getSpan(context.active())?.spanContext(),c=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(attemptIdempotencyKey(t.scope)),()=>e.tracer.startSpan(AGENT_SPAN_NAMES.step,{attributes:runtimeAttributes.agentStepAttributes({event:t,frameworkVersion:e.frameworkVersion,session:r,turn:n}),links:s===void 0||s.traceId===n.context.traceId?void 0:[{attributes:{"eve.link.type":`workflow.delivery`},context:s}]},i));c.addEvent(`step.started`);let l=trace.setSpan(i,c);o.set(t.scope,{context:l,span:c}),a.set(t.scope.attemptId,t.scope)},onStepTerminal=async e=>{let t=a.get(e.scope.attemptId)??e.scope;i.delete(t),drainOpenSpans({...e,scope:t}),u.drain(e.scope.attemptId,e.type===`step.attempt.failed`?{error:e.error}:void 0),e.type===`step.attempt.failed`&&await c.failForAttempt(t,e.error),a.delete(e.scope.attemptId);let n=o.get(t);n!==void 0&&(n.span.addEvent(e.type===`step.attempt.completed`?`step.completed`:`step.failed`),e.type===`step.attempt.failed`&&recordAgentSpanError(n.span,e.error),n.span.end(),o.delete(t))},onTurnTerminal=async t=>{await e.stateStore.updateTurn(t.sessionId,t.turnId,e=>({...e,terminal:t.type===`turn.failed`?{error:t.error,type:t.type}:{type:t.type}}))},onSessionTransition=async t=>{if(t.type===`session.failed`&&t.turnId!==void 0&&await e.stateStore.updateTurn(t.sessionId,t.turnId,e=>({...e,terminal:e.terminal??{error:t.error,type:`turn.failed`}})),t.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0){let r=await e.stateStore.getSession(t.sessionId);if(isSampledTrace(n.context)){let i=r?.agentName??n.subagentName,a=withChannelAudience(n.caller===void 0||n.caller.isRemote===!0?ROOT_CONTEXT:contextFromSpanContext(n.caller),r?.channelAudience),startSpan=()=>e.tracer.startSpan(agentInvocationSpanName(i),{attributes:runtimeAttributes.agentActivationAttributes({agentName:i,frameworkVersion:e.frameworkVersion,session:r,sessionId:t.sessionId,turnId:t.turnId,turn:n}),kind:SpanKind.INTERNAL,links:agentActivationLinks(n),root:n.caller===void 0||n.caller.isRemote===!0,startTime:n.startTimeMs},a),o=e.idGenerator.withSpanId(n.context.spanId,()=>e.idGenerator.withTraceId(n.context.traceId,startSpan));setAgentInvocationUsage(o,n.modelUsage),o.addEvent(`turn.started`,void 0,n.startTimeMs),n.terminal!==void 0&&(o.setAttribute(`agent.turn.outcome`,n.terminal.type===`turn.completed`?`completed`:n.terminal.type===`turn.cancelled`?`cancelled`:`failed`),o.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordAgentSpanError(o,n.terminal.error)),o.end()}await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&(await c.deleteForSession(t.sessionId),await e.stateStore.deleteSession(t.sessionId))},onModelCallStarted=t=>{let r=o.get(t.scope);if(r===void 0)return;r.span.setAttribute(`agent.model.id`,t.model.modelId),r.span.setAttribute(`agent.model.provider`,t.model.provider);let i=e.tracer.startSpan(modelSpanName(t.model.modelId),{attributes:{"gen_ai.agent.name":t.scope.functionId,"gen_ai.operation.name":`chat`,"gen_ai.provider.name":t.model.provider,"gen_ai.request.model":t.model.modelId,...agentSpanNamingAttributes(modelSpanName(t.model.modelId),`chat`),...agentTraceIdentityAttributes({rootSessionId:t.scope.rootSessionId??t.scope.sessionId,traceSessionId:traceSessionIdOf(t.scope),sessionId:t.scope.sessionId}),...runtimeAttributes.runtimeContextAttributes(t.runtimeContext)},kind:SpanKind.CLIENT},r.context);if(n&&t.input!==void 0){let e=genAiInputMessagesAttribute(t.input.messages);e!==void 0&&i.setAttribute(`gen_ai.input.messages`,e);let n=genAiSystemInstructionsAttribute(t.input.instructions);n!==void 0&&i.setAttribute(`gen_ai.system_instructions`,n)}let a={context:trace.setSpan(r.context,i),span:i};getExecutionContexts(t.scope).set(t.idempotencyKey,a.context),getSpanStates(s,t.scope).set(t.idempotencyKey,a)},onModelCallTerminal=async e=>{i.get(e.scope)?.delete(e.idempotencyKey);let t=takeSpanState(s,e.scope,e.idempotencyKey);if(t!==void 0){if(e.type===`model.call.failed`)recordAgentSpanError(t.span,e.error);else{await recordTurnUsage(e),setGenAiUsage(t.span,e.usage),e.responseId!==void 0&&t.span.setAttribute(`gen_ai.response.id`,e.responseId),e.responseModelId!==void 0&&t.span.setAttribute(`gen_ai.response.model`,e.responseModelId),t.span.setAttribute(`gen_ai.response.finish_reasons`,[e.finishReason]);let n=o.get(e.scope);if(n!==void 0&&setAgentUsage(n.span,e.usage),r){t.span.setAttribute(`ai.response.finish_reason`,e.finishReason);let n=e.content;if(n===void 0){t.span.end();return}let r=genAiOutputMessagesAttribute(n,e.finishReason);r!==void 0&&t.span.setAttribute(`gen_ai.output.messages`,r);let i=textContentAttribute(n.filter(e=>e.type===`reasoning`).map(e=>e.text).filter(e=>e.trim().length>0).join(`
-`));i!==void 0&&t.span.setAttribute(`ai.response.reasoning`,i);let a=textContentAttribute(n.filter(e=>e.type===`text`).map(e=>e.text).join(``));a!==void 0&&t.span.setAttribute(`ai.response.text`,a);let o=n.filter(e=>e.type===`tool-call`).map(e=>({callId:e.callId,input:e.input,toolName:e.toolName}));if(o.length>0){let e=contentAttribute(o);e!==void 0&&t.span.setAttribute(`ai.response.tool_calls`,e)}let s=n.filter(e=>e.type===`tool-result`||e.type===`tool-error`).map(e=>e.type===`tool-result`?{callId:e.callId,input:e.input,output:e.output,toolName:e.toolName}:{callId:e.callId,error:errorText(e.error),input:e.input,toolName:e.toolName});if(s.length>0){let e=toolResultsContentAttribute(s);e!==void 0&&t.span.setAttribute(`ai.response.tool_results`,e)}}}t.span.end()}},recordTurnUsage=async t=>{(t.usage.inputTokens!==void 0||t.usage.outputTokens!==void 0)&&await e.stateStore.updateTurn(t.scope.sessionId,t.scope.turnId,e=>({...e,modelUsage:{inputTokens:t.usage.inputTokens===void 0?e.modelUsage?.inputTokens:(e.modelUsage?.inputTokens??0)+t.usage.inputTokens,outputTokens:t.usage.outputTokens===void 0?e.modelUsage?.outputTokens:(e.modelUsage?.outputTokens??0)+t.usage.outputTokens}}))},m=createAgentChannelDeliveryInstrumentation({recordInputs:n,stateStore:e.stateStore}),onStepMetadata=e=>{let t=o.get(e.scope);if(t===void 0)return;let n=readGatewayCost(e.providerMetadata);if(n!==void 0)for(let[e,r]of Object.entries(n))t.span.setAttribute(e,r)};return{hook:{events:{...m,"action.completed":c.events[`action.completed`],"action.failed":c.events[`action.failed`],async"action.started"(e,t){await c.events[`action.started`](e,t),await u.actionStarted(e)},...l,...d.events,"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":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted},name:`eve.otel`,projectEvent,tracePolicy:()=>({emit:!0,recordInputs:n,recordOutputs:r})},prepareSessionTrace:f,prepareTurnTrace:p,async runInContext(o,s){if(o.type===`memory.operation`)return d.runInContext(o,s);let c=a.get(o.scope.attemptId)??o.scope,l=i.get(c),f=o.type===`model.call`?l?.get(o.idempotencyKey):u.contextFor(o.scope.attemptId,o.idempotencyKey);if(f===void 0){let t=await e.stateStore.getTurn(o.scope.sessionId,o.scope.turnId);t!==void 0&&(f=withChannelAudience(contextFromSpanContext(t.context),o.scope.channelAudience),isSampledTrace(t.context)||(f=suppressTracing(f)))}let p=await e.stateStore.getSession(o.scope.sessionId),m=resolveForwardedTraceSeed(contextStorage.getStore()?.get(SessionTraceSeedKey)),h=m?.decision??p?.decision,g=h===void 0?void 0:applyLiveDeliveryAudienceCeiling(h,normalizeChannelAudience(o.scope.channelAudience),m?.forwardedTracePolicy,t),_={recordInputs:n&&g?.action===`record`&&g.recordInputs,recordOutputs:r&&g?.action===`record`&&g.recordOutputs};if(f===void 0)return s();let v=withErrorContent(f,_.recordOutputs),y=o.type===`tool.call`?withAgentToolContentPolicy(v,_):v;return context.with(markAgentTraceContext(withOperationConversation(y,o.scope)),s)}};function getExecutionContexts(e){let t=i.get(e);return t===void 0&&(t=new Map,i.set(e,t)),t}function drainOpenSpans(e){for(let t of s.get(e.scope)?.values()??[])e.type===`step.attempt.failed`&&recordAgentSpanError(t.span,e.error),t.span.end();s.delete(e.scope)}}function agentActivationLinks(e){let t=[];return e.caller?.isRemote===!0&&t.push({context:e.caller,attributes:{"eve.link.type":`agent.dispatch`}}),e.channelDelivery?.requestTraceContext!==void 0&&t.push({context:e.channelDelivery.requestTraceContext,attributes:{"eve.link.type":`channel.request`}}),t.length===0?void 0:t}function sessionIdForEvent(e){return`scope`in e?e.scope.sessionId:e.sessionId}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)}function getSpanStates(e,t){let n=e.get(t);return n===void 0&&(n=new Map,e.set(t,n)),n}function takeSpanState(e,t,n){let r=e.get(t),i=r?.get(n);if(r!==void 0)return r.delete(n),r.size===0&&e.delete(t),i}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}const errorText=e=>e instanceof Error?e.message:e;export{createAgentOtelInstrumentation};
+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{AGENT_SPAN_NAMES,agentInvocationSpanName,modelSpanName}from"#tracing/agent-span-contract.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{withOperationConversation}from"#tracing/conversation-context.js";import{isSampledTrace,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,context,trace}from"#compiled/@opentelemetry/api/index.js";import{markAgentTraceContext}from"#tracing/agent-trace-context.js";import{attemptIdempotencyKey}from"#instrumentation/lifecycle.js";import{withoutInstrumentationContent}from"#instrumentation/content.js";import{withErrorContent}from"#tracing/error-content-context.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute,genAiInputMessagesAttribute,genAiOutputMessagesAttribute,genAiSystemInstructionsAttribute,textContentAttribute,toolResultsContentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{withAgentToolContentPolicy}from"#tracing/agent-tool-span-context.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";import{instrumentationEventForTraceDecision}from"#instrumentation/content-policy.js";import{createAgentApprovalInstrumentation}from"#tracing/agent-approval-instrumentation.js";import{createAgentChannelDeliveryInstrumentation}from"#tracing/agent-channel-delivery-instrumentation.js";import{createAgentToolInstrumentation}from"#tracing/agent-tool-instrumentation.js";import*as runtimeAttributes from"#tracing/agent-otel-runtime-context.js";import{createAgentMemoryInstrumentation}from"#tracing/agent-memory-instrumentation.js";import{readGatewayCost,setAgentInvocationUsage,setAgentUsage,setGenAiUsage}from"#tracing/agent-otel-usage.js";import{createAgentOtelSessionContext}from"#tracing/agent-otel-session-context.js";function createAgentOtelInstrumentation(e){let t=e.environment??resolveInstrumentationEnvironment(),n=e.recordInputs??!1,r=e.recordOutputs??!1,i=new WeakMap,a=new Map,o=new WeakMap,s=new WeakMap,c=createAgentToolInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:n,recordOutputs:r,resolveTraceContext:async t=>(await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId))?.context,stateStore:e.stateStore,resolveFallback:e=>{let t=a.get(e.scope.attemptId)??e.scope,n=o.get(t);return n===void 0?void 0:{context:n.context,spanContext:n.span.spanContext()}},tracer:e.tracer}),l=createAgentApprovalInstrumentation({actionContextFor:c.dispatchContextFor,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,tracer:e.tracer}),u=createAgentMemoryInstrumentation({...e,environment:t}),{prepareSessionTrace:d,prepareTurnTrace:f}=createAgentOtelSessionContext({...e,environment:t}),projectEvent=async i=>{let a=await e.stateStore.getSession(sessionIdForEvent(i)),o=audienceForEvent(i,a?.channelAudience),s=`traceSeed`in i?i.traceSeed:void 0,c=contextStorage.getStore()?.get(SessionTraceSeedKey),l=resolveForwardedTraceSeed(c),u=resolveForwardedTraceSeed(s,l?.forwardedTracePolicy),decisionForTrace=e=>e===void 0?void 0:resolveTracePolicyDecision(isSampledTrace(e),{audience:o,environment:t}),d=u?.decision??l?.decision??readInstrumentationDecision(a?.decision)??decisionForTrace(s)??decisionForTrace(c)??decisionForTrace(a?.context);if(d===void 0)return withoutInstrumentationContent(i);let f=u===void 0||!(`traceSeed`in i)||i.traceSeed===void 0?i:{...i,traceSeed:{...i.traceSeed,decision:u.decision,traceFlags:u.traceFlags}};return instrumentationEventForTraceDecision(f,applyLiveDeliveryAudienceCeiling(d.action===`drop`?d:{action:`record`,recordInputs:n&&d.recordInputs,recordOutputs:r&&d.recordOutputs},o,u?.forwardedTracePolicy??l?.forwardedTracePolicy,t),{audience:o,environment:t},{applyAudienceCeiling:!1})},onSessionStarted=async e=>{await d(e)},onTurnStarted=async e=>{await f(e)},onStepStarted=async t=>{let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);if(n===void 0||!isSampledTrace(n.context))return;let r=await e.stateStore.getSession(t.scope.sessionId),i=withChannelAudience(contextFromSpanContext(n.context),t.scope.channelAudience),s=trace.getSpan(context.active())?.spanContext(),c=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(attemptIdempotencyKey(t.scope)),()=>e.tracer.startSpan(AGENT_SPAN_NAMES.step,{attributes:runtimeAttributes.agentStepAttributes({event:t,frameworkVersion:e.frameworkVersion,session:r,turn:n}),links:s===void 0||s.traceId===n.context.traceId?void 0:[{attributes:{"eve.link.type":`workflow.delivery`},context:s}]},i));c.addEvent(`step.started`);let l=trace.setSpan(i,c);o.set(t.scope,{context:l,span:c}),a.set(t.scope.attemptId,t.scope)},onStepTerminal=async e=>{let t=a.get(e.scope.attemptId)??e.scope;i.delete(t),drainOpenSpans({...e,scope:t}),c.drain(e.scope.attemptId,e.type===`step.attempt.failed`?{error:e.error}:void 0),e.type===`step.attempt.failed`&&await c.failForAttempt(t,e.error),a.delete(e.scope.attemptId);let n=o.get(t);n!==void 0&&(n.span.addEvent(e.type===`step.attempt.completed`?`step.completed`:`step.failed`),e.type===`step.attempt.failed`&&recordAgentSpanError(n.span,e.error),n.span.end(),o.delete(t))},onTurnTerminal=async t=>{await e.stateStore.updateTurn(t.sessionId,t.turnId,e=>({...e,terminal:t.type===`turn.failed`?{error:t.error,type:t.type}:{type:t.type}}))},onSessionTransition=async t=>{if(t.type===`session.failed`&&t.turnId!==void 0&&await e.stateStore.updateTurn(t.sessionId,t.turnId,e=>({...e,terminal:e.terminal??{error:t.error,type:`turn.failed`}})),t.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0){let r=await e.stateStore.getSession(t.sessionId);if(isSampledTrace(n.context)){let i=r?.agentName??n.subagentName,a=withChannelAudience(n.caller===void 0||n.caller.isRemote===!0?ROOT_CONTEXT:contextFromSpanContext(n.caller),r?.channelAudience),startSpan=()=>e.tracer.startSpan(agentInvocationSpanName(i),{attributes:runtimeAttributes.agentActivationAttributes({agentName:i,frameworkVersion:e.frameworkVersion,session:r,sessionId:t.sessionId,turnId:t.turnId,turn:n}),kind:SpanKind.INTERNAL,links:agentActivationLinks(n),root:n.caller===void 0||n.caller.isRemote===!0,startTime:n.startTimeMs},a),o=e.idGenerator.withSpanId(n.context.spanId,()=>e.idGenerator.withTraceId(n.context.traceId,startSpan));setAgentInvocationUsage(o,n.modelUsage),o.addEvent(`turn.started`,void 0,n.startTimeMs),n.terminal!==void 0&&(o.setAttribute(`agent.turn.outcome`,n.terminal.type===`turn.completed`?`completed`:n.terminal.type===`turn.cancelled`?`cancelled`:`failed`),o.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordAgentSpanError(o,n.terminal.error)),o.end()}await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&(await c.deleteForSession(t.sessionId),await e.stateStore.deleteSession(t.sessionId))},onModelCallStarted=t=>{let r=o.get(t.scope);if(r===void 0)return;r.span.setAttribute(`agent.model.id`,t.model.modelId);let i=e.tracer.startSpan(modelSpanName(t.model.modelId),{attributes:{"gen_ai.agent.name":t.scope.functionId,"gen_ai.operation.name":`chat`,"gen_ai.provider.name":t.model.provider,"gen_ai.request.model":t.model.modelId,...agentSpanNamingAttributes(modelSpanName(t.model.modelId),`chat`),...agentTraceIdentityAttributes({rootSessionId:t.scope.rootSessionId??t.scope.sessionId,traceSessionId:traceSessionIdOf(t.scope),sessionId:t.scope.sessionId}),...runtimeAttributes.runtimeContextAttributes(t.runtimeContext)},kind:SpanKind.CLIENT},r.context);if(n&&t.input!==void 0){let e=genAiInputMessagesAttribute(t.input.messages);e!==void 0&&i.setAttribute(`gen_ai.input.messages`,e);let n=genAiSystemInstructionsAttribute(t.input.instructions);n!==void 0&&i.setAttribute(`gen_ai.system_instructions`,n)}let a={context:trace.setSpan(r.context,i),span:i};getExecutionContexts(t.scope).set(t.idempotencyKey,a.context),getSpanStates(s,t.scope).set(t.idempotencyKey,a)},onModelCallTerminal=async e=>{i.get(e.scope)?.delete(e.idempotencyKey);let t=takeSpanState(s,e.scope,e.idempotencyKey);if(t!==void 0){if(e.type===`model.call.failed`)recordAgentSpanError(t.span,e.error);else{await recordTurnUsage(e),setGenAiUsage(t.span,e.usage),e.responseId!==void 0&&t.span.setAttribute(`gen_ai.response.id`,e.responseId),e.responseModelId!==void 0&&t.span.setAttribute(`gen_ai.response.model`,e.responseModelId),t.span.setAttribute(`gen_ai.response.finish_reasons`,[e.finishReason]);let n=o.get(e.scope);if(n!==void 0&&setAgentUsage(n.span,e.usage),r){t.span.setAttribute(`ai.response.finish_reason`,e.finishReason);let n=e.content;if(n===void 0){t.span.end();return}let r=genAiOutputMessagesAttribute(n,e.finishReason);r!==void 0&&t.span.setAttribute(`gen_ai.output.messages`,r);let i=textContentAttribute(n.filter(e=>e.type===`reasoning`).map(e=>e.text).filter(e=>e.trim().length>0).join(`
+`));i!==void 0&&t.span.setAttribute(`ai.response.reasoning`,i);let a=textContentAttribute(n.filter(e=>e.type===`text`).map(e=>e.text).join(``));a!==void 0&&t.span.setAttribute(`ai.response.text`,a);let o=n.filter(e=>e.type===`tool-call`).map(e=>({callId:e.callId,input:e.input,toolName:e.toolName}));if(o.length>0){let e=contentAttribute(o);e!==void 0&&t.span.setAttribute(`ai.response.tool_calls`,e)}let s=n.filter(e=>e.type===`tool-result`||e.type===`tool-error`).map(e=>e.type===`tool-result`?{callId:e.callId,input:e.input,output:e.output,toolName:e.toolName}:{callId:e.callId,error:errorText(e.error),input:e.input,toolName:e.toolName});if(s.length>0){let e=toolResultsContentAttribute(s);e!==void 0&&t.span.setAttribute(`ai.response.tool_results`,e)}}}t.span.end()}},recordTurnUsage=async t=>{(t.usage.inputTokens!==void 0||t.usage.outputTokens!==void 0)&&await e.stateStore.updateTurn(t.scope.sessionId,t.scope.turnId,e=>({...e,modelUsage:{inputTokens:t.usage.inputTokens===void 0?e.modelUsage?.inputTokens:(e.modelUsage?.inputTokens??0)+t.usage.inputTokens,outputTokens:t.usage.outputTokens===void 0?e.modelUsage?.outputTokens:(e.modelUsage?.outputTokens??0)+t.usage.outputTokens}}))},p=createAgentChannelDeliveryInstrumentation({recordInputs:n,stateStore:e.stateStore}),onStepMetadata=e=>{let t=o.get(e.scope);if(t===void 0)return;let n=readGatewayCost(e.providerMetadata);if(n!==void 0)for(let[e,r]of Object.entries(n))t.span.setAttribute(e,r)};return{hook:{events:{...p,...l,...u.events,"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,...c.events,"turn.cancelled":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted},name:`eve.otel`,projectEvent,tracePolicy:()=>({emit:!0,recordInputs:n,recordOutputs:r})},prepareSessionTrace:d,prepareTurnTrace:f,async runInContext(o,s){if(o.type===`memory.operation`)return u.runInContext(o,s);let l=a.get(o.scope.attemptId)??o.scope,d=i.get(l),f=o.type===`model.call`?d?.get(o.idempotencyKey):c.contextFor(o.scope.attemptId,o.idempotencyKey);if(f===void 0){let t=await e.stateStore.getTurn(o.scope.sessionId,o.scope.turnId);t!==void 0&&(f=withChannelAudience(contextFromSpanContext(t.context),o.scope.channelAudience),isSampledTrace(t.context)||(f=suppressTracing(f)))}let p=await e.stateStore.getSession(o.scope.sessionId),m=resolveForwardedTraceSeed(contextStorage.getStore()?.get(SessionTraceSeedKey)),h=m?.decision??p?.decision,g=h===void 0?void 0:applyLiveDeliveryAudienceCeiling(h,normalizeChannelAudience(o.scope.channelAudience),m?.forwardedTracePolicy,t),_={recordInputs:n&&g?.action===`record`&&g.recordInputs,recordOutputs:r&&g?.action===`record`&&g.recordOutputs},run=e=>{let t=e??f;if(t===void 0)return s();let n=withErrorContent(t,_.recordOutputs),r=o.type===`tool.call`?withAgentToolContentPolicy(n,_):n;return context.with(markAgentTraceContext(withOperationConversation(r,o.scope)),s)};return o.type===`tool.call`?c.runInContext({...o,input:_.recordInputs?o.input:void 0},run,_.recordOutputs):run(void 0)}};function getExecutionContexts(e){let t=i.get(e);return t===void 0&&(t=new Map,i.set(e,t)),t}function drainOpenSpans(e){for(let t of s.get(e.scope)?.values()??[])e.type===`step.attempt.failed`&&recordAgentSpanError(t.span,e.error),t.span.end();s.delete(e.scope)}}function agentActivationLinks(e){let t=[];return e.caller?.isRemote===!0&&t.push({context:e.caller,attributes:{"eve.link.type":`agent.dispatch`}}),e.channelDelivery?.requestTraceContext!==void 0&&t.push({context:e.channelDelivery.requestTraceContext,attributes:{"eve.link.type":`channel.request`}}),t.length===0?void 0:t}function sessionIdForEvent(e){return`scope`in e?e.scope.sessionId:e.sessionId}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)}function getSpanStates(e,t){let n=e.get(t);return n===void 0&&(n=new Map,e.set(t,n)),n}function takeSpanState(e,t,n){let r=e.get(t),i=r?.get(n);if(r!==void 0)return r.delete(n),r.size===0&&e.delete(t),i}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}const errorText=e=>e instanceof Error?e.message:e;export{createAgentOtelInstrumentation};

package/dist/src/tracing/agent-otel-usage.d.ts

@@ -3,7 +3,7 @@ import type { InstrumentationUsage } from "#instrumentation/lifecycle.js";
 import type { AgentTurnTraceState } from "#tracing/agent-trace-state.js";
 /** Applies eve's structural token usage attributes to an agent span. */
 export declare function setAgentUsage(span: Span, usage: InstrumentationUsage): void;
-/** Applies standard GenAI token usage while retaining eve's compatibility attributes. */
+/** Applies standard GenAI token usage and retains eve's cost attribute. */
 export declare function setGenAiUsage(span: Span, usage: InstrumentationUsage): void;
 export declare function setAgentInvocationUsage(span: Span, modelUsage: AgentTurnTraceState["modelUsage"]): void;
 /** Projects Vercel AI Gateway cost metadata onto GenAI span attributes. */

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

@@ -1 +1 @@
-import{AGENT_USAGE_ATTRIBUTES}from"#tracing/agent-span-contract.js";function setAgentUsage(e,t){t.costUsd!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.costUsd,t.costUsd),t.inputTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.inputTokens,t.inputTokens),t.outputTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.outputTokens,t.outputTokens);let n=t.inputTokenDetails;n?.cacheReadTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.cacheReadTokens,n.cacheReadTokens),n?.cacheWriteTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.cacheWriteTokens,n.cacheWriteTokens)}function setGenAiUsage(e,t){setAgentUsage(e,t),t.inputTokens!==void 0&&e.setAttribute(`gen_ai.usage.input_tokens`,t.inputTokens),t.outputTokens!==void 0&&e.setAttribute(`gen_ai.usage.output_tokens`,t.outputTokens);let n=t.inputTokenDetails;n?.cacheReadTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_read.input_tokens`,n.cacheReadTokens),n?.cacheWriteTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_write.input_tokens`,n.cacheWriteTokens)}function setAgentInvocationUsage(e,t){t!==void 0&&setGenAiUsage(e,t)}function readGatewayCost(e){let t=e.gateway;if(!isRecord(t))return;let n={},r=readUsd(t.cost);r!==void 0&&(n[`gen_ai.usage.cost`]=r);let i=readUsd(t.gatewayCost);i!==void 0&&(n[`gen_ai.usage.gateway_cost`]=i);let a=readUsd(t.inputInferenceCost);a!==void 0&&(n[`gen_ai.usage.input_cost`]=a);let o=readUsd(t.outputInferenceCost);return o!==void 0&&(n[`gen_ai.usage.output_cost`]=o),typeof t.generationId==`string`&&t.generationId.length>0&&(n[`gen_ai.generation.id`]=t.generationId),Object.keys(n).length===0?void 0:n}function readUsd(e){if(typeof e!=`string`)return;let t=Number(e);return Number.isFinite(t)?t:void 0}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{readGatewayCost,setAgentInvocationUsage,setAgentUsage,setGenAiUsage};
+import{AGENT_USAGE_ATTRIBUTES}from"#tracing/agent-span-contract.js";function setAgentUsage(e,t){t.costUsd!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.costUsd,t.costUsd),t.inputTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.inputTokens,t.inputTokens),t.outputTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.outputTokens,t.outputTokens);let n=t.inputTokenDetails;n?.cacheReadTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.cacheReadTokens,n.cacheReadTokens),n?.cacheWriteTokens!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.cacheWriteTokens,n.cacheWriteTokens)}function setGenAiUsage(e,t){t.costUsd!==void 0&&e.setAttribute(AGENT_USAGE_ATTRIBUTES.costUsd,t.costUsd),t.inputTokens!==void 0&&e.setAttribute(`gen_ai.usage.input_tokens`,t.inputTokens),t.outputTokens!==void 0&&e.setAttribute(`gen_ai.usage.output_tokens`,t.outputTokens);let n=t.inputTokenDetails;n?.cacheReadTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_read.input_tokens`,n.cacheReadTokens),n?.cacheWriteTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_write.input_tokens`,n.cacheWriteTokens)}function setAgentInvocationUsage(e,t){t!==void 0&&setGenAiUsage(e,t)}function readGatewayCost(e){let t=e.gateway;if(!isRecord(t))return;let n={},r=readUsd(t.cost);r!==void 0&&(n[`gen_ai.usage.cost`]=r);let i=readUsd(t.gatewayCost);i!==void 0&&(n[`gen_ai.usage.gateway_cost`]=i);let a=readUsd(t.inputInferenceCost);a!==void 0&&(n[`gen_ai.usage.input_cost`]=a);let o=readUsd(t.outputInferenceCost);return o!==void 0&&(n[`gen_ai.usage.output_cost`]=o),typeof t.generationId==`string`&&t.generationId.length>0&&(n[`gen_ai.generation.id`]=t.generationId),Object.keys(n).length===0?void 0:n}function readUsd(e){if(typeof e!=`string`)return;let t=Number(e);return Number.isFinite(t)?t:void 0}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{readGatewayCost,setAgentInvocationUsage,setAgentUsage,setGenAiUsage};

package/dist/src/tracing/agent-span-contract.d.ts

@@ -1,6 +1,5 @@
 export declare const AGENT_TRACE_SCHEMA_VERSION = 4;
 export declare const AGENT_SPAN_NAMES: {
-    readonly action: "agent.action";
     readonly approval: "agent.approval";
     readonly channelRequest: "agent.channel.request";
     readonly step: "agent.step";
@@ -22,6 +21,14 @@ interface AgentSpanRecord {
     readonly name: string;
     readonly attributes: Readonly<Record<string, unknown>>;
 }
+/** Marks the `execute_tool` span of a tool call made outside any conversation. */
+export declare const DIRECT_TOOL_CALL_ATTRIBUTE = "eve.tool.invocation";
+export declare const DIRECT_TOOL_CALL_VALUE = "direct";
+/**
+ * A direct tool call has no turn, so its own span is what starts and ends
+ * its claim on the trace, the way an activation span does for a turn.
+ */
+export declare function isDirectToolCallSpan(span: Pick<AgentSpanRecord, "attributes">): boolean;
 export declare function isAgentActivationSpan(span: AgentSpanRecord): boolean;
 export declare function agentTurnIdentity(span: AgentSpanRecord): string | undefined;
 export {};

package/dist/src/tracing/agent-span-contract.js

@@ -1 +1 @@
-const AGENT_TRACE_SCHEMA_VERSION=4,AGENT_SPAN_NAMES={action:`agent.action`,approval:`agent.approval`,channelRequest:`agent.channel.request`,step:`agent.step`},AGENT_USAGE_ATTRIBUTES={costUsd:`agent.usage.cost_usd`,inputTokens:`agent.usage.input_tokens`,outputTokens:`agent.usage.output_tokens`,cacheReadTokens:`agent.usage.cache_read_tokens`,cacheWriteTokens:`agent.usage.cache_write_tokens`};function agentInvocationSpanName(e){return e===void 0?`invoke_agent`:`invoke_agent ${e}`}function modelSpanName(e){return`chat ${e}`}function isAgentActivationSpan(e){return e.name===`agent.turn`||e.attributes[`gen_ai.operation.name`]===`invoke_agent`&&e.attributes[`agent.invocation.role`]!==`caller`&&typeof e.attributes[`agent.turn.id`]==`string`}function agentTurnIdentity(e){let t=e.attributes[`agent.run.id`],n=e.attributes[`agent.turn.id`];return typeof n==`string`?`${typeof t==`string`?t:``}\0${n}`:void 0}export{AGENT_SPAN_NAMES,AGENT_TRACE_SCHEMA_VERSION,AGENT_USAGE_ATTRIBUTES,agentInvocationSpanName,agentTurnIdentity,isAgentActivationSpan,modelSpanName};
+const AGENT_TRACE_SCHEMA_VERSION=4,AGENT_SPAN_NAMES={approval:`agent.approval`,channelRequest:`agent.channel.request`,step:`agent.step`},AGENT_USAGE_ATTRIBUTES={costUsd:`agent.usage.cost_usd`,inputTokens:`agent.usage.input_tokens`,outputTokens:`agent.usage.output_tokens`,cacheReadTokens:`agent.usage.cache_read_tokens`,cacheWriteTokens:`agent.usage.cache_write_tokens`};function agentInvocationSpanName(e){return e===void 0?`invoke_agent`:`invoke_agent ${e}`}function modelSpanName(e){return`chat ${e}`}const DIRECT_TOOL_CALL_ATTRIBUTE=`eve.tool.invocation`,DIRECT_TOOL_CALL_VALUE=`direct`;function isDirectToolCallSpan(e){return e.attributes[DIRECT_TOOL_CALL_ATTRIBUTE]===DIRECT_TOOL_CALL_VALUE}function isAgentActivationSpan(e){return e.name===`agent.turn`||e.attributes[`gen_ai.operation.name`]===`invoke_agent`&&e.attributes[`agent.invocation.role`]!==`caller`&&typeof e.attributes[`agent.turn.id`]==`string`}function agentTurnIdentity(e){let t=e.attributes[`agent.run.id`],n=e.attributes[`agent.turn.id`];return typeof n==`string`?`${typeof t==`string`?t:``}\0${n}`:void 0}export{AGENT_SPAN_NAMES,AGENT_TRACE_SCHEMA_VERSION,AGENT_USAGE_ATTRIBUTES,DIRECT_TOOL_CALL_ATTRIBUTE,DIRECT_TOOL_CALL_VALUE,agentInvocationSpanName,agentTurnIdentity,isAgentActivationSpan,isDirectToolCallSpan,modelSpanName};

package/dist/src/tracing/agent-tool-instrumentation.d.ts

@@ -1,9 +1,15 @@
 import { type Context, type SpanContext, type Tracer } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationActionStartedEvent, InstrumentationToolCallStartedEvent, InstrumentationToolCallTerminalEvent } from "#instrumentation/lifecycle.js";
+import type { InstrumentationAttemptScope, InstrumentationExecutionOperation, InstrumentationToolCallStartedEvent, InstrumentationToolCallTerminalEvent } from "#instrumentation/lifecycle.js";
 import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
-import type { AgentActionContext } from "#tracing/agent-action-instrumentation.js";
+import type { AgentTraceStateStore } from "#tracing/agent-trace-state.js";
+export interface AgentToolContext {
+    readonly context: Context;
+    readonly spanContext: SpanContext;
+}
 interface AgentToolInstrumentation {
-    actionStarted(event: InstrumentationActionStartedEvent): Promise<void>;
+    deleteForSession(sessionId: string): Promise<void>;
+    failForAttempt(scope: InstrumentationAttemptScope, error: unknown): Promise<void>;
+    dispatchContextFor(sessionId: string, turnId: string, callId: string): Promise<AgentToolContext | undefined>;
     contextFor(attemptId: string, idempotencyKey: string): Context | undefined;
     drain(attemptId: string, failure?: {
         readonly error: unknown;
@@ -13,10 +19,14 @@ interface AgentToolInstrumentation {
         readonly "tool.call.failed": (event: InstrumentationToolCallTerminalEvent) => Promise<void>;
         readonly "tool.call.started": (event: InstrumentationToolCallStartedEvent) => Promise<void>;
     };
+    runInContext<T>(operation: Extract<InstrumentationExecutionOperation, {
+        type: "tool.call";
+    }>, execute: (parent: Context | undefined) => PromiseLike<T>, recordOutputs: boolean): Promise<T>;
 }
-/** Keeps SDK tool spans parented to actions even when SDK telemetry wins the event race. */
+/** Enriches durable tool calls, exporting SDK-only calls under their step. */
 export declare function createAgentToolInstrumentation(input: {
-    readonly actionContextFor: (sessionId: string, turnId: string, callId: string) => Promise<AgentActionContext | undefined>;
+    readonly frameworkVersion: string;
+    readonly resolveTraceContext: (event: InstrumentationToolCallStartedEvent) => SpanContext | undefined | PromiseLike<SpanContext | undefined>;
     readonly idGenerator: AgentSpanIdGenerator;
     readonly recordInputs: boolean;
     readonly recordOutputs: boolean;
@@ -25,5 +35,6 @@ export declare function createAgentToolInstrumentation(input: {
         readonly spanContext: SpanContext;
     } | undefined;
     readonly tracer: Tracer;
+    readonly stateStore: AgentTraceStateStore;
 }): AgentToolInstrumentation;
 export {};

package/dist/src/tracing/agent-tool-instrumentation.js

@@ -1 +1 @@
-import{ROOT_CONTEXT,SpanKind,trace}from"#compiled/@opentelemetry/api/index.js";import{actionIdempotencyKey}from"#instrumentation/lifecycle.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{withAgentToolSpanContext}from"#tracing/agent-tool-span-context.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";function createAgentToolInstrumentation(e){let t=new Map,n=new Map,onStarted=async t=>{let n=actionIdempotencyKey(t.scope.sessionId,t.scope.turnId,t.callId),r=e.resolveFallback(t),i=r===void 0?void 0:reserve(t,n,r),a=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.callId);if(i===void 0){if(a===void 0)return;i=reserve(t,n,a)}a!==void 0&&startSpan(i,a.context)},onTerminal=async t=>{let r=n.get(t.scope.attemptId)?.get(t.idempotencyKey);if(r!==void 0){if(r.terminal=t,r.span===void 0){let t=await e.actionContextFor(r.event.scope.sessionId,r.event.scope.turnId,r.event.callId);t!==void 0&&startSpan(r,t.context)}finishIfReady(r)}};return{async actionStarted(n){let r=t.get(n.idempotencyKey);if(r===void 0||r.span!==void 0||r.finished===!0)return;let i=await e.actionContextFor(n.scope.sessionId,n.scope.turnId,n.callId);i!==void 0&&(startSpan(r,i.context),finishIfReady(r))},contextFor:(e,t)=>n.get(e)?.get(t)?.context,drain(e,t){let r=n.get(e);if(r!==void 0){for(let e of r.values())e.finished!==!0&&(e.span===void 0&&startSpan(e,e.fallbackParent),finish(e,t));n.delete(e)}},events:{"tool.call.completed":onTerminal,"tool.call.failed":onTerminal,"tool.call.started":onStarted}};function getAttemptStates(e){let t=n.get(e);return t===void 0&&(t=new Map,n.set(e,t)),t}function reserve(n,r,i){let a=e.idGenerator.deriveSpanId(`tool:${n.idempotencyKey}`),o={actionKey:r,attemptId:n.scope.attemptId,additionalAttributes:{},context:withChannelAudience(contextFromSpanContext({isRemote:!1,spanId:a,traceFlags:i.spanContext.traceFlags,traceId:i.spanContext.traceId}),n.scope.channelAudience),event:n,fallbackParent:i.context,idempotencyKey:n.idempotencyKey,spanId:a,startTimeMs:Date.now()};return o.context=withAgentToolSpanContext(o.context,{recordInputs:e.recordInputs,recordOutputs:e.recordOutputs,setAttributes(e){if(Object.assign(o.additionalAttributes,e),o.span!==void 0)for(let[t,n]of Object.entries(e))n!==void 0&&o.span.setAttribute(t,n)},recordError(e,t){o.pendingError={error:e,errorType:t},o.span!==void 0&&recordAgentSpanError(o.span,e,t)}}),getAttemptStates(n.scope.attemptId).set(n.idempotencyKey,o),t.set(r,o),o}function startSpan(t,n){if(t.span===void 0&&t.finished!==!0&&(t.span=e.idGenerator.withSpanId(t.spanId,()=>e.tracer.startSpan(`execute_tool ${t.event.toolName}`,{attributes:{...toolAttributes(t.event),...t.additionalAttributes},kind:SpanKind.INTERNAL,startTime:t.startTimeMs},n)),t.pendingError!==void 0&&recordAgentSpanError(t.span,t.pendingError.error,t.pendingError.errorType),e.recordInputs)){let e=contentAttribute(t.event.input);e!==void 0&&t.span.setAttribute(`gen_ai.tool.call.arguments`,e)}}function finishIfReady(e){e.span!==void 0&&e.terminal!==void 0&&finish(e)}function finish(r,i){let a=r.span;if(a===void 0||r.finished===!0)return;r.finished=!0;let o=r.terminal;if(o?.type===`tool.call.completed`&&o.durationMs!==void 0&&a.setAttribute(`gen_ai.execute_tool.duration`,o.durationMs/1e3),i!==void 0)recordAgentSpanError(a,i.error);else if(o?.type===`tool.call.failed`)recordAgentSpanError(a,o.error);else if(o?.output.type===`error`)recordAgentSpanError(a,o.output.error);else if(o!==void 0&&e.recordOutputs){let e=contentAttribute(o.output.output);e!==void 0&&a.setAttribute(`gen_ai.tool.call.result`,e)}a.end(),t.delete(r.actionKey);let s=n.get(r.attemptId);s?.delete(r.idempotencyKey),s?.size===0&&n.delete(r.attemptId)}}function toolAttributes(e){return{...e.scope.functionId===void 0?{}:{"gen_ai.agent.name":e.scope.functionId},"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":e.callId,"gen_ai.tool.name":e.toolName,"gen_ai.tool.type":`function`,...agentSpanNamingAttributes(`execute_tool ${e.toolName}`,`execute_tool`),...agentTraceIdentityAttributes({rootSessionId:e.scope.rootSessionId??e.scope.sessionId,traceSessionId:traceSessionIdOf(e.scope),sessionId:e.scope.sessionId})}}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}export{createAgentToolInstrumentation};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{isSampledTrace}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,trace}from"#compiled/@opentelemetry/api/index.js";import{actionIdempotencyKey,attemptIdempotencyKey}from"#instrumentation/lifecycle.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute,textContentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{withAgentToolSpanContext}from"#tracing/agent-tool-span-context.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{setAgentUsage}from"#tracing/agent-otel-usage.js";function createAgentToolInstrumentation(e){let t=new Map,n=new Map,r=new Map;async function dispatchContextFor(t,n,r){let i=await e.stateStore.getAction(actionIdempotencyKey(t,n,r))??await e.stateStore.findAction(t,r);if(i===void 0)return;let a={isRemote:!1,spanId:i.spanId,traceFlags:i.parent.traceFlags,traceId:i.parent.traceId};return{context:withChannelAudience(contextFromSpanContext(a),i.channelAudience),spanContext:a}}async function onDispatchStarted(n){let i=await e.resolveTraceContext(n);if(i===void 0||!isSampledTrace(i))return;let a=await e.stateStore.getAction(n.idempotencyKey)??{attemptIndex:n.scope.attemptIndex,callId:n.callId,channelAudience:normalizeChannelAudience(n.scope.channelAudience),inputAttribute:e.recordInputs?contentAttribute(n.input):void 0,kind:n.kind??`tool-call`,name:n.toolName,toolAttributes:{"agent.tool.is_framework":n.frameworkTool===!0},parent:{spanId:e.idGenerator.deriveSpanId(n.parentCallId===void 0?attemptIdempotencyKey(n.scope):`action:${actionIdempotencyKey(n.scope.sessionId,n.scope.turnId,n.parentCallId)}`),traceFlags:i.traceFlags,traceId:i.traceId},parentCallId:n.parentCallId,rootSessionId:n.scope.rootSessionId??n.scope.sessionId,traceSessionId:traceSessionIdOf(n.scope),sessionId:n.scope.sessionId,spanId:e.idGenerator.deriveSpanId(`action:${n.idempotencyKey}`),startTimeMs:Math.min(n.startedAtMs??Date.now(),t.get(n.idempotencyKey)?.startTimeMs??1/0),stepIndex:n.scope.stepIndex,turnId:n.scope.turnId};await e.stateStore.setAction(n.idempotencyKey,a),n.isWorkflowTool===!0&&await e.stateStore.setActionAnchor(n.idempotencyKey,a);let o=r.get(n.scope.attemptId)??new Set;o.add(n.idempotencyKey),r.set(n.scope.attemptId,o);let s=t.get(n.idempotencyKey);s!==void 0&&s.finished!==!0&&(await correlate(s),finishIfReady(s))}async function onDispatchTerminal(t){let n=await e.stateStore.getAction(t.idempotencyKey);if(n!==void 0)try{let r=startDispatchSpan(n),i=t.outcome??(t.type===`tool.call.failed`?`failed`:`completed`);if(r.setAttribute(`agent.action.outcome`,n.toolFailed===!0&&i===`completed`?`failed`:i),t.usage!==void 0&&setAgentUsage(r,t.usage),t.type===`tool.call.failed`)recordToolError(r,t.error,t.errorCode);else if(t.output.type===`error`)recordToolError(r,t.output.error);else if(n.toolFailed===!0)recordToolError(r,n.toolErrorAttribute,typeof n.toolAttributes?.[`error.type`]==`string`?n.toolAttributes[`error.type`]:void 0);else if(e.recordOutputs){let e=contentAttribute(t.output.output);e!==void 0&&r.setAttribute(`gen_ai.tool.call.result`,e)}r.end(t.acceptedAtMs??n.toolEndTimeMs)}finally{await e.stateStore.deleteAction(t.idempotencyKey);for(let[e,n]of r)n.delete(t.idempotencyKey),n.size===0&&r.delete(e)}}function startDispatchSpan(t){let n=t.kind===`subagent-call`||t.kind===`remote-agent-call`,r=e.idGenerator.withSpanId(t.spanId,()=>e.tracer.startSpan(`execute_tool ${t.name}`,{attributes:{"agent.action.kind":t.kind,"agent.action.name":t.name,...t.parentCallId===void 0?void 0:{"agent.action.parent_call_id":t.parentCallId},"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":t.callId,"gen_ai.tool.name":t.name,"gen_ai.tool.type":`function`,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":t.attemptIndex,"agent.step.index":t.stepIndex,"agent.turn.id":t.turnId,...agentSpanNamingAttributes(`execute_tool ${t.name}`,`execute_tool`),...agentTraceIdentityAttributes({rootSessionId:t.rootSessionId,traceSessionId:t.traceSessionId,sessionId:t.sessionId}),...n?{"gen_ai.agent.name":t.name,"agent.invocation.role":`caller`}:void 0,...t.toolAttributes},kind:t.kind===`remote-agent-call`?SpanKind.CLIENT:SpanKind.INTERNAL,startTime:t.startTimeMs},withChannelAudience(contextFromSpanContext({...t.parent,isRemote:!1}),t.channelAudience)));return t.inputAttribute!==void 0&&r.setAttribute(`gen_ai.tool.call.arguments`,t.inputAttribute),r}let onStarted=async t=>{if(n.get(t.scope.attemptId)?.has(t.idempotencyKey))return;let r=actionIdempotencyKey(t.scope.sessionId,t.scope.turnId,t.callId),i=e.resolveFallback(t),a=i===void 0?void 0:reserve(t,r,i),o=await dispatchContextFor(t.scope.sessionId,t.scope.turnId,t.callId);if(a===void 0){if(o===void 0)return;a=reserve(t,r,o)}o!==void 0&&await correlate(a)},onTerminal=async e=>{let t=n.get(e.scope.attemptId)?.get(e.idempotencyKey);t!==void 0&&(t.terminal=e,t.span===void 0&&await dispatchContextFor(t.event.scope.sessionId,t.event.scope.turnId,t.event.callId)!==void 0&&await correlate(t),finishIfReady(t))};return{dispatchContextFor,async deleteForSession(t){await e.stateStore.deleteActions(t),await e.stateStore.deleteActionAnchors(t)},async failForAttempt(t,n){let i=r.get(t.attemptId);r.delete(t.attemptId);for(let t of i??[]){let r=await e.stateStore.getAction(t);if(r===void 0)continue;let i=startDispatchSpan(r);recordAgentSpanError(i,n),i.end(),await e.stateStore.deleteAction(t)}},contextFor:(e,t)=>n.get(e)?.get(t)?.context,drain(e,t){let r=n.get(e);if(r!==void 0){for(let e of r.values())e.finished!==!0&&(e.span===void 0&&e.correlated!==!0&&startSpan(e,e.fallbackParent),finish(e,t));n.delete(e)}},events:{"tool.call.completed":onDispatchTerminal,"tool.call.failed":onDispatchTerminal,"tool.call.started":onDispatchStarted},async runInContext(e,t,r){if(e.callId===void 0||e.toolName===void 0)return t(n.get(e.scope.attemptId)?.get(e.idempotencyKey)?.context);await onStarted({...e,callId:e.callId,toolName:e.toolName,input:e.input,type:`tool.call.started`});let i=n.get(e.scope.attemptId)?.get(e.idempotencyKey),a=e.startedAtMs??Date.now();try{let n=await t(i?.context);return await onTerminal({type:e.failed?`tool.call.failed`:`tool.call.completed`,idempotencyKey:e.idempotencyKey,scope:e.scope,completedAtMs:e.completedAtMs??Date.now(),durationMs:(e.completedAtMs??Date.now())-a,output:{type:`result`,output:r?n:void 0}}),n}catch(t){throw await onTerminal({type:`tool.call.failed`,idempotencyKey:e.idempotencyKey,scope:e.scope,completedAtMs:Date.now(),error:r?t:void 0}),t}}};function getAttemptStates(e){let t=n.get(e);return t===void 0&&(t=new Map,n.set(e,t)),t}function reserve(n,r,i){let a=e.idGenerator.deriveSpanId(`action:${r}`),o={actionKey:r,attemptId:n.scope.attemptId,additionalAttributes:{},context:withChannelAudience(contextFromSpanContext({isRemote:!1,spanId:a,traceFlags:i.spanContext.traceFlags,traceId:i.spanContext.traceId}),n.scope.channelAudience),event:n,fallbackParent:i.context,idempotencyKey:n.idempotencyKey,spanId:a,startTimeMs:n.startedAtMs??Date.now()};return o.context=withAgentToolSpanContext(o.context,{recordInputs:e.recordInputs,recordOutputs:e.recordOutputs,setAttributes(e){if(Object.assign(o.additionalAttributes,e),o.span!==void 0)for(let[t,n]of Object.entries(e))n!==void 0&&o.span.setAttribute(t,n)},recordError(e,t){o.pendingError={error:e,errorType:t},o.span!==void 0&&recordAgentSpanError(o.span,e,t)}}),getAttemptStates(n.scope.attemptId).set(n.idempotencyKey,o),t.set(r,o),o}function startSpan(t,n){if(t.span===void 0&&t.finished!==!0&&(t.span=e.idGenerator.withSpanId(t.spanId,()=>e.tracer.startSpan(`execute_tool ${t.event.toolName}`,{attributes:{...toolAttributes(t.event),...t.additionalAttributes},kind:SpanKind.INTERNAL,startTime:t.startTimeMs},n)),t.pendingError!==void 0&&recordAgentSpanError(t.span,t.pendingError.error,t.pendingError.errorType),e.recordInputs)){let e=contentAttribute(t.event.input);e!==void 0&&t.span.setAttribute(`gen_ai.tool.call.arguments`,e)}}function finishIfReady(e){e.span===void 0&&e.correlated!==!0||e.terminal===void 0||finish(e)}async function correlate(t){let n=await e.stateStore.getAction(t.actionKey)??await e.stateStore.findAction(t.event.scope.sessionId,t.event.callId);if(n===void 0)return;t.correlated=!0,t.context=trace.setSpan(t.context,trace.wrapSpanContext({isRemote:!1,spanId:n.spanId,traceFlags:n.parent.traceFlags,traceId:n.parent.traceId}));let r=t.terminal,i=t.pendingError!==void 0||r?.type===`tool.call.failed`||r?.output.type===`error`,a=t.pendingError?.error??(r?.type===`tool.call.failed`?r.error:r?.output.type===`error`?r.output.error:void 0),o={...n.toolAttributes,...t.event.scope.functionId===void 0||n.kind===`subagent-call`||n.kind===`remote-agent-call`?void 0:{"gen_ai.agent.name":t.event.scope.functionId},"agent.tool.is_framework":t.event.frameworkTool===!0,...t.additionalAttributes,...t.pendingError?.errorType===void 0?void 0:{"error.type":t.pendingError.errorType},...r?.type===`tool.call.completed`&&r.durationMs!==void 0?{"gen_ai.execute_tool.duration":r.durationMs/1e3}:void 0};await e.stateStore.setAction(actionIdempotencyKey(n.sessionId,n.turnId,n.callId),{...n,startTimeMs:Math.min(n.startTimeMs,t.startTimeMs),toolAttributes:o,toolEndTimeMs:r?.completedAtMs??n.toolEndTimeMs,toolFailed:i||n.toolFailed,toolErrorAttribute:e.recordOutputs&&a!==void 0?contentAttribute(a instanceof Error?a.message:a):n.toolErrorAttribute})}function finish(t,n){let r=t.span;if(t.finished===!0)return;if(t.correlated===!0){t.finished=!0,forget(t);return}if(r===void 0)return;t.finished=!0;let i=t.terminal;if(i?.type===`tool.call.completed`&&i.durationMs!==void 0&&r.setAttribute(`gen_ai.execute_tool.duration`,i.durationMs/1e3),n!==void 0)recordAgentSpanError(r,n.error);else if(i?.type===`tool.call.failed`)recordAgentSpanError(r,i.error);else if(i?.output.type===`error`)recordAgentSpanError(r,i.output.error);else if(i!==void 0&&e.recordOutputs){let e=contentAttribute(i.output.output);e!==void 0&&r.setAttribute(`gen_ai.tool.call.result`,e)}r.end(i?.completedAtMs),forget(t)}function forget(e){t.delete(e.actionKey);let r=n.get(e.attemptId);r?.delete(e.idempotencyKey),r?.size===0&&n.delete(e.attemptId)}}function toolAttributes(e){return{"agent.tool.is_framework":e.frameworkTool===!0,...e.scope.functionId===void 0?{}:{"gen_ai.agent.name":e.scope.functionId},"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":e.callId,"gen_ai.tool.name":e.toolName,"gen_ai.tool.type":`function`,...agentSpanNamingAttributes(`execute_tool ${e.toolName}`,`execute_tool`),...agentTraceIdentityAttributes({rootSessionId:e.scope.rootSessionId??e.scope.sessionId,traceSessionId:traceSessionIdOf(e.scope),sessionId:e.scope.sessionId})}}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}function recordToolError(e,t,n){if(t instanceof Error||t===void 0){recordAgentSpanError(e,t,n);return}let r=typeof t==`string`?textContentAttribute(t):contentAttribute(t),i=typeof t==`object`&&t&&!Array.isArray(t)?Reflect.get(t,`message`):void 0,a=typeof i==`string`?textContentAttribute(r===void 0?i:`${i}\n${r}`):r,o=a===void 0?void 0:Error(a);o!==void 0&&n!==void 0&&(o.name=n),recordAgentSpanError(e,o,n)}export{createAgentToolInstrumentation};

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

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{isInstrumentationPrincipalType}from"#instrumentation/lifecycle.js";import{boundedPrincipalId}from"#tracing/telemetry-budget.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{boundedTraceError}from"#tracing/bounded-error.js";const AGENT_TRACE_CONTEXT_KEY=`eve.harness.agentTrace`;function decodeTraceSessionId(e){return typeof e.traceSessionId==`string`?e.traceSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``}function emptyAgentTraceContextState(){return{actionAnchors:{},actions:{},sessions:{},turns:{}}}function serializeAgentTraceContextState(e){return{actionAnchors:e.actionAnchors,actions:e.actions,sessions:Object.fromEntries(Object.entries(e.sessions).map(([e,t])=>[e,{...t,context:serializeSpanContext(t.context)}])),turns:Object.fromEntries(Object.entries(e.turns).map(([e,t])=>[e,{...t,caller:t.caller===void 0?void 0:serializeSpanContext(t.caller),channelDelivery:t.channelDelivery===void 0?void 0:{...t.channelDelivery,requestTraceContext:t.channelDelivery.requestTraceContext===void 0?void 0:serializeSpanContext(t.channelDelivery.requestTraceContext)},context:serializeSpanContext(t.context),terminal:t.terminal===void 0?void 0:t.terminal.type===`turn.failed`?{error:serializeError(t.terminal.error),type:t.terminal.type}:{type:t.terminal.type}}]))}}function deserializeAgentTraceContextState(e){return isRecord(e)?{actionAnchors:deserializeRecord(e.actionAnchors,deserializeAction),actions:deserializeRecord(e.actions,deserializeAction),sessions:deserializeRecord(e.sessions,deserializeSession),turns:deserializeRecord(e.turns,deserializeTurn)}:emptyAgentTraceContextState()}function deserializeSession(e){if(isRecord(e)&&isSpanContext(e.context))return{agentName:typeof e.agentName==`string`?e.agentName:void 0,channelAudience:normalizeChannelAudience(e.channelAudience),channelKind:typeof e.channelKind==`string`?e.channelKind:void 0,channelType:typeof e.channelType==`string`?e.channelType:void 0,context:e.context,decision:readInstrumentationDecision(e.decision),parentLineage:deserializeParentLineage(e.parentLineage),rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,traceSessionId:decodeTraceSessionId(e),scheduleId:typeof e.scheduleId==`string`?e.scheduleId:void 0,title:typeof e.title==`string`?e.title:void 0}}function deserializeTurn(e){if(isRecord(e)&&isSpanContext(e.context)&&typeof e.startTimeMs==`number`)return{caller:isSpanContext(e.caller)?e.caller:void 0,channelDelivery:deserializeTurnChannelDelivery(e.channelDelivery),context:e.context,currentPrincipal:deserializePrincipalSummary(e.currentPrincipal),initiatorPrincipal:deserializePrincipalSummary(e.initiatorPrincipal),modelUsage:deserializeModelUsage(e.modelUsage),parentLineage:deserializeParentLineage(e.parentLineage),rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,traceSessionId:decodeTraceSessionId(e),sequence:typeof e.sequence==`number`?e.sequence:0,startTimeMs:e.startTimeMs,subagentName:typeof e.subagentName==`string`?e.subagentName:void 0,terminal:deserializeTurnTerminal(e.terminal)}}function deserializeTurnChannelDelivery(e){if(isRecord(e)&&typeof e.channelKind==`string`&&typeof e.channelName==`string`&&typeof e.deliveryId==`string`)return{channelKind:e.channelKind,channelName:e.channelName,deliveryId:e.deliveryId,inputAttribute:typeof e.inputAttribute==`string`?e.inputAttribute:void 0,requestId:typeof e.requestId==`string`?e.requestId:void 0,requestTraceContext:isSpanContext(e.requestTraceContext)?e.requestTraceContext:void 0}}function deserializePrincipalSummary(e){if(!isRecord(e)||!isInstrumentationPrincipalType(e.type))return;let t=e.type===`none`?void 0:boundedPrincipalId(e.id);return t===void 0?{type:e.type}:{id:t,type:e.type}}function deserializeAction(e){if(isRecord(e)&&typeof e.attemptIndex==`number`&&typeof e.callId==`string`&&isActionKind(e.kind)&&typeof e.name==`string`&&isSpanContext(e.parent)&&typeof e.rootSessionId==`string`&&typeof e.sessionId==`string`&&typeof e.spanId==`string`&&typeof e.startTimeMs==`number`&&typeof e.stepIndex==`number`&&typeof e.turnId==`string`)return{attemptIndex:e.attemptIndex,callId:e.callId,channelAudience:normalizeChannelAudience(e.channelAudience),inputAttribute:typeof e.inputAttribute==`string`?e.inputAttribute:void 0,kind:e.kind,name:e.name,parent:e.parent,rootSessionId:e.rootSessionId,traceSessionId:decodeTraceSessionId(e),sessionId:e.sessionId,spanId:e.spanId,startTimeMs:e.startTimeMs,stepIndex:e.stepIndex,turnId:e.turnId}}function deserializeModelUsage(e){if(!isRecord(e))return;let t=typeof e.inputTokens==`number`?e.inputTokens:void 0,n=typeof e.outputTokens==`number`?e.outputTokens:void 0;return t===void 0&&n===void 0?void 0:{inputTokens:t,outputTokens:n}}function deserializeParentLineage(e){if(isRecord(e)&&typeof e.callId==`string`&&typeof e.sessionId==`string`&&typeof e.turnId==`string`)return{callId:e.callId,sessionId:e.sessionId,subagentName:typeof e.subagentName==`string`?e.subagentName:void 0,turnId:e.turnId}}function deserializeTurnTerminal(e){if(isRecord(e)&&isTurnTerminalType(e.type))return e.type===`turn.failed`?{error:deserializeError(e.error),type:e.type}:{type:e.type}}function deserializeRecord(e,t){if(!isRecord(e))return{};let n={};for(let[r,i]of Object.entries(e)){let e=t(i);e!==void 0&&(n[r]=e)}return n}function serializeSpanContext(e){return{isRemote:e.isRemote,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function serializeError(e){if(!(e instanceof Error))return;let t=boundedTraceError(e);return{message:t.message,name:t.name,stack:t.stack}}function deserializeError(e){if(!isRecord(e)||typeof e.message!=`string`)return;let t=Error(e.message);return typeof e.name==`string`&&(t.name=e.name),typeof e.stack==`string`&&(t.stack=e.stack),t}function isActionKind(e){return e===`load-skill`||e===`remote-agent-call`||e===`subagent-call`||e===`tool-call`}function isTurnTerminalType(e){return e===`turn.cancelled`||e===`turn.completed`||e===`turn.failed`}function isSpanContext(e){return isRecord(e)&&typeof e.spanId==`string`&&typeof e.traceFlags==`number`&&typeof e.traceId==`string`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{AGENT_TRACE_CONTEXT_KEY,decodeTraceSessionId,deserializeAgentTraceContextState,emptyAgentTraceContextState,serializeAgentTraceContextState};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{isInstrumentationPrincipalType}from"#instrumentation/lifecycle.js";import{boundedPrincipalId}from"#tracing/telemetry-budget.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";import{boundedTraceError}from"#tracing/bounded-error.js";const AGENT_TRACE_CONTEXT_KEY=`eve.harness.agentTrace`;function decodeTraceSessionId(e){return typeof e.traceSessionId==`string`?e.traceSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``}function emptyAgentTraceContextState(){return{actionAnchors:{},actions:{},sessions:{},turns:{}}}function serializeAgentTraceContextState(e){return{actionAnchors:e.actionAnchors,actions:e.actions,sessions:Object.fromEntries(Object.entries(e.sessions).map(([e,t])=>[e,{...t,context:serializeSpanContext(t.context)}])),turns:Object.fromEntries(Object.entries(e.turns).map(([e,t])=>[e,{...t,caller:t.caller===void 0?void 0:serializeSpanContext(t.caller),channelDelivery:t.channelDelivery===void 0?void 0:{...t.channelDelivery,requestTraceContext:t.channelDelivery.requestTraceContext===void 0?void 0:serializeSpanContext(t.channelDelivery.requestTraceContext)},context:serializeSpanContext(t.context),terminal:t.terminal===void 0?void 0:t.terminal.type===`turn.failed`?{error:serializeError(t.terminal.error),type:t.terminal.type}:{type:t.terminal.type}}]))}}function deserializeAgentTraceContextState(e){return isRecord(e)?{actionAnchors:deserializeRecord(e.actionAnchors,deserializeAction),actions:deserializeRecord(e.actions,deserializeAction),sessions:deserializeRecord(e.sessions,deserializeSession),turns:deserializeRecord(e.turns,deserializeTurn)}:emptyAgentTraceContextState()}function deserializeSession(e){if(isRecord(e)&&isSpanContext(e.context))return{agentName:typeof e.agentName==`string`?e.agentName:void 0,channelAudience:normalizeChannelAudience(e.channelAudience),channelKind:typeof e.channelKind==`string`?e.channelKind:void 0,channelType:typeof e.channelType==`string`?e.channelType:void 0,context:e.context,decision:readInstrumentationDecision(e.decision),parentLineage:deserializeParentLineage(e.parentLineage),rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,traceSessionId:decodeTraceSessionId(e),scheduleId:typeof e.scheduleId==`string`?e.scheduleId:void 0,title:typeof e.title==`string`?e.title:void 0}}function deserializeTurn(e){if(isRecord(e)&&isSpanContext(e.context)&&typeof e.startTimeMs==`number`)return{caller:isSpanContext(e.caller)?e.caller:void 0,channelDelivery:deserializeTurnChannelDelivery(e.channelDelivery),context:e.context,currentPrincipal:deserializePrincipalSummary(e.currentPrincipal),initiatorPrincipal:deserializePrincipalSummary(e.initiatorPrincipal),modelUsage:deserializeModelUsage(e.modelUsage),parentLineage:deserializeParentLineage(e.parentLineage),rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,traceSessionId:decodeTraceSessionId(e),sequence:typeof e.sequence==`number`?e.sequence:0,startTimeMs:e.startTimeMs,subagentName:typeof e.subagentName==`string`?e.subagentName:void 0,terminal:deserializeTurnTerminal(e.terminal)}}function deserializeTurnChannelDelivery(e){if(isRecord(e)&&typeof e.channelKind==`string`&&typeof e.channelName==`string`&&typeof e.deliveryId==`string`)return{channelKind:e.channelKind,channelName:e.channelName,deliveryId:e.deliveryId,inputAttribute:typeof e.inputAttribute==`string`?e.inputAttribute:void 0,requestId:typeof e.requestId==`string`?e.requestId:void 0,requestTraceContext:isSpanContext(e.requestTraceContext)?e.requestTraceContext:void 0}}function deserializePrincipalSummary(e){if(!isRecord(e)||!isInstrumentationPrincipalType(e.type))return;let t=e.type===`none`?void 0:boundedPrincipalId(e.id);return t===void 0?{type:e.type}:{id:t,type:e.type}}function deserializeAction(e){if(isRecord(e)&&typeof e.attemptIndex==`number`&&typeof e.callId==`string`&&isActionKind(e.kind)&&typeof e.name==`string`&&isSpanContext(e.parent)&&typeof e.rootSessionId==`string`&&typeof e.sessionId==`string`&&typeof e.spanId==`string`&&typeof e.startTimeMs==`number`&&typeof e.stepIndex==`number`&&typeof e.turnId==`string`)return{attemptIndex:e.attemptIndex,callId:e.callId,channelAudience:normalizeChannelAudience(e.channelAudience),inputAttribute:typeof e.inputAttribute==`string`?e.inputAttribute:void 0,kind:e.kind,name:e.name,parent:e.parent,parentCallId:typeof e.parentCallId==`string`?e.parentCallId:void 0,rootSessionId:e.rootSessionId,traceSessionId:decodeTraceSessionId(e),sessionId:e.sessionId,spanId:e.spanId,startTimeMs:e.startTimeMs,stepIndex:e.stepIndex,turnId:e.turnId,toolEndTimeMs:typeof e.toolEndTimeMs==`number`?e.toolEndTimeMs:void 0,toolFailed:e.toolFailed===!0,toolErrorAttribute:typeof e.toolErrorAttribute==`string`?e.toolErrorAttribute:void 0,toolAttributes:isRecord(e.toolAttributes)?Object.fromEntries(Object.entries(e.toolAttributes).filter(e=>{let t=e[1];return typeof t==`string`||typeof t==`number`||typeof t==`boolean`||Array.isArray(t)&&t.every(e=>[`string`,`number`,`boolean`].includes(typeof e))})):void 0}}function deserializeModelUsage(e){if(!isRecord(e))return;let t=typeof e.inputTokens==`number`?e.inputTokens:void 0,n=typeof e.outputTokens==`number`?e.outputTokens:void 0;return t===void 0&&n===void 0?void 0:{inputTokens:t,outputTokens:n}}function deserializeParentLineage(e){if(isRecord(e)&&typeof e.callId==`string`&&typeof e.sessionId==`string`&&typeof e.turnId==`string`)return{callId:e.callId,sessionId:e.sessionId,subagentName:typeof e.subagentName==`string`?e.subagentName:void 0,turnId:e.turnId}}function deserializeTurnTerminal(e){if(isRecord(e)&&isTurnTerminalType(e.type))return e.type===`turn.failed`?{error:deserializeError(e.error),type:e.type}:{type:e.type}}function deserializeRecord(e,t){if(!isRecord(e))return{};let n={};for(let[r,i]of Object.entries(e)){let e=t(i);e!==void 0&&(n[r]=e)}return n}function serializeSpanContext(e){return{isRemote:e.isRemote,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function serializeError(e){if(!(e instanceof Error))return;let t=boundedTraceError(e);return{message:t.message,name:t.name,stack:t.stack}}function deserializeError(e){if(!isRecord(e)||typeof e.message!=`string`)return;let t=Error(e.message);return typeof e.name==`string`&&(t.name=e.name),typeof e.stack==`string`&&(t.stack=e.stack),t}function isActionKind(e){return e===`load-skill`||e===`remote-agent-call`||e===`subagent-call`||e===`tool-call`}function isTurnTerminalType(e){return e===`turn.cancelled`||e===`turn.completed`||e===`turn.failed`}function isSpanContext(e){return isRecord(e)&&typeof e.spanId==`string`&&typeof e.traceFlags==`number`&&typeof e.traceId==`string`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{AGENT_TRACE_CONTEXT_KEY,decodeTraceSessionId,deserializeAgentTraceContextState,emptyAgentTraceContextState,serializeAgentTraceContextState};

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

@@ -1 +1 @@
-import{isAgentActivationSpan}from"#tracing/agent-span-contract.js";var AgentTraceSpanProcessor=class{#e;#t=new Set;#n=new Set;#r=new Set;#i=new Map;constructor(e){this.#e=e}async forceFlush(){await Promise.all(this.#e.map(e=>e.forceFlush()))}onStart(e,t){if(!isSpanLike(e))return;let n=e.attributes[`gen_ai.conversation.id`],r=e.attributes[`agent.run.id`];if(typeof n==`string`){let t=e.spanContext().traceId;this.#t.has(t)||this.#r.has(t)?this.#i.get(t)?.ownerRunId===void 0&&typeof r==`string`&&this.#i.set(t,{conversationId:n,ownerRunId:r}):(this.#t.add(t),this.#i.set(t,{conversationId:n,ownerRunId:typeof r==`string`?r:void 0}))}if(this.#a(e))for(let n of this.#e)n.onStart(e,t)}onEnd(e){if(!isSpanLike(e)||!this.#a(e))return;for(let t of this.#e)t.onEnd(e);let t=e.spanContext().traceId,n=this.#i.get(t);isAgentActivationSpan({name:e.name??``,attributes:e.attributes})&&n?.ownerRunId===e.attributes[`agent.run.id`]&&n?.conversationId===e.attributes[`gen_ai.conversation.id`]&&this.#n.add(t)}activeTraceIds(){return this.#t}releaseCompletedTraces(){if(this.#n.size===0)return!1;for(let e of this.#n)this.#t.delete(e),this.#i.delete(e),this.#r.add(e);for(this.#n.clear();this.#r.size>2048;){let e=this.#r.values().next().value;this.#r.delete(e)}return!0}releaseConversation(e){let t=!1;for(let[n,r]of this.#i)r.conversationId===e&&(t=!0,this.#t.delete(n),this.#n.delete(n),this.#i.delete(n));return t}async shutdown(){await Promise.all(this.#e.map(e=>e.shutdown()))}#a(e){return e.instrumentationScope?.name!==`workflow`&&(this.#t.has(e.spanContext().traceId)||this.#r.has(e.spanContext().traceId))}};function isSpanLike(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}export{AgentTraceSpanProcessor};
+import{isAgentActivationSpan,isDirectToolCallSpan}from"#tracing/agent-span-contract.js";var AgentTraceSpanProcessor=class{#e;#t=new Set;#n=new Set;#r=new Set;#i=new Map;#a=new Map;constructor(e){this.#e=e}async forceFlush(){await Promise.all(this.#e.map(e=>e.forceFlush()))}onStart(e,t){if(!isSpanLike(e))return;isDirectToolCallSpan(e)&&this.#o(e);let n=e.attributes[`gen_ai.conversation.id`],r=e.attributes[`agent.run.id`];if(typeof n==`string`){let t=e.spanContext().traceId;this.#t.has(t)||this.#r.has(t)?this.#a.get(t)?.ownerRunId===void 0&&typeof r==`string`&&this.#a.set(t,{conversationId:n,ownerRunId:r}):(this.#t.add(t),this.#a.set(t,{conversationId:n,ownerRunId:typeof r==`string`?r:void 0}))}if(this.#c(e))for(let n of this.#e)n.onStart(e,t)}onEnd(e){if(!isSpanLike(e)||!this.#c(e))return;for(let t of this.#e)t.onEnd(e);let t=e.spanContext().traceId,n=this.#a.get(t);isAgentActivationSpan({name:e.name??``,attributes:e.attributes})&&n?.ownerRunId===e.attributes[`agent.run.id`]&&n?.conversationId===e.attributes[`gen_ai.conversation.id`]&&this.#n.add(t),isDirectToolCallSpan(e)&&this.#s(e)}activeTraceIds(){return this.#t}releaseCompletedTraces(){if(this.#n.size===0)return!1;for(let e of this.#n)this.#t.delete(e),this.#a.delete(e),this.#r.add(e);for(this.#n.clear();this.#r.size>2048;){let e=this.#r.values().next().value;this.#r.delete(e)}return!0}releaseConversation(e){let t=!1;for(let[n,r]of this.#a)r.conversationId===e&&(t=!0,this.#t.delete(n),this.#n.delete(n),this.#a.delete(n),this.#i.delete(n));return t}async shutdown(){await Promise.all(this.#e.map(e=>e.shutdown()))}#o(e){let{spanId:t,traceId:n}=e.spanContext();if(t===void 0)return;let r=this.#i.get(n);if(r!==void 0){r.add(t),this.#n.delete(n);return}if(this.#t.has(n)&&!this.#n.has(n))return;let i=e.attributes[`gen_ai.conversation.id`],a=e.attributes[`agent.run.id`];typeof i==`string`&&(this.#n.delete(n),this.#r.delete(n),this.#t.add(n),this.#a.set(n,{conversationId:i,ownerRunId:typeof a==`string`?a:void 0}),this.#i.set(n,new Set([t])))}#s(e){let{spanId:t,traceId:n}=e.spanContext(),r=this.#i.get(n);t!==void 0&&r!==void 0&&r.delete(t)&&(r.size>0||(this.#i.delete(n),this.#n.add(n)))}#c(e){return e.instrumentationScope?.name!==`workflow`&&(this.#t.has(e.spanContext().traceId)||this.#r.has(e.spanContext().traceId))}};function isSpanLike(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}export{AgentTraceSpanProcessor};

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

@@ -1,5 +1,5 @@
-import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationActionKind, InstrumentationParentLineage, InstrumentationPrincipalSummary, InstrumentationTraceContext, InstrumentationTurnFailedEvent, InstrumentationTurnSettledEvent } from "#instrumentation/lifecycle.js";
+import type { Attributes, SpanContext } from "#compiled/@opentelemetry/api/index.js";
+import type { InstrumentationToolCallKind, InstrumentationParentLineage, InstrumentationPrincipalSummary, InstrumentationTraceContext, InstrumentationTurnFailedEvent, InstrumentationTurnSettledEvent } from "#instrumentation/lifecycle.js";
 import type { ChannelAudience } from "#shared/channel-audience.js";
 import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
 export interface AgentSessionTraceState {
@@ -52,15 +52,20 @@ export interface AgentActionTraceState {
     readonly callId: string;
     readonly channelAudience?: ChannelAudience;
     readonly inputAttribute?: string;
-    readonly kind: InstrumentationActionKind;
+    readonly kind: InstrumentationToolCallKind;
     readonly name: string;
     readonly parent: InstrumentationTraceContext;
+    readonly parentCallId?: string;
     readonly rootSessionId: string;
     readonly sessionId: string;
     readonly spanId: string;
     readonly startTimeMs: number;
     readonly stepIndex: number;
     readonly turnId: string;
+    readonly toolAttributes?: Attributes;
+    readonly toolEndTimeMs?: number;
+    readonly toolFailed?: boolean;
+    readonly toolErrorAttribute?: string;
 }
 /** Provider-owned serializable storage for durable agent trace state. */
 export interface AgentTraceStateStore {

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

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

package/dist/src/tracing/invoke-tool-span.d.ts

@@ -0,0 +1,61 @@
+import type { InvokeToolResult } from "#channel/invoke-tool.js";
+import type { SessionAuthContext } from "#channel/types.js";
+import type { ChannelAdapter } from "#channel/adapter.js";
+/** Where a direct tool call came from, so trace policy can classify it like a conversation. */
+export interface InvokeToolTraceOrigin {
+    readonly adapter: ChannelAdapter<any>;
+    readonly agentName: string;
+    readonly channelName: string;
+}
+/**
+ * Runs one direct tool call the way a conversation runs a model-issued one,
+ * minus the turn around it.
+ *
+ * Instrumentation providers get the same `tool.call.started` and
+ * `tool.call.completed` events, and the `execute_tool` span carries the same
+ * attributes. Content follows the same decision: the OpenTelemetry
+ * declaration's content setting, the trace policy, and the channel audience
+ * ceiling. Arguments, the result, and error text are recorded only when that
+ * decision allows them; otherwise a failure is a generic error. Error content
+ * is switched off until the span exists, so a trace policy that throws, or a
+ * call whose span is dropped, never writes error text to a parent span. A
+ * throwing policy is logged as a warning, which never touches a span.
+ *
+ * The span is marked as a direct call so trace processors treat it as the
+ * call's activation: it claims the trace when it starts and completes it
+ * when it ends. The call flushes the runtime afterwards so that completion
+ * is released even on a deployment that only serves direct calls.
+ */
+export declare function withInvokeToolSpan(input: {
+    /** The agent's name, on the span whether or not the call has a channel origin. */
+    readonly agentName: string;
+    readonly auth: SessionAuthContext;
+    readonly callId: string;
+    readonly origin: InvokeToolTraceOrigin | undefined;
+    readonly sessionId: string;
+    readonly toolName: string;
+}, run: (observer: InvokeToolObserver) => Promise<InvokeToolResult>): Promise<InvokeToolResult>;
+/**
+ * What the call reports while it runs, so providers and the span see the
+ * same steps a model-issued call goes through.
+ */
+export interface InvokeToolObserver {
+    /** The tool's `execute` is about to run with its checked input, the input the span records. */
+    executing(input: unknown): Promise<void>;
+    /**
+     * `execute` settled with this output, or threw this error, after running
+     * for `durationMs`: measured from just before `execute` to its settlement,
+     * so provider handlers are not counted, as in the AI SDK.
+     */
+    executed(outcome: ({
+        readonly type: "result";
+        readonly output: unknown;
+    } | {
+        readonly type: "error";
+        readonly error: unknown;
+    }) & {
+        readonly durationMs: number;
+    }): Promise<void>;
+    /** The error behind a `failed` result, recorded on the span when outputs are. */
+    failedWith(error: unknown): void;
+}

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

@@ -0,0 +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/agent-span-contract.js";import{resolveInstrumentationEnvironment}from"#internal/application/dev-environment.js";import{SpanKind,context,trace}from"#compiled/@opentelemetry/api/index.js";import{buildConversationContext}from"#channel/conversation-context.js";import{markAgentTraceContext}from"#tracing/agent-trace-context.js";import{toolCallIdempotencyKey}from"#instrumentation/lifecycle.js";import{resolveTracePolicy}from"#shared/trace-policy.js";import{withErrorContent}from"#tracing/error-content-context.js";import{getInstrumentationRuntime}from"#instrumentation/runtime-global.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{withAgentToolSpanContext}from"#tracing/agent-tool-span-context.js";import{agentTraceIdentityAttributes}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";const log=createLogger(`invoke-tool`);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=buildConversationContext({adapter:e.origin?.adapter??{kind:`channel`},auth:e.auth,channelName:e.origin?.channelName},resolveInstrumentationEnvironment()),a=toolCallEvents(r.hooks.forTrace?.({agentName:e.agentName,...i})??r.hooks,{attemptId:e.callId,attemptIndex:0,channelAudience:i.audience,functionId:e.agentName,rootSessionId:e.sessionId,sessionId:e.sessionId,stepIndex:0,traceSessionId:e.sessionId,turnId:e.callId},e),o=r.otelSettings;if(o===void 0)return await n(a.observer(void 0));let s=resolveTracePolicy(o.tracePolicy,{agentName:e.agentName,...i},e=>log.warn(`tracePolicy threw; dropping the tool call's trace`,{error:formatError(e)}));if(s.action===`drop`)return await context.with(suppressTracing(t),()=>n(a.observer(void 0)));let c=applyLiveDeliveryAudienceCeiling({action:`record`,recordInputs:o.recordInputs&&s.recordInputs,recordOutputs:o.recordOutputs&&s.recordOutputs},i.audience,void 0,i.environment),l=c.action===`record`&&c.recordInputs,u=c.action===`record`&&c.recordOutputs,d=`execute_tool ${e.toolName}`,f=withChannelAudience(t,i.audience),p={"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,...agentSpanNamingAttributes(d,`execute_tool`),...agentTraceIdentityAttributes({rootSessionId:e.sessionId,sessionId:e.sessionId,traceSessionId:e.sessionId})};e.origin!==void 0&&(p[`eve.channel.kind`]=i.channel.kind,p[`eve.channel.name`]=e.origin.channelName);let m=trace.getTracer(`eve.agent`).startSpan(d,{attributes:p,kind:SpanKind.INTERNAL},f),h=markAgentTraceContext(withAgentToolSpanContext(withErrorContent(trace.setSpan(f,m),u),{recordInputs:l,recordOutputs:u,recordError:(e,t)=>recordAgentSpanError(m,u?e:void 0,t),setAttributes:e=>setDefined(m,e)})),g,_=a.observer({failedWith:e=>{g={error:e}},recordInputs:l,span:m});try{let e=await context.with(h,()=>n(_));if(m.setAttribute(`eve.tool.outcome`,e.status),e.status===`completed`&&u){let t=contentAttribute(e.output);t!==void 0&&m.setAttribute(`gen_ai.tool.call.result`,t)}return e.status===`invalid-input`?recordAgentSpanError(m,void 0,e.status):e.status===`failed`&&recordAgentSpanError(m,u?g?.error:void 0,g===void 0?e.status:void 0),e}catch(e){throw recordAgentSpanError(m,u?e:void 0),e}finally{m.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/local-trace-analysis.js

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

package/dist/src/vue/index.d.ts

@@ -2,5 +2,7 @@ export { useEveAgent, type PrepareSend, type UseEveAgentOptions, type UseEveAgen
 export { type EveAgentReducer, type EveAgentReducerEvent, type ClientInputRespondedEvent, type ClientMessageFailedEvent, type ClientMessageSubmittedEvent, } from "#client/reducer.js";
 export { conversationReducer } from "#client/conversation-reducer.js";
 export { openConversationInputs } from "#client/conversation-state.js";
+export { toolCallState, type ToolCallState, type ToolCallStatus } from "#client/tool-call-state.js";
+export type { SessionAuthorization, SessionCall, SessionCallStatus, SessionProjection, } from "#protocol/session-projection.js";
 export type { AgentObservation, ConversationAgentSession, ConversationInput, ConversationState, ConversationTask, ConversationTaskCall, ConversationTurn, } from "#client/conversation-state.js";
 export { defaultMessageReducer, type EveAuthorizationChallenge, type EveAuthorizationOutcome, type EveAuthorizationPart, type EveMessageData, type EveDynamicToolPart, type EveMessageInputRequest, type EveMessage, type EveMessageMetadata, type EveMessagePart, type EveMessageToolMetadata, } from "#client/message-reducer.js";

package/dist/src/vue/index.js

@@ -1,3 +1,40 @@
-import { i as openConversationInputs, n as conversationReducer, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CFCaYnrI.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-C1GYGCtb.js";
 
-export { conversationReducer, defaultMessageReducer, openConversationInputs, useEveAgent };
+//#region src/client/tool-call-state.ts
+function toolCallState(conversation, callId, options = {}) {
+	const part = findToolPart(conversation, callId);
+	const projection = conversationProjection(conversation);
+	const call = projection.calls[callId];
+	const status = callStatus(projection, callId, options) ?? partStatus(part, options);
+	if (status === void 0) return void 0;
+	const taskCall = (call?.taskId === void 0 ? void 0 : conversation.tasks[call.taskId])?.calls[callId];
+	const output = taskCall?.output ?? part?.output;
+	const errorText = taskCall?.error?.message ?? part?.errorText ?? call?.error?.message ?? (part?.state === "output-denied" ? part.approval.reason : void 0);
+	const state = { status: respondedStatus(conversation, part, status) };
+	if (output !== void 0) state.output = output;
+	if (errorText !== void 0) state.errorText = errorText;
+	if (call?.error?.code !== void 0) state.errorCode = call.error.code;
+	return state;
+}
+function respondedStatus(conversation, part, status) {
+	if (status !== "awaiting-input" || part?.state !== "approval-requested") return status;
+	const input = conversation.inputs[part.approval.id];
+	if (input?.status !== "responded") return status;
+	return input.response?.optionId === "approve" ? "running" : "rejected";
+}
+function partStatus(part, options) {
+	if (part === void 0) return void 0;
+	switch (part.state) {
+		case "output-available": return part.partial === true ? "running" : "completed";
+		case "output-error": return "failed";
+		case "output-denied": return "rejected";
+		case "approval-requested": return "awaiting-input";
+		default: return options.streaming === false ? "interrupted" : "running";
+	}
+}
+function findToolPart(conversation, callId) {
+	for (let index = conversation.messages.length - 1; index >= 0; index -= 1) for (const part of conversation.messages[index].parts) if (part.type === "dynamic-tool" && part.toolCallId === callId) return part;
+}
+
+//#endregion
+export { conversationReducer, defaultMessageReducer, openConversationInputs, toolCallState, useEveAgent };

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

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

package/docs/agent-config.md

@@ -69,8 +69,8 @@ takes precedence; AI Gateway hashes IDs longer than 256 characters.
 
 ### Choose the model dynamically
 
-To select a model from the incoming prompt with an AI SDK evaluation model, use
-[`auto` from `eve/models`](./guides/evaluate).
+To select a model from the incoming prompt with an AI SDK decision model, use
+[`auto` from `eve/models`](./guides/decide).
 
 `model` also accepts `defineDynamic({ events })`. Each matching handler must
 return the concrete model for its scope; a dynamic model has no compiled

package/docs/channels/chat-sdk.mdx

@@ -208,7 +208,7 @@ await to(channel, { adapterName: "resend", threadId: "resend:user@example.com" }
 
 ### Attachments
 
-`send` takes plain text or an AI SDK `UserContent` array. To forward a Chat SDK message's attachments, convert it with `messageToUserContent`, which returns `message.text` when there are no attachments and a `UserContent` array (text plus one file part per attachment URL) when there are:
+`send` takes plain text or an AI SDK `UserContent` array. To forward a Chat SDK message's attachments, convert it with `messageToUserContent`. It returns `message.text` when there are no attachments, and a `UserContent` array (the text plus one part per attachment) when there are:
 
 ```ts
 import { messageToUserContent } from "eve/channels/chat-sdk";
@@ -218,6 +218,8 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
+When the adapter can download an attachment (it sets `fetchData`, as the Slack, Google Chat, WhatsApp, and Twilio adapters do), eve downloads it with the adapter's credentials when the turn runs, not in the webhook, and passes the bytes. Platform file URLs usually need those credentials, so the model provider couldn't open them. eve rebuilds the download with the adapter's `rehydrateAttachment`; an adapter without one can't download after the webhook returns, so its files reach the agent as a short note. A failed download, or a file over 25 MB, also becomes a note. An attachment with only a URL is passed as that URL.
+
 See [File uploads](./custom#file-uploads) for how eve stages remote file URLs before the model call.
 
 ## Configuration reference

package/docs/channels/custom.mdx

@@ -68,6 +68,9 @@ Each route receives these operation surfaces:
 - `to(channel, target).send(message, options)` hands work to another authored channel.
 - `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
 - `describe()` returns the agent's name, description, and the compiled tools a caller can run outside a turn, with their JSON schemas, sorted by name. It carries no paths, config, or other inspection detail, so a channel can publish it to its callers. Tools that need a turn (framework tools, workflow and provider tools, tools without `execute`) and tools added by dynamic resolvers or subagents are left out.
+- `invokeTool(name, input, { auth })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Each call gets its own session. Authored state starts from its initial value and is not kept, and a sandbox the tool opens is deleted when the call ends. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
+
+  A direct call doesn't go through the AI SDK, so AI SDK telemetry integrations never see it. Conversation tool calls do: an integration that an `agent/instrumentation/*.ts` module registers with `registerTelemetry()` from `ai` receives `onToolExecutionStart` and `onToolExecutionEnd` for each of them. A direct call is traced by eve itself instead. It gets an `execute_tool` span under the caller's trace and emits `tool.call.started` and `tool.call.completed` to instrumentation. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
 
 Event handlers receive `(eventData, channel, ctx)`. `ctx.session.id` identifies
 the exact session, while `channel.continuation` exposes the current address and

package/docs/channels/discord.mdx

@@ -19,7 +19,7 @@ The setup guides you through creating a Discord application and bot, then:
 - signs you in to Vercel and creates or links a project when needed;
 - validates the bot token;
 - creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
-- registers an application command with a required `message` option;
+- registers an application command with a required `message` option and an optional `file` attachment option;
 - configures the Discord application's Interactions Endpoint URL;
 - scaffolds the channel with Connect-managed credentials; and
 - prints the bot installation URL.
@@ -41,13 +41,14 @@ The route is `POST /eve/v1/discord` by default. Connect resolves the application
 
 ### Configure Discord manually
 
-If you do not use the guided Connect setup, register a command with Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction:
+If you do not use the guided Connect setup, register a command with Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction, and an attachment option lets people send a file with the command:
 
 ```bash
 curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \
   -H "Authorization: Bot $DISCORD_BOT_TOKEN" -H "Content-Type: application/json" \
   -d '[{"name":"ask","description":"Ask the eve agent","type":1,
-    "options":[{"name":"message","description":"What should the agent do?","type":3,"required":true}]}]'
+    "options":[{"name":"message","description":"What should the agent do?","type":3,"required":true},
+      {"name":"file","description":"A file for the agent to read","type":11,"required":false}]}]'
 ```
 
 Then configure the public `https://…/eve/v1/discord` route as the application's Interactions Endpoint URL. Pass `credentials: { applicationId, botToken, publicKey }` to `discordChannel`, or set the corresponding `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, and `DISCORD_PUBLIC_KEY` environment variables.
@@ -99,7 +100,7 @@ Start a session without an inbound interaction through `to(discord, target).send
 
 ### Attachments
 
-Inbound file attachments are not supported on this channel today.
+Files attached through a command's attachment options (type `11`) reach the agent as file parts. eve downloads each one from Discord's signed CDN URL (`cdn.discordapp.com` or `media.discordapp.net`) without credentials. A file over 25 MB, or one whose download fails, reaches the agent as a short note instead. Each command starts its own session, so a file is available in the conversation that command starts.
 
 ## What to read next