eve 0.29.2 → 0.29.3

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

@@ -0,0 +1,2 @@
+import{ROOT_CONTEXT,SpanStatusCode,context,trace}from"#compiled/@opentelemetry/api/index.js";import{contentAttribute,messagesContentAttribute,systemPromptAttribute,textContentAttribute,toolResultsContentAttribute}from"#tracing/agent-otel-content.js";const SESSION_WINDOW_TURN_LIMIT=200;var InMemoryAgentTraceStateStore=class{#e=new Map;#t=new Map;deleteSession(e){this.#e.delete(e)}deleteTurn(e,t){this.#t.delete(turnKey(e,t))}getSession(e){return this.#e.get(e)}getTurn(e,t){return this.#t.get(turnKey(e,t))}setSession(e,t){this.#e.set(e,t)}setTurn(e,t,n){this.#t.set(turnKey(e,t),n)}};function createAgentOtelInstrumentation(e){let t=e.captureContent??!0,l=new WeakMap,u=new WeakMap,onSessionStarted=async e=>{await ensureSessionContext(e)},onTurnStarted=async t=>{let n=advanceSessionWindow(t.sessionId,await ensureSessionContext({agentName:void 0,channelKind:void 0,parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId,sessionId:t.sessionId,type:`session.started`})),r=e.tracer.startSpan(`agent.turn`,{attributes:{"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.name":n.agentName,...parentLineageAttributes(t.parentLineage),"agent.root.session.id":t.rootSessionId,"agent.session.id":t.sessionId,"agent.session.window":n.window,"agent.turn.id":t.turnId,"agent.turn.sequence":t.sequence}},contextFromSpanContext(n.context));r.addEvent(`turn.started`),await e.stateStore.setSession(t.sessionId,{...n,turnsInWindow:n.turnsInWindow+1}),await e.stateStore.setTurn(t.sessionId,t.turnId,{context:r.spanContext(),rootSessionId:t.rootSessionId,sequence:t.sequence}),r.end()},onAttemptStarted=async t=>{let n=await e.stateStore.getTurn(t.scope.sessionId,t.scope.turnId);if(n===void 0)return;let i=contextFromSpanContext(n.context),a=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}},i);a.addEvent(`step.started`);let o=trace.setSpan(i,a),s=t.operation.operationId,c=e.tracer.startSpan(s,{attributes:{"gen_ai.operation.name":s,"gen_ai.provider.name":t.operation.provider,"gen_ai.request.model":t.operation.modelId}},o);u.set(t.scope,{operation:{context:trace.setSpan(o,c),name:s,span:c},step:{context:o,span:a}})},onAttemptTerminal=e=>{l.delete(e.scope);let t=u.get(e.scope);t!==void 0&&(t.step.span.addEvent(e.type===`attempt.completed`?`step.completed`:`step.failed`),e.type===`attempt.failed`&&(recordError(t.operation.span,e.error),recordError(t.step.span,e.error)),t.operation.span.end(),t.step.span.end(),u.delete(e.scope))},onTurnTerminal=async t=>{let n=await e.stateStore.getTurn(t.sessionId,t.turnId);n!==void 0&&await e.stateStore.setTurn(t.sessionId,t.turnId,{...n,terminal:{error:t.error,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=e.tracer.startSpan(`agent.turn.terminal`,{attributes:{"agent.root.session.id":n.rootSessionId,"agent.session.id":t.sessionId,"agent.turn.id":t.turnId,"agent.turn.sequence":n.sequence}},contextFromSpanContext(n.context));n.terminal!==void 0&&(r.addEvent(n.terminal.type),n.terminal.type===`turn.failed`&&recordError(r,n.terminal.error)),r.addEvent(t.type),r.end(),await e.stateStore.deleteTurn(t.sessionId,t.turnId)}}(t.type===`session.completed`||t.type===`session.failed`)&&await e.stateStore.deleteSession(t.sessionId)},beforeModelCall=n=>{let i=u.get(n.scope);if(i===void 0)return;i.step.span.setAttribute(`agent.model.id`,n.source.modelId),i.step.span.setAttribute(`agent.model.provider`,n.source.provider);let s=e.tracer.startSpan(modelSpanName(i.operation.name),{attributes:{"gen_ai.operation.name":i.operation.name,"gen_ai.provider.name":n.source.provider,"gen_ai.request.model":n.source.modelId}},i.operation.context);if(t){let e=messagesContentAttribute(n.source.messages);e!==void 0&&s.setAttribute(`ai.prompt.messages`,e);let t=systemPromptAttribute(n.source.instructions);t!==void 0&&s.setAttribute(`ai.prompt.system`,t)}let c={context:trace.setSpan(i.operation.context,s),span:s};return getExecutionContexts(n.scope).models.set(n.id,c.context),c},afterModelCall=(e,n)=>{if(l.get(e.scope)?.models.delete(e.id),isSpanState(n)){if(e.type===`model.call.failed`)recordError(n.span,e.error);else{setUsage(n.span,e.source.usage);let r=u.get(e.scope);if(r!==void 0&&setUsage(r.step.span,e.source.usage),t){n.span.setAttribute(`ai.response.finish_reason`,e.source.finishReason);let t=textContentAttribute(e.source.content.filter(e=>e.type===`reasoning`).map(e=>e.text).filter(e=>e.trim().length>0).join(`
+`));t!==void 0&&n.span.setAttribute(`ai.response.reasoning`,t);let r=textContentAttribute(e.source.content.filter(e=>e.type===`text`).map(e=>e.text).join(``));r!==void 0&&n.span.setAttribute(`ai.response.text`,r);let a=e.source.content.filter(e=>e.type===`tool-call`).map(e=>({input:e.input,toolName:e.toolName}));if(a.length>0){let e=contentAttribute(a,!1);e!==void 0&&n.span.setAttribute(`ai.response.tool_calls`,e)}let o=e.source.content.filter(e=>e.type===`tool-result`||e.type===`tool-error`).map(e=>e.type===`tool-result`?{input:e.input,output:e.output,toolName:e.toolName}:{error:errorText(e.error),input:e.input,toolName:e.toolName});if(o.length>0){let e=toolResultsContentAttribute(o);e!==void 0&&n.span.setAttribute(`ai.response.tool_results`,e)}}}n.span.end()}},beforeToolCall=n=>{let a=u.get(n.scope);if(a===void 0)return;let o=e.tracer.startSpan(`agent.action`,{attributes:{"agent.action.call_id":n.source.toolCall.toolCallId,"agent.action.kind":`tool`,"agent.action.name":n.source.toolCall.toolName,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.root.session.id":n.scope.rootSessionId??n.scope.sessionId,"agent.session.id":n.scope.sessionId,"agent.step.attempt":n.scope.attemptIndex,"agent.step.index":n.scope.stepIndex,"agent.turn.id":n.scope.turnId}},a.step.context),s=trace.setSpan(a.step.context,o),c=e.tracer.startSpan(`ai.toolCall`,{attributes:{"gen_ai.operation.name":`execute_tool`,"gen_ai.tool.call.id":n.source.toolCall.toolCallId,"gen_ai.tool.name":n.source.toolCall.toolName}},s);if(t){let e=contentAttribute(n.source.toolCall.input,!1);e!==void 0&&c.setAttribute(`gen_ai.tool.call.arguments`,e)}let l={context:trace.setSpan(s,c),span:o,toolSpan:c};return getExecutionContexts(n.scope).tools.set(n.id,l.context),l},afterToolCall=(e,n)=>{if(l.get(e.scope)?.tools.delete(e.id),isToolSpanState(n)){if(e.type===`tool.call.failed`)recordError(n.toolSpan,e.error),recordError(n.span,e.error);else if(e.source.toolOutput.type!==`tool-result`)recordError(n.toolSpan,e.source.toolOutput.error),recordError(n.span,e.source.toolOutput.error);else if(t){let t=contentAttribute(e.source.toolOutput.output,!1);t!==void 0&&n.toolSpan.setAttribute(`gen_ai.tool.call.result`,t)}n.toolSpan.end(),n.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,...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},advanceSessionWindow=(e,t)=>{if(t.turnsInWindow<200)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}};return{hook:{events:{"attempt.completed":onAttemptTerminal,"attempt.failed":onAttemptTerminal,"attempt.metadata":e=>{let t=u.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)},"attempt.started":onAttemptStarted,"model.call":{after:afterModelCall,before:beforeModelCall},"session.completed":onSessionTransition,"session.failed":onSessionTransition,"session.started":onSessionStarted,"session.waiting":onSessionTransition,"tool.call":{after:afterToolCall,before:beforeToolCall},"turn.cancelled":onTurnTerminal,"turn.completed":onTurnTerminal,"turn.failed":onTurnTerminal,"turn.started":onTurnStarted}},runInContext(e,t){let r=l.get(e.scope),i=e.type===`model.call`?r?.models.get(e.id):r?.tools.get(e.id);return i===void 0?t():context.with(i,t)}};function getExecutionContexts(e){let t=l.get(e);return t===void 0&&(t={models:new Map,tools:new Map},l.set(e,t)),t}}function turnKey(e,t){return`${e}:${t}`}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:!1,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 isSpanState(e){return typeof e==`object`&&!!e&&`context`in e&&`span`in e}function isToolSpanState(e){return isSpanState(e)&&`toolSpan`in e}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function modelSpanName(e){return e===`ai.generateText`?`ai.generateText.doGenerate`:`ai.streamText.doStream`}function setUsage(e,t){t.inputTokens!==void 0&&e.setAttribute(`agent.usage.input_tokens`,t.inputTokens),t.outputTokens!==void 0&&e.setAttribute(`agent.usage.output_tokens`,t.outputTokens);let n=t.inputTokenDetails;n?.cacheReadTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_read.input_tokens`,n.cacheReadTokens),n?.cacheWriteTokens!==void 0&&e.setAttribute(`gen_ai.usage.cache_creation.input_tokens`,n.cacheWriteTokens)}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{InMemoryAgentTraceStateStore,SESSION_WINDOW_TURN_LIMIT,createAgentOtelInstrumentation};

