eve 0.34.0 → 0.36.0

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

@@ -1,2 +1,2 @@
-import{ROOT_CONTEXT,SpanStatusCode,context,trace}from"#compiled/@opentelemetry/api/index.js";import{sessionIdempotencyKey}from"#harness/instrumentation-lifecycle.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{SESSION_WINDOW_TURN_LIMIT}from"#tracing/agent-trace-state.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";function createAgentOtelInstrumentation(e){let t=e.recordInputs??!0,d=e.recordOutputs??!0,f=new WeakMap,p=new Map,m=new WeakMap,h=new WeakMap,g=createAgentActionInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:t,recordOutputs:d,resolveParent:async t=>{let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);return n===void 0?void 0:{context:contextFromSpanContext(n.context),spanContext:n.context}},stateStore:e.stateStore,tracer:e.tracer}),_=createAgentApprovalInstrumentation({actionContextFor:g.contextFor,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:t,recordOutputs:d,tracer:e.tracer}),v=createAgentToolInstrumentation({actionContextFor:g.contextFor,idGenerator:e.idGenerator,recordInputs:t,recordOutputs:d,resolveFallback:e=>{let t=p.get(e.scope.attemptId)??e.scope,n=m.get(t)?.step;return n===void 0?void 0:{context:n.context,spanContext:n.span.spanContext()}},tracer:e.tracer}),onSessionStarted=async e=>{await ensureSessionContext(e)},onTurnStarted=async t=>{let n=advanceSessionWindow(t.sessionId,await ensureSessionContext({agentName:void 0,channelKind:void 0,idempotencyKey:sessionIdempotencyKey(t.sessionId),parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId,sessionId:t.sessionId,type:`session.started`})),r={isRemote:!1,spanId:e.idGenerator.deriveSpanId(`turn:${t.idempotencyKey}`),traceFlags:n.context.traceFlags,traceId:n.context.traceId};await e.stateStore.setSession(t.sessionId,{...n,turnsInWindow:n.turnsInWindow+1}),await e.stateStore.setTurn(t.sessionId,t.turnId,{context:r,lineage:t.parentLineage,parentIsRemote:n.context.isRemote,parentSpanId:n.context.spanId,rootSessionId:t.rootSessionId,sequence:t.sequence,startTimeMs:Date.now()})},onStepStarted=async t=>{let i=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);if(i===void 0)return;let a=contextFromSpanContext(i.context),o=trace.getSpan(context.active())?.spanContext(),s=e.tracer.startSpan(`agent.step`,{attributes:{"agent.session.id":t.scope.sessionId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.root.session.id":t.scope.rootSessionId??t.scope.sessionId,"agent.step.attempt":t.scope.attemptIndex,"agent.step.index":t.scope.stepIndex,"agent.turn.id":t.scope.turnId,"agent.name":t.scope.functionId},links:o===void 0||o.traceId===i.context.traceId?void 0:[{attributes:{"eve.link.type":`workflow.delivery`},context:o}]},a);s.addEvent(`step.started`);let c=trace.setSpan(a,s),l=t.operation.operationId,u=e.tracer.startSpan(l,{attributes:{"ai.operation.name":l,"ai.provider.name":t.operation.provider,"ai.request.model":t.operation.modelId}},c);m.set(t.scope,{operation:{context:trace.setSpan(c,u),name:l,span:u},step:{context:c,span:s}}),p.set(t.scope.attemptId,t.scope)},onStepTerminal=async e=>{let t=p.get(e.scope.attemptId)??e.scope;f.delete(t),drainOpenSpans({...e,scope:t}),v.drain(e.scope.attemptId,e.type===`step.attempt.failed`?{error:e.error}:void 0),e.type===`step.attempt.failed`&&await g.failForAttempt(t,e.error),p.delete(e.scope.attemptId);let n=m.get(t);n!==void 0&&(n.step.span.addEvent(e.type===`step.attempt.completed`?`step.completed`:`step.failed`),e.type===`step.attempt.failed`&&(recordError(n.operation.span,e.error),recordError(n.step.span,e.error)),n.operation.span.end(),n.step.span.end(),m.delete(t))},onTurnTerminal=async t=>{(t.type===`turn.cancelled`||t.type===`turn.failed`)&&await g.deleteForTurn(t.sessionId,t.turnId);let n=await e.stateStore.getTurn(t.sessionId,t.turnId);n!==void 0&&await e.stateStore.setTurn(t.sessionId,t.turnId,{...n,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 r=await e.stateStore.getSession(t.sessionId),i=e.idGenerator.withSpanId(n.context.spanId,()=>e.tracer.startSpan(`agent.turn`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":r?.agentName,...parentLineageAttributes(n.lineage),"agent.root.session.id":n.rootSessionId,"agent.session.id":t.sessionId,"agent.session.window":r?.window,"agent.turn.id":t.turnId,"agent.turn.sequence":n.sequence},startTime:n.startTimeMs},contextFromSpanContext({isRemote:n.parentIsRemote??!1,spanId:n.parentSpanId,traceFlags:n.context.traceFlags,traceId:n.context.traceId})));i.addEvent(`turn.started`,void 0,n.startTimeMs),n.terminal!==void 0&&(i.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordError(i,n.terminal.error)),i.end(),await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&(await g.deleteForSession(t.sessionId),await e.stateStore.deleteSession(t.sessionId))},onModelCallStarted=n=>{let i=m.get(n.scope);if(i===void 0)return;i.step.span.setAttribute(`agent.model.id`,n.model.modelId),i.step.span.setAttribute(`agent.model.provider`,n.model.provider);let a=e.tracer.startSpan(modelSpanName(n.model.modelId),{attributes:{"gen_ai.agent.name":n.scope.functionId,"gen_ai.operation.name":`chat`,"gen_ai.provider.name":n.model.provider,"gen_ai.request.model":n.model.modelId}},i.operation.context);if(t&&n.input!==void 0){let e=messagesContentAttribute(n.input.messages);e!==void 0&&a.setAttribute(`ai.prompt.messages`,e);let t=genAiInputMessagesAttribute(n.input.messages);t!==void 0&&a.setAttribute(`gen_ai.input.messages`,t);let r=systemPromptAttribute(n.input.instructions);r!==void 0&&a.setAttribute(`ai.prompt.system`,r);let i=genAiSystemInstructionsAttribute(n.input.instructions);i!==void 0&&a.setAttribute(`gen_ai.system_instructions`,i)}let s={context:trace.setSpan(i.operation.context,a),span:a};getExecutionContexts(n.scope).set(n.idempotencyKey,s.context),getSpanStates(h,n.scope).set(n.idempotencyKey,s)},onModelCallTerminal=e=>{f.get(e.scope)?.delete(e.idempotencyKey);let t=takeSpanState(h,e.scope,e.idempotencyKey);if(t!==void 0){if(e.type===`model.call.failed`)recordError(t.span,e.error);else{setAgentUsage(t.span,e.usage),t.span.setAttribute(`gen_ai.response.finish_reasons`,[e.finishReason]);let n=m.get(e.scope);if(n!==void 0&&setAgentUsage(n.step.span,e.usage),d){t.span.setAttribute(`ai.response.finish_reason`,e.finishReason);let n=e.content??[],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 o=textContentAttribute(n.filter(e=>e.type===`text`).map(e=>e.text).join(``));o!==void 0&&t.span.setAttribute(`ai.response.text`,o);let c=n.filter(e=>e.type===`tool-call`).map(e=>({callId:e.callId,input:e.input,toolName:e.toolName}));if(c.length>0){let e=contentAttribute(c,!1);e!==void 0&&t.span.setAttribute(`ai.response.tool_calls`,e)}let l=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(l.length>0){let e=toolResultsContentAttribute(l);e!==void 0&&t.span.setAttribute(`ai.response.tool_results`,e)}}}t.span.end()}},openSessionWindow=t=>{let n=e.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":t.agentName,"agent.root.session.id":t.rootSessionId,"agent.session.id":t.sessionId,"agent.session.window":t.index,"agent.trace.schema.version":1,...t.previousTraceId===void 0?{}:{"agent.session.window.previous.trace.id":t.previousTraceId}},root:!0});return n.addEvent(t.index===0?`session.started`:`session.window.opened`),n.end(),n.spanContext()},ensureSessionContext=async t=>{let n=await e.stateStore.getSession(t.sessionId);return n===void 0&&(n={agentName:t.agentName,channelKind:t.channelKind,context:t.parentTraceContext===void 0?openSessionWindow({agentName:t.agentName,index:0,rootSessionId:t.rootSessionId,sessionId:t.sessionId}):adoptedSpanContext(t.parentTraceContext),rootSessionId:t.rootSessionId,turnsInWindow:0,window:0},await e.stateStore.setSession(t.sessionId,n)),n},y=createAgentChannelDeliveryInstrumentation({ensureSessionContext,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:t,stateStore:e.stateStore,tracer:e.tracer}),advanceSessionWindow=(e,t)=>{if(t.turnsInWindow<SESSION_WINDOW_TURN_LIMIT)return t;let n=t.window+1;return{...t,context:openSessionWindow({agentName:t.agentName,index:n,previousTraceId:t.context.traceId,rootSessionId:t.rootSessionId,sessionId:e}),turnsInWindow:0,window:n}},onStepMetadata=e=>{let t=m.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.step.span.setAttribute(e,r)};return{hook:{capture:t||d?`content`:`metadata`,events:{...y,"action.completed":g.events[`action.completed`],"action.failed":g.events[`action.failed`],async"action.started"(e,t){await g.events[`action.started`](e,t),await v.actionStarted(e)},..._,"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,...v.events,"turn.cancelled":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted},name:`eve.otel`},runInContext(e,t){let r=p.get(e.scope.attemptId)??e.scope,i=f.get(r),a=e.type===`model.call`?i?.get(e.idempotencyKey):v.contextFor(e.scope.attemptId,e.idempotencyKey);return a===void 0?t():context.with(a,t)}};function getExecutionContexts(e){let t=f.get(e);return t===void 0&&(t=new Map,f.set(e,t)),t}function drainOpenSpans(e){for(let t of h.get(e.scope)?.values()??[])e.type===`step.attempt.failed`&&recordError(t.span,e.error),t.span.end();h.delete(e.scope)}}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 parentLineageAttributes(e){if(e===void 0)return{};let t={"agent.parent.call_id":e.callId,"agent.parent.session.id":e.sessionId,"agent.parent.turn.id":e.turnId};return e.subagentName!==void 0&&(t[`agent.subagent.name`]=e.subagentName),t}function adoptedSpanContext(e){return{isRemote:`isRemote`in e&&e.isRemote===!0,spanId:e.spanId,traceFlags:e.traceFlags,traceId:e.traceId}}function contextFromSpanContext(t){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t))}function readGatewayCost(e){let t=e.gateway;if(!isRecord(t))return;let n={},r=readUsd(t.cost);r!==void 0&&(n[`gen_ai.usage.cost`]=r);let i=readUsd(t.gatewayCost);i!==void 0&&(n[`gen_ai.usage.gateway_cost`]=i);let a=readUsd(t.inputInferenceCost);a!==void 0&&(n[`gen_ai.usage.input_cost`]=a);let o=readUsd(t.outputInferenceCost);return o!==void 0&&(n[`gen_ai.usage.output_cost`]=o),typeof t.generationId==`string`&&t.generationId.length>0&&(n[`gen_ai.generation.id`]=t.generationId),Object.keys(n).length===0?void 0:n}function readUsd(e){if(typeof e!=`string`)return;let t=Number(e);return Number.isFinite(t)?t:void 0}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function modelSpanName(e){return`chat ${e}`}function errorText(e){return e instanceof Error?e.message:e}function recordError(e,n){n instanceof Error?(e.recordException(n),e.setStatus({code:SpanStatusCode.ERROR,message:n.message})):e.setStatus({code:SpanStatusCode.ERROR})}export{createAgentOtelInstrumentation};
+import{ROOT_CONTEXT,SpanStatusCode,context,trace}from"#compiled/@opentelemetry/api/index.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{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{createAgentOtelSessionContext}from"#tracing/agent-otel-session-context.js";function createAgentOtelInstrumentation(e){let t=e.recordInputs??!1,d=e.recordOutputs??!1,f=new WeakMap,p=new Map,m=new WeakMap,h=new WeakMap,g=createAgentActionInstrumentation({frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:t,recordOutputs:d,resolveParent:async t=>{let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);return n===void 0?void 0:{context:contextFromSpanContext(n.context),spanContext:n.context}},stateStore:e.stateStore,tracer:e.tracer}),_=createAgentApprovalInstrumentation({actionContextFor:g.contextFor,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:t,recordOutputs:d,tracer:e.tracer}),v=createAgentToolInstrumentation({actionContextFor:g.contextFor,idGenerator:e.idGenerator,recordInputs:t,recordOutputs:d,resolveFallback:e=>{let t=p.get(e.scope.attemptId)??e.scope,n=m.get(t)?.step;return n===void 0?void 0:{context:n.context,spanContext:n.span.spanContext()}},tracer:e.tracer}),{ensureSessionContext:y,prepareSessionTrace:b,prepareTurnTrace:x}=createAgentOtelSessionContext(e),onSessionStarted=async e=>{await b(e)},onTurnStarted=async e=>{await x(e)},onStepStarted=async t=>{let i=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);if(i===void 0)return;let a=contextFromSpanContext(i.context),o=trace.getSpan(context.active())?.spanContext(),s=e.tracer.startSpan(`agent.step`,{attributes:{"agent.session.id":t.scope.sessionId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.root.session.id":t.scope.rootSessionId??t.scope.sessionId,"agent.step.attempt":t.scope.attemptIndex,"agent.step.index":t.scope.stepIndex,"agent.turn.id":t.scope.turnId,"agent.name":t.scope.functionId},links:o===void 0||o.traceId===i.context.traceId?void 0:[{attributes:{"eve.link.type":`workflow.delivery`},context:o}]},a);s.addEvent(`step.started`);let c=trace.setSpan(a,s),l=t.operation.operationId,u=e.tracer.startSpan(l,{attributes:{"ai.operation.name":l,"ai.provider.name":t.operation.provider,"ai.request.model":t.operation.modelId}},c);m.set(t.scope,{operation:{context:trace.setSpan(c,u),name:l,span:u},step:{context:c,span:s}}),p.set(t.scope.attemptId,t.scope)},onStepTerminal=async e=>{let t=p.get(e.scope.attemptId)??e.scope;f.delete(t),drainOpenSpans({...e,scope:t}),v.drain(e.scope.attemptId,e.type===`step.attempt.failed`?{error:e.error}:void 0),e.type===`step.attempt.failed`&&await g.failForAttempt(t,e.error),p.delete(e.scope.attemptId);let n=m.get(t);n!==void 0&&(n.step.span.addEvent(e.type===`step.attempt.completed`?`step.completed`:`step.failed`),e.type===`step.attempt.failed`&&(recordError(n.operation.span,e.error),recordError(n.step.span,e.error)),n.operation.span.end(),n.step.span.end(),m.delete(t))},onTurnTerminal=async t=>{(t.type===`turn.cancelled`||t.type===`turn.failed`)&&await g.deleteForTurn(t.sessionId,t.turnId);let n=await e.stateStore.getTurn(t.sessionId,t.turnId);n!==void 0&&await e.stateStore.setTurn(t.sessionId,t.turnId,{...n,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 r=await e.stateStore.getSession(t.sessionId),i=e.idGenerator.withSpanId(n.context.spanId,()=>e.tracer.startSpan(`agent.turn`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":r?.agentName,...parentLineageAttributes(n.lineage),"agent.root.session.id":n.rootSessionId,"agent.session.id":t.sessionId,"agent.session.window":r?.window,"agent.turn.id":t.turnId,"agent.turn.sequence":n.sequence},startTime:n.startTimeMs},contextFromSpanContext({isRemote:n.parentIsRemote??!1,spanId:n.parentSpanId,traceFlags:n.context.traceFlags,traceId:n.context.traceId})));i.addEvent(`turn.started`,void 0,n.startTimeMs),n.terminal!==void 0&&(i.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordError(i,n.terminal.error)),i.end(),await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&(await g.deleteForSession(t.sessionId),await e.stateStore.deleteSession(t.sessionId))},onModelCallStarted=n=>{let i=m.get(n.scope);if(i===void 0)return;i.step.span.setAttribute(`agent.model.id`,n.model.modelId),i.step.span.setAttribute(`agent.model.provider`,n.model.provider);let o=e.tracer.startSpan(modelSpanName(n.model.modelId),{attributes:{"gen_ai.agent.name":n.scope.functionId,"gen_ai.operation.name":`chat`,"gen_ai.provider.name":n.model.provider,"gen_ai.request.model":n.model.modelId}},i.operation.context);if(t&&n.input!==void 0){let e=messagesContentAttribute(n.input.messages);e!==void 0&&o.setAttribute(`ai.prompt.messages`,e);let t=genAiInputMessagesAttribute(n.input.messages);t!==void 0&&o.setAttribute(`gen_ai.input.messages`,t);let r=systemPromptAttribute(n.input.instructions);r!==void 0&&o.setAttribute(`ai.prompt.system`,r);let i=genAiSystemInstructionsAttribute(n.input.instructions);i!==void 0&&o.setAttribute(`gen_ai.system_instructions`,i)}let u={context:trace.setSpan(i.operation.context,o),span:o};getExecutionContexts(n.scope).set(n.idempotencyKey,u.context),getSpanStates(h,n.scope).set(n.idempotencyKey,u)},onModelCallTerminal=e=>{f.get(e.scope)?.delete(e.idempotencyKey);let t=takeSpanState(h,e.scope,e.idempotencyKey);if(t!==void 0){if(e.type===`model.call.failed`)recordError(t.span,e.error);else{setAgentUsage(t.span,e.usage),t.span.setAttribute(`gen_ai.response.finish_reasons`,[e.finishReason]);let n=m.get(e.scope);if(n!==void 0&&setAgentUsage(n.step.span,e.usage),d){t.span.setAttribute(`ai.response.finish_reason`,e.finishReason);let n=e.content??[],r=genAiOutputMessagesAttribute(n,e.finishReason);r!==void 0&&t.span.setAttribute(`gen_ai.output.messages`,r);let a=textContentAttribute(n.filter(e=>e.type===`reasoning`).map(e=>e.text).filter(e=>e.trim().length>0).join(`
+`));a!==void 0&&t.span.setAttribute(`ai.response.reasoning`,a);let s=textContentAttribute(n.filter(e=>e.type===`text`).map(e=>e.text).join(``));s!==void 0&&t.span.setAttribute(`ai.response.text`,s);let c=n.filter(e=>e.type===`tool-call`).map(e=>({callId:e.callId,input:e.input,toolName:e.toolName}));if(c.length>0){let e=contentAttribute(c,!1);e!==void 0&&t.span.setAttribute(`ai.response.tool_calls`,e)}let l=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(l.length>0){let e=toolResultsContentAttribute(l);e!==void 0&&t.span.setAttribute(`ai.response.tool_results`,e)}}}t.span.end()}},S=createAgentChannelDeliveryInstrumentation({ensureSessionContext:y,frameworkVersion:e.frameworkVersion,idGenerator:e.idGenerator,recordInputs:t,stateStore:e.stateStore,tracer:e.tracer}),onStepMetadata=e=>{let t=m.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.step.span.setAttribute(e,r)};return{hook:{capture:t||d?`content`:`metadata`,events:{...S,"action.completed":g.events[`action.completed`],"action.failed":g.events[`action.failed`],async"action.started"(e,t){await g.events[`action.started`](e,t),await v.actionStarted(e)},..._,"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,...v.events,"turn.cancelled":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted},name:`eve.otel`},prepareSessionTrace:b,prepareTurnTrace:x,runInContext(e,t){let r=p.get(e.scope.attemptId)??e.scope,i=f.get(r),a=e.type===`model.call`?i?.get(e.idempotencyKey):v.contextFor(e.scope.attemptId,e.idempotencyKey);return a===void 0?t():context.with(a,t)}};function getExecutionContexts(e){let t=f.get(e);return t===void 0&&(t=new Map,f.set(e,t)),t}function drainOpenSpans(e){for(let t of h.get(e.scope)?.values()??[])e.type===`step.attempt.failed`&&recordError(t.span,e.error),t.span.end();h.delete(e.scope)}}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 parentLineageAttributes(e){if(e===void 0)return{};let t={"agent.parent.call_id":e.callId,"agent.parent.session.id":e.sessionId,"agent.parent.turn.id":e.turnId};return e.subagentName!==void 0&&(t[`agent.subagent.name`]=e.subagentName),t}function contextFromSpanContext(t){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t))}function readGatewayCost(e){let t=e.gateway;if(!isRecord(t))return;let n={},r=readUsd(t.cost);r!==void 0&&(n[`gen_ai.usage.cost`]=r);let i=readUsd(t.gatewayCost);i!==void 0&&(n[`gen_ai.usage.gateway_cost`]=i);let a=readUsd(t.inputInferenceCost);a!==void 0&&(n[`gen_ai.usage.input_cost`]=a);let o=readUsd(t.outputInferenceCost);return o!==void 0&&(n[`gen_ai.usage.output_cost`]=o),typeof t.generationId==`string`&&t.generationId.length>0&&(n[`gen_ai.generation.id`]=t.generationId),Object.keys(n).length===0?void 0:n}function readUsd(e){if(typeof e!=`string`)return;let t=Number(e);return Number.isFinite(t)?t:void 0}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function modelSpanName(e){return`chat ${e}`}function errorText(e){return e instanceof Error?e.message:e}function recordError(e,n){n instanceof Error?(e.recordException(n),e.setStatus({code:SpanStatusCode.ERROR,message:n.message})):e.setStatus({code:SpanStatusCode.ERROR})}export{createAgentOtelInstrumentation};

package/dist/src/tracing/agent-otel-session-context.d.ts

@@ -0,0 +1,17 @@
+import type { Tracer } from "#compiled/@opentelemetry/api/index.js";
+import { type InstrumentationSessionStartedEvent, type InstrumentationTraceContext, type InstrumentationTurnStartedEvent } from "#harness/instrumentation/lifecycle.js";
+import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
+import { type AgentSessionTraceState, type AgentTraceStateStore } from "#tracing/agent-trace-state.js";
+interface AgentOtelSessionContextInput {
+    readonly frameworkVersion: string;
+    readonly idGenerator: AgentSpanIdGenerator;
+    readonly stateStore: AgentTraceStateStore;
+    readonly tracer: Tracer;
+}
+interface AgentOtelSessionContext {
+    readonly ensureSessionContext: (event: InstrumentationSessionStartedEvent) => Promise<AgentSessionTraceState>;
+    readonly prepareSessionTrace: (event: InstrumentationSessionStartedEvent) => Promise<InstrumentationTraceContext>;
+    readonly prepareTurnTrace: (event: InstrumentationTurnStartedEvent) => Promise<InstrumentationTraceContext>;
+}
+export declare function createAgentOtelSessionContext(input: AgentOtelSessionContextInput): AgentOtelSessionContext;
+export {};

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

@@ -0,0 +1 @@
+import{sessionIdempotencyKey}from"#harness/instrumentation/lifecycle.js";import{SESSION_WINDOW_TURN_LIMIT}from"#tracing/agent-trace-state.js";function createAgentOtelSessionContext(n){let openSessionWindow=e=>{let t=n.tracer.startSpan(`agent.session`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":n.frameworkVersion,"agent.name":e.agentName,"agent.root.session.id":e.rootSessionId,"agent.session.id":e.sessionId,"agent.session.window":e.index,"agent.trace.schema.version":1,...e.previousTraceId===void 0?{}:{"agent.session.window.previous.trace.id":e.previousTraceId}},root:!0});return t.addEvent(e.index===0?`session.started`:`session.window.opened`),t.end(),t.spanContext()},ensureSessionContext=async e=>{let t=await n.stateStore.getSession(e.sessionId);return t===void 0&&(t={agentName:e.agentName,channelKind:e.channelKind,context:e.parentTraceContext===void 0?openSessionWindow({agentName:e.agentName,index:0,rootSessionId:e.rootSessionId,sessionId:e.sessionId}):adoptedSpanContext(e.parentTraceContext),rootSessionId:e.rootSessionId,turnsInWindow:0,window:0},await n.stateStore.setSession(e.sessionId,t)),t},advanceSessionWindow=(e,n)=>{if(n.turnsInWindow<SESSION_WINDOW_TURN_LIMIT)return n;let r=n.window+1;return{...n,context:openSessionWindow({agentName:n.agentName,index:r,previousTraceId:n.context.traceId,rootSessionId:n.rootSessionId,sessionId:e}),turnsInWindow:0,window:r}};return{ensureSessionContext,prepareSessionTrace:async e=>portableSpanContext((await ensureSessionContext(e)).context),prepareTurnTrace:async t=>{let r=await n.stateStore.getTurn(t.sessionId,t.turnId);if(r!==void 0)return{spanId:r.parentSpanId,traceFlags:r.context.traceFlags,traceId:r.context.traceId};let i=advanceSessionWindow(t.sessionId,await ensureSessionContext({agentName:void 0,channelKind:void 0,idempotencyKey:sessionIdempotencyKey(t.sessionId),parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId,sessionId:t.sessionId,type:`session.started`})),a={isRemote:!1,spanId:n.idGenerator.deriveSpanId(`turn:${t.idempotencyKey}`),traceFlags:i.context.traceFlags,traceId:i.context.traceId};return await n.stateStore.setSession(t.sessionId,{...i,turnsInWindow:i.turnsInWindow+1}),await n.stateStore.setTurn(t.sessionId,t.turnId,{context:a,lineage:t.parentLineage,parentIsRemote:i.context.isRemote,parentSpanId:i.context.spanId,rootSessionId:t.rootSessionId,sequence:t.sequence,startTimeMs:Date.now()}),portableSpanContext(i.context)}}}function portableSpanContext(e){return{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}}export{createAgentOtelSessionContext};

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

@@ -1,4 +1,4 @@
 import type { Span } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationUsage } from "#harness/instrumentation-lifecycle.js";
+import type { InstrumentationUsage } from "#harness/instrumentation/lifecycle.js";
 /** Applies eve's structural token usage attributes to an agent span. */
 export declare function setAgentUsage(span: Span, usage: InstrumentationUsage): void;

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

@@ -1,5 +1,5 @@
 import { type Context, type SpanContext, type Tracer } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationActionStartedEvent, InstrumentationToolCallStartedEvent, InstrumentationToolCallTerminalEvent } from "#harness/instrumentation-lifecycle.js";
+import type { InstrumentationActionStartedEvent, InstrumentationToolCallStartedEvent, InstrumentationToolCallTerminalEvent } from "#harness/instrumentation/lifecycle.js";
 import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
 import type { AgentActionContext } from "#tracing/agent-action-instrumentation.js";
 export interface AgentToolInstrumentation {

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

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

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

@@ -1,5 +1,5 @@
 import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationActionKind, InstrumentationParentLineage, InstrumentationTraceContext, InstrumentationTurnFailedEvent, InstrumentationTurnSettledEvent } from "#harness/instrumentation-lifecycle.js";
+import type { InstrumentationActionKind, InstrumentationParentLineage, InstrumentationTraceContext, InstrumentationTurnFailedEvent, InstrumentationTurnSettledEvent } from "#harness/instrumentation/lifecycle.js";
 /** Sized so an ordinary session stays one trace and only an outsized one rolls. */
 export declare const SESSION_WINDOW_TURN_LIMIT = 200;
 export interface AgentSessionTraceState {

package/dist/src/tracing/install-instrumentation-runtime.d.ts

@@ -1,5 +1,5 @@
-import { type InstrumentationProviderDefinition } from "#harness/instrumentation-lifecycle.js";
-import { type InstrumentationRuntime } from "#harness/instrumentation-runtime.js";
+import { type InstrumentationProviderDefinition } from "#harness/instrumentation/lifecycle.js";
+import { type InstrumentationRuntime } from "#harness/instrumentation/runtime.js";
 import type { CollectedOtel } from "#tracing/otel-declaration.js";
 /**
  * Installs the process instrumentation runtime around a collected pipeline.

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"#harness/instrumentation-runtime.js";import{trace}from"#compiled/@opentelemetry/api/index.js";import{createInstrumentationHooks}from"#harness/instrumentation-lifecycle.js";import{hasSessionRelease}from"#tracing/local-traces.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{registerOtelPipeline}from"#tracing/otel-registration.js";const log=createLogger(`tracing.install-instrumentation-runtime`);function installInstrumentationRuntime(e){let t=[],a=[],o,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)});t.push({...r.hook,stateNamespace:`internal:otel`}),runInContext=r.runInContext;let i=e.collected.pipeline.spanProcessors.filter(isSpanProcessor).filter(hasSessionRelease);i.length>0&&a.push(sessionReleaseProvider(i))}let s=[...t,...e.providers,...a],c;return registerInstrumentationRuntime({forceFlush:()=>settleAll([...o===void 0?[]:[o.forceFlush],...s.map(e=>()=>e.flush?.())]),hooks:createInstrumentationHooks({parallel:e.providers,serialAfter:a,serialBefore:t}),otelSettings:e.collected.declared?e.collected.settings:void 0,runInContext,shutdown:()=>(c??=settleAll([...o===void 0?[]:[o.shutdown],...s.map(e=>()=>e.shutdown?.())]),c)})}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"#harness/instrumentation/runtime.js";import{trace}from"#compiled/@opentelemetry/api/index.js";import{createInstrumentationHooks}from"#harness/instrumentation/lifecycle.js";import{hasSessionRelease}from"#tracing/local-traces.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{registerOtelPipeline}from"#tracing/otel-registration.js";const log=createLogger(`tracing.install-instrumentation-runtime`);function installInstrumentationRuntime(e){let t=[],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)});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}),otelSettings:e.collected.declared?e.collected.settings:void 0,prepareSessionTrace:s,prepareTurnTrace:c,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};

package/dist/src/tracing/local-instrumentation-runtime.d.ts

@@ -1,4 +1,4 @@
-import { type InstrumentationRuntime } from "#harness/instrumentation-runtime.js";
+import { type InstrumentationRuntime } from "#harness/instrumentation/runtime.js";
 /** Installs the zero-config local OTel runtime once in an `eve dev` worker. */
 export declare function installLocalInstrumentationRuntime(input: {
     readonly appRoot: string;

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

@@ -1 +1 @@
-import{getInstrumentationRuntime}from"#harness/instrumentation-runtime.js";import{installInstrumentationRuntime}from"#tracing/install-instrumentation-runtime.js";import{collectOtelPipeline,otel,otelIntegration}from"#tracing/otel-declaration.js";import{createLocalTracesProcessor,resolveLocalTracesContent}from"#tracing/local-traces.js";function installLocalInstrumentationRuntime(e){let t=getInstrumentationRuntime();if(t!==void 0)return t;let n=createLocalTracesProcessor({appRoot:e.appRoot});return installInstrumentationRuntime({collected:collectOtelPipeline([otel(),otelIntegration({...resolveLocalTracesContent(),spanProcessors:[n]})]),frameworkVersion:e.frameworkVersion,providers:[],serviceName:e.serviceName})}export{installLocalInstrumentationRuntime};
+import{getInstrumentationRuntime}from"#harness/instrumentation/runtime.js";import{installInstrumentationRuntime}from"#tracing/install-instrumentation-runtime.js";import{collectOtelPipeline,otel,otelIntegration}from"#tracing/otel-declaration.js";import{createLocalTracesProcessor,resolveLocalTracesContent}from"#tracing/local-traces.js";function installLocalInstrumentationRuntime(e){let t=getInstrumentationRuntime();if(t!==void 0)return t;let n=createLocalTracesProcessor({appRoot:e.appRoot});return installInstrumentationRuntime({collected:collectOtelPipeline([otel(),otelIntegration({...resolveLocalTracesContent(),spanProcessors:[n]})]),frameworkVersion:e.frameworkVersion,providers:[],serviceName:e.serviceName})}export{installLocalInstrumentationRuntime};

package/dist/src/tracing/local-traces.d.ts

@@ -41,9 +41,9 @@ export declare function createLocalTracesProcessor(input?: {
  * The local spool's content policy: its options, intersected with
  * `EVE_TRACES_CONTENT`.
  *
- * The variable used to be the process-wide switch. It now applies to this one
- * destination, and only ever narrows — `off` still wins where it applies, but
- * it no longer decides what a hosted backend beside it receives.
+ * The variable applies to this destination only. `on` opts the zero-config
+ * spool into content, while `off` overrides authored local options without
+ * changing what a hosted backend beside it receives.
  *
  * @internal
  */

package/dist/src/tracing/local-traces.js

@@ -1 +1 @@
-import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";function hasSessionRelease(e){return typeof e.releaseSession==`function`}function createLocalTracesProcessor(n={}){let r=n.appRoot??process.env.EVE_DEV_WORKER_APP_ROOT;if(r===void 0)return inertLocalTracesProcessor();let i=resolveLocalTraceRetentionSettings(),a=new AgentTraceSpanProcessor(i.enabled?[new LocalTraceSpanProcessor(r)]:[]),requestPrune=()=>{i.enabled&&requestLocalTraceStorePrune({activeTraceIds:a.activeTraceIds(),appRoot:r,maxAgeMs:i.maxAgeMs,maxTotalBytes:i.maxTotalBytes,retainCount:i.retainCount})};return requestPrune(),{forceFlush:()=>a.forceFlush(),onEnd:e=>a.onEnd(e),onStart:(e,t)=>a.onStart(e,t),async releaseSession(e){return await a.forceFlush(),a.releaseSession(e)?(requestPrune(),!0):!1},shutdown:()=>a.shutdown()}}function resolveLocalTracesContent(e={}){let t=process.env.EVE_TRACES_CONTENT!==`off`;return{recordInputs:t&&e.recordInputs!==!1,recordOutputs:t&&e.recordOutputs!==!1}}function inertLocalTracesProcessor(){return{forceFlush:async()=>void 0,onEnd:()=>void 0,onStart:()=>void 0,releaseSession:async()=>!1,shutdown:async()=>void 0}}export{createLocalTracesProcessor,hasSessionRelease,resolveLocalTracesContent};
+import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";function hasSessionRelease(e){return typeof e.releaseSession==`function`}function createLocalTracesProcessor(r={}){let i=r.appRoot??process.env.EVE_DEV_WORKER_APP_ROOT;if(i===void 0)return inertLocalTracesProcessor();let a=resolveLocalTraceRetentionSettings(),o=new AgentTraceSpanProcessor(a.enabled?[new LocalTraceSpanProcessor(i)]:[]),requestPrune=()=>{a.enabled&&requestLocalTraceStorePrune({activeTraceIds:o.activeTraceIds(),appRoot:i,maxAgeMs:a.maxAgeMs,maxTotalBytes:a.maxTotalBytes,retainCount:a.retainCount})};return requestPrune(),{forceFlush:()=>o.forceFlush(),onEnd:e=>o.onEnd(e),onStart:(e,t)=>o.onStart(e,t),async releaseSession(e){return await o.forceFlush(),o.releaseSession(e)?(requestPrune(),!0):!1},shutdown:()=>o.shutdown()}}function resolveLocalTracesContent(e={}){let t=process.env.EVE_TRACES_CONTENT===`on`,n=process.env.EVE_TRACES_CONTENT!==`off`;return{recordInputs:n&&(e.recordInputs??t),recordOutputs:n&&(e.recordOutputs??t)}}function inertLocalTracesProcessor(){return{forceFlush:async()=>void 0,onEnd:()=>void 0,onStart:()=>void 0,releaseSession:async()=>!1,shutdown:async()=>void 0}}export{createLocalTracesProcessor,hasSessionRelease,resolveLocalTracesContent};

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

@@ -49,9 +49,9 @@ export interface OtelOptions {
  * longer have to agree.
  */
 export interface ContentOptions {
-    /** Record model prompts and tool call inputs. Defaults to `true`. */
+    /** Record model prompts and tool call inputs. Defaults to `false`. */
     readonly recordInputs?: boolean;
-    /** Record model responses and tool call outputs. Defaults to `true`. */
+    /** Record model responses and tool call outputs. Defaults to `false`. */
     readonly recordOutputs?: boolean;
 }
 /** Where one `otelIntegration()` sends spans, and what it records. */

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

@@ -1 +1 @@
-import{PROVIDER}from"#public/instrumentation/provider.js";import{batchSpanProcessor}from"#tracing/batch-span-processor.js";import{contentFilteringProcessor}from"#tracing/content-span-processor.js";import{vercelRuntimeSpanProcessor}from"#tracing/vercel-runtime-span-exporter.js";const OTEL_DECLARATION=Symbol.for(`eve.instrumentation.otel`),OTEL_INTEGRATION=Symbol.for(`eve.instrumentation.otel-integration`);function otel(t={}){return{[OTEL_DECLARATION]:!0,[PROVIDER]:!0,options:t}}function otelIntegration(r={}){let i={recordInputs:r.recordInputs!==!1,recordOutputs:r.recordOutputs!==!1},o=r.spanProcessors??[],s=r.traceExporter===void 0?o:[...o,batchSpanProcessor(r.traceExporter)];return{[OTEL_INTEGRATION]:!0,[PROVIDER]:!0,content:i,spanProcessors:i.recordInputs&&i.recordOutputs?s:s.map(e=>contentFilteringProcessor(e,i))}}function agentRunsIntegration(t={}){let i=resolveContentOptions(t);return{[OTEL_INTEGRATION]:!0,[PROVIDER]:!0,content:i,spanProcessors:i.recordInputs&&i.recordOutputs?[`auto`]:[contentFilteringProcessor(vercelRuntimeSpanProcessor(),i)]}}function resolveContentOptions(e){return{recordInputs:e.recordInputs!==!1,recordOutputs:e.recordOutputs!==!1}}function isOtelDeclaration(e){return typeof e==`object`&&!!e&&e[OTEL_DECLARATION]===!0}function isOtelIntegration(e){return typeof e==`object`&&!!e&&e[OTEL_INTEGRATION]===!0}function collectOtelPipeline(e){let t=[],n,r=!1,i=!1,a=!1;for(let o of e){if(isOtelIntegration(o)){r=!0,i||=o.content.recordInputs,a||=o.content.recordOutputs,t.push(...o.spanProcessors);continue}if(isOtelDeclaration(o)){if(n!==void 0)throw Error("Instrumentation declares `otel()` more than once. One process has one OpenTelemetry tracer provider, so it has one resource, one sampler, and one propagator set — declare them in a single `otel()`.");r=!0,n=o}}let o=n?.options??{};return{declared:r,pipeline:{propagators:o.propagators,resource:o.resource,sampler:o.sampler,spanProcessors:t},settings:{functionId:o.functionId,recordInputs:i,recordOutputs:a,traceChannelRequests:o.traceChannelRequests===!0}}}export{agentRunsIntegration,collectOtelPipeline,isOtelDeclaration,isOtelIntegration,otel,otelIntegration,resolveContentOptions};
+import{PROVIDER}from"#public/instrumentation/provider.js";import{batchSpanProcessor}from"#tracing/batch-span-processor.js";import{contentFilteringProcessor}from"#tracing/content-span-processor.js";import{vercelRuntimeSpanProcessor}from"#tracing/vercel-runtime-span-exporter.js";const OTEL_DECLARATION=Symbol.for(`eve.instrumentation.otel`),OTEL_INTEGRATION=Symbol.for(`eve.instrumentation.otel-integration`);function otel(t={}){return{[OTEL_DECLARATION]:!0,[PROVIDER]:!0,options:t}}function otelIntegration(r={}){let i={recordInputs:r.recordInputs===!0,recordOutputs:r.recordOutputs===!0},o=r.spanProcessors??[],s=r.traceExporter===void 0?o:[...o,batchSpanProcessor(r.traceExporter)];return{[OTEL_INTEGRATION]:!0,[PROVIDER]:!0,content:i,spanProcessors:i.recordInputs&&i.recordOutputs?s:s.map(e=>contentFilteringProcessor(e,i))}}function agentRunsIntegration(t={}){let i=resolveContentOptions(t);return{[OTEL_INTEGRATION]:!0,[PROVIDER]:!0,content:i,spanProcessors:i.recordInputs&&i.recordOutputs?[`auto`]:[contentFilteringProcessor(vercelRuntimeSpanProcessor(),i)]}}function resolveContentOptions(e){return{recordInputs:e.recordInputs===!0,recordOutputs:e.recordOutputs===!0}}function isOtelDeclaration(e){return typeof e==`object`&&!!e&&e[OTEL_DECLARATION]===!0}function isOtelIntegration(e){return typeof e==`object`&&!!e&&e[OTEL_INTEGRATION]===!0}function collectOtelPipeline(e){let t=[],n,r=!1,i=!1,a=!1;for(let o of e){if(isOtelIntegration(o)){r=!0,i||=o.content.recordInputs,a||=o.content.recordOutputs,t.push(...o.spanProcessors);continue}if(isOtelDeclaration(o)){if(n!==void 0)throw Error("Instrumentation declares `otel()` more than once. One process has one OpenTelemetry tracer provider, so it has one resource, one sampler, and one propagator set — declare them in a single `otel()`.");r=!0,n=o}}let o=n?.options??{};return{declared:r,pipeline:{propagators:o.propagators,resource:o.resource,sampler:o.sampler,spanProcessors:t},settings:{functionId:o.functionId,recordInputs:i,recordOutputs:a,traceChannelRequests:o.traceChannelRequests===!0}}}export{agentRunsIntegration,collectOtelPipeline,isOtelDeclaration,isOtelIntegration,otel,otelIntegration,resolveContentOptions};

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-FJkEMXYk.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CnppTEFk.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-FJkEMXYk.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-CnppTEFk.js";
 
 export { useEveAgent };

package/docs/README.md

@@ -34,26 +34,24 @@ Casing convention:
 Read in this order:
 
 1. [Getting Started](./getting-started.mdx)
-2. [Installation](./installation.mdx)
-3. [Project Structure](./project-structure.mdx)
-4. [Project Layout](./reference/project-layout.md)
-5. [`agent.ts`](./agent-config.md)
-6. [TypeScript API](./reference/typescript-api.md)
-7. [Context Control](./concepts/context-control.md)
-8. [Skills](./skills.mdx)
-9. [Tools](./tools/overview.mdx)
-10. [Connections](./connections/overview.mdx)
-11. [Sandboxes](./sandbox.mdx)
-12. [Channels](./channels/overview.mdx)
-13. [Session Context](./reference/typescript-api.md)
-14. [Sessions And Streaming](./concepts/sessions-runs-and-streaming.md)
-15. [TypeScript SDK](./guides/client/overview.mdx)
-16. [Subagents](./subagents.mdx)
-17. [Schedules](./schedules.mdx)
-18. [Evals](./evals/overview.mdx)
-19. [Auth And Route Protection](./guides/auth-and-route-protection.md)
-20. [Vercel Deployment](./guides/deployment/overview.md)
-21. [CLI, Build, And Debugging](./reference/cli.md)
+2. [Tutorial](./tutorial/first-agent.mdx)
+3. [Agents](./agent-config.md)
+4. [TypeScript API Reference](./reference/typescript-api.md)
+5. [Context Control](./concepts/context-control.md)
+6. [Skills](./skills.mdx)
+7. [Tools](./tools/overview.mdx)
+8. [Connections](./connections/overview.mdx)
+9. [Sandboxes](./sandbox.mdx)
+10. [Channels](./channels/overview.mdx)
+11. [Session Context](./guides/session-context.md)
+12. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md)
+13. [Client SDK](./guides/client/overview.mdx)
+14. [Subagents](./subagents/index.mdx)
+15. [Schedules](./schedules.mdx)
+16. [Evals](./evals/overview.mdx)
+17. [Authentication](./guides/auth-and-route-protection.md)
+18. [Deployment](./guides/deployment/overview.md)
+19. [CLI](./reference/cli.md)
 
 ## The public mental model
 

package/docs/agent-config.md

@@ -1,9 +1,9 @@
 ---
-title: "agent.ts"
-description: "Set the agent's runtime config in agent.ts with defineAgent, including the model, reasoning effort, and compaction."
+title: "Agents"
+description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
 ---
 
-An agent's `agent.ts` calls `defineAgent` (from `eve`) to set its runtime config.
+An eve app has one root agent assembled from the files under `agent/`. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
 
 ## Set the model
 
@@ -22,7 +22,10 @@ project root with `eve set --model anthropic/claude-opus-4.8` or from the local
 dev TUI with `/model anthropic/claude-opus-4.8`.
 
 The root `agent.ts` can be omitted when no runtime config is needed. In that case, eve defaults
-to `anthropic/claude-sonnet-5`. When `agent.ts` is present, `model` is required.
+to `zai/glm-5.2`. GLM 5.2 does not support image input; choose a
+vision-capable model or [route image inputs to Gemini
+Flash](./guides/dynamic-capabilities#route-image-inputs-to-a-vision-model).
+When `agent.ts` is present, `model` is required.
 
 `model` accepts a gateway model id string, which routes through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). To call a provider directly and configure the model in code, pass a provider-authored `LanguageModel`.
 
@@ -229,7 +232,7 @@ installed package must stay external in hosted output, list it in
 
 ## Other defineAgent fields
 
-`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
+`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
 
 | Field          | Type                                    | Default          | Description                                                                                                                                                                                                   |
 | -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -257,5 +260,5 @@ During `eve dev`, ordinary dependencies are bundled into each retained runtime g
 ## What to read next
 
 - [Default harness](./concepts/default-harness) for the loop and built-in tools this config drives
-- [TypeScript API](./reference/typescript-api) for every `defineAgent` field and type
+- [TypeScript API Reference](./reference/typescript-api) for every `defineAgent` field and type
 - [Subagents](./subagents) for the `description` requirement and child-agent config

package/docs/channels/custom.mdx

@@ -388,7 +388,7 @@ defineChannel({
 
 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.
+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.
 
 ## What to read next
 

package/docs/channels/eve.mdx

@@ -36,15 +36,13 @@ The session routes use only durable session IDs. Create a session explicitly, th
 
 ### Start and continue a session
 
+Start a session with an initial message, then use the returned `sessionId` for every follow-up and control operation:
+
 ```bash
 curl -X POST https://<deployment>/eve/v1/session \
   -H "Content-Type: application/json" \
   -d '{"message":"What is the weather in Paris?"}'
 # {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-
