eve 0.33.3 → 0.35.0

package/dist/src/harness/instrumentation/lifecycle.d.ts

@@ -0,0 +1,491 @@
+import type { InstrumentationStateSlot } from "#harness/instrumentation/state.js";
+import type { RuntimeTraceContext } from "#protocol/message.js";
+/**
+ * Stable eve identity for one actual model attempt.
+ *
+ * A step retried three times produces three of these, all sharing `stepIndex`
+ * and separated by `attemptIndex` — which is why the events carrying this
+ * scope are named `step.attempt.*` and not `step.*`. The protocol's `step.*`
+ * and the `events["step.started"]` resolver hook fire once per step; these
+ * fire once per attempt.
+ */
+export interface InstrumentationAttemptScope {
+    readonly attemptId: string;
+    readonly attemptIndex: number;
+    readonly functionId?: string;
+    readonly rootSessionId?: string;
+    readonly sessionId: string;
+    readonly stepIndex: number;
+    readonly turnId: string;
+}
+/** The model SDK operation an attempt runs through. */
+export interface InstrumentationOperationRef {
+    readonly modelId: string;
+    readonly operationId: string;
+    readonly provider: string;
+}
+export interface InstrumentationModelRef {
+    readonly modelId: string;
+    readonly provider: string;
+}
+/** Token usage for one model call. A field is absent when the provider omits it. */
+export interface InstrumentationUsage {
+    readonly inputTokenDetails?: {
+        readonly cacheReadTokens?: number;
+        readonly cacheWriteTokens?: number;
+    };
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}
+/** Final model input for one call. Message shape stays opaque to this layer. */
+export interface InstrumentationModelInput {
+    readonly instructions?: unknown;
+    readonly messages: readonly unknown[];
+}
+/**
+ * The model response parts eve records. A kind outside this union is dropped
+ * when the bridge maps a response, so widening the union is what makes a new
+ * kind reachable by a provider.
+ */
+export type InstrumentationContentPart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "reasoning";
+    readonly text: string;
+} | {
+    readonly type: "tool-call";
+    readonly callId: string;
+    readonly input: unknown;
+    readonly toolName: string;
+} | {
+    readonly type: "tool-result";
+    readonly callId: string;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly toolName: string;
+} | {
+    readonly type: "tool-error";
+    readonly callId: string;
+    readonly error: unknown;
+    readonly input: unknown;
+    readonly toolName: string;
+};
+/**
+ * What eve dispatched an action as. The model sees every action as a tool, so
+ * this is the only thing that separates a subagent or remote-agent call from an
+ * ordinary tool in a trace.
+ */
+export type InstrumentationActionKind = "load-skill" | "remote-agent-call" | "subagent-call" | "tool-call";
+/**
+ * How one action ended.
+ *
+ * `type` survives a provider that declined content, so whether the tool errored
+ * is answerable without seeing what it returned.
+ */
+export type InstrumentationActionOutput = {
+    readonly type: "result";
+    readonly output?: unknown;
+} | {
+    readonly type: "error";
+    readonly error?: unknown;
+};
+/**
+ * How much of an event a provider is handed.
+ *
+ * `"metadata"` — the default — is structure, identity, usage, and timing: every
+ * field except what the conversation actually said. `"content"` adds the
+ * prompt, the response, tool arguments, and tool results.
+ *
+ * Declared per provider rather than per process, because two consumers of one
+ * bus rarely have the same retention path. Content is built at all only when
+ * some provider asked for it, and a provider that did not ask never receives
+ * it — which is the same guarantee a destination that declines content gets,
+ * one layer lower and without an OpenTelemetry pipeline to route it through.
+ */
+export type InstrumentationCapture = "content" | "metadata";
+/**
+ * Every event carries an `idempotencyKey` naming the operation it is about: a
+ * start and its terminal share one, and two operations never collide.
+ *
+ * Every part is identity eve reconstructs on replay — session and turn ids,
+ * `scope.attemptId` (itself `session:turn:step:attempt`), AI SDK step number,
+ * and durable runtime-action call ids. A provider writing rows can use the key
+ * as its row id and be idempotent by construction.
+ */
+export declare function sessionIdempotencyKey(sessionId: string): string;
+export declare function turnIdempotencyKey(sessionId: string, turnId: string): string;
+export declare function attemptIdempotencyKey(scope: InstrumentationAttemptScope): string;
+/** One model call occurs per AI SDK step within an eve attempt. */
+export declare function modelCallIdempotencyKey(scope: InstrumentationAttemptScope, stepNumber: number): string;
+export declare function toolCallIdempotencyKey(scope: InstrumentationAttemptScope, callId: string, stepNumber: number): string;
+export declare function inputIdempotencyKey(sessionId: string, turnId: string, requestId: string): string;
+export declare function channelDeliveryIdempotencyKey(sessionId: string, deliveryId: string): string;
+export interface InstrumentationChannelDeliveryRef {
+    readonly channelKind: string;
+    readonly channelName: string;
+    readonly deliveryId: string;
+    readonly requestId?: string;
+    readonly requestTraceContext?: InstrumentationTraceContext;
+}
+/** Known framework delivery input; adapter-specific fields are never projected. */
+export interface InstrumentationChannelDeliveryInput {
+    readonly context?: readonly string[];
+    readonly inputResponses?: readonly InstrumentationInputResponse[];
+    readonly message?: unknown;
+    readonly outputSchema?: unknown;
+}
+interface InstrumentationChannelDeliveryScope {
+    readonly agentName?: string;
+    readonly delivery: InstrumentationChannelDeliveryRef;
+    readonly idempotencyKey: string;
+    readonly rootSessionId: string;
+    readonly sequence?: number;
+    readonly sessionId: string;
+    readonly turnId?: string;
+}
+export interface InstrumentationChannelDeliveryStartedEvent extends InstrumentationChannelDeliveryScope {
+    readonly parentTraceContext?: InstrumentationTraceContext;
+    readonly type: "channel.delivery.started";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly input?: InstrumentationChannelDeliveryInput;
+}
+export type InstrumentationChannelDeliveryOutcome = "cancelled" | "completed" | "failed";
+export interface InstrumentationChannelDeliveryTerminalEvent extends InstrumentationChannelDeliveryScope {
+    readonly type: "channel.delivery.cancelled" | "channel.delivery.completed" | "channel.delivery.failed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly errorCode?: string;
+    readonly outcome: InstrumentationChannelDeliveryOutcome;
+}
+/** Framework-owned reason an agent suspended for user input. */
+export type InstrumentationInputKind = "question" | "session-limit" | "tool-approval";
+export interface InstrumentationInputOption {
+    readonly description?: string;
+    readonly id: string;
+    readonly label: string;
+    readonly style?: "danger" | "default" | "primary";
+}
+/** User-facing input request content projected without runtime-owned types. */
+export interface InstrumentationInputRequest {
+    readonly allowFreeform?: boolean;
+    readonly display?: "confirmation" | "select" | "text";
+    readonly options?: readonly InstrumentationInputOption[];
+    readonly prompt: string;
+}
+/** User response content projected without runtime-owned types. */
+export interface InstrumentationInputResponse {
+    readonly optionId?: string;
+    readonly text?: string;
+}
+export type InstrumentationInputOutcome = "answered" | "approved" | "cancelled" | "denied" | "failed" | "ignored" | "invalid";
+export interface InstrumentationInputRequestedEvent {
+    readonly type: "input.requested";
+    readonly action: {
+        readonly callId: string;
+        readonly name: string;
+    };
+    readonly idempotencyKey: string;
+    readonly kind: InstrumentationInputKind;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly request?: InstrumentationInputRequest;
+    readonly requestId: string;
+    readonly scope: InstrumentationAttemptScope;
+}
+export interface InstrumentationInputResolvedEvent {
+    readonly type: "input.resolved";
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
+    readonly kind: InstrumentationInputKind;
+    readonly outcome: InstrumentationInputOutcome;
+    readonly requestId: string;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly response?: InstrumentationInputResponse;
+    readonly scope: InstrumentationAttemptScope;
+}
+/** Runtime action call IDs are durable and unique within one session. */
+export declare function actionIdempotencyKey(sessionId: string, turnId: string, callId: string): string;
+export interface InstrumentationStepAttemptStartedEvent {
+    readonly type: "step.attempt.started";
+    readonly idempotencyKey: string;
+    readonly operation: InstrumentationOperationRef;
+    readonly scope: InstrumentationAttemptScope;
+}
+export interface InstrumentationSessionStartedEvent {
+    readonly type: "session.started";
+    readonly agentName?: string;
+    readonly channelKind?: string;
+    readonly idempotencyKey: string;
+    readonly parentTraceContext?: InstrumentationTraceContext;
+    readonly rootSessionId: string;
+    readonly sessionId: string;
+}
+export type InstrumentationTraceContext = RuntimeTraceContext;
+/**
+ * Which tool call dispatched a subagent child. The trace structure alone
+ * cannot say: one turn's children all parent to the same window.
+ */
+export interface InstrumentationParentLineage {
+    readonly callId: string;
+    readonly sessionId: string;
+    readonly subagentName?: string;
+    readonly turnId: string;
+}
+/**
+ * A session transition that carries no failure.
+ *
+ * `session.waiting` sits here rather than with the failed shape because it is
+ * not terminal: the session suspends awaiting input or approval and may resume
+ * with a new turn.
+ */
+export interface InstrumentationSessionSettledEvent {
+    readonly type: "session.completed" | "session.waiting";
+    readonly idempotencyKey: string;
+    readonly sessionId: string;
+    readonly turnId?: string;
+}
+export interface InstrumentationSessionFailedEvent {
+    readonly type: "session.failed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
+    readonly sessionId: string;
+    readonly turnId?: string;
+}
+export type InstrumentationSessionTransitionEvent = InstrumentationSessionSettledEvent | InstrumentationSessionFailedEvent;
+export interface InstrumentationTurnStartedEvent {
+    readonly type: "turn.started";
+    readonly idempotencyKey: string;
+    readonly parentLineage?: InstrumentationParentLineage;
+    readonly parentTraceContext?: InstrumentationTraceContext;
+    readonly rootSessionId: string;
+    readonly sequence: number;
+    readonly sessionId: string;
+    readonly turnId: string;
+}
+/**
+ * A turn that ended without a failure.
+ *
+ * `turn.cancelled` sits here rather than with the failed shape because
+ * cancellation is not an error: the harness settles a cancelled turn as
+ * `turn.cancelled` → `session.waiting`, with no failure surfaced anywhere.
+ */
+export interface InstrumentationTurnSettledEvent {
+    readonly type: "turn.cancelled" | "turn.completed";
+    readonly idempotencyKey: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+}
+export interface InstrumentationTurnFailedEvent {
+    readonly type: "turn.failed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+}
+export type InstrumentationTurnTerminalEvent = InstrumentationTurnSettledEvent | InstrumentationTurnFailedEvent;
+export interface InstrumentationStepAttemptCompletedEvent {
+    readonly type: "step.attempt.completed";
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+}
+export interface InstrumentationStepAttemptFailedEvent {
+    readonly type: "step.attempt.failed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+}
+export type InstrumentationStepAttemptTerminalEvent = InstrumentationStepAttemptCompletedEvent | InstrumentationStepAttemptFailedEvent;
+/**
+ * Provider metadata for one completed attempt, as reported by the AI SDK
+ * (`StepResult.providerMetadata`). Carries Vercel AI Gateway cost data when
+ * the request went through the gateway; absent for other providers.
+ */
+export interface InstrumentationStepAttemptMetadataEvent {
+    readonly type: "step.attempt.metadata";
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+    readonly providerMetadata: Readonly<Record<string, unknown>>;
+}
+export interface InstrumentationModelCallStartedEvent {
+    readonly type: "model.call.started";
+    readonly idempotencyKey: string;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly input?: InstrumentationModelInput;
+    readonly model: InstrumentationModelRef;
+    readonly scope: InstrumentationAttemptScope;
+}
+export interface InstrumentationModelCallCompletedEvent {
+    readonly type: "model.call.completed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly content?: readonly InstrumentationContentPart[];
+    readonly finishReason: string;
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+    readonly usage: InstrumentationUsage;
+}
+export interface InstrumentationModelCallFailedEvent {
+    readonly type: "model.call.failed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+}
+export type InstrumentationModelCallTerminalEvent = InstrumentationModelCallCompletedEvent | InstrumentationModelCallFailedEvent;
+export type InstrumentationToolOutput = InstrumentationActionOutput;
+export interface InstrumentationToolCallStartedEvent {
+    readonly type: "tool.call.started";
+    readonly callId: string;
+    readonly idempotencyKey: string;
+    readonly input: unknown;
+    readonly scope: InstrumentationAttemptScope;
+    readonly toolName: string;
+}
+export interface InstrumentationToolCallCompletedEvent {
+    readonly type: "tool.call.completed";
+    readonly idempotencyKey: string;
+    readonly output: InstrumentationToolOutput;
+    readonly scope: InstrumentationAttemptScope;
+}
+export interface InstrumentationToolCallFailedEvent {
+    readonly type: "tool.call.failed";
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+}
+export type InstrumentationToolCallTerminalEvent = InstrumentationToolCallCompletedEvent | InstrumentationToolCallFailedEvent;
+/**
+ * One thing the agent did on the model's behalf. `kind` is what separates a
+ * subagent or remote-agent call from an ordinary tool; `name` is the name the
+ * model called, which is the tool name for every kind.
+ */
+export interface InstrumentationActionStartedEvent {
+    readonly type: "action.started";
+    readonly callId: string;
+    readonly idempotencyKey: string;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly input?: unknown;
+    readonly kind: InstrumentationActionKind;
+    readonly name: string;
+    readonly scope: InstrumentationAttemptScope;
+}
+export type InstrumentationActionOutcome = "abandoned" | "cancelled" | "completed" | "failed" | "rejected";
+export interface InstrumentationActionCompletedEvent {
+    readonly type: "action.completed";
+    readonly acceptedAtMs?: number;
+    readonly idempotencyKey: string;
+    readonly outcome: "completed";
+    readonly output: InstrumentationActionOutput;
+    readonly scope: InstrumentationAttemptScope;
+    readonly usage?: InstrumentationUsage;
+}
+export interface InstrumentationActionFailedEvent {
+    readonly type: "action.failed";
+    readonly acceptedAtMs?: number;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly errorCode?: string;
+    readonly idempotencyKey: string;
+    readonly outcome: Exclude<InstrumentationActionOutcome, "completed">;
+    readonly scope: InstrumentationAttemptScope;
+}
+export type InstrumentationActionTerminalEvent = InstrumentationActionCompletedEvent | InstrumentationActionFailedEvent;
+/** The second argument to every handler. */
+export interface InstrumentationHandlerContext {
+    /** Durable state scoped to this provider and this operation. */
+    readonly state: InstrumentationStateSlot;
+}
+/**
+ * The AI SDK can omit a model terminal when an incomplete stream closes. A
+ * handler can use `ctx.state` for durable correlation when a terminal arrives,
+ * but providers must scope live resources to the attempt and release anything
+ * still open when the step attempt terminates.
+ */
+export type InstrumentationEventHandler<TEvent> = (event: TEvent, ctx: InstrumentationHandlerContext) => void | PromiseLike<void>;
+/** Internal provider shape mirrored by the future public hook contract. */
+export interface InstrumentationProviderDefinition {
+    readonly name: string;
+    /** Durable state identity, separate from the human-readable log name. */
+    readonly stateNamespace?: string;
+    /** Defaults to `"metadata"`. See {@link InstrumentationCapture}. */
+    readonly capture?: InstrumentationCapture;
+    readonly events?: {
+        readonly "channel.delivery.started"?: InstrumentationEventHandler<InstrumentationChannelDeliveryStartedEvent>;
+        readonly "channel.delivery.cancelled"?: InstrumentationEventHandler<InstrumentationChannelDeliveryTerminalEvent>;
+        readonly "channel.delivery.completed"?: InstrumentationEventHandler<InstrumentationChannelDeliveryTerminalEvent>;
+        readonly "channel.delivery.failed"?: InstrumentationEventHandler<InstrumentationChannelDeliveryTerminalEvent>;
+        readonly "step.attempt.started"?: InstrumentationEventHandler<InstrumentationStepAttemptStartedEvent>;
+        readonly "step.attempt.completed"?: InstrumentationEventHandler<InstrumentationStepAttemptCompletedEvent>;
+        readonly "step.attempt.failed"?: InstrumentationEventHandler<InstrumentationStepAttemptFailedEvent>;
+        readonly "step.attempt.metadata"?: InstrumentationEventHandler<InstrumentationStepAttemptMetadataEvent>;
+        readonly "model.call.started"?: InstrumentationEventHandler<InstrumentationModelCallStartedEvent>;
+        readonly "model.call.completed"?: InstrumentationEventHandler<InstrumentationModelCallCompletedEvent>;
+        readonly "model.call.failed"?: InstrumentationEventHandler<InstrumentationModelCallFailedEvent>;
+        readonly "input.requested"?: InstrumentationEventHandler<InstrumentationInputRequestedEvent>;
+        readonly "input.resolved"?: InstrumentationEventHandler<InstrumentationInputResolvedEvent>;
+        readonly "session.completed"?: InstrumentationEventHandler<InstrumentationSessionSettledEvent>;
+        readonly "session.failed"?: InstrumentationEventHandler<InstrumentationSessionFailedEvent>;
+        readonly "session.started"?: InstrumentationEventHandler<InstrumentationSessionStartedEvent>;
+        readonly "session.waiting"?: InstrumentationEventHandler<InstrumentationSessionSettledEvent>;
+        readonly "action.started"?: InstrumentationEventHandler<InstrumentationActionStartedEvent>;
+        readonly "action.completed"?: InstrumentationEventHandler<InstrumentationActionCompletedEvent>;
+        readonly "action.failed"?: InstrumentationEventHandler<InstrumentationActionFailedEvent>;
+        readonly "tool.call.started"?: InstrumentationEventHandler<InstrumentationToolCallStartedEvent>;
+        readonly "tool.call.completed"?: InstrumentationEventHandler<InstrumentationToolCallCompletedEvent>;
+        readonly "tool.call.failed"?: InstrumentationEventHandler<InstrumentationToolCallFailedEvent>;
+        readonly "turn.cancelled"?: InstrumentationEventHandler<InstrumentationTurnSettledEvent>;
+        readonly "turn.completed"?: InstrumentationEventHandler<InstrumentationTurnSettledEvent>;
+        readonly "turn.failed"?: InstrumentationEventHandler<InstrumentationTurnFailedEvent>;
+        readonly "turn.started"?: InstrumentationEventHandler<InstrumentationTurnStartedEvent>;
+    };
+    /** Drains anything buffered. Driven by the runtime, not by the bus. */
+    readonly flush?: () => void | PromiseLike<void>;
+    /** Releases resources when the process is going away. */
+    readonly shutdown?: () => void | PromiseLike<void>;
+}
+type InstrumentationProviderInput = Omit<InstrumentationProviderDefinition, "name"> & {
+    readonly name?: string;
+};
+export interface InstrumentationDispatchGroups {
+    readonly serialBefore?: readonly InstrumentationProviderDefinition[];
+    readonly parallel?: readonly InstrumentationProviderDefinition[];
+    readonly serialAfter?: readonly InstrumentationProviderDefinition[];
+}
+export type InstrumentationHooksInput = readonly InstrumentationProviderInput[] | InstrumentationDispatchGroups;
+/** Events that pair a start with its terminal under one `idempotencyKey`. */
+export type InstrumentationCorrelatedEvent = InstrumentationChannelDeliveryStartedEvent | InstrumentationChannelDeliveryTerminalEvent | InstrumentationInputRequestedEvent | InstrumentationInputResolvedEvent | InstrumentationActionStartedEvent | InstrumentationActionTerminalEvent | InstrumentationModelCallStartedEvent | InstrumentationModelCallTerminalEvent | InstrumentationToolCallStartedEvent | InstrumentationToolCallTerminalEvent;
+export type InstrumentationPointEvent = InstrumentationStepAttemptStartedEvent | InstrumentationStepAttemptMetadataEvent | InstrumentationStepAttemptTerminalEvent | InstrumentationSessionStartedEvent | InstrumentationSessionTransitionEvent | InstrumentationTurnStartedEvent | InstrumentationTurnTerminalEvent;
+export type InstrumentationEvent = InstrumentationCorrelatedEvent | InstrumentationPointEvent;
+/** Trusted framework operation for activating context around AI SDK execution. */
+export type InstrumentationContextRunner = <T>(operation: InstrumentationExecutionOperation, execute: () => PromiseLike<T>) => PromiseLike<T>;
+/** Stable identity supplied only to a trusted framework context runner. */
+export type InstrumentationExecutionOperation = {
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+    readonly type: "tool.call";
+} | {
+    readonly idempotencyKey: string;
+    readonly scope: InstrumentationAttemptScope;
+    readonly type: "model.call";
+};
+/** Provider-neutral hook operations consumed by the AI SDK bridge. */
+export interface InstrumentationHooks {
+    /**
+     * Whether any registered provider declared `capture: "content"`.
+     *
+     * False means nothing downstream can read what was said, so the publisher
+     * should not serialize it in the first place. This is the only way the
+     * projection is skipped rather than merely withheld.
+     */
+    readonly capturesContent: boolean;
+    publish(event: InstrumentationEvent): Promise<void>;
+}
+export interface CreateInstrumentationHooksOptions {
+    readonly handlerTimeoutMs?: number;
+}
+/** Creates failure-isolated hooks backed by normalized dispatch groups. */
+export declare function createInstrumentationHooks(input: InstrumentationHooksInput, options?: CreateInstrumentationHooksOptions): InstrumentationHooks;
+export {};

package/dist/src/harness/instrumentation/lifecycle.js

@@ -0,0 +1 @@
+import{createInstrumentationDispatcher}from"#harness/instrumentation/dispatch.js";function sessionIdempotencyKey(e){return`session:${e}`}function turnIdempotencyKey(e,t){return`turn:${e}:${t}`}function attemptIdempotencyKey(e){return`step:${e.attemptId}`}function modelCallIdempotencyKey(e,t){return`model:${e.attemptId}:${String(t)}`}function toolCallIdempotencyKey(e,t,n){return`tool:${e.attemptId}:${t}:${String(n)}`}function inputIdempotencyKey(e,t,n){return`input:${e}:${t}:${n}`}function channelDeliveryIdempotencyKey(e,t){return`channel-delivery:${e}:${t}`}function actionIdempotencyKey(e,t,n){return`action:${e}:${t}:${n}`}function createInstrumentationHooks(t,n={}){return createInstrumentationDispatcher(t,n)}export{actionIdempotencyKey,attemptIdempotencyKey,channelDeliveryIdempotencyKey,createInstrumentationHooks,inputIdempotencyKey,modelCallIdempotencyKey,sessionIdempotencyKey,toolCallIdempotencyKey,turnIdempotencyKey};

package/dist/src/harness/{instrumentation-native-events.d.ts → instrumentation/native-events.d.ts}

@@ -1,7 +1,10 @@
-import type { InstrumentationHooks, InstrumentationParentLineage, InstrumentationTraceContext } from "#harness/instrumentation-lifecycle.js";
+import type { InstrumentationAttemptScope, InstrumentationHooks, InstrumentationParentLineage, InstrumentationTraceContext } from "#harness/instrumentation/lifecycle.js";
+import type { ResolvedInputBatch } from "#harness/input-requests.js";
 import type { HandleEventFn } from "#harness/types.js";
 export interface CreateInstrumentationHandleEventInput {
     readonly agentName?: string;
+    readonly channelKind?: string;
+    readonly getAttemptScope?: () => InstrumentationAttemptScope | undefined;
     readonly handleEvent?: HandleEventFn;
     readonly hooks?: InstrumentationHooks;
     readonly parentLineage?: InstrumentationParentLineage;
@@ -12,3 +15,9 @@ export interface CreateInstrumentationHandleEventInput {
 }
 /** Publishes eve-native lifecycle transitions after durable event acceptance. */
 export declare function createInstrumentationHandleEvent(input: CreateInstrumentationHandleEventInput): HandleEventFn | undefined;
+/** Publishes accepted input resolutions against their original request scope. */
+export declare function publishInputResolutions(input: {
+    readonly batch: ResolvedInputBatch;
+    readonly hooks: InstrumentationHooks;
+    readonly sessionId: string;
+}): Promise<void>;

package/dist/src/harness/instrumentation/native-events.js

@@ -0,0 +1 @@
+import{contextStorage}from"#context/container.js";import{instrumentChannelDelivery}from"#harness/channel-delivery-instrumentation.js";import{rememberInstrumentationActionScope,rememberInstrumentationInputScope,takeInstrumentationActionScopeForCall,takeInstrumentationInputScope}from"#harness/instrumentation/state.js";import{RuntimeActionSettlementTimesKey}from"#harness/runtime-action-settlement-state.js";import{actionIdempotencyKey,inputIdempotencyKey,sessionIdempotencyKey,turnIdempotencyKey}from"#harness/instrumentation/lifecycle.js";function createInstrumentationHandleEvent(n){if(n.hooks===void 0)return n.handleEvent;if(n.handleEvent===void 0)return;let r=n.handleEvent,i=n.hooks,a=new Set,o=new Set,s=n.turnId;return async(c,l)=>{await r(c,l);let u=toLifecycleEvent(c,n,s);if(c.type===`turn.started`&&(s=c.data.turnId),c.type===`turn.cancelled`||c.type===`turn.completed`||c.type===`turn.failed`||c.type===`session.completed`||c.type===`session.failed`){let n=contextStorage.getStore();n!==void 0&&await instrumentChannelDelivery({ctx:n,error:c.type===`turn.failed`||c.type===`session.failed`?Error(c.data.message):void 0,errorCode:c.type===`turn.failed`||c.type===`session.failed`?c.data.code:void 0,hooks:i,includeTurn:c.type===`turn.cancelled`||c.type===`turn.completed`||c.type===`turn.failed`,outcome:c.type===`turn.failed`||c.type===`session.failed`?`failed`:c.type===`turn.cancelled`?`cancelled`:`completed`})}u!==void 0&&await i.publish(u),c.type===`actions.requested`?await publishActionStarts(c,n,i,a):c.type===`action.result`?await publishActionTerminal(c,n,i):c.type===`input.requested`&&await publishInputStarts(c,n,i,o)}}async function publishInputStarts(e,t,n,i){let a=t.getAttemptScope?.();if(a!==void 0)for(let o of e.data.requests){let s=inputIdempotencyKey(t.sessionId,e.data.turnId,o.requestId);i.has(s)||(i.add(s),rememberInstrumentationInputScope(s,a),await n.publish(Object.freeze({action:Object.freeze({callId:o.action.callId,name:o.action.toolName}),idempotencyKey:s,kind:o.kind,request:n.capturesContent?Object.freeze({allowFreeform:o.allowFreeform,display:o.display,options:o.options,prompt:o.prompt}):void 0,requestId:o.requestId,scope:a,type:`input.requested`})))}}async function publishInputResolutions(e){for(let t of e.batch.inputs){let n=inputIdempotencyKey(e.sessionId,e.batch.event.turnId,t.request.requestId),r=takeInstrumentationInputScope(n);r!==void 0&&await e.hooks.publish(Object.freeze({idempotencyKey:n,kind:t.request.kind,outcome:t.outcome,requestId:t.request.requestId,response:!e.hooks.capturesContent||t.response===void 0?void 0:Object.freeze({optionId:t.response.optionId,text:t.response.text}),scope:r,type:`input.resolved`}))}}async function publishActionStarts(e,t,r,i){let a=t.getAttemptScope?.();if(a!==void 0)for(let o of e.data.actions){let c=actionIdempotencyKey(t.sessionId,e.data.turnId,o.callId);i.has(c)||(i.add(c),rememberInstrumentationActionScope(c,a),await r.publish(Object.freeze({callId:o.callId,idempotencyKey:c,input:r.capturesContent?o.input:void 0,kind:o.kind,name:actionName(o),scope:a,type:`action.started`})))}}async function publishActionTerminal(t,n,r){let a=takeInstrumentationActionScopeForCall(n.sessionId,t.data.result.callId);if(a===void 0)return;let{idempotencyKey:s,scope:c}=a;if(t.data.status===`completed`){await r.publish(Object.freeze({acceptedAtMs:contextStorage.getStore()?.get(RuntimeActionSettlementTimesKey)?.[t.data.result.callId],idempotencyKey:s,outcome:`completed`,output:Object.freeze(r.capturesContent?{output:t.data.result.output,type:`result`}:{type:`result`}),scope:c,type:`action.completed`,usage:actionUsage(t.data.result)}));return}let l=t.data.error===void 0?t.data.result.output:Object.assign(Error(t.data.error.message),{code:t.data.error.code});await r.publish(Object.freeze({acceptedAtMs:contextStorage.getStore()?.get(RuntimeActionSettlementTimesKey)?.[t.data.result.callId],error:l,errorCode:t.data.error?.code,idempotencyKey:s,outcome:t.data.status,scope:c,type:`action.failed`}))}function actionUsage(e){if(!(e.kind!==`subagent-result`||e.origin!==`child`||e.usage===void 0))return{inputTokenDetails:{cacheReadTokens:e.usage.cacheReadTokens,cacheWriteTokens:e.usage.cacheWriteTokens},inputTokens:e.usage.inputTokens,outputTokens:e.usage.outputTokens}}function actionName(e){return e.kind===`tool-call`?e.toolName:e.kind===`load-skill`?`load_skill`:e.name}function toLifecycleEvent(e,t,n){switch(e.type){case`session.started`:return{agentName:t.agentName,channelKind:t.channelKind,idempotencyKey:sessionIdempotencyKey(t.sessionId),parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId??t.sessionId,sessionId:t.sessionId,type:`session.started`};case`session.completed`:case`session.waiting`:return{idempotencyKey:sessionIdempotencyKey(t.sessionId),sessionId:t.sessionId,turnId:n,type:e.type};case`session.failed`:return{error:Error(e.data.message),idempotencyKey:sessionIdempotencyKey(t.sessionId),sessionId:t.sessionId,turnId:n,type:`session.failed`};case`turn.started`:return{idempotencyKey:turnIdempotencyKey(t.sessionId,e.data.turnId),parentLineage:t.parentLineage,parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId??t.sessionId,sequence:e.data.sequence,sessionId:t.sessionId,turnId:e.data.turnId,type:`turn.started`};case`turn.completed`:case`turn.cancelled`:return{idempotencyKey:turnIdempotencyKey(t.sessionId,e.data.turnId),sessionId:t.sessionId,turnId:e.data.turnId,type:e.type};case`turn.failed`:return{error:Error(e.data.message),idempotencyKey:turnIdempotencyKey(t.sessionId,e.data.turnId),sessionId:t.sessionId,turnId:e.data.turnId,type:`turn.failed`};default:return}}export{createInstrumentationHandleEvent,publishInputResolutions};

package/dist/src/harness/instrumentation/providers.d.ts

@@ -0,0 +1,50 @@
+import { type InstrumentationRuntime } from "#harness/instrumentation/runtime.js";
+import { type InstrumentationProvider } from "#public/instrumentation/provider.js";
+/** One provider and the `instrumentation/<slot>.ts` file it came from. */
+export interface RegisteredInstrumentationProvider {
+    readonly provider: InstrumentationProvider;
+    readonly slot: string;
+}
+/** Fills reserved slots before authored files may reconfigure or disable them. */
+export declare function seedInstrumentationProviders(): void;
+/**
+ * Registers one authored provider and awaits its `setup`.
+ *
+ * Called once per `instrumentation/<slot>.ts` by the generated Nitro plugin at
+ * server startup, before any event is published. A default export that is not
+ * a `defineInstrumentation` result throws rather than being skipped: a slot
+ * that registers nothing is telemetry that silently does nothing, which is the
+ * failure this surface exists to prevent.
+ *
+ * @internal — not part of the public API.
+ */
+export declare function registerInstrumentationProvider(input: {
+    readonly agentName: string;
+    readonly slot: string;
+    readonly value: unknown;
+}): Promise<void>;
+/** Registered providers in slot order. @internal */
+export declare function getInstrumentationProviders(): readonly RegisteredInstrumentationProvider[];
+/**
+ * Installs the process instrumentation runtime from the registered providers.
+ *
+ * Called once by the generated Nitro plugin after every slot has registered,
+ * which is also why it cannot happen inside `setup`: the OpenTelemetry pipeline
+ * is the union of every destination declared in the directory, so no single
+ * file knows enough to build it. A `setup` that reaches for a tracer therefore
+ * gets the no-op one; declare destinations as values and let this assemble
+ * them.
+ *
+ * A directory that declared no OpenTelemetry at all still gets a bus. Its
+ * providers see every event; they just have no spans to hang them on.
+ *
+ * @internal — not part of the public API.
+ */
+export declare function finalizeInstrumentationProviders(input: {
+    readonly serviceName: string;
+}): InstrumentationRuntime;
+/**
+ * Releases every registered provider and OTel processor from Nitro's close
+ * hook, the last point a buffered exporter can still reach the network.
+ */
+export declare function shutdownInstrumentationProviders(): Promise<void>;

package/dist/src/harness/instrumentation/providers.js

@@ -0,0 +1 @@
+import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{getInstrumentationRuntime}from"#harness/instrumentation/runtime.js";import{createInstrumentationSetupContext}from"#harness/instrumentation/setup-context.js";import{DEVELOPMENT_WORKER_APP_ROOT_ENV}from"#internal/workflow/development-world-protocol.js";import{agentRuns,localTraces}from"#public/instrumentation/otel.js";import{installInstrumentationRuntime}from"#tracing/install-instrumentation-runtime.js";import{collectOtelPipeline}from"#tracing/otel-declaration.js";import{isInstrumentationDisabled,isInstrumentationProvider}from"#public/instrumentation/provider.js";const INSTRUMENTATION_PROVIDERS_GLOBAL_KEY=Symbol.for(`eve.harness-instrumentation-providers`),globalContainer=globalThis;function providerRegistry(){let e=globalContainer[INSTRUMENTATION_PROVIDERS_GLOBAL_KEY];if(e!==void 0)return e;let t=new Map;return globalContainer[INSTRUMENTATION_PROVIDERS_GLOBAL_KEY]=t,t}function seedInstrumentationProviders(){let e=providerRegistry();process.env.VERCEL_ENV===`production`&&e.set(`agent-runs`,agentRuns()),process.env[DEVELOPMENT_WORKER_APP_ROOT_ENV]!==void 0&&e.set(`local`,localTraces())}async function registerInstrumentationProvider(e){if(isInstrumentationDisabled(e.value)){providerRegistry().delete(e.slot);return}if(!isInstrumentationProvider(e.value))throw Error(`The default export of "instrumentation/${e.slot}" is not an instrumentation provider. Return the result of \`defineInstrumentation\` or \`disableInstrumentation\` from it.`);providerRegistry().set(e.slot,e.value),await e.value.setup?.(createInstrumentationSetupContext(e.agentName))}function getInstrumentationProviders(){return[...providerRegistry()].sort(([e],[t])=>e.localeCompare(t)).map(([e,t])=>({provider:t,slot:e}))}function finalizeInstrumentationProviders(t){let n=getInstrumentationProviders();return installInstrumentationRuntime({collected:collectOtelPipeline(n.map(e=>e.provider)),frameworkVersion:resolveInstalledPackageInfo().version,providers:n.map(toProviderDefinition),serviceName:t.serviceName})}async function shutdownInstrumentationProviders(){await getInstrumentationRuntime()?.shutdown()}function toProviderDefinition(e){return{capture:e.provider.capture,events:e.provider.events,flush:e.provider.flush,name:e.slot,shutdown:e.provider.shutdown,stateNamespace:`authored:${e.slot}`}}export{finalizeInstrumentationProviders,getInstrumentationProviders,registerInstrumentationProvider,seedInstrumentationProviders,shutdownInstrumentationProviders};

package/dist/src/harness/{instrumentation-runtime.d.ts → instrumentation/runtime.d.ts}

@@ -1,12 +1,17 @@
-import type { InstrumentationContextRunner, InstrumentationHooks } from "#harness/instrumentation-lifecycle.js";
+import type { InstrumentationContextRunner, InstrumentationHooks, InstrumentationSessionStartedEvent, InstrumentationTraceContext, InstrumentationTurnStartedEvent } from "#harness/instrumentation/lifecycle.js";
+import type { OtelHarnessSettings } from "#tracing/otel-declaration.js";
 /** Process-wide runtime consumed by every harness execution surface. */
 export interface InstrumentationRuntime {
     readonly forceFlush: () => Promise<void>;
     readonly hooks: InstrumentationHooks;
+    readonly prepareSessionTrace?: (event: InstrumentationSessionStartedEvent) => Promise<InstrumentationTraceContext>;
+    readonly prepareTurnTrace?: (event: InstrumentationTurnStartedEvent) => Promise<InstrumentationTraceContext>;
+    otelSettings: OtelHarnessSettings | undefined;
     readonly runInContext: InstrumentationContextRunner;
+    readonly shutdown: () => Promise<void>;
 }
 /** Instrumentation capabilities consumed inside one harness execution. */
-export type HarnessInstrumentation = Pick<InstrumentationRuntime, "hooks" | "runInContext">;
+export type HarnessInstrumentation = Pick<InstrumentationRuntime, "hooks" | "prepareSessionTrace" | "prepareTurnTrace" | "runInContext">;
 /** Registers the process instrumentation runtime before agent execution begins. */
 export declare function registerInstrumentationRuntime(runtime: InstrumentationRuntime): InstrumentationRuntime;
 /** Returns the process instrumentation runtime, when one was installed. */

package/dist/src/harness/{instrumentation-runtime.js → instrumentation/runtime.js}

@@ -1 +1 @@
-const INSTRUMENTATION_RUNTIME_KEY=Symbol.for(`eve.instrumentation-runtime`),globalRuntime=globalThis;function registerInstrumentationRuntime(e){let t=globalRuntime[INSTRUMENTATION_RUNTIME_KEY];return t===void 0?(globalRuntime[INSTRUMENTATION_RUNTIME_KEY]=e,e):t}function getInstrumentationRuntime(){return globalRuntime[INSTRUMENTATION_RUNTIME_KEY]}export{getInstrumentationRuntime,registerInstrumentationRuntime};
+const INSTRUMENTATION_RUNTIME_KEY=Symbol.for(`eve.instrumentation-runtime`),globalRuntime=globalThis;function registerInstrumentationRuntime(e){let t=globalRuntime[INSTRUMENTATION_RUNTIME_KEY];return t===void 0?(globalRuntime[INSTRUMENTATION_RUNTIME_KEY]=e,e):(t.otelSettings=e.otelSettings,t)}function getInstrumentationRuntime(){return globalRuntime[INSTRUMENTATION_RUNTIME_KEY]}export{getInstrumentationRuntime,registerInstrumentationRuntime};

package/dist/src/harness/instrumentation/setup-context.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderSetupContext } from "#public/instrumentation/provider.js";
+/**
+ * Builds the context handed to an authored `setup` at server startup.
+ *
+ * Shared by both layouts so the two cannot drift: a divergent context type
+ * would leave `defineInstrumentation`'s union without a contextual signature
+ * for `setup`, silently making every authored `setup(context)` parameter an
+ * implicit `any`.
+ *
+ * @internal — not part of the public API.
+ */
+export declare function createInstrumentationSetupContext(agentName: string): ProviderSetupContext;

package/dist/src/harness/instrumentation/setup-context.js

@@ -0,0 +1 @@
+import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{isEveDevEnvironment,resolveEveEvaluationRunId}from"#internal/application/dev-environment.js";function createInstrumentationSetupContext(e){let t=resolveEveEvaluationRunId();return{agentName:e,environment:resolveInstrumentationEnvironment(),evaluation:t===void 0?void 0:{runId:t},frameworkVersion:resolveInstalledPackageInfo().version}}function resolveInstrumentationEnvironment(){return isEveDevEnvironment()||process.env.VERCEL_ENV===`development`?`development`:process.env.VERCEL_ENV===`preview`?`preview`:`production`}export{createInstrumentationSetupContext};