eve 0.33.3 → 0.34.0

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

@@ -1,6 +1,13 @@
-import type { Telemetry } from "ai";
-type TelemetryEvent<TKey extends keyof Telemetry> = Parameters<NonNullable<Telemetry[TKey]>>[0];
-/** Stable eve identity for one actual model attempt. */
+import type { InstrumentationStateSlot } from "#harness/instrumentation-state.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;
@@ -10,16 +17,204 @@ export interface InstrumentationAttemptScope {
     readonly stepIndex: number;
     readonly turnId: string;
 }
-export interface InstrumentationAttemptStartedEvent {
-    readonly type: "attempt.started";
+/** 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;
-    readonly operation: TelemetryEvent<"onStart">;
-    readonly step: TelemetryEvent<"onStepStart">;
 }
 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;
@@ -39,14 +234,31 @@ export interface InstrumentationParentLineage {
     readonly subagentName?: string;
     readonly turnId: string;
 }
-export interface InstrumentationSessionTransitionEvent {
-    readonly type: "session.completed" | "session.failed" | "session.waiting";
+/**
+ * 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;
@@ -54,118 +266,229 @@ export interface InstrumentationTurnStartedEvent {
     readonly sessionId: string;
     readonly turnId: string;
 }
-export interface InstrumentationTurnTerminalEvent {
-    readonly type: "turn.cancelled" | "turn.completed" | "turn.failed";
+/**
+ * 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 interface InstrumentationAttemptTerminalEvent {
-    readonly type: "attempt.completed" | "attempt.failed";
+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 step, as reported by the AI SDK
+ * 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 InstrumentationAttemptMetadataEvent {
-    readonly type: "attempt.metadata";
+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 id: string;
+    readonly idempotencyKey: string;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly input?: InstrumentationModelInput;
+    readonly model: InstrumentationModelRef;
     readonly scope: InstrumentationAttemptScope;
-    readonly source: TelemetryEvent<"onLanguageModelCallStart">;
 }
 export interface InstrumentationModelCallCompletedEvent {
     readonly type: "model.call.completed";
-    readonly id: string;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly content?: readonly InstrumentationContentPart[];
+    readonly finishReason: string;
+    readonly idempotencyKey: string;
     readonly scope: InstrumentationAttemptScope;
-    readonly source: TelemetryEvent<"onLanguageModelCallEnd">;
+    readonly usage: InstrumentationUsage;
 }
 export interface InstrumentationModelCallFailedEvent {
     readonly type: "model.call.failed";
-    readonly error: unknown;
-    readonly id: string;
+    /** 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 id: string;
+    readonly callId: string;
+    readonly idempotencyKey: string;
+    readonly input: unknown;
     readonly scope: InstrumentationAttemptScope;
-    readonly source: TelemetryEvent<"onToolExecutionStart">;
+    readonly toolName: string;
 }
 export interface InstrumentationToolCallCompletedEvent {
     readonly type: "tool.call.completed";
-    readonly id: string;
+    readonly idempotencyKey: string;
+    readonly output: InstrumentationToolOutput;
     readonly scope: InstrumentationAttemptScope;
-    readonly source: TelemetryEvent<"onToolExecutionEnd">;
 }
 export interface InstrumentationToolCallFailedEvent {
     readonly type: "tool.call.failed";
-    readonly error: unknown;
-    readonly id: string;
+    /** Content. Absent unless this provider declared `capture: "content"`. */
+    readonly error?: unknown;
+    readonly idempotencyKey: string;
     readonly scope: InstrumentationAttemptScope;
 }
 export type InstrumentationToolCallTerminalEvent = InstrumentationToolCallCompletedEvent | InstrumentationToolCallFailedEvent;
