The Open Framework for Building Agents
feat(eve): configure audience-aware tracing (#2335)
Chad Hietala47e8b64df647
diff --git a/.changeset/calm-pandas-trace.md b/.changeset/calm-pandas-trace.mdnew file mode 100644index 000000000..5c0966fc9--- /dev/null+++ b/.changeset/calm-pandas-trace.md@@ -0,0 +1,5 @@+---+"eve": minor+---++Make traces public-only by default while retaining unclassified HTTP/TUI sessions in zero-config local tracing, and add composable input/output redaction, span filtering, and attribute filtering to the export pipeline.diff --git a/packages/eve/src/cli/dev/tui/traces/trace-view.ts b/packages/eve/src/cli/dev/tui/traces/trace-view.tsindex 3164db3ab..a4fd76a5f 100644--- a/packages/eve/src/cli/dev/tui/traces/trace-view.ts+++ b/packages/eve/src/cli/dev/tui/traces/trace-view.ts@@ -304,7 +304,7 @@ function renderConversation(if (state.conversationItems.length === 0) {return [chromeStyles(theme, options.surfaces).muted(- " No conversation content in this trace — content capture may be off (EVE_TRACES_CONTENT).",+ " No conversation content in this trace; its export policy may have redacted it.",),];}diff --git a/packages/eve/src/execution/workflow-trace-context.ts b/packages/eve/src/execution/workflow-trace-context.tsindex 86dbbd246..264d64428 100644--- a/packages/eve/src/execution/workflow-trace-context.ts+++ b/packages/eve/src/execution/workflow-trace-context.ts@@ -1,5 +1,9 @@import type { ContextContainer } from "#context/container.js";-import { ParentSessionKey, ParentTraceContextKey } from "#context/keys.js";+import {+ ChannelInstrumentationKey,+ ParentSessionKey,+ ParentTraceContextKey,+} from "#context/keys.js";import type { HarnessEmissionState } from "#harness/emission.js";import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";import { resolveParentLineage } from "#harness/parent-lineage.js";@@ -7,6 +11,7 @@ import { prepareTurnTraceContext } from "#harness/prepare-trace-context.js";import type { HarnessSession } from "#harness/types.js";import type { RuntimeIdentity, RuntimeTraceContext } from "#protocol/message.js";import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";/** Prepares native tracing for workflow-owned preambles emitted outside the tool loop. */export async function prepareWorkflowPreambleTrace(input: {@@ -16,8 +21,10 @@ export async function prepareWorkflowPreambleTrace(input: {readonly session: HarnessSession;}): Promise<RuntimeTraceContext | undefined> {const parent = input.ctx.get(ParentSessionKey);+ const channel = input.ctx.get(ChannelInstrumentationKey);return await prepareTurnTraceContext({agentName: input.runtimeIdentity.agentName,+ channelAudience: normalizeChannelAudience(channel?.metadata.audience),instrumentation: getInstrumentationRuntime(),parentLineage: resolveParentLineage(parent, input.ctx.get(ChannelKey)),parentTraceContext: input.ctx.get(ParentTraceContextKey),diff --git a/packages/eve/src/harness/channel-delivery-instrumentation.ts b/packages/eve/src/harness/channel-delivery-instrumentation.tsindex 3ede9df1e..dabfe29f6 100644--- a/packages/eve/src/harness/channel-delivery-instrumentation.ts+++ b/packages/eve/src/harness/channel-delivery-instrumentation.ts@@ -2,6 +2,7 @@ import type { DeliverHookPayload, DeliverPayload } from "#channel/types.js";import type { AlsContext } from "#context/container.js";import {ActiveChannelDeliveriesKey,+ ChannelInstrumentationKey,ParentTraceContextKey,type ActiveChannelDelivery,} from "#context/keys.js";@@ -11,6 +12,7 @@ import type {InstrumentationHooks,} from "#harness/instrumentation/lifecycle.js";import { channelDeliveryIdempotencyKey } from "#harness/instrumentation/lifecycle.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";interface ChannelDeliveryStartInstrumentation {readonly agentName?: string;@@ -68,9 +70,13 @@ export async function instrumentChannelDelivery(if (input.hooks === undefined || input.delivery.deliveryMetadata === undefined) return;const active: ActiveChannelDelivery[] = [];+ const channelAudience = normalizeChannelAudience(+ input.ctx.get(ChannelInstrumentationKey)?.metadata.audience,+ );for (const metadata of input.delivery.deliveryMetadata) {const payload = input.delivery.payloads[metadata.payloadIndex];const delivery = {+ channelAudience,channelKind: metadata.channelKind,channelName: metadata.channelName,deliveryId: metadata.deliveryId,diff --git a/packages/eve/src/harness/instrumentation/lifecycle.ts b/packages/eve/src/harness/instrumentation/lifecycle.tsindex 239e64a5a..9598608c0 100644--- a/packages/eve/src/harness/instrumentation/lifecycle.ts+++ b/packages/eve/src/harness/instrumentation/lifecycle.ts@@ -1,6 +1,7 @@import { createInstrumentationDispatcher } from "#harness/instrumentation/dispatch.js";import type { InstrumentationStateSlot } from "#harness/instrumentation/state.js";import type { RuntimeTraceContext } from "#protocol/message.js";+import type { ChannelAudience } from "#shared/channel-audience.js";/*** Stable eve identity for one actual model attempt.@@ -12,6 +13,7 @@ import type { RuntimeTraceContext } from "#protocol/message.js";* fire once per attempt.*/export interface InstrumentationAttemptScope {+ readonly channelAudience?: ChannelAudience;readonly attemptId: string;readonly attemptIndex: number;readonly functionId?: string;@@ -160,6 +162,7 @@ export function channelDeliveryIdempotencyKey(sessionId: string, deliveryId: str}export interface InstrumentationChannelDeliveryRef {+ readonly channelAudience?: ChannelAudience;readonly channelKind: string;readonly channelName: string;readonly deliveryId: string;@@ -281,6 +284,7 @@ export interface InstrumentationSessionStartedEvent {readonly type: "session.started";readonly agentName?: string;readonly channelKind?: string;+ readonly channelAudience?: ChannelAudience;readonly idempotencyKey: string;readonly parentTraceContext?: InstrumentationTraceContext;readonly rootSessionId: string;diff --git a/packages/eve/src/harness/instrumentation/native-events.ts b/packages/eve/src/harness/instrumentation/native-events.tsindex 5dfc62bad..0987c371f 100644--- a/packages/eve/src/harness/instrumentation/native-events.ts+++ b/packages/eve/src/harness/instrumentation/native-events.ts@@ -29,10 +29,12 @@ import type { ResolvedInputBatch } from "#harness/input-requests.js";import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";import type { HandleEventFn } from "#harness/types.js";import type { RuntimeActionRequest, RuntimeActionResult } from "#runtime/actions/types.js";+import type { ChannelAudience } from "#shared/channel-audience.js";export interface CreateInstrumentationHandleEventInput {readonly agentName?: string;readonly channelKind?: string;+ readonly channelAudience?: ChannelAudience;readonly getAttemptScope?: () => InstrumentationAttemptScope | undefined;readonly handleEvent?: HandleEventFn;readonly hooks?: InstrumentationHooks;@@ -292,6 +294,7 @@ function toLifecycleEvent(case "session.started":return {agentName: input.agentName,+ channelAudience: input.channelAudience,channelKind: input.channelKind,idempotencyKey: sessionIdempotencyKey(input.sessionId),parentTraceContext: input.parentTraceContext,diff --git a/packages/eve/src/harness/instrumentation/providers.test.ts b/packages/eve/src/harness/instrumentation/providers.test.tsindex f8695ad2d..80a4964fb 100644--- a/packages/eve/src/harness/instrumentation/providers.test.ts+++ b/packages/eve/src/harness/instrumentation/providers.test.ts@@ -152,7 +152,7 @@ describe("seedInstrumentationProviders", () => {it("lets an authored reserved slot reconfigure or disable its default", async () => {seedInstrumentationProviders();- const authored = localTraces({ recordInputs: false });+ const authored = localTraces({ exportPolicy: { span: () => false } });await register("local", authored);expect(getInstrumentationProviders()).toEqual([{ provider: authored, slot: "local" }]);@@ -160,11 +160,11 @@ describe("seedInstrumentationProviders", () => {expect(getInstrumentationProviders()).toEqual([]);});- it("lets an authored Agent Runs slot narrow the production default", async () => {+ it("lets an authored Agent Runs slot reconfigure the production default", async () => {vi.stubEnv(DEVELOPMENT_WORKER_APP_ROOT_ENV, undefined);vi.stubEnv("VERCEL_ENV", "production");seedInstrumentationProviders();- const authored = agentRuns({ recordOutputs: false });+ const authored = agentRuns({ exportPolicy: { span: () => false } });await register("agent-runs", authored);@@ -176,7 +176,7 @@ describe("seedInstrumentationProviders", () => {seedInstrumentationProviders();await register("zeta", defineInstrumentation({}));await register("audit", defineInstrumentation({}));- await register("local", localTraces({ recordInputs: false }));+ await register("local", localTraces({ exportPolicy: { span: () => false } }));expect(getInstrumentationProviders().map(({ slot }) => slot)).toEqual(["agent-runs",diff --git a/packages/eve/src/harness/prepare-trace-context.ts b/packages/eve/src/harness/prepare-trace-context.tsindex 92873c1e0..d8c1d6735 100644--- a/packages/eve/src/harness/prepare-trace-context.ts+++ b/packages/eve/src/harness/prepare-trace-context.ts@@ -6,12 +6,14 @@ import type {} from "#harness/instrumentation/lifecycle.js";import { sessionIdempotencyKey, turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";import type { HarnessInstrumentation } from "#harness/instrumentation/runtime.js";+import type { ChannelAudience } from "#shared/channel-audience.js";const log = createLogger("harness.prepare-trace-context");/** Prepares native session/turn tracing before their durable stream events. */export async function prepareTurnTraceContext(input: {readonly agentName?: string;+ readonly channelAudience?: ChannelAudience;readonly instrumentation?: HarnessInstrumentation;readonly parentLineage?: InstrumentationParentLineage;readonly parentTraceContext?: InstrumentationTraceContext;@@ -28,6 +30,7 @@ export async function prepareTurnTraceContext(input: {try {prepared = await input.instrumentation.prepareSessionTrace({agentName: input.agentName,+ channelAudience: input.channelAudience,idempotencyKey: sessionIdempotencyKey(input.sessionId),parentTraceContext: input.parentTraceContext,rootSessionId: input.rootSessionId,diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex df4f29351..5a1e77d5d 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -55,6 +55,7 @@ import {import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";import { toErrorMessage } from "#shared/errors.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";import {createActionResultEvent,createApprovalCandidateEvent,@@ -648,6 +649,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {let emissionState = getHarnessEmissionState(session.state);const store = contextStorage.getStore();+ const channelInstrumentation = store?.get(ChannelInstrumentationKey);const parent = store?.get(ParentSessionKey);const channel = store?.get(ChannelKey);const callback = store?.get(SessionCallbackKey);@@ -661,7 +663,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {let activeAttemptScope: InstrumentationAttemptScope | undefined;const emit = createInstrumentationHandleEvent({agentName: config.runtimeIdentity?.agentName,- channelKind: store?.get(ChannelInstrumentationKey)?.kind,+ channelAudience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),+ channelKind: channelInstrumentation?.kind,getAttemptScope: () => activeAttemptScope,handleEvent: baseEmit,hooks: config.instrumentation?.hooks,@@ -718,6 +721,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {: undefined;return await prepareTurnTraceContext({agentName: config.runtimeIdentity?.agentName,+ channelAudience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),instrumentation: config.instrumentation,parentLineage,parentTraceContext,@@ -1497,6 +1501,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {: {attemptId: `${session.sessionId}:${instrumentationTurnId}:${emissionState.stepIndex}:${opts.attemptIndex}`,attemptIndex: opts.attemptIndex,+ channelAudience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),functionId: otelSettings?.functionId ?? agentName,rootSessionId: parent?.rootSessionId ?? session.sessionId,sessionId: session.sessionId,diff --git a/packages/eve/src/public/instrumentation/otel.ts b/packages/eve/src/public/instrumentation/otel.tsindex 0a988bec7..15c43e72b 100644--- a/packages/eve/src/public/instrumentation/otel.ts+++ b/packages/eve/src/public/instrumentation/otel.ts@@ -12,8 +12,8 @@import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";import {agentRunsIntegration,- otelIntegration,- type ContentOptions,+ managedOtelIntegration,+ type ManagedTraceOptions,type OtelIntegration,} from "#tracing/otel-declaration.js";@@ -22,11 +22,22 @@ export {isOtelIntegration,otel,otelIntegration,+ composeSpanExportPolicies,+ redactSpanInputs,+ redactSpanOutputs,type ContentOptions,type OtelDeclaration,type OtelIntegration,type OtelIntegrationOptions,type OtelOptions,+ type ManagedTraceOptions,+ type SpanAttributeDecision,+ type SpanExportAttributeValue,+ type SpanExportContext,+ type SpanExportPolicy,+ type SpanExportPredicate,+ type TraceCaptureContext,+ type TraceCapturePolicy,} from "#tracing/otel-declaration.js";export type { SpanExporter, SpanProcessor } from "#compiled/@vercel/otel/index.js";@@ -34,10 +45,10 @@ export type { SpanExporter, SpanProcessor } from "#compiled/@vercel/otel/index.j/*** Vercel Agent Runs, enabled by default in production.*- * Export it from `agent/instrumentation/agent-runs.ts` to configure content- * capture, or export `disableInstrumentation()` from that file to turn it off.+ * Export it from `agent/instrumentation/agent-runs.ts` to configure export, or+ * export `disableInstrumentation()` from that file to turn it off.*/-export function agentRuns(options: ContentOptions = {}): OtelIntegration {+export function agentRuns(options: ManagedTraceOptions = {}): OtelIntegration {return agentRunsIntegration(options);}@@ -47,13 +58,10 @@ export function agentRuns(options: ContentOptions = {}): OtelIntegration {* Export it from `agent/instrumentation/local.ts` to keep it alongside a hosted* backend, or export `disableInstrumentation()` from that file to turn it off.* Omitting the file leaves eve's default in place.- *- * `EVE_TRACES_CONTENT=on` opts the default local spool into content capture.- * `off` overrides this destination and no other, so declining content locally- * leaves what a hosted backend receives alone.*/-export function localTraces(options: ContentOptions = {}): OtelIntegration {- return otelIntegration({+export function localTraces(options: ManagedTraceOptions = {}): OtelIntegration {+ return managedOtelIntegration({+ ...options,...resolveLocalTracesContent(options),spanProcessors: [createLocalTracesProcessor()],});diff --git a/packages/eve/src/tracing/agent-action-instrumentation.ts b/packages/eve/src/tracing/agent-action-instrumentation.tsindex 4cad11bfb..83de88e60 100644--- a/packages/eve/src/tracing/agent-action-instrumentation.ts+++ b/packages/eve/src/tracing/agent-action-instrumentation.ts@@ -19,6 +19,9 @@ import { contentAttribute } from "#tracing/agent-otel-content.js";import { setAgentUsage } from "#tracing/agent-otel-usage.js";import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";import type { AgentActionTraceState, AgentTraceStateStore } from "#tracing/agent-trace-state.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";+import { isSampledTrace } from "#tracing/sampled-trace.js";+import { withChannelAudience } from "#tracing/channel-audience-context.js";export interface AgentActionInstrumentation {readonly events: Pick<@@ -56,12 +59,13 @@ export function createAgentActionInstrumentation(input: {const onStarted = async (event: InstrumentationActionStartedEvent): Promise<void> => {const traceContext = await input.resolveTraceContext(event);- if (traceContext === undefined) return;+ if (traceContext === undefined || !isSampledTrace(traceContext)) return;const existing = await input.stateStore.getAction(event.idempotencyKey);const state: AgentActionTraceState = existing ?? {attemptIndex: event.scope.attemptIndex,callId: event.callId,+ channelAudience: normalizeChannelAudience(event.scope.channelAudience),inputAttribute: input.recordInputs ? contentAttribute(event.input, false) : undefined,kind: event.kind,name: event.name,@@ -185,13 +189,19 @@ function actionContext(state: AgentActionTraceState): AgentActionContext {traceId: state.parent.traceId,};return {- context: trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext(spanContext)),+ context: withChannelAudience(+ trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext(spanContext)),+ state.channelAudience,+ ),spanContext,};}function contextFromActionState(state: AgentActionTraceState): Context {- return trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext({ ...state.parent, isRemote: false }));+ return withChannelAudience(+ trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext({ ...state.parent, isRemote: false })),+ state.channelAudience,+ );}function recordError(span: Span, error: unknown): void {diff --git a/packages/eve/src/tracing/agent-approval-instrumentation.ts b/packages/eve/src/tracing/agent-approval-instrumentation.tsindex 6f095249c..cff37245b 100644--- a/packages/eve/src/tracing/agent-approval-instrumentation.ts+++ b/packages/eve/src/tracing/agent-approval-instrumentation.ts@@ -17,11 +17,13 @@ import type { JsonValue } from "#shared/json.js";import { contentAttribute } from "#tracing/agent-otel-content.js";import type { AgentActionContext } from "#tracing/agent-action-instrumentation.js";import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";+import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";interface AgentApprovalSpanState {readonly actionCallId: string;readonly actionName: string;readonly attemptIndex: number;+ readonly channelAudience: ChannelAudience;readonly parent: SpanContext;readonly requestAttribute?: string;readonly requestId: string;@@ -63,6 +65,7 @@ export function createAgentApprovalInstrumentation(input: {actionCallId: event.action.callId,actionName: event.action.name,attemptIndex: event.scope.attemptIndex,+ channelAudience: normalizeChannelAudience(event.scope.channelAudience),parent: {spanId: parent.spanContext.spanId,traceFlags: parent.spanContext.traceFlags,@@ -158,6 +161,7 @@ function readState(value: unknown): AgentApprovalSpanState | undefined {actionCallId: state["actionCallId"],actionName: state["actionName"],attemptIndex: state["attemptIndex"],+ channelAudience: normalizeChannelAudience(state["channelAudience"]),parent: {isRemote: false,spanId: parentRecord["spanId"],diff --git a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.tsindex 97f861953..d363e9ac5 100644--- a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts+++ b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts@@ -17,11 +17,14 @@ import type {} from "#harness/instrumentation/lifecycle.js";import { sessionIdempotencyKey } from "#harness/instrumentation/lifecycle.js";import type { JsonValue } from "#shared/json.js";+import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";import { contentAttribute } from "#tracing/agent-otel-content.js";import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";import type { AgentSessionTraceState, AgentTraceStateStore } from "#tracing/agent-trace-state.js";+import { isSampledTrace } from "#tracing/sampled-trace.js";interface ChannelDeliverySpanState {+ readonly channelAudience: ChannelAudience;readonly inputAttribute?: string;readonly parent: SpanContext;readonly requestTraceContext?: SpanContext;@@ -53,6 +56,7 @@ export function createAgentChannelDeliveryInstrumentation(input: {): Promise<void> => {const session = await input.ensureSessionContext({agentName: event.agentName,+ channelAudience: event.delivery.channelAudience,channelKind: event.delivery.channelKind,idempotencyKey: sessionIdempotencyKey(event.sessionId),parentTraceContext: event.parentTraceContext,@@ -60,8 +64,10 @@ export function createAgentChannelDeliveryInstrumentation(input: {sessionId: event.sessionId,type: "session.started",});+ if (!isSampledTrace(session.context)) return;const inputAttribute = input.recordInputs ? contentAttribute(event.input, false) : undefined;const state: Record<string, JsonValue> = {+ channelAudience: normalizeChannelAudience(event.delivery.channelAudience),parent: {isRemote: session.context.isRemote ?? false,spanId: session.context.spanId,@@ -178,6 +184,7 @@ function readState(value: unknown): ChannelDeliverySpanState | undefined {? value.requestTraceContext: undefined;return {+ channelAudience: normalizeChannelAudience(value.channelAudience),inputAttribute: typeof value.inputAttribute === "string" ? value.inputAttribute : undefined,parent: value.parent,requestTraceContext,diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.tsindex fe2416717..849d4e849 100644--- a/packages/eve/src/tracing/agent-otel-provider.test.ts+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts@@ -15,7 +15,10 @@ import {import { ContextContainer, contextStorage } from "#context/container.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";-import { createAgentOtelInstrumentation } from "#tracing/agent-otel-provider.js";+import {+ createAgentOtelInstrumentation,+ type AgentOtelInstrumentationInput,+} from "#tracing/agent-otel-provider.js";import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";import { ContextAgentTraceStateStore } from "#tracing/agent-trace-context-store.js";import {@@ -33,6 +36,8 @@ import {type InstrumentationTraceContext,type InstrumentationUsage,} from "#harness/instrumentation/lifecycle.js";+import type { ChannelAudience } from "#shared/channel-audience.js";+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";import {actionIdempotencyKey,attemptIdempotencyKey,@@ -56,6 +61,7 @@ interface TestRuntime {function createRuntime(stateStore: AgentTraceStateStore = new InMemoryAgentTraceStateStore(),+ tracePolicy: TraceCapturePolicy | null = () => true,): TestRuntime {const exporter = new InMemorySpanExporter();const idGenerator = new AgentSpanIdGenerator();@@ -64,14 +70,18 @@ function createRuntime(spanProcessors: [new SimpleSpanProcessor(exporter)],});const tracer = provider.getTracer("eve.agent");- const agentOtel = createAgentOtelInstrumentation({+ const agentOtelInput: Omit<AgentOtelInstrumentationInput, "tracePolicy"> & {+ tracePolicy?: TraceCapturePolicy;+ } = {frameworkVersion: "test",idGenerator,recordInputs: true,recordOutputs: true,stateStore,tracer,- });+ };+ if (tracePolicy !== null) agentOtelInput.tracePolicy = tracePolicy;+ const agentOtel = createAgentOtelInstrumentation(agentOtelInput);const hooks = createInstrumentationHooks([agentOtel.hook]);return {exporter,@@ -88,6 +98,7 @@ async function emitAttempt(input: {readonly actionUsage?: InstrumentationUsage;readonly attemptIndex?: number;readonly attemptError?: Error;+ readonly channelAudience?: ChannelAudience;readonly hooks: InstrumentationHooks;readonly parentTraceContext?: InstrumentationTraceContext;readonly runInContext: InstrumentationContextRunner;@@ -105,6 +116,7 @@ async function emitAttempt(input: {const scope: InstrumentationAttemptScope = {attemptId: `${input.sessionId}:${input.turnId}:0:${input.attemptIndex ?? 0}`,attemptIndex: input.attemptIndex ?? 0,+ channelAudience: input.channelAudience,functionId: "weather",sessionId: input.sessionId,stepIndex: 0,@@ -274,6 +286,7 @@ async function emitAttempt(input: {}async function publishTurnStarted(input: {+ readonly channelAudience?: ChannelAudience;readonly hooks: InstrumentationHooks;readonly parentLineage?: InstrumentationParentLineage;readonly parentTraceContext?: InstrumentationTraceContext;@@ -285,6 +298,7 @@ async function publishTurnStarted(input: {const rootSessionId = input.rootSessionId ?? input.sessionId;await input.hooks.publish({agentName: "weather",+ channelAudience: input.channelAudience,channelKind: "http",idempotencyKey: sessionIdempotencyKey(input.sessionId),parentTraceContext: input.parentTraceContext,@@ -632,6 +646,7 @@ describe("createAgentOtelInstrumentation", () => {const contextWith = vi.spyOn(context, "with");await context.with(activeContext, () =>emitAttempt({+ channelAudience: "public",hooks: runtime.hooks,runInContext: runtime.runInContext,sessionId: "session-1",@@ -657,6 +672,7 @@ describe("createAgentOtelInstrumentation", () => {expect(session.parentSpanContext).toBeUndefined();expect(session.events.map((event) => event.name)).toEqual(["session.started"]);expect(session.attributes).toMatchObject({+ "agent.channel.audience": "public","agent.session.id": "session-1","agent.session.window": 0,"agent.trace.schema.version": 1,@@ -679,6 +695,9 @@ 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, operation, model, action, tool]) {+ expect(span.attributes).not.toHaveProperty("agent.channel.audience");+ }expect(new Set(spans@@ -710,6 +729,62 @@ describe("createAgentOtelInstrumentation", () => {});});+ it.each(["private", "unknown"] as const)(+ "does not record %s conversation traces by default",+ async (audience) => {+ const runtime = createRuntime(new InMemoryAgentTraceStateStore(), null);++ await emitAttempt({+ channelAudience: audience,+ hooks: runtime.hooks,+ runInContext: runtime.runInContext,+ sessionId: `session-${audience}`,+ turnId: `turn-${audience}`,+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ expect(runtime.exporter.getFinishedSpans()).toEqual([]);+ },+ );++ it("applies the private audience gate to an adopted sampled trace", async () => {+ const runtime = createRuntime(new InMemoryAgentTraceStateStore(), null);++ await emitAttempt({+ channelAudience: "private",+ hooks: runtime.hooks,+ parentTraceContext: {+ spanId: "a".repeat(16),+ traceFlags: 1,+ traceId: "b".repeat(32),+ },+ runInContext: runtime.runInContext,+ sessionId: "session-private",+ turnId: "turn-private",+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ expect(runtime.exporter.getFinishedSpans()).toEqual([]);+ });++ it("allows private tracing when the trace policy opts in", async () => {+ const runtime = createRuntime(new InMemoryAgentTraceStateStore(), () => true);++ await emitAttempt({+ channelAudience: "private",+ hooks: runtime.hooks,+ runInContext: runtime.runInContext,+ sessionId: "session-private",+ turnId: "turn-private",+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ expect(byName(runtime.exporter.getFinishedSpans(), "agent.session")).toHaveLength(1);+ });+it("writes merged runtime context onto the step, operation, and chat spans", async () => {const runtime = createRuntime();diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.tsindex 3e2122617..2900345e0 100644--- a/packages/eve/src/tracing/agent-otel-provider.ts+++ b/packages/eve/src/tracing/agent-otel-provider.ts@@ -27,6 +27,10 @@ import { createAgentChannelDeliveryInstrumentation } from "#tracing/agent-channeimport { createAgentToolInstrumentation } from "#tracing/agent-tool-instrumentation.js";import { setAgentUsage } from "#tracing/agent-otel-usage.js";import { createAgentOtelSessionContext } from "#tracing/agent-otel-session-context.js";+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";+import { isSampledTrace } from "#tracing/sampled-trace.js";+import { withChannelAudience } from "#tracing/channel-audience-context.js";+import { suppressTracing } from "#tracing/suppress-tracing.js";import type {InstrumentationStepAttemptMetadataEvent,InstrumentationAttemptScope,@@ -68,6 +72,7 @@ export interface AgentOtelInstrumentationInput {readonly idGenerator: AgentSpanIdGenerator;readonly stateStore: AgentTraceStateStore;readonly tracer: Tracer;+ readonly tracePolicy?: TraceCapturePolicy;}/** OTel event definition and its trusted framework context runner. */@@ -142,8 +147,11 @@ export function createAgentOtelInstrumentation(const onStepStarted = async (event: InstrumentationStepAttemptStartedEvent): Promise<void> => {const turn = await input.stateStore.getTurn(event.scope.sessionId, event.scope.turnId);- if (turn === undefined) return;- const turnContext = contextFromSpanContext(turn.context);+ if (turn === undefined || !isSampledTrace(turn.context)) return;+ const turnContext = withChannelAudience(+ contextFromSpanContext(turn.context),+ event.scope.channelAudience,+ );const activeSpanContext = trace.getSpan(context.active())?.spanContext();const stepSpan = input.idGenerator.withSpanId(input.idGenerator.deriveSpanId(attemptIdempotencyKey(event.scope)),@@ -251,39 +259,41 @@ export function createAgentOtelInstrumentation(const turn = await input.stateStore.getTurn(event.sessionId, event.turnId);if (turn !== undefined) {const session = await input.stateStore.getSession(event.sessionId);- const span = input.idGenerator.withSpanId(turn.context.spanId, () =>- input.tracer.startSpan(- "agent.turn",- {- attributes: {- "agent.framework.name": "eve",- "agent.framework.version": input.frameworkVersion,- "agent.name": session?.agentName,- ...parentLineageAttributes(turn.lineage),- "agent.root.session.id": turn.rootSessionId,- "agent.session.id": event.sessionId,- "agent.session.window": session?.window,- "agent.turn.id": event.turnId,- "agent.turn.sequence": turn.sequence,+ if (isSampledTrace(turn.context)) {+ const span = input.idGenerator.withSpanId(turn.context.spanId, () =>+ input.tracer.startSpan(+ "agent.turn",+ {+ attributes: {+ "agent.framework.name": "eve",+ "agent.framework.version": input.frameworkVersion,+ "agent.name": session?.agentName,+ ...parentLineageAttributes(turn.lineage),+ "agent.root.session.id": turn.rootSessionId,+ "agent.session.id": event.sessionId,+ "agent.session.window": session?.window,+ "agent.turn.id": event.turnId,+ "agent.turn.sequence": turn.sequence,+ },+ startTime: turn.startTimeMs,},- startTime: turn.startTimeMs,- },- contextFromSpanContext({- isRemote: turn.parentIsRemote ?? false,- spanId: turn.parentSpanId,- traceFlags: turn.context.traceFlags,- traceId: turn.context.traceId,- }),- ),- );- span.addEvent("turn.started", undefined, turn.startTimeMs);- if (turn.terminal !== undefined) {- span.addEvent(turn.terminal.type);- if (turn.terminal.type === "turn.failed") {- recordError(span, turn.terminal.error);+ contextFromSpanContext({+ isRemote: turn.parentIsRemote ?? false,+ spanId: turn.parentSpanId,+ traceFlags: turn.context.traceFlags,+ traceId: turn.context.traceId,+ }),+ ),+ );+ span.addEvent("turn.started", undefined, turn.startTimeMs);+ if (turn.terminal !== undefined) {+ span.addEvent(turn.terminal.type);+ if (turn.terminal.type === "turn.failed") {+ recordError(span, turn.terminal.error);+ }}+ span.end();}- span.end();await input.stateStore.deleteTurn(event.sessionId, event.turnId);}}@@ -458,13 +468,26 @@ export function createAgentOtelInstrumentation(},prepareSessionTrace,prepareTurnTrace,- runInContext(operation, execute) {+ async runInContext(operation, execute) {const scope = attemptScopes.get(operation.scope.attemptId) ?? operation.scope;const contexts = executionContexts.get(scope);- const parent =+ let parent =operation.type === "model.call"? contexts?.get(operation.idempotencyKey): tools.contextFor(operation.scope.attemptId, operation.idempotencyKey);+ if (parent === undefined) {+ const turn = await input.stateStore.getTurn(+ operation.scope.sessionId,+ operation.scope.turnId,+ );+ if (turn !== undefined) {+ parent = withChannelAudience(+ contextFromSpanContext(turn.context),+ operation.scope.channelAudience,+ );+ if (!isSampledTrace(turn.context)) parent = suppressTracing(parent);+ }+ }return parent === undefined ? execute() : context.with(parent, execute);},};diff --git a/packages/eve/src/tracing/agent-otel-session-context.ts b/packages/eve/src/tracing/agent-otel-session-context.tsindex 154f0c978..c0f2dbeac 100644--- a/packages/eve/src/tracing/agent-otel-session-context.ts+++ b/packages/eve/src/tracing/agent-otel-session-context.ts@@ -7,6 +7,9 @@ import {type InstrumentationTurnStartedEvent,} from "#harness/instrumentation/lifecycle.js";import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";+import type { ChannelAudience } from "#shared/channel-audience.js";+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";import {SESSION_WINDOW_TURN_LIMIT,type AgentSessionTraceState,@@ -18,6 +21,7 @@ interface AgentOtelSessionContextInput {readonly idGenerator: AgentSpanIdGenerator;readonly stateStore: AgentTraceStateStore;readonly tracer: Tracer;+ readonly tracePolicy?: TraceCapturePolicy;}interface AgentOtelSessionContext {@@ -37,15 +41,25 @@ export function createAgentOtelSessionContext(): AgentOtelSessionContext {const openSessionWindow = (window: {readonly agentName?: string;+ readonly channelAudience: ChannelAudience;readonly index: number;readonly previousTraceId?: string;readonly rootSessionId: string;readonly sessionId: string;}): SpanContext => {+ if (!shouldTrace(input.tracePolicy, window)) {+ return {+ isRemote: false,+ spanId: input.idGenerator.deriveSpanId(`session:${window.sessionId}:${window.index}`),+ traceFlags: 0,+ traceId: input.idGenerator.generateTraceId(),+ };+ }const span = input.tracer.startSpan("agent.session", {attributes: {"agent.framework.name": "eve","agent.framework.version": input.frameworkVersion,+ "agent.channel.audience": window.channelAudience,"agent.name": window.agentName,"agent.root.session.id": window.rootSessionId,"agent.session.id": window.sessionId,@@ -72,16 +86,26 @@ export function createAgentOtelSessionContext(if (state === undefined) {state = {agentName: event.agentName,+ channelAudience: normalizeChannelAudience(event.channelAudience),channelKind: event.channelKind,context:event.parentTraceContext === undefined? openSessionWindow({agentName: event.agentName,+ channelAudience: normalizeChannelAudience(event.channelAudience),index: 0,rootSessionId: event.rootSessionId,sessionId: event.sessionId,})- : adoptedSpanContext(event.parentTraceContext),+ : adoptedSpanContext(+ event.parentTraceContext,+ shouldTrace(input.tracePolicy, {+ agentName: event.agentName,+ channelAudience: normalizeChannelAudience(event.channelAudience),+ rootSessionId: event.rootSessionId,+ sessionId: event.sessionId,+ }),+ ),rootSessionId: event.rootSessionId,turnsInWindow: 0,window: 0,@@ -101,6 +125,7 @@ export function createAgentOtelSessionContext(...session,context: openSessionWindow({agentName: session.agentName,+ channelAudience: normalizeChannelAudience(session.channelAudience),index,previousTraceId: session.context.traceId,rootSessionId: session.rootSessionId,@@ -133,6 +158,7 @@ export function createAgentOtelSessionContext(event.sessionId,await ensureSessionContext({agentName: undefined,+ channelAudience: "unknown",channelKind: undefined,idempotencyKey: sessionIdempotencyKey(event.sessionId),parentTraceContext: event.parentTraceContext,@@ -169,6 +195,29 @@ export function createAgentOtelSessionContext(return { ensureSessionContext, prepareSessionTrace, prepareTurnTrace };}+function shouldTrace(+ policy: TraceCapturePolicy | undefined,+ trace: {+ readonly agentName?: string;+ readonly channelAudience: ChannelAudience;+ readonly rootSessionId: string;+ readonly sessionId: string;+ },+): boolean {+ try {+ return (+ policy?.({+ agentName: trace.agentName,+ audience: trace.channelAudience,+ rootSessionId: trace.rootSessionId,+ sessionId: trace.sessionId,+ }) ?? trace.channelAudience === "public"+ );+ } catch {+ return false;+ }+}+function portableSpanContext(spanContext: SpanContext): InstrumentationTraceContext {return {spanId: spanContext.spanId,@@ -177,11 +226,11 @@ function portableSpanContext(spanContext: SpanContext): InstrumentationTraceCont};}-function adoptedSpanContext(handed: InstrumentationTraceContext): SpanContext {+function adoptedSpanContext(handed: InstrumentationTraceContext, sampled = true): SpanContext {return {isRemote: "isRemote" in handed && handed.isRemote === true,spanId: handed.spanId,- traceFlags: handed.traceFlags,+ traceFlags: sampled ? handed.traceFlags : 0,traceId: handed.traceId,};}diff --git a/packages/eve/src/tracing/agent-trace-context-store.ts b/packages/eve/src/tracing/agent-trace-context-store.tsindex 104101347..eba434d30 100644--- a/packages/eve/src/tracing/agent-trace-context-store.ts+++ b/packages/eve/src/tracing/agent-trace-context-store.ts@@ -9,6 +9,7 @@ import type {AgentTraceStateStore,AgentTurnTraceState,} from "#tracing/agent-trace-state.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";interface AgentTraceContextState {readonly actions: Readonly<Record<string, AgentActionTraceState>>;@@ -191,6 +192,7 @@ function deserializeState(data: unknown): AgentTraceContextState {if (!isRecord(value) || !isSpanContext(value.context)) return undefined;return {agentName: typeof value.agentName === "string" ? value.agentName : undefined,+ channelAudience: normalizeChannelAudience(value.channelAudience),channelKind: typeof value.channelKind === "string" ? value.channelKind : undefined,context: value.context,rootSessionId: typeof value.rootSessionId === "string" ? value.rootSessionId : "",@@ -237,6 +239,7 @@ function deserializeAction(value: unknown): AgentActionTraceState | undefined {return {attemptIndex: value.attemptIndex,callId: value.callId,+ channelAudience: normalizeChannelAudience(value.channelAudience),inputAttribute: typeof value.inputAttribute === "string" ? value.inputAttribute : undefined,kind: value.kind,name: value.name,diff --git a/packages/eve/src/tracing/agent-trace-state.ts b/packages/eve/src/tracing/agent-trace-state.tsindex 21c79182d..84f0d32cd 100644--- a/packages/eve/src/tracing/agent-trace-state.ts+++ b/packages/eve/src/tracing/agent-trace-state.ts@@ -7,11 +7,13 @@ import type {InstrumentationTurnFailedEvent,InstrumentationTurnSettledEvent,} from "#harness/instrumentation/lifecycle.js";+import type { ChannelAudience } from "#shared/channel-audience.js";/** Sized so an ordinary session stays one trace and only an outsized one rolls. */export const SESSION_WINDOW_TURN_LIMIT = 200;export interface AgentSessionTraceState {+ readonly channelAudience?: ChannelAudience;readonly agentName?: string;readonly channelKind?: string;readonly context: SpanContext;@@ -36,6 +38,7 @@ export interface AgentTurnTraceState {export interface AgentActionTraceState {readonly attemptIndex: number;readonly callId: string;+ readonly channelAudience?: ChannelAudience;readonly inputAttribute?: string;readonly kind: InstrumentationActionKind;readonly name: string;diff --git a/packages/eve/src/tracing/channel-audience-context.ts b/packages/eve/src/tracing/channel-audience-context.tsnew file mode 100644index 000000000..a8884c3bd--- /dev/null+++ b/packages/eve/src/tracing/channel-audience-context.ts@@ -0,0 +1,16 @@+import { createContextKey, type Context } from "#compiled/@opentelemetry/api/index.js";+import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";++const CHANNEL_AUDIENCE_KEY = createContextKey("eve.channel.audience");++export function channelAudienceFromContext(context: unknown): ChannelAudience {+ if (typeof context !== "object" || context === null) return "unknown";+ const getValue = Reflect.get(context, "getValue");+ return typeof getValue === "function"+ ? normalizeChannelAudience(Reflect.apply(getValue, context, [CHANNEL_AUDIENCE_KEY]))+ : "unknown";+}++export function withChannelAudience(context: Context, audience: unknown): Context {+ return context.setValue(CHANNEL_AUDIENCE_KEY, normalizeChannelAudience(audience));+}diff --git a/packages/eve/src/tracing/content-attributes.ts b/packages/eve/src/tracing/content-attributes.tsindex 5e9f33062..bc7b3a866 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.approval.request","ai.documents","ai.prompt","ai.prompt.messages",@@ -37,6 +38,7 @@ const INPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([* `recordOutputs`; matching that is what keeps one destination's view coherent.*/const OUTPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([+ "agent.approval.response","ai.embedding","ai.embeddings","ai.ranking",diff --git a/packages/eve/src/tracing/content-span-processor.test.ts b/packages/eve/src/tracing/content-span-processor.test.tsindex 628e87e70..26dd66535 100644--- a/packages/eve/src/tracing/content-span-processor.test.ts+++ b/packages/eve/src/tracing/content-span-processor.test.ts@@ -7,6 +7,11 @@ import {import type { SpanProcessor } from "#compiled/@vercel/otel/index.js";import { contentFilteringProcessor } from "#tracing/content-span-processor.js";+import {+ composeSpanExportPolicies,+ redactSpanInputs,+ redactSpanOutputs,+} from "#tracing/span-export-policy.js";function recordingProcessor(): SpanProcessor & {readonly ended: unknown[];@@ -40,9 +45,7 @@ describe("contentFilteringProcessor", () => {const downstream = recordingProcessor();const original = span({ "ai.prompt.messages": "what the user said" });- contentFilteringProcessor(downstream, { recordInputs: true, recordOutputs: true }).onEnd(- original as never,- );+ contentFilteringProcessor(downstream).onEnd(original as never);expect(downstream.ended).toEqual([original]);});@@ -50,7 +53,7 @@ describe("contentFilteringProcessor", () => {it("forwards a copy without what the destination declined", () => {const downstream = recordingProcessor();- contentFilteringProcessor(downstream, { recordInputs: false, recordOutputs: true }).onEnd(+ contentFilteringProcessor(downstream, redactSpanInputs()).onEnd(span({"ai.prompt.messages": "what the user said","ai.response.text": "what the model said",@@ -67,9 +70,10 @@ describe("contentFilteringProcessor", () => {const declined = recordingProcessor();const original = span({ "ai.prompt.messages": "what the user said" });- contentFilteringProcessor(declined, { recordInputs: false, recordOutputs: false }).onEnd(- original as never,- );+ contentFilteringProcessor(+ declined,+ composeSpanExportPolicies(redactSpanInputs(), redactSpanOutputs()),+ ).onEnd(original as never);kept.onEnd(original as never);expect((declined.ended[0] as { attributes: unknown }).attributes).toEqual({});@@ -81,9 +85,10 @@ describe("contentFilteringProcessor", () => {it("keeps the rest of the span surface reachable on the copy", () => {const downstream = recordingProcessor();- contentFilteringProcessor(downstream, { recordInputs: false, recordOutputs: false }).onEnd(- span({ "ai.prompt.messages": "what the user said" }) as never,- );+ contentFilteringProcessor(+ downstream,+ composeSpanExportPolicies(redactSpanInputs(), redactSpanOutputs()),+ ).onEnd(span({ "ai.prompt.messages": "what the user said" }) as never);expect((downstream.ended[0] as { spanContext: () => unknown }).spanContext()).toEqual({spanId: "span",@@ -102,9 +107,7 @@ describe("contentFilteringProcessor", () => {status: { code: 2, message: "private failure detail" },};- contentFilteringProcessor(downstream, { recordInputs: true, recordOutputs: false }).onEnd(- original as never,- );+ contentFilteringProcessor(downstream, redactSpanOutputs()).onEnd(original as never);const visible = downstream.ended[0] as {events: unknown[];@@ -123,7 +126,7 @@ describe("contentFilteringProcessor", () => {"service.name": "weather",});- contentFilteringProcessor(downstream, { recordInputs: false, recordOutputs: true }).onStart(+ contentFilteringProcessor(downstream, redactSpanInputs()).onStart(original as never,undefined as never,);@@ -144,10 +147,7 @@ describe("contentFilteringProcessor", () => {"ai.prompt.messages": "what the user said","service.name": "weather",}) as { attributes: Record<string, unknown> };- const processor = contentFilteringProcessor(downstream, {- recordInputs: false,- recordOutputs: true,- });+ const processor = contentFilteringProcessor(downstream, redactSpanInputs());processor.onStart(original as never, undefined as never);const retainedAttributes = (downstream.started[0] as { attributes: unknown }).attributes;@@ -184,10 +184,7 @@ describe("contentFilteringProcessor", () => {},};const downstream = recordingProcessor();- const processor = contentFilteringProcessor(downstream, {- recordInputs: false,- recordOutputs: true,- });+ const processor = contentFilteringProcessor(downstream, redactSpanInputs());processor.onStart(original as never, undefined as never);@@ -210,10 +207,7 @@ describe("contentFilteringProcessor", () => {const original = span({ "ai.prompt.messages": "what the user said" }) as {attributes: Record<string, unknown>;};- const processor = contentFilteringProcessor(downstream, {- recordInputs: false,- recordOutputs: true,- });+ const processor = contentFilteringProcessor(downstream, redactSpanInputs());processor.onStart(original as never, undefined as never);Object.freeze(downstream.started[0]);@@ -227,10 +221,7 @@ describe("contentFilteringProcessor", () => {it("facades a real OpenTelemetry span across both callbacks", () => {const downstream = recordingProcessor();- const filtering = contentFilteringProcessor(downstream, {- recordInputs: false,- recordOutputs: true,- });+ const filtering = contentFilteringProcessor(downstream, redactSpanInputs());const provider = new BasicTracerProvider({spanProcessors: [filtering as OpenTelemetrySpanProcessor],});@@ -250,15 +241,92 @@ describe("contentFilteringProcessor", () => {});});+ it.each([+ ["public", true],+ ["private", false],+ ["unknown", false],+ ] as const)("retains content for the %s audience: %s", (audience, retained) => {+ const downstream = recordingProcessor();+ contentFilteringProcessor(+ downstream,+ composeSpanExportPolicies(+ redactSpanInputs(({ audience }) => audience !== "public"),+ redactSpanOutputs(({ audience }) => audience !== "public"),+ ),+ ).onEnd(+ span({+ "agent.channel.audience": audience,+ "ai.prompt.messages": "input",+ "ai.response.text": "output",+ }) as never,+ );++ const expected: Record<string, unknown> = { "agent.channel.audience": audience };+ if (retained) {+ expected["ai.prompt.messages"] = "input";+ expected["ai.response.text"] = "output";+ }+ expect((downstream.ended[0] as { attributes: Record<string, unknown> }).attributes).toEqual(+ expected,+ );+ });++ it("fails closed when audience attributes disagree", () => {+ const downstream = recordingProcessor();+ contentFilteringProcessor(+ downstream,+ composeSpanExportPolicies(+ redactSpanInputs(({ audience }) => audience !== "public"),+ redactSpanOutputs(({ audience }) => audience !== "public"),+ ),+ ).onEnd(+ span({+ "agent.channel.audience": "public",+ "ai.prompt.messages": "private",+ "ai.settings.context.eve.channel.audience": "private",+ }) as never,+ );++ expect(+ (downstream.ended[0] as { attributes: Record<string, unknown> }).attributes,+ ).not.toHaveProperty("ai.prompt.messages");+ });++ it("can drop an individual span", () => {+ const downstream = recordingProcessor();+ contentFilteringProcessor(downstream, { span: ({ name }) => name !== "private-work" }).onEnd({+ ...(span({}) as object),+ name: "private-work",+ } as never);++ expect(downstream.ended).toEqual([]);+ });++ it("can drop and replace individual attributes", () => {+ const downstream = recordingProcessor();+ contentFilteringProcessor(downstream, {+ attribute: ({ key }) =>+ key === "secret"+ ? { action: "drop" }+ : key === "email"+ ? { action: "replace", value: "[redacted]" }+ : { action: "keep" },+ }).onEnd(span({ email: "[email protected]", secret: "value" }) as never);++ expect((downstream.ended[0] as { attributes: unknown }).attributes).toEqual({+ email: "[redacted]",+ });+ });+it("preserves local trace session release through the wrapper", async () => {const releaseSession = vi.fn(async () => true);const downstream: SpanProcessor & {releaseSession(sessionId: string): Promise<boolean>;} = { ...recordingProcessor(), releaseSession };- const processor = contentFilteringProcessor(downstream, {- recordInputs: false,- recordOutputs: false,- }) as SpanProcessor & { releaseSession(sessionId: string): Promise<boolean> };+ const processor = contentFilteringProcessor(+ downstream,+ composeSpanExportPolicies(redactSpanInputs(), redactSpanOutputs()),+ ) as SpanProcessor & { releaseSession(sessionId: string): Promise<boolean> };await expect(processor.releaseSession("session-1")).resolves.toBe(true);expect(releaseSession).toHaveBeenCalledExactlyOnceWith("session-1");diff --git a/packages/eve/src/tracing/content-span-processor.ts b/packages/eve/src/tracing/content-span-processor.tsindex 9465eb844..563162c8c 100644--- a/packages/eve/src/tracing/content-span-processor.ts+++ b/packages/eve/src/tracing/content-span-processor.ts@@ -5,15 +5,24 @@ import {type ResolvedContentOptions,} from "#tracing/content-attributes.js";import { hasSessionRelease, type LocalTracesProcessor } from "#tracing/local-traces.js";+import { normalizeChannelAudience } from "#shared/channel-audience.js";+import type { ChannelAudience } from "#shared/channel-audience.js";+import {+ contentRedactionForSpan,+ spanExportPolicyStages,+ type SpanExportContext,+ type SpanExportPolicy,+} from "#tracing/span-export-policy.js";+import { channelAudienceFromContext } from "#tracing/channel-audience-context.js";/*** Puts one destination's content policy in front of it.*- * Content is written onto a span if any destination wants it, so the span- * reaching a destination that declined still carries it. This cannot strip the- * attribute in place: that span object is shared with every other processor in- * the pipeline, and editing it would strip the attribute everywhere. So it- * gives the destination a facade whose attributes omit what it declined.+ * Accepted traces carry content before they reach destination policies. This+ * cannot strip an attribute in place: the span object is shared with every+ * processor in the pipeline, and editing it would strip the attribute+ * everywhere. So it gives the destination a facade whose attributes omit what+ * its policy redacted.** One facade follows the original from start through end. This preserves the* object identity stateful processors key on without ever exposing the original@@ -24,20 +33,36 @@ import { hasSessionRelease, type LocalTracesProcessor } from "#tracing/local-tra*/export function contentFilteringProcessor(downstream: SpanProcessor,- content: ResolvedContentOptions,+ exportPolicy?: SpanExportPolicy,): SpanProcessor {- if (content.recordInputs && content.recordOutputs) return downstream;+ if (exportPolicy === undefined) return downstream;+ let processor = downstream;+ for (const policy of spanExportPolicyStages(exportPolicy).toReversed()) {+ processor = policyFilteringProcessor(processor, policy);+ }+ return processor;+}++function policyFilteringProcessor(+ downstream: SpanProcessor,+ exportPolicy: SpanExportPolicy,+): SpanProcessor {const facades = new WeakMap<object, SpanFacade>();+ const dropped = new WeakSet<object>();const filtering: SpanProcessor = {forceFlush: () => downstream.forceFlush(),onEnd: (span) => {if (typeof span !== "object" || span === null) {- downstream.onEnd(span);return;}- const scoped = facadeFor(span, content, facades);+ const scoped = facadeFor(span, exportPolicy, facades);+ if (dropped.has(span) || !scoped.exported) {+ dropped.delete(span);+ facades.delete(span);+ return;+ }scoped.refresh();try {downstream.onEnd(scoped.value);@@ -47,10 +72,19 @@ export function contentFilteringProcessor(},onStart: (span, parentContext) => {if (typeof span !== "object" || span === null) {- downstream.onStart(span, parentContext);return;}- downstream.onStart(facadeFor(span, content, facades).value, parentContext);+ const scoped = facadeFor(+ span,+ exportPolicy,+ facades,+ channelAudienceFromContext(parentContext),+ );+ if (!scoped.exported) {+ dropped.add(span);+ return;+ }+ downstream.onStart(scoped.value, parentContext);},shutdown: () => downstream.shutdown(),};@@ -64,27 +98,32 @@ export function contentFilteringProcessor(}interface SpanFacade {+ readonly context: SpanExportContext;+ readonly exported: boolean;readonly refresh: () => void;readonly value: object;}function facadeFor(span: object,- content: ResolvedContentOptions,+ exportPolicy: SpanExportPolicy,facades: WeakMap<object, SpanFacade>,+ inheritedAudience?: ChannelAudience,): SpanFacade {const existing = facades.get(span);if (existing !== undefined) return existing;+ const context = spanExportContext(span, inheritedAudience);+ const effectiveContent = contentForSpan(context, exportPolicy);const attributes: Record<string, unknown> = {};const events: unknown[] = [];const status: Record<string, unknown> = {};const target = Object.create(Reflect.getPrototypeOf(span)) as Record<PropertyKey, unknown>;const boundMethods = new Map<PropertyKey, unknown>();const refresh = (): void => {- refreshAttributes(attributes, span, content);- refreshEvents(events, span, content);- refreshStatus(status, span, content);+ refreshAttributes(attributes, span, effectiveContent, context, exportPolicy);+ refreshEvents(events, span, effectiveContent);+ refreshStatus(status, span, effectiveContent);};let value: object;const readOriginal = (property: PropertyKey): unknown => {@@ -134,6 +173,8 @@ function facadeFor(: readOriginal(property),});const facade = {+ context,+ exported: shouldExport(context, exportPolicy),refresh,value,};@@ -142,10 +183,20 @@ function facadeFor(return facade;}+function contentForSpan(span: SpanExportContext, policy: SpanExportPolicy): ResolvedContentOptions {+ const redaction = contentRedactionForSpan(policy, span);+ return {+ recordInputs: !redaction.redactInputs,+ recordOutputs: !redaction.redactOutputs,+ };+}+function refreshAttributes(destination: Record<string, unknown>,span: object,content: ResolvedContentOptions,+ context: SpanExportContext,+ policy: SpanExportPolicy | undefined,): void {for (const key of Object.keys(destination)) delete destination[key];@@ -153,7 +204,68 @@ function refreshAttributes(if (typeof source !== "object" || source === null) return;const kept = withoutDeclinedContent(source as Record<string, unknown>, content);- Object.assign(destination, kept ?? source);+ const visible = kept ?? (source as Record<string, unknown>);+ for (const [key, value] of Object.entries(visible)) {+ const decision = attributeDecision(policy, { key, span: context, value });+ if (decision.action === "keep") destination[key] = value;+ else if (decision.action === "replace") destination[key] = decision.value;+ }+}++function spanExportContext(+ span: object,+ inheritedAudience: ChannelAudience = "unknown",+): SpanExportContext {+ const attributes = (span as { readonly attributes?: unknown }).attributes;+ const record =+ typeof attributes === "object" && attributes !== null+ ? (attributes as Readonly<Record<string, unknown>>)+ : {};+ const candidates = [+ record["agent.channel.audience"],+ record["ai.settings.context.eve.channel.audience"],+ ].filter((value) => value !== undefined);+ const normalized = candidates.map(normalizeChannelAudience);+ const audience =+ normalized.length > 0 && normalized.every((value) => value === normalized[0])+ ? normalized[0]!+ : normalized.length > 0+ ? "unknown"+ : inheritedAudience;+ const spanContext = (span as { readonly spanContext?: () => unknown }).spanContext?.();+ const ids =+ typeof spanContext === "object" && spanContext !== null+ ? (spanContext as Readonly<Record<string, unknown>>)+ : {};+ const name = (span as { readonly name?: unknown }).name;+ return {+ attributes: record,+ audience,+ name: typeof name === "string" ? name : "",+ spanId: typeof ids["spanId"] === "string" ? ids["spanId"] : "",+ traceId: typeof ids["traceId"] === "string" ? ids["traceId"] : "",+ };+}++function shouldExport(context: SpanExportContext, policy: SpanExportPolicy | undefined): boolean {+ if (policy === undefined) return true;+ try {+ return policy.span?.(context) !== false;+ } catch {+ return false;+ }+}++function attributeDecision(+ policy: SpanExportPolicy | undefined,+ input: Parameters<NonNullable<SpanExportPolicy["attribute"]>>[0],+) {+ if (policy?.attribute === undefined) return { action: "keep" } as const;+ try {+ return policy.attribute(input);+ } catch {+ return { action: "drop" } as const;+ }}function refreshEvents(diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.test.ts b/packages/eve/src/tracing/install-instrumentation-runtime.test.tsindex 84d2edd9b..d56ad362a 100644--- a/packages/eve/src/tracing/install-instrumentation-runtime.test.ts+++ b/packages/eve/src/tracing/install-instrumentation-runtime.test.ts@@ -70,8 +70,9 @@ describe("installInstrumentationRuntime", () => {expect(forceFlush).toHaveBeenCalledOnce();expect(providerFlush).toHaveBeenCalledOnce();expect(runtime.otelSettings).toEqual({- recordInputs: false,- recordOutputs: false,+ functionId: undefined,+ recordInputs: true,+ recordOutputs: true,traceChannelRequests: false,});expect(shutdown).toHaveBeenCalledOnce();diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.ts b/packages/eve/src/tracing/install-instrumentation-runtime.tsindex c3882e7c5..7c78c5e3f 100644--- a/packages/eve/src/tracing/install-instrumentation-runtime.ts+++ b/packages/eve/src/tracing/install-instrumentation-runtime.ts@@ -54,6 +54,7 @@ export function installInstrumentationRuntime(input: {recordOutputs: input.collected.settings.recordOutputs,stateStore: new ContextAgentTraceStateStore(),tracer: trace.getTracer("eve.agent", input.frameworkVersion),+ tracePolicy: input.collected.settings.tracePolicy,});// The span must exist before authored providers observe the lifecycle event.serialBefore.push({ ...agentOtel.hook, stateNamespace: "internal:otel" });diff --git a/packages/eve/src/tracing/local-instrumentation-runtime.ts b/packages/eve/src/tracing/local-instrumentation-runtime.tsindex 3695f01dd..905547fb1 100644--- a/packages/eve/src/tracing/local-instrumentation-runtime.ts+++ b/packages/eve/src/tracing/local-instrumentation-runtime.ts@@ -4,7 +4,16 @@ import {} from "#harness/instrumentation/runtime.js";import { installInstrumentationRuntime } from "#tracing/install-instrumentation-runtime.js";import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";-import { collectOtelPipeline, otel, otelIntegration } from "#tracing/otel-declaration.js";+import {+ collectOtelPipeline,+ managedOtelIntegration,+ otel,+ type TraceCapturePolicy,+} from "#tracing/otel-declaration.js";++/** Zero-config local tracing keeps unclassified HTTP/TUI sessions observable. @internal */+export const localTracePolicy: TraceCapturePolicy = ({ audience }) =>+ audience === "public" || audience === "unknown";/** Installs the zero-config local OTel runtime once in an `eve dev` worker. */export function installLocalInstrumentationRuntime(input: {@@ -18,8 +27,11 @@ export function installLocalInstrumentationRuntime(input: {const spool = createLocalTracesProcessor({ appRoot: input.appRoot });return installInstrumentationRuntime({collected: collectOtelPipeline([- otel(),- otelIntegration({ ...resolveLocalTracesContent(), spanProcessors: [spool] }),+ otel({ tracePolicy: localTracePolicy }),+ managedOtelIntegration({+ ...resolveLocalTracesContent(),+ spanProcessors: [spool],+ }),]),frameworkVersion: input.frameworkVersion,providers: [],diff --git a/packages/eve/src/tracing/local-traces.test.ts b/packages/eve/src/tracing/local-traces.test.tsindex ac7e42240..e0bd1e850 100644--- a/packages/eve/src/tracing/local-traces.test.ts+++ b/packages/eve/src/tracing/local-traces.test.ts@@ -1,6 +1,7 @@import { afterEach, describe, expect, it, vi } from "vitest";import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";+import { localTracePolicy } from "#tracing/local-instrumentation-runtime.js";import { localTraces } from "#public/instrumentation/otel.js";vi.mock("#tracing/local-trace-span-processor.js", () => ({@@ -65,21 +66,21 @@ describe("createLocalTracesProcessor", () => {});describe("resolveLocalTracesContent", () => {- it("records no content by default", () => {+ it("retains content by default", () => {expect(resolveLocalTracesContent()).toEqual({- recordInputs: false,- recordOutputs: false,+ recordInputs: true,+ recordOutputs: true,});});- it("records content when explicitly enabled", () => {- expect(resolveLocalTracesContent({ recordInputs: true, recordOutputs: true })).toEqual({- recordInputs: true,+ it("preserves explicit legacy redaction", () => {+ expect(resolveLocalTracesContent({ recordInputs: false })).toEqual({+ recordInputs: false,recordOutputs: true,});});- it("uses EVE_TRACES_CONTENT=on as the zero-config opt-in", () => {+ it("keeps EVE_TRACES_CONTENT=on compatible with the new default", () => {vi.stubEnv("EVE_TRACES_CONTENT", "on");expect(resolveLocalTracesContent()).toEqual({@@ -88,7 +89,7 @@ describe("resolveLocalTracesContent", () => {});});- it("lets EVE_TRACES_CONTENT=off override explicit local capture", () => {+ it("maps EVE_TRACES_CONTENT=off to full local redaction", () => {vi.stubEnv("EVE_TRACES_CONTENT", "off");expect(resolveLocalTracesContent({ recordInputs: true, recordOutputs: true })).toEqual({@@ -97,3 +98,19 @@ describe("resolveLocalTracesContent", () => {});});});++describe("localTracePolicy", () => {+ it.each([+ ["public", true],+ ["unknown", true],+ ["private", false],+ ] as const)("accepts the %s audience: %s", (audience, accepted) => {+ expect(+ localTracePolicy({+ audience,+ rootSessionId: "session-1",+ sessionId: "session-1",+ }),+ ).toBe(accepted);+ });+});diff --git a/packages/eve/src/tracing/local-traces.ts b/packages/eve/src/tracing/local-traces.tsindex 37c51d50f..b9310bb93 100644--- a/packages/eve/src/tracing/local-traces.ts+++ b/packages/eve/src/tracing/local-traces.ts@@ -89,27 +89,19 @@ export function createLocalTracesProcessor(};}-/**- * The local spool's content policy: its options, intersected with- * `EVE_TRACES_CONTENT`.- *- * The variable applies to this destination only. `on` opts the zero-config- * spool into content, while `off` overrides authored local options without- * changing what a hosted backend beside it receives.- *- * @internal- */+/** Maps legacy local content configuration onto destination redaction. @internal */export function resolveLocalTracesContent(options: {readonly recordInputs?: boolean;readonly recordOutputs?: boolean;} = {},): { readonly recordInputs: boolean; readonly recordOutputs: boolean } {- const environmentDefault = process.env.EVE_TRACES_CONTENT === "on";- const enabled = process.env.EVE_TRACES_CONTENT !== "off";+ if (process.env.EVE_TRACES_CONTENT === "off") {+ return { recordInputs: false, recordOutputs: false };+ }return {- recordInputs: enabled && (options.recordInputs ?? environmentDefault),- recordOutputs: enabled && (options.recordOutputs ?? environmentDefault),+ recordInputs: options.recordInputs !== false,+ recordOutputs: options.recordOutputs !== false,};}diff --git a/packages/eve/src/tracing/otel-declaration.test.ts b/packages/eve/src/tracing/otel-declaration.test.tsindex 89789075d..57173f035 100644--- a/packages/eve/src/tracing/otel-declaration.test.ts+++ b/packages/eve/src/tracing/otel-declaration.test.ts@@ -6,9 +6,11 @@ import {collectOtelPipeline,isOtelDeclaration,isOtelIntegration,+ managedOtelIntegration,otel,otelIntegration,} from "#tracing/otel-declaration.js";+import { composeSpanExportPolicies, redactSpanInputs } from "#tracing/span-export-policy.js";/** Collection only ever moves processors, so a fresh no-op is identity enough. */function processor(): SpanProcessor {@@ -29,6 +31,14 @@ function exporter(): SpanExporter {};}+function testSpan(attributes: Record<string, unknown>): never {+ return {+ attributes,+ name: "agent.step",+ spanContext: () => ({ spanId: "span", traceId: "trace" }),+ } as never;+}+describe("otel", () => {it("declares settings without registering anything", () => {const declaration = otel({ sampler: "always_on" });@@ -41,8 +51,6 @@ describe("otelIntegration", () => {it("passes declared processors through untouched", () => {const first = processor();const integration = otelIntegration({- recordInputs: true,- recordOutputs: true,spanProcessors: [first],});@@ -53,8 +61,6 @@ describe("otelIntegration", () => {it("wraps an exporter in a batching processor, after any declared ones", () => {const first = processor();const integration = otelIntegration({- recordInputs: true,- recordOutputs: true,spanProcessors: [first],traceExporter: exporter(),});@@ -63,39 +69,94 @@ describe("otelIntegration", () => {expect(integration.spanProcessors[0]).toBe(first);});- it("records no content unless explicitly enabled", () => {- expect(otelIntegration().content).toStrictEqual({ recordInputs: false, recordOutputs: false });- });-- // An author's own processor is part of this destination, and the point of- // declining is that nothing under it sees what was said.- it("puts a declined policy in front of every processor, an author's included", () => {+ it("maps deprecated capture switches to destination redaction", () => {const first = processor();- const integration = otelIntegration({- recordInputs: true,- recordOutputs: false,- spanProcessors: [first],- });+ const integration = otelIntegration({ recordInputs: false, spanProcessors: [first] });- expect(integration.content).toStrictEqual({ recordInputs: true, recordOutputs: false });+ expect(integration.content).toEqual({ recordInputs: false, recordOutputs: true });expect(integration.spanProcessors[0]).not.toBe(first);});});describe("agentRunsIntegration", () => {- it("records no content by default", () => {+ it("declares the Agent Runs runtime processor", () => {const integration = agentRunsIntegration();- expect(integration.content).toStrictEqual({ recordInputs: false, recordOutputs: false });expect(integration.spanProcessors).toHaveLength(1);expect(integration.spanProcessors[0]).not.toBe("auto");});+});++describe("managed export policy", () => {+ it("does not redact content unless the export pipeline requests it", () => {+ let visibleAttributes: Readonly<Record<string, unknown>> | undefined;+ const integration = managedOtelIntegration({+ exportPolicy: {+ span: ({ attributes }) => {+ visibleAttributes = attributes;+ return true;+ },+ },+ spanProcessors: [processor()],+ });++ const spanProcessor = integration.spanProcessors[0];+ if (spanProcessor === undefined || spanProcessor === "auto") throw new Error("Expected policy");+ spanProcessor.onEnd(+ testSpan({+ "agent.channel.audience": "private",+ "ai.prompt.messages": "private input",+ }),+ );++ expect(visibleAttributes).toHaveProperty("ai.prompt.messages", "private input");+ });++ it("runs composed export policies in declaration order", () => {+ let visibleAttributes: Readonly<Record<string, unknown>> | undefined;+ const integration = managedOtelIntegration({+ exportPolicy: composeSpanExportPolicies(+ redactSpanInputs(({ audience }) => audience !== "public"),+ {+ span: ({ attributes }) => {+ visibleAttributes = attributes;+ return true;+ },+ },+ ),+ spanProcessors: [processor()],+ });++ const spanProcessor = integration.spanProcessors[0];+ if (spanProcessor === undefined || spanProcessor === "auto") throw new Error("Expected policy");+ spanProcessor.onEnd(+ testSpan({+ "agent.channel.audience": "private",+ "ai.prompt.messages": "private input",+ }),+ );++ expect(visibleAttributes).toEqual({ "agent.channel.audience": "private" });+ });- it("uses Vercel's automatic processor when all content is enabled", () => {- const integration = agentRunsIntegration({ recordInputs: true, recordOutputs: true });+ it("applies deprecated content switches before the configured export policy", () => {+ let visibleAttributes: Readonly<Record<string, unknown>> | undefined;+ const integration = managedOtelIntegration({+ exportPolicy: {+ span: ({ attributes }) => {+ visibleAttributes = attributes;+ return true;+ },+ },+ recordInputs: false,+ spanProcessors: [processor()],+ });++ const spanProcessor = integration.spanProcessors[0];+ if (spanProcessor === undefined || spanProcessor === "auto") throw new Error("Expected policy");+ spanProcessor.onEnd(testSpan({ "ai.prompt.messages": "private input" }));- expect(integration.content).toStrictEqual({ recordInputs: true, recordOutputs: true });- expect(integration.spanProcessors).toStrictEqual(["auto"]);+ expect(visibleAttributes).toEqual({});});});@@ -109,11 +170,9 @@ describe("collectOtelPipeline", () => {const [first, second, third] = [processor(), processor(), processor()];const collected = collectOtelPipeline([otelIntegration({- recordInputs: true,- recordOutputs: true,spanProcessors: [first, second],}),- otelIntegration({ recordInputs: true, recordOutputs: true, spanProcessors: [third] }),+ otelIntegration({ spanProcessors: [third] }),otel(),]);@@ -127,8 +186,8 @@ describe("collectOtelPipeline", () => {expect(collected.declared).toBe(true);expect(collected.settings).toStrictEqual({functionId: undefined,- recordInputs: false,- recordOutputs: false,+ recordInputs: true,+ recordOutputs: true,traceChannelRequests: false,});});@@ -151,32 +210,17 @@ describe("collectOtelPipeline", () => {});expect(collected.settings).toStrictEqual({functionId: "weather",- // Nothing declared a destination, so nothing asked for content.+ // Nothing declared a destination, so nothing consumes content.recordInputs: false,recordOutputs: false,traceChannelRequests: true,});});- // Content governs what is written onto the span, which is upstream of every- // destination — so one that wants it is enough, and the ones that declined- // drop it on their own way out.- it("takes content capture as the union across destinations", () => {- const collected = collectOtelPipeline([- otelIntegration({ recordInputs: false, recordOutputs: false }),- otelIntegration({ recordInputs: false, recordOutputs: true }),- ]);-- expect(collected.settings).toMatchObject({ recordInputs: false, recordOutputs: true });- });-- it("writes nothing when every destination declined", () => {- const collected = collectOtelPipeline([- otelIntegration({ recordInputs: false, recordOutputs: false }),- otelIntegration({ recordInputs: false, recordOutputs: false }),- ]);+ it("captures complete spans whenever a destination is declared", () => {+ const collected = collectOtelPipeline([otelIntegration()]);- expect(collected.settings).toMatchObject({ recordInputs: false, recordOutputs: false });+ expect(collected.settings).toMatchObject({ recordInputs: true, recordOutputs: true });});// A process has one tracer provider, so letting the first declaration windiff --git a/packages/eve/src/tracing/otel-declaration.ts b/packages/eve/src/tracing/otel-declaration.tsindex b14e557a2..e14ff8b22 100644--- a/packages/eve/src/tracing/otel-declaration.ts+++ b/packages/eve/src/tracing/otel-declaration.ts@@ -13,6 +13,26 @@ import { batchSpanProcessor } from "#tracing/batch-span-processor.js";import type { ResolvedContentOptions } from "#tracing/content-attributes.js";import { contentFilteringProcessor } from "#tracing/content-span-processor.js";import { vercelRuntimeSpanProcessor } from "#tracing/vercel-runtime-span-exporter.js";+import type { ChannelAudience } from "#shared/channel-audience.js";+import {+ composeSpanExportPolicies,+ redactSpanInputs,+ redactSpanOutputs,+ type SpanExportPolicy,+} from "#tracing/span-export-policy.js";++export type {+ SpanAttributeDecision,+ SpanExportAttributeValue,+ SpanExportContext,+ SpanExportPolicy,+ SpanExportPredicate,+} from "#tracing/span-export-policy.js";+export {+ composeSpanExportPolicies,+ redactSpanInputs,+ redactSpanOutputs,+} from "#tracing/span-export-policy.js";/*** The process-wide OpenTelemetry settings, declared by `otel()`.@@ -39,6 +59,11 @@ export interface OtelOptions {* outgoing HTTP spans. Defaults to `false`.*/readonly traceChannelRequests?: boolean;+ /**+ * Process-wide head gate for an agent session trace. Defaults to retaining+ * only public conversations. A thrown error rejects the trace.+ */+ readonly tracePolicy?: TraceCapturePolicy;/*** Resource attributes merged into eve's own, which already carry the* service name.@@ -64,23 +89,31 @@ export interface OtelOptions {readonly instrumentations?: readonly unknown[];}-/**- * What one destination records of the conversation itself.- *- * Declining is per destination, not per process: content is written onto the- * span if any destination wants it, and one that declined never exports it. So- * an agent whose every destination declines still never materializes a prompt —- * the union of nothing is nothing — but a local spool and a hosted backend no- * longer have to agree.- */+export interface ManagedTraceOptions {+ /** Destination policy applied before spans are exported. */+ readonly exportPolicy?: SpanExportPolicy;+ /** @deprecated Use `exportPolicy: redactSpanInputs()` instead. */+ readonly recordInputs?: boolean;+ /** @deprecated Use `exportPolicy: redactSpanOutputs()` instead. */+ readonly recordOutputs?: boolean;+}++/** @deprecated Compose `redactSpanInputs()` and `redactSpanOutputs()` into an export policy. */export interface ContentOptions {- /** Record model prompts and tool call inputs. Defaults to `false`. */readonly recordInputs?: boolean;- /** Record model responses and tool call outputs. Defaults to `false`. */readonly recordOutputs?: boolean;}-/** Where one `otelIntegration()` sends spans, and what it records. */+export interface TraceCaptureContext {+ readonly agentName?: string;+ readonly audience: ChannelAudience;+ readonly rootSessionId: string;+ readonly sessionId: string;+}++export type TraceCapturePolicy = (trace: TraceCaptureContext) => boolean;++/** Where one `otelIntegration()` sends spans. */export interface OtelIntegrationOptions extends ContentOptions {/** Merged into the pipeline in declaration order. */readonly spanProcessors?: readonly SpanProcessor[];@@ -114,7 +147,7 @@ export interface OtelDeclaration extends InstrumentationProvider {/** One declared destination. A process may have as many as it has files. */export interface OtelIntegration extends InstrumentationProvider {readonly [OTEL_INTEGRATION]: true;- /** Resolved from `ContentOptions`, so the union does not re-apply defaults. */+ /** @deprecated Content is captured upstream and redacted by destination policies. */readonly content: ResolvedContentOptions;readonly runtimeContext?: (input: InstrumentationRuntimeContextInput) => JsonObject | undefined;readonly spanProcessors: readonly SpanProcessorOrName[];@@ -138,15 +171,24 @@ export function otel(options: OtelOptions = {}): OtelDeclaration {* the one-line form of a hosted backend enough. Pass `spanProcessors` instead* when the destination needs its own batching, sampling, or filtering.*- * Declining content wraps every processor here, an author's included: they are- * this destination, and the point of declining is that nothing under it sees- * what was said.+ * The export policy wraps every processor here, an author's included: they are+ * this destination, and nothing beneath the policy sees what it removes.*/export function otelIntegration(options: OtelIntegrationOptions = {}): OtelIntegration {- const content: ResolvedContentOptions = {- recordInputs: options.recordInputs === true,- recordOutputs: options.recordOutputs === true,- };+ return createOtelIntegration(options);+}++/** @internal Local and Agent Runs destination declaration. */+export function managedOtelIntegration(+ options: OtelIntegrationOptions & ManagedTraceOptions = {},+): OtelIntegration {+ return createOtelIntegration(options, options.exportPolicy);+}++function createOtelIntegration(+ options: OtelIntegrationOptions,+ exportPolicy?: SpanExportPolicy,+): OtelIntegration {const declared = options.spanProcessors ?? [];const spanProcessors =options.traceExporter === undefined@@ -156,36 +198,55 @@ export function otelIntegration(options: OtelIntegrationOptions = {}): OtelIntegreturn {[OTEL_INTEGRATION]: true,[PROVIDER]: true,- content,+ content: resolveContentOptions(options),runtimeContext: options.runtimeContext,- spanProcessors:- content.recordInputs && content.recordOutputs- ? spanProcessors- : spanProcessors.map((processor) => contentFilteringProcessor(processor, content)),+ spanProcessors: spanProcessors.map((processor) =>+ withExportPolicies(processor, legacyContentRedactionPolicy(options), exportPolicy),+ ),};}/** Vercel Agent Runs through the production request-context transport. @internal */-export function agentRunsIntegration(options: ContentOptions = {}): OtelIntegration {- const content = resolveContentOptions(options);+export function agentRunsIntegration(options: ManagedTraceOptions = {}): OtelIntegration {return {[OTEL_INTEGRATION]: true,[PROVIDER]: true,- content,- spanProcessors:- content.recordInputs && content.recordOutputs- ? ["auto"]- : [contentFilteringProcessor(vercelRuntimeSpanProcessor(), content)],+ content: resolveContentOptions(options),+ spanProcessors: [+ withExportPolicies(+ vercelRuntimeSpanProcessor(),+ legacyContentRedactionPolicy(options),+ options.exportPolicy,+ ),+ ],};}+function legacyContentRedactionPolicy(options: ContentOptions): SpanExportPolicy | undefined {+ const policies: SpanExportPolicy[] = [];+ if (options.recordInputs === false) policies.push(redactSpanInputs());+ if (options.recordOutputs === false) policies.push(redactSpanOutputs());+ return policies.length === 0 ? undefined : composeSpanExportPolicies(...policies);+}+export function resolveContentOptions(options: ContentOptions): ResolvedContentOptions {return {- recordInputs: options.recordInputs === true,- recordOutputs: options.recordOutputs === true,+ recordInputs: options.recordInputs !== false,+ recordOutputs: options.recordOutputs !== false,};}+function withExportPolicies(+ downstream: SpanProcessor,+ ...policies: readonly (SpanExportPolicy | undefined)[]+): SpanProcessor {+ let processor = downstream;+ for (const policy of policies.toReversed()) {+ processor = contentFilteringProcessor(processor, policy);+ }+ return processor;+}+export function isOtelDeclaration(value: unknown): value is OtelDeclaration {return (typeof value === "object" &&@@ -215,11 +276,8 @@ export interface OtelPipeline {export interface OtelHarnessSettings {readonly functionId?: string;readonly traceChannelRequests: boolean;- /**- * What to write onto a span at all, as opposed to what any one destination- * exports. `agent/instrumentation.ts` sets this directly; a provider- * directory arrives at it as the union of its destinations.- */+ readonly tracePolicy?: TraceCapturePolicy;+ /** Legacy `defineInstrumentation()` capture settings. Provider destinations capture fully. */readonly recordInputs?: boolean;readonly recordOutputs?: boolean;}@@ -249,10 +307,6 @@ export interface CollectedOtel {* happened to visit first. With one declaration per file that collision needs* two files both exporting `otel()`, which is the only way to reach it.*- * Content capture is the union of what the destinations asked for, because it- * governs what is written rather than what is exported. Each destination's own- * processors already drop what it declined.- ** @internal*/export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {@@ -260,14 +314,12 @@ export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {const runtimeContextResolvers: RuntimeContextResolver[] = [];let declaration: OtelDeclaration | undefined;let declared = false;- let recordInputs = false;- let recordOutputs = false;+ let capturesContent = false;for (const value of values) {if (isOtelIntegration(value)) {declared = true;- recordInputs ||= value.content.recordInputs;- recordOutputs ||= value.content.recordOutputs;+ capturesContent = true;spanProcessors.push(...value.spanProcessors);if (value.runtimeContext !== undefined) {runtimeContextResolvers.push(value.runtimeContext);@@ -285,6 +337,15 @@ export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {}const options = declaration?.options ?? {};+ const settings: OtelHarnessSettings = {+ functionId: options.functionId,+ recordInputs: capturesContent,+ recordOutputs: capturesContent,+ traceChannelRequests: options.traceChannelRequests === true,+ };+ if (options.tracePolicy !== undefined) {+ Object.assign(settings, { tracePolicy: options.tracePolicy });+ }return {declared,pipeline: {@@ -295,11 +356,6 @@ export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {spanProcessors,},runtimeContextResolvers,- settings: {- functionId: options.functionId,- recordInputs,- recordOutputs,- traceChannelRequests: options.traceChannelRequests === true,- },+ settings,};}diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.tsnew file mode 100644index 000000000..ccebfd272--- /dev/null+++ b/packages/eve/src/tracing/sampled-trace.ts@@ -0,0 +1,5 @@+import { TraceFlags, type SpanContext } from "#compiled/@opentelemetry/api/index.js";++export function isSampledTrace(context: Pick<SpanContext, "traceFlags">): boolean {+ return (context.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;+}diff --git a/packages/eve/src/tracing/span-export-policy.ts b/packages/eve/src/tracing/span-export-policy.tsnew file mode 100644index 000000000..116008179--- /dev/null+++ b/packages/eve/src/tracing/span-export-policy.ts@@ -0,0 +1,94 @@+import type { ChannelAudience } from "#shared/channel-audience.js";++export interface SpanExportContext {+ readonly attributes: Readonly<Record<string, unknown>>;+ readonly audience: ChannelAudience;+ readonly name: string;+ readonly spanId: string;+ readonly traceId: string;+}++export type SpanExportPredicate = (span: SpanExportContext) => boolean;++export type SpanExportAttributeValue =+ | string+ | number+ | boolean+ | readonly string[]+ | readonly number[]+ | readonly boolean[];++export type SpanAttributeDecision =+ | { readonly action: "keep" }+ | { readonly action: "drop" }+ | { readonly action: "replace"; readonly value: SpanExportAttributeValue };++export interface SpanExportPolicy {+ /** Return false to block one span without blocking its trace. */+ readonly span?: SpanExportPredicate;+ /** Drop or replace individual span attributes after content filtering. */+ readonly attribute?: (input: {+ readonly key: string;+ readonly span: SpanExportContext;+ readonly value: unknown;+ }) => SpanAttributeDecision;+}++interface ContentRedaction {+ readonly inputs: readonly SpanExportPredicate[];+ readonly outputs: readonly SpanExportPredicate[];+}++const contentRedactions = new WeakMap<SpanExportPolicy, ContentRedaction>();+const composedPolicies = new WeakMap<SpanExportPolicy, readonly SpanExportPolicy[]>();++/** Redact input content from every matching span. */+export function redactSpanInputs(when: SpanExportPredicate = () => true): SpanExportPolicy {+ const policy = {};+ contentRedactions.set(policy, { inputs: [when], outputs: [] });+ return policy;+}++/** Redact output content, exception details, and status messages from every matching span. */+export function redactSpanOutputs(when: SpanExportPredicate = () => true): SpanExportPolicy {+ const policy = {};+ contentRedactions.set(policy, { inputs: [], outputs: [when] });+ return policy;+}++/** Compose policies in declaration order. A drop or redaction from any policy is final. */+export function composeSpanExportPolicies(+ ...policies: readonly SpanExportPolicy[]+): SpanExportPolicy {+ if (policies.length === 0) return {};+ if (policies.length === 1) return policies[0]!;+ const composed = {};+ composedPolicies.set(composed, policies.flatMap(spanExportPolicyStages));+ return composed;+}++/** @internal */+export function spanExportPolicyStages(policy: SpanExportPolicy): readonly SpanExportPolicy[] {+ return composedPolicies.get(policy) ?? [policy];+}++/** @internal */+export function contentRedactionForSpan(+ policy: SpanExportPolicy | undefined,+ span: SpanExportContext,+): { readonly redactInputs: boolean; readonly redactOutputs: boolean } {+ const redaction = policy === undefined ? undefined : contentRedactions.get(policy);+ return {+ redactInputs: redaction?.inputs.some((when) => matches(when, span)) ?? false,+ redactOutputs: redaction?.outputs.some((when) => matches(when, span)) ?? false,+ };+}++function matches(predicate: SpanExportPredicate, span: SpanExportContext): boolean {+ try {+ return predicate(span);+ } catch {+ // Redaction predicates fail closed.+ return true;+ }+}diff --git a/packages/eve/src/tracing/suppress-tracing.ts b/packages/eve/src/tracing/suppress-tracing.tsnew file mode 100644index 000000000..b21a13abb--- /dev/null+++ b/packages/eve/src/tracing/suppress-tracing.ts@@ -0,0 +1,8 @@+import { createContextKey, type Context } from "#compiled/@opentelemetry/api/index.js";++// Standard OpenTelemetry SDK suppression key, kept behind an eve-owned wrapper.+const SUPPRESS_TRACING_KEY = createContextKey("OpenTelemetry SDK Context Key SUPPRESS_TRACING");++export function suppressTracing(context: Context): Context {+ return context.setValue(SUPPRESS_TRACING_KEY, true);+}