The Open Framework for Building Agents
feat(eve): connect workflow runs to agent traces (#2490)
Chad Hietala7ed4fb135e85
diff --git a/.changeset/eve-trace-id-attribute.md b/.changeset/eve-trace-id-attribute.mdnew file mode 100644index 000000000..8c1d7be7e--- /dev/null+++ b/.changeset/eve-trace-id-attribute.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Workflow session, subagent, and turn rows now include `$eve.trace_id` when a sampled agent trace is available, allowing workflow views to open the corresponding OpenTelemetry trace directly. Rows without an exported agent trace omit the attribute.diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.mdindex 71c26eea6..253e79a13 100644--- a/docs/guides/instrumentation.md+++ b/docs/guides/instrumentation.md@@ -164,6 +164,7 @@ Structural tags describe each run's place in the tree:- `$eve.subagent`: compiled graph node id (subagent runs only)- `$eve.trigger`: the channel kind that started the run- `$eve.title`: truncated title derived from the first user message+- `$eve.trace_id`: trace id of the sampled agent trace containing the run, written on session, subagent, and turn rows so a dashboard run can be joined to its OpenTelemetry trace. Present only when the trace is sampled; absence means no exported OTEL trace exists.Per-turn usage tags are written on each step of a turn, accumulating cumulative totals (last write wins):diff --git a/packages/eve/src/execution/eve-workflow-attributes.test.ts b/packages/eve/src/execution/eve-workflow-attributes.test.tsindex be8b0bec1..f8ec45f12 100644--- a/packages/eve/src/execution/eve-workflow-attributes.test.ts+++ b/packages/eve/src/execution/eve-workflow-attributes.test.ts@@ -11,6 +11,7 @@ import {readParentLineage,readParentSessionId,readRootSessionId,+ readSessionTraceId,} from "#execution/eve-workflow-attributes.js";import { ChannelRequestIdKey } from "#context/keys.js";@@ -151,6 +152,7 @@ describe("buildSessionAttributes", () => {expect(attrs).toEqual({"$eve.channel_request_id": undefined,"$eve.is_trace_content_visible": true,+ "$eve.trace_id": undefined,"$eve.type": "session","$eve.trigger": "slack","$eve.title": "ship the thing please",@@ -191,6 +193,30 @@ describe("buildSessionAttributes", () => {expect(attrs["$eve.channel_request_id"]).toBe("req_session");});++ it("emits $eve.trace_id from a sampled trace seed", () => {+ const attrs = buildSessionAttributes({+ inputMessage: "hi",+ serializedContext: {+ ...slackChannelCtx,+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 1, traceId: "b".repeat(32) },+ },+ });++ expect(attrs["$eve.trace_id"]).toBe("b".repeat(32));+ });++ it("withholds $eve.trace_id from an unsampled trace seed", () => {+ const attrs = buildSessionAttributes({+ inputMessage: "hi",+ serializedContext: {+ ...slackChannelCtx,+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 0, traceId: "b".repeat(32) },+ },+ });++ expect(attrs["$eve.trace_id"]).toBeUndefined();+ });});describe("buildSubagentRootAttributes", () => {@@ -207,6 +233,7 @@ describe("buildSubagentRootAttributes", () => {expect(attrs).toEqual({"$eve.channel_request_id": undefined,"$eve.is_trace_content_visible": true,+ "$eve.trace_id": undefined,"$eve.type": "subagent","$eve.parent": "wrun_parent_subagent","$eve.parent_call": "call_subagent_0",@@ -230,6 +257,22 @@ describe("buildSubagentRootAttributes", () => {expect(attrs["$eve.channel_request_id"]).toBe("req_subagent");});++ it("emits $eve.trace_id from a sampled trace seed", () => {+ const attrs = buildSubagentRootAttributes({+ identity: { nodeId: "subagents/linear" },+ parentCallId: "call_subagent_0",+ parentSessionId: "wrun_parent_subagent",+ parentTurnId: "turn_0",+ rootSessionId: "wrun_top_level_session",+ serializedContext: {+ ...subagentChainCtx,+ "eve.sessionTraceSeed": { spanId: "e".repeat(16), traceFlags: 1, traceId: "f".repeat(32) },+ },+ });++ expect(attrs["$eve.trace_id"]).toBe("f".repeat(32));+ });});describe("buildTurnAttributes", () => {@@ -243,6 +286,7 @@ describe("buildTurnAttributes", () => {expect(attrs).toEqual({"$eve.channel_request_id": undefined,"$eve.is_trace_content_visible": true,+ "$eve.trace_id": undefined,"$eve.type": "turn","$eve.parent": "wrun_session_123","$eve.root": "wrun_session_123",@@ -259,4 +303,39 @@ describe("buildTurnAttributes", () => {expect(attrs["$eve.channel_request_id"]).toBe("req_turn");});++ it("emits $eve.trace_id from a sampled trace seed", () => {+ const attrs = buildTurnAttributes({+ parentSessionId: "wrun_session_123",+ rootSessionId: "wrun_session_123",+ serializedContext: {+ ...slackChannelCtx,+ "eve.sessionTraceSeed": { spanId: "c".repeat(16), traceFlags: 1, traceId: "d".repeat(32) },+ },+ });++ expect(attrs["$eve.trace_id"]).toBe("d".repeat(32));+ });+});++describe("readSessionTraceId", () => {+ it("returns the trace id from a sampled seed", () => {+ expect(+ readSessionTraceId({+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 1, traceId: "b".repeat(32) },+ }),+ ).toBe("b".repeat(32));+ });++ it("returns undefined for an unsampled seed", () => {+ expect(+ readSessionTraceId({+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 0, traceId: "b".repeat(32) },+ }),+ ).toBeUndefined();+ });++ it("returns undefined when no seed is present", () => {+ expect(readSessionTraceId({})).toBeUndefined();+ });});diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.tsindex 396bc370e..08bcfcc56 100644--- a/packages/eve/src/execution/eve-workflow-attributes.ts+++ b/packages/eve/src/execution/eve-workflow-attributes.ts@@ -26,10 +26,14 @@* - `$eve.invocation_token` — channel-local continuation token for an external invocation* - `$eve.invocation_owner` — SHA-256 fingerprint of the invocation's initiating principal* - `$eve.is_trace_content_visible` — whether observability may read content-bearing workflow data+ * - `$eve.trace_id` — trace id of the `agent.session` span, read from the pre-allocated+ * trace seed in the serialized context. Present only when the trace is sampled;+ * absence means no exported OTEL trace exists.*/-import { ChannelRequestIdKey } from "#context/keys.js";+import { ChannelRequestIdKey, type SessionTraceSeed } from "#context/keys.js";import { shouldCaptureInstrumentationContent } from "#harness/instrumentation/content-policy.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";@@ -88,6 +92,12 @@ export function isWorkflowTraceContentVisible(serializedContext: Record<string,return shouldCaptureInstrumentationContent(normalizeChannelAudience(channel?.audience));}+export function readSessionTraceId(serializedContext: Record<string, unknown>): string | undefined {+ const seed = serializedContext["eve.sessionTraceSeed"] as SessionTraceSeed | undefined;+ if (seed === undefined || !isSampledTrace(seed)) return undefined;+ return isNonEmptyString(seed.traceId) ? seed.traceId : undefined;+}+/*** Reads parent session lineage from a deserialized context map. Returns* an empty object for top-level runs or malformed delegated contexts.@@ -222,6 +232,7 @@ export function buildSessionAttributes(input: {return {"$eve.channel_request_id": readChannelRequestId(input.serializedContext),"$eve.is_trace_content_visible": isTraceContentVisible,+ "$eve.trace_id": readSessionTraceId(input.serializedContext),"$eve.type": "session","$eve.trigger": readChannelKind(input.serializedContext),"$eve.title": isTraceContentVisible ? deriveSessionTitle(input.inputMessage) : undefined,@@ -248,6 +259,7 @@ export function buildSubagentRootAttributes(input: {return {"$eve.channel_request_id": readChannelRequestId(input.serializedContext),"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),+ "$eve.trace_id": readSessionTraceId(input.serializedContext),"$eve.type": "subagent","$eve.parent": input.parentSessionId,"$eve.parent_call": input.parentCallId,@@ -277,6 +289,7 @@ export function buildTurnAttributes(input: {return {"$eve.channel_request_id": input.requestId,"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),+ "$eve.trace_id": readSessionTraceId(input.serializedContext),"$eve.type": "turn","$eve.parent": input.parentSessionId,"$eve.root": input.rootSessionId,diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.tsindex bd22801a2..a545e9be7 100644--- a/packages/eve/src/tracing/sampled-trace.ts+++ b/packages/eve/src/tracing/sampled-trace.ts@@ -1,9 +1,12 @@-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;+// W3C sampled flag; written as a literal so this module stays out of the+// vendored OTel chunk, which the workflow driver bundle cannot include.+const TRACE_FLAGS_SAMPLED = 0x01;++export function isSampledTrace(context: { readonly traceFlags: number }): boolean {+ return (context.traceFlags & TRACE_FLAGS_SAMPLED) === TRACE_FLAGS_SAMPLED;}export function evaluateTracePolicy(