Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index dc781dd36..8be8c3e80 100644
--- a/docs/guides/instrumentation.md
+++ b/docs/guides/instrumentation.md
@@ -201,6 +201,19 @@ exception. Vercel deployments additionally carry
trusted remote subagents. Remote lineage is accepted only when the receiver's
`trustedForwarders` predicate approves the authenticated caller. Child
activation 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 invocation
that coordinates at least one nested agent uses `invoke_workflow`, with its
path-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.ts
index 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.ts
index 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.ts
index 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>): stri
return 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 | undefined
decision: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
new file mode 100644
index 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.