-curl -X POST https://<deployment>/eve/v1/session/wrun_A \
-  -H "Content-Type: application/json" \
-  -d '{"message":"How about tomorrow?"}'
 ```
 
 The first request requires `message`. A follow-up request accepts exactly one of
@@ -65,69 +63,25 @@ creates or follows a replacement session.
 
 ### Stream events
 
-Stream responses are newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:
-
-```bash
-curl -N https://<deployment>/eve/v1/session/wrun_A/stream
-# {"type":"turn.started",...}
-# {"type":"message.appended","data":{"messageDelta":"It is ",...}}
-# {"type":"message.completed",...}
-```
+Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
 
 ### Cancel a turn
 
-Cancel a session's in-flight turn with an empty body, or scope the cancel to the turn you observed by passing the `turnId` stamped on that turn's stream events:
+Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.cancelled` followed by `session.waiting`.
 
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/cancel
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-Cancellation is asynchronous: `"accepted"` means the live session durably queued the request. Confirm an actual cancellation on the stream as `turn.cancelled` followed by `session.waiting`—never as a failure. Active local and remote subagents are cancelled recursively before the parent settles. Content emitted before cancellation stays on the event stream, while durable model history keeps only content that had already settled. The session accepts the next message normally.
-
-An accepted cancellation returns HTTP `202` with `sessionId`. An inactive target
-returns HTTP `200` with `{"ok":true,"status":"no_active_turn"}`.
-
-A live session also returns `"accepted"` when it is already parked; the driver consumes that late or duplicate cancel as a no-op. An unknown or terminal session returns `"no_active_turn"`. A `turnId` naming any other turn is likewise accepted and consumed as a no-op, so a guarded cancel racing a turn boundary cannot stop a turn the caller never saw.
+See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for response statuses, HTTP status codes, subagent cancellation, and race behavior.
 
 ### Clear context
 
