Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

refactor(eve): bind session instrumentation through execution (#2681)

Chad Hietalacfc82cc31c5a
diff --git a/.changeset/refactor-instrumentation-runtime.md b/.changeset/refactor-instrumentation-runtime.md
new file mode 100644
index 000000000..233831d90
--- /dev/null
+++ b/.changeset/refactor-instrumentation-runtime.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Refactor internal instrumentation ownership and execution wiring without changing session tracing behavior.
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index 0483587bb..cab175c69 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -21,7 +21,7 @@ import type {
} from "#channel/types.js";
import { ContextKey } from "#context/key.js";
import { SESSION_CALLBACK_CONTEXT_KEY_NAME } from "#context/key-names.js";
-import type { InstrumentationChannelDeliveryRef } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationChannelDeliveryRef } from "#instrumentation/lifecycle.js";
import type { HandleEventFn } from "#harness/types.js";
import type { DurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.ts
index c8d6d542b..6be72cec2 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.ts
@@ -38,13 +38,14 @@ import {
ChannelRequestIdKey,
OtelTraceEnabledKey,
ScheduleIdKey,
+ SessionTraceSeedKey,
type SessionTraceSeed,
} from "#context/keys.js";
-import { shouldCaptureInstrumentationContent } from "#shared/instrumentation-content.js";
-import { isSampledTrace } from "#tracing/sampled-trace.js";
import type { EveAttributeValue } from "#runtime/attributes/normalize.js";
-import { normalizeChannelAudience } from "#shared/channel-audience.js";
import { isNonEmptyString } from "#shared/guards.js";
+import { shouldCaptureInstrumentationContent } from "#shared/instrumentation-content.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import { isSampledTrace } from "#tracing/sampled-trace.js";
/**
* Active compiled graph node id for the session's agent. Returned by
@@ -109,7 +110,7 @@ export function isWorkflowOtelTraceEnabled(serializedContext: Record<string, unk
}
export function readSessionTraceId(serializedContext: Record<string, unknown>): string | undefined {
- const seed = serializedContext["eve.sessionTraceSeed"] as SessionTraceSeed | undefined;
+ const seed = serializedContext[SessionTraceSeedKey.name] as SessionTraceSeed | undefined;
if (seed === undefined || !isSampledTrace(seed)) return undefined;
return isNonEmptyString(seed.traceId) ? seed.traceId : undefined;
}
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index ea9976154..7c8e7d73c 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -5,6 +5,11 @@ import { ContextContainer, contextStorage } from "#context/container.js";
import { AuthKey, InitiatorAuthKey, SessionIdKey, SessionKey } from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
+import { createInstrumentationHooks } from "#instrumentation/lifecycle.js";
+import {
+ bindInstrumentationRuntime,
+ type InstrumentationRuntime,
+} from "#instrumentation/runtime.js";
import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";
import { resolveRuntimeModelReference } from "#runtime/agent/resolve-model.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
@@ -387,6 +392,18 @@ describe("createNodeHarnessTools", () => {
describe("createExecutionNodeStep", () => {
it("builds a usable harness step for the root node", async () => {
setupMockAgentForToolExecution("regular-tool", { question: "Run the tool." });
+ const forceFlush = vi.fn(async () => undefined);
+ const runtime: InstrumentationRuntime = {
+ forceFlush,
+ hooks: createInstrumentationHooks([]),
+ otelSettings: undefined,
+ runInContext: (_operation, execute) => execute(),
+ shutdown: async () => undefined,
+ };
+ const instrumentation = bindInstrumentationRuntime(runtime, new ContextContainer(), {
+ rootSessionId: "sess-root",
+ sessionId: "sess-root",
+ });
const toolRegistry = await createRuntimeToolRegistry({
tools: [
@@ -416,6 +433,7 @@ describe("createExecutionNodeStep", () => {
};
const step = createExecutionNodeStep({
createRuntime: () => createNoopRuntime(),
+ instrumentation,
mode: "task",
modelResolutionScope,
node: rootNode,
@@ -453,6 +471,7 @@ describe("createExecutionNodeStep", () => {
rootNode.turnAgent.model,
modelResolutionScope,
);
+ expect(forceFlush).toHaveBeenCalledOnce();
});
it("records visible subagent tools as pending runtime actions", async () => {
@@ -478,6 +497,7 @@ describe("createExecutionNodeStep", () => {
);
const step = createExecutionNodeStep({
createRuntime,
+ instrumentation: undefined,
mode: "task",
modelResolutionScope: {
moduleMap: { nodes: {} },
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index f1b708cb3..dfe07a255 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -7,11 +7,11 @@ import {
createHarnessDelegationToolDefinition,
} from "#execution/delegation-tool.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import type { ExecutionInstrumentation } from "#instrumentation/runtime.js";
import { LOAD_SKILL_TOOL_NAME } from "#runtime/skills/fragment-context.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import type { HandleEventFn, HarnessToolMap, StepFn } from "#harness/types.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
import { createLogger } from "#internal/logging.js";
import type { RuntimeIdentity } from "#protocol/message.js";
import { UNSPECIFIED_INPUT_SCHEMA } from "#tools/schema.js";
@@ -74,6 +74,7 @@ export interface CreateExecutionNodeStepInput {
readonly handleEvent?: HandleEventFn;
readonly historyProjector?: HistoryViewProjector;
readonly historyView?: PreparedHistoryView;
+ readonly instrumentation: ExecutionInstrumentation | undefined;
readonly mode: RunMode;
readonly modelResolutionScope: RuntimeModelResolutionScope;
readonly node: ResolvedRuntimeAgentNode;
@@ -98,7 +99,8 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
input.node.turnAgent.dynamicModel,
);
const tools = createNodeHarnessTools({ node: input.node });
- const instrumentation = getInstrumentationRuntime();
+ const instrumentation = input.instrumentation;
+ const sessionInstrumentation = instrumentation?.prepareExecution();
const step = createToolLoopHarness({
abortSignal: input.abortSignal,
capabilities: input.capabilities,
@@ -110,7 +112,7 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
handleEvent: input.handleEvent,
historyProjector: input.historyProjector,
historyView: input.historyView,
- instrumentation,
+ instrumentation: sessionInstrumentation,
mode: input.mode,
onCompaction: preserveFrameworkStateOnCompaction,
dispatchDynamicModelEvent: dispatchModelEvent,
@@ -123,7 +125,7 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
try {
return await step(session, stepInput);
} finally {
- await instrumentation.forceFlush();
+ await instrumentation.flush();
}
};
}
diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.ts b/packages/eve/src/execution/settle-cancelled-turn-step.ts
index ef50c137a..54b9079ab 100644
--- a/packages/eve/src/execution/settle-cancelled-turn-step.ts
+++ b/packages/eve/src/execution/settle-cancelled-turn-step.ts
@@ -3,7 +3,6 @@ import { callAdapterEventHandler } from "#channel/adapter.js";
import { dispatchStreamEventHooks } from "#context/hook-lifecycle.js";
import { withContextScope } from "#context/run-step.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
-import { ChannelInstrumentationKey } from "#context/keys.js";
import { setChannelContext } from "#execution/channel-context.js";
import { observeSessionActivity } from "#execution/session-activity-projection.js";
import {
@@ -28,8 +27,7 @@ import {
} from "#harness/proxy-input-requests.js";
import { abandonRunningAgentTurns } from "#harness/handles/transitions.js";
import { clearPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
-import { createInstrumentationHandleEvent } from "#harness/instrumentation/native-events.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
+import { bindSessionInstrumentation } from "#instrumentation/runtime.js";
import { getTurnUsageState, toUsage } from "#harness/turn-tag-state.js";
import { clearPendingWorkflowInterrupt } from "#harness/workflow-interrupt-state.js";
import {
@@ -66,7 +64,6 @@ export async function settleCancelledTurnStep(input: {
const adapterCtx = buildAdapterContext(adapter, ctx);
const bundle = ctx.require(BundleKey);
const effectiveAgent = resolveEffectiveAgentRuntime(bundle, ctx);
- const instrumentation = getInstrumentationRuntime();
let session = hydrateDurableSession({
compactionOverrides: {
@@ -75,6 +72,12 @@ export async function settleCancelledTurnStep(input: {
durable: durableSession,
turnAgent: effectiveAgent.turnAgent,
});
+ const instrumentation = bindSessionInstrumentation({
+ agentName: effectiveAgent.turnAgent.id,
+ ctx,
+ rootSessionId: session.rootSessionId ?? session.sessionId,
+ sessionId: session.sessionId,
+ });
let emissionState = getHarnessEmissionState(durableSession.state);
// A descendant HITL wait already streamed this turn's waiting boundary
@@ -107,12 +110,8 @@ export async function settleCancelledTurnStep(input: {
});
};
const emit =
- createInstrumentationHandleEvent({
- agentName: bundle.turnAgent.id,
- channelKind: ctx.get(ChannelInstrumentationKey)?.kind,
+ instrumentation?.createCancellationHandleEvent({
handleEvent: baseEmit,
- hooks: instrumentation?.hooks,
- sessionId: session.sessionId,
turnId: activeTurnId(emissionState),
}) ?? baseEmit;
return {
@@ -123,7 +122,7 @@ export async function settleCancelledTurnStep(input: {
emissionState = scoped.result;
session = scoped.session;
} finally {
- await instrumentation?.forceFlush();
+ await instrumentation?.flush();
writer.releaseLock();
}
}
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index cfe912c1f..484a455b2 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -14,7 +14,7 @@ import {
} from "#execution/workflow-runtime.js";
import { RuntimeSessionOwnershipConflictError } from "#execution/runtime-errors.js";
import { sessionCommandHookToken } from "#execution/session-command-token.js";
-import { registerInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
+import { registerInstrumentationRuntime } from "#instrumentation/runtime.js";
import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
@@ -839,7 +839,8 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
it("allocates a sampled trace seed when the policy is sampled", async () => {
const idGenerator = new AgentSpanIdGenerator();
- installAgentOtelRuntime(idGenerator, () => true);
+ const tracePolicy = vi.fn(() => true);
+ installAgentOtelRuntime(idGenerator, tracePolicy);
mockBundleAndRun();
startMock.mockResolvedValue({ runId: "driver-run" });
@@ -866,6 +867,7 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
expect(seed!.traceId).toMatch(/^[0-9a-f]{32}$/u);
expect(serialized["eve.otelTraceEnabled"]).toBe(true);
expect(startMock.mock.calls[0]?.[2].attributes["$eve.is_otel_trace_enabled"]).toBe("true");
+ expect(tracePolicy).toHaveBeenCalledOnce();
});
it("passes the channel adapter kind as channelType to the policy", async () => {
@@ -926,7 +928,8 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
});
it("inherits the parent trace context for delegated subagents", async () => {
- installAgentOtelRuntime(new AgentSpanIdGenerator(), () => false);
+ const tracePolicy = vi.fn(() => false);
+ installAgentOtelRuntime(new AgentSpanIdGenerator(), tracePolicy);
mockBundleAndRun();
const parentTrace = {
@@ -959,6 +962,7 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
expect(seed).toEqual(parentTrace);
expect(serialized["eve.otelTraceEnabled"]).toBe(true);
expect(startMock.mock.calls[0]?.[2].attributes["$eve.is_otel_trace_enabled"]).toBe("true");
+ expect(tracePolicy).not.toHaveBeenCalled();
});
it("does not allocate a seed when no instrumentation runtime is installed", async () => {
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 7e489df49..764e2f3d9 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -19,16 +19,9 @@ import type {
Runtime,
SessionCommand,
SessionCommandResult,
- SessionTraceContext,
} from "#channel/types.js";
import { ActivityObserverKey } from "#context/keys.js";
import { serializeContext } from "#context/serialize.js";
-import {
- ChannelInstrumentationKey,
- OtelTraceEnabledKey,
- SessionTraceSeedKey,
- type SessionTraceSeed,
-} from "#context/keys.js";
import {
buildSessionAttributes,
buildSubagentRootAttributes,
@@ -69,13 +62,7 @@ import { buildInvocationAttributes } from "#internal/invocation/metadata.js";
import { sessionCommandHookToken } from "#execution/session-command-token.js";
import { resumeSessionInbox } from "#execution/wire/session-inbox-resume.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
-import {
- isSampledTrace,
- resolveTracePolicy,
- resolveTracePolicyDecision,
-} from "#tracing/sampled-trace.js";
-import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import { initializeSessionInstrumentation } from "#instrumentation/runtime.js";
const WORKFLOW_ENTRY_NAME = "workflowEntry";
const TURN_WORKFLOW_NAME = "turnWorkflow";
@@ -172,17 +159,11 @@ export function createWorkflowRuntime(config: {
run: input,
});
const effectiveAgent = resolveEffectiveAgentRuntime(bundle, ctx);
- const channelInstrumentation = ctx.get(ChannelInstrumentationKey);
- const traceSeed = allocateSessionTraceSeed({
+ initializeSessionInstrumentation({
agentName: effectiveAgent.turnAgent.id,
- audience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),
- channelType: channelInstrumentation?.channelType,
+ ctx,
parentTraceContext: input.parentTraceContext,
});
- if (traceSeed !== undefined) {
- ctx.set(SessionTraceSeedKey, traceSeed);
- }
- ctx.set(OtelTraceEnabledKey, getInstrumentationRuntime()?.prepareSessionTrace !== undefined);
const sessionTimeoutMs = effectiveAgent.limits?.sessionTimeoutMs;
let collectorRunId: string | undefined;
let activityObserver = input.activityObserver;
@@ -536,36 +517,3 @@ function normalizeWorkflowHook(value: unknown): WorkflowHookRecord {
runId,
};
}
-
-function allocateSessionTraceSeed(input: {
- readonly agentName?: string;
- readonly audience: ReturnType<typeof normalizeChannelAudience>;
- readonly channelType?: string;
- readonly parentTraceContext?: SessionTraceContext;
-}): SessionTraceSeed | undefined {
- if (input.parentTraceContext !== undefined) {
- const decision =
- input.parentTraceContext.decision ??
- resolveTracePolicyDecision(isSampledTrace(input.parentTraceContext), input.audience);
- return {
- decision,
- spanId: input.parentTraceContext.spanId,
- traceFlags: input.parentTraceContext.traceFlags,
- traceId: input.parentTraceContext.traceId,
- };
- }
- const instrumentation = getInstrumentationRuntime();
- if (instrumentation?.prepareSessionTrace === undefined) return undefined;
- if (instrumentation.idGenerator === undefined) return undefined;
- const decision = resolveTracePolicy(instrumentation.otelSettings?.tracePolicy, {
- agentName: input.agentName,
- audience: input.audience,
- channelType: input.channelType,
- });
- return {
- decision,
- spanId: instrumentation.idGenerator.allocateSpanId(),
- traceFlags: decision.action === "record" ? 1 : 0,
- traceId: instrumentation.idGenerator.generateTraceId(),
- };
-}
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index 4d85831ea..78d7c987b 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -40,12 +40,8 @@ import {
isHarnessBetweenTurns,
setHarnessEmissionState,
} from "#harness/emission.js";
-import {
- channelDeliveryErrorCode,
- instrumentChannelDelivery,
-} from "#harness/channel-delivery-instrumentation.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
-import { preserveSerializedInstrumentationState } from "#harness/instrumentation/state.js";
+import { bindSessionInstrumentation } from "#instrumentation/runtime.js";
+import { preserveSerializedInstrumentationState } from "#instrumentation/state.js";
import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";
import { preserveSerializedAgentTraceState } from "#tracing/agent-trace-context-store.js";
import { matchAuthorizationCallbacks } from "#execution/authorization-callback-match.js";
@@ -113,6 +109,14 @@ import { stageAttachmentsToSandbox } from "#harness/attachment-staging.js";
const TASK_DONE_WITH_PENDING_INPUT_ERROR_MESSAGE =
"Task mode cannot complete while input requests remain pending.";
+function channelDeliveryErrorCode(error: unknown): string {
+ if (typeof error === "object" && error !== null && "code" in error) {
+ const code = (error as { readonly code?: unknown }).code;
+ if (typeof code === "string" && code.length > 0) return code;
+ }
+ return "CHANNEL_DELIVERY_FAILED";
+}
+
export type { TurnStepInput };
/** Runs one atomic harness step inside a durable `"use step"` boundary. */
@@ -194,16 +198,20 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
turnAgent: effectiveAgent.turnAgent,
});
const history = createExecutionHistoryView(initialSession);
- const instrumentation = getInstrumentationRuntime();
+ const instrumentation = bindSessionInstrumentation({
+ agentName: bundle.graph.root.agent?.config?.name,
+ ctx,
+ rootSessionId: initialSession.rootSessionId ?? initialSession.sessionId,
+ sessionId: initialSession.sessionId,
+ });
const initialEmissionState = getHarnessEmissionState(initialSession.state);
if (rawInput.input?.kind === "deliver") {
await contextStorage.run(ctx, () =>
- instrumentChannelDelivery({
+ instrumentation?.instrumentChannelDelivery({
agentName: bundle.turnAgent.id,
ctx,
delivery: rawInput.input as DeliverHookPayload,
- hooks: instrumentation?.hooks,
rootSessionId: initialSession.rootSessionId ?? initialSession.sessionId,
sequence: initialEmissionState.sequence,
sessionId: initialSession.sessionId,
@@ -214,16 +222,15 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
const failChannelDeliveries = async (error: unknown): Promise<void> => {
await contextStorage.run(ctx, () =>
- instrumentChannelDelivery({
+ instrumentation?.instrumentChannelDelivery({
ctx,
error,
errorCode: channelDeliveryErrorCode(error),
- hooks: instrumentation?.hooks,
includeTurn: false,
outcome: "failed",
}),
);
- await instrumentation?.forceFlush();
+ await instrumentation?.flush();
};
const adapterCtx = buildAdapterContext(adapter, ctx);
@@ -293,14 +300,13 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
// Adapter handled the delivery inline; re-park and skip unchanged snapshot writes.
if (input.input?.kind === "deliver" && resolved === undefined) {
await contextStorage.run(ctx, () =>
- instrumentChannelDelivery({
+ instrumentation?.instrumentChannelDelivery({
ctx,
- hooks: instrumentation?.hooks,
includeTurn: false,
outcome: "completed",
}),
);
- await instrumentation?.forceFlush();
+ await instrumentation?.flush();
const rekeyed = reconcileSessionContinuationToken(ctx, initialSession);
const nextSerializedContext = serializeContext(ctx);
const nextState =
@@ -461,10 +467,8 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
prepareDynamicInstructionPreamble(ctx, history.messages(schemaSession));
let instructionMessages: readonly import("ai").ModelMessage[] = [];
const traceContext = await prepareWorkflowPreambleTrace({
- ctx,
emissionState,
- runtimeIdentity,
- session: schemaSession,
+ instrumentation,
});
try {
emissionState = await emitTurnPreamble(
@@ -529,6 +533,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
handleEvent,
historyProjector: history.projector,
historyView: history.prepare(modelSession),
+ instrumentation,
mode,
modelResolutionScope: {
moduleMap: bundle.moduleMap,
diff --git a/packages/eve/src/execution/workflow-trace-context.ts b/packages/eve/src/execution/workflow-trace-context.ts
index 43a7a9dcc..747875b5b 100644
--- a/packages/eve/src/execution/workflow-trace-context.ts
+++ b/packages/eve/src/execution/workflow-trace-context.ts
@@ -1,40 +1,15 @@
-import type { ContextContainer } from "#context/container.js";
-import {
- ChannelInstrumentationKey,
- ParentSessionKey,
- ParentTraceContextKey,
- SessionTraceSeedKey,
-} from "#context/keys.js";
import type { HarnessEmissionState } from "#harness/emission.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
-import { resolveParentLineage } from "#harness/parent-lineage.js";
-import { prepareTurnTraceContext } from "#harness/prepare-trace-context.js";
-import type { HarnessSession } from "#harness/types.js";
-import type { RuntimeIdentity, RuntimeTraceContext } from "#protocol/message.js";
-import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
-import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import type { ExecutionInstrumentation } from "#instrumentation/runtime.js";
+import type { RuntimeTraceContext } from "#protocol/message.js";
/** Prepares native tracing for workflow-owned preambles emitted outside the tool loop. */
export async function prepareWorkflowPreambleTrace(input: {
- readonly ctx: ContextContainer;
readonly emissionState: HarnessEmissionState;
- readonly runtimeIdentity: RuntimeIdentity;
- readonly session: HarnessSession;
+ readonly instrumentation: ExecutionInstrumentation | undefined;
}): Promise<RuntimeTraceContext | undefined> {
- const parent = input.ctx.get(ParentSessionKey);
- const channel = input.ctx.get(ChannelInstrumentationKey);
- return await prepareTurnTraceContext({
- agentName: input.runtimeIdentity.agentName,
- channelAudience: normalizeChannelAudience(channel?.metadata.audience),
- channelType: channel?.channelType,
- instrumentation: getInstrumentationRuntime(),
- parentLineage: resolveParentLineage(parent, input.ctx.get(ChannelKey)),
- parentTraceContext: input.ctx.get(ParentTraceContextKey),
- rootSessionId: parent?.rootSessionId ?? input.session.rootSessionId ?? input.session.sessionId,
+ return await input.instrumentation?.preparePreamble({
sequence: input.emissionState.sequence,
- sessionId: input.session.sessionId,
sessionStarted: input.emissionState.sessionStarted,
- traceSeed: input.ctx.get(SessionTraceSeedKey),
turnId: `turn_${input.emissionState.sequence}`,
});
}
diff --git a/packages/eve/src/harness/instrumentation/config.test.ts b/packages/eve/src/harness/instrumentation/config.test.ts
deleted file mode 100644
index f8afd599e..000000000
--- a/packages/eve/src/harness/instrumentation/config.test.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-import type { InstrumentationSetupContext } from "#public/instrumentation/index.js";
-
-const RUNTIME_GLOBAL_KEY = Symbol.for("eve.instrumentation-runtime");
-
-beforeEach(() => {
- delete (globalThis as Record<symbol, unknown>)[RUNTIME_GLOBAL_KEY];
-});
-
-/**
- * Regression coverage for the instrumentation-config chunk-isolation failure.
- *
- * `eve dev` (Nitro) evaluates `instrumentation-config.ts` twice: once via the
- * generated instrumentation plugin (kept external by `file://` URL) and once
- * via the bundled harness chunk (inlined via the `#harness/*` import alias).
- * Each evaluation gets its own module loader, so any module-scoped state
- * lived in two separate bindings — a config registered by the plugin was
- * invisible to the harness one turn later, and `getInstrumentationConfig()`
- * silently returned `undefined` even when `defineInstrumentation` was set up.
- *
- * The fix mounts the config on `globalThis` under a stable `Symbol.for(...)`
- * so every module copy resolves the same slot, mirroring the established
- * patterns for the context-key registry (`context/key.ts`) and the
- * runtime-session storage (`runtime/sessions/runtime-session.ts`).
- *
- * These tests reproduce the failure by using `vi.resetModules()` to force
- * a fresh evaluation of `instrumentation-config.ts`, simulating two separate
- * module loaders holding their own copies of the file.
- */
-describe("instrumentation-config chunk-isolation regression", () => {
- it("a config registered in one module evaluation is visible from another", async () => {
- vi.resetModules();
- const moduleA = await import("#harness/instrumentation/config.js");
- const config = { functionId: "test.instrumentation.cross-module.alice" };
- await moduleA.registerInstrumentationConfig(config, { agentName: "test-agent" });
-
- vi.resetModules();
- const moduleB = await import("#harness/instrumentation/config.js");
-
- // Pre-fix: moduleB's `registeredConfig` is a fresh `undefined` binding.
- // Post-fix: both evaluations share one globalThis-mounted slot.
- expect(moduleB.getInstrumentationConfig()).toBe(config);
- });
-
- it("the config is mounted on globalThis under the canonical symbol", async () => {
- const globalKey = Symbol.for("eve.harness-instrumentation-config");
- const { registerInstrumentationConfig } = await import("#harness/instrumentation/config.js");
-
- const canary = { functionId: "test.instrumentation.global-mount.canary" };
- await registerInstrumentationConfig(canary, { agentName: "test-agent" });
-
- expect((globalThis as Record<symbol, unknown>)[globalKey]).toBe(canary);
- });
-
- it("re-importing reuses the same globalThis slot", async () => {
- const globalKey = Symbol.for("eve.harness-instrumentation-config");
-
- vi.resetModules();
- const moduleA = await import("#harness/instrumentation/config.js");
- const config = { functionId: "test.instrumentation.reimport.canary" };
- await moduleA.registerInstrumentationConfig(config, { agentName: "test-agent" });
- const firstRef = (globalThis as Record<symbol, unknown>)[globalKey];
-
- vi.resetModules();
- await import("#harness/instrumentation/config.js");
- const secondRef = (globalThis as Record<symbol, unknown>)[globalKey];
-
- expect(secondRef).toBe(firstRef);
- });
-
- it("installs harness telemetry settings on the instrumentation runtime", async () => {
- const { registerInstrumentationConfig } = await import("#harness/instrumentation/config.js");
- const { getInstrumentationRuntime } = await import("#harness/instrumentation/runtime.js");
-
- await registerInstrumentationConfig(
- {
- functionId: "weather",
- recordInputs: true,
- recordOutputs: false,
- traceChannelRequests: true,
- },
- { agentName: "test-agent" },
- );
-
- expect(getInstrumentationRuntime()?.otelSettings).toEqual({
- functionId: "weather",
- recordInputs: true,
- recordOutputs: false,
- traceChannelRequests: true,
- });
- });
-
- it("disables input and output recording by default", async () => {
- const { registerInstrumentationConfig } = await import("#harness/instrumentation/config.js");
- const { getInstrumentationRuntime } = await import("#harness/instrumentation/runtime.js");
-
- await registerInstrumentationConfig({}, { agentName: "test-agent" });
-
- expect(getInstrumentationRuntime()?.otelSettings).toEqual({
- functionId: undefined,
- recordInputs: false,
- recordOutputs: false,
- traceChannelRequests: false,
- });
- });
-
- it("awaits the setup callback with the resolved context", async () => {
- vi.resetModules();
- const { registerInstrumentationConfig } = await import("#harness/instrumentation/config.js");
-
- const contexts: InstrumentationSetupContext[] = [];
- await registerInstrumentationConfig(
- {
- setup: (context) => {
- contexts.push(context);
- },
- },
- { agentName: "weather-agent" },
- );
-
- expect(contexts).toHaveLength(1);
- expect(contexts[0]?.agentName).toBe("weather-agent");
- expect(contexts[0]?.environment).toMatch(/^(development|production)$/);
- expect(contexts[0]?.frameworkVersion).toEqual(expect.any(String));
- });
-});
diff --git a/packages/eve/src/harness/instrumentation/config.ts b/packages/eve/src/harness/instrumentation/config.ts
deleted file mode 100644
index c8bf7d8d8..000000000
--- a/packages/eve/src/harness/instrumentation/config.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import { createInstrumentationHooks } from "#harness/instrumentation/lifecycle.js";
-import { registerInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
-import { createInstrumentationSetupContext } from "#harness/instrumentation/setup-context.js";
-import type { InstrumentationDefinition } from "#public/instrumentation/index.js";
-
-/**
- * Process-global store for the authored instrumentation config.
- *
- * Populated at server startup by the generated Nitro instrumentation plugin
- * when the user's `agent/instrumentation.ts` has a default export produced
- * by `defineInstrumentation()`. The harness reads from this at turn time
- * to decide whether telemetry is enabled and which settings to pass to the
- * AI SDK.
- *
- * Rooted on `globalThis` so the generated Nitro instrumentation plugin
- * (which Nitro keeps external by `file://` URL) and the bundled harness
- * chunk (which Nitro inlines via the package's `#harness/*` import alias)
- * share one source of truth, even though they resolve to two distinct ESM
- * module instances. See `context/key.ts` and
- * `runtime/sessions/runtime-session.ts` for the established pattern.
- */
-const INSTRUMENTATION_CONFIG_GLOBAL_KEY = Symbol.for("eve.harness-instrumentation-config");
-
-interface InstrumentationConfigGlobal {
- [INSTRUMENTATION_CONFIG_GLOBAL_KEY]?: InstrumentationDefinition;
-}
-
-const globalContainer = globalThis as typeof globalThis & InstrumentationConfigGlobal;
-
-/**
- * Registers the authored instrumentation config and awaits its `setup`
- * callback.
- *
- * Called once by the generated instrumentation Nitro plugin at server
- * startup. Subsequent calls overwrite the previous value.
- *
- * The store write lands before `setup` runs so a synchronous caller sees the
- * config without waiting on the returned promise.
- *
- * @internal — not part of the public API.
- */
-export async function registerInstrumentationConfig(
- config: InstrumentationDefinition,
- input: { readonly agentName: string },
-): Promise<void> {
- globalContainer[INSTRUMENTATION_CONFIG_GLOBAL_KEY] = config;
- // This legacy layout leaves `registerOTel` to `setup`, so install only the
- // runtime projection consumed by the harness.
- registerInstrumentationRuntime({
- forceFlush: async () => undefined,
- hooks: createInstrumentationHooks([]),
- otelSettings: {
- functionId: config.functionId,
- recordInputs: config.recordInputs === true,
- recordOutputs: config.recordOutputs === true,
- traceChannelRequests: config.traceChannelRequests === true,
- },
- runInContext: (_operation, execute) => execute(),
- shutdown: async () => undefined,
- });
- await config.setup?.(createInstrumentationSetupContext(input.agentName));
-}
-
-/**
- * Returns the registered instrumentation config, or `undefined` when no
- * `defineInstrumentation` export was provided.
- *
- * @internal — not part of the public API.
- */
-export function getInstrumentationConfig(): InstrumentationDefinition | undefined {
- return globalContainer[INSTRUMENTATION_CONFIG_GLOBAL_KEY];
-}
diff --git a/packages/eve/src/harness/instrumentation/runtime.ts b/packages/eve/src/harness/instrumentation/runtime.ts
deleted file mode 100644
index 4c45c879d..000000000
--- a/packages/eve/src/harness/instrumentation/runtime.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-import type {
- InstrumentationContextRunner,
- InstrumentationHooks,
- InstrumentationSessionStartedEvent,
- InstrumentationTraceSeed,
- InstrumentationTurnStartedEvent,
-} from "#harness/instrumentation/lifecycle.js";
-import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
-import type { OtelHarnessSettings, RuntimeContextResolver } from "#tracing/otel-declaration.js";
-
-const INSTRUMENTATION_RUNTIME_KEY = Symbol.for("eve.instrumentation-runtime");
-
-/** Process-wide runtime consumed by every harness execution surface. */
-export interface InstrumentationRuntime {
- readonly forceFlush: () => Promise<void>;
- readonly hooks: InstrumentationHooks;
- readonly idGenerator?: AgentSpanIdGenerator;
- readonly prepareSessionTrace?: (
- event: InstrumentationSessionStartedEvent,
- ) => Promise<InstrumentationTraceSeed>;
- readonly prepareTurnTrace?: (
- event: InstrumentationTurnStartedEvent,
- ) => Promise<InstrumentationTraceSeed>;
- otelSettings: OtelHarnessSettings | undefined;
- readonly runtimeContextResolvers?: readonly RuntimeContextResolver[];
- readonly runInContext: InstrumentationContextRunner;
- readonly shutdown: () => Promise<void>;
-}
-
-/** Instrumentation capabilities consumed inside one harness execution. */
-export type HarnessInstrumentation = Pick<
- InstrumentationRuntime,
- "hooks" | "prepareSessionTrace" | "prepareTurnTrace" | "runInContext"
->;
-
-type InstrumentationGlobal = typeof globalThis & {
- [INSTRUMENTATION_RUNTIME_KEY]?: InstrumentationRuntime;
-};
-
-const globalRuntime = globalThis as InstrumentationGlobal;
-
-/** Registers the process instrumentation runtime before agent execution begins. */
-export function registerInstrumentationRuntime(
- runtime: InstrumentationRuntime,
-): InstrumentationRuntime {
- const existing = globalRuntime[INSTRUMENTATION_RUNTIME_KEY];
- if (existing !== undefined) {
- // A legacy config may reload without taking ownership from the installed runtime.
- existing.otelSettings = runtime.otelSettings;
- return existing;
- }
- globalRuntime[INSTRUMENTATION_RUNTIME_KEY] = runtime;
- return runtime;
-}
-
-/** Returns the process instrumentation runtime, when one was installed. */
-export function getInstrumentationRuntime(): InstrumentationRuntime | undefined {
- return globalRuntime[INSTRUMENTATION_RUNTIME_KEY];
-}
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 9f6d7c7b5..60e8be438 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -37,12 +37,17 @@ import { invocationOwnerKey } from "#internal/invocation/metadata.js";
import { decodeSandboxRef, isSandboxRefUrl } from "#internal/attachments/sandbox-refs.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
-import type { InstrumentationStepStartedEventInput } from "#public/instrumentation/index.js";
+import type {
+ InstrumentationEvents,
+ InstrumentationStepStartedEventInput,
+} from "#public/instrumentation/index.js";
import { defineInstructions } from "#public/definitions/instructions.js";
import type { ResolvedDynamicInstructionsResolver } from "#runtime/types.js";
import type { DynamicResolveContext } from "#dynamic/definition.js";
import { registerDurableDynamicCallback } from "#tools/durable-callbacks.js";
import type { RunMode } from "#shared/run-mode.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
import { compactMessages, shouldCompact } from "#harness/compaction.js";
import {
getHarnessEmissionState,
@@ -75,7 +80,12 @@ import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harn
import {
createInstrumentationHooks,
type InstrumentationContextRunner,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import {
+ bindInstrumentationRuntime,
+ type InstrumentationRuntime,
+ type SessionInstrumentation,
+} from "#instrumentation/runtime.js";
import {
CONDITIONAL_DELIVERY_INSTRUCTION,
EMPTY_DELIVERY_SENTINEL,
@@ -113,42 +123,99 @@ const {
registeredOtelIntegration: { onStart: vi.fn() },
}));
-vi.mock("./ai-sdk-hook-bridge.js", () => ({
+vi.mock("#instrumentation/ai-sdk-hook-bridge.js", () => ({
createAiSdkHookBridge: (...args: unknown[]) => mockCreateAiSdkHookBridge(...args),
}));
-vi.mock("./ai-sdk-telemetry.js", () => ({
+vi.mock("#instrumentation/ai-sdk-telemetry.js", () => ({
ensureOtelIntegration: vi.fn(),
getRegisteredTelemetryIntegrations: (options?: { readonly sanitizeEveOtelErrors?: boolean }) =>
mockGetRegisteredTelemetryIntegrations(options),
}));
-const mockGetInstrumentationConfig = vi.fn().mockReturnValue(undefined);
-vi.mock("./instrumentation/config.js", () => ({
- getInstrumentationConfig: (...args: unknown[]) => mockGetInstrumentationConfig(...args),
-}));
+let declaredAudience: ChannelAudience = "unknown";
+let declaredDecision: InstrumentationDecision | undefined;
+let declaredInstrumentation: SessionInstrumentation | undefined;
+let declaredRuntime: InstrumentationRuntime | undefined;
-const mockGetInstrumentationRuntime = vi.fn().mockReturnValue(undefined);
-vi.mock("./instrumentation/runtime.js", () => ({
- getInstrumentationRuntime: (...args: unknown[]) => mockGetInstrumentationRuntime(...args),
-}));
+function createInstrumentationContext(
+ decision: InstrumentationDecision | undefined,
+ audience: ChannelAudience,
+): ContextContainer {
+ const ctx = new ContextContainer();
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:test",
+ metadata: { audience },
+ });
+ if (decision !== undefined) {
+ ctx.set(SessionTraceSeedKey, {
+ decision,
+ spanId: "1".repeat(16),
+ traceFlags: decision.action === "record" ? 1 : 0,
+ traceId: "2".repeat(32),
+ });
+ }
+ return ctx;
+}
-/**
- * Registering an authored config writes both stores, so the tests toggle
- * telemetry through one call rather than keeping two mocks in step by hand.
- */
-function declareTelemetry(config: Readonly<Record<string, unknown>> | undefined): void {
- mockGetInstrumentationConfig.mockReturnValue(config);
- mockGetInstrumentationRuntime.mockReturnValue(
+function declareTelemetry(
+ config:
+ | (Readonly<Record<string, unknown>> & { readonly events?: InstrumentationEvents })
+ | undefined,
+ decision?: InstrumentationDecision,
+ audience: ChannelAudience = "unknown",
+): void {
+ declaredAudience = audience;
+ declaredDecision = decision;
+ declaredRuntime =
config === undefined
? undefined
: {
+ forceFlush: async () => undefined,
+ hooks: createInstrumentationHooks([]),
otelSettings: {
...config,
traceChannelRequests: config["traceChannelRequests"] === true,
},
- },
- );
+ runInContext: (_operation, execute) => execute(),
+ shutdown: async () => undefined,
+ stepStartedRuntimeContextResolver: config.events?.["step.started"] ?? (() => undefined),
+ };
+ declaredInstrumentation = bindInstrumentationRuntime(
+ declaredRuntime,
+ createInstrumentationContext(decision, audience),
+ {
+ rootSessionId: "test-session",
+ sessionId: "test-session",
+ },
+ )?.prepareExecution();
+}
+
+function bindHookInstrumentation(
+ hooks: ReturnType<typeof createInstrumentationHooks>,
+ runInContext: InstrumentationContextRunner = (_operation, execute) => execute(),
+ useDeclaredRuntime = false,
+): SessionInstrumentation {
+ return bindInstrumentationRuntime(
+ {
+ forceFlush: async () => undefined,
+ hooks,
+ otelSettings: useDeclaredRuntime ? declaredRuntime?.otelSettings : undefined,
+ runtimeContextResolvers: useDeclaredRuntime
+ ? declaredRuntime?.runtimeContextResolvers
+ : undefined,
+ runInContext,
+ shutdown: async () => undefined,
+ stepStartedRuntimeContextResolver: useDeclaredRuntime
+ ? declaredRuntime?.stepStartedRuntimeContextResolver
+ : undefined,
+ },
+ createInstrumentationContext(
+ useDeclaredRuntime ? declaredDecision : undefined,
+ useDeclaredRuntime ? declaredAudience : "unknown",
+ ),
+ { rootSessionId: "test-session", sessionId: "test-session" },
+ )!.prepareExecution();
}
vi.mock("./compaction.js", () => ({
@@ -196,6 +263,7 @@ function createTestConfig(
): ToolLoopHarnessConfig {
return {
handleEvent: emit,
+ instrumentation: declaredInstrumentation,
mode,
resolveModel: vi.fn().mockResolvedValue({} as LanguageModel),
tools: new Map([
@@ -4969,11 +5037,15 @@ describe("createToolLoopHarness", () => {
"test.attempt": typeof input.modelInput.instructions === "string" ? "original" : "retry",
},
}));
- declareTelemetry({
- events: {
- "step.started": resolveRuntimeContext,
+ declareTelemetry(
+ {
+ events: {
+ "step.started": resolveRuntimeContext,
+ },
},
- });
+ undefined,
+ "public",
+ );
const { constructedCalls } = setupRecoveryAgent({
failure: createGatewayUnsupportedToolError({ unsupportedTypes: ["web_search_20250305"] }),
successResult: {
@@ -4996,10 +5068,7 @@ describe("createToolLoopHarness", () => {
},
});
const config: ToolLoopHarnessConfig = {
- instrumentation: {
- hooks: createInstrumentationHooks([]),
- runInContext: (_operation, execute) => execute(),
- },
+ instrumentation: declaredInstrumentation,
mode: "conversation",
resolveModel: vi.fn().mockResolvedValue("anthropic/claude-opus-4.7"),
tools: new Map([
@@ -11025,10 +11094,7 @@ describe("createToolLoopHarness", () => {
]);
const runStep = createToolLoopHarness(
createTestConfig("conversation", undefined, {
- instrumentation: {
- hooks: createInstrumentationHooks([]),
- runInContext: (_operation, execute) => execute(),
- },
+ instrumentation: declaredInstrumentation,
}),
);
@@ -11068,11 +11134,14 @@ describe("createToolLoopHarness", () => {
toolCalls: [],
toolResults: [],
});
- declareTelemetry({
- recordInputs: true,
- recordOutputs: true,
- tracePolicy: () => false,
- });
+ declareTelemetry(
+ {
+ recordInputs: true,
+ recordOutputs: true,
+ tracePolicy: () => false,
+ },
+ { action: "drop" },
+ );
const runStep = createToolLoopHarness(createTestConfig());
await runStep(createTestSession(), { message: "private" });
@@ -11092,7 +11161,7 @@ describe("createToolLoopHarness", () => {
toolCalls: [],
toolResults: [],
});
- declareTelemetry({ tracePolicy: () => false });
+ declareTelemetry({ tracePolicy: () => false }, { action: "drop" });
const attemptCompleted = vi.fn();
const hooks = createInstrumentationHooks([
{
@@ -11103,7 +11172,7 @@ describe("createToolLoopHarness", () => {
]);
const runStep = createToolLoopHarness(
createTestConfig("conversation", undefined, {
- instrumentation: { hooks, runInContext: (_operation, execute) => execute() },
+ instrumentation: bindHookInstrumentation(hooks, undefined, true),
}),
);
const ctx = new ContextContainer();
@@ -11140,7 +11209,7 @@ describe("createToolLoopHarness", () => {
const hooks = createInstrumentationHooks([{ capture: "content", name: "analytics" }]);
const runStep = createToolLoopHarness(
createTestConfig("conversation", undefined, {
- instrumentation: { hooks, runInContext: (_operation, execute) => execute() },
+ instrumentation: bindHookInstrumentation(hooks, undefined, true),
}),
);
@@ -11169,23 +11238,20 @@ describe("createToolLoopHarness", () => {
toolCalls: [],
toolResults: [],
});
- declareTelemetry({
- recordInputs: true,
- recordOutputs: true,
- tracePolicy: () => ({
- emit: true,
- recordInputs: inputs,
- recordOutputs: outputs,
- }),
- });
- const runStep = createToolLoopHarness(
- createTestConfig("conversation", undefined, {
- instrumentation: {
- hooks: createInstrumentationHooks([]),
- runInContext: (_operation, execute) => execute(),
- },
- }),
+ declareTelemetry(
+ {
+ recordInputs: true,
+ recordOutputs: true,
+ tracePolicy: () => ({
+ emit: true,
+ recordInputs: inputs,
+ recordOutputs: outputs,
+ }),
+ },
+ { action: "record", recordInputs: inputs, recordOutputs: outputs },
+ "public",
);
+ const runStep = createToolLoopHarness(createTestConfig());
const ctx = new ContextContainer();
ctx.set(ChannelInstrumentationKey, {
kind: "channel:public",
@@ -11214,15 +11280,19 @@ describe("createToolLoopHarness", () => {
toolCalls: [],
toolResults: [],
});
- declareTelemetry({
- recordInputs: false,
- recordOutputs: true,
- tracePolicy: () => ({
- emit: true,
- recordInputs: true,
+ declareTelemetry(
+ {
+ recordInputs: false,
recordOutputs: true,
- }),
- });
+ tracePolicy: () => ({
+ emit: true,
+ recordInputs: true,
+ recordOutputs: true,
+ }),
+ },
+ { action: "record", recordInputs: true, recordOutputs: true },
+ "public",
+ );
const runStep = createToolLoopHarness(createTestConfig());
const ctx = new ContextContainer();
ctx.set(ChannelInstrumentationKey, {
@@ -11244,7 +11314,7 @@ describe("createToolLoopHarness", () => {
});
});
- it("reuses the persisted rejected trace decision", async () => {
+ it("uses the injected decision instead of reinterpreting the trace seed", async () => {
setupMockAgent({
finishReason: "stop",
response: { messages: [{ content: "Hello!", role: "assistant" }] },
@@ -11253,15 +11323,11 @@ describe("createToolLoopHarness", () => {
toolResults: [],
});
const tracePolicy = vi.fn(() => true);
- declareTelemetry({ recordInputs: true, recordOutputs: true, tracePolicy });
- const runStep = createToolLoopHarness(
- createTestConfig("conversation", undefined, {
- instrumentation: {
- hooks: createInstrumentationHooks([]),
- runInContext: (_operation, execute) => execute(),
- },
- }),
+ declareTelemetry(
+ { recordInputs: true, recordOutputs: true, tracePolicy },
+ { action: "drop" },
);
+ const runStep = createToolLoopHarness(createTestConfig());
const ctx = new ContextContainer();
ctx.set(SessionTraceSeedKey, {
decision: { action: "drop" },
@@ -11281,42 +11347,6 @@ describe("createToolLoopHarness", () => {
expect(tracePolicy).not.toHaveBeenCalled();
});
- it("supports a persisted legacy seed without a decision", async () => {
- setupMockAgent({
- finishReason: "stop",
- response: { messages: [{ content: "Hello!", role: "assistant" }] },
- text: "Hello!",
- toolCalls: [],
- toolResults: [],
- });
- const tracePolicy = vi.fn(() => true);
- declareTelemetry({ recordInputs: true, recordOutputs: true, tracePolicy });
- const runStep = createToolLoopHarness(
- createTestConfig("conversation", undefined, {
- instrumentation: {
- hooks: createInstrumentationHooks([]),
- runInContext: (_operation, execute) => execute(),
- },
- }),
- );
- const ctx = new ContextContainer();
- ctx.set(SessionTraceSeedKey, {
- spanId: "1".repeat(16),
- traceFlags: 0,
- traceId: "2".repeat(32),
- });
-
- await contextStorage.run(ctx, () => runStep(createTestSession(), { message: "private" }));
-
- const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
- telemetry?: { integrations?: unknown[] };
- };
- expect(agentCall.telemetry?.integrations).toEqual([
- mockCreateAiSdkHookBridge.mock.results[0]!.value,
- ]);
- expect(tracePolicy).not.toHaveBeenCalled();
- });
-
it("emits the authored turn trace with the session and turn preamble", async () => {
const authoredTrace = {
spanId: "0123456789abcdef",
@@ -11381,7 +11411,9 @@ describe("createToolLoopHarness", () => {
expect(runtimeContext?.["eve.version"]).not.toBe("");
expect(runtimeContext?.["eve.session.id"]).toBe("test-session");
expect(agentCall?.telemetry?.isEnabled).toBe(true);
- expect(agentCall?.telemetry?.integrations).toEqual([]);
+ expect(agentCall?.telemetry?.integrations).toEqual([
+ mockCreateAiSdkHookBridge.mock.results[0]!.value,
+ ]);
expect(mockGetRegisteredTelemetryIntegrations).toHaveBeenCalledWith({
sanitizeEveOtelErrors: true,
});
@@ -11401,7 +11433,7 @@ describe("createToolLoopHarness", () => {
]);
const runInContext: InstrumentationContextRunner = (_operation, execute) => execute();
const config = createTestConfig("conversation", undefined, {
- instrumentation: { hooks, runInContext },
+ instrumentation: bindHookInstrumentation(hooks, runInContext),
});
const runStep = createToolLoopHarness(config);
@@ -11477,7 +11509,7 @@ describe("createToolLoopHarness", () => {
const { emit } = createEventCollector();
const runStep = createToolLoopHarness(
createTestConfig("conversation", emit, {
- instrumentation: { hooks, runInContext: (_operation, execute) => execute() },
+ instrumentation: bindHookInstrumentation(hooks),
tools: createDelegationToolMap(),
}),
);
@@ -11503,19 +11535,15 @@ describe("createToolLoopHarness", () => {
toolCalls: [],
toolResults: [],
});
- declareTelemetry({ recordInputs: true, recordOutputs: false });
+ declareTelemetry({ recordInputs: true, recordOutputs: false }, undefined, "public");
// An authored module can register its own integration alongside eve's.
mockGetRegisteredTelemetryIntegrations.mockReturnValue([
registeredOtelIntegration,
registeredAuthorIntegration,
]);
- const hooks = createInstrumentationHooks([]);
const runStep = createToolLoopHarness(
createTestConfig("conversation", undefined, {
- instrumentation: {
- hooks,
- runInContext: (_operation, execute) => execute(),
- },
+ instrumentation: declaredInstrumentation,
}),
);
@@ -11621,11 +11649,15 @@ describe("createToolLoopHarness", () => {
},
};
});
- declareTelemetry({
- events: {
- "step.started": resolveRuntimeContext,
+ declareTelemetry(
+ {
+ events: {
+ "step.started": resolveRuntimeContext,
+ },
},
- });
+ undefined,
+ "public",
+ );
const ctx = new ContextContainer();
ctx.set(ChannelInstrumentationKey, {
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index de430a58f..bc107ff54 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -1,9 +1,3 @@
-import {
- context as otelContext,
- type Span,
- type SpanContext,
- trace,
-} from "#compiled/@opentelemetry/api/index.js";
import {
isStepCount,
type LanguageModelCallEndEvent,
@@ -11,7 +5,6 @@ import {
type ModelMessage,
type ProviderMetadata,
type SystemModelMessage,
- type Telemetry,
type TelemetryOptions,
ToolLoopAgent,
type ToolSet,
@@ -22,23 +15,14 @@ import {
import type { SessionAuthContext } from "#channel/types.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
import { resolveProviderHeaders } from "#internal/gateway.js";
-import {
- createErrorId,
- createLogger,
- formatError,
- logError,
- recordErrorOnSpan,
-} from "#internal/logging.js";
+import { createErrorId, createLogger, formatError, logError } from "#internal/logging.js";
import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
import { contextStorage } from "#context/container.js";
import {
AuthKey,
- ChannelInstrumentationKey,
ParentSessionKey,
- ParentTraceContextKey,
ScheduleIdKey,
SessionCallbackKey,
- SessionTraceSeedKey,
TurnTaskDeliveryKey,
TurnTaskStateKey,
} from "#context/keys.js";
@@ -63,7 +47,6 @@ import {
import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
import { toErrorMessage } from "#shared/errors.js";
-import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";
import {
createActionResultEvent,
createApprovalCandidateEvent,
@@ -153,16 +136,7 @@ import {
coordinateApprovalDelivery,
shouldPrepareApprovalPolicyTools,
} from "#harness/approval-delivery-coordinator.js";
-import { buildTelemetryRuntimeContext } from "#harness/instrumentation/runtime-context.js";
-import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";
-import {
- createInstrumentationHandleEvent,
- publishInputResolutions,
-} from "#harness/instrumentation/native-events.js";
-import type { InstrumentationAttemptScope } from "#harness/instrumentation/lifecycle.js";
-import { attemptIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
-import { resolveParentLineage } from "#harness/parent-lineage.js";
-import { prepareTurnTraceContext } from "#harness/prepare-trace-context.js";
+import type { InstrumentationAttempt, InstrumentationStepScope } from "#instrumentation/runtime.js";
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { TASK_UPDATE_TOOL_NAME } from "#tools/framework/task-contract.js";
import { readTaskIdFromInboxToken } from "#tasks/task-inbox-token.js";
@@ -181,20 +155,6 @@ import {
convertStaleResponsesToUserMessage,
dropStaleSessionLimitContinuationResponses,
} from "#harness/stale-input-responses.js";
-import { getInstrumentationConfig } from "#harness/instrumentation/config.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
-import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
-import {
- applyAudienceCeiling,
- shouldCaptureInstrumentationContent,
-} from "#shared/instrumentation-content.js";
-import type { OtelHarnessSettings } from "#tracing/otel-declaration.js";
-import { readCurrentSessionTraceDecision } from "#tracing/agent-trace-context-store.js";
-import {
- isSampledTrace,
- resolveTracePolicy,
- resolveTracePolicyDecision,
-} from "#tracing/sampled-trace.js";
import {
normalizeModelMessages,
normalizeUserContent,
@@ -227,10 +187,6 @@ import type { JsonObject, JsonValue } from "#shared/json.js";
import { EMPTY_DELIVERY_SENTINEL, hasEmptyDeliverySentinel } from "#shared/empty-delivery.js";
import { resolveDeliveryPolicy } from "#tasks/delivery-policy.js";
import { extractWorkflowStreamWriteErrorDetails } from "#harness/workflow-stream-error.js";
-import {
- ensureOtelIntegration,
- getRegisteredTelemetryIntegrations,
-} from "#harness/ai-sdk-telemetry.js";
import { getAdvertisedTools } from "#harness/advertised-tools.js";
import { createBackgroundToolCallBatch } from "#harness/background-tools.js";
import {
@@ -292,7 +248,7 @@ import {
*
* Custom context (authored `InstrumentationDefinition.events` plus
* eve-specific identifiers such as `eve.session.id`) is flowed through
- * {@link buildTelemetryRuntimeContext} because AI SDK v7 surfaces
+ * Bound instrumentation supplies custom context because AI SDK v7 surfaces
* per-call attributes via `runtimeContext`, not a dedicated metadata field on
* `TelemetryOptions`.
*/
@@ -335,60 +291,6 @@ const MODEL_CALL_MAX_ATTEMPTS = 3;
*/
const MODEL_CALL_RETRY_BASE_DELAY_MS = 500;
-function enrichTelemetry(
- decision: InstrumentationDecision | undefined,
- settings: OtelHarnessSettings | undefined,
- channelAudience: ChannelAudience,
- agentName: string | undefined,
- runtimeContext?: Readonly<Record<string, unknown>>,
- bridgeIntegration?: Telemetry,
-): TelemetryOptions | undefined {
- const dropsTrace = decision?.action === "drop";
- if (settings === undefined && bridgeIntegration === undefined) {
- return undefined;
- }
-
- // AI SDK telemetry redacts runtimeContext unless every exported key is
- // opted in. This context only contains sanitized instrumentation context.
- const includeRuntimeContext: Record<string, true> = {};
- for (const key of Object.keys(runtimeContext ?? {})) {
- includeRuntimeContext[key] = true;
- }
-
- const effectiveDecision =
- decision === undefined ? undefined : applyAudienceCeiling(decision, channelAudience);
- const recordInputs =
- !dropsTrace &&
- (effectiveDecision?.action === "record"
- ? effectiveDecision.recordInputs
- : shouldCaptureInstrumentationContent(channelAudience)) &&
- (settings?.recordInputs ?? false);
- const recordOutputs =
- !dropsTrace &&
- (effectiveDecision?.action === "record"
- ? effectiveDecision.recordOutputs
- : shouldCaptureInstrumentationContent(channelAudience)) &&
- (settings?.recordOutputs ?? false);
- const sanitizeEveOtelErrors = settings !== undefined && !(recordInputs && recordOutputs);
- const registeredIntegrations = () =>
- getRegisteredTelemetryIntegrations({ sanitizeEveOtelErrors });
- return {
- functionId: settings?.functionId ?? agentName,
- includeRuntimeContext,
- // Passing integrations replaces the registered ones for this call, so the
- // bridge has to be composed with them rather than handed over on its own.
- integrations:
- bridgeIntegration === undefined
- ? sanitizeEveOtelErrors
- ? [...registeredIntegrations()]
- : undefined
- : [bridgeIntegration, ...registeredIntegrations()],
- isEnabled: true,
- recordInputs,
- recordOutputs,
- };
-}
-
function mergeSystemInstructions(
instructions: readonly SystemModelMessage[],
): SystemModelMessage | undefined {
@@ -522,76 +424,6 @@ function updateCompactionThresholdForModelReference(input: {
};
}
-// ---------------------------------------------------------------------------
-// Turn trace state — survives step boundaries via session.state
-// ---------------------------------------------------------------------------
-
-const TURN_TRACE_STATE_KEY = "eve.harness.turnTrace";
-
-/**
- * Serializable subset of `SpanContext` stored on `session.state` so
- * continuation steps within the same turn can restore the parent trace.
- */
-interface TurnTraceState {
- readonly traceId: string;
- readonly spanId: string;
- readonly traceFlags: number;
-}
-
-function getTurnTraceState(session: {
- readonly state?: Readonly<Record<string, unknown>>;
-}): TurnTraceState | undefined {
- return session.state?.[TURN_TRACE_STATE_KEY] as TurnTraceState | undefined;
-}
-
-function setTurnTraceState(session: HarnessSession, spanContext: SpanContext): HarnessSession {
- const stored: TurnTraceState = {
- traceId: spanContext.traceId,
- spanId: spanContext.spanId,
- traceFlags: spanContext.traceFlags,
- };
-
- return {
- ...session,
- state: {
- ...session.state,
- [TURN_TRACE_STATE_KEY]: stored,
- },
- };
-}
-
-/**
- * Resolves the OTel context for the current step.
- *
- * First step of a turn: uses the newly created turn span.
- * Continuation steps: restores the parent span context from session state
- * so AI SDK spans nest under the same trace as the first step.
- */
-function resolveStepOtelContext(
- tracer: ReturnType<typeof trace.getTracer> | undefined,
- turnSpan: Span | undefined,
- session: { readonly state?: Readonly<Record<string, unknown>> },
-): ReturnType<typeof otelContext.active> | undefined {
- if (turnSpan) {
- return trace.setSpan(otelContext.active(), turnSpan);
- }
-
- if (tracer) {
- const stored = getTurnTraceState(session);
- if (stored) {
- const parent = trace.wrapSpanContext({
- isRemote: true,
- traceId: stored.traceId,
- spanId: stored.spanId,
- traceFlags: stored.traceFlags,
- });
- return trace.setSpan(otelContext.active(), parent);
- }
- }
-
- return undefined;
-}
-
function buildHarnessToolsWithDynamicSubagents(
tools: HarnessToolMap,
ctx: Parameters<typeof buildDynamicSubagentTools>[0] | undefined,
@@ -614,67 +446,30 @@ function buildHarnessToolsWithDynamicSubagents(
export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const baseEmit = config.handleEvent;
- const instrumentationRuntime = getInstrumentationRuntime();
- const otelSettings = instrumentationRuntime?.otelSettings;
- // The legacy single-file layout reads its runtime-context resolver from the
- // authored config object; the provider directory collects resolvers at install
- // time onto the runtime. Both paths feed buildTelemetryRuntimeContext.
- const authoredConfig = getInstrumentationConfig();
- const providerRuntimeContextResolvers = instrumentationRuntime?.runtimeContextResolvers;
- if (otelSettings !== undefined) {
- ensureOtelIntegration();
- }
- const tracer = otelSettings !== undefined ? trace.getTracer("eve") : undefined;
- const agentName = config.runtimeIdentity?.agentName;
async function runStep(
initialSession: Readonly<Parameters<StepFn>[0]>,
input?: StepInput,
): Promise<StepResult> {
- const instrumentationDecision = resolveStepInstrumentationDecision(
- otelSettings,
- agentName,
- initialSession.sessionId,
+ const executeStep = (scope: InstrumentationStepScope<HarnessSession>) =>
+ executeStepBody(scope.session, input, scope);
+ return (
+ config.instrumentation?.runStep(
+ {
+ environment,
+ eveVersion,
+ hasInput: hasStepInput(input),
+ session: initialSession,
+ },
+ executeStep,
+ ) ?? executeStepBody(initialSession, input)
);
- // --- Turn span lifecycle ------------------------------------------------
-
- // First step of a turn: open a new parent span. Continuation steps
- // restore the parent from session state via resolveStepOtelContext.
- let turnSpan: Span | undefined;
- if (tracer && instrumentationDecision?.action !== "drop" && hasStepInput(input)) {
- const functionId = otelSettings?.functionId ?? agentName;
- const attributes: Record<string, string> = {
- "eve.version": eveVersion,
- "eve.environment": environment,
- "eve.session.id": initialSession.sessionId,
- };
- if (functionId) {
- attributes["ai.telemetry.functionId"] = functionId;
- }
- turnSpan = tracer.startSpan("ai.eve.turn", { attributes });
- }
-
- // Run the step body inside the turn span's (or restored parent's)
- // OTel context so AI SDK spans nest as children.
- const parentContext = resolveStepOtelContext(tracer, turnSpan, initialSession);
- const executeStep = () =>
- executeStepBody(initialSession, input, turnSpan, instrumentationDecision);
-
- try {
- if (parentContext) {
- return await otelContext.with(parentContext, executeStep);
- }
- return await executeStep();
- } finally {
- turnSpan?.end();
- }
}
async function executeStepBody(
initialSession: Readonly<Parameters<StepFn>[0]>,
input?: StepInput,
- turnSpan?: Span,
- instrumentationDecision?: InstrumentationDecision,
+ stepInstrumentation?: InstrumentationStepScope<HarnessSession>,
): Promise<StepResult> {
let session = initialSession;
const prepareHistory = createHistoryViewPreparer({
@@ -687,17 +482,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
state: HarnessSession["state"],
): readonly ModelMessage[] => prepareHistory(messages, state).messages;
- // Store the turn span context on the session so continuation steps
- // can restore the parent trace across step boundaries.
- if (turnSpan) {
- session = setTurnTraceState(session, turnSpan.spanContext());
- }
-
let emissionState = getHarnessEmissionState(session.state);
const store = contextStorage.getStore();
- const channelInstrumentation = store?.get(ChannelInstrumentationKey);
- const channelAudience = normalizeChannelAudience(channelInstrumentation?.metadata.audience);
- const instrumentationHooks = config.instrumentation?.hooks;
const parent = store?.get(ParentSessionKey);
const channel = store?.get(ChannelKey);
const callback = store?.get(SessionCallbackKey);
@@ -706,31 +492,19 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
callback?.taskId !== undefined ||
readTaskIdFromInboxToken(String(channel?.state?.parentContinuationToken ?? "")) !== undefined;
const taskUpdatesEnabled = taskOwned && config.tools.has(TASK_UPDATE_TOOL_NAME);
- const parentLineage = resolveParentLineage(parent, channel);
- const parentTraceContext = store?.get(ParentTraceContextKey);
- const traceSeed = store?.get(SessionTraceSeedKey);
- let activeAttemptScope: InstrumentationAttemptScope | undefined;
- const emit = createInstrumentationHandleEvent({
- agentName: config.runtimeIdentity?.agentName,
- channelAudience,
- channelKind: channelInstrumentation?.kind,
- getAttemptScope: () => activeAttemptScope,
- handleEvent: baseEmit,
- hooks: instrumentationHooks,
- parentLineage,
- parentTraceContext,
- rootSessionId: parent?.rootSessionId,
- sessionId: session.sessionId,
- turnId: activeTurnId(emissionState),
- });
+ let activeAttemptScope: InstrumentationAttempt | undefined;
+ const emit =
+ stepInstrumentation?.createHandleEvent({
+ getAttemptScope: () => activeAttemptScope,
+ handleEvent: baseEmit,
+ turnId: activeTurnId(emissionState),
+ }) ?? baseEmit;
const failModelSelection = async (
error: unknown,
failureState: ReturnType<typeof getHarnessEmissionState>,
): Promise<StepResult> => {
throwIfTurnAborted(config.abortSignal);
- if (turnSpan) {
- recordErrorOnSpan(turnSpan, error);
- }
+ stepInstrumentation?.recordError(error);
if (!emit) {
throw error;
}
@@ -759,28 +533,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
};
};
const preparePreambleTrace = async (): Promise<RuntimeTraceContext | undefined> => {
- const spanContext = turnSpan?.spanContext();
- const authoredTraceContext =
- spanContext !== undefined && isValidSpanContext(spanContext)
- ? {
- spanId: spanContext.spanId,
- traceFlags: spanContext.traceFlags,
- traceId: spanContext.traceId,
- }
- : undefined;
- return await prepareTurnTraceContext({
- agentName: config.runtimeIdentity?.agentName,
- channelAudience,
- channelType: channelInstrumentation?.channelType,
- instrumentation: config.instrumentation,
- parentLineage,
- parentTraceContext,
- rootSessionId: parent?.rootSessionId ?? session.rootSessionId ?? session.sessionId,
+ return await stepInstrumentation?.preparePreamble({
sequence: emissionState.sequence,
- sessionId: session.sessionId,
sessionStarted: emissionState.sessionStarted,
- traceContext: authoredTraceContext,
- traceSeed,
+ traceContext: stepInstrumentation?.traceContext,
turnId: `turn_${emissionState.sequence}`,
});
};
@@ -830,9 +586,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
resolveModel: config.resolveModel,
runtimeIdentity: config.runtimeIdentity,
session,
- telemetry:
- enrichTelemetry(instrumentationDecision, otelSettings, channelAudience, agentName) ??
- undefined,
+ telemetry: stepInstrumentation?.telemetry(),
});
session = {
@@ -1122,13 +876,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
if (pending.resolvedInputs !== undefined) {
for (const batch of pending.resolvedInputs) {
- if (instrumentationHooks !== undefined) {
- await publishInputResolutions({
- batch,
- hooks: instrumentationHooks,
- sessionId: session.sessionId,
- });
- }
+ await stepInstrumentation?.publishInputResolutions({
+ batch,
+ sessionId: session.sessionId,
+ });
if (emit) {
await emit(
createInputResolvedEvent({
@@ -1229,9 +980,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
instructionMessages = store === undefined ? [] : drainDynamicInstructionUserMessages(store);
memoryCommit = store === undefined ? undefined : drainMemoryCommit(store);
- if (turnSpan) {
- turnSpan.setAttribute("eve.turn.id", emissionState.turnId);
- }
+ stepInstrumentation?.setTurnId(emissionState.turnId);
}
const committedHistory = memoryCommit?.history ?? pending.session.history;
@@ -1341,9 +1090,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
resolveModel: config.resolveModel,
runtimeIdentity: config.runtimeIdentity,
session,
- telemetry:
- enrichTelemetry(instrumentationDecision, otelSettings, channelAudience, agentName) ??
- undefined,
+ telemetry: stepInstrumentation?.telemetry(),
});
session = compaction.session;
if (compaction.compacted) {
@@ -1432,16 +1179,14 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
return {
instructions,
- telemetryRuntimeContext: buildTelemetryRuntimeContext({
+ telemetryRuntimeContext: stepInstrumentation?.resolveRuntimeContext({
eveVersion,
- authored: authoredConfig,
emissionState,
environment,
modelInput: {
instructions,
messages: modelMessages,
},
- providerResolvers: providerRuntimeContextResolvers,
session,
}),
};
@@ -1556,29 +1301,14 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const effectiveTools = marker ? applyLastToolCacheBreakpoint(modelTools, marker) : modelTools;
const instrumentationTurnId = activeTurnId(emissionState);
- const attemptScope: InstrumentationAttemptScope | undefined =
- instrumentationHooks === undefined
- ? undefined
- : {
- attemptId: `${session.sessionId}:${instrumentationTurnId}:${emissionState.stepIndex}:${opts.attemptIndex}`,
- attemptIndex: opts.attemptIndex,
- channelAudience,
- functionId: otelSettings?.functionId ?? agentName,
- rootSessionId: parent?.rootSessionId ?? session.sessionId,
- sessionId: session.sessionId,
- stepIndex: emissionState.stepIndex,
- turnId: instrumentationTurnId,
- };
+ const attempt = stepInstrumentation?.prepareAttempt({
+ attemptIndex: opts.attemptIndex,
+ runtimeContext: telemetryRuntimeContext,
+ stepIndex: emissionState.stepIndex,
+ turnId: instrumentationTurnId,
+ });
+ const attemptScope = attempt?.scope;
activeAttemptScope = attemptScope;
- const bridgeIntegration =
- attemptScope === undefined || instrumentationHooks === undefined
- ? undefined
- : createAiSdkHookBridge(
- attemptScope,
- instrumentationHooks,
- config.instrumentation?.runInContext,
- telemetryRuntimeContext,
- );
const hooks = buildStepHooks({
auth: ctx?.get(AuthKey) ?? null,
@@ -1627,14 +1357,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
reasoning: session.agent.reasoning,
runtimeContext: telemetryRuntimeContext,
stopWhen: isStepCount(1),
- telemetry: enrichTelemetry(
- instrumentationDecision,
- otelSettings,
- channelAudience,
- agentName,
- telemetryRuntimeContext,
- bridgeIntegration,
- ),
+ telemetry: attempt?.telemetry,
toolApproval: buildToolApproval(modelTools),
tools: effectiveTools,
};
@@ -1724,23 +1447,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
try {
const result = await executeModelCall();
- if (attemptScope !== undefined) {
- await instrumentationHooks?.publish({
- idempotencyKey: attemptIdempotencyKey(attemptScope),
- scope: attemptScope,
- type: "step.attempt.completed",
- });
- }
+ await attempt?.complete();
return result;
} catch (error) {
- if (attemptScope !== undefined) {
- await instrumentationHooks?.publish({
- error,
- idempotencyKey: attemptIdempotencyKey(attemptScope),
- scope: attemptScope,
- type: "step.attempt.failed",
- });
- }
+ await attempt?.fail(error);
return rethrowNoOutputAsEmptyResponse(error);
}
};
@@ -1837,9 +1547,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// so the gateway-wrapped upstream 4xx body would otherwise be
// invisible to OTel providers.
const finalError = recoveryResult.error;
- if (turnSpan) {
- recordErrorOnSpan(turnSpan, finalError);
- }
+ stepInstrumentation?.recordError(finalError);
if (!emit) {
// Internal harness callers without an emit fn (tests, task-only
@@ -2057,42 +1765,6 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
return runStep;
}
-function resolveStepInstrumentationDecision(
- settings: OtelHarnessSettings | undefined,
- agentName: string | undefined,
- sessionId: string,
-): InstrumentationDecision | undefined {
- if (settings === undefined) return undefined;
-
- const store = contextStorage.getStore();
- const traceSeed = store?.get(SessionTraceSeedKey);
- if (traceSeed?.decision !== undefined) return traceSeed.decision;
- const persisted = readCurrentSessionTraceDecision(sessionId);
- if (persisted !== undefined) return persisted;
-
- const channel = store?.get(ChannelInstrumentationKey);
- const audience = normalizeChannelAudience(channel?.metadata.audience);
- if (traceSeed !== undefined) {
- return resolveTracePolicyDecision(isSampledTrace(traceSeed), audience);
- }
- // The first step can reach this before OTel session preparation persists its
- // decision, so that preparation may invoke the policy again.
- return resolveTracePolicy(settings.tracePolicy, {
- agentName,
- audience,
- channelType: channel?.channelType,
- });
-}
-
-function isValidSpanContext(spanContext: SpanContext): boolean {
- return (
- /^[0-9a-f]{32}$/u.test(spanContext.traceId) &&
- spanContext.traceId !== "00000000000000000000000000000000" &&
- /^[0-9a-f]{16}$/u.test(spanContext.spanId) &&
- spanContext.spanId !== "0000000000000000"
- );
-}
-
function extractTokenUsageDelta(input: {
readonly costUsd: number | undefined;
readonly usage: HarnessStepResult["usage"] | undefined;
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 54e0c77ed..270f0acb0 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -14,7 +14,7 @@ import type { InternalToolDefinition } from "#tools/definition.js";
import type { WebSearchProvider } from "#shared/web-search.js";
import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
-import type { HarnessInstrumentation } from "#harness/instrumentation/runtime.js";
+import type { SessionInstrumentation } from "#instrumentation/runtime.js";
import type { HistoryViewProjector, PreparedHistoryView } from "#shared/history-view.js";
/**
@@ -310,7 +310,7 @@ export interface ToolLoopHarnessConfig {
* Internal lifecycle hooks injected into each actual model attempt.
* Omitted in production until an instrumentation runtime opts in.
*/
- readonly instrumentation?: HarnessInstrumentation;
+ readonly instrumentation?: SessionInstrumentation;
/**
* Execution mode for the current harness.
*
diff --git a/packages/eve/src/harness/ai-sdk-hook-bridge.test.ts b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts
similarity index 99%
rename from packages/eve/src/harness/ai-sdk-hook-bridge.test.ts
rename to packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts
index 754bd31e6..ec0b7466d 100644
--- a/packages/eve/src/harness/ai-sdk-hook-bridge.test.ts
+++ b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it, vi } from "vitest";
-import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";
+import { createAiSdkHookBridge } from "#instrumentation/ai-sdk-hook-bridge.js";
import {
attemptIdempotencyKey,
createInstrumentationHooks,
@@ -13,7 +13,7 @@ import {
type InstrumentationStepAttemptStartedEvent,
type InstrumentationToolCallStartedEvent,
type InstrumentationToolCallTerminalEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
const scope: InstrumentationAttemptScope = {
attemptId: "turn-1:step-0:attempt-0",
diff --git a/packages/eve/src/harness/ai-sdk-hook-bridge.ts b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts
similarity index 98%
rename from packages/eve/src/harness/ai-sdk-hook-bridge.ts
rename to packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts
index 8aef26bdb..6e1c9d506 100644
--- a/packages/eve/src/harness/ai-sdk-hook-bridge.ts
+++ b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts
@@ -13,13 +13,13 @@ import type {
InstrumentationToolCallStartedEvent,
InstrumentationToolOutput,
InstrumentationUsage,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import {
attemptIdempotencyKey,
modelCallIdempotencyKey,
toolCallIdempotencyKey,
-} from "#harness/instrumentation/lifecycle.js";
-import { structuralProviderMetadata } from "#harness/instrumentation/content.js";
+} from "#instrumentation/lifecycle.js";
+import { structuralProviderMetadata } from "#instrumentation/content.js";
type TelemetryEvent<TKey extends keyof Telemetry> = Parameters<NonNullable<Telemetry[TKey]>>[0];
diff --git a/packages/eve/src/harness/ai-sdk-telemetry.test.ts b/packages/eve/src/instrumentation/ai-sdk-telemetry.test.ts
similarity index 99%
rename from packages/eve/src/harness/ai-sdk-telemetry.test.ts
rename to packages/eve/src/instrumentation/ai-sdk-telemetry.test.ts
index 3eccc9e09..e99ea1698 100644
--- a/packages/eve/src/harness/ai-sdk-telemetry.test.ts
+++ b/packages/eve/src/instrumentation/ai-sdk-telemetry.test.ts
@@ -16,7 +16,7 @@ import {
ensureOtelIntegration,
getRegisteredTelemetryIntegrations,
telemetryWithoutErrorContent,
-} from "#harness/ai-sdk-telemetry.js";
+} from "#instrumentation/ai-sdk-telemetry.js";
describe("getRegisteredTelemetryIntegrations", () => {
const original = globalThis.AI_SDK_TELEMETRY_INTEGRATIONS;
diff --git a/packages/eve/src/harness/ai-sdk-telemetry.ts b/packages/eve/src/instrumentation/ai-sdk-telemetry.ts
similarity index 100%
rename from packages/eve/src/harness/ai-sdk-telemetry.ts
rename to packages/eve/src/instrumentation/ai-sdk-telemetry.ts
diff --git a/packages/eve/src/harness/channel-delivery-instrumentation.test.ts b/packages/eve/src/instrumentation/channel-delivery.test.ts
similarity index 78%
rename from packages/eve/src/harness/channel-delivery-instrumentation.test.ts
rename to packages/eve/src/instrumentation/channel-delivery.test.ts
index 67f34b946..2454f2af0 100644
--- a/packages/eve/src/harness/channel-delivery-instrumentation.test.ts
+++ b/packages/eve/src/instrumentation/channel-delivery.test.ts
@@ -1,16 +1,29 @@
import { describe, expect, it } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
-import {
- ChannelInstrumentationKey,
- ParentTraceContextKey,
- SessionTraceSeedKey,
-} from "#context/keys.js";
-import { instrumentChannelDelivery } from "#harness/channel-delivery-instrumentation.js";
+import { ChannelInstrumentationKey, ParentTraceContextKey } from "#context/keys.js";
import {
createInstrumentationHooks,
type InstrumentationEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import {
+ bindInstrumentationRuntime,
+ type InstrumentationRuntime,
+} from "#instrumentation/runtime.js";
+
+function bindHooks(hooks: InstrumentationRuntime["hooks"], ctx: ContextContainer) {
+ return bindInstrumentationRuntime(
+ {
+ forceFlush: async () => undefined,
+ hooks,
+ otelSettings: undefined,
+ runInContext: (_operation, execute) => execute(),
+ shutdown: async () => undefined,
+ },
+ ctx,
+ { rootSessionId: "session-1", sessionId: "session-1" },
+ );
+}
describe("channel delivery instrumentation", () => {
it("projects only known content and redacts it from metadata providers", async () => {
@@ -47,9 +60,10 @@ describe("channel delivery instrumentation", () => {
metadata: { audience: "public" },
});
ctx.set(ParentTraceContextKey, parentTraceContext);
+ const instrumentation = bindHooks(hooks, ctx);
await contextStorage.run(ctx, async () => {
- await instrumentChannelDelivery({
+ await instrumentation?.instrumentChannelDelivery({
ctx,
delivery: {
deliveryMetadata: [
@@ -63,15 +77,13 @@ describe("channel delivery instrumentation", () => {
kind: "deliver",
payloads: [{ interaction: { secret: true }, message: "hello" }],
},
- hooks,
rootSessionId: "session-1",
sequence: 0,
sessionId: "session-1",
turnId: "turn_0",
});
- await instrumentChannelDelivery({
+ await instrumentation?.instrumentChannelDelivery({
ctx,
- hooks,
includeTurn: true,
outcome: "completed",
});
@@ -102,15 +114,9 @@ describe("channel delivery instrumentation", () => {
kind: "channel:slack",
metadata: { audience: "private" },
});
- ctx.set(SessionTraceSeedKey, {
- decision: { action: "record", recordInputs: true, recordOutputs: true },
- spanId: "2".repeat(16),
- traceFlags: 1,
- traceId: "1".repeat(32),
- });
-
+ const instrumentation = bindHooks(hooks, ctx);
await contextStorage.run(ctx, () =>
- instrumentChannelDelivery({
+ instrumentation?.instrumentChannelDelivery({
ctx,
delivery: {
deliveryMetadata: [
@@ -124,7 +130,6 @@ describe("channel delivery instrumentation", () => {
kind: "deliver",
payloads: [{ message: "secret" }],
},
- hooks,
rootSessionId: "session-1",
sequence: 0,
sessionId: "session-1",
diff --git a/packages/eve/src/harness/channel-delivery-instrumentation.ts b/packages/eve/src/instrumentation/channel-delivery.ts
similarity index 85%
rename from packages/eve/src/harness/channel-delivery-instrumentation.ts
rename to packages/eve/src/instrumentation/channel-delivery.ts
index 4de3835ab..ea02180de 100644
--- a/packages/eve/src/harness/channel-delivery-instrumentation.ts
+++ b/packages/eve/src/instrumentation/channel-delivery.ts
@@ -11,11 +11,11 @@ import type {
InstrumentationChannelDeliveryOutcome,
InstrumentationChannelDeliveryTerminalEvent,
InstrumentationHooks,
-} from "#harness/instrumentation/lifecycle.js";
-import { channelDeliveryIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import { channelDeliveryIdempotencyKey } from "#instrumentation/lifecycle.js";
import { normalizeChannelAudience } from "#shared/channel-audience.js";
-interface ChannelDeliveryStartInstrumentation {
+export interface ChannelDeliveryStartInstrumentation {
readonly agentName?: string;
readonly ctx: AlsContext;
readonly delivery: DeliverHookPayload;
@@ -26,7 +26,7 @@ interface ChannelDeliveryStartInstrumentation {
readonly turnId: string;
}
-interface ChannelDeliveryTerminalInstrumentation {
+export interface ChannelDeliveryTerminalInstrumentation {
readonly ctx: AlsContext;
readonly error?: unknown;
readonly errorCode?: string;
@@ -35,12 +35,6 @@ interface ChannelDeliveryTerminalInstrumentation {
readonly outcome: InstrumentationChannelDeliveryOutcome;
}
-export function instrumentChannelDelivery(
- input: ChannelDeliveryStartInstrumentation,
-): Promise<void>;
-export function instrumentChannelDelivery(
- input: ChannelDeliveryTerminalInstrumentation,
-): Promise<void>;
export async function instrumentChannelDelivery(
input: ChannelDeliveryStartInstrumentation | ChannelDeliveryTerminalInstrumentation,
): Promise<void> {
@@ -131,11 +125,3 @@ function projectDeliveryInput(payload: DeliverPayload) {
}
return projected;
}
-
-export function channelDeliveryErrorCode(error: unknown): string {
- if (typeof error === "object" && error !== null && "code" in error) {
- const code = (error as { readonly code?: unknown }).code;
- if (typeof code === "string" && code.length > 0) return code;
- }
- return "CHANNEL_DELIVERY_FAILED";
-}
diff --git a/packages/eve/src/instrumentation/config.test.ts b/packages/eve/src/instrumentation/config.test.ts
new file mode 100644
index 000000000..3d71c9819
--- /dev/null
+++ b/packages/eve/src/instrumentation/config.test.ts
@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { InstrumentationSetupContext } from "#public/instrumentation/index.js";
+
+const RUNTIME_GLOBAL_KEY = Symbol.for("eve.instrumentation-runtime");
+
+beforeEach(() => {
+ delete (globalThis as Record<symbol, unknown>)[RUNTIME_GLOBAL_KEY];
+});
+
+describe("instrumentation config runtime registration", () => {
+ it("exposes a resolver registered in one module evaluation through the shared runtime", async () => {
+ vi.resetModules();
+ const moduleA = await import("#instrumentation/config.js");
+ const resolver = vi.fn(() => ({ runtimeContext: { team: "platform" } }));
+ await moduleA.registerInstrumentationConfig(
+ { events: { "step.started": resolver } },
+ { agentName: "test-agent" },
+ );
+
+ vi.resetModules();
+ const moduleB = await import("#instrumentation/runtime.js");
+
+ expect(
+ moduleB.getInstrumentationRuntime()?.stepStartedRuntimeContextResolver?.({} as never),
+ ).toEqual({ runtimeContext: { team: "platform" } });
+ expect(resolver).toHaveBeenCalledOnce();
+ });
+
+ it("replaces the resolver when the authored config reloads", async () => {
+ const { registerInstrumentationConfig } = await import("#instrumentation/config.js");
+ const { getInstrumentationRuntime } = await import("#instrumentation/runtime.js");
+ const first = vi.fn(() => ({ runtimeContext: { version: 1 } }));
+ const second = vi.fn(() => ({ runtimeContext: { version: 2 } }));
+
+ await registerInstrumentationConfig(
+ { events: { "step.started": first } },
+ { agentName: "test-agent" },
+ );
+ await registerInstrumentationConfig(
+ { events: { "step.started": second } },
+ { agentName: "test-agent" },
+ );
+
+ expect(getInstrumentationRuntime()?.stepStartedRuntimeContextResolver?.({} as never)).toEqual({
+ runtimeContext: { version: 2 },
+ });
+ expect(first).not.toHaveBeenCalled();
+ expect(second).toHaveBeenCalledOnce();
+ });
+
+ it("installs harness telemetry settings on the instrumentation runtime", async () => {
+ const { registerInstrumentationConfig } = await import("#instrumentation/config.js");
+ const { getInstrumentationRuntime } = await import("#instrumentation/runtime.js");
+
+ await registerInstrumentationConfig(
+ {
+ functionId: "weather",
+ recordInputs: true,
+ recordOutputs: false,
+ traceChannelRequests: true,
+ },
+ { agentName: "test-agent" },
+ );
+
+ expect(getInstrumentationRuntime()?.otelSettings).toEqual({
+ functionId: "weather",
+ recordInputs: true,
+ recordOutputs: false,
+ traceChannelRequests: true,
+ });
+ });
+
+ it("disables input and output recording by default", async () => {
+ const { registerInstrumentationConfig } = await import("#instrumentation/config.js");
+ const { getInstrumentationRuntime } = await import("#instrumentation/runtime.js");
+
+ await registerInstrumentationConfig({}, { agentName: "test-agent" });
+
+ expect(getInstrumentationRuntime()?.otelSettings).toEqual({
+ functionId: undefined,
+ recordInputs: false,
+ recordOutputs: false,
+ traceChannelRequests: false,
+ });
+ });
+
+ it("awaits the setup callback with the resolved context", async () => {
+ vi.resetModules();
+ const { registerInstrumentationConfig } = await import("#instrumentation/config.js");
+
+ const contexts: InstrumentationSetupContext[] = [];
+ await registerInstrumentationConfig(
+ {
+ setup: (context) => {
+ contexts.push(context);
+ },
+ },
+ { agentName: "weather-agent" },
+ );
+
+ expect(contexts).toHaveLength(1);
+ expect(contexts[0]?.agentName).toBe("weather-agent");
+ expect(contexts[0]?.environment).toMatch(/^(development|production)$/);
+ expect(contexts[0]?.frameworkVersion).toEqual(expect.any(String));
+ });
+});
diff --git a/packages/eve/src/instrumentation/config.ts b/packages/eve/src/instrumentation/config.ts
new file mode 100644
index 000000000..afdd8ac72
--- /dev/null
+++ b/packages/eve/src/instrumentation/config.ts
@@ -0,0 +1,35 @@
+import { createInstrumentationHooks } from "#instrumentation/lifecycle.js";
+import { registerInstrumentationRuntime } from "#instrumentation/runtime.js";
+import { createInstrumentationSetupContext } from "#instrumentation/setup-context.js";
+import type { InstrumentationDefinition } from "#public/instrumentation/index.js";
+
+/**
+ * Registers the authored instrumentation config and awaits its `setup`
+ * callback.
+ *
+ * Called once by the generated instrumentation Nitro plugin at server
+ * startup. Subsequent calls overwrite the previous value.
+ *
+ * @internal — not part of the public API.
+ */
+export async function registerInstrumentationConfig(
+ config: InstrumentationDefinition,
+ input: { readonly agentName: string },
+): Promise<void> {
+ // This legacy layout leaves `registerOTel` to `setup`, so install only the
+ // runtime projection consumed by the harness.
+ const runtime = registerInstrumentationRuntime({
+ forceFlush: async () => undefined,
+ hooks: createInstrumentationHooks([]),
+ otelSettings: {
+ functionId: config.functionId,
+ recordInputs: config.recordInputs === true,
+ recordOutputs: config.recordOutputs === true,
+ traceChannelRequests: config.traceChannelRequests === true,
+ },
+ runInContext: (_operation, execute) => execute(),
+ shutdown: async () => undefined,
+ });
+ runtime.stepStartedRuntimeContextResolver = (event) => config.events?.["step.started"]?.(event);
+ await config.setup?.(createInstrumentationSetupContext(input.agentName));
+}
diff --git a/packages/eve/src/harness/instrumentation/content-policy.test.ts b/packages/eve/src/instrumentation/content-policy.test.ts
similarity index 92%
rename from packages/eve/src/harness/instrumentation/content-policy.test.ts
rename to packages/eve/src/instrumentation/content-policy.test.ts
index e266e7db9..5fefbfd24 100644
--- a/packages/eve/src/harness/instrumentation/content-policy.test.ts
+++ b/packages/eve/src/instrumentation/content-policy.test.ts
@@ -1,7 +1,7 @@
import { describe, expect, it } from "vitest";
-import { instrumentationEventForTraceDecision } from "#harness/instrumentation/content-policy.js";
-import type { InstrumentationEvent } from "#harness/instrumentation/lifecycle.js";
+import { instrumentationEventForTraceDecision } from "#instrumentation/content-policy.js";
+import type { InstrumentationEvent } from "#instrumentation/lifecycle.js";
const event: InstrumentationEvent = {
idempotencyKey: "model:session-1:turn-1:0:0:0",
diff --git a/packages/eve/src/harness/instrumentation/content-policy.ts b/packages/eve/src/instrumentation/content-policy.ts
similarity index 85%
rename from packages/eve/src/harness/instrumentation/content-policy.ts
rename to packages/eve/src/instrumentation/content-policy.ts
index 4f55c2b19..33d19eba7 100644
--- a/packages/eve/src/harness/instrumentation/content-policy.ts
+++ b/packages/eve/src/instrumentation/content-policy.ts
@@ -1,8 +1,8 @@
import {
withInstrumentationDecision,
withoutInstrumentationContent,
-} from "#harness/instrumentation/content.js";
-import type { InstrumentationEvent } from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/content.js";
+import type { InstrumentationEvent } from "#instrumentation/lifecycle.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import { applyAudienceCeiling } from "#shared/instrumentation-content.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
diff --git a/packages/eve/src/harness/instrumentation/content.test.ts b/packages/eve/src/instrumentation/content.test.ts
similarity index 95%
rename from packages/eve/src/harness/instrumentation/content.test.ts
rename to packages/eve/src/instrumentation/content.test.ts
index da5cb44b9..5e6975ebe 100644
--- a/packages/eve/src/harness/instrumentation/content.test.ts
+++ b/packages/eve/src/instrumentation/content.test.ts
@@ -1,10 +1,10 @@
import { describe, expect, it } from "vitest";
-import { withInstrumentationDecision } from "#harness/instrumentation/content.js";
+import { withInstrumentationDecision } from "#instrumentation/content.js";
import type {
InstrumentationInputRequestedEvent,
InstrumentationInputResolvedEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
const scope = {
attemptId: "attempt-1",
diff --git a/packages/eve/src/harness/instrumentation/content.ts b/packages/eve/src/instrumentation/content.ts
similarity index 97%
rename from packages/eve/src/harness/instrumentation/content.ts
rename to packages/eve/src/instrumentation/content.ts
index 284fedd29..c6611cfe7 100644
--- a/packages/eve/src/harness/instrumentation/content.ts
+++ b/packages/eve/src/instrumentation/content.ts
@@ -1,4 +1,4 @@
-import type { InstrumentationEvent } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationEvent } from "#instrumentation/lifecycle.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
/** Returns an immutable event projection with conversation content removed. */
diff --git a/packages/eve/src/harness/instrumentation/dispatch.ts b/packages/eve/src/instrumentation/dispatch.ts
similarity index 98%
rename from packages/eve/src/harness/instrumentation/dispatch.ts
rename to packages/eve/src/instrumentation/dispatch.ts
index c85a3d129..ac558ba86 100644
--- a/packages/eve/src/harness/instrumentation/dispatch.ts
+++ b/packages/eve/src/instrumentation/dispatch.ts
@@ -7,8 +7,8 @@ import {
releaseAllInstrumentationTurnState,
takeInstrumentationActionScopes,
type InstrumentationStateOwner,
-} from "#harness/instrumentation/state.js";
-import { withoutInstrumentationContent } from "#harness/instrumentation/content.js";
+} from "#instrumentation/state.js";
+import { withoutInstrumentationContent } from "#instrumentation/content.js";
import { createLogger, formatError } from "#internal/logging.js";
import type {
@@ -24,7 +24,7 @@ import type {
InstrumentationSessionSettledEvent,
InstrumentationTurnFailedEvent,
InstrumentationTurnSettledEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
const log = createLogger("harness.instrumentation-dispatch");
const DEFAULT_HANDLER_TIMEOUT_MS = 5_000;
diff --git a/packages/eve/src/harness/instrumentation/lifecycle.test.ts b/packages/eve/src/instrumentation/lifecycle.test.ts
similarity index 99%
rename from packages/eve/src/harness/instrumentation/lifecycle.test.ts
rename to packages/eve/src/instrumentation/lifecycle.test.ts
index cec7f8608..20b3e8523 100644
--- a/packages/eve/src/harness/instrumentation/lifecycle.test.ts
+++ b/packages/eve/src/instrumentation/lifecycle.test.ts
@@ -15,12 +15,12 @@ import {
type InstrumentationModelCallStartedEvent,
type InstrumentationProviderDefinition,
type InstrumentationToolCallCompletedEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import {
findInstrumentationActionScopeForCall,
instrumentationStateSlot,
rememberInstrumentationActionScope,
-} from "#harness/instrumentation/state.js";
+} from "#instrumentation/state.js";
const { logWarn } = vi.hoisted(() => ({ logWarn: vi.fn() }));
vi.mock("#internal/logging.js", () => ({
diff --git a/packages/eve/src/harness/instrumentation/lifecycle.ts b/packages/eve/src/instrumentation/lifecycle.ts
similarity index 99%
rename from packages/eve/src/harness/instrumentation/lifecycle.ts
rename to packages/eve/src/instrumentation/lifecycle.ts
index e7901942d..2bfe5c73f 100644
--- a/packages/eve/src/harness/instrumentation/lifecycle.ts
+++ b/packages/eve/src/instrumentation/lifecycle.ts
@@ -1,5 +1,5 @@
-import { createInstrumentationDispatcher } from "#harness/instrumentation/dispatch.js";
-import type { InstrumentationStateSlot } from "#harness/instrumentation/state.js";
+import { createInstrumentationDispatcher } from "#instrumentation/dispatch.js";
+import type { InstrumentationStateSlot } from "#instrumentation/state.js";
import type { RuntimeTraceContext } from "#protocol/message.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
diff --git a/packages/eve/src/harness/instrumentation/native-events.test.ts b/packages/eve/src/instrumentation/native-events.test.ts
similarity index 98%
rename from packages/eve/src/harness/instrumentation/native-events.test.ts
rename to packages/eve/src/instrumentation/native-events.test.ts
index 86dbdff12..6d1a30948 100644
--- a/packages/eve/src/harness/instrumentation/native-events.test.ts
+++ b/packages/eve/src/instrumentation/native-events.test.ts
@@ -19,17 +19,14 @@ import {
import {
createInstrumentationHandleEvent,
publishInputResolutions,
-} from "#harness/instrumentation/native-events.js";
-import type {
- InstrumentationEvent,
- InstrumentationHooks,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/native-events.js";
+import type { InstrumentationEvent, InstrumentationHooks } from "#instrumentation/lifecycle.js";
import {
actionIdempotencyKey,
inputIdempotencyKey,
sessionIdempotencyKey,
turnIdempotencyKey,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";
describe("createInstrumentationHandleEvent", () => {
diff --git a/packages/eve/src/harness/instrumentation/native-events.ts b/packages/eve/src/instrumentation/native-events.ts
similarity index 98%
rename from packages/eve/src/harness/instrumentation/native-events.ts
rename to packages/eve/src/instrumentation/native-events.ts
index 3a5df1c9d..2be1fcb0d 100644
--- a/packages/eve/src/harness/instrumentation/native-events.ts
+++ b/packages/eve/src/instrumentation/native-events.ts
@@ -1,6 +1,6 @@
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { contextStorage } from "#context/container.js";
-import { instrumentChannelDelivery } from "#harness/channel-delivery-instrumentation.js";
+import { instrumentChannelDelivery } from "#instrumentation/channel-delivery.js";
import type {
InstrumentationActionFailedEvent,
InstrumentationActionStartedEvent,
@@ -12,19 +12,19 @@ import type {
InstrumentationPointEvent,
InstrumentationTraceContext,
InstrumentationUsage,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import {
actionIdempotencyKey,
inputIdempotencyKey,
sessionIdempotencyKey,
turnIdempotencyKey,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import {
rememberInstrumentationActionScope,
rememberInstrumentationInputScope,
takeInstrumentationActionScopeForCall,
takeInstrumentationInputScope,
-} from "#harness/instrumentation/state.js";
+} from "#instrumentation/state.js";
import type { ResolvedInputBatch } from "#harness/input-requests.js";
import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";
import type { HandleEventFn } from "#harness/types.js";
diff --git a/packages/eve/src/harness/parent-lineage.test.ts b/packages/eve/src/instrumentation/parent-lineage.test.ts
similarity index 93%
rename from packages/eve/src/harness/parent-lineage.test.ts
rename to packages/eve/src/instrumentation/parent-lineage.test.ts
index 9b89f697e..bd353eb76 100644
--- a/packages/eve/src/harness/parent-lineage.test.ts
+++ b/packages/eve/src/instrumentation/parent-lineage.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import { resolveParentLineage } from "#harness/parent-lineage.js";
+import { resolveParentLineage } from "#instrumentation/parent-lineage.js";
const parent = {
callId: "call-1",
diff --git a/packages/eve/src/harness/parent-lineage.ts b/packages/eve/src/instrumentation/parent-lineage.ts
similarity index 90%
rename from packages/eve/src/harness/parent-lineage.ts
rename to packages/eve/src/instrumentation/parent-lineage.ts
index 95724ea76..dd651e955 100644
--- a/packages/eve/src/harness/parent-lineage.ts
+++ b/packages/eve/src/instrumentation/parent-lineage.ts
@@ -1,6 +1,6 @@
import type { SessionParent } from "#channel/types.js";
import { isSubagentAdapterState } from "#execution/subagent-adapter-state.js";
-import type { InstrumentationParentLineage } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationParentLineage } from "#instrumentation/lifecycle.js";
/**
* Resolves the dispatch that created the running session, if any. Dispatch
diff --git a/packages/eve/src/harness/prepare-trace-context.test.ts b/packages/eve/src/instrumentation/prepare-trace-context.test.ts
similarity index 77%
rename from packages/eve/src/harness/prepare-trace-context.test.ts
rename to packages/eve/src/instrumentation/prepare-trace-context.test.ts
index 0c46496c8..f29c00557 100644
--- a/packages/eve/src/harness/prepare-trace-context.test.ts
+++ b/packages/eve/src/instrumentation/prepare-trace-context.test.ts
@@ -2,8 +2,7 @@ import { describe, expect, it } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionTraceSeedKey } from "#context/keys.js";
-import { createInstrumentationHooks } from "#harness/instrumentation/lifecycle.js";
-import { prepareTurnTraceContext } from "#harness/prepare-trace-context.js";
+import { prepareTurnTraceContext } from "#instrumentation/prepare-trace-context.js";
describe("prepareTurnTraceContext", () => {
it("backfills a persisted trace decision for pre-seed workflow contexts", async () => {
@@ -18,9 +17,7 @@ describe("prepareTurnTraceContext", () => {
await contextStorage.run(context, () =>
prepareTurnTraceContext({
instrumentation: {
- hooks: createInstrumentationHooks([]),
prepareSessionTrace: async () => seed,
- runInContext: (_operation, execute) => execute(),
},
rootSessionId: "session-1",
sequence: 0,
diff --git a/packages/eve/src/harness/prepare-trace-context.ts b/packages/eve/src/instrumentation/prepare-trace-context.ts
similarity index 79%
rename from packages/eve/src/harness/prepare-trace-context.ts
rename to packages/eve/src/instrumentation/prepare-trace-context.ts
index 7d8f93b2e..ec8818d20 100644
--- a/packages/eve/src/harness/prepare-trace-context.ts
+++ b/packages/eve/src/instrumentation/prepare-trace-context.ts
@@ -3,21 +3,29 @@ import { contextStorage } from "#context/container.js";
import type { RuntimeTraceContext } from "#protocol/message.js";
import type {
InstrumentationParentLineage,
+ InstrumentationSessionStartedEvent,
InstrumentationTraceSeed,
-} from "#harness/instrumentation/lifecycle.js";
-import { sessionIdempotencyKey, turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
-import type { HarnessInstrumentation } from "#harness/instrumentation/runtime.js";
+ InstrumentationTurnStartedEvent,
+} from "#instrumentation/lifecycle.js";
+import { sessionIdempotencyKey, turnIdempotencyKey } from "#instrumentation/lifecycle.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import { SessionTraceSeedKey, type SessionTraceSeed } from "#context/keys.js";
const log = createLogger("harness.prepare-trace-context");
/** Prepares native session/turn tracing before their durable stream events. */
-export async function prepareTurnTraceContext(input: {
+export interface PrepareTurnTraceContextInput {
readonly agentName?: string;
readonly channelAudience?: ChannelAudience;
readonly channelType?: string;
- readonly instrumentation?: HarnessInstrumentation;
+ readonly instrumentation?: {
+ readonly prepareSessionTrace?: (
+ event: InstrumentationSessionStartedEvent,
+ ) => Promise<InstrumentationTraceSeed>;
+ readonly prepareTurnTrace?: (
+ event: InstrumentationTurnStartedEvent,
+ ) => Promise<InstrumentationTraceSeed>;
+ };
readonly parentLineage?: InstrumentationParentLineage;
readonly parentTraceContext?: InstrumentationTraceSeed;
readonly rootSessionId: string;
@@ -27,7 +35,11 @@ export async function prepareTurnTraceContext(input: {
readonly traceContext?: RuntimeTraceContext;
readonly traceSeed?: SessionTraceSeed;
readonly turnId: string;
-}): Promise<RuntimeTraceContext | undefined> {
+}
+
+export async function prepareTurnTraceContext(
+ input: PrepareTurnTraceContextInput,
+): Promise<RuntimeTraceContext | undefined> {
let prepared: InstrumentationTraceSeed | undefined;
if (!input.sessionStarted && input.instrumentation?.prepareSessionTrace !== undefined) {
diff --git a/packages/eve/src/instrumentation/provider.ts b/packages/eve/src/instrumentation/provider.ts
index 7c9bbd0d0..161d483de 100644
--- a/packages/eve/src/instrumentation/provider.ts
+++ b/packages/eve/src/instrumentation/provider.ts
@@ -9,10 +9,7 @@
// runtime. The event shapes are eve's own vocabulary; deriving the handler map
// from the union below is what keeps the public contract from drifting away
// from the bus that feeds it.
-import type {
- InstrumentationCapture,
- InstrumentationEvent,
-} from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationCapture, InstrumentationEvent } from "#instrumentation/lifecycle.js";
import type { JsonValue } from "#shared/json.js";
export type { JsonValue } from "#shared/json.js";
@@ -65,7 +62,7 @@ export type {
InstrumentationTurnStartedEvent,
InstrumentationTurnTerminalEvent,
InstrumentationUsage,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
/**
* Marks a value as having come from `defineInstrumentation` or a built-in
diff --git a/packages/eve/src/harness/instrumentation/providers-local.scenario.test.ts b/packages/eve/src/instrumentation/providers-local.scenario.test.ts
similarity index 96%
rename from packages/eve/src/harness/instrumentation/providers-local.scenario.test.ts
rename to packages/eve/src/instrumentation/providers-local.scenario.test.ts
index f8cdb6ee6..a1be9eb5e 100644
--- a/packages/eve/src/harness/instrumentation/providers-local.scenario.test.ts
+++ b/packages/eve/src/instrumentation/providers-local.scenario.test.ts
@@ -9,7 +9,7 @@ import {
getInstrumentationProviders,
registerInstrumentationProvider,
seedInstrumentationProviders,
-} from "#harness/instrumentation/providers.js";
+} from "#instrumentation/providers.js";
import { DEVELOPMENT_WORKER_APP_ROOT_ENV } from "#internal/workflow/development-world-protocol.js";
import { otelIntegration } from "#public/instrumentation/otel.js";
diff --git a/packages/eve/src/harness/instrumentation/providers-otel-policy.test.ts b/packages/eve/src/instrumentation/providers-otel-policy.test.ts
similarity index 98%
rename from packages/eve/src/harness/instrumentation/providers-otel-policy.test.ts
rename to packages/eve/src/instrumentation/providers-otel-policy.test.ts
index f1d693753..a9a2c8738 100644
--- a/packages/eve/src/harness/instrumentation/providers-otel-policy.test.ts
+++ b/packages/eve/src/instrumentation/providers-otel-policy.test.ts
@@ -4,7 +4,7 @@ import { ContextContainer, contextStorage } from "#context/container.js";
import {
finalizeInstrumentationProviders,
registerInstrumentationProvider,
-} from "#harness/instrumentation/providers.js";
+} from "#instrumentation/providers.js";
import { defineInstrumentation } from "#public/instrumentation/index.js";
import { otel, type TracePolicyDecision } from "#public/instrumentation/otel.js";
diff --git a/packages/eve/src/harness/instrumentation/providers-production.scenario.test.ts b/packages/eve/src/instrumentation/providers-production.scenario.test.ts
similarity index 95%
rename from packages/eve/src/harness/instrumentation/providers-production.scenario.test.ts
rename to packages/eve/src/instrumentation/providers-production.scenario.test.ts
index a64c8043e..dd36f8c2f 100644
--- a/packages/eve/src/harness/instrumentation/providers-production.scenario.test.ts
+++ b/packages/eve/src/instrumentation/providers-production.scenario.test.ts
@@ -5,7 +5,7 @@ import {
getInstrumentationProviders,
registerInstrumentationProvider,
seedInstrumentationProviders,
-} from "#harness/instrumentation/providers.js";
+} from "#instrumentation/providers.js";
import { localTraces } from "#public/instrumentation/otel.js";
afterEach(() => {
diff --git a/packages/eve/src/harness/instrumentation/providers.integration.test.ts b/packages/eve/src/instrumentation/providers.integration.test.ts
similarity index 95%
rename from packages/eve/src/harness/instrumentation/providers.integration.test.ts
rename to packages/eve/src/instrumentation/providers.integration.test.ts
index fc2741f0d..63c78600c 100644
--- a/packages/eve/src/harness/instrumentation/providers.integration.test.ts
+++ b/packages/eve/src/instrumentation/providers.integration.test.ts
@@ -1,10 +1,10 @@
import { beforeEach, describe, expect, it } from "vitest";
-import { turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+import { turnIdempotencyKey } from "#instrumentation/lifecycle.js";
import {
finalizeInstrumentationProviders,
registerInstrumentationProvider,
-} from "#harness/instrumentation/providers.js";
+} from "#instrumentation/providers.js";
import { defineInstrumentation } from "#public/instrumentation/index.js";
const REGISTRY_GLOBAL_KEY = Symbol.for("eve.harness-instrumentation-providers");
diff --git a/packages/eve/src/harness/instrumentation/providers.test.ts b/packages/eve/src/instrumentation/providers.test.ts
similarity index 98%
rename from packages/eve/src/harness/instrumentation/providers.test.ts
rename to packages/eve/src/instrumentation/providers.test.ts
index 80a4964fb..946b97f75 100644
--- a/packages/eve/src/harness/instrumentation/providers.test.ts
+++ b/packages/eve/src/instrumentation/providers.test.ts
@@ -1,6 +1,6 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
-import { turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+import { turnIdempotencyKey } from "#instrumentation/lifecycle.js";
import {
EVE_EVALUATION_ENV_FLAG,
EVE_EVALUATION_RUN_ID_ENV,
@@ -11,7 +11,7 @@ import {
registerInstrumentationProvider,
seedInstrumentationProviders,
shutdownInstrumentationProviders,
-} from "#harness/instrumentation/providers.js";
+} from "#instrumentation/providers.js";
import { DEVELOPMENT_WORKER_APP_ROOT_ENV } from "#internal/workflow/development-world-protocol.js";
import { defineInstrumentation } from "#public/instrumentation/index.js";
import { agentRuns, localTraces, otelIntegration } from "#public/instrumentation/otel.js";
diff --git a/packages/eve/src/harness/instrumentation/providers.ts b/packages/eve/src/instrumentation/providers.ts
similarity index 96%
rename from packages/eve/src/harness/instrumentation/providers.ts
rename to packages/eve/src/instrumentation/providers.ts
index 73b119e5c..64f752079 100644
--- a/packages/eve/src/harness/instrumentation/providers.ts
+++ b/packages/eve/src/instrumentation/providers.ts
@@ -1,9 +1,9 @@
-import type { InstrumentationProviderDefinition } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationProviderDefinition } from "#instrumentation/lifecycle.js";
import {
getInstrumentationRuntime,
type InstrumentationRuntime,
-} from "#harness/instrumentation/runtime.js";
-import { createInstrumentationSetupContext } from "#harness/instrumentation/setup-context.js";
+} from "#instrumentation/runtime.js";
+import { createInstrumentationSetupContext } from "#instrumentation/setup-context.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
import { DEVELOPMENT_WORKER_APP_ROOT_ENV } from "#internal/workflow/development-world-protocol.js";
import { agentRuns, localTraces } from "#public/instrumentation/otel.js";
diff --git a/packages/eve/src/harness/instrumentation/runtime-context.test.ts b/packages/eve/src/instrumentation/runtime-context.test.ts
similarity index 69%
rename from packages/eve/src/harness/instrumentation/runtime-context.test.ts
rename to packages/eve/src/instrumentation/runtime-context.test.ts
index c7547830a..6c20d14a8 100644
--- a/packages/eve/src/harness/instrumentation/runtime-context.test.ts
+++ b/packages/eve/src/instrumentation/runtime-context.test.ts
@@ -7,7 +7,7 @@ import type { HarnessEmissionState } from "#harness/emission.js";
import {
buildTelemetryRuntimeContext,
type BuildTelemetryRuntimeContextInput,
-} from "#harness/instrumentation/runtime-context.js";
+} from "#instrumentation/runtime-context.js";
import type { RuntimeContextResolver } from "#tracing/otel-declaration.js";
import type { HarnessSession } from "#harness/types.js";
import type {
@@ -50,19 +50,20 @@ function build(
overrides: Partial<BuildTelemetryRuntimeContextInput> = {},
): Record<string, unknown> | undefined {
return buildTelemetryRuntimeContext({
+ capturesContent: false,
eveVersion: "0.0.0-test",
- authored: { events: {} },
emissionState,
environment: "test",
modelInput: { instructions: undefined, messages },
session,
+ stepStartedResolver: () => undefined,
...overrides,
});
}
describe("buildTelemetryRuntimeContext", () => {
it("returns undefined when no instrumentation is authored", () => {
- expect(build({ authored: undefined })).toBeUndefined();
+ expect(build({ stepStartedResolver: undefined })).toBeUndefined();
});
it("emits framework identifiers when no resolver is configured", () => {
@@ -71,7 +72,7 @@ describe("buildTelemetryRuntimeContext", () => {
it("merges authored step.started runtime context beneath framework keys", () => {
const runtimeContext = build({
- authored: { events: { "step.started": () => ({ runtimeContext: { team: "platform" } }) } },
+ stepStartedResolver: () => ({ runtimeContext: { team: "platform" } }),
});
expect(runtimeContext).toEqual({ ...FRAMEWORK_KEYS, team: "platform" });
@@ -79,19 +80,15 @@ describe("buildTelemetryRuntimeContext", () => {
it("drops reserved eve.* keys from authored runtime context", () => {
const runtimeContext = build({
- authored: {
- events: {
- "step.started": () =>
- ({
- runtimeContext: {
- "eve.session.id": "user-override",
- count: 1,
- nested: { ok: true },
- team: "platform",
- },
- }) as never,
- },
- },
+ stepStartedResolver: () =>
+ ({
+ runtimeContext: {
+ "eve.session.id": "user-override",
+ count: 1,
+ nested: { ok: true },
+ team: "platform",
+ },
+ }) as never,
});
expect(runtimeContext).toEqual({
@@ -104,12 +101,8 @@ describe("buildTelemetryRuntimeContext", () => {
it("keeps framework context authoritative when authored runtime context throws", () => {
const runtimeContext = build({
- authored: {
- events: {
- "step.started": () => {
- throw new Error("runtime context resolver failed");
- },
- },
+ stepStartedResolver: () => {
+ throw new Error("runtime context resolver failed");
},
});
@@ -118,11 +111,7 @@ describe("buildTelemetryRuntimeContext", () => {
it("ignores authored runtime context that returns a Promise", () => {
const runtimeContext = build({
- authored: {
- events: {
- "step.started": () => Promise.resolve({ runtimeContext: { team: "platform" } }) as never,
- },
- },
+ stepStartedResolver: () => Promise.resolve({ runtimeContext: { team: "platform" } }) as never,
});
expect(runtimeContext).toEqual(FRAMEWORK_KEYS);
@@ -130,11 +119,7 @@ describe("buildTelemetryRuntimeContext", () => {
it("ignores authored event results without runtimeContext", () => {
const runtimeContext = build({
- authored: {
- events: {
- "step.started": () => ({}) as never,
- },
- },
+ stepStartedResolver: () => ({}) as never,
});
expect(runtimeContext).toEqual(FRAMEWORK_KEYS);
@@ -145,11 +130,7 @@ describe("buildTelemetryRuntimeContext", () => {
try {
const runtimeContext = build({
- authored: {
- events: {
- "step.started": () => undefined,
- },
- },
+ stepStartedResolver: () => undefined,
});
expect(runtimeContext).toEqual(FRAMEWORK_KEYS);
@@ -168,23 +149,19 @@ describe("buildTelemetryRuntimeContext", () => {
const runtimeContext = contextStorage.run(ctx, () =>
build({
- authored: {
- events: {
- "step.started": (
- input: InstrumentationStepStartedEventInput,
- ): InstrumentationStepStartedEventResult =>
- input.channel.kind === "channel:support"
- ? {
- runtimeContext: {
- "slack.user_id":
- typeof input.channel.metadata["triggeringUserId"] === "string"
- ? input.channel.metadata["triggeringUserId"]
- : "",
- },
- }
- : { runtimeContext: {} },
- },
- },
+ stepStartedResolver: (
+ input: InstrumentationStepStartedEventInput,
+ ): InstrumentationStepStartedEventResult =>
+ input.channel.kind === "channel:support"
+ ? {
+ runtimeContext: {
+ "slack.user_id":
+ typeof input.channel.metadata["triggeringUserId"] === "string"
+ ? input.channel.metadata["triggeringUserId"]
+ : "",
+ },
+ }
+ : { runtimeContext: {} },
}),
);
@@ -198,20 +175,16 @@ describe("buildTelemetryRuntimeContext", () => {
let captured: InstrumentationStepStartedEventInput | undefined;
build({
- authored: {
- events: {
- "step.started": (input: InstrumentationStepStartedEventInput) => {
- captured = input;
- return { runtimeContext: {} };
- },
- },
+ stepStartedResolver: (input: InstrumentationStepStartedEventInput) => {
+ captured = input;
+ return { runtimeContext: {} };
},
});
expect(captured?.modelInput).toEqual({ instructions: undefined, messages: [] });
});
- it("exposes model content to public-audience resolvers", () => {
+ it("exposes model content when worker controls allow it", () => {
const ctx = new ContextContainer();
ctx.set(ChannelInstrumentationKey, {
kind: "channel:public",
@@ -221,13 +194,10 @@ describe("buildTelemetryRuntimeContext", () => {
contextStorage.run(ctx, () =>
build({
- authored: {
- events: {
- "step.started": (input: InstrumentationStepStartedEventInput) => {
- captured = input;
- return { runtimeContext: {} };
- },
- },
+ capturesContent: true,
+ stepStartedResolver: (input: InstrumentationStepStartedEventInput) => {
+ captured = input;
+ return { runtimeContext: {} };
},
}),
);
@@ -253,13 +223,9 @@ describe("buildTelemetryRuntimeContext", () => {
let captured: InstrumentationStepStartedEventInput | undefined;
contextStorage.run(ctx, () =>
build({
- authored: {
- events: {
- "step.started": (input: InstrumentationStepStartedEventInput) => {
- captured = input;
- return { runtimeContext: {} };
- },
- },
+ stepStartedResolver: (input: InstrumentationStepStartedEventInput) => {
+ captured = input;
+ return { runtimeContext: {} };
},
}),
);
@@ -277,14 +243,20 @@ describe("buildTelemetryRuntimeContext", () => {
describe("provider runtimeContext resolvers", () => {
it("emits framework keys when a provider resolver returns undefined", () => {
const resolver: RuntimeContextResolver = () => undefined;
- const runtimeContext = build({ authored: undefined, providerResolvers: [resolver] });
+ const runtimeContext = build({
+ providerResolvers: [resolver],
+ stepStartedResolver: undefined,
+ });
expect(runtimeContext).toEqual(FRAMEWORK_KEYS);
});
it("merges a single provider resolver beneath framework keys", () => {
const resolver: RuntimeContextResolver = () => ({ team: "platform" });
- const runtimeContext = build({ authored: undefined, providerResolvers: [resolver] });
+ const runtimeContext = build({
+ providerResolvers: [resolver],
+ stepStartedResolver: undefined,
+ });
expect(runtimeContext).toEqual({ ...FRAMEWORK_KEYS, team: "platform" });
});
@@ -292,7 +264,10 @@ describe("buildTelemetryRuntimeContext", () => {
it("merges multiple provider resolvers, later ones overriding earlier", () => {
const first: RuntimeContextResolver = () => ({ env: "prod", team: "a" });
const second: RuntimeContextResolver = () => ({ team: "b" });
- const runtimeContext = build({ authored: undefined, providerResolvers: [first, second] });
+ const runtimeContext = build({
+ providerResolvers: [first, second],
+ stepStartedResolver: undefined,
+ });
expect(runtimeContext).toEqual({ ...FRAMEWORK_KEYS, env: "prod", team: "b" });
});
@@ -300,7 +275,10 @@ describe("buildTelemetryRuntimeContext", () => {
it("drops reserved eve.* keys from provider resolver results", () => {
const resolver: RuntimeContextResolver = () =>
({ "eve.session.id": "override", team: "platform" }) as never;
- const runtimeContext = build({ authored: undefined, providerResolvers: [resolver] });
+ const runtimeContext = build({
+ providerResolvers: [resolver],
+ stepStartedResolver: undefined,
+ });
expect(runtimeContext).toEqual({ ...FRAMEWORK_KEYS, team: "platform" });
});
@@ -310,21 +288,26 @@ describe("buildTelemetryRuntimeContext", () => {
throw new Error("boom");
};
const healthy: RuntimeContextResolver = () => ({ team: "platform" });
- const runtimeContext = build({ authored: undefined, providerResolvers: [failing, healthy] });
+ const runtimeContext = build({
+ providerResolvers: [failing, healthy],
+ stepStartedResolver: undefined,
+ });
expect(runtimeContext).toEqual({ ...FRAMEWORK_KEYS, team: "platform" });
});
it("returns undefined when no authored config and no provider resolvers", () => {
- expect(build({ authored: undefined, providerResolvers: undefined })).toBeUndefined();
- expect(build({ authored: undefined, providerResolvers: [] })).toBeUndefined();
+ expect(
+ build({ providerResolvers: undefined, stepStartedResolver: undefined }),
+ ).toBeUndefined();
+ expect(build({ providerResolvers: [], stepStartedResolver: undefined })).toBeUndefined();
});
it("merges provider resolver results alongside the legacy step.started hook", () => {
const resolver: RuntimeContextResolver = () => ({ source: "provider" });
const runtimeContext = build({
- authored: { events: { "step.started": () => ({ runtimeContext: { source: "legacy" } }) } },
providerResolvers: [resolver],
+ stepStartedResolver: () => ({ runtimeContext: { source: "legacy" } }),
});
expect(runtimeContext).toEqual({ ...FRAMEWORK_KEYS, source: "provider" });
diff --git a/packages/eve/src/harness/instrumentation/runtime-context.ts b/packages/eve/src/instrumentation/runtime-context.ts
similarity index 78%
rename from packages/eve/src/harness/instrumentation/runtime-context.ts
rename to packages/eve/src/instrumentation/runtime-context.ts
index 054558b75..a793511e2 100644
--- a/packages/eve/src/harness/instrumentation/runtime-context.ts
+++ b/packages/eve/src/instrumentation/runtime-context.ts
@@ -1,6 +1,10 @@
import type { ModelMessage, SystemModelMessage } from "ai";
-import type { SessionAuthContext } from "#channel/types.js";
+import type {
+ ChannelInstrumentationProjection,
+ SessionAuthContext,
+ SessionParent,
+} from "#channel/types.js";
import type { AlsContext } from "#context/container.js";
import { contextStorage } from "#context/container.js";
import {
@@ -12,7 +16,6 @@ import {
import type { HarnessEmissionState } from "#harness/emission.js";
import type { HarnessSession } from "#harness/types.js";
import type { RuntimeContextResolver } from "#tracing/otel-declaration.js";
-import { shouldCaptureInstrumentationContent } from "#shared/instrumentation-content.js";
import {
normalizeInstrumentationChannelKind,
resolveInstrumentationProjection,
@@ -20,18 +23,18 @@ import {
import { createLogger, formatError } from "#internal/logging.js";
import type {
InstrumentationChannel,
- InstrumentationDefinition,
+ InstrumentationEvents,
InstrumentationRuntimeContext,
InstrumentationStepStartedEventInput,
} from "#public/instrumentation/index.js";
-import { normalizeChannelAudience } from "#shared/channel-audience.js";
import { parseJsonObject, parseJsonValue, type JsonObject, type JsonValue } from "#shared/json.js";
const log = createLogger("harness.instrumentation-runtime-context");
export interface BuildTelemetryRuntimeContextInput {
+ readonly capturesContent: boolean;
+ readonly context?: InstrumentationRuntimeContextSnapshot;
readonly eveVersion: string;
- readonly authored: InstrumentationDefinition | undefined;
readonly emissionState: HarnessEmissionState;
readonly environment: string;
readonly modelInput: {
@@ -40,6 +43,33 @@ export interface BuildTelemetryRuntimeContextInput {
};
readonly providerResolvers?: readonly RuntimeContextResolver[];
readonly session: HarnessSession;
+ readonly stepStartedResolver: InstrumentationEvents["step.started"];
+}
+
+export interface InstrumentationRuntimeContextSnapshot {
+ readonly channel?: ChannelInstrumentationProjection;
+ readonly currentAuth: SessionAuthContext | null;
+ readonly initiatorAuth: SessionAuthContext | null;
+ readonly parent?: SessionParent;
+}
+
+export function snapshotInstrumentationRuntimeContext(
+ context: AlsContext | undefined,
+): InstrumentationRuntimeContextSnapshot {
+ const currentAuth = context?.get(AuthKey) ?? null;
+ return {
+ channel: snapshotForInstrumentation(
+ context?.get(ChannelInstrumentationKey),
+ "channel.instrumentation",
+ ),
+ currentAuth: snapshotForInstrumentation(currentAuth, "session.auth.current") ?? null,
+ initiatorAuth:
+ snapshotForInstrumentation(
+ context?.get(InitiatorAuthKey) ?? currentAuth,
+ "session.auth.initiator",
+ ) ?? null,
+ parent: snapshotForInstrumentation(context?.get(ParentSessionKey), "session.parent"),
+ };
}
/**
@@ -52,17 +82,17 @@ export interface BuildTelemetryRuntimeContextInput {
export function buildTelemetryRuntimeContext(
input: BuildTelemetryRuntimeContextInput,
): Record<string, unknown> | undefined {
- const hasAuthored = input.authored !== undefined;
+ const hasStepStartedResolver = input.stepStartedResolver !== undefined;
const hasProviderResolvers =
input.providerResolvers !== undefined && input.providerResolvers.length > 0;
- if (!hasAuthored && !hasProviderResolvers) {
+ if (!hasStepStartedResolver && !hasProviderResolvers) {
return undefined;
}
const authoredRuntimeContext = resolveStepStartedRuntimeContext(input);
const providerRuntimeContext = resolveProviderRuntimeContext(input);
- const context = contextStorage.getStore();
- const projection = context?.get(ChannelInstrumentationKey);
+ const context = input.context ?? snapshotInstrumentationRuntimeContext(contextStorage.getStore());
+ const projection = context.channel;
return {
...authoredRuntimeContext,
@@ -78,20 +108,20 @@ export function buildTelemetryRuntimeContext(
}
function buildInstrumentationStepStartedInput(
- input: Omit<BuildTelemetryRuntimeContextInput, "authored" | "eveVersion" | "environment">,
+ input: Omit<
+ BuildTelemetryRuntimeContextInput,
+ "eveVersion" | "environment" | "stepStartedResolver"
+ >,
): InstrumentationStepStartedEventInput {
- const context = contextStorage.getStore();
- const projection = context?.get(ChannelInstrumentationKey);
- const capturesContent = shouldCaptureInstrumentationContent(
- normalizeChannelAudience(projection?.metadata.audience),
- );
+ const context = input.context ?? snapshotInstrumentationRuntimeContext(contextStorage.getStore());
+ const projection = context.channel;
return {
channel: {
kind: normalizeInstrumentationChannelKind(projection?.kind),
metadata: snapshotForInstrumentation(projection?.metadata, "channel.metadata") ?? {},
} as InstrumentationChannel,
- modelInput: capturesContent
+ modelInput: input.capturesContent
? (snapshotForInstrumentation(input.modelInput, "modelInput") ?? {
instructions: undefined,
messages: [],
@@ -100,7 +130,7 @@ function buildInstrumentationStepStartedInput(
session: {
auth: projectSessionAuth(context),
id: input.session.sessionId,
- parent: snapshotForInstrumentation(context?.get(ParentSessionKey), "session.parent"),
+ parent: context.parent,
},
step: {
index: input.emissionState.stepIndex,
@@ -136,7 +166,7 @@ function filterAuthoredRuntimeContext(
function resolveStepStartedRuntimeContext(
input: BuildTelemetryRuntimeContextInput,
): InstrumentationRuntimeContext | undefined {
- const resolver = input.authored?.events?.["step.started"];
+ const resolver = input.stepStartedResolver;
if (resolver === undefined) {
return undefined;
}
@@ -214,15 +244,13 @@ function resolveProviderRuntimeContext(
return contributed ? merged : undefined;
}
-function projectSessionAuth(context: AlsContext | undefined): {
+function projectSessionAuth(context: InstrumentationRuntimeContextSnapshot): {
readonly current: SessionAuthContext | null;
readonly initiator: SessionAuthContext | null;
} {
- const current = context?.get(AuthKey) ?? null;
- const initiator = context?.get(InitiatorAuthKey) ?? current;
return {
- current: snapshotForInstrumentation(current, "session.auth.current") ?? null,
- initiator: snapshotForInstrumentation(initiator, "session.auth.initiator") ?? null,
+ current: context.currentAuth,
+ initiator: context.initiatorAuth,
};
}
diff --git a/packages/eve/src/instrumentation/runtime.test.ts b/packages/eve/src/instrumentation/runtime.test.ts
new file mode 100644
index 000000000..6a36d961d
--- /dev/null
+++ b/packages/eve/src/instrumentation/runtime.test.ts
@@ -0,0 +1,314 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ContextContainer, contextStorage } from "#context/container.js";
+import {
+ ChannelInstrumentationKey,
+ OtelTraceEnabledKey,
+ SessionTraceSeedKey,
+} from "#context/keys.js";
+import type { InstrumentationHooks } from "#instrumentation/lifecycle.js";
+import {
+ bindInstrumentationRuntime,
+ bindSessionInstrumentation,
+ registerInstrumentationRuntime,
+ type ExecutionInstrumentation,
+ type InstrumentationRuntime,
+ type InstrumentationStepScope,
+} from "#instrumentation/runtime.js";
+import { ContextAgentTraceStateStore } from "#tracing/agent-trace-context-store.js";
+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";
+
+const boundSession = { rootSessionId: "session-1", sessionId: "session-1" };
+
+function createRuntime(
+ hooks: InstrumentationHooks,
+ tracePolicy?: TraceCapturePolicy,
+): InstrumentationRuntime {
+ return {
+ forceFlush: async () => undefined,
+ hooks,
+ otelSettings: {
+ recordInputs: true,
+ recordOutputs: true,
+ tracePolicy,
+ traceChannelRequests: false,
+ },
+ runInContext: (_operation, execute) => execute(),
+ shutdown: async () => undefined,
+ };
+}
+
+function createContext(audience: "private" | "public" = "public"): ContextContainer {
+ const ctx = new ContextContainer();
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:test",
+ metadata: { audience },
+ });
+ return ctx;
+}
+
+async function readTelemetry(instrumentation: ExecutionInstrumentation | undefined) {
+ return instrumentation?.prepareExecution().runStep(
+ {
+ environment: "test",
+ eveVersion: "0.0.0",
+ hasInput: false,
+ session: { sessionId: "session-1" },
+ },
+ async (scope) => scope.telemetry(),
+ );
+}
+
+beforeEach(() => {
+ delete (globalThis as Record<symbol, unknown>)[Symbol.for("eve.instrumentation-runtime")];
+});
+
+describe("bindInstrumentationRuntime", () => {
+ it("returns no worker controls when no runtime is loaded", () => {
+ expect(
+ bindInstrumentationRuntime(undefined, new ContextContainer(), boundSession),
+ ).toBeUndefined();
+ });
+
+ it("reads the channel audience when the step runs", async () => {
+ const ctx = createContext("public");
+ const instrumentation = bindInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }),
+ ctx,
+ boundSession,
+ );
+
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:test",
+ metadata: { audience: "private" },
+ });
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: false,
+ recordOutputs: false,
+ });
+ });
+
+ it("keeps the step-entry audience for the rest of the step", async () => {
+ const ctx = createContext("private");
+ const instrumentation = bindInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }),
+ ctx,
+ boundSession,
+ );
+
+ const telemetry = await instrumentation?.prepareExecution().runStep(
+ {
+ environment: "test",
+ eveVersion: "0.0.0",
+ hasInput: false,
+ session: { sessionId: "session-1" },
+ },
+ async (scope) => {
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:test",
+ metadata: { audience: "public" },
+ });
+ expect(
+ scope.prepareAttempt({
+ attemptIndex: 0,
+ stepIndex: 0,
+ turnId: "turn-1",
+ })?.scope.channelAudience,
+ ).toBe("private");
+ return scope.telemetry();
+ },
+ );
+
+ expect(telemetry).toMatchObject({ recordInputs: false, recordOutputs: false });
+ });
+
+ it("isolates concurrent step decisions and audiences", async () => {
+ const ctx = createContext("private");
+ const runtime = createRuntime({ capturesContent: true, publish: vi.fn() });
+ runtime.stepStartedRuntimeContextResolver = (event) => ({
+ runtimeContext: { messageCount: event.modelInput.messages.length },
+ });
+ const instrumentation = bindInstrumentationRuntime(
+ runtime,
+ ctx,
+ boundSession,
+ )?.prepareExecution();
+ let releaseFirst!: () => void;
+ const waitForSecond = new Promise<void>((resolve) => {
+ releaseFirst = resolve;
+ });
+ const stepInput = {
+ environment: "test",
+ eveVersion: "0.0.0",
+ hasInput: false,
+ session: { sessionId: "session-1" },
+ };
+ const readScopedState = (scope: InstrumentationStepScope<{ sessionId: string }>) => ({
+ messageCount: scope.resolveRuntimeContext({
+ eveVersion: "0.0.0",
+ emissionState: { sessionStarted: true, sequence: 0, stepIndex: 0, turnId: "turn-1" },
+ environment: "test",
+ modelInput: { instructions: undefined, messages: [{ content: "secret", role: "user" }] },
+ session: { sessionId: "session-1" } as never,
+ })?.["messageCount"],
+ telemetry: scope.telemetry(),
+ });
+
+ const first = instrumentation?.runStep(stepInput, async (scope) => {
+ await waitForSecond;
+ return readScopedState(scope);
+ });
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:test",
+ metadata: { audience: "public" },
+ });
+ const second = instrumentation?.runStep(stepInput, async (scope) => readScopedState(scope));
+ releaseFirst();
+
+ await expect(first).resolves.toMatchObject({
+ messageCount: 0,
+ telemetry: { recordInputs: false, recordOutputs: false },
+ });
+ await expect(second).resolves.toMatchObject({
+ messageCount: 1,
+ telemetry: { recordInputs: true, recordOutputs: true },
+ });
+ });
+
+ it("uses the directional decision from the existing trace seed", async () => {
+ const ctx = createContext();
+ ctx.set(SessionTraceSeedKey, {
+ decision: { action: "record", recordInputs: true, recordOutputs: false },
+ spanId: "1".repeat(16),
+ traceFlags: 1,
+ traceId: "2".repeat(32),
+ });
+ const instrumentation = bindInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }),
+ ctx,
+ boundSession,
+ );
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: true,
+ recordOutputs: false,
+ });
+ });
+
+ it("applies the live audience ceiling to a seeded decision", async () => {
+ const ctx = createContext("private");
+ ctx.set(SessionTraceSeedKey, {
+ decision: { action: "record", recordInputs: true, recordOutputs: true },
+ spanId: "1".repeat(16),
+ traceFlags: 1,
+ traceId: "2".repeat(32),
+ });
+ const instrumentation = bindInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }),
+ ctx,
+ boundSession,
+ );
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: false,
+ recordOutputs: false,
+ });
+ });
+
+ it("derives a legacy seed decision from trace flags", async () => {
+ const policy = vi.fn(() => true);
+ const ctx = createContext();
+ ctx.set(SessionTraceSeedKey, {
+ spanId: "1".repeat(16),
+ traceFlags: 0,
+ traceId: "2".repeat(32),
+ });
+ const instrumentation = bindInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }, policy),
+ ctx,
+ boundSession,
+ );
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: false,
+ recordOutputs: false,
+ });
+ expect(policy).not.toHaveBeenCalled();
+ });
+});
+
+describe("bindSessionInstrumentation", () => {
+ it("uses a persisted decision without migrating the durable context", async () => {
+ const policy = vi.fn(() => true);
+ registerInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }, policy),
+ );
+ const ctx = createContext();
+ contextStorage.run(ctx, () => {
+ new ContextAgentTraceStateStore().setSession("session-1", {
+ context: { spanId: "1".repeat(16), traceFlags: 1, traceId: "2".repeat(32) },
+ decision: { action: "record", recordInputs: false, recordOutputs: true },
+ rootSessionId: "session-1",
+ });
+ });
+
+ const instrumentation = bindSessionInstrumentation({
+ ctx,
+ rootSessionId: "session-1",
+ sessionId: "session-1",
+ });
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: false,
+ recordOutputs: true,
+ });
+ expect(ctx.get(SessionTraceSeedKey)).toBeUndefined();
+ expect(policy).not.toHaveBeenCalled();
+ });
+
+ it("reevaluates policy for seedless steps", async () => {
+ const policy = vi.fn().mockReturnValueOnce(false).mockReturnValueOnce(true);
+ registerInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }, policy),
+ );
+ const ctx = createContext();
+ const instrumentation = bindSessionInstrumentation({
+ ctx,
+ rootSessionId: "session-1",
+ sessionId: "session-1",
+ });
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: false,
+ recordOutputs: false,
+ });
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: true,
+ recordOutputs: true,
+ });
+ expect(policy).toHaveBeenCalledTimes(2);
+ expect(ctx.get(SessionTraceSeedKey)).toBeUndefined();
+ });
+
+ it("does not treat the legacy OTel marker as an admission decision", async () => {
+ const policy = vi.fn(() => true);
+ registerInstrumentationRuntime(
+ createRuntime({ capturesContent: true, publish: vi.fn() }, policy),
+ );
+ const ctx = createContext();
+ ctx.set(OtelTraceEnabledKey, false);
+ const instrumentation = bindSessionInstrumentation({
+ ctx,
+ rootSessionId: "session-1",
+ sessionId: "session-1",
+ });
+
+ expect(await readTelemetry(instrumentation)).toMatchObject({
+ recordInputs: true,
+ recordOutputs: true,
+ });
+ expect(policy).toHaveBeenCalledOnce();
+ expect(ctx.get(SessionTraceSeedKey)).toBeUndefined();
+ });
+});
diff --git a/packages/eve/src/instrumentation/runtime.ts b/packages/eve/src/instrumentation/runtime.ts
new file mode 100644
index 000000000..cf3a44275
--- /dev/null
+++ b/packages/eve/src/instrumentation/runtime.ts
@@ -0,0 +1,574 @@
+import type { Telemetry, TelemetryOptions } from "ai";
+import { context as otelContext, trace } from "#compiled/@opentelemetry/api/index.js";
+
+import type { InstrumentationEvents } from "#public/instrumentation/index.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
+import {
+ applyAudienceCeiling,
+ shouldCaptureInstrumentationContent,
+} from "#shared/instrumentation-content.js";
+import type {
+ InstrumentationAttemptScope,
+ InstrumentationContextRunner,
+ InstrumentationHooks,
+ InstrumentationSessionStartedEvent,
+ InstrumentationTraceContext,
+ InstrumentationTraceSeed,
+ InstrumentationTurnStartedEvent,
+} from "#instrumentation/lifecycle.js";
+import { attemptIdempotencyKey } from "#instrumentation/lifecycle.js";
+import {
+ buildTelemetryRuntimeContext,
+ snapshotInstrumentationRuntimeContext,
+ type BuildTelemetryRuntimeContextInput,
+} from "#instrumentation/runtime-context.js";
+import {
+ ensureOtelIntegration,
+ getRegisteredTelemetryIntegrations,
+} from "#instrumentation/ai-sdk-telemetry.js";
+import { createAiSdkHookBridge } from "#instrumentation/ai-sdk-hook-bridge.js";
+import {
+ createInstrumentationHandleEvent,
+ publishInputResolutions,
+ type CreateInstrumentationHandleEventInput,
+} from "#instrumentation/native-events.js";
+import type { ResolvedInputBatch } from "#harness/input-requests.js";
+import type { HandleEventFn } from "#harness/types.js";
+import {
+ instrumentChannelDelivery,
+ type ChannelDeliveryStartInstrumentation,
+ type ChannelDeliveryTerminalInstrumentation,
+} from "#instrumentation/channel-delivery.js";
+import { recordErrorOnSpan } from "#internal/logging.js";
+import {
+ prepareTurnTraceContext,
+ type PrepareTurnTraceContextInput,
+} from "#instrumentation/prepare-trace-context.js";
+import type { RuntimeTraceContext } from "#protocol/message.js";
+import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
+import type { OtelHarnessSettings, RuntimeContextResolver } from "#tracing/otel-declaration.js";
+import type { SessionTraceSeed } from "#context/keys.js";
+import { contextStorage, type ContextContainer } from "#context/container.js";
+import {
+ ChannelInstrumentationKey,
+ OtelTraceEnabledKey,
+ ParentSessionKey,
+ ParentTraceContextKey,
+ SessionTraceSeedKey,
+} from "#context/keys.js";
+import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import {
+ isSampledTrace,
+ resolveTracePolicy,
+ resolveTracePolicyDecision,
+} from "#tracing/sampled-trace.js";
+import { resolveParentLineage } from "#instrumentation/parent-lineage.js";
+import type { ChannelInstrumentationProjection, SessionTraceContext } from "#channel/types.js";
+import { readSessionTraceDecision } from "#tracing/agent-trace-context-store.js";
+
+const INSTRUMENTATION_RUNTIME_KEY = Symbol.for("eve.instrumentation-runtime");
+const TURN_TRACE_STATE_KEY = "eve.harness.turnTrace";
+
+interface InstrumentedStepSession {
+ readonly sessionId: string;
+ readonly state?: Readonly<Record<string, unknown>>;
+}
+
+export interface InstrumentationStepScope<TSession> {
+ readonly createHandleEvent: (
+ input: Omit<
+ CreateInstrumentationHandleEventInput,
+ | "agentName"
+ | "channelAudience"
+ | "channelKind"
+ | "hooks"
+ | "parentLineage"
+ | "parentTraceContext"
+ | "rootSessionId"
+ | "sessionId"
+ >,
+ ) => HandleEventFn | undefined;
+ readonly prepareAttempt: (input: {
+ readonly attemptIndex: number;
+ readonly runtimeContext?: Readonly<Record<string, unknown>>;
+ readonly stepIndex: number;
+ readonly turnId: string;
+ }) => PreparedInstrumentationAttempt;
+ readonly preparePreamble: (
+ input: Omit<
+ PrepareTurnTraceContextInput,
+ | "agentName"
+ | "channelAudience"
+ | "channelType"
+ | "instrumentation"
+ | "parentLineage"
+ | "parentTraceContext"
+ | "rootSessionId"
+ | "sessionId"
+ | "traceSeed"
+ >,
+ ) => Promise<RuntimeTraceContext | undefined>;
+ readonly publishInputResolutions: (input: {
+ readonly batch: ResolvedInputBatch;
+ readonly sessionId: string;
+ }) => Promise<void>;
+ readonly recordError: (error: unknown) => void;
+ readonly resolveRuntimeContext: (
+ input: Omit<
+ BuildTelemetryRuntimeContextInput,
+ "capturesContent" | "context" | "providerResolvers" | "stepStartedResolver"
+ >,
+ ) => Record<string, unknown> | undefined;
+ readonly session: TSession;
+ readonly setTurnId: (turnId: string) => void;
+ readonly telemetry: () => TelemetryOptions | undefined;
+ readonly traceContext?: InstrumentationTraceContext;
+}
+
+export interface PreparedInstrumentationAttempt {
+ readonly complete: () => Promise<void>;
+ readonly fail: (error: unknown) => Promise<void>;
+ readonly scope: InstrumentationAttemptScope;
+ readonly telemetry: TelemetryOptions | undefined;
+}
+
+export type InstrumentationAttempt = InstrumentationAttemptScope;
+
+export interface BoundInstrumentationSession {
+ readonly agentName?: string;
+ readonly rootSessionId: string;
+ readonly sessionId: string;
+}
+
+/** Process-wide runtime consumed by every harness execution surface. */
+export interface InstrumentationRuntime {
+ readonly forceFlush: () => Promise<void>;
+ readonly hooks: InstrumentationHooks;
+ readonly idGenerator?: AgentSpanIdGenerator;
+ readonly prepareSessionTrace?: (
+ event: InstrumentationSessionStartedEvent,
+ ) => Promise<InstrumentationTraceSeed>;
+ readonly prepareTurnTrace?: (
+ event: InstrumentationTurnStartedEvent,
+ ) => Promise<InstrumentationTraceSeed>;
+ otelSettings: OtelHarnessSettings | undefined;
+ readonly runtimeContextResolvers?: readonly RuntimeContextResolver[];
+ readonly runInContext: InstrumentationContextRunner;
+ readonly shutdown: () => Promise<void>;
+ stepStartedRuntimeContextResolver?: InstrumentationEvents["step.started"];
+}
+
+/** Worker-bound instrumentation operations consumed by one session execution. */
+export interface SessionInstrumentation {
+ readonly runStep: <TSession extends InstrumentedStepSession, TResult>(
+ input: {
+ readonly environment: string;
+ readonly eveVersion: string;
+ readonly hasInput: boolean;
+ readonly session: TSession;
+ },
+ execute: (scope: InstrumentationStepScope<TSession>) => Promise<TResult>,
+ ) => Promise<TResult>;
+}
+
+export interface ExecutionInstrumentation {
+ readonly createCancellationHandleEvent: (input: {
+ readonly handleEvent?: HandleEventFn;
+ readonly turnId: string;
+ }) => HandleEventFn | undefined;
+ readonly flush: () => Promise<void>;
+ readonly instrumentChannelDelivery: (
+ input:
+ | Omit<ChannelDeliveryStartInstrumentation, "hooks">
+ | Omit<ChannelDeliveryTerminalInstrumentation, "hooks">,
+ ) => Promise<void>;
+ readonly prepareExecution: () => SessionInstrumentation;
+ readonly preparePreamble: InstrumentationStepScope<never>["preparePreamble"];
+}
+
+export function bindInstrumentationRuntime(
+ runtime: InstrumentationRuntime | undefined,
+ ctx: ContextContainer,
+ boundSession: BoundInstrumentationSession,
+): ExecutionInstrumentation | undefined {
+ if (runtime === undefined) return undefined;
+ const hooks = runtime.hooks;
+ const readSessionContext = () => {
+ const context = contextStorage.getStore() ?? ctx;
+ return {
+ channel: context.get(ChannelKey),
+ context,
+ instrumentation: context.get(ChannelInstrumentationKey),
+ parent: context.get(ParentSessionKey),
+ parentTraceContext: context.get(ParentTraceContextKey),
+ traceSeed: context.get(SessionTraceSeedKey),
+ };
+ };
+ const captureExecutionRuntime = () => {
+ const otelSettings = runtime.otelSettings;
+ if (otelSettings !== undefined) ensureOtelIntegration();
+ return {
+ otelSettings,
+ runtimeContextResolvers: runtime.runtimeContextResolvers,
+ stepStartedRuntimeContextResolver: runtime.stepStartedRuntimeContextResolver,
+ tracer: otelSettings === undefined ? undefined : trace.getTracer("eve"),
+ };
+ };
+ const preparePreamble = (
+ input: Parameters<ExecutionInstrumentation["preparePreamble"]>[0],
+ sessionContext: ReturnType<typeof readSessionContext>,
+ ) => {
+ const channel = sessionContext.instrumentation;
+ const audience = normalizeChannelAudience(channel?.metadata.audience);
+ return prepareTurnTraceContext({
+ ...input,
+ agentName: boundSession.agentName,
+ channelAudience: audience,
+ channelType: channel?.channelType,
+ instrumentation: runtime,
+ parentLineage: resolveParentLineage(sessionContext.parent, sessionContext.channel),
+ parentTraceContext: sessionContext.parentTraceContext,
+ rootSessionId: sessionContext.parent?.rootSessionId ?? boundSession.rootSessionId,
+ sessionId: boundSession.sessionId,
+ traceSeed: sessionContext.traceSeed,
+ });
+ };
+ const prepareExecution = (): SessionInstrumentation => {
+ const executionRuntime = captureExecutionRuntime();
+ return {
+ runStep: async (input, execute) => {
+ const policyContext = readSessionContext();
+ const settings = executionRuntime.otelSettings;
+ const decision = resolveStepInstrumentationDecision(
+ settings,
+ boundSession.agentName,
+ policyContext.instrumentation,
+ policyContext.traceSeed,
+ readSessionTraceDecision(policyContext.context, boundSession.sessionId),
+ );
+ const tracer = executionRuntime.tracer;
+ const attributes: Record<string, string> = {
+ "eve.environment": input.environment,
+ "eve.session.id": input.session.sessionId,
+ "eve.version": input.eveVersion,
+ };
+ const functionId = settings?.functionId ?? boundSession.agentName;
+ if (functionId) attributes["ai.telemetry.functionId"] = functionId;
+ let turnSpan =
+ tracer !== undefined && decision?.action !== "drop" && input.hasInput
+ ? tracer.startSpan("ai.eve.turn", { attributes })
+ : undefined;
+ const spanContext = turnSpan?.spanContext();
+ const session =
+ spanContext === undefined
+ ? input.session
+ : ({
+ ...input.session,
+ state: {
+ ...input.session.state,
+ [TURN_TRACE_STATE_KEY]: {
+ spanId: spanContext.spanId,
+ traceFlags: spanContext.traceFlags,
+ traceId: spanContext.traceId,
+ },
+ },
+ } as typeof input.session);
+ let parentContext =
+ turnSpan === undefined ? undefined : trace.setSpan(otelContext.active(), turnSpan);
+ if (parentContext === undefined && tracer !== undefined) {
+ const stored = input.session.state?.[TURN_TRACE_STATE_KEY] as
+ | { readonly spanId: string; readonly traceFlags: number; readonly traceId: string }
+ | undefined;
+ if (stored !== undefined) {
+ parentContext = trace.setSpan(
+ otelContext.active(),
+ trace.wrapSpanContext({ ...stored, isRemote: true }),
+ );
+ }
+ }
+
+ const sessionContext = readSessionContext();
+ const runtimeContextSnapshot = snapshotInstrumentationRuntimeContext(
+ sessionContext.context,
+ );
+ const channel = sessionContext.instrumentation;
+ const audience = normalizeChannelAudience(channel?.metadata.audience);
+ const capturesContent = shouldCaptureInstrumentationContent(audience);
+ const effectiveDecision =
+ decision === undefined ? undefined : applyAudienceCeiling(decision, audience);
+ const dropsTrace = decision?.action === "drop";
+ const content = {
+ recordInputs:
+ !dropsTrace &&
+ (effectiveDecision?.action === "record"
+ ? effectiveDecision.recordInputs
+ : capturesContent) &&
+ (settings?.recordInputs ?? false),
+ recordOutputs:
+ !dropsTrace &&
+ (effectiveDecision?.action === "record"
+ ? effectiveDecision.recordOutputs
+ : capturesContent) &&
+ (settings?.recordOutputs ?? false),
+ };
+ const telemetry = (telemetryInput: {
+ readonly bridgeIntegration?: Telemetry;
+ readonly runtimeContext?: Readonly<Record<string, unknown>>;
+ }): TelemetryOptions | undefined => {
+ if (settings === undefined && telemetryInput.bridgeIntegration === undefined) {
+ return undefined;
+ }
+ const includeRuntimeContext: Record<string, true> = {};
+ for (const key of Object.keys(telemetryInput.runtimeContext ?? {})) {
+ includeRuntimeContext[key] = true;
+ }
+ const sanitizeEveOtelErrors =
+ settings !== undefined && !(content.recordInputs && content.recordOutputs);
+ const integrations = () => getRegisteredTelemetryIntegrations({ sanitizeEveOtelErrors });
+ return {
+ functionId: settings?.functionId ?? boundSession.agentName,
+ includeRuntimeContext,
+ integrations:
+ telemetryInput.bridgeIntegration === undefined
+ ? sanitizeEveOtelErrors
+ ? [...integrations()]
+ : undefined
+ : [telemetryInput.bridgeIntegration, ...integrations()],
+ isEnabled: true,
+ recordInputs: content.recordInputs,
+ recordOutputs: content.recordOutputs,
+ };
+ };
+ const run = () =>
+ execute({
+ createHandleEvent: (eventInput) =>
+ createInstrumentationHandleEvent({
+ ...eventInput,
+ agentName: boundSession.agentName,
+ channelAudience: audience,
+ channelKind: channel?.kind,
+ hooks,
+ parentLineage: resolveParentLineage(sessionContext.parent, sessionContext.channel),
+ parentTraceContext: sessionContext.parentTraceContext,
+ rootSessionId: sessionContext.parent?.rootSessionId,
+ sessionId: boundSession.sessionId,
+ }),
+ prepareAttempt: (attemptInput) => {
+ const scope: InstrumentationAttemptScope = {
+ attemptId: `${boundSession.sessionId}:${attemptInput.turnId}:${attemptInput.stepIndex}:${attemptInput.attemptIndex}`,
+ attemptIndex: attemptInput.attemptIndex,
+ channelAudience: audience,
+ functionId: settings?.functionId ?? boundSession.agentName,
+ rootSessionId: sessionContext.parent?.rootSessionId ?? boundSession.sessionId,
+ sessionId: boundSession.sessionId,
+ stepIndex: attemptInput.stepIndex,
+ turnId: attemptInput.turnId,
+ };
+ const bridgeIntegration = createAiSdkHookBridge(
+ scope,
+ hooks,
+ runtime.runInContext,
+ attemptInput.runtimeContext,
+ );
+ return {
+ complete: () =>
+ hooks.publish({
+ idempotencyKey: attemptIdempotencyKey(scope),
+ scope,
+ type: "step.attempt.completed",
+ }),
+ fail: (error) =>
+ hooks.publish({
+ error,
+ idempotencyKey: attemptIdempotencyKey(scope),
+ scope,
+ type: "step.attempt.failed",
+ }),
+ scope,
+ telemetry: telemetry({
+ bridgeIntegration,
+ runtimeContext: attemptInput.runtimeContext,
+ }),
+ };
+ },
+ preparePreamble: (preambleInput) => preparePreamble(preambleInput, sessionContext),
+ publishInputResolutions: (resolutionInput) =>
+ publishInputResolutions({ ...resolutionInput, hooks }),
+ recordError: (error) => {
+ if (turnSpan !== undefined) recordErrorOnSpan(turnSpan, error);
+ },
+ resolveRuntimeContext: (runtimeContextInput) => {
+ const runtimeContextAudience = normalizeChannelAudience(
+ runtimeContextSnapshot.channel?.metadata.audience,
+ );
+ return buildTelemetryRuntimeContext({
+ ...runtimeContextInput,
+ capturesContent: shouldCaptureInstrumentationContent(runtimeContextAudience),
+ context: runtimeContextSnapshot,
+ providerResolvers: executionRuntime.runtimeContextResolvers,
+ stepStartedResolver: executionRuntime.stepStartedRuntimeContextResolver,
+ });
+ },
+ session,
+ setTurnId: (turnId) => turnSpan?.setAttribute("eve.turn.id", turnId),
+ telemetry: () => telemetry({}),
+ traceContext:
+ spanContext === undefined || !isValidSpanContext(spanContext)
+ ? undefined
+ : {
+ spanId: spanContext.spanId,
+ traceFlags: spanContext.traceFlags,
+ traceId: spanContext.traceId,
+ },
+ });
+ try {
+ return parentContext === undefined
+ ? await run()
+ : await otelContext.with(parentContext, run);
+ } finally {
+ turnSpan?.end();
+ turnSpan = undefined;
+ }
+ },
+ };
+ };
+ return {
+ createCancellationHandleEvent: (input) =>
+ createInstrumentationHandleEvent({
+ agentName: boundSession.agentName,
+ channelKind: readSessionContext().instrumentation?.kind,
+ handleEvent: input.handleEvent,
+ hooks,
+ sessionId: boundSession.sessionId,
+ turnId: input.turnId,
+ }),
+ flush: runtime.forceFlush,
+ instrumentChannelDelivery: (input) => instrumentChannelDelivery({ ...input, hooks }),
+ prepareExecution,
+ preparePreamble: (input) => preparePreamble(input, readSessionContext()),
+ };
+}
+
+export function bindSessionInstrumentation(input: {
+ readonly agentName?: string;
+ readonly ctx: ContextContainer;
+ readonly rootSessionId: string;
+ readonly sessionId: string;
+}): ExecutionInstrumentation | undefined {
+ return bindInstrumentationRuntime(getInstrumentationRuntime(), input.ctx, {
+ agentName: input.agentName,
+ rootSessionId: input.rootSessionId,
+ sessionId: input.sessionId,
+ });
+}
+
+export function initializeSessionInstrumentation(input: {
+ readonly agentName?: string;
+ readonly ctx: ContextContainer;
+ readonly parentTraceContext?: SessionTraceContext;
+}): void {
+ const runtime = getInstrumentationRuntime();
+ const channel = input.ctx.get(ChannelInstrumentationKey);
+ const audience = normalizeChannelAudience(channel?.metadata.audience);
+ const traceSeed = allocateSessionTraceSeed({
+ agentName: input.agentName,
+ audience,
+ channelType: channel?.channelType,
+ parentTraceContext: input.parentTraceContext,
+ runtime,
+ });
+ if (traceSeed !== undefined) input.ctx.set(SessionTraceSeedKey, traceSeed);
+ input.ctx.set(OtelTraceEnabledKey, runtime?.prepareSessionTrace !== undefined);
+}
+
+function allocateSessionTraceSeed(input: {
+ readonly agentName?: string;
+ readonly audience: ReturnType<typeof normalizeChannelAudience>;
+ readonly channelType?: string;
+ readonly parentTraceContext?: SessionTraceContext;
+ readonly runtime: InstrumentationRuntime | undefined;
+}): SessionTraceSeed | undefined {
+ if (input.parentTraceContext !== undefined) {
+ const decision =
+ input.parentTraceContext.decision ??
+ resolveTracePolicyDecision(isSampledTrace(input.parentTraceContext), input.audience);
+ return {
+ decision,
+ spanId: input.parentTraceContext.spanId,
+ traceFlags: input.parentTraceContext.traceFlags,
+ traceId: input.parentTraceContext.traceId,
+ };
+ }
+ if (input.runtime?.prepareSessionTrace === undefined) return undefined;
+ if (input.runtime.idGenerator === undefined) return undefined;
+ const decision = resolveTracePolicy(input.runtime.otelSettings?.tracePolicy, {
+ agentName: input.agentName,
+ audience: input.audience,
+ channelType: input.channelType,
+ });
+ return {
+ decision,
+ spanId: input.runtime.idGenerator.allocateSpanId(),
+ traceFlags: decision.action === "record" ? 1 : 0,
+ traceId: input.runtime.idGenerator.generateTraceId(),
+ };
+}
+
+function resolveStepInstrumentationDecision(
+ settings: OtelHarnessSettings | undefined,
+ agentName: string | undefined,
+ channel: ChannelInstrumentationProjection | undefined,
+ traceSeed: SessionTraceSeed | undefined,
+ persisted: InstrumentationDecision | undefined,
+): InstrumentationDecision | undefined {
+ if (settings === undefined) return undefined;
+ if (traceSeed?.decision !== undefined) return traceSeed.decision;
+ if (persisted !== undefined) return persisted;
+ const audience = normalizeChannelAudience(channel?.metadata.audience);
+ if (traceSeed !== undefined) {
+ return resolveTracePolicyDecision(isSampledTrace(traceSeed), audience);
+ }
+ return resolveTracePolicy(settings.tracePolicy, {
+ agentName,
+ audience,
+ channelType: channel?.channelType,
+ });
+}
+
+function isValidSpanContext(spanContext: {
+ readonly spanId: string;
+ readonly traceId: string;
+}): boolean {
+ return (
+ /^[0-9a-f]{32}$/u.test(spanContext.traceId) &&
+ spanContext.traceId !== "00000000000000000000000000000000" &&
+ /^[0-9a-f]{16}$/u.test(spanContext.spanId) &&
+ spanContext.spanId !== "0000000000000000"
+ );
+}
+
+type InstrumentationGlobal = typeof globalThis & {
+ [INSTRUMENTATION_RUNTIME_KEY]?: InstrumentationRuntime;
+};
+
+const globalRuntime = globalThis as InstrumentationGlobal;
+
+/** Registers the process instrumentation runtime before agent execution begins. */
+export function registerInstrumentationRuntime(
+ runtime: InstrumentationRuntime,
+): InstrumentationRuntime {
+ const existing = globalRuntime[INSTRUMENTATION_RUNTIME_KEY];
+ if (existing !== undefined) {
+ // A legacy config may reload without taking ownership from the installed runtime.
+ existing.otelSettings = runtime.otelSettings;
+ return existing;
+ }
+ globalRuntime[INSTRUMENTATION_RUNTIME_KEY] = runtime;
+ return runtime;
+}
+
+/** Returns the process instrumentation runtime, when one was installed. */
+export function getInstrumentationRuntime(): InstrumentationRuntime | undefined {
+ return globalRuntime[INSTRUMENTATION_RUNTIME_KEY];
+}
diff --git a/packages/eve/src/harness/instrumentation/setup-context.ts b/packages/eve/src/instrumentation/setup-context.ts
similarity index 100%
rename from packages/eve/src/harness/instrumentation/setup-context.ts
rename to packages/eve/src/instrumentation/setup-context.ts
diff --git a/packages/eve/src/harness/instrumentation/state.test.ts b/packages/eve/src/instrumentation/state.test.ts
similarity index 95%
rename from packages/eve/src/harness/instrumentation/state.test.ts
rename to packages/eve/src/instrumentation/state.test.ts
index 32c51c492..3672409b7 100644
--- a/packages/eve/src/harness/instrumentation/state.test.ts
+++ b/packages/eve/src/instrumentation/state.test.ts
@@ -5,17 +5,17 @@ import { deserializeContext, serializeContext } from "#context/serialize.js";
import {
actionIdempotencyKey,
type InstrumentationAttemptScope,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import {
abandonInstrumentationState,
instrumentationStateSlot,
isInstrumentationStateAbandoned,
- preserveSerializedInstrumentationState,
rememberInstrumentationActionScope,
releaseAllInstrumentationAttemptState,
releaseAllInstrumentationState,
takeInstrumentationActionScopeForCall,
-} from "#harness/instrumentation/state.js";
+} from "#instrumentation/state.js";
+import { preserveSerializedInstrumentationState } from "#instrumentation/state.js";
describe("instrumentation state", () => {
it("survives a serialized step boundary", async () => {
@@ -124,7 +124,9 @@ describe("instrumentation state", () => {
expect(
preserveSerializedInstrumentationState(
{ authored: "original" },
- { "eve.harness.instrumentationState": { state: true } },
+ {
+ "eve.harness.instrumentationState": { state: true },
+ },
),
).toEqual({
authored: "original",
diff --git a/packages/eve/src/harness/instrumentation/state.ts b/packages/eve/src/instrumentation/state.ts
similarity index 95%
rename from packages/eve/src/harness/instrumentation/state.ts
rename to packages/eve/src/instrumentation/state.ts
index 043c441d3..53a17d559 100644
--- a/packages/eve/src/harness/instrumentation/state.ts
+++ b/packages/eve/src/instrumentation/state.ts
@@ -1,8 +1,8 @@
import { contextStorage, loadContext } from "#context/container.js";
-import { ActiveChannelDeliveriesKey } from "#context/keys.js";
import { ContextKey } from "#context/key.js";
+import { ActiveChannelDeliveriesKey } from "#context/keys.js";
import { type JsonValue, parseJsonValue } from "#shared/json.js";
-import type { InstrumentationAttemptScope } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationAttemptScope } from "#instrumentation/lifecycle.js";
/**
* What every provider has staged, flattened into one durable slot.
@@ -63,16 +63,7 @@ const InstrumentationInputScopeKey = new ContextKey<InstrumentationScopeMap>(
},
);
-/**
- * Keeps provider state from an interrupted step's context changes.
- *
- * A cancelled step's context writes are discarded wholesale. Provider state has
- * to be an exception for the same reason eve's own trace state is: the
- * cancellation epilogue still publishes `turn.cancelled`, and a provider that
- * staged something at the start of the operation being cancelled needs it there
- * to close cleanly. Without this, the terminal arrives with an empty slot and
- * whatever the provider opened is never closed.
- */
+/** Keeps only provider state needed to settle an interrupted operation. */
export function preserveSerializedInstrumentationState(
original: Record<string, unknown>,
interrupted: Record<string, unknown>,
diff --git a/packages/eve/src/internal/application/compiled-artifacts.ts b/packages/eve/src/internal/application/compiled-artifacts.ts
index 2a8940479..34c1ed3fd 100644
--- a/packages/eve/src/internal/application/compiled-artifacts.ts
+++ b/packages/eve/src/internal/application/compiled-artifacts.ts
@@ -486,9 +486,7 @@ function createInstrumentationPluginSource(input: {
const agentName = JSON.stringify(input.agentName);
if (input.layout.kind === "module-map") {
- const registerConfigPath = resolvePackageSourceFilePath(
- "src/harness/instrumentation/config.ts",
- );
+ const registerConfigPath = resolvePackageSourceFilePath("src/instrumentation/config.ts");
return [
"// Generated by eve. Do not edit by hand.",
`import { moduleMap } from ${stringifyEsmImportSpecifier(input.layout.moduleMapPath)};`,
@@ -505,9 +503,7 @@ function createInstrumentationPluginSource(input: {
}
if (input.layout.kind === "file") {
- const registerConfigPath = resolvePackageSourceFilePath(
- "src/harness/instrumentation/config.ts",
- );
+ const registerConfigPath = resolvePackageSourceFilePath("src/instrumentation/config.ts");
return [
"// Generated by eve. Do not edit by hand.",
`import * as instrumentationModule from ${stringifyEsmImportSpecifier(input.layout.modulePath)};`,
@@ -524,9 +520,7 @@ function createInstrumentationPluginSource(input: {
].join("\n");
}
- const registerProviderPath = resolvePackageSourceFilePath(
- "src/harness/instrumentation/providers.ts",
- );
+ const registerProviderPath = resolvePackageSourceFilePath("src/instrumentation/providers.ts");
const slots = Object.entries(input.layout.modulePathsBySlot);
return [
diff --git a/packages/eve/src/internal/instrumentation.ts b/packages/eve/src/internal/instrumentation.ts
index 15a975507..79d3c1308 100644
--- a/packages/eve/src/internal/instrumentation.ts
+++ b/packages/eve/src/internal/instrumentation.ts
@@ -1,7 +1,7 @@
/**
* Shared instrumentation primitives used by both the channel projection
* builder (`#channel/instrumentation.ts`) and the harness telemetry
- * builder (`#harness/instrumentation/runtime-context.ts`).
+ * builder (`#instrumentation/runtime-context.ts`).
*
* Both layers resolve a user-authored projector callback into a plain
* record and reason about the same channel-kind vocabulary. Keeping that
diff --git a/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts b/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts
index afb6ce16c..40c05be95 100644
--- a/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts
+++ b/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts
@@ -21,10 +21,7 @@ import {
setChannelInstrumentationKind,
} from "#channel/compiled-channel.js";
import type { RouteHandlerArgs } from "#channel/routes.js";
-import {
- getInstrumentationConfig,
- registerInstrumentationConfig,
-} from "#harness/instrumentation/config.js";
+import { registerInstrumentationConfig } from "#instrumentation/config.js";
import type { Runtime } from "#channel/types.js";
import { readVercelProjectLink } from "#internal/vercel/project-link.js";
import { resolveVercelOidcCurrentProject } from "#channel/auth/vercel-oidc-project.js";
@@ -709,7 +706,6 @@ function slackChannel(
describe("dispatchChannelRequest tracing", () => {
let exporter: InMemorySpanExporter;
let provider: BasicTracerProvider;
- let priorConfig: ReturnType<typeof getInstrumentationConfig>;
beforeEach(() => {
exporter = new InMemorySpanExporter();
@@ -718,12 +714,11 @@ describe("dispatchChannelRequest tracing", () => {
apiPropagation.setGlobalPropagator(w3cPropagator as never);
apiTrace.setGlobalTracerProvider(provider);
// Request spans are opt-in; enable them for this suite.
- priorConfig = getInstrumentationConfig();
registerInstrumentationConfig({ traceChannelRequests: true }, { agentName: "test" });
});
afterEach(() => {
- registerInstrumentationConfig(priorConfig ?? {}, { agentName: "test" });
+ registerInstrumentationConfig({}, { agentName: "test" });
apiTrace.disable();
apiContext.disable();
apiPropagation.disable();
@@ -1019,7 +1014,6 @@ describe("dispatchChannelRequest tracing", () => {
describe("dispatchChannelRequest without an OTel provider", () => {
let exporter: InMemorySpanExporter;
let provider: BasicTracerProvider;
- let priorConfig: ReturnType<typeof getInstrumentationConfig>;
beforeEach(() => {
// Register an exporter to prove nothing reaches it, but leave the global
@@ -1030,12 +1024,11 @@ describe("dispatchChannelRequest without an OTel provider", () => {
apiTrace.disable();
apiContext.disable();
apiPropagation.disable();
- priorConfig = getInstrumentationConfig();
registerInstrumentationConfig({ traceChannelRequests: true }, { agentName: "test" });
});
afterEach(() => {
- registerInstrumentationConfig(priorConfig ?? {}, { agentName: "test" });
+ registerInstrumentationConfig({}, { agentName: "test" });
apiTrace.disable();
});
@@ -1063,7 +1056,6 @@ describe("dispatchChannelRequest without an OTel provider", () => {
describe("dispatchChannelRequest with request tracing not enabled", () => {
let exporter: InMemorySpanExporter;
let provider: BasicTracerProvider;
- let priorConfig: ReturnType<typeof getInstrumentationConfig>;
beforeEach(() => {
// A live provider proves the opt-in flag — not a missing provider — is what
@@ -1073,12 +1065,11 @@ describe("dispatchChannelRequest with request tracing not enabled", () => {
apiContext.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
apiPropagation.setGlobalPropagator(w3cPropagator as never);
apiTrace.setGlobalTracerProvider(provider);
- priorConfig = getInstrumentationConfig();
+ registerInstrumentationConfig({}, { agentName: "test" });
});
afterEach(() => {
- // Restore the process-global config so the toggle does not leak.
- registerInstrumentationConfig(priorConfig ?? {}, { agentName: "test" });
+ registerInstrumentationConfig({}, { agentName: "test" });
apiTrace.disable();
apiContext.disable();
apiPropagation.disable();
diff --git a/packages/eve/src/internal/nitro/routes/channel-request-instrumentation.ts b/packages/eve/src/internal/nitro/routes/channel-request-instrumentation.ts
index 3f9b0431c..7ddb9454a 100644
--- a/packages/eve/src/internal/nitro/routes/channel-request-instrumentation.ts
+++ b/packages/eve/src/internal/nitro/routes/channel-request-instrumentation.ts
@@ -8,7 +8,7 @@ import {
type TextMapGetter,
trace,
} from "#compiled/@opentelemetry/api/index.js";
-import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
+import { getInstrumentationRuntime } from "#instrumentation/runtime.js";
import { recordErrorOnSpan } from "#internal/logging.js";
/**
diff --git a/packages/eve/src/tracing/agent-action-instrumentation.ts b/packages/eve/src/tracing/agent-action-instrumentation.ts
index 166056de5..1be39377c 100644
--- a/packages/eve/src/tracing/agent-action-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-action-instrumentation.ts
@@ -13,8 +13,8 @@ import type {
InstrumentationActionTerminalEvent,
InstrumentationAttemptScope,
InstrumentationProviderDefinition,
-} from "#harness/instrumentation/lifecycle.js";
-import { actionIdempotencyKey, attemptIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import { actionIdempotencyKey, attemptIdempotencyKey } from "#instrumentation/lifecycle.js";
import { contentAttribute } from "#tracing/agent-otel-content.js";
import { setAgentUsage } from "#tracing/agent-otel-usage.js";
import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
diff --git a/packages/eve/src/tracing/agent-approval-instrumentation.ts b/packages/eve/src/tracing/agent-approval-instrumentation.ts
index f70f29aa9..81ba13768 100644
--- a/packages/eve/src/tracing/agent-approval-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-approval-instrumentation.ts
@@ -12,7 +12,7 @@ import type {
InstrumentationInputRequestedEvent,
InstrumentationInputResolvedEvent,
InstrumentationProviderDefinition,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import type { JsonValue } from "#shared/json.js";
import { contentAttribute } from "#tracing/agent-otel-content.js";
import type { AgentActionContext } from "#tracing/agent-action-instrumentation.js";
diff --git a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts
index 67932744a..331472372 100644
--- a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts
@@ -14,8 +14,8 @@ import type {
InstrumentationHandlerContext,
InstrumentationProviderDefinition,
InstrumentationSessionStartedEvent,
-} from "#harness/instrumentation/lifecycle.js";
-import { sessionIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import { sessionIdempotencyKey } from "#instrumentation/lifecycle.js";
import type { JsonValue } from "#shared/json.js";
import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";
import { contentAttribute } from "#tracing/agent-otel-content.js";
diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.ts
index d169b788e..3996dda3a 100644
--- a/packages/eve/src/tracing/agent-otel-provider.test.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts
@@ -14,7 +14,7 @@ import {
} from "#compiled/@opentelemetry/api/index.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
-import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";
+import { createAiSdkHookBridge } from "#instrumentation/ai-sdk-hook-bridge.js";
import {
createAgentOtelInstrumentation,
type AgentOtelInstrumentationInput,
@@ -35,7 +35,7 @@ import {
type InstrumentationParentLineage,
type InstrumentationTraceContext,
type InstrumentationUsage,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";
import {
@@ -45,7 +45,7 @@ import {
modelCallIdempotencyKey,
sessionIdempotencyKey,
turnIdempotencyKey,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
interface TestRuntime {
readonly exporter: InMemorySpanExporter;
diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.ts
index 6f3f1c2f6..aa4765cf5 100644
--- a/packages/eve/src/tracing/agent-otel-provider.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.ts
@@ -11,8 +11,8 @@ import {
import { contextStorage } from "#context/container.js";
import { SessionTraceSeedKey } from "#context/keys.js";
-import { withoutInstrumentationContent } from "#harness/instrumentation/content.js";
-import { instrumentationEventForTraceDecision } from "#harness/instrumentation/content-policy.js";
+import { withoutInstrumentationContent } from "#instrumentation/content.js";
+import { instrumentationEventForTraceDecision } from "#instrumentation/content-policy.js";
import type { AgentTraceStateStore } from "#tracing/agent-trace-state.js";
import {
contentAttribute,
@@ -51,8 +51,8 @@ import type {
InstrumentationSessionTransitionEvent,
InstrumentationTurnStartedEvent,
InstrumentationTurnTerminalEvent,
-} from "#harness/instrumentation/lifecycle.js";
-import { attemptIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import { attemptIdempotencyKey } from "#instrumentation/lifecycle.js";
interface SpanState {
readonly context: Context;
diff --git a/packages/eve/src/tracing/agent-otel-session-context.ts b/packages/eve/src/tracing/agent-otel-session-context.ts
index 92ac5b6bd..e3b4198ce 100644
--- a/packages/eve/src/tracing/agent-otel-session-context.ts
+++ b/packages/eve/src/tracing/agent-otel-session-context.ts
@@ -6,7 +6,7 @@ import {
type InstrumentationTraceContext,
type InstrumentationTraceSeed,
type InstrumentationTurnStartedEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import { normalizeChannelAudience } from "#shared/channel-audience.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
diff --git a/packages/eve/src/tracing/agent-otel-usage.ts b/packages/eve/src/tracing/agent-otel-usage.ts
index 1d1ce31e3..3bb81a133 100644
--- a/packages/eve/src/tracing/agent-otel-usage.ts
+++ b/packages/eve/src/tracing/agent-otel-usage.ts
@@ -1,6 +1,6 @@
import type { Span } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationUsage } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationUsage } from "#instrumentation/lifecycle.js";
/** Applies eve's structural token usage attributes to an agent span. */
export function setAgentUsage(span: Span, usage: InstrumentationUsage): void {
diff --git a/packages/eve/src/tracing/agent-tool-instrumentation.ts b/packages/eve/src/tracing/agent-tool-instrumentation.ts
index ed291d7b2..21d0568df 100644
--- a/packages/eve/src/tracing/agent-tool-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-tool-instrumentation.ts
@@ -12,8 +12,8 @@ import type {
InstrumentationActionStartedEvent,
InstrumentationToolCallStartedEvent,
InstrumentationToolCallTerminalEvent,
-} from "#harness/instrumentation/lifecycle.js";
-import { actionIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
+import { actionIdempotencyKey } from "#instrumentation/lifecycle.js";
import { contentAttribute } from "#tracing/agent-otel-content.js";
import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import type { AgentActionContext } from "#tracing/agent-action-instrumentation.js";
diff --git a/packages/eve/src/tracing/agent-trace-context-store.ts b/packages/eve/src/tracing/agent-trace-context-store.ts
index 129ce34f7..7b15fce31 100644
--- a/packages/eve/src/tracing/agent-trace-context-store.ts
+++ b/packages/eve/src/tracing/agent-trace-context-store.ts
@@ -3,6 +3,7 @@ import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
import type { SessionTraceContext } from "#channel/types.js";
import { contextStorage, loadContext } from "#context/container.js";
import { ContextKey } from "#context/key.js";
+import type { ContextAccessor } from "#context/key.js";
import { SessionTraceSeedKey, type SessionTraceSeed } from "#context/keys.js";
import type {
AgentActionTraceState,
@@ -30,7 +31,15 @@ const AgentTraceContextKey = new ContextKey<AgentTraceContextState>("eve.harness
export function readCurrentSessionTraceDecision(
sessionId: string,
): InstrumentationDecision | undefined {
- return contextStorage.getStore()?.get(AgentTraceContextKey)?.sessions[sessionId]?.decision;
+ const context = contextStorage.getStore();
+ return context === undefined ? undefined : readSessionTraceDecision(context, sessionId);
+}
+
+export function readSessionTraceDecision(
+ context: ContextAccessor,
+ sessionId: string,
+): InstrumentationDecision | undefined {
+ return context.get(AgentTraceContextKey)?.sessions[sessionId]?.decision;
}
/** Keeps only framework trace state from an interrupted step's context changes. */
diff --git a/packages/eve/src/tracing/agent-trace-state.ts b/packages/eve/src/tracing/agent-trace-state.ts
index cbb7748e0..f66171903 100644
--- a/packages/eve/src/tracing/agent-trace-state.ts
+++ b/packages/eve/src/tracing/agent-trace-state.ts
@@ -5,7 +5,7 @@ import type {
InstrumentationTraceContext,
InstrumentationTurnFailedEvent,
InstrumentationTurnSettledEvent,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.test.ts b/packages/eve/src/tracing/install-instrumentation-runtime.test.ts
index d56ad362a..3e51681e0 100644
--- a/packages/eve/src/tracing/install-instrumentation-runtime.test.ts
+++ b/packages/eve/src/tracing/install-instrumentation-runtime.test.ts
@@ -1,7 +1,7 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
-import { turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+import { turnIdempotencyKey } from "#instrumentation/lifecycle.js";
import { installInstrumentationRuntime } from "#tracing/install-instrumentation-runtime.js";
import { otelIntegration, collectOtelPipeline } from "#tracing/otel-declaration.js";
diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.ts b/packages/eve/src/tracing/install-instrumentation-runtime.ts
index 1c33f660e..39adb343a 100644
--- a/packages/eve/src/tracing/install-instrumentation-runtime.ts
+++ b/packages/eve/src/tracing/install-instrumentation-runtime.ts
@@ -4,11 +4,11 @@ import type { SpanProcessor } from "#compiled/@vercel/otel/index.js";
import {
createInstrumentationHooks,
type InstrumentationProviderDefinition,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import {
registerInstrumentationRuntime,
type InstrumentationRuntime,
-} from "#harness/instrumentation/runtime.js";
+} from "#instrumentation/runtime.js";
import { createLogger, formatError } from "#internal/logging.js";
import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import { ContextAgentTraceStateStore } from "#tracing/agent-trace-context-store.js";
diff --git a/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts b/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts
index bd6c42626..8a0088451 100644
--- a/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts
+++ b/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts
@@ -13,15 +13,15 @@ import {
trace as runtimeTrace,
} from "#compiled/@opentelemetry/api/index.js";
import { ContextContainer, contextStorage } from "#context/container.js";
-import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";
+import { createAiSdkHookBridge } from "#instrumentation/ai-sdk-hook-bridge.js";
import { listLocalTraces } from "#tracing/local-trace-reader.js";
-import type { InstrumentationAttemptScope } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationAttemptScope } from "#instrumentation/lifecycle.js";
import {
actionIdempotencyKey,
attemptIdempotencyKey,
sessionIdempotencyKey,
turnIdempotencyKey,
-} from "#harness/instrumentation/lifecycle.js";
+} from "#instrumentation/lifecycle.js";
import { installLocalInstrumentationRuntime } from "#tracing/local-instrumentation-runtime.js";
import { LocalTraceSpanProcessor } from "#tracing/local-trace-span-processor.js";
diff --git a/packages/eve/src/tracing/local-instrumentation-runtime.ts b/packages/eve/src/tracing/local-instrumentation-runtime.ts
index 905547fb1..99cbe0f72 100644
--- a/packages/eve/src/tracing/local-instrumentation-runtime.ts
+++ b/packages/eve/src/tracing/local-instrumentation-runtime.ts
@@ -1,7 +1,7 @@
import {
getInstrumentationRuntime,
type InstrumentationRuntime,
-} from "#harness/instrumentation/runtime.js";
+} from "#instrumentation/runtime.js";
import { installInstrumentationRuntime } from "#tracing/install-instrumentation-runtime.js";
import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";
import {
diff --git a/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts b/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts
index dc54ade9c..4cec5c973 100644
--- a/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts
+++ b/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts
@@ -200,8 +200,7 @@ describe("writeCompiledArtifactsFiles", () => {
// The plugin resolves the registry by absolute path while the assertion
// resolves it by package alias, so this also proves the globalThis rooting
// survives two module instances.
- const { getInstrumentationProviders } =
- await import("../../src/harness/instrumentation/providers.js");
+ const { getInstrumentationProviders } = await import("../../src/instrumentation/providers.js");
expect((globalThis as Record<string, unknown>).__eveProviderSetups).toEqual([
"local:compiled-artifacts-providers-test-agent",
diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjs
index 4953d16c8..117aaeb57 100644
--- a/scripts/guard-invariants.mjs
+++ b/scripts/guard-invariants.mjs
@@ -92,11 +92,10 @@
* authoring roots, every historical epoch must be supported or
* dropped, every retained epoch needs a compiling fixture, and
* every public authoring value must belong to a capability.
- * rule 37 — The instrumentation lifecycle contract stays provider-neutral.
- * `harness/instrumentation/lifecycle.ts` must not import from
- * `ai`: its event payloads are eve's published shape, so deriving
- * them from the model SDK's callback types would make an SDK
- * upgrade a breaking change for every provider. Map at the bridge.
+ * rule 37 — Instrumentation ownership stays provider-neutral and outside the
+ * harness. The lifecycle contract must not import from `ai`, harness
+ * code may import only runtime facade types, and execution may use
+ * only runtime entrypoints and cancellation-state preservation.
* rule 38 — Workspace build scripts must not launch a nested
* `pnpm --filter eve build`. Turbo owns workspace dependency
* ordering; nested builds race on eve's clean-and-publish dist
@@ -358,7 +357,23 @@ function checkRule35(posix, lines, violations) {
// ---------- Rule 37: instrumentation lifecycle provider boundary ----------
-const INSTRUMENTATION_LIFECYCLE_CONTRACT = "packages/eve/src/harness/instrumentation/lifecycle.ts";
+const INSTRUMENTATION_LIFECYCLE_CONTRACT = "packages/eve/src/instrumentation/lifecycle.ts";
+const HARNESS_RUNTIME_IMPORTS = new Map([
+ ["InstrumentationAttempt", "type"],
+ ["InstrumentationStepScope", "type"],
+ ["SessionInstrumentation", "type"],
+]);
+const EXECUTION_INSTRUMENTATION_IMPORTS = new Map([
+ [
+ "#instrumentation/runtime.js",
+ new Map([
+ ["bindSessionInstrumentation", "value"],
+ ["ExecutionInstrumentation", "type"],
+ ["initializeSessionInstrumentation", "value"],
+ ]),
+ ],
+ ["#instrumentation/state.js", new Map([["preserveSerializedInstrumentationState", "value"]])],
+]);
/**
* @param {string} posix
@@ -366,7 +381,15 @@ const INSTRUMENTATION_LIFECYCLE_CONTRACT = "packages/eve/src/harness/instrumenta
* @param {Violation[]} violations
*/
function checkRule37(posix, source, violations) {
- if (posix !== INSTRUMENTATION_LIFECYCLE_CONTRACT) return;
+ const productionHarness =
+ posix.startsWith("packages/eve/src/harness/") &&
+ !/\.(?:test|integration\.test|scenario\.test)\.ts$/.test(posix);
+ const productionExecution =
+ posix.startsWith("packages/eve/src/execution/") &&
+ !/\.(?:test|integration\.test|scenario\.test)\.ts$/.test(posix);
+ if (posix !== INSTRUMENTATION_LIFECYCLE_CONTRACT && !productionHarness && !productionExecution) {
+ return;
+ }
const sourceFile = ts.createSourceFile(
posix,
@@ -377,7 +400,11 @@ function checkRule37(posix, source, violations) {
);
const visit = (node) => {
const specifier = importSpecifier(node);
- if (specifier !== undefined && (specifier.text === "ai" || specifier.text.startsWith("ai/"))) {
+ if (
+ posix === INSTRUMENTATION_LIFECYCLE_CONTRACT &&
+ specifier !== undefined &&
+ (specifier.text === "ai" || specifier.text.startsWith("ai/"))
+ ) {
violations.push({
rule: 37,
file: posix,
@@ -385,11 +412,86 @@ function checkRule37(posix, source, violations) {
message: `imports from "ai". Lifecycle event payloads are eve's own shape, so an AI SDK type reaching them makes an SDK upgrade a breaking change for every provider. Add an eve type here and map to it in ai-sdk-hook-bridge.ts.`,
});
}
+ if (
+ productionHarness &&
+ specifier?.text.startsWith("#instrumentation/") === true &&
+ specifier.text !== "#instrumentation/runtime.js"
+ ) {
+ violations.push({
+ rule: 37,
+ file: posix,
+ line: sourceFile.getLineAndCharacterOfPosition(specifier.getStart(sourceFile)).line + 1,
+ message: `imports "${specifier.text}" directly. Harness code may consume instrumentation only through the bound SessionInstrumentation facade from "#instrumentation/runtime.js".`,
+ });
+ }
+ if (productionHarness && specifier?.text.startsWith("#tracing/") === true) {
+ violations.push({
+ rule: 37,
+ file: posix,
+ line: sourceFile.getLineAndCharacterOfPosition(specifier.getStart(sourceFile)).line + 1,
+ message: `imports "${specifier.text}" directly. Tracing implementation belongs behind the bound instrumentation facade.`,
+ });
+ }
+ if (
+ productionHarness &&
+ specifier?.text === "#instrumentation/runtime.js" &&
+ !hasOnlyAllowedNamedImports(node, HARNESS_RUNTIME_IMPORTS)
+ ) {
+ violations.push({
+ rule: 37,
+ file: posix,
+ line: sourceFile.getLineAndCharacterOfPosition(specifier.getStart(sourceFile)).line + 1,
+ message: `imports unsupported instrumentation runtime bindings. Harness code may use only the SessionInstrumentation, InstrumentationStepScope, and InstrumentationAttempt types.`,
+ });
+ }
+ if (productionHarness && specifier?.text.startsWith("#compiled/@opentelemetry/") === true) {
+ violations.push({
+ rule: 37,
+ file: posix,
+ line: sourceFile.getLineAndCharacterOfPosition(specifier.getStart(sourceFile)).line + 1,
+ message: `imports OpenTelemetry directly. OTel implementation belongs behind the bound instrumentation facade.`,
+ });
+ }
+ if (
+ productionExecution &&
+ specifier?.text.startsWith("#instrumentation/") === true &&
+ !hasOnlyAllowedNamedImports(
+ node,
+ EXECUTION_INSTRUMENTATION_IMPORTS.get(specifier.text) ?? new Map(),
+ )
+ ) {
+ violations.push({
+ rule: 37,
+ file: posix,
+ line: sourceFile.getLineAndCharacterOfPosition(specifier.getStart(sourceFile)).line + 1,
+ message: `imports unsupported instrumentation bindings from "${specifier.text}". Execution may use only session binding/initialization, the ExecutionInstrumentation type, and cancellation-state preservation.`,
+ });
+ }
ts.forEachChild(node, visit);
};
visit(sourceFile);
}
+function hasOnlyAllowedNamedImports(node, allowed) {
+ if (!ts.isImportDeclaration(node)) return false;
+ const clause = node.importClause;
+ if (
+ clause === undefined ||
+ clause.name !== undefined ||
+ clause.namedBindings === undefined ||
+ !ts.isNamedImports(clause.namedBindings) ||
+ clause.namedBindings.elements.length === 0
+ ) {
+ return false;
+ }
+ return clause.namedBindings.elements.every((element) => {
+ const imported = element.propertyName?.text ?? element.name.text;
+ const expectedKind = allowed.get(imported);
+ const actualKind = clause.isTypeOnly || element.isTypeOnly ? "type" : "value";
+ return expectedKind === actualKind;
+ });
+}
+
function importSpecifier(node) {
if (
(ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&