package/dist/src/{harness → tracing}/agent-trace-context-store.d.ts

@@ -1,6 +1,13 @@
-import type { AgentSessionTraceState, AgentTraceStateStore, AgentTurnTraceState } from "#harness/agent-otel-provider.js";
+import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
+import type { AgentSessionTraceState, AgentTraceStateStore, AgentTurnTraceState } from "#tracing/agent-otel-provider.js";
 /** Keeps only framework trace state from an interrupted step's context changes. */
 export declare function preserveSerializedAgentTraceState(original: Record<string, unknown>, interrupted: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Reads a named session's trace window straight out of a serialized context,
+ * which {@link ContextAgentTraceStateStore} cannot do — its reads are scoped
+ * to the ambient session.
+ */
+export declare function readSessionTraceContext(serializedContext: Readonly<Record<string, unknown>>, sessionId: string): SpanContext | undefined;
 /** Durable trace state backed by eve's serialized Workflow context. */
 export declare class ContextAgentTraceStateStore implements AgentTraceStateStore {
     deleteSession(sessionId: string): void;

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

@@ -0,0 +1 @@
+import{contextStorage,loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";const AgentTraceContextKey=new ContextKey(`eve.harness.agentTrace`,{codec:{deserialize:deserializeState,serialize:serializeState}});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 deserializeState(n).sessions[t]?.context}var ContextAgentTraceStateStore=class{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}})}getSession(t){return contextStorage.getStore()?.get(AgentTraceContextKey)?.sessions[t]}getTurn(t,n){return contextStorage.getStore()?.get(AgentTraceContextKey)?.turns[turnKey(t,n)]}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}}))}};function updateState(e){loadContext().set(AgentTraceContextKey,t=>e(t??{sessions:{},turns:{}}))}function turnKey(e,t){return`${e}\0${t}`}function serializeState(e){return{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:{error:serializeError(t.terminal.error),type:t.terminal.type}}]))}}function deserializeState(e){return isRecord(e)?{sessions:deserializeRecord(e.sessions,e=>{if(!(!isRecord(e)||!isSpanContext(e.context)))return{agentName:typeof e.agentName==`string`?e.agentName:void 0,channelKind:typeof e.channelKind==`string`?e.channelKind:void 0,context:e.context,rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,turnsInWindow:typeof e.turnsInWindow==`number`?e.turnsInWindow:0,window:typeof e.window==`number`?e.window:0}}),turns:deserializeRecord(e.turns,e=>{if(!(!isRecord(e)||!isSpanContext(e.context)))return{context:e.context,rootSessionId:typeof e.rootSessionId==`string`?e.rootSessionId:``,sequence:typeof e.sequence==`number`?e.sequence:0,terminal:deserializeTerminal(e.terminal)}})}:{sessions:{},turns:{}}}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{error:deserializeError(e.error),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,readSessionTraceContext};

package/dist/src/{harness → tracing}/agent-trace-span-processor.d.ts

@@ -9,7 +9,11 @@ export declare class AgentTraceSpanProcessor implements SpanProcessor {
     onEnd(span: unknown): void;
     /** Trace ids whose session is still open, so retention never evicts them. */
     activeTraceIds(): ReadonlySet<string>;
-    /** Forgets one session's trace, reporting whether it owned one. */
+    /**
+     * Forgets every trace one root session owned, reporting whether it owned any.
+     * A subagent child owns none, so releasing one reports `false` and leaves the
+     * shared trace pinned until its root finishes.
+     */
     releaseSession(sessionId: string): boolean;
     shutdown(): Promise<void>;
 }

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

@@ -0,0 +1 @@
+var AgentTraceSpanProcessor=class{#e;#t=new Set;#n=new Map;#r=!1;constructor(e){this.#e=e}async forceFlush(){await Promise.all(this.#e.map(e=>e.forceFlush()))}isAttached(){return this.#r}onStart(e,t){if(this.#r=!0,!isSpanLike(e))return;let n=e.attributes[`agent.session.id`];if(typeof n==`string`){let t=e.attributes[`agent.root.session.id`],r=typeof t==`string`?t:n,i=e.spanContext().traceId;this.#t.add(i);let a=this.#n.get(r)??new Set;a.add(i),this.#n.set(r,a)}if(this.#i(e))for(let n of this.#e)n.onStart(e,t)}onEnd(e){if(!(!isSpanLike(e)||!this.#i(e)))for(let t of this.#e)t.onEnd(e)}activeTraceIds(){return this.#t}releaseSession(e){let t=this.#n.get(e);if(t===void 0)return!1;for(let e of t)this.#t.delete(e);return this.#n.delete(e),!0}async shutdown(){await Promise.all(this.#e.map(e=>e.shutdown()))}#i(e){return e.instrumentationScope?.name!==`workflow`&&this.#t.has(e.spanContext().traceId)}};function isSpanLike(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}export{AgentTraceSpanProcessor};

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

@@ -0,0 +1 @@
+import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";import{ContextAgentTraceStateStore}from"#tracing/agent-trace-context-store.js";import{getInstrumentationRuntime,registerInstrumentationRuntime}from"#harness/instrumentation-runtime.js";import{context,trace}from"#compiled/@opentelemetry/api/index.js";import{registerOTel}from"#compiled/@vercel/otel/index.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{createInstrumentationHooks}from"#harness/instrumentation-lifecycle.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";function installLocalInstrumentationRuntime(t){let n=getInstrumentationRuntime();if(n!==void 0)return n;let r=resolveLocalTraceRetentionSettings(),i=new AgentTraceSpanProcessor(r.enabled?[new LocalTraceSpanProcessor(t.appRoot)]:[]);registerOTel({autoDetectResources:!1,instrumentations:[],propagators:[`none`],serviceName:t.serviceName,spanProcessors:[i]});let a=trace.getTracer(`eve.registration`).startSpan(`eve.otel.registration`),o=trace.setSpan(context.active(),a),s=context.with(o,()=>trace.getActiveSpan()===a);if(a.end(),!i.isAttached()||!s)throw Error(`eve could not register OpenTelemetry because another runtime already exists.`);let c=createAgentOtelInstrumentation({captureContent:process.env.EVE_TRACES_CONTENT!==`off`,frameworkVersion:t.frameworkVersion,stateStore:new ContextAgentTraceStateStore,tracer:trace.getTracer(`eve.agent`,t.frameworkVersion)}),l={events:{"session.completed":releaseSessionTrace,"session.failed":releaseSessionTrace}};return requestPrune(),registerInstrumentationRuntime({forceFlush:()=>i.forceFlush(),hooks:createInstrumentationHooks([c.hook,l]),runInContext:c.runInContext});async function releaseSessionTrace(e){await i.forceFlush(),i.releaseSession(e.sessionId)&&requestPrune()}function requestPrune(){r.enabled&&requestLocalTraceStorePrune({activeTraceIds:i.activeTraceIds(),appRoot:t.appRoot,maxAgeMs:r.maxAgeMs,maxTotalBytes:r.maxTotalBytes,retainCount:r.retainCount})}}export{installLocalInstrumentationRuntime};

package/dist/src/tracing/local-trace-reader.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Reads the local trace spool written by {@link LocalTraceSpanProcessor}.
+ *
+ * The spool is the contract between the dev-time writer and every viewer
+ * (`eve traces`, the TUI trace viewer): one directory per trace under
+ * `.eve/traces/v1/<traceId>/segments/`, one immutable OTLP/JSON file per
+ * span. Parsing is defensive end to end — malformed or oversized segments
+ * are skipped so a partial write never breaks a view.
+ */
+export interface LocalTraceSpan {
+    readonly attributes: Readonly<Record<string, unknown>>;
+    readonly endTimeNs: bigint;
+    readonly name: string;
+    readonly parentSpanId?: string;
+    readonly scope?: string;
+    readonly spanId: string;
+    readonly startTimeNs: bigint;
+    readonly statusCode: number;
+    readonly traceId: string;
+}
+export interface LocalTrace {
+    readonly agentName?: string;
+    readonly endTimeNs: bigint;
+    /** Session that opened the trace, which is the one the list shows. */
+    readonly sessionId?: string;
+    /**
+     * Every session recorded in the trace, opener first.
+     *
+     * A subagent child records into the window its parent had open, so one
+     * trace can hold several sessions and any of their ids resolves to it.
+     */
+    readonly sessionIds: readonly string[];
+    readonly spans: readonly LocalTraceSpan[];
+    readonly startTimeNs: bigint;
+    readonly traceId: string;
+    /** Zero-based session window this trace holds, when the spans record one. */
+    readonly window?: number;
+}
+/** Reads valid local traces, newest first, while ignoring malformed segments. */
+export declare function listLocalTraces(appRoot: string): Promise<LocalTrace[]>;
+/**
+ * Reads one trace from its segments directory, or `undefined` when the trace
+ * has no valid spans. Spans come back ordered by start time.
+ */
+export declare function readLocalTrace(root: string, traceId: string): Promise<LocalTrace | undefined>;
+/** Sorts spans into timeline order: start, then end, then a stable tiebreak. */
+export declare function compareLocalTraceSpans(left: LocalTraceSpan, right: LocalTraceSpan): number;
+/** Builds a trace from already-parsed spans, deriving summary fields. */
+export declare function assembleLocalTrace(traceId: string, spans: readonly LocalTraceSpan[]): LocalTrace;
+/**
+ * Extracts short human-facing details from a span's structural attributes
+ * (turn id, step index/attempt, action kind/name, model id) for one-line
+ * span labels. Raw values — callers sanitize for their output surface.
+ */
+export declare function describeLocalTraceSpan(span: LocalTraceSpan): string[];
+/** Parses one OTLP/JSON segment file into spans belonging to `expectedTraceId`. */
+export declare function parseLocalTraceSegment(content: string, expectedTraceId: string): LocalTraceSpan[];

package/dist/src/tracing/local-trace-reader.js

@@ -0,0 +1 @@
+import{join}from"node:path";import{readFile,readdir,stat}from"node:fs/promises";import{resolveLocalTraceSchemaDirectory}from"#tracing/local-trace-span-processor.js";const TRACE_ID_PATTERN=/^[0-9a-f]{32}$/u,SPAN_FILE_PATTERN=/^([0-9a-f]{16})\.otlp\.json$/u;async function listLocalTraces(e){let t=resolveLocalTraceSchemaDirectory(e),r;try{r=await readdir(t,{withFileTypes:!0})}catch(e){if(isMissing(e))return[];throw e}let o=[];for(let e of r){if(!e.isDirectory()||!TRACE_ID_PATTERN.test(e.name))continue;let n=await readLocalTrace(t,e.name).catch(()=>void 0);n!==void 0&&o.push(n)}return o.sort((e,t)=>e.startTimeNs===t.startTimeNs?e.traceId.localeCompare(t.traceId):e.startTimeNs>t.startTimeNs?-1:1)}async function readLocalTrace(i,a){let s=join(i,a,`segments`),c;try{c=await readdir(s,{withFileTypes:!0})}catch(e){if(isMissing(e))return;throw e}let l=new Map;for(let n of c.sort((e,t)=>e.name.localeCompare(t.name))){if(!n.isFile()||!SPAN_FILE_PATTERN.test(n.name))continue;let i;try{let a=join(s,n.name);if((await stat(a)).size>8388608)continue;i=await readFile(a,`utf8`)}catch{continue}for(let e of parseLocalTraceSegment(i,a))l.has(e.spanId)||l.set(e.spanId,e)}if(l.size!==0)return assembleLocalTrace(a,[...l.values()])}function compareLocalTraceSpans(e,t){return e.startTimeNs===t.startTimeNs?e.endTimeNs===t.endTimeNs?e.name.localeCompare(t.name)||e.spanId.localeCompare(t.spanId):e.endTimeNs<t.endTimeNs?-1:1:e.startTimeNs<t.startTimeNs?-1:1}function assembleLocalTrace(e,t){let n=[...t].sort(compareLocalTraceSpans),r=n.map(e=>e.attributes),i=distinctAttributes(r,`agent.session.id`);return{agentName:firstAttribute(r,`agent.name`),endTimeNs:n.reduce((e,t)=>t.endTimeNs>e?t.endTimeNs:e,0n),sessionId:i[0],sessionIds:i,spans:n,startTimeNs:n.reduce((e,t)=>t.startTimeNs<e?t.startTimeNs:e,n[0].startTimeNs),traceId:e,window:firstNumberAttribute(r,`agent.session.window`)}}function describeLocalTraceSpan(e){let t=[],n=stringSpanAttribute(e,`agent.turn.id`),r=valueSpanAttribute(e,`agent.step.index`),i=valueSpanAttribute(e,`agent.step.attempt`),a=stringSpanAttribute(e,`agent.action.kind`),o=stringSpanAttribute(e,`agent.action.name`),s=stringSpanAttribute(e,`agent.model.id`)??stringSpanAttribute(e,`gen_ai.request.model`);return e.name===`agent.turn`&&n!==void 0&&t.push(n),e.name===`agent.step`&&r!==void 0&&t.push(`step ${String(r)}${i===void 0?``:`, attempt ${String(i)}`}`),e.name===`agent.action`&&o!==void 0&&t.push(`${a??`action`}: ${o}`),s!==void 0&&e.name.includes(`do`)&&t.push(`model ${s}`),t}function parseLocalTraceSegment(e,t){try{let n=JSON.parse(e);if(!isRecord(n)||!Array.isArray(n.resourceSpans))return[];let r=[];for(let e of n.resourceSpans)if(!(!isRecord(e)||!Array.isArray(e.scopeSpans)))for(let n of e.scopeSpans){if(!isRecord(n)||!Array.isArray(n.spans))continue;let e=isRecord(n.scope)&&typeof n.scope.name==`string`?n.scope.name:void 0;for(let i of n.spans){let n=parseLocalTraceSpan(i,t,e);n!==void 0&&r.push(n)}}return r}catch{return[]}}function parseLocalTraceSpan(e,t,n){if(!isRecord(e)||e.traceId!==t||typeof e.spanId!=`string`||!/^[0-9a-f]{16}$/u.test(e.spanId)||typeof e.name!=`string`)return;let r=parseNanos(e.startTimeUnixNano),i=parseNanos(e.endTimeUnixNano);if(!(r===void 0||i===void 0||i<r))return{attributes:parseAttributes(e.attributes),endTimeNs:i,name:e.name,parentSpanId:typeof e.parentSpanId==`string`&&/^[0-9a-f]{16}$/u.test(e.parentSpanId)?e.parentSpanId:void 0,scope:n,spanId:e.spanId,startTimeNs:r,statusCode:parseStatusCode(e.status),traceId:t}}function parseAttributes(e){if(!Array.isArray(e))return{};let t={};for(let n of e){if(!isRecord(n)||typeof n.key!=`string`||!isRecord(n.value))continue;let e=parseAnyValue(n.value);e!==void 0&&(t[n.key]=e)}return t}function parseAnyValue(e){for(let t of[`stringValue`,`boolValue`,`intValue`,`doubleValue`])if(t in e)return e[t];if(isRecord(e.arrayValue)&&Array.isArray(e.arrayValue.values))return e.arrayValue.values.filter(isRecord).map(e=>parseAnyValue(e))}function parseNanos(e){if(!(typeof e!=`string`&&typeof e!=`number`))try{let t=BigInt(e);return t>=0n&&t<=18446744073709551615n?t:void 0}catch{return}}function parseStatusCode(e){return isRecord(e)?typeof e.code==`number`?e.code:e.code===`STATUS_CODE_ERROR`?2:0:0}function firstAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`string`&&e.length>0)return e}}function firstNumberAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`number`)return e;if(typeof e==`bigint`)return Number(e)}}function distinctAttributes(e,t){let n=new Set;for(let r of e){let e=r[t];typeof e==`string`&&e.length>0&&n.add(e)}return[...n]}function stringSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`?n:void 0}function valueSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`||typeof n==`number`?n:void 0}function isMissing(e){return e.code===`ENOENT`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{assembleLocalTrace,compareLocalTraceSpans,describeLocalTraceSpan,listLocalTraces,parseLocalTraceSegment,readLocalTrace};

package/dist/src/{harness → tracing}/local-trace-retention.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{readdir,rm,stat}from"node:fs/promises";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#harness/local-trace-span-processor.js";const log=createLogger(`harness.local-trace-retention`),LOCAL_TRACE_QUIESCENCE_MS=300*1e3,LOCAL_TRACE_MAX_AGE_MS=10080*60*1e3,LOCAL_TRACE_MAX_TOTAL_BYTES=512*1024*1024;function resolveLocalTraceRetentionSettings(e=process.env){return{enabled:!isDisabled(e.EVE_TRACES),maxAgeMs:readBound(e,`EVE_TRACES_MAX_AGE_MS`,LOCAL_TRACE_MAX_AGE_MS),maxTotalBytes:readBound(e,`EVE_TRACES_MAX_TOTAL_BYTES`,LOCAL_TRACE_MAX_TOTAL_BYTES),retainCount:readBound(e,`EVE_TRACES_RETAIN_COUNT`,20)}}async function pruneLocalTraceStore(e){let t=e.now??Date.now(),n=clampBound(e.maxAgeMs??LOCAL_TRACE_MAX_AGE_MS),r=clampBound(e.maxTotalBytes??LOCAL_TRACE_MAX_TOTAL_BYTES),a=clampCount(e.retainCount??20),o=await readStoredTraces(e.appRoot,t),s=[...o].sort((e,t)=>t.modifiedAtMs-e.modifiedAtMs),c=new Set(s.slice(0,a===!1?0:a)),l=new Set,u=o.reduce((e,t)=>e+t.byteSize,0),d=0,f=0,p=0;for(let a of s.toReversed()){let o=t-a.modifiedAtMs,s=e.activeTraceIds.has(a.traceId)||c.has(a)||o<=LOCAL_TRACE_QUIESCENCE_MS?void 0:n!==!1&&o>n?`maxAgeMs`:r!==!1&&u>r?`maxTotalBytes`:void 0;if(s===void 0){p+=1;continue}await rm(a.path,{force:!0,recursive:!0}),u-=a.byteSize,d+=a.byteSize,f+=1,l.add(s)}return{reasons:[...l],reclaimedBytes:d,removedTraces:f,retainedTraces:p}}const pruneRequest={input:{activeTraceIds:new Set,appRoot:``},requested:!1,running:void 0};function requestLocalTraceStorePrune(e){pruneRequest.input=e,pruneRequest.requested=!0,pruneRequest.running===void 0&&startPruning()}function startPruning(){pruneRequest.running=(async()=>{for(;pruneRequest.requested;)pruneRequest.requested=!1,report(await pruneLocalTraceStore(pruneRequest.input))})().catch(e=>{log.warn(`local trace retention failed`,{error:formatError(e)})}).finally(()=>{pruneRequest.running=void 0,pruneRequest.requested&&startPruning()})}function report(e){e.removedTraces!==0&&log.info(`pruned local traces`,{reasons:e.reasons.join(`,`),reclaimedBytes:e.reclaimedBytes,removedTraces:e.removedTraces,retainedTraces:e.retainedTraces})}async function readStoredTraces(e,t){let r=resolveLocalTraceSchemaDirectory(e),i=await readDirectoryEntries(r);return i===void 0?[]:(await Promise.all(i.filter(e=>e.isDirectory()).map(async i=>{let a=join(r,i.name),o=resolveLocalTraceSegmentsDirectory(e,i.name);await reapAbandonedTemporaryFiles(o,t);let c=await directoryMtime(o)??await directoryMtime(a);if(c!==void 0)return{byteSize:await directorySize(a),modifiedAtMs:c,path:a,traceId:i.name}}))).filter(e=>e!==void 0)}async function reapAbandonedTemporaryFiles(e,t){let r=await readDirectoryEntries(e);if(r!==void 0)for(let o of r){if(!o.isFile()||!o.name.includes(`.tmp-`))continue;let r=join(e,o.name);try{if(t-(await stat(r)).mtimeMs<=LOCAL_TRACE_QUIESCENCE_MS)continue;await rm(r,{force:!0})}catch{}}}async function directoryMtime(e){try{return(await stat(e)).mtimeMs}catch{return}}async function directorySize(e){let t=await readDirectoryEntries(e);if(t===void 0)return 0;let r=0;for(let i of t){let t=join(e,i.name);if(i.isDirectory()){r+=await directorySize(t);continue}try{r+=(await stat(t)).size}catch{}}return r}async function readDirectoryEntries(e){try{return await readdir(e,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&(e.code===`ENOENT`||e.code===`ENOTDIR`))return;throw e}}function isDisabled(e){if(e===void 0)return!1;let t=e.trim().toLowerCase();return t===`off`||t===`false`||t===`0`}function readBound(e,t,n){let r=e[t];if(r===void 0)return n;let i=r.trim().toLowerCase();if(i===`off`||i===`false`)return!1;let a=Number(i);return!Number.isFinite(a)||a<0?(log.warn(`ignoring invalid local trace retention value`,{fallback:n,name:t,value:r}),n):a}function clampBound(e){return e!==!1&&Math.max(0,e)}function clampCount(e){return e!==!1&&Math.max(0,Math.trunc(e))}export{pruneLocalTraceStore,requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings};
+import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{readdir,rm,stat}from"node:fs/promises";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#tracing/local-trace-span-processor.js";const log=createLogger(`harness.local-trace-retention`),LOCAL_TRACE_QUIESCENCE_MS=300*1e3,LOCAL_TRACE_MAX_AGE_MS=10080*60*1e3,LOCAL_TRACE_MAX_TOTAL_BYTES=512*1024*1024;function resolveLocalTraceRetentionSettings(e=process.env){return{enabled:!isDisabled(e.EVE_TRACES),maxAgeMs:readBound(e,`EVE_TRACES_MAX_AGE_MS`,LOCAL_TRACE_MAX_AGE_MS),maxTotalBytes:readBound(e,`EVE_TRACES_MAX_TOTAL_BYTES`,LOCAL_TRACE_MAX_TOTAL_BYTES),retainCount:readBound(e,`EVE_TRACES_RETAIN_COUNT`,20)}}async function pruneLocalTraceStore(e){let t=e.now??Date.now(),n=clampBound(e.maxAgeMs??LOCAL_TRACE_MAX_AGE_MS),r=clampBound(e.maxTotalBytes??LOCAL_TRACE_MAX_TOTAL_BYTES),a=clampCount(e.retainCount??20),o=await readStoredTraces(e.appRoot,t),s=[...o].sort((e,t)=>t.modifiedAtMs-e.modifiedAtMs),c=new Set(s.slice(0,a===!1?0:a)),l=new Set,u=o.reduce((e,t)=>e+t.byteSize,0),d=0,f=0,p=0;for(let a of s.toReversed()){let o=t-a.modifiedAtMs,s=e.activeTraceIds.has(a.traceId)||c.has(a)||o<=LOCAL_TRACE_QUIESCENCE_MS?void 0:n!==!1&&o>n?`maxAgeMs`:r!==!1&&u>r?`maxTotalBytes`:void 0;if(s===void 0){p+=1;continue}await rm(a.path,{force:!0,recursive:!0}),u-=a.byteSize,d+=a.byteSize,f+=1,l.add(s)}return{reasons:[...l],reclaimedBytes:d,removedTraces:f,retainedTraces:p}}const pruneRequest={input:{activeTraceIds:new Set,appRoot:``},requested:!1,running:void 0};function requestLocalTraceStorePrune(e){pruneRequest.input=e,pruneRequest.requested=!0,pruneRequest.running===void 0&&startPruning()}function startPruning(){pruneRequest.running=(async()=>{for(;pruneRequest.requested;)pruneRequest.requested=!1,report(await pruneLocalTraceStore(pruneRequest.input))})().catch(e=>{log.warn(`local trace retention failed`,{error:formatError(e)})}).finally(()=>{pruneRequest.running=void 0,pruneRequest.requested&&startPruning()})}function report(e){e.removedTraces!==0&&log.info(`pruned local traces`,{reasons:e.reasons.join(`,`),reclaimedBytes:e.reclaimedBytes,removedTraces:e.removedTraces,retainedTraces:e.retainedTraces})}async function readStoredTraces(e,t){let r=resolveLocalTraceSchemaDirectory(e),i=await readDirectoryEntries(r);return i===void 0?[]:(await Promise.all(i.filter(e=>e.isDirectory()).map(async i=>{let a=join(r,i.name),o=resolveLocalTraceSegmentsDirectory(e,i.name);await reapAbandonedTemporaryFiles(o,t);let c=await directoryMtime(o)??await directoryMtime(a);if(c!==void 0)return{byteSize:await directorySize(a),modifiedAtMs:c,path:a,traceId:i.name}}))).filter(e=>e!==void 0)}async function reapAbandonedTemporaryFiles(e,t){let r=await readDirectoryEntries(e);if(r!==void 0)for(let o of r){if(!o.isFile()||!o.name.includes(`.tmp-`))continue;let r=join(e,o.name);try{if(t-(await stat(r)).mtimeMs<=LOCAL_TRACE_QUIESCENCE_MS)continue;await rm(r,{force:!0})}catch{}}}async function directoryMtime(e){try{return(await stat(e)).mtimeMs}catch{return}}async function directorySize(e){let t=await readDirectoryEntries(e);if(t===void 0)return 0;let r=0;for(let i of t){let t=join(e,i.name);if(i.isDirectory()){r+=await directorySize(t);continue}try{r+=(await stat(t)).size}catch{}}return r}async function readDirectoryEntries(e){try{return await readdir(e,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&(e.code===`ENOENT`||e.code===`ENOTDIR`))return;throw e}}function isDisabled(e){if(e===void 0)return!1;let t=e.trim().toLowerCase();return t===`off`||t===`false`||t===`0`}function readBound(e,t,n){let r=e[t];if(r===void 0)return n;let i=r.trim().toLowerCase();if(i===`off`||i===`false`)return!1;let a=Number(i);return!Number.isFinite(a)||a<0?(log.warn(`ignoring invalid local trace retention value`,{fallback:n,name:t,value:r}),n):a}function clampBound(e){return e!==!1&&Math.max(0,e)}function clampCount(e){return e!==!1&&Math.max(0,Math.trunc(e))}export{pruneLocalTraceStore,requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings};

package/dist/src/{harness → tracing}/local-trace-span-processor.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{mkdir}from"node:fs/promises";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";import{atomicWriteFile}from"#shared/atomic-write-file.js";const log=createLogger(`harness.local-trace-span-processor`);function resolveLocalTraceStoreDirectory(e){return join(e,`.eve`,`traces`)}function resolveLocalTraceSchemaDirectory(e){return join(resolveLocalTraceStoreDirectory(e),`v1`)}function resolveLocalTraceSegmentsDirectory(e,t){return join(resolveLocalTraceSchemaDirectory(e),t,`segments`)}var LocalTraceSpanProcessor=class{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}forceFlush(){return this.#t}onStart(){}onEnd(e){if(!isReadableSpan(e))return;let{spanId:n,traceId:r}=e.spanContext();if(!isHexId(r,32)||!isHexId(n,16))return;let i=JsonTraceSerializer.serializeRequest([e]);i!==void 0&&(this.#t=this.#t.then(async()=>{let e=resolveLocalTraceSegmentsDirectory(this.#e,r);await mkdir(e,{recursive:!0}),await atomicWriteFile(join(e,`${n}.otlp.json`),i)}).catch(e=>{this.#n||(this.#n=!0,log.warn(`local trace persistence failed`,{error:formatError(e)}))}))}shutdown(){return this.forceFlush()}};function isReadableSpan(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}function isHexId(e,t){return e.length===t&&/^[0-9a-f]+$/u.test(e)}export{LocalTraceSpanProcessor,resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory};
+import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{mkdir}from"node:fs/promises";import{atomicWriteFile}from"#shared/atomic-write-file.js";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";const log=createLogger(`harness.local-trace-span-processor`);function resolveLocalTraceStoreDirectory(e){return join(e,`.eve`,`traces`)}function resolveLocalTraceSchemaDirectory(e){return join(resolveLocalTraceStoreDirectory(e),`v1`)}function resolveLocalTraceSegmentsDirectory(e,t){return join(resolveLocalTraceSchemaDirectory(e),t,`segments`)}var LocalTraceSpanProcessor=class{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}forceFlush(){return this.#t}onStart(){}onEnd(e){if(!isReadableSpan(e))return;let{spanId:n,traceId:r}=e.spanContext();if(!isHexId(r,32)||!isHexId(n,16))return;let i=JsonTraceSerializer.serializeRequest([e]);i!==void 0&&(this.#t=this.#t.then(async()=>{let e=resolveLocalTraceSegmentsDirectory(this.#e,r);await mkdir(e,{recursive:!0}),await atomicWriteFile(join(e,`${n}.otlp.json`),i)}).catch(e=>{this.#n||(this.#n=!0,log.warn(`local trace persistence failed`,{error:formatError(e)}))}))}shutdown(){return this.forceFlush()}};function isReadableSpan(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}function isHexId(e,t){return e.length===t&&/^[0-9a-f]+$/u.test(e)}export{LocalTraceSpanProcessor,resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory};

package/docs/channels/chat-sdk.mdx

@@ -97,7 +97,24 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-`options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
+`options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName?, turnPolicy? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
+
+### Experimental steering
+
+By default, a message sent while an eve turn is active waits for the next turn. Pass `turnPolicy: "experimental-steer"` to cancel the active turn before sending the new message:
+
+```ts
+bot.onSubscribedMessage(async (thread, message) => {
+  await send(message.text, {
+    thread,
+    turnPolicy: "experimental-steer",
+  });
+});
+```
+
+This is cancellation-backed steering: the interrupted turn emits `turn.cancelled`, and the replacement message starts a new turn with a new turn ID. Partial output and completed side effects from the interrupted turn are not rolled back. If no turn is active, the message is sent normally. Use the default `turnPolicy: "queue"` when every turn should finish in order.
+
+This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the experimental steering path immediately.
 
 ### Delivery
 

package/docs/channels/meta.json

@@ -4,6 +4,7 @@
     "overview",
     "eve",
     "slack",
+    "photon",
     "discord",
     "teams",
     "telegram",

package/docs/channels/overview.mdx

@@ -28,7 +28,7 @@ agent/
     intake.ts
 ```
 
-Install a built-in channel with `eve add channel/slack` or `eve add channel/web`. You can also author the file by hand.
+Install a channel from the registry with `eve add channel/photon-imessage`, `eve add channel/slack`, or `eve add channel/web`. You can also author the file by hand.
 
 ## The eve HTTP channel (default)
 

package/docs/channels/photon.mdx

@@ -0,0 +1,78 @@
+---
+title: Photon
+description: Connect an eve agent to iMessage through Photon.
+---
+
+Use `photonIMessageChannel` to receive and reply to iMessages through a Photon project.
+
+Run `eve add channel/photon-imessage` to create or use a Photon project and register
+your phone number. It then asks whether to configure Vercel Connect or portable
+credentials. With Vercel Connect, eve creates the connector and configures
+Photon’s webhook through Connect. The channel resolves credentials lazily when
+the adapter first initializes:
+
+```ts title="agent/channels/photon.ts"
+import { connectPhotonCredentials } from "@vercel/connect/eve";
+import { photonIMessageChannel } from "eve/channels/photon";
+
+export default photonIMessageChannel({
+  credentials: connectPhotonCredentials("photon/my-agent"),
+});
+```
+
+The default webhook route is `/eve/v1/photon`. The channel verifies forwarded
+webhooks with same-project Vercel OIDC by default, marks accepted messages as
+read, and continues the same eve session for every message in an iMessage
+conversation. A new accepted message cooperatively cancels an active turn and
+steers its replacement turn.
+
+Customize inbound dispatch with `onMessage`. Return `null` to ignore a message:
+
+```ts
+export default photonIMessageChannel({
+  credentials: connectPhotonCredentials("photon/my-agent"),
+  onMessage(_ctx, message) {
+    if (message.author.isBot) return null;
+    return {
+      auth: null,
+      context: [`The sender is ${message.author.fullName}.`],
+    };
+  },
+});
+```
+
+Set `route` to override the webhook path or `webhookVerifier` to use a different
+trusted-forwarder verifier.
+
+## Other hosts
+
+For a host without Vercel Connect, choose **Use portable credentials** during
+`eve add channel/photon-imessage`. eve scaffolds the channel and writes
+`IMESSAGE_PROJECT_ID` and `IMESSAGE_PROJECT_SECRET` to `.env.local`.
+
+After deploying the agent:
+
+1. Create a Photon webhook for your public `https://…/eve/v1/photon` URL.
+2. Copy its signing secret into `IMESSAGE_WEBHOOK_SECRET`.
+3. Set `IMESSAGE_PROJECT_ID`, `IMESSAGE_PROJECT_SECRET`, and
+   `IMESSAGE_WEBHOOK_SECRET` in the host’s encrypted environment variables.
+
+To configure the channel by hand, use lazy environment-backed credentials:
+
+```ts title="agent/channels/photon.ts"
+import { photonIMessageChannel } from "eve/channels/photon";
+
+export default photonIMessageChannel({
+  async credentials() {
+    const projectId = process.env.IMESSAGE_PROJECT_ID;
+    const projectSecret = process.env.IMESSAGE_PROJECT_SECRET;
+    if (!projectId || !projectSecret) throw new Error("Photon project credentials are required.");
+    return { projectId, projectSecret };
+  },
+  webhookSecret: process.env.IMESSAGE_WEBHOOK_SECRET,
+});
+```
+
+For direct Photon webhooks, pass `webhookSecret` or set
+`IMESSAGE_WEBHOOK_SECRET`; the signing secret takes precedence over the default
+OIDC verifier.

package/docs/concepts/default-harness.md

@@ -41,6 +41,8 @@ The shell and file tools (`bash`, `read_file`, `write_file`, `glob`, `grep`) run
 | `load_skill`        | Pull an on-demand [skill](../skills)'s instructions into the current turn. Present only when the agent declares skills.                                                                                             | App runtime   |
 | `connection_search` | Discover tools across declared [connections](../connections); matched tools become directly callable. Present only when the agent declares connections.                                                             | App runtime   |
 
+The model-facing file tools accept absolute paths and paths beginning with `$HOME/`. eve resolves `$HOME` against the sandbox before invoking non-shell file operations, so packaged skill references such as `$HOME/.agents/skills/<skill>/references/...` work consistently across `read_file`, `write_file`, `glob`, and `grep`.
+
 Notes:
 
 - **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](../guides/state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).