-Clear one session's model-message history without replacing the session:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/clear
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-An accepted clear emits `context.cleared` followed by `session.waiting`. The next message uses the same session without prior model messages; the system prompt, tools, skills, durable state, limits, and session-scoped sandbox remain.
+Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ### Compact context
 
-Compact one session's context without sending a message:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/compact
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-Compaction is asynchronous. A successful operation emits `compaction.requested` and `compaction.completed`, then returns through `session.waiting`. When a turn is active, compaction waits for it to settle. If summarization fails, the session still returns to `session.waiting` with its previous history.
+Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ### Reset a session
 
-Reset terminally retires the exact session ID:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/reset \
-  -H "Content-Type: application/json" \
-  -d '{"reason":"Start over"}'
-# {"ok":true,"previousSessionId":"wrun_A","status":"reset"}
-```
-
-After reset, the old ID cannot accept another message. Start a replacement explicitly with `POST /eve/v1/session`.
-
-The control routes never create sessions. `compact`, `clear`, and `reset` return `"no_active_session"` when the ID is already inactive. Session message and control request/response bodies do not accept or return continuation tokens. For compatibility, the streamed `session.waiting` event retains `data.continuationToken`: it is the channel-local token for a channel-addressed session and the immutable session ID for an ID-only session. New clients should continue through their fixed session handle instead of reading this field.
-
-See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the complete event set, operation results, and cursor behavior.
+Post to `/eve/v1/session/:sessionId/reset` to terminally retire that session. Reset never replaces the ID automatically; create a new session explicitly for a fresh conversation. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ## CORS
 
@@ -199,11 +153,11 @@ always dispatches and therefore always produces or continues a session.
 
 The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.
 
-For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
+For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
 
 ## What to read next
 
 - [Frontend](../guides/frontend/overview): drive the eve channel from browser UI with `useEveAgent`
-- [TypeScript SDK](../guides/client/overview): call the eve channel from TypeScript
+- [Client SDK](../guides/client/overview): call the eve channel from TypeScript
 - [Auth & route protection](../guides/auth-and-route-protection): the route auth policy
 - [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the routes this channel exposes

package/docs/channels/github.mdx

@@ -58,7 +58,7 @@ GITHUB_WEBHOOK_SECRET=...    # verifies the webhook signature
 GITHUB_APP_SLUG=...          # supplies botName when it is not set in config
 ```
 
-`appId`/`privateKey`/`webhookSecret` also take a lazy resolver function if you'd rather fetch them on demand.
+`appId`/`privateKey`/`webhookSecret` also take a lazy resolver function if you'd rather fetch them on demand, and so does `botName`: it resolves on first use inside request handling, caches on success, and retries on the next event after a failure, so a resolver that depends on request-scoped credentials works in production. When `botName` is not configured, the channel falls back to the credentials' `appSlug`, then to `GITHUB_APP_SLUG`.
 
 Point the GitHub App webhook URL at `https://<deployment>/eve/v1/github`. For comment-invoked turns, subscribe to `issue_comment` and `pull_request_review_comment`; add `issues`, `pull_request`, `check_suite`, `check_run`, or `workflow_run` if you wire up their opt-in hooks. After installing the App for the repository, a new comment that includes `@botName` starts a turn. This is a text invocation token, not a GitHub-native mention: GitHub may display the App as `botName[bot]`, but it may not autocomplete or link `@botName`.
 

package/docs/channels/meta.json

@@ -1,5 +1,6 @@
 {
   "title": "Channels",
+  "defaultOpen": false,
   "pages": [
     "overview",
     "eve",