eve 0.47.6 → 0.48.0

package/dist/src/tracing/agent-otel-session-context.js

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{isSampledTrace,resolveTracePolicy,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{sessionIdempotencyKey}from"#instrumentation/lifecycle.js";function createAgentOtelSessionContext(n){let openSessionTrace=e=>{if(e.traceSeed!==void 0){if(!isSampledTrace(e.traceSeed))return{isRemote:!1,spanId:e.traceSeed.spanId,traceFlags:0,traceId:e.traceSeed.traceId};let startSpan=()=>n.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":n.frameworkVersion,"agent.channel.audience":e.channelAudience,"agent.name":e.agentName,"agent.session.id":e.sessionId,"agent.trace.schema.version":3},root:!0}),r=n.idGenerator.withSpanId(e.traceSeed.spanId,()=>n.idGenerator.withTraceId(e.traceSeed.traceId,startSpan));return r.addEvent(`session.started`),r.end(),r.spanContext()}if(e.traceDecision.action===`drop`)return{isRemote:!1,spanId:n.idGenerator.deriveSpanId(`session:${e.sessionId}`),traceFlags:0,traceId:n.idGenerator.generateTraceId()};let r=n.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":n.frameworkVersion,"agent.channel.audience":e.channelAudience,"agent.name":e.agentName,"agent.session.id":e.sessionId,"agent.trace.schema.version":3},root:!0});return r.addEvent(`session.started`),r.end(),r.spanContext()},ensureSessionContext=async t=>{let r=await n.stateStore.getSession(t.sessionId);if(r===void 0){let i=normalizeChannelAudience(t.channelAudience),a=resolveSessionTraceDecision(t,i,n.tracePolicy);r={agentName:t.agentName,channelAudience:i,channelKind:t.channelKind,decision:a,context:t.parentTraceContext===void 0?openSessionTrace({agentName:t.agentName,channelAudience:i,channelType:t.channelType,rootSessionId:t.rootSessionId,sessionId:t.sessionId,traceDecision:a,traceSeed:t.traceSeed}):adoptedSpanContext(t.parentTraceContext),rootSessionId:t.rootSessionId},await n.stateStore.setSession(t.sessionId,r)}return r};return{ensureSessionContext,prepareSessionTrace:async e=>{let t=await ensureSessionContext(e);return portableSpanContext(t.context,t.decision)},prepareTurnTrace:async e=>{let t=await n.stateStore.getTurn(e.sessionId,e.turnId);if(t!==void 0)return{decision:(await n.stateStore.getSession(e.sessionId))?.decision,spanId:t.parentSpanId,traceFlags:t.context.traceFlags,traceId:t.context.traceId};let r=await ensureSessionContext({agentName:e.agentName,channelAudience:`unknown`,channelKind:void 0,idempotencyKey:sessionIdempotencyKey(e.sessionId),parentTraceContext:e.parentTraceContext,rootSessionId:e.rootSessionId,sessionId:e.sessionId,type:`session.started`}),a={isRemote:!1,spanId:n.idGenerator.deriveSpanId(`turn:${e.idempotencyKey}`),traceFlags:r.context.traceFlags,traceId:r.context.traceId};return await n.stateStore.setTurn(e.sessionId,e.turnId,{context:a,parentIsRemote:r.context.isRemote,parentSpanId:r.context.spanId,rootSessionId:e.rootSessionId,sequence:e.sequence,startTimeMs:Date.now(),subagentName:e.parentLineage?.subagentName}),portableSpanContext(r.context,r.decision)}}}function portableSpanContext(e,t){return{decision:t,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function adoptedSpanContext(e){return{isRemote:`isRemote`in e&&e.isRemote===!0,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function resolveSessionTraceDecision(e,i,a){return e.traceSeed?.decision===void 0?e.traceSeed===void 0?e.parentTraceContext===void 0?e.agentName===void 0?a===void 0?resolveTracePolicyDecision(!0,i):{action:`drop`}:resolveTracePolicy(a,{agentName:e.agentName,audience:i,channelType:e.channelType}):resolveTracePolicyDecision(isSampledTrace(e.parentTraceContext),i):resolveTracePolicyDecision(isSampledTrace(e.traceSeed),i):e.traceSeed.decision}export{createAgentOtelSessionContext};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{isSampledTrace,resolveTracePolicy,resolveTracePolicyDecision}from"#tracing/sampled-trace.js";import{sessionIdempotencyKey}from"#instrumentation/lifecycle.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";function createAgentOtelSessionContext(n){let openSessionTrace=e=>{if(e.traceSeed!==void 0){if(e.traceDecision.action===`drop`||!isSampledTrace(e.traceSeed))return{isRemote:!1,spanId:e.traceSeed.spanId,traceFlags:0,traceId:e.traceSeed.traceId};let startSpan=()=>n.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":n.frameworkVersion,"agent.channel.audience":e.channelAudience,"agent.name":e.agentName,"agent.session.id":e.sessionId,"agent.trace.schema.version":3},root:!0}),r=n.idGenerator.withSpanId(e.traceSeed.spanId,()=>n.idGenerator.withTraceId(e.traceSeed.traceId,startSpan));return r.addEvent(`session.started`),r.end(),r.spanContext()}if(e.traceDecision.action===`drop`)return{isRemote:!1,spanId:n.idGenerator.deriveSpanId(`session:${e.sessionId}`),traceFlags:0,traceId:n.idGenerator.generateTraceId()};let r=n.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":n.frameworkVersion,"agent.channel.audience":e.channelAudience,"agent.name":e.agentName,"agent.session.id":e.sessionId,"agent.trace.schema.version":3},root:!0});return r.addEvent(`session.started`),r.end(),r.spanContext()},ensureSessionContext=async t=>{let r=await n.stateStore.getSession(t.sessionId);if(r===void 0){let i=normalizeChannelAudience(t.channelAudience),a=resolveSessionTraceDecision(t,i,n.tracePolicy);r={agentName:t.agentName,channelAudience:i,channelKind:t.channelKind,decision:a,context:t.parentTraceContext===void 0?openSessionTrace({agentName:t.agentName,channelAudience:i,channelType:t.channelType,rootSessionId:t.rootSessionId,sessionId:t.sessionId,traceDecision:a,traceSeed:t.traceSeed}):adoptedSpanContext(t.parentTraceContext),rootSessionId:t.rootSessionId},await n.stateStore.setSession(t.sessionId,r)}return r};return{ensureSessionContext,prepareSessionTrace:async e=>{let t=await ensureSessionContext(e);return portableSpanContext(t.context,t.decision)},prepareTurnTrace:async e=>{let t=await n.stateStore.getTurn(e.sessionId,e.turnId);if(t!==void 0)return{decision:(await n.stateStore.getSession(e.sessionId))?.decision,spanId:t.parentSpanId,traceFlags:t.context.traceFlags,traceId:t.context.traceId};let r=await ensureSessionContext({agentName:e.agentName,channelAudience:`unknown`,channelKind:void 0,idempotencyKey:sessionIdempotencyKey(e.sessionId),parentTraceContext:e.parentTraceContext,rootSessionId:e.rootSessionId,sessionId:e.sessionId,type:`session.started`}),a={isRemote:!1,spanId:n.idGenerator.deriveSpanId(`turn:${e.idempotencyKey}`),traceFlags:r.context.traceFlags,traceId:r.context.traceId};return await n.stateStore.setTurn(e.sessionId,e.turnId,{context:a,parentIsRemote:r.context.isRemote,parentSpanId:r.context.spanId,rootSessionId:e.rootSessionId,sequence:e.sequence,startTimeMs:Date.now(),subagentName:e.parentLineage?.subagentName}),portableSpanContext(r.context,r.decision)}}}function portableSpanContext(e,t){return{decision:t,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function adoptedSpanContext(e){return{isRemote:`isRemote`in e&&e.isRemote===!0,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function resolveSessionTraceDecision(e,i,o){return e.traceSeed?.decision===void 0?e.traceSeed===void 0?e.parentTraceContext===void 0?e.agentName===void 0?o===void 0?resolveTracePolicyDecision(!0,i):{action:`drop`}:resolveTracePolicy(o,{agentName:e.agentName,audience:i,channelType:e.channelType}):resolveTracePolicyDecision(isSampledTrace(e.parentTraceContext),i):resolveTracePolicyDecision(isSampledTrace(e.traceSeed),i):readInstrumentationDecision(e.traceSeed.decision)??{action:`drop`}}export{createAgentOtelSessionContext};

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/agent-trace-context-store.d.ts

@@ -1,7 +1,7 @@
 import type { SessionTraceContext } from "#channel/types.js";
 import type { ContextAccessor } from "#context/key.js";
 import type { AgentActionTraceState, AgentSessionTraceState, AgentTraceStateStore, AgentTurnTraceState } from "#tracing/agent-trace-state.js";
-import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
+import { type InstrumentationDecision } from "#shared/instrumentation-decision.js";
 /** Reads the decision already bound to a session in the current worker context. */
 export declare function readCurrentSessionTraceDecision(sessionId: string): InstrumentationDecision | undefined;
 export declare function readSessionTraceDecision(context: ContextAccessor, sessionId: string): InstrumentationDecision | undefined;

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

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{contextStorage,loadContext}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{ContextKey}from"#context/key.js";const AgentTraceContextKey=new ContextKey(`eve.harness.agentTrace`,{codec:{deserialize:deserializeState,serialize:serializeState}});function readCurrentSessionTraceDecision(e){let n=contextStorage.getStore();return n===void 0?void 0:readSessionTraceDecision(n,e)}function readSessionTraceDecision(e,t){return e.get(AgentTraceContextKey)?.sessions[t]?.decision}function preserveSerializedAgentTraceState(e,t){let n=t[AgentTraceContextKey.name];return n===void 0?e:{...e,[AgentTraceContextKey.name]:n}}function readSessionTraceContext(e,t){let n=e[AgentTraceContextKey.name];if(n===void 0)return;let r=deserializeState(n).sessions[t];return r===void 0?void 0:withTraceDecision(e,r.context,r.decision)}function readActionTraceContext(e,t,n,r){let i=e[AgentTraceContextKey.name];if(i===void 0)return;let o=deserializeState(i),s=Object.values(o.actions).find(e=>e.sessionId===t&&e.turnId===n&&e.callId===r);if(s!==void 0)return withTraceDecision(e,{isRemote:!1,spanId:s.spanId,traceFlags:s.parent.traceFlags,traceId:s.parent.traceId},o.sessions[s.sessionId]?.decision)}function withTraceDecision(e,t,n){let i=e[SessionTraceSeedKey.name],a=n??i?.decision;return a===void 0?t:{...t,decision:a}}var ContextAgentTraceStateStore=class{deleteAction(e){updateState(t=>{let n={...t.actions};return delete n[e],{...t,actions:n}})}deleteActions(e,t){updateState(n=>{let r={...n.actions};for(let[n,i]of Object.entries(r))i.sessionId===e&&(t===void 0||i.turnId===t)&&delete r[n];return{...n,actions:r}})}deleteSession(e){updateState(t=>{let n={...t.sessions};return delete n[e],{...t,sessions:n}})}deleteTurn(e,t){updateState(n=>{let r={...n.turns};return delete r[turnKey(e,t)],{...n,turns:r}})}findAction(e,n){return Object.values(contextStorage.getStore()?.get(AgentTraceContextKey)?.actions??{}).find(t=>t.sessionId===e&&t.callId===n)}getAction(e){return contextStorage.getStore()?.get(AgentTraceContextKey)?.actions[e]}getSession(e){return contextStorage.getStore()?.get(AgentTraceContextKey)?.sessions[e]}getTurn(e,n){return contextStorage.getStore()?.get(AgentTraceContextKey)?.turns[turnKey(e,n)]}setAction(e,t){updateState(n=>({...n,actions:{...n.actions,[e]:t}}))}setSession(e,t){updateState(n=>({...n,sessions:{...n.sessions,[e]:t}}))}setTurn(e,t,n){updateState(r=>({...r,turns:{...r.turns,[turnKey(e,t)]:n}}))}updateTurn(e,t,n){updateState(r=>{let i=turnKey(e,t),a=r.turns[i];return a===void 0?r:{...r,turns:{...r.turns,[i]:n(a)}}})}};function updateState(e){loadContext().set(AgentTraceContextKey,t=>e(t??{actions:{},sessions:{},turns:{}}))}function turnKey(e,t){return`${e}\0${t}`}function serializeState(e){return{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,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 deserializeState(t){return isRecord(t)?{actions:deserializeRecord(t.actions,deserializeAction),sessions:deserializeRecord(t.sessions,t=>{if(!(!isRecord(t)||!isSpanContext(t.context)))return{agentName:typeof t.agentName==`string`?t.agentName:void 0,channelAudience:normalizeChannelAudience(t.channelAudience),channelKind:typeof t.channelKind==`string`?t.channelKind:void 0,context:t.context,decision:deserializeInstrumentationDecision(t.decision),rootSessionId:typeof t.rootSessionId==`string`?t.rootSessionId:``}}),turns:deserializeRecord(t.turns,e=>{if(!(!isRecord(e)||!isSpanContext(e.context))&&!(typeof e.parentSpanId!=`string`||typeof e.startTimeMs!=`number`))return{context:e.context,modelUsage:deserializeModelUsage(e.modelUsage),parentIsRemote:typeof e.parentIsRemote==`boolean`?e.parentIsRemote:void 0,parentSpanId:e.parentSpanId,rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,sequence:typeof e.sequence==`number`?e.sequence:0,startTimeMs:e.startTimeMs,subagentName:typeof e.subagentName==`string`?e.subagentName:void 0,terminal:deserializeTerminal(e.terminal)}})}:{actions:{},sessions:{},turns:{}}}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 deserializeAction(t){if(!(!isRecord(t)||typeof t.attemptIndex!=`number`||typeof t.callId!=`string`||!isActionKind(t.kind)||typeof t.name!=`string`||!isSpanContext(t.parent)||typeof t.rootSessionId!=`string`||typeof t.sessionId!=`string`||typeof t.spanId!=`string`||typeof t.startTimeMs!=`number`||typeof t.stepIndex!=`number`||typeof t.turnId!=`string`))return{attemptIndex:t.attemptIndex,callId:t.callId,channelAudience:normalizeChannelAudience(t.channelAudience),inputAttribute:typeof t.inputAttribute==`string`?t.inputAttribute:void 0,kind:t.kind,name:t.name,parent:t.parent,rootSessionId:t.rootSessionId,sessionId:t.sessionId,spanId:t.spanId,startTimeMs:t.startTimeMs,stepIndex:t.stepIndex,turnId:t.turnId}}function isActionKind(e){return e===`load-skill`||e===`remote-agent-call`||e===`subagent-call`||e===`tool-call`}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 deserializeTerminal(e){if(!isRecord(e)||typeof e.type!=`string`)return;let t=e.type;if(isTurnTerminalType(t))return t===`turn.failed`?{error:deserializeError(e.error),type:t}:{type:t}}function serializeSpanContext(e){return{isRemote:e.isRemote,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function isSpanContext(e){return isRecord(e)&&typeof e.spanId==`string`&&typeof e.traceFlags==`number`&&typeof e.traceId==`string`}function serializeError(e){return e instanceof Error?{message:e.message,name:e.name,stack:e.stack}:void 0}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 isTurnTerminalType(e){return e===`turn.cancelled`||e===`turn.completed`||e===`turn.failed`}function deserializeInstrumentationDecision(e){if(isRecord(e))return e.action===`drop`?{action:`drop`}:e.action===`record`&&typeof e.recordInputs==`boolean`&&typeof e.recordOutputs==`boolean`?{action:`record`,recordInputs:e.recordInputs,recordOutputs:e.recordOutputs}:void 0}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{ContextAgentTraceStateStore,preserveSerializedAgentTraceState,readActionTraceContext,readCurrentSessionTraceDecision,readSessionTraceContext,readSessionTraceDecision};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{contextStorage,loadContext}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{ContextKey}from"#context/key.js";import{decisionToTraceContentCeiling,resolveForwardedTraceSeed}from"#shared/forwarded-trace-policy.js";import{readInstrumentationDecision}from"#shared/instrumentation-decision.js";const AgentTraceContextKey=new ContextKey(`eve.harness.agentTrace`,{codec:{deserialize:deserializeState,serialize:serializeState}});function readCurrentSessionTraceDecision(e){let n=contextStorage.getStore();return n===void 0?void 0:readSessionTraceDecision(n,e)}function readSessionTraceDecision(e,t){return e.get(AgentTraceContextKey)?.sessions[t]?.decision}function preserveSerializedAgentTraceState(e,t){let n=t[AgentTraceContextKey.name];return n===void 0?e:{...e,[AgentTraceContextKey.name]:n}}function readSessionTraceContext(e,t){let n=e[AgentTraceContextKey.name];if(n===void 0)return;let r=deserializeState(n).sessions[t];return r===void 0?void 0:withTraceDecision(e,r.context,r.decision)}function readActionTraceContext(e,t,n,r){let i=e[AgentTraceContextKey.name];if(i===void 0)return;let a=deserializeState(i),o=Object.values(a.actions).find(e=>e.sessionId===t&&e.turnId===n&&e.callId===r);if(o!==void 0)return withTraceDecision(e,{isRemote:!1,spanId:o.spanId,traceFlags:o.parent.traceFlags,traceId:o.parent.traceId},a.sessions[o.sessionId]?.decision)}function withTraceDecision(e,t,n){let i=e[SessionTraceSeedKey.name],s=resolveForwardedTraceSeed({decision:n??i?.decision,forwardedTracePolicy:i?.forwardedTracePolicy,traceFlags:t.traceFlags}),c=s.decision,l=s.forwardedTracePolicy,u=decisionToTraceContentCeiling(c),d={...t,traceFlags:s.traceFlags};if(l===void 0)return c===void 0?d:{...d,decision:c};let f=u===void 0?l:{...l,ceiling:u};return c===void 0?{...d,forwardedTracePolicy:f}:{...d,decision:c,forwardedTracePolicy:f}}var ContextAgentTraceStateStore=class{deleteAction(e){updateState(t=>{let n={...t.actions};return delete n[e],{...t,actions:n}})}deleteActions(e,t){updateState(n=>{let r={...n.actions};for(let[n,i]of Object.entries(r))i.sessionId===e&&(t===void 0||i.turnId===t)&&delete r[n];return{...n,actions:r}})}deleteSession(e){updateState(t=>{let n={...t.sessions};return delete n[e],{...t,sessions:n}})}deleteTurn(e,t){updateState(n=>{let r={...n.turns};return delete r[turnKey(e,t)],{...n,turns:r}})}findAction(e,n){return Object.values(contextStorage.getStore()?.get(AgentTraceContextKey)?.actions??{}).find(t=>t.sessionId===e&&t.callId===n)}getAction(e){return contextStorage.getStore()?.get(AgentTraceContextKey)?.actions[e]}getSession(e){return contextStorage.getStore()?.get(AgentTraceContextKey)?.sessions[e]}getTurn(e,n){return contextStorage.getStore()?.get(AgentTraceContextKey)?.turns[turnKey(e,n)]}setAction(e,t){updateState(n=>({...n,actions:{...n.actions,[e]:t}}))}setSession(e,t){updateState(n=>({...n,sessions:{...n.sessions,[e]:t}}))}setTurn(e,t,n){updateState(r=>({...r,turns:{...r.turns,[turnKey(e,t)]:n}}))}updateTurn(e,t,n){updateState(r=>{let i=turnKey(e,t),a=r.turns[i];return a===void 0?r:{...r,turns:{...r.turns,[i]:n(a)}}})}};function updateState(e){loadContext().set(AgentTraceContextKey,t=>e(t??{actions:{},sessions:{},turns:{}}))}function turnKey(e,t){return`${e}\0${t}`}function serializeState(e){return{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,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 deserializeState(t){return isRecord(t)?{actions:deserializeRecord(t.actions,deserializeAction),sessions:deserializeRecord(t.sessions,t=>{if(!(!isRecord(t)||!isSpanContext(t.context)))return{agentName:typeof t.agentName==`string`?t.agentName:void 0,channelAudience:normalizeChannelAudience(t.channelAudience),channelKind:typeof t.channelKind==`string`?t.channelKind:void 0,context:t.context,decision:readInstrumentationDecision(t.decision),rootSessionId:typeof t.rootSessionId==`string`?t.rootSessionId:``}}),turns:deserializeRecord(t.turns,e=>{if(!(!isRecord(e)||!isSpanContext(e.context))&&!(typeof e.parentSpanId!=`string`||typeof e.startTimeMs!=`number`))return{context:e.context,modelUsage:deserializeModelUsage(e.modelUsage),parentIsRemote:typeof e.parentIsRemote==`boolean`?e.parentIsRemote:void 0,parentSpanId:e.parentSpanId,rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,sequence:typeof e.sequence==`number`?e.sequence:0,startTimeMs:e.startTimeMs,subagentName:typeof e.subagentName==`string`?e.subagentName:void 0,terminal:deserializeTerminal(e.terminal)}})}:{actions:{},sessions:{},turns:{}}}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 deserializeAction(t){if(!(!isRecord(t)||typeof t.attemptIndex!=`number`||typeof t.callId!=`string`||!isActionKind(t.kind)||typeof t.name!=`string`||!isSpanContext(t.parent)||typeof t.rootSessionId!=`string`||typeof t.sessionId!=`string`||typeof t.spanId!=`string`||typeof t.startTimeMs!=`number`||typeof t.stepIndex!=`number`||typeof t.turnId!=`string`))return{attemptIndex:t.attemptIndex,callId:t.callId,channelAudience:normalizeChannelAudience(t.channelAudience),inputAttribute:typeof t.inputAttribute==`string`?t.inputAttribute:void 0,kind:t.kind,name:t.name,parent:t.parent,rootSessionId:t.rootSessionId,sessionId:t.sessionId,spanId:t.spanId,startTimeMs:t.startTimeMs,stepIndex:t.stepIndex,turnId:t.turnId}}function isActionKind(e){return e===`load-skill`||e===`remote-agent-call`||e===`subagent-call`||e===`tool-call`}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 deserializeTerminal(e){if(!isRecord(e)||typeof e.type!=`string`)return;let t=e.type;if(isTurnTerminalType(t))return t===`turn.failed`?{error:deserializeError(e.error),type:t}:{type:t}}function serializeSpanContext(e){return{isRemote:e.isRemote,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function isSpanContext(e){return isRecord(e)&&typeof e.spanId==`string`&&typeof e.traceFlags==`number`&&typeof e.traceId==`string`}function serializeError(e){return e instanceof Error?{message:e.message,name:e.name,stack:e.stack}:void 0}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 isTurnTerminalType(e){return e===`turn.cancelled`||e===`turn.completed`||e===`turn.failed`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{ContextAgentTraceStateStore,preserveSerializedAgentTraceState,readActionTraceContext,readCurrentSessionTraceDecision,readSessionTraceContext,readSessionTraceDecision};

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-declaration.d.ts

@@ -38,9 +38,11 @@ export interface OtelOptions {
      * existing audience-aware behavior; explicit decisions can disable emission
      * or select input and output capture independently. Defaults to emitting
      * every audience, with content only for public conversations. The result is
-     * an OpenTelemetry capture ceiling: per-delivery audience and destination
-     * settings can only narrow it. It never changes what authored instrumentation
-     * providers receive. A thrown error rejects trace production without
+     * an OpenTelemetry capture ceiling: local delivery audience and destination
+     * settings can only narrow it. For a trusted remote trace, eve evaluates this
+     * policy against the immutable origin audience and intersects it with the
+     * parent's effective ceiling, so every hop can only narrow capture. It never
+     * changes what authored instrumentation providers receive. A thrown error rejects trace production without
      * silencing lifecycle providers. The policy may be invoked more than once
      * while a new session is being prepared, so it must be deterministic for
      * consistent results.

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

@@ -13,9 +13,11 @@ export declare function registerOtelPipeline(input: {
     readonly pipeline: OtelPipeline;
     readonly serviceName: string;
 }): RegisteredOtelPipeline;
-/** Lifecycle retained from the tracer provider that owns every destination. */
+/** Lifecycle retained from the providers that own every destination. */
 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,metrics,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.`);n?.setDelegate(c);let l=runtimeMeterProvider();return{forceFlush:async()=>{await Promise.all([c.forceFlush(),l.forceFlush?.()])},idGenerator:r,samplesTrace:e=>samplerAdmitsTrace(r,e),shutdown:async()=>{disableInstrumentations(t.instrumentations),await Promise.all([c.shutdown(),l.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 runtimeMeterProvider(){let e=metrics.getMeterProvider();return{forceFlush:typeof e?.forceFlush==`function`?()=>e.forceFlush():void 0,shutdown:typeof e?.shutdown==`function`?()=>e.shutdown():void 0}}function disableInstrumentations(e){for(let t of e??[]){let e=t?.disable;if(typeof e==`function`)try{e.call(t)}catch{}}}function globalTracerUses(e){let t=e.allocateSpanId();return e.withSpanId(t,()=>trace.getTracer(`eve.registration`).startSpan(REGISTRATION_SPAN_NAME)).spanContext().spanId===t}function isRegistrationSpan(e){return typeof e==`object`&&!!e&&`name`in e&&e.name===REGISTRATION_SPAN_NAME}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-Bgp6INfi.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-Bgp6INfi.js";
 
 export { useEveAgent };

package/docs/channels/custom.mdx

@@ -405,6 +405,8 @@ defineChannel({
 });
 ```
 
+If `fetchFile` throws, eve replaces that attachment with a model-visible error note and continues the turn. Built-in channels include safe details such as the upstream HTTP status. Custom channel errors use a generic note, while eve keeps the original error in operator logs.
+
 The `URL` object survives the queue boundary as a string and is reconstituted inside the workflow step. The staging pipeline calls `fetchFile` with the URL serialized as a string (the URL's `href`), which is why the example matches on `url.startsWith(...)`. Return bytes to stage the file to the sandbox, or `null` to let the URL pass through to the model provider.
 
 The framework handles staging bytes to the sandbox, enforcing upload policy, hydrating files for the model call, and reconstituting `URL` objects after queue serialization. See [Inbound attachments](../sandbox#inbound-attachments) for the shared storage, size, and provider-input behavior.

package/docs/channels/eve.mdx

@@ -47,6 +47,10 @@ curl -X POST https://<deployment>/eve/v1/session \
 # {"ok":true,"sessionId":"wrun_A","status":"accepted"}
 ```
 
+The `202` response means Workflow accepted the durable run. The command inbox may still be
+starting, so an immediate follow-up or control request can report that the session is not active.
+The event-stream client retries the brief window before the new run becomes readable.
+
 Authenticated callers that may retry a create request can pass their own `operationId` for
 create-once semantics. The same operation under the same authenticated principal returns the
 active session it already created instead of dispatching the input again. The first accepted
@@ -72,7 +76,7 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
 
 Follow-up messages use `turnPolicy: "steer"` by default. If a turn is active, eve buffers the message before cooperatively cancelling that turn, then starts the follow-up as a replacement turn with a new turn ID. Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `inputResponses` never steer.
 
-Sending a message to an unknown or terminal session ID returns `409` with
+Sending a message to an unknown, terminal, or not-yet-active session ID returns `409` with
 `{"code":"session_not_active","error":"The session is no longer active.","ok":false}`.
 TypeScript clients expose the stable code as `ClientError.code`. The route never
 creates or follows a replacement session.

package/docs/channels/teams.mdx

@@ -70,10 +70,15 @@ Inbound files are off by default. Opt in to allow personal-scope downloads and p
 
 ```ts
 export default teamsChannel({
-  files: { enabled: true, allowedHosts: ["contoso.sharepoint.com"] },
+  files: {
+    enabled: true,
+    allowedHosts: ["smba.trafficmanager.net", "contoso.sharepoint.com"],
+  },
 });
 ```
 
+eve authenticates downloads from Microsoft Bot Connector hosts with your bot credentials. Downloads from other allowlisted hosts remain unauthenticated.
+
 ## What to read next
 
 - [Channels overview](./overview): the channel contract and every built-in channel

package/docs/concepts/sessions-runs-and-streaming.md

@@ -32,8 +32,10 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session \
   -d '{"message":"Summarize the latest forecast."}'
 ```
 
-eve responds right away with the durable `sessionId` in the JSON body and
-`x-eve-session-id` header.
+eve responds with `202` and the durable `sessionId` in the JSON body and
+`x-eve-session-id` header as soon as Workflow accepts the run. The command inbox can still be
+starting at that point. An immediate follow-up can return `409 session_not_active`; wait for
+`session.waiting` before sending the next message.
 
 ## Stream a session
 

package/docs/guides/auth-and-route-protection.md

@@ -239,7 +239,11 @@ export default eveChannel({
 
 The predicate authorizes the _forwarder_ (the verified route-auth principal — who is asserting), not the forwarded principal (what is asserted). Match it precisely: a permissive predicate like `() => true` lets any caller that passes route auth assert any principal, including preview deployments of your own project when `vercelOidc()` is in the walk. `trustedForwarders` exists only on your authored channel — the framework default channel never accepts a forwarded principal, so a receiving deployment must author `agent/channels/eve.ts`.
 
-When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller. The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller.
+
+The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+
+For requests marked as remote delegations by a callback body and valid sampled `traceparent`, the same accepted `trustedForwarders` result may admit an origin audience and directional content ceiling from one W3C Baggage member. The assertion is not an authorization grant: the receiver's trace policy independently decides against the immutable origin audience, and the two decisions are intersected. Every later hop forwards only that narrowed result. Malformed, partial, unsampled, or mixed-version assertions become metadata-only. The callback and headers are caller-supplied—the verified transport principal and `trustedForwarders` are the trust boundary. See [Preserving trace content](./remote-agents#preserving-trace-content).
 
 > ⚠️ Both deployments must support continuation forwarding before you resume persistent remote sessions. A create-only receiver rejects a forwarded continuation with HTTP 400; the sender does not fall back to service authority. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity) for the upgrade behavior.
 

package/docs/guides/client/messages.mdx

@@ -36,6 +36,12 @@ console.log(result.status, result.message);
 
 When the stream includes `session.failed`, the turn returns `status: "failed"` rather than throwing. Transport and route errors throw `ClientError`.
 
+`session.send()` retries `409 session_not_active` three times when a durable run has been accepted
+but its command inbox is still starting. The retries wait 250 ms, 500 ms, and 1 second. Other
+errors, `session.respond()`, control methods, and raw HTTP requests do not use this retry. An unknown
+session still throws `ClientError` immediately, while a terminal session throws after the final
+attempt. The client never creates a replacement session.
+
 ## Send a full turn payload
 
 Pass the full payload to `create()` for the first turn or `send()` for a follow-up:

package/docs/guides/dev-tui.md

@@ -13,35 +13,47 @@ The transcript remains in your terminal scrollback after you exit. Run `/help` i
 
 ## Commands
 
-| Command       | Description                                                                                                                                               |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/model`      | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`.                                                     |
-| `/add`        | Browse and install channels, MCP connections, extensions, and observability integrations. Pass an item address to open it directly: `/add channel/slack`. |
-| `/deploy`     | Deploy the agent to Vercel production. Links the directory first if needed.                                                                               |
-| `/vc:install` | Install the Vercel CLI.                                                                                                                                   |
-| `/vc:login`   | Log in to Vercel or restore access to a remote deployment.                                                                                                |
-| `/info`       | Show the resolved application, compiled artifacts, discovery diagnostics, and messaging routes.                                                           |
-| `/loglevel`   | Choose which server and agent logs appear in the transcript.                                                                                              |
-| `/traces`     | Open the local trace viewer. Pass a trace ID prefix to open a specific trace.                                                                             |
-| `/reset`      | Start a fresh session.                                                                                                                                    |
-| `/cancel`     | Cancel the current turn without discarding settled context.                                                                                               |
-| `/clear`      | Clear the session's model-message history. `/new` is an alias.                                                                                            |
-| `/compact`    | Compact the current session's context.                                                                                                                    |
-| `/exit`       | Quit the UI.                                                                                                                                              |
-| `/help`       | List available commands.                                                                                                                                  |
+| Command       | Description                                                                                                                                                              |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/model`      | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`.                                                                    |
+| `/add`        | Select and install channels, MCP connections, extensions, and observability integrations. Pass an item address to confirm and install it directly: `/add channel/slack`. |
+| `/deploy`     | Deploy the agent to Vercel production. Links the directory first if needed.                                                                                              |
+| `/vc:install` | Install the Vercel CLI.                                                                                                                                                  |
+| `/vc:login`   | Log in to Vercel or restore access to a remote deployment.                                                                                                               |
+| `/info`       | Show the resolved application, compiled artifacts, discovery diagnostics, and messaging routes.                                                                          |
+| `/loglevel`   | Choose which server and agent logs appear in the transcript.                                                                                                             |
+| `/traces`     | Open the local trace viewer. Pass a trace ID prefix to open a specific trace.                                                                                            |
+| `/reset`      | Start a fresh session.                                                                                                                                                   |
+| `/cancel`     | Cancel the current turn without discarding settled context.                                                                                                              |
+| `/clear`      | Clear the session's model-message history. `/new` is an alias.                                                                                                           |
+| `/compact`    | Compact the current session's context.                                                                                                                                   |
+| `/exit`       | Quit the UI.                                                                                                                                                             |
+| `/help`       | List available commands.                                                                                                                                                 |
 
 `/model`, `/add`, `/deploy`, `/info`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.
 
+## Set up a new agent
+
+After `eve init`, the terminal UI guides you through **Model**, **Channels**, **Integrations**, and **Review** before the first chat prompt. The progress rail keeps the four steps visible throughout onboarding. Model setup can install or upgrade the Vercel CLI, open Vercel login, and resume project linking without leaving the flow.
+
+Model and Vercel changes take effect when you complete Model, then onboarding continues to Channels. Channel and integration selections remain drafts until you finish Review. You can move back and forth between Channels, Integrations, and Review; use `/model` after onboarding to change the committed model configuration.
+
 ## Add an integration
 
-Bare `/add` opens the categorized registry browser. Pass an item address — `<category>/<name>`, where category is `channel`, `connection`, `extension`, or `instrumentation` — to skip the category and search screens and open that item directly:
+Bare `/add` opens the standalone planner on **Channels**. It does not include model configuration. The progress rail shows selection counts as you move between **Channels**, **Integrations**, and **Review**.
+
+Press `Space` or `Enter` to toggle the highlighted item. Press `Right Arrow` to preserve the current selections and continue, `Left Arrow` to preserve them and go back, or `Esc` to cancel. Installation requires `Enter` on **Install and set up** from Review. During installation, `Esc` cancels only the active item and continues with the remaining selections. The final summary reports installed, cancelled, and failed items separately.
+
+Pass an item address to `/add` to confirm and install that exact address without opening the planner:
 
 ```text
 /add channel/slack
 /add extension/agent-browser
+/add linear
+/add @acme/analytics
 ```
 
-Either way the UI shows the item's details and asks to confirm before installing, then runs the same installation and setup prompts. Choosing **Back** on a directly addressed item returns to the registry browser.
+The UI installs planner selections in order and offers deployment once after the batch when an installed item requires it.
 
 ## Work with the agent
 

package/docs/guides/remote-agents.md

@@ -143,6 +143,31 @@ Forwarding is explicit on both sides. The receiver names which forwarders it tru
 
 A receiver on an eve version that predates all principal forwarding may instead drop the unknown field and run the session as your app's service identity; per-user connections there fail with `principal_required`. On remote requests where the dispatching turn has no auth, the field is omitted and the call proceeds on transport trust alone.
 
+## Preserving trace content
+
+With `forwardPrincipal: true`, a sampled trace carries its original audience and the maximum content the next hop may record. For example, `eve.audience=private;ceiling=i0o1` allows outputs but not inputs. eve sends this as [W3C Baggage](https://www.w3.org/TR/baggage/).
+
+The receiver uses it only after `trustedForwarders` accepts the authenticated calling deployment:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [vercelOidc()],
+  trustedForwarders: (forwarder) =>
+    forwarder.subject === vercelSubject({ teamSlug: "acme", projectName: "router" }),
+});
+```
+
+The request must also include a callback and a valid sampled `traceparent`. Those fields identify a remote call, but they do not establish trust. `trustedForwarders` is the authorization boundary.
+
+The receiver combines the incoming ceiling with its own trace policy. Each hop may narrow the result, but it cannot restore inputs or outputs removed earlier. The original audience stays the same across remote and local subagent hops. Public origins may include content by default; private and unknown origins stay metadata-only unless both deployments explicitly allow them.
+
+The live delivery audience still matters. An unknown callback delivery, or one matching the origin, uses the session decision. A different explicit audience applies its own hard ceiling, so a private delivery stays redacted even when the trace began in public.
+
+Missing, malformed, duplicate, unsampled, untrusted, and mixed-version assertions fall back to metadata-only tracing. Dropped traces use only the unsampled trace flag. The decision is fixed when the remote session starts and reused by continuations. Agent Runs shows Workflow content only when both inputs and outputs are allowed.
+
 ## How remote dispatch and callbacks work
 
 A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:

package/docs/reference/cli.md

@@ -210,7 +210,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 | `-H, --header <header>`             | string | none               | Request header for a URL target, in `Name: value` form; repeat for multiple headers       |
 | `--no-ui`                           | flag   | UI on              | Start the server without an interactive UI                                                |
 | `--name <name>`                     | string | app folder name    | Title shown in the terminal UI                                                            |
-| `--input <text>`                    | string | none               | Pre-fill the prompt input; bare local `/model` starts onboarding                          |
+| `--input <text>`                    | string | none               | Pre-fill the prompt input                                                                 |
 | `--tools <mode>`                    | enum   | `auto-collapsed`   | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
 | `--reasoning <mode>`                | enum   | `full`             | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
 | `--subagents <mode>`                | enum   | `auto-collapsed`   | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`         |
@@ -221,7 +221,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 
 `eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API and accepts the same URL credentials and request headers as `eve dev <url>`. Pass `--scope <team>` when the active Vercel scope does not own the deployment; `EVE_VERCEL_SCOPE` provides the same value for managed harnesses. See [Agent Client Protocol (ACP)](../protocols/acp) for client configuration and capability limits.
 
-A fresh `eve init` passes `--input /model`. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, opens `/model`, then offers categorized registry next steps before the first prompt. Other input stays editable in the prompt.
+A fresh `eve init` starts onboarding before the first prompt: the TUI installs the Vercel CLI if needed, asks you to log in if needed, guides you through model configuration, then lets you choose channels and integrations. Other `--input` text stays editable in the prompt.
 
 For a URL target protected by HTTP Basic auth, put the credentials in the URL. eve sends them as a Basic `Authorization` header and strips them from the server URL before connecting:
 

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/docs/tools/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Tools",
   "defaultOpen": false,
-  "pages": ["overview", "human-in-the-loop"]
+  "pages": ["overview", "human-in-the-loop", "workflows"]
 }

package/docs/tools/overview.mdx

@@ -78,6 +78,13 @@ Later task-triggered parent turns receive fresh state for the same cohort. The m
 to keep related intermediate results silent while any task remains pending. Once every related
 task is terminal, the state includes their outputs so the model can combine the useful results.
 
+### Durable tools
+
+A tool whose `execute` starts with `"use workflow"` runs as a durable Workflow run instead of
+inside the model step. It can wait for a person, a webhook, or a timer for as long as it takes, with
+nothing running in between, and its return value still settles the tool call. See
+[Durable tools](/docs/tools/workflows).
+
 ### The `ctx` parameter
 
 `execute` gets a `ctx` carrying the runtime accessors: