eve/dist/src/instrumentation/runtime.js

Filesystem-first framework for durable backend AI agents that run anywhere.

import{createLogger,recordErrorOnSpan}from"#internal/logging.js";import{normalizeChannelAudience}from"#shared/channel-audience.js";import{contextStorage}from"#context/container.js";import{ChannelInstrumentationKey,ConversationIdKey,OtelTraceEnabledKey,ParentSessionKey,ParentTraceContextKey,SessionTraceSeedKey}from"#context/keys.js";import{createMemoryInstrumentation}from"#instrumentation/memory.js";import{readConversationId}from"#tracing/conversation-context.js";import{applyLiveDeliveryAudienceCeiling,formatTraceContentCeiling,readForwardedTraceAssertion,traceContentCeilingToDecision}from"#shared/forwarded-trace-policy.js";import{readSessionTraceDecision}from"#tracing/agent-trace-context-store.js";import{shouldCaptureInstrumentationContent}from"#shared/instrumentation-content.js";import{isSampledTrace,resolveTracePolicy,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{context,trace}from"#compiled/@opentelemetry/api/index.js";import{attemptIdempotencyKey}from"#instrumentation/lifecycle.js";import{createInstrumentationHandleEvent,publishInputResolutions}from"#instrumentation/native-events.js";import{instrumentChannelDelivery}from"#instrumentation/channel-delivery.js";import{buildTelemetryRuntimeContext,snapshotInstrumentationRuntimeContext}from"#instrumentation/runtime-context.js";import{ensureOtelIntegration,getRegisteredTelemetryIntegrations}from"#instrumentation/ai-sdk-telemetry.js";import{createAiSdkHookBridge}from"#instrumentation/ai-sdk-hook-bridge.js";import{createBackgroundTaskInstrumentation}from"#instrumentation/background-task-runtime.js";import{prepareTurnTraceContext}from"#instrumentation/prepare-trace-context.js";import{AgentSpanIdGenerator}from"#tracing/agent-span-id-generator.js";import{withErrorContent}from"#tracing/error-content-context.js";import{readInstrumentationSessionContext}from"#instrumentation/session-context.js";import{intersectInstrumentationDecisions,readInstrumentationDecision}from"#shared/instrumentation-decision.js";const INSTRUMENTATION_RUNTIME_KEY=Symbol.for(`eve.instrumentation-runtime`),TURN_TRACE_STATE_KEY=`eve.harness.turnTrace`,log=createLogger(`instrumentation.runtime`);function bindInstrumentationRuntime(e,t,n){if(readConversationId(t.get(ConversationIdKey))===void 0&&t.set(ConversationIdKey,t.get(ParentSessionKey)?.rootSessionId??n.rootSessionId),e===void 0)return;let r=e.hooks,readSessionContext=()=>readInstrumentationSessionContext(contextStorage.getStore()??t),bindHooks=e=>{let t=e.instrumentation;return r.forTrace?.({agentName:n.agentName,audience:e.audience,channelType:t?.channelType})??r},captureExecutionRuntime=()=>{let t=e.otelSettings,n=e.ownsAgentSpans===!0;return t!==void 0&&!n&&ensureOtelIntegration(),{ownsAgentSpans:n,otelSettings:t,runtimeContextResolvers:e.runtimeContextResolvers,stepStartedRuntimeContextResolver:e.stepStartedRuntimeContextResolver,tracer:t===void 0?void 0:trace.getTracer(`eve`)}},preparePreamble=(t,r)=>{let i=r.instrumentation;return prepareTurnTraceContext({...t,instrumentation:e,principals:r.principals,session:{agentName:n.agentName,channelAudience:r.audience,channelType:i?.channelType,parentLineage:r.parentLineage,parentTraceContext:r.parentTraceContext,rootSessionId:r.parent?.rootSessionId??n.rootSessionId,sessionId:n.sessionId,traceSeed:r.traceSeed}})},i=e.memoryOperations===!0?createMemoryInstrumentation({resolveContext:()=>{let e=readSessionContext();return{hooks:bindHooks(e),rootSessionId:e.parent?.rootSessionId??n.rootSessionId}},runInContext:e.runInContext,sessionId:n.sessionId}):void 0,prepareExecution=()=>{let t=captureExecutionRuntime();return{runStep:async(r,i)=>{let a=readSessionContext(),o=bindHooks(a),s=t.otelSettings,c=resolveStepInstrumentationDecision(s,n.agentName,a.instrumentation,a.traceSeed,readSessionTraceDecision(a.context,n.sessionId)),l=t.tracer,u={"eve.environment":r.environment,"eve.session.id":r.session.sessionId,"eve.version":r.eveVersion},d=s?.functionId??n.agentName;d&&(u[`ai.telemetry.functionId`]=d);let f=l!==void 0&&!t.ownsAgentSpans&&c?.action!==`drop`&&r.hasInput?l.startSpan(`ai.eve.turn`,{attributes:u}):void 0,p=f?.spanContext(),m=p===void 0?r.session:{...r.session,state:{...r.session.state,[TURN_TRACE_STATE_KEY]:{spanId:p.spanId,traceFlags:p.traceFlags,traceId:p.traceId}}},h=f===void 0?void 0:trace.setSpan(context.active(),f);if(h===void 0&&l!==void 0){let e=r.session.state?.[TURN_TRACE_STATE_KEY];e!==void 0&&(h=trace.setSpan(context.active(),trace.wrapSpanContext({...e,isRemote:!0})))}let g=readSessionContext(),_=snapshotInstrumentationRuntimeContext(g.context),v=g.instrumentation,y=normalizeChannelAudience(v?.metadata.audience),b=shouldCaptureInstrumentationContent(y),x=c===void 0?c:applyLiveDeliveryAudienceCeiling(c,y,g.forwardedTracePolicy),S=x===void 0?b:x.action===`record`&&x.recordInputs,C=c?.action===`drop`,w={recordInputs:!C&&(x?.action===`record`?x.recordInputs:b)&&(s?.recordInputs??!1),recordOutputs:!C&&(x?.action===`record`?x.recordOutputs:b)&&(s?.recordOutputs??!1)},telemetry=e=>{if(s===void 0&&e.bridgeIntegration===void 0)return;let r={};for(let t of Object.keys(e.runtimeContext??{}))r[t]=!0;let i=s!==void 0&&!(w.recordInputs&&w.recordOutputs),integrations=()=>getRegisteredTelemetryIntegrations({...t.ownsAgentSpans?{excludeEveOtelIntegration:!0}:void 0,sanitizeEveOtelErrors:i});return{functionId:s?.functionId??n.agentName,includeRuntimeContext:r,integrations:e.bridgeIntegration===void 0?i?[...integrations()]:void 0:[e.bridgeIntegration,...integrations()],isEnabled:!0,recordInputs:w.recordInputs,recordOutputs:w.recordOutputs}},run=()=>i({createHandleEvent:e=>createInstrumentationHandleEvent({...e,agentName:n.agentName,channelAudience:y,channelKind:v?.kind,hooks:o,parentLineage:g.parentLineage,parentTraceContext:g.parentTraceContext,rootSessionId:g.parent?.rootSessionId,sessionId:n.sessionId}),prepareAttempt:t=>{let r={attemptId:`${n.sessionId}:${t.turnId}:${t.stepIndex}:${t.attemptIndex}`,attemptIndex:t.attemptIndex,channelAudience:y,functionId:s?.functionId??n.agentName,rootSessionId:g.parent?.rootSessionId??n.sessionId,sessionId:n.sessionId,stepIndex:t.stepIndex,turnId:t.turnId},i=createAiSdkHookBridge(r,o,e.runInContext,t.runtimeContext);return{complete:()=>o.publish({idempotencyKey:attemptIdempotencyKey(r),scope:r,type:`step.attempt.completed`}),fail:e=>o.publish({error:e,idempotencyKey:attemptIdempotencyKey(r),scope:r,type:`step.attempt.failed`}),scope:r,telemetry:telemetry({bridgeIntegration:i,runtimeContext:t.runtimeContext})}},preparePreamble:e=>preparePreamble(e,g),publishInputResolutions:e=>publishInputResolutions({...e,hooks:o}),recordError:e=>{f!==void 0&&recordErrorOnSpan(f,e)},resolveRuntimeContext:e=>buildTelemetryRuntimeContext({...e,capturesContent:S,context:_,providerResolvers:t.runtimeContextResolvers,stepStartedResolver:t.stepStartedRuntimeContextResolver}),session:m,setTurnId:e=>f?.setAttribute(`eve.turn.id`,e),telemetry:()=>telemetry({}),traceContext:p===void 0||!isValidSpanContext(p)?void 0:{spanId:p.spanId,traceFlags:p.traceFlags,traceId:p.traceId}});try{return await context.with(withErrorContent(h??context.active(),w.recordOutputs),run)}finally{f?.end(),f=void 0}}}};return{...createBackgroundTaskInstrumentation({ctx:t,hooks:()=>bindHooks(readSessionContext()),sessionId:n.sessionId}),createHandleEvent:e=>{let t=readSessionContext();return createInstrumentationHandleEvent({agentName:n.agentName,channelKind:t.instrumentation?.kind,handleEvent:e.handleEvent,hooks:bindHooks(t),sessionId:n.sessionId,turnId:e.turnId})},flush:e.forceFlush,instrumentChannelDelivery:e=>instrumentChannelDelivery({...e,hooks:r,policyAgentName:n.agentName}),memory:i,prepareExecution,preparePreamble:e=>preparePreamble(e,readSessionContext())}}function bindSessionInstrumentation(e){return bindInstrumentationRuntime(getInstrumentationRuntime(),e.ctx,{agentName:e.agentName,rootSessionId:e.rootSessionId,sessionId:e.sessionId})}function initializeSessionInstrumentation(e){let t=getInstrumentationRuntime(),n=e.ctx.get(ChannelInstrumentationKey),r=e.ctx.get(ParentTraceContextKey),i=readForwardedTraceAssertion(r?.forwardedTracePolicy),a=i?.originAudience??normalizeChannelAudience(n?.metadata.audience),o=allocateSessionTraceSeed({agentName:e.agentName,audience:a,channelType:n?.channelType,forwardedTracePolicy:i,parentTraceContext:r,runtime:t});if(o!==void 0&&(e.ctx.set(SessionTraceSeedKey,o),i!==void 0&&log.info(`resolved forwarded trace policy`,{ceilingEffective:o.decision?.action===`record`?formatTraceContentCeiling(o.decision):`drop`,ceilingIn:formatTraceContentCeiling(i.ceiling),originAudience:i.originAudience}),i!==void 0&&r!==void 0)){let t={...r,decision:o.decision,traceFlags:o.traceFlags};delete t.forwardedTracePolicy,e.ctx.set(ParentTraceContextKey,t)}e.ctx.set(OtelTraceEnabledKey,t?.prepareSessionTrace!==void 0)}function allocateSessionTraceSeed(e){let localDecision=()=>resolveTracePolicy(e.runtime?.otelSettings?.tracePolicy,{agentName:e.agentName,audience:e.audience,channelType:e.channelType});if(e.parentTraceContext!==void 0){let t=e.forwardedTracePolicy?traceContentCeilingToDecision(e.forwardedTracePolicy.ceiling):void 0,n=readInstrumentationDecision(e.parentTraceContext.decision),r=isSampledTrace(e.parentTraceContext)?t?n===void 0?t:intersectInstrumentationDecisions(t,n):n??resolveTracePolicyDecision(isSampledTrace(e.parentTraceContext),e.audience):{action:`drop`},i=e.forwardedTracePolicy?intersectInstrumentationDecisions(r,localDecision()):r,a=e.runtime?.idGenerator??new AgentSpanIdGenerator;return{decision:i,...e.forwardedTracePolicy===void 0?void 0:{forwardedTracePolicy:e.forwardedTracePolicy},spanId:a.allocateSpanId(),traceFlags:i.action===`drop`?0:e.parentTraceContext.traceFlags,traceId:a.generateTraceId()}}if(e.runtime?.prepareSessionTrace===void 0||e.runtime.idGenerator===void 0)return;let t=localDecision(),n=e.runtime.idGenerator.generateTraceId(),r=t.action===`record`;return{decision:t,spanId:e.runtime.idGenerator.allocateSpanId(),traceFlags:+!!r,traceId:n}}function resolveStepInstrumentationDecision(e,t,n,r,i){if(e===void 0)return;if(r?.decision!==void 0)return readInstrumentationDecision(r.decision);if(i!==void 0)return i;let a=normalizeChannelAudience(n?.metadata.audience);return r===void 0?resolveTracePolicy(e.tracePolicy,{agentName:t,audience:a,channelType:n?.channelType}):resolveTracePolicyDecision(isSampledTrace(r),a)}function isValidSpanContext(e){return/^[0-9a-f]{32}$/u.test(e.traceId)&&e.traceId!==`00000000000000000000000000000000`&&/^[0-9a-f]{16}$/u.test(e.spanId)&&e.spanId!==`0000000000000000`}const globalRuntime=globalThis;function registerInstrumentationRuntime(e){let t=globalRuntime[INSTRUMENTATION_RUNTIME_KEY];return t===void 0?(globalRuntime[INSTRUMENTATION_RUNTIME_KEY]=e,e):(t.otelSettings=e.otelSettings,t)}function getInstrumentationRuntime(){return globalRuntime[INSTRUMENTATION_RUNTIME_KEY]}export{bindInstrumentationRuntime,bindSessionInstrumentation,getInstrumentationRuntime,initializeSessionInstrumentation,registerInstrumentationRuntime};