eve 0.47.6 → 0.47.7

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

@@ -1,2 +1,2 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{isSampledTrace,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,SpanStatusCode,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{contentAttribute,genAiInputMessagesAttribute,genAiOutputMessagesAttribute,genAiSystemInstructionsAttribute,messagesContentAttribute,systemPromptAttribute,textContentAttribute,toolResultsContentAttribute}from"#tracing/agent-otel-content.js";import{setAgentUsage}from"#tracing/agent-otel-usage.js";import{withChannelAudience}from"#tracing/channel-audience-context.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{runtimeContextAttributes}from"#tracing/agent-otel-runtime-context.js";import{createAgentOtelSessionContext}from"#tracing/agent-otel-session-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";function createAgentOtelInstrumentation(e){let a=e.recordInputs??!1,s=e.recordOutputs??!1,p=new WeakMap,m=new Map,h=new WeakMap,g=new WeakMap,_=createAgentActionInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:a,recordOutputs:s,resolveTraceContext:async t=>(await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId))?.context,stateStore:e.stateStore,tracer:e.tracer}),v=createAgentApprovalInstrumentation({actionContextFor:_.contextFor,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,tracer:e.tracer}),y=createAgentToolInstrumentation({actionContextFor:_.contextFor,idGenerator:e.idGenerator,recordInputs:a,recordOutputs:s,resolveFallback:e=>{let t=m.get(e.scope.attemptId)??e.scope,n=h.get(t);return n===void 0?void 0:{context:n.context,spanContext:n.span.spanContext()}},tracer:e.tracer}),{ensureSessionContext:b,prepareSessionTrace:x,prepareTurnTrace:S}=createAgentOtelSessionContext(e),projectEvent=async o=>{let c=await e.stateStore.getSession(sessionIdForEvent(o)),l=audienceForEvent(o,c?.channelAudience),u=`traceSeed`in o?o.traceSeed:void 0,d=contextStorage.getStore()?.get(SessionTraceSeedKey),f=u?.decision??d?.decision??c?.decision??(u===void 0?d===void 0?c===void 0?void 0:resolveTracePolicyDecision(isSampledTrace(c.context),l):resolveTracePolicyDecision(isSampledTrace(d),l):resolveTracePolicyDecision(isSampledTrace(u),l));return f===void 0?withoutInstrumentationContent(o):instrumentationEventForTraceDecision(o,f.action===`drop`?f:{action:`record`,recordInputs:a&&f.recordInputs,recordOutputs:s&&f.recordOutputs},l)},onSessionStarted=async e=>{await x(e)},onTurnStarted=async e=>{await S(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 i=withChannelAudience(contextFromSpanContext(n.context),t.scope.channelAudience),a=trace.getSpan(context.active())?.spanContext(),o=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(attemptIdempotencyKey(t.scope)),()=>e.tracer.startSpan(`agent.step`,{attributes:{"agent.session.id":t.scope.sessionId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":t.scope.attemptIndex,"agent.step.index":t.scope.stepIndex,"agent.turn.id":t.scope.turnId,"agent.name":t.scope.functionId,...runtimeContextAttributes(t.runtimeContext)},links:a===void 0||a.traceId===n.context.traceId?void 0:[{attributes:{"eve.link.type":`workflow.delivery`},context:a}]},i));o.addEvent(`step.started`);let s=trace.setSpan(i,o);h.set(t.scope,{context:s,span:o}),m.set(t.scope.attemptId,t.scope)},onStepTerminal=async e=>{let t=m.get(e.scope.attemptId)??e.scope;p.delete(t),drainOpenSpans({...e,scope:t}),y.drain(e.scope.attemptId,e.type===`step.attempt.failed`?{error:e.error}:void 0),e.type===`step.attempt.failed`&&await _.failForAttempt(t,e.error),m.delete(e.scope.attemptId);let n=h.get(t);n!==void 0&&(n.span.addEvent(e.type===`step.attempt.completed`?`step.completed`:`step.failed`),e.type===`step.attempt.failed`&&recordError(n.span,e.error),n.span.end(),h.delete(t))},onTurnTerminal=async t=>{(t.type===`turn.cancelled`||t.type===`turn.failed`)&&await _.deleteForTurn(t.sessionId,t.turnId),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.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0){let i=await e.stateStore.getSession(t.sessionId);if(isSampledTrace(n.context)){let r=i?.agentName??n.subagentName,a=e.idGenerator.withSpanId(n.context.spanId,()=>e.tracer.startSpan(agentSpanName(r),{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":r,"agent.session.id":t.sessionId,"agent.subagent.name":n.subagentName,"agent.turn.id":t.turnId,"agent.turn.sequence":n.sequence,"gen_ai.agent.name":r,"gen_ai.conversation.id":t.sessionId,"gen_ai.operation.name":`invoke_agent`},kind:SpanKind.INTERNAL,startTime:n.startTimeMs},contextFromSpanContext({isRemote:n.parentIsRemote??!1,spanId:n.parentSpanId,traceFlags:n.context.traceFlags,traceId:n.context.traceId})));setAgentInvocationUsage(a,n.modelUsage),a.addEvent(`turn.started`,void 0,n.startTimeMs),n.terminal!==void 0&&(a.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordError(a,n.terminal.error)),a.end()}await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&(await _.deleteForSession(t.sessionId),await e.stateStore.deleteSession(t.sessionId))},onModelCallStarted=t=>{let n=h.get(t.scope);if(n===void 0)return;n.span.setAttribute(`agent.model.id`,t.model.modelId),n.span.setAttribute(`agent.model.provider`,t.model.provider);let r=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,...runtimeContextAttributes(t.runtimeContext)}},n.context);if(a&&t.input!==void 0){let e=messagesContentAttribute(t.input.messages);e!==void 0&&r.setAttribute(`ai.prompt.messages`,e);let n=genAiInputMessagesAttribute(t.input.messages);n!==void 0&&r.setAttribute(`gen_ai.input.messages`,n);let i=systemPromptAttribute(t.input.instructions);i!==void 0&&r.setAttribute(`ai.prompt.system`,i);let a=genAiSystemInstructionsAttribute(t.input.instructions);a!==void 0&&r.setAttribute(`gen_ai.system_instructions`,a)}let i={context:trace.setSpan(n.context,r),span:r};getExecutionContexts(t.scope).set(t.idempotencyKey,i.context),getSpanStates(g,t.scope).set(t.idempotencyKey,i)},onModelCallTerminal=async e=>{p.get(e.scope)?.delete(e.idempotencyKey);let t=takeSpanState(g,e.scope,e.idempotencyKey);if(t!==void 0){if(e.type===`model.call.failed`)recordError(t.span,e.error);else{await recordTurnUsage(e),setAgentUsage(t.span,e.usage),t.span.setAttribute(`gen_ai.response.finish_reasons`,[e.finishReason]);let n=h.get(e.scope);if(n!==void 0&&setAgentUsage(n.span,e.usage),s){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(`
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{isSampledTrace,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,SpanStatusCode,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{contentAttribute,genAiInputMessagesAttribute,genAiOutputMessagesAttribute,genAiSystemInstructionsAttribute,messagesContentAttribute,systemPromptAttribute,textContentAttribute,toolResultsContentAttribute}from"#tracing/agent-otel-content.js";import{setAgentUsage}from"#tracing/agent-otel-usage.js";import{withChannelAudience}from"#tracing/channel-audience-context.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{runtimeContextAttributes}from"#tracing/agent-otel-runtime-context.js";import{createAgentOtelSessionContext}from"#tracing/agent-otel-session-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";function createAgentOtelInstrumentation(e){let a=e.recordInputs??!1,s=e.recordOutputs??!1,p=new WeakMap,m=new Map,h=new WeakMap,g=new WeakMap,_=createAgentActionInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:a,recordOutputs:s,resolveTraceContext:async t=>(await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId))?.context,stateStore:e.stateStore,tracer:e.tracer}),v=createAgentApprovalInstrumentation({actionContextFor:_.contextFor,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,tracer:e.tracer}),y=createAgentToolInstrumentation({actionContextFor:_.contextFor,idGenerator:e.idGenerator,recordInputs:a,recordOutputs:s,resolveFallback:e=>{let t=m.get(e.scope.attemptId)??e.scope,n=h.get(t);return n===void 0?void 0:{context:n.context,spanContext:n.span.spanContext()}},tracer:e.tracer}),{ensureSessionContext:b,prepareSessionTrace:x,prepareTurnTrace:S}=createAgentOtelSessionContext(e),projectEvent=async o=>{let c=await e.stateStore.getSession(sessionIdForEvent(o)),l=audienceForEvent(o,c?.channelAudience),u=`traceSeed`in o?o.traceSeed:void 0,d=contextStorage.getStore()?.get(SessionTraceSeedKey),f=u?.decision??d?.decision??c?.decision??(u===void 0?d===void 0?c===void 0?void 0:resolveTracePolicyDecision(isSampledTrace(c.context),l):resolveTracePolicyDecision(isSampledTrace(d),l):resolveTracePolicyDecision(isSampledTrace(u),l));return f===void 0?withoutInstrumentationContent(o):instrumentationEventForTraceDecision(o,f.action===`drop`?f:{action:`record`,recordInputs:a&&f.recordInputs,recordOutputs:s&&f.recordOutputs},l)},onSessionStarted=async e=>{await x(e)},onTurnStarted=async e=>{await S(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 i=withChannelAudience(contextFromSpanContext(n.context),t.scope.channelAudience),a=trace.getSpan(context.active())?.spanContext(),o=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(attemptIdempotencyKey(t.scope)),()=>e.tracer.startSpan(`agent.step`,{attributes:{"agent.session.id":t.scope.sessionId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":t.scope.attemptIndex,"agent.step.index":t.scope.stepIndex,"agent.turn.id":t.scope.turnId,"agent.name":t.scope.functionId,...runtimeContextAttributes(t.runtimeContext)},links:a===void 0||a.traceId===n.context.traceId?void 0:[{attributes:{"eve.link.type":`workflow.delivery`},context:a}]},i));o.addEvent(`step.started`);let s=trace.setSpan(i,o);h.set(t.scope,{context:s,span:o}),m.set(t.scope.attemptId,t.scope)},onStepTerminal=async e=>{let t=m.get(e.scope.attemptId)??e.scope;p.delete(t),drainOpenSpans({...e,scope:t}),y.drain(e.scope.attemptId,e.type===`step.attempt.failed`?{error:e.error}:void 0),e.type===`step.attempt.failed`&&await _.failForAttempt(t,e.error),m.delete(e.scope.attemptId);let n=h.get(t);n!==void 0&&(n.span.addEvent(e.type===`step.attempt.completed`?`step.completed`:`step.failed`),e.type===`step.attempt.failed`&&recordError(n.span,e.error),n.span.end(),h.delete(t))},onTurnTerminal=async t=>{(t.type===`turn.cancelled`||t.type===`turn.failed`)&&await _.deleteForTurn(t.sessionId,t.turnId),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.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0){let i=await e.stateStore.getSession(t.sessionId);if(isSampledTrace(n.context)){let r=i?.agentName??n.subagentName,a=e.idGenerator.withSpanId(n.context.spanId,()=>e.tracer.startSpan(agentSpanName(r),{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":r,"agent.session.id":t.sessionId,"agent.subagent.name":n.subagentName,"agent.turn.id":t.turnId,"agent.turn.sequence":n.sequence,"gen_ai.agent.name":r,"gen_ai.conversation.id":t.sessionId,"gen_ai.operation.name":`invoke_agent`},kind:SpanKind.INTERNAL,startTime:n.startTimeMs},withChannelAudience(contextFromSpanContext({isRemote:n.parentIsRemote??!1,spanId:n.parentSpanId,traceFlags:n.context.traceFlags,traceId:n.context.traceId}),i?.channelAudience)));setAgentInvocationUsage(a,n.modelUsage),a.addEvent(`turn.started`,void 0,n.startTimeMs),n.terminal!==void 0&&(a.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordError(a,n.terminal.error)),a.end()}await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&(await _.deleteForSession(t.sessionId),await e.stateStore.deleteSession(t.sessionId))},onModelCallStarted=t=>{let n=h.get(t.scope);if(n===void 0)return;n.span.setAttribute(`agent.model.id`,t.model.modelId),n.span.setAttribute(`agent.model.provider`,t.model.provider);let r=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,...runtimeContextAttributes(t.runtimeContext)}},n.context);if(a&&t.input!==void 0){let e=messagesContentAttribute(t.input.messages);e!==void 0&&r.setAttribute(`ai.prompt.messages`,e);let n=genAiInputMessagesAttribute(t.input.messages);n!==void 0&&r.setAttribute(`gen_ai.input.messages`,n);let i=systemPromptAttribute(t.input.instructions);i!==void 0&&r.setAttribute(`ai.prompt.system`,i);let a=genAiSystemInstructionsAttribute(t.input.instructions);a!==void 0&&r.setAttribute(`gen_ai.system_instructions`,a)}let i={context:trace.setSpan(n.context,r),span:r};getExecutionContexts(t.scope).set(t.idempotencyKey,i.context),getSpanStates(g,t.scope).set(t.idempotencyKey,i)},onModelCallTerminal=async e=>{p.get(e.scope)?.delete(e.idempotencyKey);let t=takeSpanState(g,e.scope,e.idempotencyKey);if(t!==void 0){if(e.type===`model.call.failed`)recordError(t.span,e.error);else{await recordTurnUsage(e),setAgentUsage(t.span,e.usage),t.span.setAttribute(`gen_ai.response.finish_reasons`,[e.finishReason]);let n=h.get(e.scope);if(n!==void 0&&setAgentUsage(n.span,e.usage),s){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,!1);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}}))},C=createAgentChannelDeliveryInstrumentation({ensureSessionContext:b,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:a,stateStore:e.stateStore,tracer:e.tracer}),onStepMetadata=e=>{let t=h.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:{...C,"action.completed":_.events[`action.completed`],"action.failed":_.events[`action.failed`],async"action.started"(e,t){await _.events[`action.started`](e,t),await y.actionStarted(e)},...v,"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,...y.events,"turn.cancelled":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted},name:`eve.otel`,projectEvent,tracePolicy:()=>({emit:!0,recordInputs:a,recordOutputs:s})},prepareSessionTrace:x,prepareTurnTrace:S,async runInContext(t,n){let i=m.get(t.scope.attemptId)??t.scope,a=p.get(i),o=t.type===`model.call`?a?.get(t.idempotencyKey):y.contextFor(t.scope.attemptId,t.idempotencyKey);if(o===void 0){let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);n!==void 0&&(o=withChannelAudience(contextFromSpanContext(n.context),t.scope.channelAudience),isSampledTrace(n.context)||(o=suppressTracing(o)))}return o===void 0?n():context.with(markAgentTraceContext(o),n)}};function getExecutionContexts(e){let t=p.get(e);return t===void 0&&(t=new Map,p.set(e,t)),t}function drainOpenSpans(e){for(let t of g.get(e.scope)?.values()??[])e.type===`step.attempt.failed`&&recordError(t.span,e.error),t.span.end();g.delete(e.scope)}}function sessionIdForEvent(e){return`scope`in e?e.scope.sessionId:e.sessionId}function audienceForEvent(t,n){return`delivery`in t?normalizeChannelAudience(t.delivery.channelAudience):`scope`in t&&t.scope.channelAudience!==void 0?normalizeChannelAudience(t.scope.channelAudience):t.type===`session.started`?normalizeChannelAudience(t.channelAudience):normalizeChannelAudience(n)}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))}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)}function modelSpanName(e){return`chat ${e}`}function agentSpanName(e){return e===void 0?`invoke_agent`:`invoke_agent ${e}`}function setAgentInvocationUsage(e,t){t!==void 0&&(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))}function errorText(e){return e instanceof Error?e.message:e}function recordError(e,t){e.setAttribute(`error.type`,t instanceof Error?t.name||`Error`:`_OTHER`),t instanceof Error?(e.recordException(t),e.setStatus({code:SpanStatusCode.ERROR,message:t.message})):e.setStatus({code:SpanStatusCode.ERROR})}export{createAgentOtelInstrumentation};

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

@@ -1 +1 @@
-import{ROOT_CONTEXT,SpanKind,SpanStatusCode,trace}from"#compiled/@opentelemetry/api/index.js";import{actionIdempotencyKey}from"#instrumentation/lifecycle.js";import{contentAttribute}from"#tracing/agent-otel-content.js";function createAgentToolInstrumentation(e){let n=new Map,r=new Map,onStarted=async t=>{let n=actionIdempotencyKey(t.scope.sessionId,t.scope.turnId,t.callId),r=e.resolveFallback(t),a=r===void 0?void 0:reserve(t,n,r),o=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.callId);if(a===void 0){if(o===void 0)return;a=reserve(t,n,o)}o!==void 0&&startSpan(a,o.context)},onTerminal=async t=>{let n=r.get(t.scope.attemptId)?.get(t.idempotencyKey);if(n!==void 0){if(n.terminal=t,n.span===void 0){let t=await e.actionContextFor(n.event.scope.sessionId,n.event.scope.turnId,n.event.callId);t!==void 0&&startSpan(n,t.context)}finishIfReady(n)}};return{async actionStarted(t){let r=n.get(t.idempotencyKey);if(r===void 0||r.span!==void 0||r.finished===!0)return;let i=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.callId);i!==void 0&&(startSpan(r,i.context),finishIfReady(r))},contextFor:(e,t)=>r.get(e)?.get(t)?.context,drain(e,t){let n=r.get(e);if(n!==void 0){for(let e of n.values())e.finished!==!0&&(e.span===void 0&&startSpan(e,e.fallbackParent),finish(e,t));r.delete(e)}},events:{"tool.call.completed":onTerminal,"tool.call.failed":onTerminal,"tool.call.started":onStarted}};function getAttemptStates(e){let t=r.get(e);return t===void 0&&(t=new Map,r.set(e,t)),t}function reserve(t,r,i){let a=e.idGenerator.deriveSpanId(`tool:${t.idempotencyKey}`),o={actionKey:r,attemptId:t.scope.attemptId,context:contextFromSpanContext({isRemote:!1,spanId:a,traceFlags:i.spanContext.traceFlags,traceId:i.spanContext.traceId}),event:t,fallbackParent:i.context,idempotencyKey:t.idempotencyKey,spanId:a,startTimeMs:Date.now()};return getAttemptStates(t.scope.attemptId).set(t.idempotencyKey,o),n.set(r,o),o}function startSpan(n,r){if(!(n.span!==void 0||n.finished===!0)&&(n.span=e.idGenerator.withSpanId(n.spanId,()=>e.tracer.startSpan(`execute_tool ${n.event.toolName}`,{attributes:toolAttributes(n.event),kind:SpanKind.INTERNAL,startTime:n.startTimeMs},r)),e.recordInputs)){let e=contentAttribute(n.event.input,!1);e!==void 0&&n.span.setAttribute(`gen_ai.tool.call.arguments`,e)}}function finishIfReady(e){e.span===void 0||e.terminal===void 0||finish(e)}function finish(t,i){let o=t.span;if(o===void 0||t.finished===!0)return;t.finished=!0;let s=t.terminal;if(i!==void 0)recordError(o,i.error);else if(s?.type===`tool.call.failed`)recordError(o,s.error);else if(s?.output.type===`error`)recordError(o,s.output.error);else if(s!==void 0&&e.recordOutputs){let e=contentAttribute(s.output.output,!1);e!==void 0&&o.setAttribute(`gen_ai.tool.call.result`,e)}o.end(),n.delete(t.actionKey);let c=r.get(t.attemptId);c?.delete(t.idempotencyKey),c?.size===0&&r.delete(t.attemptId)}}function toolAttributes(e){return{"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":e.callId,"gen_ai.tool.name":e.toolName,"gen_ai.tool.type":`function`}}function contextFromSpanContext(t){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t))}function recordError(e,t){e.setAttribute(`error.type`,t instanceof Error?t.name||`Error`:`_OTHER`),t instanceof Error?(e.recordException(t),e.setStatus({code:SpanStatusCode.ERROR,message:t.message})):e.setStatus({code:SpanStatusCode.ERROR})}export{createAgentToolInstrumentation};
+import{ROOT_CONTEXT,SpanKind,SpanStatusCode,trace}from"#compiled/@opentelemetry/api/index.js";import{actionIdempotencyKey}from"#instrumentation/lifecycle.js";import{contentAttribute}from"#tracing/agent-otel-content.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";function createAgentToolInstrumentation(e){let n=new Map,r=new Map,onStarted=async t=>{let n=actionIdempotencyKey(t.scope.sessionId,t.scope.turnId,t.callId),r=e.resolveFallback(t),a=r===void 0?void 0:reserve(t,n,r),o=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.callId);if(a===void 0){if(o===void 0)return;a=reserve(t,n,o)}o!==void 0&&startSpan(a,o.context)},onTerminal=async t=>{let n=r.get(t.scope.attemptId)?.get(t.idempotencyKey);if(n!==void 0){if(n.terminal=t,n.span===void 0){let t=await e.actionContextFor(n.event.scope.sessionId,n.event.scope.turnId,n.event.callId);t!==void 0&&startSpan(n,t.context)}finishIfReady(n)}};return{async actionStarted(t){let r=n.get(t.idempotencyKey);if(r===void 0||r.span!==void 0||r.finished===!0)return;let i=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.callId);i!==void 0&&(startSpan(r,i.context),finishIfReady(r))},contextFor:(e,t)=>r.get(e)?.get(t)?.context,drain(e,t){let n=r.get(e);if(n!==void 0){for(let e of n.values())e.finished!==!0&&(e.span===void 0&&startSpan(e,e.fallbackParent),finish(e,t));r.delete(e)}},events:{"tool.call.completed":onTerminal,"tool.call.failed":onTerminal,"tool.call.started":onStarted}};function getAttemptStates(e){let t=r.get(e);return t===void 0&&(t=new Map,r.set(e,t)),t}function reserve(t,r,i){let a=e.idGenerator.deriveSpanId(`tool:${t.idempotencyKey}`),s={actionKey:r,attemptId:t.scope.attemptId,context:withChannelAudience(contextFromSpanContext({isRemote:!1,spanId:a,traceFlags:i.spanContext.traceFlags,traceId:i.spanContext.traceId}),t.scope.channelAudience),event:t,fallbackParent:i.context,idempotencyKey:t.idempotencyKey,spanId:a,startTimeMs:Date.now()};return getAttemptStates(t.scope.attemptId).set(t.idempotencyKey,s),n.set(r,s),s}function startSpan(n,r){if(!(n.span!==void 0||n.finished===!0)&&(n.span=e.idGenerator.withSpanId(n.spanId,()=>e.tracer.startSpan(`execute_tool ${n.event.toolName}`,{attributes:toolAttributes(n.event),kind:SpanKind.INTERNAL,startTime:n.startTimeMs},r)),e.recordInputs)){let e=contentAttribute(n.event.input,!1);e!==void 0&&n.span.setAttribute(`gen_ai.tool.call.arguments`,e)}}function finishIfReady(e){e.span===void 0||e.terminal===void 0||finish(e)}function finish(t,i){let o=t.span;if(o===void 0||t.finished===!0)return;t.finished=!0;let s=t.terminal;if(i!==void 0)recordError(o,i.error);else if(s?.type===`tool.call.failed`)recordError(o,s.error);else if(s?.output.type===`error`)recordError(o,s.output.error);else if(s!==void 0&&e.recordOutputs){let e=contentAttribute(s.output.output,!1);e!==void 0&&o.setAttribute(`gen_ai.tool.call.result`,e)}o.end(),n.delete(t.actionKey);let c=r.get(t.attemptId);c?.delete(t.idempotencyKey),c?.size===0&&r.delete(t.attemptId)}}function toolAttributes(e){return{"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":e.callId,"gen_ai.tool.name":e.toolName,"gen_ai.tool.type":`function`}}function contextFromSpanContext(t){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t))}function recordError(e,t){e.setAttribute(`error.type`,t instanceof Error?t.name||`Error`:`_OTHER`),t instanceof Error?(e.recordException(t),e.setStatus({code:SpanStatusCode.ERROR,message:t.message})):e.setStatus({code:SpanStatusCode.ERROR})}export{createAgentToolInstrumentation};

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

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

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

