The Open Framework for Building Agents
feat(eve): establish agent trace identity before workflow startup (#2494)
Chad Hietala2be67fac78fb
diff --git a/.changeset/eve-preallocate-session-trace.md b/.changeset/eve-preallocate-session-trace.mdnew file mode 100644index 000000000..fccc99807--- /dev/null+++ b/.changeset/eve-preallocate-session-trace.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Agent trace identity is now established before workflow execution begins, allowing workflow runs and OpenTelemetry spans to refer to the same trace from the outset. Delegated agents inherit the parent trace, while already-running sessions retain their current behavior.diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.tsindex f1d31ea0a..e27d7f492 100644--- a/packages/eve/src/context/keys.ts+++ b/packages/eve/src/context/keys.ts@@ -95,6 +95,14 @@ export const ModeKey = new ContextKey<RunMode>("eve.mode");export const ParentSessionKey = new ContextKey<SessionParent>("eve.parentSession");/** Separate from {@link ParentSessionKey} so it stays out of what extensions read. */export const ParentTraceContextKey = new ContextKey<SessionTraceContext>("eve.parentTraceContext");++export interface SessionTraceSeed {+ readonly traceId: string;+ readonly spanId: string;+ readonly traceFlags: number;+}+export const SessionTraceSeedKey = new ContextKey<SessionTraceSeed>("eve.sessionTraceSeed");+export const SubagentDepthKey = new ContextKey<number>("eve.subagentDepth");/**diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.tsindex a2c0a00a2..68eb0bf9a 100644--- a/packages/eve/src/execution/workflow-runtime.test.ts+++ b/packages/eve/src/execution/workflow-runtime.test.ts@@ -11,6 +11,8 @@ import {workflowEntryReference,} from "#execution/workflow-runtime.js";import { sessionCommandHookToken } from "#execution/session-command-token.js";+import { registerInstrumentationRuntime } from "#harness/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";@@ -630,3 +632,180 @@ describe("createWorkflowRuntime#createSession", () => {expect(getReadable).toHaveBeenCalledTimes(1);});});++describe("createWorkflowRuntime#createSession trace seed allocation", () => {+ const adapter: ChannelAdapter = { kind: "http" };++ function buildRuntime() {+ return createWorkflowRuntime({ compiledArtifactsSource: {} as RuntimeCompiledArtifactsSource });+ }++ function mockBundleAndRun(): void {+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({+ compiledArtifactsSource: {},+ resolvedAgent: { config: {} },+ turnAgent: {+ id: "test-agent",+ instructions: [],+ model: { id: "openai/gpt-5.5" },+ tools: [],+ workspaceSpec: { rootEntries: [] },+ },+ } as never);+ getHookByTokenMock.mockResolvedValue({ runId: "driver-run" });+ getRunMock.mockReturnValue({+ getReadable: () =>+ new ReadableStream<Uint8Array>({+ start(controller) {+ controller.close();+ },+ }),+ });+ }++ function installAgentOtelRuntime(+ idGenerator: AgentSpanIdGenerator,+ tracePolicy: () => boolean,+ ): void {+ registerInstrumentationRuntime({+ forceFlush: async () => undefined,+ hooks: undefined as never,+ idGenerator,+ otelSettings: {+ tracePolicy,+ recordInputs: false,+ recordOutputs: false,+ traceChannelRequests: false,+ },+ prepareSessionTrace: vi.fn().mockResolvedValue(undefined),+ runInContext: (_op: never, fn: () => unknown) => fn(),+ shutdown: async () => undefined,+ } as never);+ }++ afterEach(() => {+ const global = globalThis as Record<symbol, unknown>;+ delete global[Symbol.for("eve.instrumentation-runtime")];+ });++ it("allocates a sampled trace seed when the policy is sampled", async () => {+ const idGenerator = new AgentSpanIdGenerator();+ installAgentOtelRuntime(idGenerator, () => true);+ mockBundleAndRun();+ startMock.mockResolvedValue({ runId: "driver-run" });++ await buildRuntime().createSession({+ adapter,+ auth: null,+ channelMetadata: { kind: "http", metadata: { audience: "public" } },+ input: { message: "hello" },+ mode: "conversation",+ });++ const [, workflowInput] = startMock.mock.calls[0]!;+ const serialized = workflowInput[0].serializedContext as Record<string, unknown>;+ const seed = serialized["eve.sessionTraceSeed"] as+ | { traceId: string; traceFlags: number }+ | undefined;+ expect(seed).toBeDefined();+ expect(seed!.traceFlags).toBe(1);+ expect(seed!.traceId).toMatch(/^[0-9a-f]{32}$/u);+ });++ it("allocates an unsampled trace seed when the policy is unsampled", async () => {+ installAgentOtelRuntime(new AgentSpanIdGenerator(), () => false);+ mockBundleAndRun();+ startMock.mockResolvedValue({ runId: "driver-run" });++ await buildRuntime().createSession({+ adapter,+ auth: null,+ channelMetadata: { kind: "http", metadata: { audience: "private" } },+ input: { message: "hello" },+ mode: "conversation",+ });++ const [, workflowInput] = startMock.mock.calls[0]!;+ const serialized = workflowInput[0].serializedContext as Record<string, unknown>;+ const seed = serialized["eve.sessionTraceSeed"] as+ | { traceId: string; traceFlags: number }+ | undefined;+ expect(seed).toBeDefined();+ expect(seed!.traceFlags).toBe(0);+ });++ it("inherits the parent trace context for delegated subagents", async () => {+ installAgentOtelRuntime(new AgentSpanIdGenerator(), () => false);+ mockBundleAndRun();++ const parentTrace = { spanId: "c".repeat(16), traceFlags: 1, traceId: "d".repeat(32) };+ startMock.mockResolvedValue({ runId: "child-run" });+ getHookByTokenMock.mockResolvedValue({ runId: "child-run" });+ await buildRuntime().createSession({+ adapter: { kind: "subagent" },+ auth: null,+ input: { message: "research" },+ mode: "task",+ parent: {+ callId: "call-1",+ rootSessionId: "root-session",+ sessionId: "parent-session",+ turn: { id: "turn-1", sequence: 1 },+ },+ parentTraceContext: parentTrace,+ });++ const [, workflowInput] = startMock.mock.calls[0]!;+ const serialized = workflowInput[0].serializedContext as Record<string, unknown>;+ const seed = serialized["eve.sessionTraceSeed"] as+ | { traceId: string; spanId: string; traceFlags: number }+ | undefined;+ expect(seed).toEqual(parentTrace);+ });++ it("does not allocate a seed when no instrumentation runtime is installed", async () => {+ mockBundleAndRun();+ startMock.mockResolvedValue({ runId: "driver-run" });++ await buildRuntime().createSession({+ adapter,+ auth: null,+ input: { message: "hello" },+ mode: "conversation",+ });++ const [, workflowInput] = startMock.mock.calls[0]!;+ const serialized = workflowInput[0].serializedContext as Record<string, unknown>;+ expect(serialized["eve.sessionTraceSeed"]).toBeUndefined();+ });++ it("does not allocate a seed when the runtime has no prepareSessionTrace", async () => {+ registerInstrumentationRuntime({+ forceFlush: async () => undefined,+ hooks: undefined as never,+ idGenerator: new AgentSpanIdGenerator(),+ otelSettings: {+ tracePolicy: () => true,+ recordInputs: false,+ recordOutputs: false,+ traceChannelRequests: false,+ },+ runInContext: (_op: never, fn: () => unknown) => fn(),+ shutdown: async () => undefined,+ } as never);+ mockBundleAndRun();+ startMock.mockResolvedValue({ runId: "driver-run" });++ await buildRuntime().createSession({+ adapter,+ auth: null,+ channelMetadata: { kind: "http", metadata: { audience: "public" } },+ input: { message: "hello" },+ mode: "conversation",+ });++ const [, workflowInput] = startMock.mock.calls[0]!;+ const serialized = workflowInput[0].serializedContext as Record<string, unknown>;+ expect(serialized["eve.sessionTraceSeed"]).toBeUndefined();+ });+});diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex c05edf25f..3c429ac50 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -18,6 +18,11 @@ import type {SessionCommandResult,} from "#channel/types.js";import { serializeContext } from "#context/serialize.js";+import {+ ChannelInstrumentationKey,+ SessionTraceSeedKey,+ type SessionTraceSeed,+} from "#context/keys.js";import {buildSessionAttributes,buildSubagentRootAttributes,@@ -50,6 +55,9 @@ 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 { evaluateTracePolicy } from "#tracing/sampled-trace.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";const WORKFLOW_ENTRY_NAME = "workflowEntry";const TURN_WORKFLOW_NAME = "turnWorkflow";@@ -138,6 +146,14 @@ export function createWorkflowRuntime(config: {run: input,});const effectiveAgent = resolveEffectiveAgentRuntime(bundle, ctx);+ const traceSeed = allocateSessionTraceSeed({+ agentName: effectiveAgent.turnAgent.id,+ audience: normalizeChannelAudience(ctx.get(ChannelInstrumentationKey)?.metadata.audience),+ parentTraceContext: input.parentTraceContext,+ });+ if (traceSeed !== undefined) {+ ctx.set(SessionTraceSeedKey, traceSeed);+ }const serializedContext = serializeContext(ctx);const parentLineage = readParentLineage(serializedContext);const sessionTimeoutMs = effectiveAgent.limits?.sessionTimeoutMs;@@ -433,3 +449,33 @@ function normalizeWorkflowHook(value: unknown): WorkflowHookRecord {runId,};}++function allocateSessionTraceSeed(input: {+ readonly agentName?: string;+ readonly audience: ReturnType<typeof normalizeChannelAudience>;+ readonly parentTraceContext?: {+ readonly traceId: string;+ readonly spanId: string;+ readonly traceFlags: number;+ };+}): SessionTraceSeed | undefined {+ if (input.parentTraceContext !== undefined) {+ return {+ 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 sampled = evaluateTracePolicy(instrumentation.otelSettings?.tracePolicy, {+ agentName: input.agentName,+ audience: input.audience,+ });+ return {+ spanId: instrumentation.idGenerator.allocateSpanId(),+ traceFlags: sampled ? 1 : 0,+ traceId: instrumentation.idGenerator.generateTraceId(),+ };+}diff --git a/packages/eve/src/execution/workflow-trace-context.ts b/packages/eve/src/execution/workflow-trace-context.tsindex 264d64428..437b9a95f 100644--- a/packages/eve/src/execution/workflow-trace-context.ts+++ b/packages/eve/src/execution/workflow-trace-context.ts@@ -3,6 +3,7 @@ import {ChannelInstrumentationKey,ParentSessionKey,ParentTraceContextKey,+ SessionTraceSeedKey,} from "#context/keys.js";import type { HarnessEmissionState } from "#harness/emission.js";import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";@@ -32,6 +33,7 @@ export async function prepareWorkflowPreambleTrace(input: {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/channel-delivery-instrumentation.ts b/packages/eve/src/harness/channel-delivery-instrumentation.tsindex 0b640b02b..46d256c5e 100644--- a/packages/eve/src/harness/channel-delivery-instrumentation.ts+++ b/packages/eve/src/harness/channel-delivery-instrumentation.ts@@ -4,6 +4,7 @@ import {ActiveChannelDeliveriesKey,ChannelInstrumentationKey,ParentTraceContextKey,+ SessionTraceSeedKey,type ActiveChannelDelivery,} from "#context/keys.js";import type {@@ -108,6 +109,7 @@ export async function instrumentChannelDelivery(parentTraceContext: input.ctx.get(ParentTraceContextKey),rootSessionId: input.rootSessionId,sessionId: input.sessionId,+ traceSeed: input.ctx.get(SessionTraceSeedKey),type: "channel.delivery.started",});}diff --git a/packages/eve/src/harness/instrumentation/lifecycle.ts b/packages/eve/src/harness/instrumentation/lifecycle.tsindex b09629d91..5a2b1e522 100644--- a/packages/eve/src/harness/instrumentation/lifecycle.ts+++ b/packages/eve/src/harness/instrumentation/lifecycle.ts@@ -187,6 +187,7 @@ interface InstrumentationChannelDeliveryScope {readonly rootSessionId: string;readonly sequence?: number;readonly sessionId: string;+ readonly traceSeed?: InstrumentationTraceContext;readonly turnId?: string;}@@ -291,6 +292,7 @@ export interface InstrumentationSessionStartedEvent {readonly parentTraceContext?: InstrumentationTraceContext;readonly rootSessionId: string;readonly sessionId: string;+ readonly traceSeed?: InstrumentationTraceContext;}export type InstrumentationTraceContext = RuntimeTraceContext;diff --git a/packages/eve/src/harness/instrumentation/runtime.ts b/packages/eve/src/harness/instrumentation/runtime.tsindex 188ca6aa8..4871c6c7d 100644--- a/packages/eve/src/harness/instrumentation/runtime.ts+++ b/packages/eve/src/harness/instrumentation/runtime.ts@@ -5,6 +5,7 @@ import type {InstrumentationTraceContext,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");@@ -13,6 +14,7 @@ const INSTRUMENTATION_RUNTIME_KEY = Symbol.for("eve.instrumentation-runtime");export interface InstrumentationRuntime {readonly forceFlush: () => Promise<void>;readonly hooks: InstrumentationHooks;+ readonly idGenerator?: AgentSpanIdGenerator;readonly prepareSessionTrace?: (event: InstrumentationSessionStartedEvent,) => Promise<InstrumentationTraceContext>;@@ -20,7 +22,6 @@ export interface InstrumentationRuntime {event: InstrumentationTurnStartedEvent,) => Promise<InstrumentationTraceContext>;otelSettings: OtelHarnessSettings | undefined;- /** Provider `runtimeContext` resolvers, collected at install time. */readonly runtimeContextResolvers?: readonly RuntimeContextResolver[];readonly runInContext: InstrumentationContextRunner;readonly shutdown: () => Promise<void>;diff --git a/packages/eve/src/harness/prepare-trace-context.ts b/packages/eve/src/harness/prepare-trace-context.tsindex d8c1d6735..1a9733ec9 100644--- a/packages/eve/src/harness/prepare-trace-context.ts+++ b/packages/eve/src/harness/prepare-trace-context.ts@@ -7,6 +7,7 @@ import type {import { sessionIdempotencyKey, turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";import type { HarnessInstrumentation } from "#harness/instrumentation/runtime.js";import type { ChannelAudience } from "#shared/channel-audience.js";+import type { SessionTraceSeed } from "#context/keys.js";const log = createLogger("harness.prepare-trace-context");@@ -22,6 +23,7 @@ export async function prepareTurnTraceContext(input: {readonly sessionId: string;readonly sessionStarted: boolean;readonly traceContext?: RuntimeTraceContext;+ readonly traceSeed?: SessionTraceSeed;readonly turnId: string;}): Promise<RuntimeTraceContext | undefined> {let prepared: RuntimeTraceContext | undefined;@@ -35,6 +37,7 @@ export async function prepareTurnTraceContext(input: {parentTraceContext: input.parentTraceContext,rootSessionId: input.rootSessionId,sessionId: input.sessionId,+ traceSeed: input.traceSeed,type: "session.started",});} catch (error) {diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex b3081551c..c4e789312 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -37,6 +37,7 @@ import {ParentSessionKey,ParentTraceContextKey,SessionCallbackKey,+ SessionTraceSeedKey,TurnTaskDeliveryKey,TurnTaskStateKey,} from "#context/keys.js";@@ -671,6 +672,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {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,@@ -741,6 +743,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {sessionId: session.sessionId,sessionStarted: emissionState.sessionStarted,traceContext: authoredTraceContext,+ traceSeed,turnId: `turn_${emissionState.sequence}`,});};diff --git a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.tsindex 9da8c11a8..67932744a 100644--- a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts+++ b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts@@ -61,6 +61,7 @@ export function createAgentChannelDeliveryInstrumentation(input: {parentTraceContext: event.parentTraceContext,rootSessionId: event.rootSessionId,sessionId: event.sessionId,+ traceSeed: event.traceSeed,type: "session.started",});if (!isSampledTrace(session.context)) return;diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.tsindex a8dd88e78..8c7b29932 100644--- a/packages/eve/src/tracing/agent-otel-provider.test.ts+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts@@ -383,6 +383,124 @@ describe("createAgentOtelInstrumentation", () => {expect(turn.parentSpanContext?.spanId).toBe(turnTrace.spanId);});+ it("uses the pre-allocated trace seed's trace id for agent.session", async () => {+ const runtime = createRuntime();+ const seed: InstrumentationTraceContext = {+ spanId: "a".repeat(16),+ traceFlags: 1,+ traceId: "b".repeat(32),+ };+ const sessionEvent = {+ agentName: "weather",+ idempotencyKey: sessionIdempotencyKey("session-seed"),+ rootSessionId: "session-seed",+ sessionId: "session-seed",+ traceSeed: seed,+ type: "session.started" as const,+ };++ await runtime.prepareSessionTrace(sessionEvent);+ await runtime.hooks.publish(sessionEvent);+ await runtime.provider.forceFlush();++ const spans = runtime.exporter.getFinishedSpans();+ const session = byName(spans, "agent.session")[0]!;+ expect(session.spanContext().traceId).toBe(seed.traceId);+ expect(session.spanContext().spanId).toBe(seed.spanId);+ });++ it("falls back to fresh ids when no trace seed is present", async () => {+ const runtime = createRuntime();+ const sessionEvent = {+ agentName: "weather",+ idempotencyKey: sessionIdempotencyKey("session-noseed"),+ rootSessionId: "session-noseed",+ sessionId: "session-noseed",+ type: "session.started" as const,+ };++ const trace = await runtime.prepareSessionTrace(sessionEvent);+ await runtime.hooks.publish(sessionEvent);+ await runtime.provider.forceFlush();++ const spans = runtime.exporter.getFinishedSpans();+ const session = byName(spans, "agent.session")[0]!;+ expect(session.spanContext().traceId).toBe(trace.traceId);+ // Fresh span id is random, not derived — just verify it matches the returned context.+ expect(session.spanContext().spanId).toBe(trace.spanId);+ });++ it("inherits parent trace context for delegated agents", async () => {+ const runtime = createRuntime();+ const parentTrace: InstrumentationTraceContext = {+ spanId: "c".repeat(16),+ traceFlags: 1,+ traceId: "d".repeat(32),+ };+ const sessionEvent = {+ agentName: "researcher",+ idempotencyKey: sessionIdempotencyKey("session-child"),+ parentTraceContext: parentTrace,+ rootSessionId: "root-session",+ sessionId: "session-child",+ type: "session.started" as const,+ };++ const trace = await runtime.prepareSessionTrace(sessionEvent);+ expect(trace.traceId).toBe(parentTrace.traceId);+ expect(trace.spanId).toBe(parentTrace.spanId);+ });++ it("treats the seed as authoritative when late policy would reject", async () => {+ const runtime = createRuntime(undefined, () => false);+ const seed: InstrumentationTraceContext = {+ spanId: "a".repeat(16),+ traceFlags: 1,+ traceId: "b".repeat(32),+ };+ const sessionEvent = {+ agentName: "weather",+ idempotencyKey: sessionIdempotencyKey("session-seed-authoritative"),+ rootSessionId: "session-seed-authoritative",+ sessionId: "session-seed-authoritative",+ traceSeed: seed,+ type: "session.started" as const,+ };++ await runtime.prepareSessionTrace(sessionEvent);+ await runtime.hooks.publish(sessionEvent);+ await runtime.provider.forceFlush();++ const spans = runtime.exporter.getFinishedSpans();+ const session = byName(spans, "agent.session")[0]!;+ expect(session.spanContext().traceId).toBe(seed.traceId);+ expect(session.spanContext().traceFlags).toBe(1);+ });++ it("treats an unsampled seed as authoritative when late policy would accept", async () => {+ const runtime = createRuntime();+ const seed: InstrumentationTraceContext = {+ spanId: "e".repeat(16),+ traceFlags: 0,+ traceId: "f".repeat(32),+ };+ const sessionEvent = {+ agentName: "weather",+ idempotencyKey: sessionIdempotencyKey("session-seed-unsampled"),+ rootSessionId: "session-seed-unsampled",+ sessionId: "session-seed-unsampled",+ traceSeed: seed,+ type: "session.started" as const,+ };++ await runtime.prepareSessionTrace(sessionEvent);+ await runtime.hooks.publish(sessionEvent);+ await runtime.provider.forceFlush();++ const spans = runtime.exporter.getFinishedSpans();+ expect(byName(spans, "agent.session")).toHaveLength(0);+ });+it.each([["cancelled", SpanStatusCode.UNSET],["failed", SpanStatusCode.ERROR],@@ -680,7 +798,7 @@ describe("createAgentOtelInstrumentation", () => {},);- it("applies the private audience gate to an adopted sampled trace", async () => {+ it("preserves the parent's sampling decision for adopted traces", async () => {const runtime = createRuntime(new InMemoryAgentTraceStateStore(), null);await emitAttempt({@@ -698,7 +816,12 @@ describe("createAgentOtelInstrumentation", () => {});await runtime.provider.forceFlush();- expect(runtime.exporter.getFinishedSpans()).toEqual([]);+ // The parent's traceFlags are authoritative — the child does not re-evaluate.+ const spans = runtime.exporter.getFinishedSpans();+ expect(spans.length).toBeGreaterThan(0);+ for (const span of spans) {+ expect(span.spanContext().traceId).toBe("b".repeat(32));+ }});it("allows private tracing when the trace policy opts in", async () => {@@ -1712,3 +1835,31 @@ describe("createAgentOtelInstrumentation", () => {expect(byName(spans, "agent.turn")[0]!.status.code).toBe(SpanStatusCode.UNSET);});});++describe("AgentSpanIdGenerator.withTraceId", () => {+ it("primes the next generateTraceId call", () => {+ const gen = new AgentSpanIdGenerator();+ const primed = "e".repeat(32);+ const result = gen.withTraceId(primed, () => gen.generateTraceId());+ expect(result).toBe(primed);+ // After the callback, a fresh call should produce a different id.+ const next = gen.generateTraceId();+ expect(next).not.toBe(primed);+ });++ it("nests inside withSpanId to prime both ids", () => {+ const gen = new AgentSpanIdGenerator();+ const primedTraceId = "f".repeat(32);+ const primedSpanId = "a".repeat(16);+ let capturedTraceId: string | undefined;+ let capturedSpanId: string | undefined;+ gen.withSpanId(primedSpanId, () =>+ gen.withTraceId(primedTraceId, () => {+ capturedTraceId = gen.generateTraceId();+ capturedSpanId = gen.generateSpanId();+ }),+ );+ expect(capturedTraceId).toBe(primedTraceId);+ expect(capturedSpanId).toBe(primedSpanId);+ });+});diff --git a/packages/eve/src/tracing/agent-otel-session-context.ts b/packages/eve/src/tracing/agent-otel-session-context.tsindex 17c2651b8..a1028c970 100644--- a/packages/eve/src/tracing/agent-otel-session-context.ts+++ b/packages/eve/src/tracing/agent-otel-session-context.ts@@ -10,6 +10,7 @@ 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";import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";+import { evaluateTracePolicy, isSampledTrace } from "#tracing/sampled-trace.js";import type { AgentSessionTraceState, AgentTraceStateStore } from "#tracing/agent-trace-state.js";interface AgentOtelSessionContextInput {@@ -40,8 +41,43 @@ export function createAgentOtelSessionContext(readonly channelAudience: ChannelAudience;readonly rootSessionId: string;readonly sessionId: string;+ readonly traceSeed?: InstrumentationTraceContext;}): SpanContext => {- if (!shouldTrace(input.tracePolicy, session)) {+ if (session.traceSeed !== undefined) {+ if (!isSampledTrace(session.traceSeed)) {+ return {+ isRemote: false,+ spanId: session.traceSeed.spanId,+ traceFlags: 0,+ traceId: session.traceSeed.traceId,+ };+ }+ const startSpan = () =>+ input.tracer.startSpan("agent.session", {+ attributes: {+ "agent.framework.name": "eve",+ "agent.framework.version": input.frameworkVersion,+ "agent.channel.audience": session.channelAudience,+ "agent.name": session.agentName,+ "agent.session.id": session.sessionId,+ "agent.trace.schema.version": 2,+ },+ root: true,+ });+ const span = input.idGenerator.withSpanId(session.traceSeed.spanId, () =>+ input.idGenerator.withTraceId(session.traceSeed!.traceId, startSpan),+ );+ span.addEvent("session.started");+ span.end();+ return span.spanContext();+ }+ // Fallback for already-running workflows that predate the seed.+ if (+ !evaluateTracePolicy(input.tracePolicy, {+ agentName: session.agentName,+ audience: session.channelAudience,+ })+ ) {return {isRemote: false,spanId: input.idGenerator.deriveSpanId(`session:${session.sessionId}`),@@ -61,9 +97,6 @@ export function createAgentOtelSessionContext(root: true,});span.addEvent("session.started");- // The session outlives this worker and has no guaranteed close — an idle- // session never ends — so the root is recorded as a zero-duration marker- // and later spans parent through its persisted context.span.end();return span.spanContext();};@@ -84,16 +117,9 @@ export function createAgentOtelSessionContext(channelAudience: normalizeChannelAudience(event.channelAudience),rootSessionId: event.rootSessionId,sessionId: event.sessionId,+ traceSeed: event.traceSeed,})- : adoptedSpanContext(- event.parentTraceContext,- shouldTrace(input.tracePolicy, {- agentName: event.agentName,- channelAudience: normalizeChannelAudience(event.channelAudience),- rootSessionId: event.rootSessionId,- sessionId: event.sessionId,- }),- ),+ : adoptedSpanContext(event.parentTraceContext),rootSessionId: event.rootSessionId,};await input.stateStore.setSession(event.sessionId, state);@@ -153,29 +179,6 @@ export function createAgentOtelSessionContext(return { ensureSessionContext, prepareSessionTrace, prepareTurnTrace };}-function shouldTrace(- policy: TraceCapturePolicy | undefined,- trace: {- readonly agentName?: string;- readonly channelAudience: ChannelAudience;- readonly rootSessionId: string;- readonly sessionId: string;- },-): boolean {- try {- return (- policy?.({- agentName: trace.agentName,- audience: trace.channelAudience,- rootSessionId: trace.rootSessionId,- sessionId: trace.sessionId,- }) ?? trace.channelAudience === "public"- );- } catch {- return false;- }-}-function portableSpanContext(spanContext: SpanContext): InstrumentationTraceContext {return {spanId: spanContext.spanId,@@ -184,11 +187,11 @@ function portableSpanContext(spanContext: SpanContext): InstrumentationTraceCont};}-function adoptedSpanContext(handed: InstrumentationTraceContext, sampled = true): SpanContext {+function adoptedSpanContext(handed: InstrumentationTraceContext): SpanContext {return {isRemote: "isRemote" in handed && handed.isRemote === true,spanId: handed.spanId,- traceFlags: sampled ? handed.traceFlags : 0,+ traceFlags: handed.traceFlags,traceId: handed.traceId,};}diff --git a/packages/eve/src/tracing/agent-span-id-generator.ts b/packages/eve/src/tracing/agent-span-id-generator.tsindex 9e7ad0c92..5646d3663 100644--- a/packages/eve/src/tracing/agent-span-id-generator.ts+++ b/packages/eve/src/tracing/agent-span-id-generator.ts@@ -8,6 +8,7 @@ import { createHash } from "node:crypto";*/export class AgentSpanIdGenerator {#primedSpanId: string | undefined;+ #primedTraceId: string | undefined;/** Reserves a span id for a span emitted later via {@link withSpanId}. */allocateSpanId(): string {@@ -30,6 +31,11 @@ export class AgentSpanIdGenerator {}generateTraceId(): string {+ const primed = this.#primedTraceId;+ if (primed !== undefined) {+ this.#primedTraceId = undefined;+ return primed;+ }return randomHexId(32);}@@ -42,6 +48,15 @@ export class AgentSpanIdGenerator {this.#primedSpanId = undefined;}}++ withTraceId<T>(traceId: string, startSpan: () => T): T {+ this.#primedTraceId = traceId;+ try {+ return startSpan();+ } finally {+ this.#primedTraceId = undefined;+ }+ }}const HEX_DIGITS = "0123456789abcdef";diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.ts b/packages/eve/src/tracing/install-instrumentation-runtime.tsindex 7c78c5e3f..1c33f660e 100644--- a/packages/eve/src/tracing/install-instrumentation-runtime.ts+++ b/packages/eve/src/tracing/install-instrumentation-runtime.ts@@ -10,6 +10,7 @@ import {type InstrumentationRuntime,} from "#harness/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";import { createAgentOtelInstrumentation } from "#tracing/agent-otel-provider.js";import { hasSessionRelease, type LocalTracesProcessor } from "#tracing/local-traces.js";@@ -81,6 +82,7 @@ export function installInstrumentationRuntime(input: {serialAfter,serialBefore,}),+ idGenerator: otelRuntime?.idGenerator ?? new AgentSpanIdGenerator(),otelSettings: input.collected.declared ? input.collected.settings : undefined,prepareSessionTrace,prepareTurnTrace,diff --git a/packages/eve/src/tracing/local-traces.test.ts b/packages/eve/src/tracing/local-traces.test.tsindex e0bd1e850..f9ca53da3 100644--- a/packages/eve/src/tracing/local-traces.test.ts+++ b/packages/eve/src/tracing/local-traces.test.ts@@ -108,8 +108,6 @@ describe("localTracePolicy", () => {expect(localTracePolicy({audience,- rootSessionId: "session-1",- sessionId: "session-1",}),).toBe(accepted);});diff --git a/packages/eve/src/tracing/otel-declaration.ts b/packages/eve/src/tracing/otel-declaration.tsindex e14ff8b22..d821d4cd6 100644--- a/packages/eve/src/tracing/otel-declaration.ts+++ b/packages/eve/src/tracing/otel-declaration.ts@@ -107,8 +107,6 @@ export interface ContentOptions {export interface TraceCaptureContext {readonly agentName?: string;readonly audience: ChannelAudience;- readonly rootSessionId: string;- readonly sessionId: string;}export type TraceCapturePolicy = (trace: TraceCaptureContext) => boolean;diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.tsindex ccebfd272..bd22801a2 100644--- a/packages/eve/src/tracing/sampled-trace.ts+++ b/packages/eve/src/tracing/sampled-trace.ts@@ -1,5 +1,26 @@import { TraceFlags, type SpanContext } from "#compiled/@opentelemetry/api/index.js";+import type { ChannelAudience } from "#shared/channel-audience.js";+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";export function isSampledTrace(context: Pick<SpanContext, "traceFlags">): boolean {return (context.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;}++export function evaluateTracePolicy(+ policy: TraceCapturePolicy | undefined,+ trace: {+ readonly agentName?: string;+ readonly audience: ChannelAudience;+ },+): boolean {+ try {+ return (+ policy?.({+ agentName: trace.agentName,+ audience: trace.audience,+ }) ?? trace.audience === "public"+ );+ } catch {+ return false;+ }+}