Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add provider trace policies (#2721)

Chad Hietalae2e055cdd278
diff --git a/.changeset/add-provider-trace-policy.md b/.changeset/add-provider-trace-policy.md
new file mode 100644
index 000000000..34e4b1993
--- /dev/null
+++ b/.changeset/add-provider-trace-policy.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Instrumentation providers can now define a `tracePolicy` to independently control event admission and input or output content capture. The deprecated `capture` setting continues to work through an equivalent policy mapping, while providers that omit both settings capture content only for public audiences.
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index cab175c69..966fc8118 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -85,7 +85,9 @@ export const TurnTaskDeliveryKey = new ContextKey<"none" | "initiating" | "pendi
export const TurnTaskStateKey = new ContextKey<string>("eve.turnTaskState");
export interface ActiveChannelDelivery {
readonly agentName?: string;
+ readonly channelType?: string;
readonly delivery: InstrumentationChannelDeliveryRef;
+ readonly policyAgentName?: string;
readonly rootSessionId: string;
readonly sequence: number;
readonly sessionId: string;
diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.ts b/packages/eve/src/execution/settle-cancelled-turn-step.ts
index 54b9079ab..b59417445 100644
--- a/packages/eve/src/execution/settle-cancelled-turn-step.ts
+++ b/packages/eve/src/execution/settle-cancelled-turn-step.ts
@@ -73,7 +73,7 @@ export async function settleCancelledTurnStep(input: {
turnAgent: effectiveAgent.turnAgent,
});
const instrumentation = bindSessionInstrumentation({
- agentName: effectiveAgent.turnAgent.id,
+ agentName: bundle.graph.root.agent?.config?.name,
ctx,
rootSessionId: session.rootSessionId ?? session.sessionId,
sessionId: session.sessionId,
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 60e8be438..96469187e 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -11184,7 +11184,11 @@ describe("createToolLoopHarness", () => {
await contextStorage.run(ctx, () => runStep(createTestSession(), { message: "private" }));
expect(attemptCompleted).toHaveBeenCalledOnce();
- expect(mockCreateAiSdkHookBridge.mock.calls[0]?.[1]).toBe(hooks);
+ expect(mockCreateAiSdkHookBridge.mock.calls[0]?.[1]).toMatchObject({
+ capturesContent: true,
+ capturesInputs: true,
+ capturesOutputs: true,
+ });
const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
telemetry?: { integrations?: unknown[] };
};
@@ -11215,7 +11219,11 @@ describe("createToolLoopHarness", () => {
await runStep(createTestSession(), { message: "private" });
- expect(mockCreateAiSdkHookBridge.mock.calls[0]?.[1]).toBe(hooks);
+ expect(mockCreateAiSdkHookBridge.mock.calls[0]?.[1]).toMatchObject({
+ capturesContent: true,
+ capturesInputs: true,
+ capturesOutputs: true,
+ });
const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
telemetry?: { recordInputs?: boolean; recordOutputs?: boolean };
};
@@ -11447,7 +11455,11 @@ describe("createToolLoopHarness", () => {
stepIndex: 0,
turnId: "turn_0",
}),
- hooks,
+ expect.objectContaining({
+ capturesContent: false,
+ capturesInputs: false,
+ capturesOutputs: false,
+ }),
runInContext,
{},
);
diff --git a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts
index eed73210c..2e608974e 100644
--- a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts
+++ b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts
@@ -24,6 +24,26 @@ const scope: InstrumentationAttemptScope = {
};
describe("createAiSdkHookBridge", () => {
+ it("withholds content when a bridge is not bound to a trace", async () => {
+ const started = vi.fn();
+ const hooks = createInstrumentationHooks([
+ { events: { "model.call.started": started }, name: "default-policy" },
+ ]);
+ const bridge = createAiSdkHookBridge({ ...scope, channelAudience: "public" }, hooks);
+
+ await Reflect.apply(bridge.onLanguageModelCallStart!, bridge, [
+ {
+ callId: "call-1",
+ instructions: "private instructions",
+ messages: [{ content: "private message", role: "user" }],
+ modelId: "model",
+ provider: "test",
+ },
+ ]);
+
+ expect(started.mock.calls[0]?.[0].input).toBeUndefined();
+ });
+
it("publishes normalized model lifecycle to every provider", async () => {
const calls: string[] = [];
const provider = (name: string): InstrumentationProviderDefinition => {
diff --git a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts
index 6e1c9d506..dc07bcd97 100644
--- a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts
+++ b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts
@@ -24,8 +24,8 @@ import { structuralProviderMetadata } from "#instrumentation/content.js";
type TelemetryEvent<TKey extends keyof Telemetry> = Parameters<NonNullable<Telemetry[TKey]>>[0];
interface AttemptState {
- /** False when no provider asked for content, so none is projected at all. */
- readonly capturesContent: boolean;
+ readonly capturesInputs: boolean;
+ readonly capturesOutputs: boolean;
readonly modelKeys: Map<string, string>;
readonly runtimeContext?: Readonly<Record<string, unknown>>;
readonly scope: InstrumentationAttemptScope;
@@ -43,7 +43,8 @@ export function createAiSdkHookBridge(
runtimeContext?: Readonly<Record<string, unknown>>,
): Telemetry {
const state: AttemptState = {
- capturesContent: hooks.capturesContent,
+ capturesInputs: hooks.capturesInputs ?? hooks.capturesContent,
+ capturesOutputs: hooks.capturesOutputs ?? hooks.capturesContent,
modelKeys: new Map(),
runtimeContext:
runtimeContext !== undefined && Object.keys(runtimeContext).length > 0
@@ -90,7 +91,7 @@ export function createAiSdkHookBridge(
// that the per-call telemetry events don't. Publish it for providers
// that know what to do with it; skip when there is none.
if (event.providerMetadata === undefined) return;
- const providerMetadata = state.capturesContent
+ const providerMetadata = state.capturesOutputs
? event.providerMetadata
: structuralProviderMetadata(event.providerMetadata);
await hooks.publish(
@@ -174,7 +175,7 @@ function toModelCallStarted(
): InstrumentationModelCallStartedEvent {
return Object.freeze({
idempotencyKey,
- input: state.capturesContent
+ input: state.capturesInputs
? Object.freeze({
instructions: source.instructions,
messages: Object.freeze([...source.messages]),
@@ -193,7 +194,7 @@ function toModelCallCompleted(
source: TelemetryEvent<"onLanguageModelCallEnd">,
): InstrumentationModelCallCompletedEvent {
return Object.freeze({
- content: state.capturesContent ? toContentParts(source.content) : undefined,
+ content: state.capturesOutputs ? toContentParts(source.content) : undefined,
finishReason: source.finishReason,
idempotencyKey,
scope: state.scope,
@@ -271,7 +272,7 @@ function toToolCallStarted(
return Object.freeze({
callId: source.toolCall.toolCallId,
idempotencyKey,
- input: state.capturesContent ? source.toolCall.input : undefined,
+ input: state.capturesInputs ? source.toolCall.input : undefined,
scope: state.scope,
toolName: source.toolCall.toolName,
type: "tool.call.started",
@@ -285,7 +286,7 @@ function toToolCallCompleted(
): InstrumentationToolCallCompletedEvent {
return Object.freeze({
idempotencyKey,
- output: toToolOutput(source.toolOutput, state.capturesContent),
+ output: toToolOutput(source.toolOutput, state.capturesOutputs),
scope: state.scope,
type: "tool.call.completed",
});
diff --git a/packages/eve/src/instrumentation/channel-delivery.test.ts b/packages/eve/src/instrumentation/channel-delivery.test.ts
index 2454f2af0..165b6f9cc 100644
--- a/packages/eve/src/instrumentation/channel-delivery.test.ts
+++ b/packages/eve/src/instrumentation/channel-delivery.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
import { ChannelInstrumentationKey, ParentTraceContextKey } from "#context/keys.js";
@@ -11,7 +11,11 @@ import {
type InstrumentationRuntime,
} from "#instrumentation/runtime.js";
-function bindHooks(hooks: InstrumentationRuntime["hooks"], ctx: ContextContainer) {
+function bindHooks(
+ hooks: InstrumentationRuntime["hooks"],
+ ctx: ContextContainer,
+ agentName?: string,
+) {
return bindInstrumentationRuntime(
{
forceFlush: async () => undefined,
@@ -21,7 +25,7 @@ function bindHooks(hooks: InstrumentationRuntime["hooks"], ctx: ContextContainer
shutdown: async () => undefined,
},
ctx,
- { rootSessionId: "session-1", sessionId: "session-1" },
+ { agentName, rootSessionId: "session-1", sessionId: "session-1" },
);
}
@@ -31,7 +35,7 @@ describe("channel delivery instrumentation", () => {
const metadata: InstrumentationEvent[] = [];
const hooks = createInstrumentationHooks([
{
- capture: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
events: {
"channel.delivery.started": (event) => {
content.push(event);
@@ -40,6 +44,7 @@ describe("channel delivery instrumentation", () => {
name: "content",
},
{
+ tracePolicy: () => ({ emit: true, recordInputs: false, recordOutputs: false }),
events: {
"channel.delivery.started": (event) => {
metadata.push(event);
@@ -100,7 +105,7 @@ describe("channel delivery instrumentation", () => {
const events: InstrumentationEvent[] = [];
const hooks = createInstrumentationHooks([
{
- capture: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
events: {
"channel.delivery.started": (event) => {
events.push(event);
@@ -139,4 +144,64 @@ describe("channel delivery instrumentation", () => {
expect(events[0]).toMatchObject({ input: { message: "secret" } });
});
+
+ it("uses delivery-start context when a bound turn publishes the terminal", async () => {
+ const completed = vi.fn();
+ const tracePolicy = vi.fn(({ audience }) => audience === "public");
+ const hooks = createInstrumentationHooks([
+ {
+ events: { "channel.delivery.completed": completed },
+ name: "public-only",
+ tracePolicy,
+ },
+ ]);
+ const ctx = new ContextContainer();
+ ctx.set(ChannelInstrumentationKey, {
+ channelType: "slack",
+ kind: "channel:slack",
+ metadata: { audience: "public" },
+ });
+ const instrumentation = bindHooks(hooks, ctx, "Weather Display Name");
+
+ await contextStorage.run(ctx, async () => {
+ await instrumentation?.instrumentChannelDelivery({
+ agentName: "weather",
+ ctx,
+ delivery: {
+ deliveryMetadata: [
+ {
+ channelKind: "channel:slack",
+ channelName: "slack",
+ deliveryId: "delivery-1",
+ payloadIndex: 0,
+ },
+ ],
+ kind: "deliver",
+ payloads: [{ message: "hello" }],
+ },
+ rootSessionId: "session-1",
+ sequence: 0,
+ sessionId: "session-1",
+ turnId: "turn_0",
+ });
+ ctx.set(ChannelInstrumentationKey, {
+ channelType: "slack",
+ kind: "channel:slack",
+ metadata: { audience: "private" },
+ });
+ await instrumentation?.instrumentChannelDelivery({
+ ctx,
+ includeTurn: true,
+ outcome: "completed",
+ });
+ });
+
+ expect(completed).toHaveBeenCalledOnce();
+ expect(completed.mock.calls[0]?.[0].agentName).toBe("weather");
+ expect(tracePolicy.mock.calls[0]?.[0]).toEqual({
+ agentName: "Weather Display Name",
+ audience: "public",
+ channelType: "slack",
+ });
+ });
});
diff --git a/packages/eve/src/instrumentation/channel-delivery.ts b/packages/eve/src/instrumentation/channel-delivery.ts
index ea02180de..b38214116 100644
--- a/packages/eve/src/instrumentation/channel-delivery.ts
+++ b/packages/eve/src/instrumentation/channel-delivery.ts
@@ -20,6 +20,7 @@ export interface ChannelDeliveryStartInstrumentation {
readonly ctx: AlsContext;
readonly delivery: DeliverHookPayload;
readonly hooks: InstrumentationHooks | undefined;
+ readonly policyAgentName?: string;
readonly rootSessionId: string;
readonly sequence: number;
readonly sessionId: string;
@@ -44,7 +45,13 @@ export async function instrumentChannelDelivery(
const type =
`channel.delivery.${input.outcome}` as InstrumentationChannelDeliveryTerminalEvent["type"];
for (const item of active) {
- await input.hooks.publish({
+ const hooks =
+ input.hooks.forTrace?.({
+ agentName: item.policyAgentName,
+ audience: normalizeChannelAudience(item.delivery.channelAudience),
+ channelType: item.channelType,
+ }) ?? input.hooks;
+ await hooks.publish({
agentName: item.agentName,
delivery: item.delivery,
error: input.error,
@@ -65,10 +72,14 @@ 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,
- );
- const hooks = input.hooks;
+ const channel = input.ctx.get(ChannelInstrumentationKey);
+ const channelAudience = normalizeChannelAudience(channel?.metadata.audience);
+ const hooks =
+ input.hooks.forTrace?.({
+ agentName: input.policyAgentName,
+ audience: channelAudience,
+ channelType: channel?.channelType,
+ }) ?? input.hooks;
for (const metadata of input.delivery.deliveryMetadata) {
const payload = input.delivery.payloads[metadata.payloadIndex];
const delivery = {
@@ -79,11 +90,14 @@ export async function instrumentChannelDelivery(
requestId: metadata.requestId,
requestTraceContext: metadata.requestTraceContext,
};
+ const capturesInputs = hooks.capturesInputs ?? hooks.capturesContent;
const deliveryInput =
- !hooks?.capturesContent || payload === undefined ? undefined : projectDeliveryInput(payload);
+ !capturesInputs || payload === undefined ? undefined : projectDeliveryInput(payload);
const item: ActiveChannelDelivery = {
agentName: input.agentName,
+ channelType: channel?.channelType,
delivery,
+ policyAgentName: input.policyAgentName,
rootSessionId: input.rootSessionId,
sequence: input.sequence,
sessionId: input.sessionId,
diff --git a/packages/eve/src/instrumentation/dispatch.ts b/packages/eve/src/instrumentation/dispatch.ts
index ac558ba86..47f777550 100644
--- a/packages/eve/src/instrumentation/dispatch.ts
+++ b/packages/eve/src/instrumentation/dispatch.ts
@@ -8,8 +8,13 @@ import {
takeInstrumentationActionScopes,
type InstrumentationStateOwner,
} from "#instrumentation/state.js";
-import { withoutInstrumentationContent } from "#instrumentation/content.js";
+import {
+ withInstrumentationDecision,
+ withoutInstrumentationContent,
+} from "#instrumentation/content.js";
import { createLogger, formatError } from "#internal/logging.js";
+import { legacyCaptureTracePolicy, resolveTracePolicy } from "#shared/trace-policy.js";
+import type { TraceCaptureContext } from "#shared/trace-policy.js";
import type {
CreateInstrumentationHooksOptions,
@@ -35,84 +40,157 @@ export function createInstrumentationDispatcher(
): InstrumentationHooks {
const handlerTimeoutMs = options.handlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
const groups = normalizeDispatchGroups(input);
- const snapshots = new WeakMap<object, unknown>();
const providers = [...groups.serialBefore, ...groups.parallel, ...groups.serialAfter];
- const capturesContent = providers.some((provider) => provider.capture === "content");
+ const warnedPolicyFailures = new Set<InstrumentationProviderDefinition>();
+
+ const forTrace = (trace: TraceCaptureContext): InstrumentationHooks => {
+ const snapshots = new WeakMap<object, unknown>();
+ const decisions = new Map(
+ providers.map((provider) => [
+ provider,
+ resolveTracePolicy(
+ provider.tracePolicy ?? legacyCaptureTracePolicy(provider.capture),
+ trace,
+ (error) => {
+ if (warnedPolicyFailures.has(provider)) return;
+ warnedPolicyFailures.add(provider);
+ log.warn("instrumentation provider trace policy failed", {
+ error: formatError(error),
+ provider: provider.name,
+ });
+ },
+ ),
+ ]),
+ );
+ const capturesInputs = [...decisions.values()].some(
+ (decision) => decision.action === "record" && decision.recordInputs,
+ );
+ const capturesOutputs = [...decisions.values()].some(
+ (decision) => decision.action === "record" && decision.recordOutputs,
+ );
+ const capturesContent = capturesInputs || capturesOutputs;
- const publish = async (event: InstrumentationEvent): Promise<void> => {
- const snapshot = snapshotInstrumentationEvent(event, snapshots);
- const cleanupSession =
- snapshot.type === "session.completed" || snapshot.type === "session.failed";
- const cleanupTurn = snapshot.type === "turn.cancelled" || snapshot.type === "turn.failed";
- if (cleanupSession || cleanupTurn) {
- const pendingActions = takeInstrumentationActionScopes(
- snapshot.sessionId,
- cleanupTurn ? snapshot.turnId : undefined,
+ const publish = async (event: InstrumentationEvent): Promise<void> => {
+ const snapshot = snapshotInstrumentationEvent(
+ withInstrumentationDecision(event, {
+ action: "record",
+ recordInputs: capturesInputs,
+ recordOutputs: capturesOutputs,
+ }),
+ snapshots,
+ event,
);
- const failure = terminalActionFailure(snapshot);
- for (const action of pendingActions) {
- await publish({
- ...failure,
- idempotencyKey: action.idempotencyKey,
- scope: action.scope,
- type: "action.failed",
- });
+ const cleanupSession =
+ snapshot.type === "session.completed" || snapshot.type === "session.failed";
+ const cleanupTurn = snapshot.type === "turn.cancelled" || snapshot.type === "turn.failed";
+ if (cleanupSession || cleanupTurn) {
+ const pendingActions = takeInstrumentationActionScopes(
+ snapshot.sessionId,
+ cleanupTurn ? snapshot.turnId : undefined,
+ );
+ const failure = terminalActionFailure(snapshot);
+ for (const action of pendingActions) {
+ await publish({
+ ...failure,
+ idempotencyKey: action.idempotencyKey,
+ scope: action.scope,
+ type: "action.failed",
+ });
+ }
}
- }
- let stripped: InstrumentationEvent | undefined;
- const visibleEvent = (provider: InstrumentationProviderDefinition): InstrumentationEvent => {
- if (provider.capture === "content") return snapshot;
- stripped ??= withoutInstrumentationContent(snapshot);
- return stripped;
- };
+ const projections = new Map<string, InstrumentationEvent>();
+ const visibleEvent = (provider: InstrumentationProviderDefinition): InstrumentationEvent => {
+ const decision = decisions.get(provider);
+ if (decision === undefined || decision.action === "drop") {
+ return withoutInstrumentationContent(snapshot);
+ }
+ if (decision.recordInputs && decision.recordOutputs) return snapshot;
+ const key = `${String(decision.recordInputs)}:${String(decision.recordOutputs)}`;
+ let projected = projections.get(key);
+ if (projected === undefined) {
+ projected = withInstrumentationDecision(snapshot, decision);
+ projections.set(key, projected);
+ }
+ return projected;
+ };
+ const admitted = (provider: InstrumentationProviderDefinition): boolean =>
+ decisions.get(provider)?.action === "record";
- try {
try {
- for (const provider of groups.serialBefore) {
- await dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
- visibleEvent(provider),
- );
- }
+ try {
+ for (const provider of groups.serialBefore) {
+ if (!admitted(provider)) continue;
+ await dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
+ visibleEvent(provider),
+ );
+ }
- if (groups.parallel.length === 1) {
- const provider = groups.parallel[0]!;
- await dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
- visibleEvent(provider),
- );
- } else if (groups.parallel.length > 1) {
- const results = await Promise.allSettled(
- groups.parallel.map((provider) =>
- dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
- visibleEvent(provider),
+ const parallel = groups.parallel.filter(admitted);
+ if (parallel.length === 1) {
+ const provider = parallel[0]!;
+ await dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
+ visibleEvent(provider),
+ );
+ } else if (parallel.length > 1) {
+ const results = await Promise.allSettled(
+ parallel.map((provider) =>
+ dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
+ visibleEvent(provider),
+ ),
),
- ),
- );
- const rejected = results.find(
- (result): result is PromiseRejectedResult => result.status === "rejected",
- );
- if (rejected !== undefined) throw rejected.reason;
+ );
+ const rejected = results.find(
+ (result): result is PromiseRejectedResult => result.status === "rejected",
+ );
+ if (rejected !== undefined) throw rejected.reason;
+ }
+ } finally {
+ for (const provider of groups.serialAfter) {
+ if (!admitted(provider)) continue;
+ await dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
+ visibleEvent(provider),
+ );
+ }
}
} finally {
- for (const provider of groups.serialAfter) {
- await dispatchToProvider(provider, snapshot, handlerTimeoutMs, () =>
- visibleEvent(provider),
- );
- }
+ releaseTerminalState(snapshot);
}
- } finally {
- releaseTerminalState(snapshot);
- }
+ };
+
+ return { capturesContent, capturesInputs, capturesOutputs, forTrace, publish };
};
- return { capturesContent, publish };
+ let unboundHooks: InstrumentationHooks | undefined;
+ let loggedUnboundPublish = false;
+ return {
+ capturesContent: providers.some(
+ (provider) => provider.tracePolicy === undefined && provider.capture === "content",
+ ),
+ forTrace,
+ async publish(event) {
+ if (!loggedUnboundPublish) {
+ loggedUnboundPublish = true;
+ log.debug("instrumentation event published without trace binding", {
+ eventType: event.type,
+ });
+ }
+ unboundHooks ??= forTrace({ audience: "unknown" });
+ await unboundHooks.publish(event);
+ },
+ };
}
function snapshotInstrumentationEvent(
event: InstrumentationEvent,
snapshots: WeakMap<object, unknown>,
+ source: InstrumentationEvent,
): InstrumentationEvent {
- return snapshotPlainValue(event, snapshots) as InstrumentationEvent;
+ const existing = snapshots.get(source);
+ if (existing !== undefined) return existing as InstrumentationEvent;
+ const snapshot = snapshotPlainValue(event, snapshots) as InstrumentationEvent;
+ snapshots.set(source, snapshot);
+ return snapshot;
}
function snapshotPlainValue(value: unknown, seen: WeakMap<object, unknown>): unknown {
diff --git a/packages/eve/src/instrumentation/lifecycle.test.ts b/packages/eve/src/instrumentation/lifecycle.test.ts
index 20b3e8523..2eacee6ca 100644
--- a/packages/eve/src/instrumentation/lifecycle.test.ts
+++ b/packages/eve/src/instrumentation/lifecycle.test.ts
@@ -12,6 +12,7 @@ import {
toolCallIdempotencyKey,
turnIdempotencyKey,
type InstrumentationAttemptScope,
+ type InstrumentationEvent,
type InstrumentationModelCallStartedEvent,
type InstrumentationProviderDefinition,
type InstrumentationToolCallCompletedEvent,
@@ -22,9 +23,9 @@ import {
rememberInstrumentationActionScope,
} from "#instrumentation/state.js";
-const { logWarn } = vi.hoisted(() => ({ logWarn: vi.fn() }));
+const { logDebug, logWarn } = vi.hoisted(() => ({ logDebug: vi.fn(), logWarn: vi.fn() }));
vi.mock("#internal/logging.js", () => ({
- createLogger: () => ({ warn: logWarn }),
+ createLogger: () => ({ debug: logDebug, warn: logWarn }),
formatError: (error: unknown) => error,
}));
@@ -821,31 +822,283 @@ describe("provider dispatch groups", () => {
});
});
-describe("capture", () => {
- it("reports content capture only when some provider asked for it", () => {
- expect(createInstrumentationHooks([{ name: "quiet" }]).capturesContent).toBe(false);
+describe("trace policies", () => {
+ it("defaults provider content to the audience-aware policy", () => {
+ const hooks = createInstrumentationHooks([{ name: "provider" }]);
+
+ expect(hooks.forTrace?.({ audience: "public" }).capturesContent).toBe(true);
+ expect(hooks.forTrace?.({ audience: "private" }).capturesContent).toBe(false);
+ });
+
+ it("passes trace context to each provider policy", () => {
+ const tracePolicy = vi.fn(() => ({
+ emit: true as const,
+ recordInputs: true,
+ recordOutputs: false,
+ }));
+ const hooks = createInstrumentationHooks([{ name: "provider", tracePolicy }]);
+ const trace = {
+ agentName: "weather",
+ audience: "private" as const,
+ channelType: "slack",
+ };
+
+ tracePolicy.mockClear();
+ expect(hooks.forTrace?.(trace).capturesContent).toBe(true);
+ expect(tracePolicy).toHaveBeenCalledExactlyOnceWith(trace);
+ });
+
+ it("evaluates unbound policies once with an unknown trace", async () => {
+ const tracePolicy = vi.fn(() => true);
+ const hooks = createInstrumentationHooks([{ name: "provider", tracePolicy }]);
+
+ await hooks.publish({
+ idempotencyKey: turnIdempotencyKey("session-1", "turn-1"),
+ rootSessionId: "session-1",
+ sequence: 0,
+ sessionId: "session-1",
+ turnId: "turn-1",
+ type: "turn.started",
+ });
+ await hooks.publish({
+ idempotencyKey: turnIdempotencyKey("session-1", "turn-1"),
+ sessionId: "session-1",
+ turnId: "turn-1",
+ type: "turn.completed",
+ });
+
+ expect(tracePolicy).toHaveBeenCalledExactlyOnceWith({
+ agentName: undefined,
+ audience: "unknown",
+ channelType: undefined,
+ });
+ });
+
+ it("lets an explicit provider policy authorize private content", async () => {
+ const observed = vi.fn();
+ const hooks = createInstrumentationHooks([
+ {
+ events: { "action.started": observed },
+ name: "private-audit",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: false }),
+ },
+ ]).forTrace!({ audience: "private" });
+
+ await hooks.publish({
+ callId: "call-1",
+ idempotencyKey: actionIdempotencyKey(scope.sessionId, scope.turnId, "call-1"),
+ input: { secret: "private" },
+ kind: "tool-call",
+ name: "weather",
+ scope,
+ type: "action.started",
+ });
+
+ expect(observed.mock.calls[0]?.[0].input).toEqual({ secret: "private" });
+ });
+
+ it("projects input and output content independently per provider", async () => {
+ const inputEvents: InstrumentationEvent[] = [];
+ const outputEvents: InstrumentationEvent[] = [];
+ const events = (target: InstrumentationEvent[]) => ({
+ "model.call.completed": (event: InstrumentationEvent) => void target.push(event),
+ "model.call.started": (event: InstrumentationEvent) => void target.push(event),
+ });
+ const hooks = createInstrumentationHooks([
+ {
+ events: events(inputEvents),
+ name: "inputs",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: false }),
+ },
+ {
+ events: events(outputEvents),
+ name: "outputs",
+ tracePolicy: () => ({ emit: true, recordInputs: false, recordOutputs: true }),
+ },
+ ]).forTrace!({ audience: "public" });
+
+ await hooks.publish({
+ idempotencyKey: "model-1",
+ input: { instructions: "private prompt", messages: [] },
+ model: { modelId: "test", provider: "test" },
+ scope,
+ type: "model.call.started",
+ });
+ await hooks.publish({
+ content: [{ text: "private answer", type: "text" }],
+ finishReason: "stop",
+ idempotencyKey: "model-1",
+ scope,
+ type: "model.call.completed",
+ usage: {},
+ });
+
+ expect(inputEvents).toMatchObject([
+ { input: { instructions: "private prompt" } },
+ { content: undefined },
+ ]);
+ expect(outputEvents).toMatchObject([
+ { input: undefined },
+ { content: [{ text: "private answer", type: "text" }] },
+ ]);
+ });
+
+ it("does not snapshot denied error content", async () => {
+ const observed = vi.fn();
+ const error = Object.defineProperty({}, "secret", {
+ enumerable: true,
+ get: () => {
+ throw new Error("error content was read");
+ },
+ });
+ const hooks = createInstrumentationHooks([
+ {
+ events: { "turn.failed": observed },
+ name: "inputs-only",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: false }),
+ },
+ ]).forTrace!({ audience: "public" });
+
+ await hooks.publish({
+ error,
+ idempotencyKey: turnIdempotencyKey("session-1", "turn-1"),
+ sessionId: "session-1",
+ turnId: "turn-1",
+ type: "turn.failed",
+ });
+
+ expect(observed.mock.calls[0]?.[0].error).toBeUndefined();
+ });
+
+ it("reports content capture only when an admitted provider requests it", () => {
expect(
- createInstrumentationHooks([{ capture: "metadata", name: "quiet" }, { name: "also-quiet" }])
- .capturesContent,
+ createInstrumentationHooks([
+ {
+ name: "unbound",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
+ },
+ ]).capturesContent,
).toBe(false);
expect(
- createInstrumentationHooks([{ name: "quiet" }, { capture: "content", name: "loud" }])
+ createInstrumentationHooks([{ capture: "content", name: "legacy" }]).capturesContent,
+ ).toBe(true);
+ expect(
+ createInstrumentationHooks([
+ {
+ capture: "content",
+ name: "explicit-policy",
+ tracePolicy: () => ({ emit: true, recordInputs: false, recordOutputs: false }),
+ },
+ ]).capturesContent,
+ ).toBe(false);
+ expect(
+ createInstrumentationHooks([{ name: "quiet" }]).forTrace!({ audience: "private" })
.capturesContent,
+ ).toBe(false);
+ expect(
+ createInstrumentationHooks([
+ {
+ name: "quiet",
+ tracePolicy: () => ({ emit: true, recordInputs: false, recordOutputs: false }),
+ },
+ {
+ name: "also-quiet",
+ tracePolicy: () => ({ emit: true, recordInputs: false, recordOutputs: false }),
+ },
+ ]).forTrace!({ audience: "public" }).capturesContent,
+ ).toBe(false);
+ expect(
+ createInstrumentationHooks([
+ { name: "quiet" },
+ {
+ name: "loud",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
+ },
+ ]).forTrace!({ audience: "public" }).capturesContent,
).toBe(true);
expect(
createInstrumentationHooks({
- parallel: [{ capture: "content", name: "loud" }],
- }).capturesContent,
+ parallel: [
+ {
+ name: "loud",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
+ },
+ ],
+ }).forTrace!({ audience: "public" }).capturesContent,
).toBe(true);
});
+ it("does not invoke a provider whose policy drops the trace", async () => {
+ const observed = vi.fn();
+ const hooks = createInstrumentationHooks([
+ {
+ events: { "turn.started": observed },
+ name: "dropped",
+ tracePolicy: () => false,
+ },
+ ]).forTrace!({ audience: "public" });
+
+ await hooks.publish({
+ idempotencyKey: turnIdempotencyKey("session-1", "turn-1"),
+ rootSessionId: "session-1",
+ sequence: 0,
+ sessionId: "session-1",
+ turnId: "turn-1",
+ type: "turn.started",
+ });
+
+ expect(observed).not.toHaveBeenCalled();
+ });
+
+ it("isolates a throwing policy to its provider", async () => {
+ const rejected = vi.fn();
+ const observed = vi.fn();
+ const unboundHooks = createInstrumentationHooks([
+ {
+ events: { "turn.started": rejected },
+ name: "rejected",
+ tracePolicy: () => {
+ throw new Error("policy failed");
+ },
+ },
+ {
+ events: { "turn.started": observed },
+ name: "observed",
+ tracePolicy: () => ({ emit: true, recordInputs: false, recordOutputs: false }),
+ },
+ ]);
+ const hooks = unboundHooks.forTrace!({ audience: "public" });
+ unboundHooks.forTrace!({ audience: "private" });
+
+ await hooks.publish({
+ idempotencyKey: turnIdempotencyKey("session-1", "turn-1"),
+ rootSessionId: "session-1",
+ sequence: 0,
+ sessionId: "session-1",
+ turnId: "turn-1",
+ type: "turn.started",
+ });
+
+ expect(rejected).not.toHaveBeenCalled();
+ expect(observed).toHaveBeenCalledOnce();
+ expect(logWarn).toHaveBeenCalledWith(
+ "instrumentation provider trace policy failed",
+ expect.objectContaining({ provider: "rejected" }),
+ );
+ expect(
+ logWarn.mock.calls.filter(
+ ([message]) => message === "instrumentation provider trace policy failed",
+ ),
+ ).toHaveLength(1);
+ });
+
it("allows only structural provider metadata by default", async () => {
const metadataOnly = vi.fn();
const wantsContent = vi.fn();
const hooks = createInstrumentationHooks([
{ events: { "step.attempt.metadata": metadataOnly }, name: "metadata" },
{
- capture: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
events: { "step.attempt.metadata": wantsContent },
name: "content",
},
@@ -883,7 +1136,11 @@ describe("capture", () => {
const wantsContent = vi.fn();
const hooks = createInstrumentationHooks([
{ events: { "action.failed": metadataOnly }, name: "metadata" },
- { capture: "content", events: { "action.failed": wantsContent }, name: "content" },
+ {
+ events: { "action.failed": wantsContent },
+ name: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
+ },
]);
const error = { output: "private tool output", requestBody: "private request" };
const actionScope = { ...scope };
@@ -944,7 +1201,7 @@ describe("capture", () => {
name: "metadata",
},
{
- capture: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
events: {
"input.requested": (event) => void contentEvents.push(event),
"input.resolved": (event) => void contentEvents.push(event),
@@ -998,7 +1255,7 @@ describe("capture", () => {
{ events: { "tool.call.completed": mutator }, name: "first" },
{ events: { "tool.call.completed": observed }, name: "second" },
{
- capture: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
events: { "tool.call.completed": content },
name: "content",
},
diff --git a/packages/eve/src/instrumentation/lifecycle.ts b/packages/eve/src/instrumentation/lifecycle.ts
index 2bfe5c73f..926396398 100644
--- a/packages/eve/src/instrumentation/lifecycle.ts
+++ b/packages/eve/src/instrumentation/lifecycle.ts
@@ -3,6 +3,11 @@ import type { InstrumentationStateSlot } from "#instrumentation/state.js";
import type { RuntimeTraceContext } from "#protocol/message.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
+import type {
+ InstrumentationCapture,
+ TraceCaptureContext,
+ TraceCapturePolicy,
+} from "#shared/trace-policy.js";
/**
* Stable eve identity for one actual model attempt.
@@ -102,23 +107,6 @@ export type InstrumentationActionOutput =
| { readonly type: "result"; readonly output?: unknown }
| { readonly type: "error"; readonly error?: unknown };
-/**
- * How much of an event a provider is handed.
- *
- * `"metadata"` — the default — is structure, identity, usage, and timing: every
- * field except what the conversation actually said. `"content"` adds the
- * prompt, the response, tool arguments, and tool results.
- *
- * Declared per provider rather than per process, because two consumers of one
- * bus rarely have the same retention path. Content is built at all only when
- * some provider asked for it, and a provider that did not ask never receives
- * it — which is the same guarantee a destination that declines content gets,
- * one layer lower and without an OpenTelemetry pipeline to route it through.
- * OpenTelemetry trace policy is applied only inside the OTel provider and does
- * not narrow this provider-level projection.
- */
-export type InstrumentationCapture = "content" | "metadata";
-
/**
* Every event carries an `idempotencyKey` naming the operation it is about: a
* start and its terminal share one, and two operations never collide.
@@ -195,7 +183,7 @@ interface InstrumentationChannelDeliveryScope {
export interface InstrumentationChannelDeliveryStartedEvent extends InstrumentationChannelDeliveryScope {
readonly parentTraceContext?: InstrumentationTraceContext;
readonly type: "channel.delivery.started";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly input?: InstrumentationChannelDeliveryInput;
}
@@ -206,7 +194,7 @@ export interface InstrumentationChannelDeliveryTerminalEvent extends Instrumenta
| "channel.delivery.cancelled"
| "channel.delivery.completed"
| "channel.delivery.failed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly errorCode?: string;
readonly outcome: InstrumentationChannelDeliveryOutcome;
@@ -253,7 +241,7 @@ export interface InstrumentationInputRequestedEvent {
};
readonly idempotencyKey: string;
readonly kind: InstrumentationInputKind;
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly request?: InstrumentationInputRequest;
readonly requestId: string;
readonly scope: InstrumentationAttemptScope;
@@ -266,7 +254,7 @@ export interface InstrumentationInputResolvedEvent {
readonly kind: InstrumentationInputKind;
readonly outcome: InstrumentationInputOutcome;
readonly requestId: string;
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly response?: InstrumentationInputResponse;
readonly scope: InstrumentationAttemptScope;
}
@@ -329,7 +317,7 @@ export interface InstrumentationSessionSettledEvent {
export interface InstrumentationSessionFailedEvent {
readonly type: "session.failed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly idempotencyKey: string;
readonly sessionId: string;
@@ -367,7 +355,7 @@ export interface InstrumentationTurnSettledEvent {
export interface InstrumentationTurnFailedEvent {
readonly type: "turn.failed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly idempotencyKey: string;
readonly sessionId: string;
@@ -386,7 +374,7 @@ export interface InstrumentationStepAttemptCompletedEvent {
export interface InstrumentationStepAttemptFailedEvent {
readonly type: "step.attempt.failed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly idempotencyKey: string;
readonly scope: InstrumentationAttemptScope;
@@ -411,7 +399,7 @@ export interface InstrumentationStepAttemptMetadataEvent {
export interface InstrumentationModelCallStartedEvent {
readonly type: "model.call.started";
readonly idempotencyKey: string;
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly input?: InstrumentationModelInput;
readonly model: InstrumentationModelRef;
readonly runtimeContext?: Readonly<Record<string, unknown>>;
@@ -420,7 +408,7 @@ export interface InstrumentationModelCallStartedEvent {
export interface InstrumentationModelCallCompletedEvent {
readonly type: "model.call.completed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly content?: readonly InstrumentationContentPart[];
readonly finishReason: string;
readonly idempotencyKey: string;
@@ -430,7 +418,7 @@ export interface InstrumentationModelCallCompletedEvent {
export interface InstrumentationModelCallFailedEvent {
readonly type: "model.call.failed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly idempotencyKey: string;
readonly scope: InstrumentationAttemptScope;
@@ -460,7 +448,7 @@ export interface InstrumentationToolCallCompletedEvent {
export interface InstrumentationToolCallFailedEvent {
readonly type: "tool.call.failed";
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly idempotencyKey: string;
readonly scope: InstrumentationAttemptScope;
@@ -479,7 +467,7 @@ export interface InstrumentationActionStartedEvent {
readonly type: "action.started";
readonly callId: string;
readonly idempotencyKey: string;
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly input?: unknown;
readonly kind: InstrumentationActionKind;
readonly name: string;
@@ -506,7 +494,7 @@ export interface InstrumentationActionCompletedEvent {
export interface InstrumentationActionFailedEvent {
readonly type: "action.failed";
readonly acceptedAtMs?: number;
- /** Content. Absent unless this provider declared `capture: "content"`. */
+ /** Content. Absent unless this provider's trace policy records this direction. */
readonly error?: unknown;
readonly errorCode?: string;
readonly idempotencyKey: string;
@@ -538,14 +526,16 @@ export type InstrumentationEventHandler<TEvent> = (
/** Internal provider shape mirrored by the future public hook contract. */
export interface InstrumentationProviderDefinition {
readonly name: string;
+ /** @deprecated Use `tracePolicy` to select directional content. */
+ readonly capture?: InstrumentationCapture;
/** Durable state identity, separate from the human-readable log name. */
readonly stateNamespace?: string;
/** Internal provider-specific projection applied after capture filtering. */
readonly projectEvent?: (
event: InstrumentationEvent,
) => InstrumentationEvent | PromiseLike<InstrumentationEvent>;
- /** Defaults to `"metadata"`. See {@link InstrumentationCapture}. */
- readonly capture?: InstrumentationCapture;
+ /** Provider-specific event admission and directional content policy. */
+ readonly tracePolicy?: TraceCapturePolicy;
readonly events?: {
readonly "channel.delivery.started"?: InstrumentationEventHandler<InstrumentationChannelDeliveryStartedEvent>;
readonly "channel.delivery.cancelled"?: InstrumentationEventHandler<InstrumentationChannelDeliveryTerminalEvent>;
@@ -641,13 +631,18 @@ export type InstrumentationExecutionOperation =
/** Provider-neutral hook operations consumed by the AI SDK bridge. */
export interface InstrumentationHooks {
/**
- * Whether any registered provider declared `capture: "content"`.
+ * Whether any provider admitted by this bound trace requests content.
*
* False means nothing downstream can read what was said, so the publisher
* should not serialize it in the first place. This is the only way the
* projection is skipped rather than merely withheld.
*/
readonly capturesContent: boolean;
+ /** Input-content demand for publishers that can project directions separately. */
+ readonly capturesInputs?: boolean;
+ /** Output-content demand for publishers that can project directions separately. */
+ readonly capturesOutputs?: boolean;
+ readonly forTrace?: (trace: TraceCaptureContext) => InstrumentationHooks;
publish(event: InstrumentationEvent): Promise<void>;
}
diff --git a/packages/eve/src/instrumentation/native-events.ts b/packages/eve/src/instrumentation/native-events.ts
index 2be1fcb0d..18492b96d 100644
--- a/packages/eve/src/instrumentation/native-events.ts
+++ b/packages/eve/src/instrumentation/native-events.ts
@@ -113,6 +113,7 @@ async function publishInputStarts(
): Promise<void> {
const scope = input.getAttemptScope?.();
if (scope === undefined) return;
+ const capturesOutputs = hooks.capturesOutputs ?? hooks.capturesContent;
for (const request of event.data.requests) {
const idempotencyKey = inputIdempotencyKey(
@@ -131,7 +132,7 @@ async function publishInputStarts(
}),
idempotencyKey,
kind: request.kind,
- request: hooks.capturesContent
+ request: capturesOutputs
? Object.freeze({
allowFreeform: request.allowFreeform,
display: request.display,
@@ -153,6 +154,7 @@ export async function publishInputResolutions(input: {
readonly hooks: InstrumentationHooks;
readonly sessionId: string;
}): Promise<void> {
+ const capturesInputs = input.hooks.capturesInputs ?? input.hooks.capturesContent;
for (const resolved of input.batch.inputs) {
const idempotencyKey = inputIdempotencyKey(
input.sessionId,
@@ -168,7 +170,7 @@ export async function publishInputResolutions(input: {
outcome: resolved.outcome,
requestId: resolved.request.requestId,
response:
- !input.hooks.capturesContent || resolved.response === undefined
+ !capturesInputs || resolved.response === undefined
? undefined
: Object.freeze({
optionId: resolved.response.optionId,
@@ -189,6 +191,7 @@ async function publishActionStarts(
): Promise<void> {
const scope = input.getAttemptScope?.();
if (scope === undefined) return;
+ const capturesInputs = hooks.capturesInputs ?? hooks.capturesContent;
for (const action of event.data.actions) {
const idempotencyKey = actionIdempotencyKey(input.sessionId, event.data.turnId, action.callId);
@@ -199,7 +202,7 @@ async function publishActionStarts(
Object.freeze({
callId: action.callId,
idempotencyKey,
- input: hooks.capturesContent ? action.input : undefined,
+ input: capturesInputs ? action.input : undefined,
kind: action.kind,
name: actionName(action),
scope,
@@ -220,6 +223,7 @@ async function publishActionTerminal(
);
if (correlation === undefined) return;
const { idempotencyKey, scope } = correlation;
+ const capturesOutputs = hooks.capturesOutputs ?? hooks.capturesContent;
if (event.data.status === "completed") {
await hooks.publish(
@@ -230,7 +234,7 @@ async function publishActionTerminal(
idempotencyKey,
outcome: "completed",
output: Object.freeze(
- hooks.capturesContent
+ capturesOutputs
? { output: event.data.result.output, type: "result" }
: { type: "result" },
),
@@ -242,10 +246,11 @@ async function publishActionTerminal(
return;
}
- const error =
- event.data.error === undefined
+ const error = capturesOutputs
+ ? event.data.error === undefined
? event.data.result.output
- : Object.assign(new Error(event.data.error.message), { code: event.data.error.code });
+ : Object.assign(new Error(event.data.error.message), { code: event.data.error.code })
+ : undefined;
await hooks.publish(
Object.freeze({
acceptedAtMs: contextStorage.getStore()?.get(RuntimeActionSettlementTimesKey)?.[
diff --git a/packages/eve/src/instrumentation/provider.ts b/packages/eve/src/instrumentation/provider.ts
index 161d483de..1899f1437 100644
--- a/packages/eve/src/instrumentation/provider.ts
+++ b/packages/eve/src/instrumentation/provider.ts
@@ -9,8 +9,9 @@
// runtime. The event shapes are eve's own vocabulary; deriving the handler map
// from the union below is what keeps the public contract from drifting away
// from the bus that feeds it.
-import type { InstrumentationCapture, InstrumentationEvent } from "#instrumentation/lifecycle.js";
+import type { InstrumentationEvent } from "#instrumentation/lifecycle.js";
import type { JsonValue } from "#shared/json.js";
+import type { InstrumentationCapture, TraceCapturePolicy } from "#shared/trace-policy.js";
export type { JsonValue } from "#shared/json.js";
@@ -22,7 +23,6 @@ export type {
InstrumentationActionOutput,
InstrumentationActionStartedEvent,
InstrumentationAttemptScope,
- InstrumentationCapture,
InstrumentationChannelDeliveryInput,
InstrumentationChannelDeliveryOutcome,
InstrumentationChannelDeliveryRef,
@@ -63,6 +63,12 @@ export type {
InstrumentationTurnTerminalEvent,
InstrumentationUsage,
} from "#instrumentation/lifecycle.js";
+export type {
+ InstrumentationCapture,
+ TraceCaptureContext,
+ TraceCapturePolicy,
+ TracePolicyDecision,
+} from "#shared/trace-policy.js";
/**
* Marks a value as having come from `defineInstrumentation` or a built-in
@@ -148,15 +154,17 @@ export type ProviderEvents = {
* completion order.
*/
export interface ProviderDefinition {
+ /** @deprecated Use `tracePolicy`. Ignored when `tracePolicy` is also set. */
+ readonly capture?: InstrumentationCapture;
/**
- * How much of each event this provider is handed. Defaults to `"metadata"`:
- * structure, identity, usage, and timing, but not what was said.
- *
- * `"content"` adds the prompt, the response, tool arguments, and tool
- * results. Asking is what makes eve build the projection at all, so a
- * directory in which nobody asks never serializes a prompt.
+ * Whether this provider receives events and which content directions they
+ * include. Defaults to emitting every audience, with content only for public
+ * conversations. Boolean `true` uses the same audience-aware content rule;
+ * an explicit emitted decision can authorize either direction independently.
+ * A thrown error disables this provider for the trace. The policy can run
+ * again across durable steps, so it must be deterministic.
*/
- readonly capture?: InstrumentationCapture;
+ readonly tracePolicy?: TraceCapturePolicy;
readonly events?: ProviderEvents;
/** Runs once at server startup, before any event is published. */
readonly setup?: (context: ProviderSetupContext) => void | PromiseLike<void>;
diff --git a/packages/eve/src/instrumentation/providers-otel-policy.test.ts b/packages/eve/src/instrumentation/providers-otel-policy.test.ts
index a9a2c8738..41ccf141e 100644
--- a/packages/eve/src/instrumentation/providers-otel-policy.test.ts
+++ b/packages/eve/src/instrumentation/providers-otel-policy.test.ts
@@ -46,7 +46,7 @@ describe("otel and authored provider composition", () => {
agentName: "weather-agent",
slot: "rows",
value: defineInstrumentation({
- capture: "content",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
events: { "model.call.started": modelStarted },
}),
});
diff --git a/packages/eve/src/instrumentation/providers.test.ts b/packages/eve/src/instrumentation/providers.test.ts
index de9f93140..89a9f8671 100644
--- a/packages/eve/src/instrumentation/providers.test.ts
+++ b/packages/eve/src/instrumentation/providers.test.ts
@@ -215,6 +215,34 @@ describe("finalizeInstrumentationProviders", () => {
expect(started.mock.calls[0]?.[0]).toMatchObject({ turnId: "turn-1" });
});
+ it.each([
+ ["content", true],
+ ["metadata", false],
+ ] as const)(
+ "maps the deprecated %s capture setting to provider policy",
+ async (capture, expected) => {
+ await register("legacy", defineInstrumentation({ capture }));
+
+ const runtime = finalizeInstrumentationProviders({ serviceName: "weather-agent" });
+
+ expect(runtime.hooks.forTrace?.({ audience: "private" }).capturesContent).toBe(expected);
+ },
+ );
+
+ it("prefers provider tracePolicy over deprecated capture", async () => {
+ await register(
+ "provider",
+ defineInstrumentation({
+ capture: "metadata",
+ tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
+ }),
+ );
+
+ const runtime = finalizeInstrumentationProviders({ serviceName: "weather-agent" });
+
+ expect(runtime.hooks.forTrace?.({ audience: "private" }).capturesContent).toBe(true);
+ });
+
it("still runs execution when no destination was declared", async () => {
// A directory with no `otel()` has nothing to hang a span on, so
// `runInContext` degrades to running the work directly rather than
diff --git a/packages/eve/src/instrumentation/providers.ts b/packages/eve/src/instrumentation/providers.ts
index 320ef3e9f..68b598579 100644
--- a/packages/eve/src/instrumentation/providers.ts
+++ b/packages/eve/src/instrumentation/providers.ts
@@ -154,5 +154,6 @@ function toProviderDefinition(
name: entry.slot,
shutdown: entry.provider.shutdown,
stateNamespace: `authored:${entry.slot}`,
+ tracePolicy: entry.provider.tracePolicy,
};
}
diff --git a/packages/eve/src/instrumentation/runtime.test.ts b/packages/eve/src/instrumentation/runtime.test.ts
index 6a36d961d..aa48cdf10 100644
--- a/packages/eve/src/instrumentation/runtime.test.ts
+++ b/packages/eve/src/instrumentation/runtime.test.ts
@@ -89,6 +89,30 @@ describe("bindInstrumentationRuntime", () => {
});
});
+ it("binds provider hooks to the step-entry agent and channel", async () => {
+ const boundHooks: InstrumentationHooks = { capturesContent: false, publish: vi.fn() };
+ const forTrace = vi.fn(() => boundHooks);
+ const ctx = createContext("private");
+ ctx.set(ChannelInstrumentationKey, {
+ channelType: "slack",
+ kind: "channel:test",
+ metadata: { audience: "private" },
+ });
+ const instrumentation = bindInstrumentationRuntime(
+ createRuntime({ capturesContent: false, forTrace, publish: vi.fn() }),
+ ctx,
+ { ...boundSession, agentName: "Weather Display Name" },
+ );
+
+ await readTelemetry(instrumentation);
+
+ expect(forTrace).toHaveBeenCalledExactlyOnceWith({
+ agentName: "Weather Display Name",
+ audience: "private",
+ channelType: "slack",
+ });
+ });
+
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 aa86b554e..57064aaa5 100644
--- a/packages/eve/src/instrumentation/runtime.ts
+++ b/packages/eve/src/instrumentation/runtime.ts
@@ -181,7 +181,7 @@ export interface ExecutionInstrumentation {
readonly flush: () => Promise<void>;
readonly instrumentChannelDelivery: (
input:
- | Omit<ChannelDeliveryStartInstrumentation, "hooks">
+ | Omit<ChannelDeliveryStartInstrumentation, "hooks" | "policyAgentName">
| Omit<ChannelDeliveryTerminalInstrumentation, "hooks">,
) => Promise<void>;
readonly prepareExecution: () => SessionInstrumentation;
@@ -194,7 +194,7 @@ export function bindInstrumentationRuntime(
boundSession: BoundInstrumentationSession,
): ExecutionInstrumentation | undefined {
if (runtime === undefined) return undefined;
- const hooks = runtime.hooks;
+ const baseHooks = runtime.hooks;
const readSessionContext = () => {
const context = contextStorage.getStore() ?? ctx;
return {
@@ -206,6 +206,16 @@ export function bindInstrumentationRuntime(
traceSeed: context.get(SessionTraceSeedKey),
};
};
+ const bindHooks = (sessionContext: ReturnType<typeof readSessionContext>) => {
+ const channel = sessionContext.instrumentation;
+ return (
+ baseHooks.forTrace?.({
+ agentName: boundSession.agentName,
+ audience: normalizeChannelAudience(channel?.metadata.audience),
+ channelType: channel?.channelType,
+ }) ?? baseHooks
+ );
+ };
const captureExecutionRuntime = () => {
const otelSettings = runtime.otelSettings;
if (otelSettings !== undefined) ensureOtelIntegration();
@@ -240,6 +250,7 @@ export function bindInstrumentationRuntime(
return {
runStep: async (input, execute) => {
const policyContext = readSessionContext();
+ const hooks = bindHooks(policyContext);
const settings = executionRuntime.otelSettings;
const decision = resolveStepInstrumentationDecision(
settings,
@@ -435,17 +446,24 @@ export function bindInstrumentationRuntime(
};
};
return {
- createCancellationHandleEvent: (input) =>
- createInstrumentationHandleEvent({
+ createCancellationHandleEvent: (input) => {
+ const sessionContext = readSessionContext();
+ return createInstrumentationHandleEvent({
agentName: boundSession.agentName,
- channelKind: readSessionContext().instrumentation?.kind,
+ channelKind: sessionContext.instrumentation?.kind,
handleEvent: input.handleEvent,
- hooks,
+ hooks: bindHooks(sessionContext),
sessionId: boundSession.sessionId,
turnId: input.turnId,
- }),
+ });
+ },
flush: runtime.forceFlush,
- instrumentChannelDelivery: (input) => instrumentChannelDelivery({ ...input, hooks }),
+ instrumentChannelDelivery: (input) =>
+ instrumentChannelDelivery({
+ ...input,
+ hooks: baseHooks,
+ policyAgentName: boundSession.agentName,
+ }),
prepareExecution,
preparePreamble: (input) => preparePreamble(input, readSessionContext()),
};
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 902fa0d3b..3347f778d 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -18,7 +18,10 @@ import {
defineDynamic as defineDynamicInstructions,
defineInstructions,
} from "#public/definitions/instructions.js";
-import { defineInstrumentation } from "#public/definitions/instrumentation.js";
+import {
+ defineInstrumentation,
+ type ProviderDefinition,
+} from "#public/definitions/instrumentation.js";
import { defineSandbox } from "#public/definitions/sandbox.js";
import { defineSchedule } from "#public/definitions/schedule.js";
import { defineSkill } from "#public/definitions/skill.js";
@@ -305,6 +308,9 @@ function typeOnlyFixtures(): void {
},
});
+ const providerWithCapture: ProviderDefinition = { capture: "content" };
+ void providerWithCapture;
+
defineInstrumentation({
// @ts-expect-error Instrumentation event hooks are authored through `events`.
runtimeContext: {
diff --git a/packages/eve/src/public/instrumentation/provider.test.ts b/packages/eve/src/public/instrumentation/provider.test.ts
index 7752e0614..5c03374ae 100644
--- a/packages/eve/src/public/instrumentation/provider.test.ts
+++ b/packages/eve/src/public/instrumentation/provider.test.ts
@@ -27,6 +27,17 @@ describe("defineInstrumentation", () => {
expect(isInstrumentationProvider(provider)).toBe(true);
});
+ it("preserves a provider trace policy", () => {
+ const tracePolicy = ({ audience }: { audience: string }) => ({
+ emit: true as const,
+ recordInputs: audience === "public",
+ recordOutputs: false,
+ });
+ const provider = defineInstrumentation({ tracePolicy });
+
+ expect(provider.tracePolicy).toBe(tracePolicy);
+ });
+
it("brands a legacy config-shaped declaration", () => {
const config = defineInstrumentation({ functionId: "support", recordInputs: false });
diff --git a/packages/eve/src/shared/trace-policy.ts b/packages/eve/src/shared/trace-policy.ts
new file mode 100644
index 000000000..6e1b6ca39
--- /dev/null
+++ b/packages/eve/src/shared/trace-policy.ts
@@ -0,0 +1,81 @@
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import { shouldCaptureInstrumentationContent } from "#shared/instrumentation-content.js";
+import {
+ DROP_INSTRUMENTATION,
+ type InstrumentationDecision,
+} from "#shared/instrumentation-decision.js";
+
+/** @deprecated Use `TraceCapturePolicy` to select directional content. */
+export type InstrumentationCapture = "content" | "metadata";
+
+export interface TraceCaptureContext {
+ readonly agentName?: string;
+ readonly audience: ChannelAudience;
+ readonly channelType?: string;
+}
+
+export type TracePolicyDecision =
+ | { readonly emit: false }
+ | {
+ readonly emit: true;
+ readonly recordInputs: boolean;
+ readonly recordOutputs: boolean;
+ };
+
+export type TraceCapturePolicy = (trace: TraceCaptureContext) => TracePolicyDecision | boolean;
+
+export function legacyCaptureTracePolicy(
+ capture: InstrumentationCapture | undefined,
+): TraceCapturePolicy | undefined {
+ if (capture === undefined) return undefined;
+ const recordsContent = capture === "content";
+ return () => ({
+ emit: true,
+ recordInputs: recordsContent,
+ recordOutputs: recordsContent,
+ });
+}
+
+export function resolveTracePolicy(
+ policy: TraceCapturePolicy | undefined,
+ trace: TraceCaptureContext,
+ onError?: (error: unknown) => void,
+): InstrumentationDecision {
+ try {
+ const decision = policy?.({
+ agentName: trace.agentName,
+ audience: trace.audience,
+ channelType: trace.channelType,
+ });
+ return resolveTracePolicyDecision(
+ decision ?? {
+ emit: true,
+ recordInputs: trace.audience === "public",
+ recordOutputs: trace.audience === "public",
+ },
+ trace.audience,
+ );
+ } catch (error) {
+ try {
+ onError?.(error);
+ } catch {}
+ return DROP_INSTRUMENTATION;
+ }
+}
+
+export function resolveTracePolicyDecision(
+ decision: TracePolicyDecision | boolean,
+ audience: ChannelAudience,
+): InstrumentationDecision {
+ if (decision === false) return DROP_INSTRUMENTATION;
+ if (decision === true) {
+ const content = shouldCaptureInstrumentationContent(audience);
+ return { action: "record", recordInputs: content, recordOutputs: content };
+ }
+ if (!decision.emit) return DROP_INSTRUMENTATION;
+ return {
+ action: "record",
+ recordInputs: decision.recordInputs,
+ recordOutputs: decision.recordOutputs,
+ };
+}
diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.ts
index 8e732986a..0f8b589e0 100644
--- a/packages/eve/src/tracing/agent-otel-provider.test.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts
@@ -131,16 +131,16 @@ async function emitAttempt(input: {
stepIndex: 0,
turnId: input.turnId,
};
+ const hooks =
+ input.hooks.forTrace?.({
+ agentName: "weather",
+ audience: scope.channelAudience ?? "unknown",
+ }) ?? input.hooks;
if (input.turnAlreadyStarted !== true) {
- await publishTurnStarted(input);
+ await publishTurnStarted({ ...input, hooks });
}
- const bridge = createAiSdkHookBridge(
- scope,
- input.hooks,
- input.runInContext,
- input.runtimeContext,
- );
+ const bridge = createAiSdkHookBridge(scope, hooks, input.runInContext, input.runtimeContext);
Reflect.apply(bridge.onStart!, bridge, [
{
callId: "call-1",
@@ -203,7 +203,7 @@ async function emitAttempt(input: {
]);
}
const actionKey = actionIdempotencyKey(input.sessionId, input.turnId, "tool-1");
- await input.hooks.publish({
+ await hooks.publish({
callId: "tool-1",
idempotencyKey: actionKey,
input: { secret: "value" },
@@ -236,7 +236,7 @@ async function emitAttempt(input: {
: { error: input.toolError, type: "tool-error" },
},
]);
- await input.hooks.publish(
+ await hooks.publish(
input.toolError === undefined
? {
idempotencyKey: actionKey,
@@ -258,7 +258,7 @@ async function emitAttempt(input: {
}
if (input.providerMetadata !== undefined) {
- await input.hooks.publish({
+ await hooks.publish({
idempotencyKey: attemptIdempotencyKey(scope),
providerMetadata: input.providerMetadata,
scope,
@@ -266,7 +266,7 @@ async function emitAttempt(input: {
});
}
- await input.hooks.publish(
+ await hooks.publish(
input.attemptError === undefined
? {
idempotencyKey: attemptIdempotencyKey(scope),
@@ -280,13 +280,13 @@ async function emitAttempt(input: {
type: "step.attempt.failed",
},
);
- await input.hooks.publish({
+ await hooks.publish({
idempotencyKey: turnIdempotencyKey(input.sessionId, input.turnId),
sessionId: input.sessionId,
turnId: input.turnId,
type: "turn.completed",
});
- await input.hooks.publish({
+ await hooks.publish({
idempotencyKey: sessionIdempotencyKey(input.sessionId),
sessionId: input.sessionId,
turnId: input.turnId,
@@ -1548,7 +1548,8 @@ describe("createAgentOtelInstrumentation", () => {
stepIndex: 0,
turnId: "turn-1",
};
- await runtime.hooks.publish({
+ const hooks = runtime.hooks.forTrace!({ agentName: "weather", audience: "public" });
+ await hooks.publish({
agentName: "weather",
channelAudience: "public",
channelKind: "http",
@@ -1557,7 +1558,7 @@ describe("createAgentOtelInstrumentation", () => {
sessionId: "session-1",
type: "session.started",
});
- await runtime.hooks.publish({
+ await hooks.publish({
idempotencyKey: turnIdempotencyKey("session-1", "turn-1"),
rootSessionId: "session-1",
sequence: 0,
@@ -1565,7 +1566,7 @@ describe("createAgentOtelInstrumentation", () => {
turnId: "turn-1",
type: "turn.started",
});
- const bridge = createAiSdkHookBridge(scope, runtime.hooks, runtime.runInContext);
+ const bridge = createAiSdkHookBridge(scope, hooks, runtime.runInContext);
Reflect.apply(bridge.onStart!, bridge, [
{
callId: "call-1",
diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.ts
index 1b65fab01..0c56a2065 100644
--- a/packages/eve/src/tracing/agent-otel-provider.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.ts
@@ -476,10 +476,6 @@ export function createAgentOtelInstrumentation(
return {
hook: {
- // The destinations behind this pipeline filter content per exporter, but
- // that filter only runs on a span that has it. Declining both here is
- // what stops the projection from being built upstream.
- capture: recordInputs || recordOutputs ? "content" : "metadata",
events: {
...channelDeliveries,
"action.completed": actions.events["action.completed"],
@@ -508,6 +504,7 @@ export function createAgentOtelInstrumentation(
},
name: "eve.otel",
projectEvent,
+ tracePolicy: () => ({ emit: true, recordInputs, recordOutputs }),
},
prepareSessionTrace,
prepareTurnTrace,
diff --git a/packages/eve/src/tracing/otel-declaration.ts b/packages/eve/src/tracing/otel-declaration.ts
index aa1f05d7b..b16a2239c 100644
--- a/packages/eve/src/tracing/otel-declaration.ts
+++ b/packages/eve/src/tracing/otel-declaration.ts
@@ -14,7 +14,12 @@ 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 type { TraceCapturePolicy } from "#shared/trace-policy.js";
+export type {
+ TraceCaptureContext,
+ TraceCapturePolicy,
+ TracePolicyDecision,
+} from "#shared/trace-policy.js";
import {
composeSpanExportPolicies,
redactSpanInputs,
@@ -113,22 +118,6 @@ export interface ContentOptions {
readonly recordOutputs?: boolean;
}
-export interface TraceCaptureContext {
- readonly agentName?: string;
- readonly audience: ChannelAudience;
- readonly channelType?: string;
-}
-
-export type TracePolicyDecision =
- | { readonly emit: false }
- | {
- readonly emit: true;
- readonly recordInputs: boolean;
- readonly recordOutputs: boolean;
- };
-
-export type TraceCapturePolicy = (trace: TraceCaptureContext) => TracePolicyDecision | boolean;
-
/** Where one `otelIntegration()` sends spans and metrics. */
export interface OtelIntegrationOptions extends ContentOptions {
/** Merged into the pipeline in declaration order. */
diff --git a/packages/eve/src/tracing/sampled-trace.test.ts b/packages/eve/src/tracing/sampled-trace.test.ts
index f95533143..dd7600a54 100644
--- a/packages/eve/src/tracing/sampled-trace.test.ts
+++ b/packages/eve/src/tracing/sampled-trace.test.ts
@@ -63,6 +63,20 @@ describe("resolveTracePolicyDecision", () => {
).toEqual({ action: "drop" });
});
+ it("fails closed when policy error reporting also throws", () => {
+ expect(
+ resolveTracePolicy(
+ () => {
+ throw new Error("policy failed");
+ },
+ { audience: "public" },
+ () => {
+ throw new Error("reporting failed");
+ },
+ ),
+ ).toEqual({ action: "drop" });
+ });
+
it.each([
["public", true],
["private", false],
diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.ts
index fb087bc25..86a634f6d 100644
--- a/packages/eve/src/tracing/sampled-trace.ts
+++ b/packages/eve/src/tracing/sampled-trace.ts
@@ -1,10 +1,4 @@
-import type { ChannelAudience } from "#shared/channel-audience.js";
-import { shouldCaptureInstrumentationContent } from "#shared/instrumentation-content.js";
-import {
- DROP_INSTRUMENTATION,
- type InstrumentationDecision,
-} from "#shared/instrumentation-decision.js";
-import type { TraceCapturePolicy, TracePolicyDecision } from "#tracing/otel-declaration.js";
+export { resolveTracePolicy, resolveTracePolicyDecision } from "#shared/trace-policy.js";
// W3C sampled flag; written as a literal so this module stays out of the
// vendored OTel chunk, which the workflow driver bundle cannot include.
@@ -13,58 +7,3 @@ const TRACE_FLAGS_SAMPLED = 0x01;
export function isSampledTrace(context: { readonly traceFlags: number }): boolean {
return (context.traceFlags & TRACE_FLAGS_SAMPLED) === TRACE_FLAGS_SAMPLED;
}
-
-export function evaluateTracePolicy(
- policy: TraceCapturePolicy | undefined,
- trace: {
- readonly agentName?: string;
- readonly audience: ChannelAudience;
- readonly channelType?: string;
- },
-): boolean {
- return resolveTracePolicy(policy, trace).action === "record";
-}
-
-export function resolveTracePolicy(
- policy: TraceCapturePolicy | undefined,
- trace: {
- readonly agentName?: string;
- readonly audience: ChannelAudience;
- readonly channelType?: string;
- },
-): InstrumentationDecision {
- try {
- const decision = policy?.({
- agentName: trace.agentName,
- audience: trace.audience,
- channelType: trace.channelType,
- });
- return resolveTracePolicyDecision(
- decision ?? {
- emit: true,
- recordInputs: trace.audience === "public",
- recordOutputs: trace.audience === "public",
- },
- trace.audience,
- );
- } catch {
- return DROP_INSTRUMENTATION;
- }
-}
-
-export function resolveTracePolicyDecision(
- decision: TracePolicyDecision | boolean,
- audience: ChannelAudience,
-): InstrumentationDecision {
- if (decision === false) return DROP_INSTRUMENTATION;
- if (decision === true) {
- const content = shouldCaptureInstrumentationContent(audience);
- return { action: "record", recordInputs: content, recordOutputs: content };
- }
- if (!decision.emit) return DROP_INSTRUMENTATION;
- return {
- action: "record",
- recordInputs: decision.recordInputs,
- recordOutputs: decision.recordOutputs,
- };
-}
diff --git a/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts b/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts
index 4cec5c973..05ea736bd 100644
--- a/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts
+++ b/packages/eve/test/scenarios/compiled-artifacts-bootstrap.scenario.test.ts
@@ -149,6 +149,11 @@ describe("writeCompiledArtifactsFiles", () => {
"const container = globalThis as Record<string, unknown>;",
"",
"export default defineInstrumentation({",
+ " tracePolicy: ({ audience }) => ({",
+ " emit: true,",
+ ' recordInputs: audience === "public",',
+ " recordOutputs: false,",
+ " }),",
" setup(context) {",
" container.__eveProviderSetups ??= [];",
` (container.__eveProviderSetups as string[]).push(\`${slot}:\${context.agentName}\`);`,
@@ -206,7 +211,13 @@ describe("writeCompiledArtifactsFiles", () => {
"local:compiled-artifacts-providers-test-agent",
"otel:compiled-artifacts-providers-test-agent",
]);
- expect(getInstrumentationProviders().map((entry) => entry.slot)).toEqual(["local", "otel"]);
+ const providers = getInstrumentationProviders();
+ expect(providers.map((entry) => entry.slot)).toEqual(["local", "otel"]);
+ expect(providers[0]?.provider.tracePolicy?.({ audience: "public" })).toEqual({
+ emit: true,
+ recordInputs: true,
+ recordOutputs: false,
+ });
expect(closeHandlers).toHaveLength(1);
await closeHandlers[0]?.();
});
diff --git a/research/channel-audience-content-policy.md b/research/channel-audience-content-policy.md
index d814e8f2a..4ae21835e 100644
--- a/research/channel-audience-content-policy.md
+++ b/research/channel-audience-content-policy.md
@@ -1,7 +1,7 @@
---
issue: https://github.com/vercel/eve/issues/2331
status: proposed
-last_updated: "2026-08-20"
+last_updated: "2026-08-28"
---
# Audience-aware trace content policy
@@ -34,8 +34,7 @@ The process-wide declaration owns trace creation:
interface TraceCaptureContext {
readonly agentName?: string;
readonly audience: ChannelAudience;
- readonly rootSessionId: string;
- readonly sessionId: string;
+ readonly channelType?: string;
}
type TracePolicyDecision =
@@ -53,13 +52,20 @@ interface OtelOptions {
readonly tracePolicy?: TraceCapturePolicy;
}
+interface ProviderDefinition {
+ readonly tracePolicy?: TraceCapturePolicy;
+}
+
declare function otel(options?: OtelOptions): OtelDeclaration;
```
-The trace decision is a process-wide ceiling. Each delivery is intersected with
-its own audience classification, and destination capture settings may narrow it
-further. A boolean return keeps the existing behavior: `false` drops trace
-production, while `true` records content only where the audience ceiling permits.
+The `otel()` trace decision is a process-wide OTel ceiling. Each delivery is
+intersected with its own audience classification, and destination settings may
+narrow it further. A provider's `defineInstrumentation({ tracePolicy })` decision
+is independent: `false` skips that provider, `true` uses audience-aware content,
+and an explicit emitted decision authorizes its input and output directions even
+for private channels. An omitted provider policy uses the default audience-aware
+behavior.
Agent Runs and local traces expose the managed export policy:
@@ -148,11 +154,14 @@ The default authored and production head policy is equivalent to:
});
```
-| Audience | Trace created by default | Content when admitted by a custom trace policy |
-| --------- | ------------------------ | ---------------------------------------------- |
-| `public` | Yes | Yes |
-| `private` | Yes | No |
-| `unknown` | Yes | No |
+| Audience | Trace created by default | Content by default |
+| --------- | ------------------------ | ------------------ |
+| `public` | Yes | Yes |
+| `private` | Yes | No |
+| `unknown` | Yes | No |
+
+An explicit provider policy can authorize content for any audience. The OTel
+policy remains subject to its process-wide audience ceiling.
The default policy for local tracing for `eve dev` is equivalent to:
@@ -170,12 +179,23 @@ The runtime order is:
4. Run each managed destination's composed export policies in declaration order. Custom integrations run their declared span processors.
5. Hand the resulting facade to that destination's processors or exporter.
+The lifecycle bus separately evaluates each instrumentation provider's policy
+against the same agent and channel context, skips rejected providers, and applies
+directional content projection before invoking accepted handlers.
+
There is no implicit content redaction after a custom trace policy admits an audience. Redaction occurs only when the export pipeline includes `redactSpanInputs()` or `redactSpanOutputs()` (or when a retained compatibility option explicitly requests the equivalent redaction).
Policies fail closed at their boundary: a throwing trace policy rejects the trace, a throwing span policy drops the span, a throwing attribute policy drops the attribute, and a throwing content-redaction predicate redacts that content direction. Missing, malformed, or conflicting audience evidence normalizes to `unknown`.
## Compatibility
-The existing `recordInputs` and `recordOutputs` destination options remain accepted as deprecated source-compatible aliases. An explicit `false` prepends the corresponding redaction policy; these options no longer prevent accepted spans from capturing content upstream. `EVE_TRACES_CONTENT=off` similarly prepends both redactors for local traces.
+Instrumentation providers deprecate the experimental `capture` field in favor
+of `tracePolicy`; `"content"` and `"metadata"` are mapped to equivalent fixed
+policies while integrations migrate. The existing OTel destination
+`recordInputs` and `recordOutputs` options remain accepted as deprecated
+source-compatible aliases. An explicit `false` prepends the corresponding
+redaction policy; these options no longer prevent accepted spans from capturing
+content upstream. `EVE_TRACES_CONTENT=off` similarly prepends both redactors for
+local traces.
Filtering remains a span-processor responsibility because local trace persistence and authored processors are processors rather than uniform exporters. Keeping the filtering boundary immediately above each destination prevents one destination's policy from mutating what another destination receives.
diff --git a/research/provider-neutral-local-observability.md b/research/provider-neutral-local-observability.md
index cb43aed50..f98376b3f 100644
--- a/research/provider-neutral-local-observability.md
+++ b/research/provider-neutral-local-observability.md
@@ -37,7 +37,7 @@ events, assigns stable attempt/model-call/tool-call identities, terminalizes ope
error and abort, and invokes the trusted `runInContext` while calling execution exactly once. AI
SDK `callId` values are bridge correlation details, not provider run identities.
-The bridge does not create spans, export records, apply capture policy, or publish durable
+The bridge does not create spans, export records, apply provider policy, or publish durable
eve-native events. Session, turn, compaction, suspension, and canonical step-terminal events are
published by the harness.
@@ -90,9 +90,9 @@ backends can recognize agent invocations and tool calls without eve-specific map
The `agent.*` namespace carries cheap structural attributes only: session/turn/step/attempt
identity, action identity, and agent and framework identity. Standard `gen_ai.*` attributes describe
-the operation, agent, conversation, and tool. Message content, model output, and tool payloads are
-optional capture. The OTel provider owns this mapping; the bridge and hooks contain no span names,
-attributes, or parent contexts.
+the operation, agent, conversation, and tool. Message content, model output, and tool payloads follow
+each provider's audience-aware `tracePolicy`. The OTel provider owns this mapping; the bridge and
+hooks contain no span names, attributes, or parent contexts.
### The session root is a real span