@@ -17,5 +17,7 @@ export declare function registerOtelPipeline(input: {
 export interface RegisteredOtelPipeline {
     readonly forceFlush: () => Promise<void>;
     readonly idGenerator: AgentSpanIdGenerator;
+    /** Whether the installed sampler would record a trace with this id. */
+    readonly samplesTrace: (traceId: string) => boolean;
     readonly shutdown: () => Promise<void>;
 }

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

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

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DjYwFJF7.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-B5zw1dwj.js";
 
 export { defaultMessageReducer, useEveAgent };

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

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

package/docs/reference/typescript-api.md

@@ -132,6 +132,7 @@ import template from "../../prompts/template.txt?raw";
 | `eve/context`                                                               | `defineState`, session and state types                                    |
 | `eve/sandbox`                                                               | `defineSandbox`, backends                                                 |
 | `eve/instrumentation`                                                       | `defineInstrumentation`, `isChannel`                                      |
+| `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                             |
 | `eve/models/openai`                                                         | `chatgpt`, deprecated `experimental_chatgpt`                              |
 | `eve/evals`                                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                 |
 | `eve/evals/expect`                                                          | `includes`, `equals`, `matches`, `similarity`                             |
@@ -143,6 +144,29 @@ import template from "../../prompts/template.txt?raw";
 
 Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
 
+## Local development capability
+
+Use `getLocalDevCapability()` when an authored tool needs to modify the local application's source tree during an interactive development turn:
+
+```ts
+import { getLocalDevCapability } from "eve/local-dev";
+
+const localDev = getLocalDevCapability();
+if (localDev === undefined) {
+  throw new Error("This tool is available only from a local eve dev client.");
+}
+
+await localDev.withSuspendedSource(async () => {
+  // Write under localDev.appRoot here.
+});
+```
+
+The function returns `LocalDevCapability | undefined`. It returns a capability only while authored code handles a request from a client on the same machine as the `eve dev` server. Deployed runtimes and clients attached over the network receive `undefined`, even when the target is another development server. A local TUI that attaches to an existing headless server receives the capability because availability follows each request rather than the process that started the server.
+
+`appRoot` is the authored application directory containing `package.json` and `agent/`, not the temporary runtime snapshot. `interactiveClient` is `true` when the requesting local client is the dev TUI; check it before starting a flow that requires terminal interaction.
+
+Run source mutations inside `withSuspendedSource()`. It acquires a unique watcher lease, waits for your asynchronous callback to settle, and then releases the lease. Concurrent or nested calls cannot resume each other early, and releasing the final lease rebuilds the runtime artifacts. The callback's return value is returned, and its error is rethrown after release. If suspension cannot be acquired, the callback does not run. If the host cannot confirm release after a retry, the method throws an actionable error; restart `eve dev` before making more source changes.
+
 ## ChatGPT subscription models
 
 `chatgpt()` from `eve/models/openai` serves an OpenAI model through the local Codex login and bills the ChatGPT subscription. With no argument, it selects `gpt-5.6-sol`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.47.6",
+  "version": "0.47.7",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -266,6 +266,11 @@
       "import": "./dist/src/internal/programmatic-source-loader.js",
       "default": "./dist/src/internal/programmatic-source-loader.js"
     },
+    "./local-dev": {
+      "types": "./dist/src/public/local-dev.d.ts",
+      "import": "./dist/src/public/local-dev.js",
+      "default": "./dist/src/public/local-dev.js"
+    },
     "./extension": {
       "types": "./dist/src/public/extension/index.d.ts",
       "import": "./dist/src/public/extension/index.js",

package/dist/src/execution/tools/tasks.d.ts

@@ -1,18 +0,0 @@
-import type { HarnessToolDefinition } from "#harness/execute-tool.js";
-/**
- * Builds the harness definitions injected when the root agent enables
- * `experimental.tasks`. Follows the implicit `agent` tool pattern:
- * inline definitions, no registry entry, session-shape hiding in
- * advertised-tools, and re-validation at dispatch.
- */
-export declare function createTaskToolHarnessDefinitions(): readonly HarnessToolDefinition[];
-/**
- * Whether one node's sessions receive the task tools.
- *
- * Mirrors `isImplicitAgentToolAvailable`: the compile step already
- * rejects `experimental.tasks` on subagents, authored tools with the
- * same name shadow the framework tool, and `disableTool(name)` removes
- * individual tools. Root-node self-delegated children share this node's
- * config, so advertised-tools uses caller/session shape to expose only
- * `task_update` to delegated task children.
- */

package/dist/src/execution/tools/tasks.js

@@ -1 +0,0 @@
-import{TASK_CANCEL_INPUT_SCHEMA,TASK_CANCEL_TOOL_NAME,TASK_UPDATE_INPUT_SCHEMA,TASK_UPDATE_TOOL_NAME,TASK_VIEWS_OUTPUT_SCHEMA}from"#tools/framework/task-contract.js";function createTaskToolHarnessDefinitions(){return[{description:`Request cooperative cancellation of one or more background tasks. Cancellation is final: a task that finishes after you cancel it stays cancelled. Cancelling an already-finished task changes nothing.`,inputSchema:TASK_CANCEL_INPUT_SCHEMA,name:TASK_CANCEL_TOOL_NAME,outputSchema:TASK_VIEWS_OUTPUT_SCHEMA,runtimeAction:{kind:`task-control`}},{description:`Briefly tell the parent agent what this background task is currently doing. Report activity, not preliminary findings or results.`,inputSchema:TASK_UPDATE_INPUT_SCHEMA,name:TASK_UPDATE_TOOL_NAME,runtimeAction:{kind:`task-control`}}]}export{createTaskToolHarnessDefinitions};