package/docs/guides/dev-tui.md

@@ -40,11 +40,12 @@ Each command echoes as an invocation line, asks through a bordered panel that ta
 | `/vc:install` | Installs the Vercel CLI. Available locally and on a remote session.                                                                                          |
 | `/vc:login`   | Logs in to Vercel locally. On a remote session, resolves the deployment's project, refreshes its OIDC token, and confirms any required Trusted Sources rule. |
 | `/loglevel`   | Switches which logs the transcript shows. See [Control what logs show](#control-what-logs-show).                                                             |
+| `/traces`     | Opens the full-screen local trace viewer. See [Inspect traces](#inspect-traces).                                                                             |
 | `/new`        | Starts a fresh session.                                                                                                                                      |
 | `/exit`       | Quits the TUI.                                                                                                                                               |
 | `/help`       | Lists the commands available for the current local or remote session.                                                                                        |
 
-`/model`, `/add`, and `/deploy` manage the local agent or its linked project. They are available only when `eve dev` runs the server locally, not when connected to a remote server with `--url`.
+`/model`, `/add`, `/deploy`, and `/traces` manage the local agent or its linked project. They are available only when `eve dev` runs the server locally, not when connected to a remote server with `--url`.
 
 ### Configure the model and provider
 
@@ -106,6 +107,24 @@ Every captured line, tool failure, workflow error, and eve framework log record
 
 Each log has a same-named `.dump` sibling — one JSON document with environment diagnostics (eve, Node.js, and Vercel CLI versions, the Vercel CLI path, and the size of the local session store) plus running session stats: prompts, token usage, tool calls by name, and subagent dispatches. `eve logs --dump` prints the dump and the log together as one parseable report to attach when filing an issue.
 
+## Inspect traces
+
+`/traces` opens a full-screen viewer over the local trace spool (`.eve/traces/v1`) that `eve dev` writes while you chat — see [Zero-config local traces](instrumentation#zero-config-local-traces). It reads the spool files directly and refreshes about once a second, so spans from the current session stream in live. The viewer takes over the terminal's alternate screen; closing it restores the transcript exactly where you left it.
+
+The viewer opens on your current session's trace (or the most recent one). It re-tells the trace as a chat-like flow of cards: the system prompt sits at the top as a collapsed card, then user and assistant messages (assistant cards carry model, duration, token, and gateway cost metadata), and tool calls show their inputs and results inline. Work a subagent performed appears in the same flow, ordered by when it happened — between the parent's dispatch step and its resumed reply — with a dim `subagent` badge (`subagent:<name>` when the dispatch named one) on every card of the delegated turn; the delegated prompt renders as a `task` card rather than a `user` message. Error spans paint their whole card red. The header names the agent, session, span count, and duration, plus a `● live` badge while spans are still landing. `/traces <trace>` opens a specific trace by id prefix.
+
+| Key       | Action                                                                   |
+| --------- | ------------------------------------------------------------------------ |
+| `↑` / `↓` | Move the card selection (scroll the attributes panel when it has focus). |
+| `←` / `→` | Expand / collapse the selected card (only cards with hidden content).    |
+| `Enter`   | Open the attributes panel for the selected card; close it when open.     |
+| `Tab`     | Move focus between the conversation and the attributes panel.            |
+| `[` / `]` | Cycle to the next / previous trace.                                      |
+| `Esc`     | Close the panel (or unfocus it), otherwise close the viewer.             |
+| `q`       | Close the viewer.                                                        |
+
+`←`/`→` or a mouse click expands a card to its full contents (the system prompt, long payloads) and collapses it back; cards that already fit have nothing to expand. The scroll wheel scrolls the conversation (or the attributes panel when the pointer is over it). Dragging with the mouse selects text — the selection highlights as you drag, and releasing copies it to your clipboard with a `Copied to clipboard` toast in the top-right corner; `Esc` cancels an in-flight selection. The attributes panel opens on the right and stays metadata-only — status, timing, ids, and the span's non-payload OTLP attributes — since the cards already carry the payloads. Model spans capture the system prompt, the prompt messages (rendered as a chat transcript), and the response (text, tool calls, finish reason); tool-call spans capture the call arguments and result, pretty-printed — each capped at 32 KB, with provider transport metadata stripped. When a conversation's messages exceed the cap, the oldest messages are dropped and the transcript notes how many were omitted. Set `EVE_TRACES_CONTENT=off` to stop capturing payload content. With no spans yet, the viewer shows an empty state and keeps watching; if tracing is disabled (`EVE_TRACES=off`) it says so instead.
+
 ## Display flags
 
 Density flags control how much of each section renders. They accept `full`, `collapsed`, `auto-collapsed`, or `hidden`.

package/docs/guides/instrumentation.md

@@ -13,7 +13,7 @@ When no authored `instrumentation.ts` exists, `eve dev` records agent, AI SDK, a
 
 The directory is an immutable OTLP/JSON spool and remains available after `eve dev` exits, subject to the [retention policy](#local-trace-retention) below. Inspection tools may build a query index from these segments, but the index is derived and can be rebuilt without changing the captured trace data.
 
-Use `eve traces ls` to list captured traces and `eve traces <trace>` to inspect a session's span tree.
+Use `eve traces ls` to list captured traces and `eve traces <trace>` to inspect a session's span tree. Inside the dev TUI, [`/traces`](dev-tui#inspect-traces) opens a full-screen live viewer that re-tells the trace as a chat-style conversation (expandable message and tool-call cards) with a right-side metadata drawer. Model and tool-call spans also carry the inputs and outputs (system prompt, prompt messages, and response text for models; call arguments and results for tools, each capped at 32 KB) — set `EVE_TRACES_CONTENT=off` to keep payloads out of the spool.
 
 When a model call is served by Vercel AI Gateway, its `agent.step` span also carries the cost the gateway reported: `gen_ai.usage.cost` (raw inference, USD), `gen_ai.usage.gateway_cost` (with the gateway surcharge), `gen_ai.usage.input_cost` / `gen_ai.usage.output_cost` (the split), and `gen_ai.generation.id` for reconciliation with the gateway dashboard. These attributes only exist for gateway-served calls — other providers emit nothing. Cost per turn is the sum across the turn's step spans.
 
@@ -34,12 +34,13 @@ Whatever survives is then evicted oldest-first while the store exceeds `EVE_TRAC
 
 Open sessions are tracked per dev worker, so a session waiting across a restart, or a trace a draining worker is still writing, is not covered by the first rule. The five-minute write-recency rule is what protects those, and it applies even when you set `EVE_TRACES_MAX_AGE_MS=0`.
 
-| Variable                     | Default              | Effect                                        |
-| ---------------------------- | -------------------- | --------------------------------------------- |
-| `EVE_TRACES`                 | on                   | `off` stops writing traces and stops sweeping |
-| `EVE_TRACES_MAX_AGE_MS`      | `604800000` (7d)     | Age after which a trace may be evicted        |
-| `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store               |
-| `EVE_TRACES_RETAIN_COUNT`    | `20`                 | Newest traces kept regardless of age or size  |
+| Variable                     | Default              | Effect                                                                                      |
+| ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
+| `EVE_TRACES`                 | on                   | `off` stops writing traces and stops sweeping                                               |
+| `EVE_TRACES_CONTENT`         | on                   | `off` stops capturing model prompt/response and tool input/output attributes on local spans |
+| `EVE_TRACES_MAX_AGE_MS`      | `604800000` (7d)     | Age after which a trace may be evicted                                                      |
+| `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store                                                             |
+| `EVE_TRACES_RETAIN_COUNT`    | `20`                 | Newest traces kept regardless of age or size                                                |
 
 Set these in `.env.local`, which `eve dev` loads automatically. Each bound accepts `off` to disable it individually — note that `EVE_TRACES_RETAIN_COUNT=off` removes the keep-newest guarantee rather than retaining everything.
 

package/docs/reference/cli.md

@@ -252,7 +252,15 @@ eve traces                 # show the most recent span tree
 eve traces <trace>         # show one span tree
 ```
 
-`eve traces ls` reads the immutable OTLP/JSON segments captured under `.eve/traces/v1`; `eve dev` does not need to be running. `eve traces` accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed or incomplete segments are skipped without hiding valid spans from the same trace.
+Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need not be running. Accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed segments are skipped without hiding valid spans from the same trace.
+
+A subagent keeps its own session id but records into the trace its parent had open at dispatch, so delegated work appears under the session that caused it, tagged with `agent.root.session.id`. Either session id resolves to that trace. A remote agent traces under its own deployment and is not recorded here.
+
+A session long enough to outgrow one trace — far longer than anything you will drive locally — continues into a new one. Each is a session window, numbered from zero on `agent.session.window`; passing a session id shows every window it produced, oldest first, and a trace id shows just that window.
+
+One parent turn can dispatch several subagents into the same window, so a child's turn spans name the dispatch: `agent.parent.session.id`, `agent.parent.turn.id`, and `agent.parent.call_id` identify the tool call that created the child, and `agent.subagent.name` the subagent it invoked. Top-level sessions carry none of these.
+
+`agent.session` and `agent.turn` outlive the worker that opened them, so they are recorded as zero-duration markers. The span tree shows their descendant extent instead; `agent.step` and the model and tool spans beneath it carry real durations. A third-party OTel backend reports zero for the markers.
 
 ## `eve link`
 

package/docs/sandbox.mdx

@@ -20,7 +20,7 @@ The model already has shell and file access through the default tools:
 | `glob`                     | find files by pattern               |
 | `grep`                     | search file contents                |
 
-All of them run with `/workspace` as the working directory. Any authored runtime function (a tool, a step, a model callback) can get a live sandbox handle with `ctx.getSandbox()`.
+All of them run with `/workspace` as the working directory. The model-facing file tools accept both absolute paths and paths beginning with `$HOME/`; eve resolves the latter inside the sandbox before reading, writing, or searching. Any authored runtime function (a tool, a step, a model callback) can get a live sandbox handle with `ctx.getSandbox()`.
 
 ```ts title="agent/tools/run_analysis.ts"
 import { defineTool } from "eve/tools";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.29.2",
+  "version": "0.29.3",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -236,6 +236,11 @@
       "import": "./dist/src/public/channels/chat-sdk/index.js",
       "default": "./dist/src/public/channels/chat-sdk/index.js"
     },
+    "./channels/photon": {
+      "types": "./dist/src/public/channels/photon/index.d.ts",
+      "import": "./dist/src/public/channels/photon/index.js",
+      "default": "./dist/src/public/channels/photon/index.js"
+    },
     "./channels/github": {
       "types": "./dist/src/public/channels/github/index.d.ts",
       "import": "./dist/src/public/channels/github/index.js",
@@ -303,6 +308,7 @@
     "@opentelemetry/context-async-hooks": "2.6.1",
     "@opentelemetry/otlp-transformer": "0.214.0",
     "@opentelemetry/sdk-trace-base": "2.6.1",
+    "@photon-ai/chat-adapter-imessage": "3.2.0",
     "@standard-schema/spec": "1.1.0",
     "@sveltejs/kit": "^2.0.0",
     "@types/json-schema": "7.0.15",

package/dist/src/compiled/_chunks/node/auth-DMsLOrh7.js

@@ -1,2 +0,0 @@
-import{i as e,o as t,t as n}from"./rolldown-runtime-DaDcL9Zw.js";import{c as r,d as i,h as a,i as o,l as s,m as c,n as l,p as u,s as d,t as f}from"./version-BQBAL95V.js";import*as p from"node:path";import m from"node:path";import{homedir as h}from"node:os";import g from"node:fs";import*as _ from"node:fs/promises";import v from"os";import{setTimeout as y}from"node:timers/promises";const ee={invalid_type:`invalid_type`,too_big:`too_big`,too_small:`too_small`,invalid_format:`invalid_format`,not_multiple_of:`not_multiple_of`,unrecognized_keys:`unrecognized_keys`,invalid_union:`invalid_union`,invalid_key:`invalid_key`,invalid_element:`invalid_element`,invalid_value:`invalid_value`,custom:`custom`};var b;b||={};const x=i().transform((e,t)=>{try{return JSON.parse(e)}catch(e){return t.addIssue({code:ee.custom,message:`Invalid JSON: ${e.message}`}),a}});var S=n(((t,n)=>{let r=e(`os`),i=e(`path`),a=/^win/i.test(process.platform);function o(e){return i.normalize(i.join(e,`.`))}let s=()=>{let{env:e}=process,t={};return t.home=()=>o(r.homedir?r.homedir():e.HOME),t.temp=()=>o(r.tmpdir?r.tmpdir():e.TMPDIR||e.TEMP||e.TMP),t},c=()=>{let{env:e}=process,t={};return t.home=()=>o(r.homedir?r.homedir():e.USERPROFILE||i.join(e.HOMEDRIVE,e.HOMEPATH)||e.HOME),t.temp=()=>o(r.tmpdir?r.tmpdir():e.TEMP||e.TMP||i.join(e.LOCALAPPDATA||e.SystemRoot||e.windir,`Temp`)),t};n.exports=new class e{constructor(){let t=function(){return new e};this._fn=t;let n=a?c():s();return Object.keys(n).forEach(e=>{this._fn[e]=n[e]}),this._fn}}})),C=n(((t,n)=>{let r=e(`path`),i=S(),a=()=>{let e={};return e.cache=()=>process.env.XDG_CACHE_HOME||r.join(i.home()||i.temp(),`.cache`),e.config=()=>process.env.XDG_CONFIG_HOME||r.join(i.home()||i.temp(),`.config`),e.data=()=>process.env.XDG_DATA_HOME||r.join(i.home()||i.temp(),`.local`,`share`),e.runtime=()=>process.env.XDG_RUNTIME_DIR||void 0,e.state=()=>process.env.XDG_STATE_HOME||r.join(i.home()||i.temp(),`.local`,`state`),e},o=()=>{let e={};return e.cache=()=>process.env.XDG_CACHE_HOME||r.join(r.join(i.home()||i.temp(),`Library`),`Caches`),e.config=()=>process.env.XDG_CONFIG_HOME||r.join(r.join(i.home()||i.temp(),`Library`),`Preferences`),e.data=()=>process.env.XDG_DATA_HOME||r.join(r.join(i.home()||i.temp(),`Library`),`Application Support`),e.runtime=()=>process.env.XDG_RUNTIME_DIR||void 0,e.state=()=>process.env.XDG_STATE_HOME||r.join(r.join(i.home()||i.temp(),`Library`),`State`),e},s=()=>{let e={};return e.cache=()=>{let e=process.env.LOCALAPPDATA||r.join(i.home()||i.temp(),`AppData`,`Local`);return process.env.XDG_CACHE_HOME||r.join(e,`xdg.cache`)},e.config=()=>{let e=process.env.APPDATA||r.join(i.home()||i.temp(),`AppData`,`Roaming`);return process.env.XDG_CONFIG_HOME||r.join(e,`xdg.config`)},e.data=()=>{let e=process.env.APPDATA||r.join(i.home()||i.temp(),`AppData`,`Roaming`);return process.env.XDG_DATA_HOME||r.join(e,`xdg.data`)},e.runtime=()=>process.env.XDG_RUNTIME_DIR||void 0,e.state=()=>{let e=process.env.LOCALAPPDATA||r.join(i.home()||i.temp(),`AppData`,`Local`);return process.env.XDG_STATE_HOME||r.join(e,`xdg.state`)},e},c=()=>{let e=function(){return c()},t={};return t=/^darwin$/i.test(process.platform)?o():/^win/i.test(process.platform)?s():a(),t.configDirs=()=>{let e=[];return e.push(t.config()),process.env.XDG_CONFIG_DIRS&&e.push(...process.env.XDG_CONFIG_DIRS.split(r.delimiter)),e},t.dataDirs=()=>{let e=[];return e.push(t.data()),process.env.XDG_DATA_DIRS&&e.push(...process.env.XDG_DATA_DIRS.split(r.delimiter)),e},Object.keys(t).forEach(n=>{e[n]=t[n]}),e};n.exports=c()})),w=t(n(((t,n)=>{let r=e(`path`),i=e(`os`),a=C(),o=/^win/i.test(process.platform);function s(e,t){if(e||={},typeof e!=`object`&&(e={isolated:e}),e.isolated=e.isolated===void 0||e.isolated===null?t:e.isolated,typeof e.isolated!=`boolean`)throw TypeError(`Expected boolean for "isolated" argument, got ${typeof e.isolated}`);return e}let c=(e,t)=>{let n={};return n.cache=(n={isolated:null})=>(n=s(n,t),r.join(a.cache(),n.isolated?e:``)),n.config=(n={isolated:null})=>(n=s(n,t),r.join(a.config(),n.isolated?e:``)),n.data=(n={isolated:null})=>(n=s(n,t),r.join(a.data(),n.isolated?e:``)),n.runtime=(n={isolated:null})=>(n=s(n,t),a.runtime()?r.join(a.runtime(),n.isolated?e:``):void 0),n.state=(n={isolated:null})=>(n=s(n,t),r.join(a.state(),n.isolated?e:``)),n.configDirs=(n={isolated:null})=>(n=s(n,t),a.configDirs().map(t=>r.join(t,n.isolated?e:``))),n.dataDirs=(n={isolated:null})=>(n=s(n,t),a.dataDirs().map(t=>r.join(t,n.isolated?e:``))),n},l=(e,t)=>{let{env:n}=process,o=i.homedir(),c=i.tmpdir(),l=n.APPDATA||r.join(o||c,`AppData`,`Roaming`),u=n.LOCALAPPDATA||r.join(o||c,`AppData`,`Local`),d={};return d.cache=(i={isolated:null})=>(i=s(i,t),!i.isolated||n.XDG_CACHE_HOME?r.join(a.cache(),i.isolated?e:``):r.join(u,i.isolated?e:``,`Cache`)),d.config=(i={isolated:null})=>(i=s(i,t),!i.isolated||n.XDG_CONFIG_HOME?r.join(a.config(),i.isolated?e:``):r.join(l,i.isolated?e:``,`Config`)),d.data=(i={isolated:null})=>(i=s(i,t),!i.isolated||n.XDG_DATA_HOME?r.join(a.data(),i.isolated?e:``):r.join(l,i.isolated?e:``,`Data`)),d.runtime=(n={isolated:null})=>(n=s(n,t),a.runtime()?r.join(a.runtime(),n.isolated?e:``):void 0),d.state=(i={isolated:null})=>(i=s(i,t),!i.isolated||n.XDG_STATE_HOME?r.join(a.state(),i.isolated?e:``):r.join(u,i.isolated?e:``,`State`)),d.configDirs=(i={isolated:null})=>{i=s(i,t);let a=[d.config(i)];return n.XDG_CONFIG_DIRS&&a.push(...n.XDG_CONFIG_DIRS.split(r.delimiter).map(t=>r.join(t,i.isolated?e:``))),a},d.dataDirs=(i={isolated:null})=>{i=s(i,t);let a=[d.data(i)];return n.XDG_DATA_DIRS&&a.push(...n.XDG_DATA_DIRS.split(r.delimiter).map(t=>r.join(t,i.isolated?e:``))),a},d};n.exports=new class t{constructor(n={name:null,suffix:null,isolated:!0}){let i=function(e={name:null,suffix:null,isolated:!0}){return new t(e)};this._fn=i,n||={},typeof n!=`object`&&(n={name:n});let a=n.name||``;if(typeof a!=`string`)throw TypeError(`Expected string for "name" argument, got ${typeof a}`);let s=n.suffix||``;if(typeof s!=`string`)throw TypeError(`Expected string for "suffix" argument, got ${typeof s}`);let u=n.isolated===void 0||n.isolated===null||n.isolated;if(typeof u!=`boolean`)throw TypeError(`Expected boolean for "isolated" argument, got ${typeof u}`);a||=r.parse(process.pkg?process.execPath:e.main?e.main.filename:process.argv[0]).name,s&&(a+=s),this._fn.$name=()=>a,this._fn.$isolated=()=>u;let d=o?l(a,u):c(a,u);return Object.keys(d).forEach(e=>{this._fn[e]=d[e]}),this._fn}}}))(),1);const T=r().transform(e=>new Date(e*1e3)),E=s({token:i().min(1).optional(),refreshToken:i().min(1).optional(),expiresAt:T.optional()}),D=x.pipe(E),te=e=>{try{return g.lstatSync(e).isDirectory()}catch{return!1}},O=()=>{if(process.env.VERCEL_AUTH_CONFIG_DIR)return process.env.VERCEL_AUTH_CONFIG_DIR;let e=(0,w.default)(`com.vercel.cli`).dataDirs();return[...e,m.join(h(),`.now`),...(0,w.default)(`now`).dataDirs()].find(e=>te(e))||e[0]},ne=()=>{try{let e=m.join(O(),`auth.json`);return D.parse(g.readFileSync(e,`utf8`))}catch{return null}};function k(e){let t=m.join(O(),`auth.json`);g.mkdirSync(m.dirname(t),{recursive:!0});let n={token:e.token,expiresAt:e.expiresAt&&Math.round(e.expiresAt.getTime()/1e3),refreshToken:e.refreshToken};g.writeFileSync(t,JSON.stringify(n)+`
-`)}const A=`${v.hostname()} @ vercel/sandbox/${f} node-${process.version} ${v.platform()} (${v.arch()})`,j=new URL(`https://vercel.com`),M=`cl_HYyOPBNtFMfHhaUn9L4QPfTZz6TP47bp`,N=s({issuer:i().url(),device_authorization_endpoint:i().url(),token_endpoint:i().url(),revocation_endpoint:i().url(),jwks_uri:i().url(),introspection_endpoint:i().url()});let P;const F=s({device_code:i(),user_code:i(),verification_uri:i().url(),verification_uri_complete:i().url(),expires_in:r(),interval:r()}),I=s({active:d(!0),client_id:i(),session_id:i()}).or(s({active:d(!1)}));async function L(){if(P)return P;let e=await fetch(new URL(`.well-known/openid-configuration`,j),{headers:{"Content-Type":`application/json`,"user-agent":A}});return P=N.parse(await e.json()),P}async function R(){let e=await L();return{async deviceAuthorizationRequest(){let t=await(await fetch(e.device_authorization_endpoint,{method:`POST`,headers:{"Content-Type":`application/x-www-form-urlencoded`,"user-agent":A},body:new URLSearchParams({client_id:M,scope:`openid offline_access`})})).json(),n=F.safeParse(t);if(!n.success)throw new H(`Failed to parse device authorization response from the Vercel authorization server.`,t);return{device_code:n.data.device_code,user_code:n.data.user_code,verification_uri:n.data.verification_uri,verification_uri_complete:n.data.verification_uri_complete,expiresAt:Date.now()+n.data.expires_in*1e3,interval:n.data.interval}},async deviceAccessTokenRequest(t){try{return[null,await fetch(e.token_endpoint,{method:`POST`,headers:{"Content-Type":`application/x-www-form-urlencoded`,"user-agent":A},body:new URLSearchParams({client_id:M,grant_type:`urn:ietf:params:oauth:grant-type:device_code`,device_code:t}),signal:AbortSignal.timeout(10*1e3)})]}catch(e){return e instanceof Error?[e]:[Error(`An unknown error occurred. See the logs for details.`,{cause:e})]}},async processTokenResponse(e){let t=await e.json(),n=z.safeParse(t);return n.success?[null,n.data]:[new H(`Failed to parse token response from the Vercel authorization server.`,t)]},async revokeToken(t){let n=await fetch(e.revocation_endpoint,{method:`POST`,headers:{"Content-Type":`application/x-www-form-urlencoded`,"user-agent":A},body:new URLSearchParams({token:t,client_id:M})});if(!n.ok)return new H(`Revocation request failed`,await n.json())},async refreshToken(t){let n=await fetch(e.token_endpoint,{method:`POST`,headers:{"Content-Type":`application/x-www-form-urlencoded`,"user-agent":A},body:new URLSearchParams({client_id:M,grant_type:`refresh_token`,refresh_token:t})}),[r,i]=await this.processTokenResponse(n);if(r)throw r;return i},async introspectToken(t){let n=await(await fetch(e.introspection_endpoint,{method:`POST`,headers:{"Content-Type":`application/x-www-form-urlencoded`,"user-agent":A},body:new URLSearchParams({token:t})})).json(),r=I.safeParse(n);if(!r.success)throw new H(`Failed to parse introspection response from the Vercel authorization server.`,n);return r.data}}}const z=s({access_token:i(),token_type:d(`Bearer`),expires_in:r(),refresh_token:i().optional(),scope:i().optional()}),B=s({error:l([`invalid_request`,`invalid_client`,`invalid_grant`,`unauthorized_client`,`unsupported_grant_type`,`invalid_scope`,`server_error`,`authorization_pending`,`slow_down`,`access_denied`,`expired_token`,`unsupported_token_type`]),error_description:i().optional(),error_uri:i().optional()});function V(e){try{return B.parse(e)}catch(e){return e instanceof c?TypeError(`Invalid OAuth error response: ${e.message}`):TypeError(`Failed to parse OAuth error response`)}}var H=class extends Error{constructor(e,t){super(e),this.name=`OAuthError`;let n=V(t);if(n instanceof TypeError){this.cause=Error(`Unexpected response from the Vercel authorization server.`),this.code=`server_error`;return}let r=n.error;n.error_description&&(r+=`: ${n.error_description}`),n.error_uri&&(r+=` (${n.error_uri})`),this.cause=Error(r),this.code=n.error}};function U(e){return e instanceof H}async function*W({request:e,oauth:t}){let n=new AbortController;try{let r=e.interval*1e3;for(;Date.now()<e.expiresAt;){let[i,a]=await t.deviceAccessTokenRequest(e.device_code);if(i){if(i.message.includes(`timeout`)){r*=2,yield{_tag:`Timeout`,newInterval:r},await y(r,{signal:n.signal});continue}yield{_tag:`Error`,error:i};return}yield{_tag:`Response`,response:a.clone()};let[o,s]=await t.processTokenResponse(a);if(U(o)){let{code:e}=o;switch(e){case`authorization_pending`:await y(r,{signal:n.signal});continue;case`slow_down`:r+=5*1e3,yield{_tag:`SlowDown`,newInterval:r},await y(r,{signal:n.signal});continue;default:yield{_tag:`Error`,error:o.cause};return}}if(o){yield{_tag:`Error`,error:o};return}k({token:s.access_token,expiresAt:new Date(Date.now()+s.expires_in*1e3),refreshToken:s.refresh_token});return}yield{_tag:`Error`,error:Error(`Timed out waiting for authentication. Please try again.`)};return}finally{n.abort()}}var G=class extends Error{constructor(e){super(`HTTP ${e.statusCode}: ${e.responseText}`),this.name=`NotOk`,this.response=e}};async function K(e){let t=await fetch(`https://vercel.com/api${e.endpoint}`,{method:e.method,body:e.body,headers:{Authorization:`Bearer ${e.token}`,"Content-Type":`application/json`}});if(!t.ok){let e=await t.text();try{let{error:t}=JSON.parse(e);e=`${t.code.toUpperCase()}: ${t.message}`}catch{}throw new G({responseText:e,statusCode:t.status})}return await t.json()}const q=x.pipe(s({projectId:i(),orgId:i()}));async function J(e){let t=p.join(e,`.vercel`,`project.json`),n;try{n=await _.readFile(t,`utf-8`)}catch{return null}let r=q.safeParse(n);return r.success?{projectId:r.data.projectId,teamId:r.data.orgId}:null}const Y=s({user:s({defaultTeamId:i().nullable(),username:i()})}),X=s({id:i(),slug:i(),updatedAt:r().optional(),membership:s({role:i()}),billing:s({plan:i()})}),re=s({teams:o(u()).transform(e=>e.flatMap(e=>{let t=X.safeParse(e);return t.success?[t.data]:[]})),pagination:s({count:r(),next:r().nullable()})}),Z=`vercel-sandbox-default-project`;function Q(e){return e instanceof G&&(e.response.statusCode===402||e.response.statusCode===403)}async function ie(e){let t=await J(e.cwd??process.cwd());if(t){let n=await ae(e.token,t.teamId,t.projectId);return{...t,created:!1,...n}}if(e.teamId)return $(e.token,e.teamId);let{defaultTeamId:n,username:r}=(await K({token:e.token,endpoint:`/v2/user`}).then(Y.parse)).user;if(n)try{let t=await $(e.token,n);try{let r=await K({token:e.token,endpoint:`/v2/teams/${encodeURIComponent(n)}`}).then(s({slug:i()}).parse);return{...t,teamSlug:r.slug}}catch{return t}}catch(e){if(!Q(e))throw e}let a=null;do{let t=a===null?`/v2/teams?limit=20`:`/v2/teams?limit=20&until=${a}`,i=await K({token:e.token,endpoint:t}).then(re.parse);a=i.pagination.next;let o=i.teams.filter(e=>e.membership.role===`OWNER`&&e.billing.plan===`hobby`);if(o.length===0)continue;let s=o.find(e=>e.slug===r)??o.sort((e,t)=>(t.updatedAt??0)-(e.updatedAt??0))[0];if(s&&s.id!==n)try{return{...await $(e.token,s.id),teamSlug:s.slug}}catch(e){if(!Q(e))throw e}}while(a!==null);try{return{...await $(e.token,r),teamSlug:r}}catch(e){if(!Q(e))throw e}throw new G({statusCode:403,responseText:`Authenticated as "${r}" but none of the available teams allow sandbox creation.`})}async function $(e,t){let n=t.startsWith(`team_`)?`teamId=${encodeURIComponent(t)}`:`slug=${encodeURIComponent(t)}`,r=!1;try{await K({token:e,endpoint:`/v2/projects/vercel-sandbox-default-project?${n}`})}catch(t){if(!(t instanceof G)||t.response.statusCode!==404)throw t;await K({token:e,endpoint:`/v11/projects?${n}`,method:`POST`,body:JSON.stringify({name:Z})}),r=!0}return{projectId:Z,teamId:t,created:r}}async function ae(e,t,n){try{let r=t.startsWith(`team_`)?`teamId=${encodeURIComponent(t)}`:`slug=${encodeURIComponent(t)}`,[a,o]=await Promise.all([K({token:e,endpoint:`/v2/teams/${encodeURIComponent(t)}`}).then(s({slug:i()}).parse),K({token:e,endpoint:`/v2/projects/${encodeURIComponent(n)}?${r}`}).then(s({name:i()}).parse)]);return{teamSlug:a.slug,projectSlug:o.name}}catch{return{}}}export{G as NotOk,R as OAuth,ne as getAuth,ie as inferScope,U as isOAuthError,W as pollForToken,k as updateAuthConfig};