The Open Framework for Building Agents
feat(eve): expose activation metadata in OTEL (#3338)
Chad Hietala57d6be52d9e8
diff --git a/.changeset/add-otel-activation-metadata.md b/.changeset/add-otel-activation-metadata.mdnew file mode 100644index 000000000..e75c38ee9--- /dev/null+++ b/.changeset/add-otel-activation-metadata.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add queryable metadata to activation spans, including run type, title when input capture permits, provenance, audience, schedule, and directional trace-content policy.diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.mdindex dc781dd36..8be8c3e80 100644--- a/docs/guides/instrumentation.md+++ b/docs/guides/instrumentation.md@@ -201,6 +201,19 @@ exception. Vercel deployments additionally carrytrusted remote subagents. Remote lineage is accepted only when the receiver's`trustedForwarders` predicate approves the authenticated caller. Childactivation roots carry `agent.parent_run.id` and `agent.parent_call.id`.+Activation roots also carry `agent.run.type`, `agent.channel.audience`, and+directional `agent.trace.content.input` and `agent.trace.content.output` policy+results. Root-session activations carry their initiating `agent.channel.kind`+and `agent.session.origin` (`schedule` or `channel`), plus `agent.schedule.id`+when a schedule started the session and `agent.session.title` when input+capture permits. The title repeats on every turn activation for that session+and always describes the initial session input, not a later turn. A turn with+an actual channel delivery carries that delivery's channel kind, name, and ID.+Delivery-less subagent activations omit the root-only channel kind, origin,+schedule, and title attributes; their delegation is described by+`agent.run.type` and the parent attributes. `agent.run.type` is `session` or+`subagent`; each exported content-policy boolean reflects both the resolved+trace capture decision and that destination's redaction policy.Only activations use the `invoke_agent` operation. A workflow tool invocationthat coordinates at least one nested agent uses `invoke_workflow`, with itspath-derived tool name in `gen_ai.workflow.name`. Durable workflow tools without@@ -263,14 +276,20 @@ This workflow applies to schema v4 from the [instrumentation provider layout](./### Find an activation or conversation-| Investigation | Filter |-| ------------------------ | ----------------------------------------------------------------------- |-| Agent activations | `agent.trace.schema.version=4` and `gen_ai.operation.name=invoke_agent` |-| One logical conversation | `gen_ai.conversation.id=<conversation ID>` |-| One turn | Both `gen_ai.conversation.id` and `agent.turn.id` |-| One Vercel root session | `vercel.session_id=<root session ID>` |-| One agent run | `agent.run.id=<run ID>` |-| Delegated dispatches | `agent.invocation.role=caller` |+| Investigation | Filter |+| ------------------------- | ----------------------------------------------------------------------- |+| Agent activations | `agent.trace.schema.version=4` and `gen_ai.operation.name=invoke_agent` |+| One logical conversation | `gen_ai.conversation.id=<conversation ID>` |+| One turn | Both `gen_ai.conversation.id` and `agent.turn.id` |+| One Vercel root session | `vercel.session_id=<root session ID>` |+| One agent run | `agent.run.id=<run ID>` |+| Root agent runs | `agent.run.type=session` |+| Subagent runs | `agent.run.type=subagent` |+| Scheduled root sessions | `agent.session.origin=schedule` |+| One recorded channel kind | `agent.channel.kind=<channel kind>` |+| Exported input content | `agent.trace.content.input=true` |+| Exported output content | `agent.trace.content.output=true` |+| Delegated dispatches | `agent.invocation.role=caller` |Start with an activation filter for latency, failure, or turn-count dashboards. Every activation is a trace root. Within a conversation, group by trace ID, order activations by `agent.turn.sequence` or start time, and open the selected trace ID. Child activations link to their caller with `eve.link.type=agent.dispatch`; remote workflows keep their own execution lineage, so use conversation IDs and caller links for cross-deployment correlation.diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.tsindex ebed3897f..efd21b56e 100644--- a/packages/eve/src/context/keys.ts+++ b/packages/eve/src/context/keys.ts@@ -90,6 +90,8 @@ export const LocalDevRequestKey = new ContextKey<LocalDevRequestProvenance>();/** Authored schedule whose dispatch created this session. */export const ScheduleIdKey = new ContextKey<string>("eve.scheduleId");+/** Display title derived from the session's initial input. */+export const SessionTitleKey = new ContextKey<string>("eve.sessionTitle");export const ChannelDeliveryKey = new ContextKey<ChannelDeliveryMetadata>("eve.channelDelivery");/** Accepted messages whose response owns the current turn's durable stream events. */export const TurnDeliveryIdsKey = new ContextKey<readonly string[]>("eve.turnDeliveryIds");diff --git a/packages/eve/src/execution/eve-workflow-attributes.test.ts b/packages/eve/src/execution/eve-workflow-attributes.test.tsindex b0bc1b410..7c5c54282 100644--- a/packages/eve/src/execution/eve-workflow-attributes.test.ts+++ b/packages/eve/src/execution/eve-workflow-attributes.test.ts@@ -19,6 +19,7 @@ import {ChannelInstrumentationKey,ChannelRequestIdKey,ScheduleIdKey,+ SessionTitleKey,SessionTraceSeedKey,} from "#context/keys.js";import { CHANNEL_CONTEXT_KEY_NAME } from "#context/key-names.js";@@ -43,6 +44,7 @@ const unknownConversation = {const slackChannelCtx = {"eve.channel": { kind: "slack", state: { team: "T1" } },[ConversationContextKey.name]: publicConversation,+ [SessionTitleKey.name]: "ship the thing please",} satisfies Record<string, unknown>;const subagentChainCtx = {@@ -104,7 +106,7 @@ describe("isWorkflowTraceContentVisible", () => {};expect(isWorkflowTraceContentVisible(serializedContext)).toBe(true);- expect(buildSessionAttributes({ inputMessage: "research", serializedContext })).toMatchObject({+ expect(buildSessionAttributes({ serializedContext })).toMatchObject({"$eve.is_trace_content_visible": true,});});@@ -162,7 +164,7 @@ describe("isWorkflowTraceContentVisible", () => {};expect(isWorkflowTraceContentVisible(serializedContext)).toBe(false);- expect(buildSessionAttributes({ inputMessage: "research", serializedContext })).toMatchObject({+ expect(buildSessionAttributes({ serializedContext })).toMatchObject({"$eve.is_trace_content_visible": false,});});@@ -183,7 +185,7 @@ describe("isWorkflowTraceContentVisible", () => {};expect(isWorkflowTraceContentVisible(serializedContext)).toBe(false);- expect(buildSessionAttributes({ inputMessage: "research", serializedContext })).toMatchObject({+ expect(buildSessionAttributes({ serializedContext })).toMatchObject({"$eve.is_trace_content_visible": false,});});@@ -302,9 +304,8 @@ describe("deriveSessionTitle", () => {});describe("buildSessionAttributes", () => {- it("emits type=session with trigger and derived title", () => {+ it("emits type=session with trigger and stored title", () => {const attrs = buildSessionAttributes({- inputMessage: "ship the thing please",serializedContext: slackChannelCtx,});@@ -320,10 +321,13 @@ describe("buildSessionAttributes", () => {});});+ it("omits the title when the root context has none", () => {+ expect(buildSessionAttributes({ serializedContext: {} })["$eve.title"]).toBeUndefined();+ });+it("marks unknown sessions denied while retaining their stored title", () => {const attrs = buildSessionAttributes({- inputMessage: "hi",- serializedContext: {},+ serializedContext: { [SessionTitleKey.name]: "hi" },});expect(attrs["$eve.trigger"]).toBeUndefined();@@ -334,8 +338,10 @@ describe("buildSessionAttributes", () => {it("stamps hosted OTEL enablement without suppressing the stored title", () => {const attrs = buildSessionAttributes({- inputMessage: "private prompt",- serializedContext: { "eve.otelTraceEnabled": true },+ serializedContext: {+ "eve.otelTraceEnabled": true,+ [SessionTitleKey.name]: "private prompt",+ },});expect(attrs["$eve.is_otel_trace_enabled"]).toBe(true);@@ -345,9 +351,9 @@ describe("buildSessionAttributes", () => {it("allows unknown session content in development", () => {const attrs = buildSessionAttributes({- inputMessage: "local prompt",serializedContext: {[ConversationContextKey.name]: { ...unknownConversation, environment: "development" },+ [SessionTitleKey.name]: "local prompt",},});@@ -357,7 +363,6 @@ describe("buildSessionAttributes", () => {it("emits the channel request id when present", () => {const attrs = buildSessionAttributes({- inputMessage: "hi",serializedContext: {...slackChannelCtx,[ChannelRequestIdKey.name]: "req_session",@@ -369,7 +374,6 @@ describe("buildSessionAttributes", () => {it("emits the schedule while retaining the target channel trigger", () => {const attrs = buildSessionAttributes({- inputMessage: "run the scheduled task",serializedContext: {...slackChannelCtx,[ScheduleIdKey.name]: "dynamic-tasks",@@ -382,7 +386,6 @@ describe("buildSessionAttributes", () => {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) },@@ -394,7 +397,6 @@ describe("buildSessionAttributes", () => {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) },diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.tsindex ad089fe29..fc9dde560 100644--- a/packages/eve/src/execution/eve-workflow-attributes.ts+++ b/packages/eve/src/execution/eve-workflow-attributes.ts@@ -38,6 +38,7 @@ import {ChannelRequestIdKey,OtelTraceEnabledKey,ScheduleIdKey,+ SessionTitleKey,SessionTraceSeedKey,type SessionTraceSeed,} from "#context/keys.js";@@ -193,6 +194,12 @@ export function readScheduleId(serializedContext: Record<string, unknown>): strireturn isNonEmptyString(scheduleId) ? scheduleId : undefined;}+/** Reads the bounded title stored for a top-level session. */+export function readSessionTitle(serializedContext: Record<string, unknown>): string | undefined {+ const title = serializedContext[SessionTitleKey.name];+ return isNonEmptyString(title) ? title : undefined;+}+/*** Maximum visible length (in code points) of a derived `$eve.title`.*@@ -265,7 +272,6 @@ function collectMessageText(message: unknown): string | undefined {* so its own `workflowRunId` already identifies the chain root.*/export function buildSessionAttributes(input: {- readonly inputMessage: unknown;readonly serializedContext: Record<string, unknown>;}): Record<string, EveAttributeValue> {const isTraceContentVisible = isWorkflowTraceContentVisible(input.serializedContext);@@ -278,7 +284,7 @@ export function buildSessionAttributes(input: {"$eve.trace_id": readSessionTraceId(input.serializedContext),"$eve.type": "session","$eve.trigger": readChannelKind(input.serializedContext),- "$eve.title": deriveSessionTitle(input.inputMessage),+ "$eve.title": readSessionTitle(input.serializedContext),};}diff --git a/packages/eve/src/execution/runtime-context.test.ts b/packages/eve/src/execution/runtime-context.test.tsindex 9a8283df9..be6b88806 100644--- a/packages/eve/src/execution/runtime-context.test.ts+++ b/packages/eve/src/execution/runtime-context.test.ts@@ -11,6 +11,7 @@ import {SessionIdKey,SessionKey,ScheduleIdKey,+ SessionTitleKey,} from "#context/keys.js";import { setChannelContext } from "#execution/channel-context.js";import { buildRunContext } from "#execution/runtime-context.js";@@ -203,6 +204,36 @@ describe("buildRunContext", () => {expect(ctx.require(ScheduleIdKey)).toBe("dynamic-tasks");});+ it("stores a title only for top-level sessions", () => {+ const root = buildRunContext({+ bundle: createMinimalBundle(),+ run: {+ auth: null,+ adapter: { kind: "http" },+ input: { message: "Investigate the incident" },+ mode: "conversation",+ },+ });+ const child = buildRunContext({+ bundle: createMinimalBundle(),+ run: {+ auth: null,+ adapter: { kind: "subagent" },+ input: { message: "Delegated prompt" },+ mode: "task",+ parent: {+ callId: "call-1",+ rootSessionId: "root-session",+ sessionId: "parent-session",+ turn: { id: "turn-1", sequence: 0 },+ },+ },+ });++ expect(root.get(SessionTitleKey)).toBe("Investigate the incident");+ expect(child.get(SessionTitleKey)).toBeUndefined();+ });+it("does not invent a continuation for an ID-only run", () => {const ctx = buildRunContext({bundle: createMinimalBundle(),diff --git a/packages/eve/src/execution/runtime-context.ts b/packages/eve/src/execution/runtime-context.tsindex de782ecca..8561fb2f1 100644--- a/packages/eve/src/execution/runtime-context.ts+++ b/packages/eve/src/execution/runtime-context.ts@@ -17,7 +17,9 @@ import {ActivityObserverKey,ScheduleIdKey,SessionCallbackKey,+ SessionTitleKey,} from "#context/keys.js";+import { deriveSessionTitle } from "#execution/eve-workflow-attributes.js";import { BundleKey, type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";import { readConversationId } from "#tracing/conversation-context.js";@@ -45,6 +47,10 @@ export function buildRunContext(input: {ConversationContextKey,buildConversationContext(run, resolveInstrumentationEnvironment()),);+ if (run.parent === undefined) {+ const title = deriveSessionTitle(run.title ?? run.input.message);+ if (title !== undefined) ctx.set(SessionTitleKey, title);+ }if (run.channelMetadata !== undefined) {const existing = ctx.get(ChannelInstrumentationKey);diff --git a/packages/eve/src/execution/workflow-entry.integration.test.ts b/packages/eve/src/execution/workflow-entry.integration.test.tsindex f0734c96f..4f5fdeed3 100644--- a/packages/eve/src/execution/workflow-entry.integration.test.ts+++ b/packages/eve/src/execution/workflow-entry.integration.test.ts@@ -29,6 +29,7 @@ import type { ResolvedToolDefinition } from "#runtime/types.js";import { toInputSchema } from "#tools/schema.js";import { defineHook } from "#public/definitions/hook.js";import { ConversationContextKey } from "#shared/conversation-context.js";+import { SessionTitleKey } from "#context/keys.js";function buildSerializedContext(overrides: {acceptedDeploymentId?: string;@@ -1253,12 +1254,15 @@ describe("workflowEntry integration", () => {const continuationToken = "http:workflow-entry-tags";await runtime.run(async () => {- const serializedContext = buildSerializedContext({- audience: "public",- channelKind: "http",- continuationToken,- mode: "conversation",- });+ const serializedContext = {+ ...buildSerializedContext({+ audience: "public",+ channelKind: "http",+ continuationToken,+ mode: "conversation",+ }),+ [SessionTitleKey.name]: "session tag round-trip",+ };const run = await start(workflowEntry,[@@ -1271,7 +1275,6 @@ describe("workflowEntry integration", () => {allowReservedAttributes: true,attributes: normalizeEveAttributes(buildSessionAttributes({- inputMessage: "session tag round-trip",serializedContext,}),),diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.tsindex 3ae31f71b..5394e964d 100644--- a/packages/eve/src/execution/workflow-runtime.test.ts+++ b/packages/eve/src/execution/workflow-runtime.test.ts@@ -9,7 +9,7 @@ import {} from "#compiled/@opentelemetry/api/index.js";import type { ChannelAdapter } from "#channel/adapter.js";import { attachChannelActivityPresentation } from "#channel/activity-renderer.js";-import { ChannelRequestIdKey, ActivityObserverKey } from "#context/keys.js";+import { ActivityObserverKey, ChannelRequestIdKey, SessionTitleKey } from "#context/keys.js";import { resolveInstalledPackageInfo } from "#internal/application/package.js";import {createWorkflowRuntime,@@ -566,6 +566,7 @@ describe("createWorkflowRuntime#createSession", () => {expect(startOptions.attributes["$eve.is_trace_content_visible"]).toBe("false");expect(startOptions.attributes["$eve.is_otel_trace_enabled"]).toBe("false");expect(startOptions.attributes["$eve.title"]).toBe("ship it");+ expect(workflowInput[0].serializedContext[SessionTitleKey.name]).toBe("ship it");});it("passes the configured session timeout to the durable workflow", async () => {diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex d9a93f719..c66de7c8a 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -226,7 +226,6 @@ export function createWorkflowRuntime(config: {const sessionAttributes =parentLineage.sessionId === undefined? buildSessionAttributes({- inputMessage: input.title ?? input.input.message,serializedContext,}): buildSubagentRootAttributes({diff --git a/packages/eve/src/instrumentation/content.test.ts b/packages/eve/src/instrumentation/content.test.tsindex a96a54b17..cf80e0e84 100644--- a/packages/eve/src/instrumentation/content.test.ts+++ b/packages/eve/src/instrumentation/content.test.ts@@ -4,6 +4,7 @@ import { withInstrumentationDecision } from "#instrumentation/content.js";import type {InstrumentationInputRequestedEvent,InstrumentationInputResolvedEvent,+ InstrumentationSessionStartedEvent,} from "#instrumentation/lifecycle.js";const scope = {@@ -15,6 +16,27 @@ const scope = {};describe("withInstrumentationDecision", () => {+ it("treats the session title as input content", () => {+ const event = {+ agentName: "general",+ channelAudience: "public",+ idempotencyKey: "session:session-1",+ rootSessionId: "session-1",+ scheduleId: "daily-report",+ sessionId: "session-1",+ title: "Private title",+ type: "session.started",+ } satisfies InstrumentationSessionStartedEvent;++ expect(+ withInstrumentationDecision(event, {+ action: "record",+ recordInputs: false,+ recordOutputs: true,+ }),+ ).toEqual(expect.objectContaining({ scheduleId: "daily-report", title: undefined }));+ });+it("treats input requests as outputs and user responses as inputs", () => {const requested = withInstrumentationDecision({diff --git a/packages/eve/src/instrumentation/content.ts b/packages/eve/src/instrumentation/content.tsindex 9fe7b8545..fba17b34a 100644--- a/packages/eve/src/instrumentation/content.ts+++ b/packages/eve/src/instrumentation/content.ts@@ -22,6 +22,8 @@ export function withInstrumentationDecision(decision: Extract<InstrumentationDecision, { action: "record" }>,): InstrumentationEvent {switch (event.type) {+ case "session.started":+ return decision.recordInputs ? event : Object.freeze({ ...event, title: undefined });case "channel.delivery.started":return decision.recordInputs ? event : Object.freeze({ ...event, input: undefined });case "action.started":diff --git a/packages/eve/src/instrumentation/lifecycle.ts b/packages/eve/src/instrumentation/lifecycle.tsindex 6e7f5113e..fe1dac314 100644--- a/packages/eve/src/instrumentation/lifecycle.ts+++ b/packages/eve/src/instrumentation/lifecycle.ts@@ -11,13 +11,9 @@ import type {} from "#shared/trace-policy.js";/**- * Stable eve identity for one actual model attempt.- *- * A step retried three times produces three of these, all sharing `stepIndex`- * and separated by `attemptIndex` — which is why the events carrying this- * scope are named `step.attempt.*` and not `step.*`. The protocol's `step.*`- * and the `events["step.started"]` resolver hook fire once per step; these- * fire once per attempt.+ * Stable eve identity for one model attempt. Retries share `stepIndex` and+ * differ by `attemptIndex`, so `step.attempt.*` fires once per attempt while+ * protocol `step.*` events and the resolver hook fire once per step.*/export interface InstrumentationAttemptScope {readonly channelAudience?: ChannelAudience;@@ -283,7 +279,9 @@ export interface InstrumentationSessionStartedEvent {readonly parentLineage?: InstrumentationParentLineage;readonly parentTraceContext?: InstrumentationTraceContext;readonly rootSessionId: string;+ readonly scheduleId?: string;readonly sessionId: string;+ readonly title?: string;readonly traceSeed?: InstrumentationTraceSeed;}diff --git a/packages/eve/src/instrumentation/native-events.ts b/packages/eve/src/instrumentation/native-events.tsindex 9f165c10b..9c515bc55 100644--- a/packages/eve/src/instrumentation/native-events.ts+++ b/packages/eve/src/instrumentation/native-events.ts@@ -49,7 +49,9 @@ export interface CreateInstrumentationHandleEventInput {readonly parentLineage?: InstrumentationParentLineage;readonly parentTraceContext?: InstrumentationTraceContext;readonly rootSessionId?: string;+ readonly scheduleId?: string;readonly sessionId: string;+ readonly title?: string;readonly turnId?: string;}@@ -399,7 +401,9 @@ function toLifecycleEvent(parentLineage: input.parentLineage,parentTraceContext: input.parentTraceContext,rootSessionId: input.rootSessionId ?? input.sessionId,+ scheduleId: input.scheduleId,sessionId: input.sessionId,+ title: input.title,type: "session.started",};case "session.completed":diff --git a/packages/eve/src/instrumentation/runtime.test.ts b/packages/eve/src/instrumentation/runtime.test.tsindex 9648d0585..454c05c86 100644--- a/packages/eve/src/instrumentation/runtime.test.ts+++ b/packages/eve/src/instrumentation/runtime.test.ts@@ -9,6 +9,8 @@ import {OtelTraceEnabledKey,ParentTraceContextKey,ParentSessionKey,+ ScheduleIdKey,+ SessionTitleKey,SessionTraceSeedKey,} from "#context/keys.js";import { setChannelContext } from "#execution/channel-context.js";@@ -490,6 +492,45 @@ describe("bindInstrumentationRuntime", () => {},);+ it("prepares root activation metadata before turn sampling", async () => {+ const ctx = createContext("public");+ ctx.set(ScheduleIdKey, "daily-report");+ ctx.set(SessionTitleKey, "Prepare the daily report");+ const seed = {+ spanId: "1".repeat(16),+ traceFlags: 1,+ traceId: "2".repeat(32),+ };+ const prepareSessionTrace = vi.fn().mockResolvedValue(seed);+ const prepareTurnTrace = vi.fn().mockResolvedValue(seed);+ const instrumentation = bindInstrumentationRuntime(+ {+ ...createRuntime({ capturesContent: true, publish: vi.fn() }),+ prepareSessionTrace,+ prepareTurnTrace,+ },+ ctx,+ boundSession,+ );++ await instrumentation?.preparePreamble({+ sequence: 0,+ sessionStarted: false,+ turnId: "turn-1",+ });++ expect(prepareSessionTrace).toHaveBeenCalledWith(+ expect.objectContaining({+ channelKind: "channel:test",+ scheduleId: "daily-report",+ title: "Prepare the daily report",+ }),+ );+ expect(prepareSessionTrace.mock.invocationCallOrder[0]).toBeLessThan(+ prepareTurnTrace.mock.invocationCallOrder[0]!,+ );+ });+it("keeps the step-entry audience for the rest of the step", async () => {const ctx = createContext("private");const instrumentation = bindInstrumentationRuntime(diff --git a/packages/eve/src/instrumentation/runtime.ts b/packages/eve/src/instrumentation/runtime.tsindex ac3a69c39..2c7b83820 100644--- a/packages/eve/src/instrumentation/runtime.ts+++ b/packages/eve/src/instrumentation/runtime.ts@@ -238,11 +238,15 @@ export function bindInstrumentationRuntime(session: {agentName: boundSession.agentName,channelAudience: sessionContext.conversation.audience,+ // OTel stores the normalized conversation kind; `$eve.trigger` retains the raw adapter kind.+ channelKind: sessionContext.conversation.channel.kind,channelType: sessionContext.instrumentation?.channelType,parentLineage: sessionContext.parentLineage,parentTraceContext: sessionContext.parentTraceContext,rootSessionId: sessionContext.parent?.rootSessionId ?? boundSession.rootSessionId,+ scheduleId: sessionContext.scheduleId,sessionId: boundSession.sessionId,+ title: sessionContext.title,traceSeed: sessionContext.traceSeed,},});@@ -400,7 +404,9 @@ export function bindInstrumentationRuntime(parentLineage: sessionContext.parentLineage,parentTraceContext: sessionContext.parentTraceContext,rootSessionId: sessionContext.parent?.rootSessionId,+ scheduleId: sessionContext.scheduleId,sessionId: boundSession.sessionId,+ title: sessionContext.title,}),prepareAttempt: (attemptInput) => {const scope: InstrumentationAttemptScope = {@@ -489,10 +495,12 @@ export function bindInstrumentationRuntime(const sessionContext = readSessionContext();return createInstrumentationHandleEvent({agentName: boundSession.agentName,- channelKind: sessionContext.instrumentation?.kind,+ channelKind: sessionContext.conversation.channel.kind,handleEvent: input.handleEvent,hooks: bindHooks(sessionContext),+ scheduleId: sessionContext.scheduleId,sessionId: boundSession.sessionId,+ title: sessionContext.title,turnId: input.turnId,});},diff --git a/packages/eve/src/instrumentation/session-context.ts b/packages/eve/src/instrumentation/session-context.tsindex 6f8b1af7f..8a91507a0 100644--- a/packages/eve/src/instrumentation/session-context.ts+++ b/packages/eve/src/instrumentation/session-context.ts@@ -5,7 +5,9 @@ import {ParentSessionKey,ParentTraceContextKey,AuthKey,+ ScheduleIdKey,SessionCallbackKey,+ SessionTitleKey,SessionTraceSeedKey,} from "#context/keys.js";import {@@ -50,6 +52,8 @@ export function readInstrumentationSessionContext(context: AlsContext) {parentLineage: resolveParentLineage(parent, channel, context.get(SessionCallbackKey)),parentTraceContext: context.get(ParentTraceContextKey),principals: readInstrumentationPrincipals(context, conversation, traceSeed?.decision),+ scheduleId: context.get(ScheduleIdKey),+ title: context.get(SessionTitleKey),traceSeed,};}diff --git a/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts b/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.tsindex 4f2bf557b..6af64e5e1 100644--- a/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts+++ b/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts@@ -185,7 +185,7 @@ describe("eveChannel forwarded principal → runtime principal", () => {originAudience: "private",},});- expect(buildSessionAttributes({ inputMessage: "research", serializedContext })).toMatchObject({+ expect(buildSessionAttributes({ serializedContext })).toMatchObject({"$eve.is_trace_content_visible": false,});expect(ctx.get(ParentTraceContextKey)).toEqual({diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.tsindex 6965403ba..91b91f8f2 100644--- a/packages/eve/src/tracing/agent-otel-provider.test.ts+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts@@ -341,7 +341,9 @@ async function publishTurnStarted(input: {readonly parentLineage?: InstrumentationParentLineage;readonly parentTraceContext?: InstrumentationTraceContext;readonly rootSessionId?: string;+ readonly scheduleId?: string;readonly sessionId: string;+ readonly title?: string;readonly traceSeed?: InstrumentationTraceContext;readonly turnId: string;readonly turnSequence: number;@@ -355,7 +357,9 @@ async function publishTurnStarted(input: {parentLineage: input.parentLineage,parentTraceContext: input.parentTraceContext,rootSessionId,+ scheduleId: input.scheduleId,sessionId: input.sessionId,+ title: input.title,traceSeed: input.traceSeed,type: "session.started",});@@ -735,7 +739,9 @@ describe("createAgentOtelInstrumentation", () => {parentLineage,parentTraceContext: parent,rootSessionId: "root-session",+ scheduleId: "daily-report",sessionId: "child-session",+ title: "Research the incident",traceSeed: seed,turnId: "child-turn",turnSequence: 0,@@ -761,15 +767,87 @@ describe("createAgentOtelInstrumentation", () => {"agent.principal.current.type": "user","agent.principal.initiator.type": "none","agent.run.id": "child-session",+ "agent.run.type": "subagent",+ "agent.trace.content.input": true,+ "agent.trace.content.output": true,"gen_ai.conversation.id": "root-session","gen_ai.operation.name": "invoke_agent",});+ expect(invocation.attributes).not.toHaveProperty("agent.channel.kind");+ expect(invocation.attributes).not.toHaveProperty("agent.schedule.id");+ expect(invocation.attributes).not.toHaveProperty("agent.session.origin");+ expect(invocation.attributes).not.toHaveProperty("agent.session.title");expect(invocation.attributes).not.toHaveProperty("agent.principal.initiator.id");expect(invocation.attributes).not.toHaveProperty("agent.root_run.id");expect(invocation.attributes).not.toHaveProperty("agent.session.id");expect(invocation.attributes).not.toHaveProperty("vercel.session_id");});+ it("samples and exports preamble-prepared activation metadata consistently", async () => {+ const store = new InMemoryAgentTraceStateStore();+ const samplesTrace = vi.fn(() => true);+ const runtime = createRuntime(+ store,+ () => ({ emit: true, recordInputs: true, recordOutputs: true }),+ [],+ samplesTrace,+ );+ const setSession = vi.spyOn(store, "setSession");+ const sessionId = "session-early";+ await runtime.prepareSessionTrace({+ agentName: "weather",+ channelAudience: "public",+ channelKind: "http",+ idempotencyKey: sessionIdempotencyKey(sessionId),+ rootSessionId: sessionId,+ scheduleId: "daily-report",+ sessionId,+ title: "Prepared before sampling",+ type: "session.started",+ });+ await runtime.prepareTurnTrace({+ idempotencyKey: turnIdempotencyKey(sessionId, "turn-1"),+ rootSessionId: sessionId,+ sequence: 0,+ sessionId,+ turnId: "turn-1",+ type: "turn.started",+ });++ expect(samplesTrace).toHaveBeenCalledWith(+ expect.any(String),+ expect.objectContaining({+ attributes: expect.objectContaining({+ "agent.channel.kind": "http",+ "agent.schedule.id": "daily-report",+ "agent.session.origin": "schedule",+ "agent.session.title": "Prepared before sampling",+ }),+ }),+ );++ await publishTurnStarted({+ hooks: runtime.hooks,+ scheduleId: "daily-report",+ sessionId,+ title: "Prepared before sampling",+ turnId: "turn-1",+ turnSequence: 0,+ });+ await completeTurn(runtime.hooks, sessionId, "turn-1");+ await runtime.provider.forceFlush();++ expect(+ byName(runtime.exporter.getFinishedSpans(), "invoke_agent weather")[0]?.attributes,+ ).toMatchObject({+ "agent.channel.kind": "http",+ "agent.schedule.id": "daily-report",+ "agent.session.origin": "schedule",+ "agent.session.title": "Prepared before sampling",+ });+ expect(setSession).toHaveBeenCalledTimes(1);+ });+it("falls back to fresh ids when no trace seed is present", async () => {const runtime = createRuntime();const sessionEvent = {@@ -1192,8 +1270,11 @@ describe("createAgentOtelInstrumentation", () => {).toBe(true);expect(action.parentSpanContext?.spanId).toBe(step.spanContext().spanId);expect(tool.parentSpanContext?.spanId).toBe(action.spanContext().spanId);- for (const span of [turn, step, model, action, tool]) {+ expect(turn.attributes["agent.channel.audience"]).toBe("public");+ for (const span of [step, model, action, tool]) {expect(span.attributes).not.toHaveProperty("agent.channel.audience");+ }+ for (const span of [turn, step, model, action, tool]) {expect(span.attributes).toMatchObject({"gen_ai.conversation.id": "session-1",});diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.tsindex c23901cf9..ac6451cfd 100644--- a/packages/eve/src/tracing/agent-otel-provider.ts+++ b/packages/eve/src/tracing/agent-otel-provider.ts@@ -319,6 +319,7 @@ export function createAgentOtelInstrumentation(attributes: runtimeAttributes.agentActivationAttributes({agentName,frameworkVersion: input.frameworkVersion,+ session,sessionId: event.sessionId,turnId: event.turnId!,turn,diff --git a/packages/eve/src/tracing/agent-otel-runtime-context.test.ts b/packages/eve/src/tracing/agent-otel-runtime-context.test.tsnew file mode 100644index 000000000..1309e9163--- /dev/null+++ b/packages/eve/src/tracing/agent-otel-runtime-context.test.ts@@ -0,0 +1,119 @@+import { describe, expect, it } from "vitest";++import { agentActivationAttributes } from "#tracing/agent-otel-runtime-context.js";+import type { AgentSessionTraceState, AgentTurnTraceState } from "#tracing/agent-trace-state.js";++const context = {+ spanId: "1".repeat(16),+ traceFlags: 1,+ traceId: "2".repeat(32),+};++function turn(overrides: Partial<AgentTurnTraceState> = {}): AgentTurnTraceState {+ return {+ context,+ rootSessionId: "root-session",+ sequence: 0,+ startTimeMs: 1,+ ...overrides,+ };+}++function session(overrides: Partial<AgentSessionTraceState> = {}): AgentSessionTraceState {+ return {+ agentName: "general",+ channelAudience: "public",+ channelKind: "slack",+ context,+ decision: { action: "record", recordInputs: true, recordOutputs: true },+ rootSessionId: "root-session",+ title: "Call the general agent",+ ...overrides,+ };+}++describe("agentActivationAttributes", () => {+ it("emits root-session inventory and trace-policy metadata", () => {+ expect(+ agentActivationAttributes({+ agentName: "general",+ frameworkVersion: "test",+ session: session(),+ sessionId: "root-session",+ turn: turn(),+ turnId: "turn_0",+ }),+ ).toMatchObject({+ "agent.channel.audience": "public",+ "agent.channel.kind": "slack",+ "agent.run.type": "session",+ "agent.session.origin": "channel",+ "agent.session.title": "Call the general agent",+ "agent.trace.content.input": true,+ "agent.trace.content.output": true,+ });+ });++ it("keeps root-only provenance and title off delegated activations", () => {+ const attributes = agentActivationAttributes({+ agentName: "general",+ frameworkVersion: "test",+ session: session({+ channelAudience: "private",+ decision: { action: "record", recordInputs: false, recordOutputs: true },+ scheduleId: "daily-report",+ }),+ sessionId: "child-session",+ turn: turn({+ parentLineage: {+ callId: "call-1",+ sessionId: "parent-session",+ subagentName: "general",+ turnId: "turn_0",+ },+ }),+ turnId: "turn_0",+ });++ expect(attributes).toMatchObject({+ "agent.channel.audience": "private",+ "agent.run.type": "subagent",+ "agent.trace.content.input": false,+ "agent.trace.content.output": true,+ });+ expect(attributes["agent.channel.kind"]).toBeUndefined();+ expect(attributes["agent.schedule.id"]).toBeUndefined();+ expect(attributes["agent.session.origin"]).toBeUndefined();+ expect(attributes["agent.session.title"]).toBeUndefined();+ });++ it("keeps actual channel delivery metadata on delegated activations", () => {+ const attributes = agentActivationAttributes({+ agentName: "general",+ frameworkVersion: "test",+ session: session(),+ sessionId: "child-session",+ turn: turn({+ channelDelivery: {+ channelKind: "channel:slack",+ channelName: "slack",+ deliveryId: "delivery-1",+ },+ parentLineage: {+ callId: "call-1",+ sessionId: "parent-session",+ subagentName: "general",+ turnId: "turn_0",+ },+ }),+ turnId: "turn_1",+ });++ expect(attributes).toMatchObject({+ "agent.channel.delivery.id": "delivery-1",+ "agent.channel.kind": "channel:slack",+ "agent.channel.name": "slack",+ "agent.run.type": "subagent",+ });+ });+});diff --git a/packages/eve/src/tracing/agent-otel-runtime-context.ts b/packages/eve/src/tracing/agent-otel-runtime-context.tsindex d73b56778..2600c9590 100644--- a/packages/eve/src/tracing/agent-otel-runtime-context.ts+++ b/packages/eve/src/tracing/agent-otel-runtime-context.ts@@ -1,4 +1,4 @@-import type { AgentTurnTraceState } from "#tracing/agent-trace-state.js";+import type { AgentSessionTraceState, AgentTurnTraceState } from "#tracing/agent-trace-state.js";import { agentSpanNamingAttributes } from "#tracing/agent-span-naming.js";import { agentInvocationSpanName } from "#tracing/agent-span-contract.js";import { agentTraceIdentityAttributes } from "#tracing/agent-otel-attributes.js";@@ -9,23 +9,46 @@ type SpanAttributeValue = SpanAttributePrimitive | SpanAttributePrimitive[];export function agentActivationAttributes(input: {readonly agentName?: string;readonly frameworkVersion: string;+ readonly session?: AgentSessionTraceState;readonly sessionId: string;readonly turnId: string;readonly turn: AgentTurnTraceState;}): Record<string, string | number | boolean | undefined> {+ const recordsTrace = input.session?.decision?.action === "record";+ const recordsInputs = recordsTrace && input.session?.decision?.recordInputs === true;+ const recordsOutputs = recordsTrace && input.session?.decision?.recordOutputs === true;+ const parentLineage = input.turn.parentLineage ?? input.session?.parentLineage;+ const isSubagent = parentLineage !== undefined;+ const channelKind =+ input.turn.channelDelivery?.channelKind ??+ (isSubagent ? undefined : input.session?.channelKind);+ const scheduleId = isSubagent ? undefined : input.session?.scheduleId;+ const origin =+ isSubagent || channelKind === undefined+ ? undefined+ : scheduleId !== undefined+ ? "schedule"+ : "channel";return {"agent.framework.name": "eve","agent.framework.version": input.frameworkVersion,"agent.name": input.agentName,+ "agent.channel.audience": input.session?.channelAudience,...agentPrincipalAttributes(input.turn),"agent.channel.delivery.id": input.turn.channelDelivery?.deliveryId,"agent.channel.delivery.input": input.turn.channelDelivery?.inputAttribute,- "agent.channel.kind": input.turn.channelDelivery?.channelKind,+ "agent.channel.kind": channelKind,"agent.channel.name": input.turn.channelDelivery?.channelName,"agent.channel.request.id": input.turn.channelDelivery?.requestId,- "agent.parent_call.id": input.turn.parentLineage?.callId,- "agent.parent_run.id": input.turn.parentLineage?.sessionId,+ "agent.parent_call.id": parentLineage?.callId,+ "agent.parent_run.id": parentLineage?.sessionId,+ "agent.run.type": isSubagent ? "subagent" : "session",+ "agent.schedule.id": scheduleId,+ "agent.session.origin": origin,+ "agent.session.title": !isSubagent && recordsInputs ? input.session?.title : undefined,"agent.subagent.name": input.turn.subagentName,+ "agent.trace.content.input": recordsInputs,+ "agent.trace.content.output": recordsOutputs,"agent.turn.id": input.turnId,"agent.turn.sequence": input.turn.sequence,"gen_ai.agent.name": input.agentName,diff --git a/packages/eve/src/tracing/agent-otel-session-context.ts b/packages/eve/src/tracing/agent-otel-session-context.tsindex 4e0dc77f7..1b26dddd9 100644--- a/packages/eve/src/tracing/agent-otel-session-context.ts+++ b/packages/eve/src/tracing/agent-otel-session-context.ts@@ -67,8 +67,10 @@ export function createAgentOtelSessionContext(channelKind: event.channelKind,decision,context: initialSessionContext(input, event, decision),- rootSessionId: event.rootSessionId,parentLineage: event.parentLineage,+ rootSessionId: event.rootSessionId,+ scheduleId: event.scheduleId,+ title: event.title,};await input.stateStore.setSession(event.sessionId, state);}@@ -116,6 +118,7 @@ export function createAgentOtelSessionContext(attributes: agentActivationAttributes({agentName,frameworkVersion: input.frameworkVersion,+ session,sessionId: event.sessionId,turnId: event.turnId,turn,diff --git a/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts b/packages/eve/src/tracing/agent-telemetry-contract.integration.test.tsindex 901de1842..de3101dd4 100644--- a/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts+++ b/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts@@ -931,7 +931,7 @@ function normalizeTraceForest(const deliveryId = root.attributes["agent.channel.delivery.id"];lines.push(`trace ${alias} outcome=${String(root.attributes["agent.turn.outcome"] ?? "unknown")}${- channelKind === undefined+ deliveryId === undefined? "": ` channel=${String(channelKind)}:${String(channelName)} delivery=${String(deliveryId)}`}`,diff --git a/packages/eve/src/tracing/agent-trace-context-codec.ts b/packages/eve/src/tracing/agent-trace-context-codec.tsindex 7163f6234..85c38fa06 100644--- a/packages/eve/src/tracing/agent-trace-context-codec.ts+++ b/packages/eve/src/tracing/agent-trace-context-codec.ts@@ -103,6 +103,8 @@ function deserializeSession(value: unknown): AgentSessionTraceState | undefineddecision: readInstrumentationDecision(value.decision),parentLineage: deserializeParentLineage(value.parentLineage),rootSessionId: typeof value.rootSessionId === "string" ? value.rootSessionId : "",+ scheduleId: typeof value.scheduleId === "string" ? value.scheduleId : undefined,+ title: typeof value.title === "string" ? value.title : undefined,};}diff --git a/packages/eve/src/tracing/agent-trace-state.ts b/packages/eve/src/tracing/agent-trace-state.tsindex 6f23ee3e8..da8316286 100644--- a/packages/eve/src/tracing/agent-trace-state.ts+++ b/packages/eve/src/tracing/agent-trace-state.ts@@ -21,6 +21,8 @@ export interface AgentSessionTraceState {readonly decision?: InstrumentationDecision;readonly parentLineage?: InstrumentationParentLineage;readonly rootSessionId: string;+ readonly scheduleId?: string;+ readonly title?: string;}export interface AgentTurnTraceState {diff --git a/packages/eve/src/tracing/content-attributes.test.ts b/packages/eve/src/tracing/content-attributes.test.tsindex 626590d6a..21d80e6a6 100644--- a/packages/eve/src/tracing/content-attributes.test.ts+++ b/packages/eve/src/tracing/content-attributes.test.ts@@ -4,6 +4,9 @@ import { withoutDeclinedContent } from "#tracing/content-attributes.js";const ATTRIBUTES = {"agent.channel.delivery.input": '{"message":"private"}',+ "agent.session.title": "Private title",+ "agent.trace.content.input": true,+ "agent.trace.content.output": true,"gen_ai.input.messages": "what the user said","ai.response.finish_reason": "stop","ai.response.text": "what the model said",@@ -33,6 +36,8 @@ describe("withoutDeclinedContent", () => {expect(withoutDeclinedContent(ATTRIBUTES, { recordInputs: false, recordOutputs: true }),).toEqual({+ "agent.trace.content.input": false,+ "agent.trace.content.output": true,"ai.response.finish_reason": "stop","ai.response.text": "what the model said","gen_ai.request.model": "test-model",@@ -46,6 +51,9 @@ describe("withoutDeclinedContent", () => {withoutDeclinedContent(ATTRIBUTES, { recordInputs: true, recordOutputs: false }),).toEqual({"agent.channel.delivery.input": '{"message":"private"}',+ "agent.session.title": "Private title",+ "agent.trace.content.input": true,+ "agent.trace.content.output": false,"gen_ai.input.messages": "what the user said","ai.response.finish_reason": "stop","gen_ai.request.model": "test-model",@@ -61,6 +69,8 @@ describe("withoutDeclinedContent", () => {expect(withoutDeclinedContent(ATTRIBUTES, { recordInputs: false, recordOutputs: false }),).toEqual({+ "agent.trace.content.input": false,+ "agent.trace.content.output": false,"ai.response.finish_reason": "stop","gen_ai.request.model": "test-model","gen_ai.tool.name": "weather",@@ -73,6 +83,21 @@ describe("withoutDeclinedContent", () => {expect(attributes).toEqual(ATTRIBUTES);});+ it("narrows content policy attributes even when no content is present", () => {+ expect(+ withoutDeclinedContent(+ {+ "agent.trace.content.input": true,+ "agent.trace.content.output": true,+ },+ { recordInputs: false, recordOutputs: true },+ ),+ ).toEqual({+ "agent.trace.content.input": false,+ "agent.trace.content.output": true,+ });+ });+it("redacts recalled memory records as input content", () => {const searched = {"gen_ai.memory.records": '[{"content":"Private preference"}]',diff --git a/packages/eve/src/tracing/content-attributes.ts b/packages/eve/src/tracing/content-attributes.tsindex bd5044d4e..0f0417244 100644--- a/packages/eve/src/tracing/content-attributes.ts+++ b/packages/eve/src/tracing/content-attributes.ts@@ -16,6 +16,7 @@/** Prompts, instructions, tool arguments — what went in. */const INPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set(["agent.channel.delivery.input",+ "agent.session.title","agent.approval.request","ai.documents","ai.prompt",@@ -55,6 +56,9 @@ const OUTPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set(["gen_ai.tool.call.result",]);+const INPUT_POLICY_ATTRIBUTE = "agent.trace.content.input";+const OUTPUT_POLICY_ATTRIBUTE = "agent.trace.content.output";+/** What one destination is willing to receive. */export interface ResolvedContentOptions {readonly recordInputs: boolean;@@ -66,6 +70,26 @@ function isDeclined(key: string, content: ResolvedContentOptions): boolean {return !content.recordOutputs && OUTPUT_CONTENT_ATTRIBUTES.has(key);}+function narrowsContentPolicy(+ attributes: Readonly<Record<string, unknown>>,+ content: ResolvedContentOptions,+): boolean {+ return (+ (!content.recordInputs && attributes[INPUT_POLICY_ATTRIBUTE] === true) ||+ (!content.recordOutputs && attributes[OUTPUT_POLICY_ATTRIBUTE] === true)+ );+}++function exportedAttributeValue(+ key: string,+ value: unknown,+ content: ResolvedContentOptions,+): unknown {+ if (key === INPUT_POLICY_ATTRIBUTE && value === true && !content.recordInputs) return false;+ if (key === OUTPUT_POLICY_ATTRIBUTE && value === true && !content.recordOutputs) return false;+ return value;+}+/*** The attributes with the declined content removed, or `undefined` when there* was none to remove.@@ -79,11 +103,15 @@ export function withoutDeclinedContent(content: ResolvedContentOptions,): Record<string, unknown> | undefined {const keys = Object.keys(attributes);- if (!keys.some((key) => isDeclined(key, content))) return undefined;+ if (!keys.some((key) => isDeclined(key, content)) && !narrowsContentPolicy(attributes, content)) {+ return undefined;+ }const kept: Record<string, unknown> = {};for (const key of keys) {- if (!isDeclined(key, content)) kept[key] = attributes[key];+ if (!isDeclined(key, content)) {+ kept[key] = exportedAttributeValue(key, attributes[key], content);+ }}return kept;}diff --git a/packages/eve/src/tracing/content-span-processor.test.ts b/packages/eve/src/tracing/content-span-processor.test.tsindex e7f639b40..8f384eeec 100644--- a/packages/eve/src/tracing/content-span-processor.test.ts+++ b/packages/eve/src/tracing/content-span-processor.test.ts@@ -65,6 +65,27 @@ describe("contentFilteringProcessor", () => {});});+ it("reports the content policy visible to each destination", () => {+ const downstream = recordingProcessor();+ const original = span({+ "agent.trace.content.input": true,+ "agent.trace.content.output": true,+ "gen_ai.input.messages": "what the user said",+ });++ contentFilteringProcessor(downstream, redactSpanInputs()).onEnd(original as never);++ expect((downstream.ended[0] as { attributes: unknown }).attributes).toEqual({+ "agent.trace.content.input": false,+ "agent.trace.content.output": true,+ });+ expect((original as { attributes: unknown }).attributes).toEqual({+ "agent.trace.content.input": true,+ "agent.trace.content.output": true,+ "gen_ai.input.messages": "what the user said",+ });+ });+it("leaves the original span's attributes in place for the other destinations", () => {const kept = recordingProcessor();const declined = recordingProcessor();diff --git a/research/activation-metadata-contract.md b/research/activation-metadata-contract.mdnew file mode 100644index 000000000..84ed70af1--- /dev/null+++ b/research/activation-metadata-contract.md@@ -0,0 +1,46 @@+---+issue: "None (maintainer-requested in PR #3338)"+status: in-progress+last_updated: "2026-09-14"+---++# Activation metadata contract++## Summary++Schema v4 activation roots need a small provider-neutral attribute set for+filtering and grouping without inspecting captured payloads. The contract keeps+structural metadata on `invoke_agent` spans while preserving eve's existing+trace-content and destination-redaction boundaries.++## Attribute ownership++Every activation carries its run type, agent identity, audience, turn identity,+and directional content-policy results. Root-session activations additionally+carry their initiating channel kind, origin, authored schedule ID when+applicable, and bounded initial title when input capture permits. An actual+channel delivery carries its own channel kind, name, and delivery ID.+Delivery-less subagent activations omit the root-only attributes and use parent+lineage to describe delegation.++The session title is derived once from the initial session input, stored in the+run context, and repeated on each turn activation. It never describes a later+turn. Titles remain input content and can be omitted by the trace decision or+removed by a destination's input-redaction policy.++## Sampling and export invariants++Session metadata is available before the first turn is sampled. A sampler and+the resulting exported activation therefore observe the same channel kind,+schedule provenance, and title.++The `agent.trace.content.input` and `agent.trace.content.output` attributes+describe what the receiving destination can observe. Destination redaction can+narrow either value from `true` to `false`; it cannot widen the session's+resolved trace decision.++## Scope++This contract does not change workflow lifecycle ownership, status semantics,+trace identity, or remote-lineage authorization. It only makes existing+activation metadata queryable across OpenTelemetry destinations.