-export interface RelatedLifecycleHook<TStart, TTerminal> {
-    readonly before?: (event: TStart) => unknown | PromiseLike<unknown>;
-    readonly after?: (event: TTerminal, state: unknown) => void | PromiseLike<void>;
+/**
+ * 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 "model.call"?: RelatedLifecycleHook<InstrumentationModelCallStartedEvent, InstrumentationModelCallTerminalEvent>;
-        readonly "attempt.started"?: (event: InstrumentationAttemptStartedEvent) => void | PromiseLike<void>;
-        readonly "attempt.completed"?: (event: InstrumentationAttemptTerminalEvent) => void | PromiseLike<void>;
-        readonly "attempt.failed"?: (event: InstrumentationAttemptTerminalEvent) => void | PromiseLike<void>;
-        readonly "attempt.metadata"?: (event: InstrumentationAttemptMetadataEvent) => void | PromiseLike<void>;
-        readonly "session.completed"?: (event: InstrumentationSessionTransitionEvent) => void | PromiseLike<void>;
-        readonly "session.failed"?: (event: InstrumentationSessionTransitionEvent) => void | PromiseLike<void>;
-        readonly "session.started"?: (event: InstrumentationSessionStartedEvent) => void | PromiseLike<void>;
-        readonly "session.waiting"?: (event: InstrumentationSessionTransitionEvent) => void | PromiseLike<void>;
-        readonly "tool.call"?: RelatedLifecycleHook<InstrumentationToolCallStartedEvent, InstrumentationToolCallTerminalEvent>;
-        readonly "turn.cancelled"?: (event: InstrumentationTurnTerminalEvent) => void | PromiseLike<void>;
-        readonly "turn.completed"?: (event: InstrumentationTurnTerminalEvent) => void | PromiseLike<void>;
-        readonly "turn.failed"?: (event: InstrumentationTurnTerminalEvent) => void | PromiseLike<void>;
-        readonly "turn.started"?: (event: InstrumentationTurnStartedEvent) => void | PromiseLike<void>;
+        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>;
 }
-export interface InstrumentationRelatedEventMap {
-    readonly "model.call": {
-        readonly start: InstrumentationModelCallStartedEvent;
-        readonly terminal: InstrumentationModelCallTerminalEvent;
-    };
-    readonly "tool.call": {
-        readonly start: InstrumentationToolCallStartedEvent;
-        readonly terminal: InstrumentationToolCallTerminalEvent;
-    };
+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 InstrumentationRelatedEventName = keyof InstrumentationRelatedEventMap;
-export type InstrumentationPointEvent = InstrumentationAttemptStartedEvent | InstrumentationAttemptMetadataEvent | InstrumentationAttemptTerminalEvent | InstrumentationSessionStartedEvent | InstrumentationSessionTransitionEvent | InstrumentationTurnStartedEvent | InstrumentationTurnTerminalEvent;
+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 id: string;
+    readonly idempotencyKey: string;
     readonly scope: InstrumentationAttemptScope;
-    readonly type: "model.call";
+    readonly type: "tool.call";
 } | {
-    readonly id: string;
+    readonly idempotencyKey: string;
     readonly scope: InstrumentationAttemptScope;
-    readonly type: "tool.call";
+    readonly type: "model.call";
 };
 /** Provider-neutral hook operations consumed by the AI SDK bridge. */
 export interface InstrumentationHooks {
-    after<TKey extends InstrumentationRelatedEventName>(name: TKey, event: InstrumentationRelatedEventMap[TKey]["terminal"]): Promise<void>;
-    before<TKey extends InstrumentationRelatedEventName>(name: TKey, event: InstrumentationRelatedEventMap[TKey]["start"]): Promise<void>;
-    publish(event: InstrumentationPointEvent): Promise<void>;
+    /**
+     * 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 an ordered provider list. */
-export declare function createInstrumentationHooks(providers: readonly InstrumentationProviderDefinition[]): InstrumentationHooks;
+/** 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

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";const log=createLogger(`harness.instrumentation-lifecycle`);function createInstrumentationHooks(e){let r=new WeakMap,publish=async t=>{for(let n of e){let e=n.events?.[t.type];if(e!==void 0)try{await e(t)}catch(e){warn(t.type,e)}}},before=async(t,n)=>{let i=r.get(n.scope)??new Map;r.set(n.scope,i);for(let[r,a]of e.entries()){let e=a.events?.[t]?.before;if(e!==void 0)try{let t=await e(n);i.set(relatedStateKey(r,n.id),t)}catch(e){warn(`${t}.before`,e)}}},after=async(t,n)=>{let i=r.get(n.scope);for(let[r,a]of e.entries()){let e=a.events?.[t]?.after,o=relatedStateKey(r,n.id);if(e===void 0||!i?.has(o))continue;let s=i.get(o);i.delete(o);try{await e(n,s)}catch(e){warn(`${t}.after`,e)}}},warn=(e,r)=>{log.warn(`instrumentation provider failed`,{boundary:e,error:formatError(r)})};return{after,before,publish}}function relatedStateKey(e,t){return`${e}:${t}`}export{createInstrumentationHooks};
+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

@@ -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

@@ -1 +1 @@
-function createInstrumentationHandleEvent(e){if(e.hooks===void 0)return e.handleEvent;if(e.handleEvent===void 0)return;let t=e.handleEvent,n=e.hooks,r=e.turnId;return async(i,a)=>{await t(i,a);let o=toLifecycleEvent(i,e,r);i.type===`turn.started`&&(r=i.data.turnId),o!==void 0&&await n.publish(o)}}function toLifecycleEvent(e,t,n){switch(e.type){case`session.started`:return{agentName:t.agentName,parentTraceContext:t.parentTraceContext,rootSessionId:t.rootSessionId??t.sessionId,sessionId:t.sessionId,type:`session.started`};case`session.completed`:case`session.waiting`:return{sessionId:t.sessionId,turnId:n,type:e.type};case`session.failed`:return{error:Error(e.data.message),sessionId:t.sessionId,turnId:n,type:`session.failed`};case`turn.started`:return{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{sessionId:t.sessionId,turnId:e.data.turnId,type:e.type};case`turn.failed`:return{error:Error(e.data.message),sessionId:t.sessionId,turnId:e.data.turnId,type:`turn.failed`};default:return}}export{createInstrumentationHandleEvent};
+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>;