Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add trace capture decisions (#2628)

Chad Hietala1d79217ed446
diff --git a/.changeset/trace-policy-capture-decisions.md b/.changeset/trace-policy-capture-decisions.md
new file mode 100644
index 000000000..043fdbf68
--- /dev/null
+++ b/.changeset/trace-policy-capture-decisions.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Allow `tracePolicy` to explicitly disable emission or select directional content capture while preserving existing boolean policies, lifecycle delivery, and per-delivery audience ceilings.
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index 86db55446..522284d6b 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -8,6 +8,7 @@ import type { InputRequest, InputResponse } from "#shared/input.js";
import type { ChannelAdapter } from "#channel/adapter.js";
import type { AgentLimitsDefinition } from "#shared/agent-definition.js";
import type { JsonObject } from "#shared/json.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
import type { TaskView } from "#tasks/types.js";
export type { ContextAccessor } from "#context/key.js";
@@ -83,6 +84,7 @@ export interface SessionParent {
* free of tracing dependencies.
*/
export interface SessionTraceContext {
+ readonly decision?: InstrumentationDecision;
readonly spanId: string;
readonly traceFlags: number;
readonly traceId: string;
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index be99e46ab..6c4e276a8 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -7,6 +7,7 @@
import type { LanguageModel, ModelMessage, SystemModelMessage } from "ai";
import type { JsonObject } from "#shared/json.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
import type {
ChannelInstrumentationProjection,
ChannelDeliveryMetadata,
@@ -99,6 +100,7 @@ export const ParentSessionKey = new ContextKey<SessionParent>("eve.parentSession
export const ParentTraceContextKey = new ContextKey<SessionTraceContext>("eve.parentTraceContext");
export interface SessionTraceSeed {
+ readonly decision?: InstrumentationDecision;
readonly traceId: string;
readonly spanId: string;
readonly traceFlags: number;
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index 61a953cbb..102169484 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -718,9 +718,14 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
const [, workflowInput] = startMock.mock.calls[0]!;
const serialized = workflowInput[0].serializedContext as Record<string, unknown>;
const seed = serialized["eve.sessionTraceSeed"] as
- | { traceId: string; traceFlags: number }
+ | { decision: unknown; traceId: string; traceFlags: number }
| undefined;
expect(seed).toBeDefined();
+ expect(seed!.decision).toEqual({
+ action: "record",
+ recordInputs: true,
+ recordOutputs: true,
+ });
expect(seed!.traceFlags).toBe(1);
expect(seed!.traceId).toMatch(/^[0-9a-f]{32}$/u);
expect(serialized["eve.otelTraceEnabled"]).toBe(true);
@@ -777,9 +782,10 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
const [, workflowInput] = startMock.mock.calls[0]!;
const serialized = workflowInput[0].serializedContext as Record<string, unknown>;
const seed = serialized["eve.sessionTraceSeed"] as
- | { traceId: string; traceFlags: number }
+ | { decision: unknown; traceId: string; traceFlags: number }
| undefined;
expect(seed).toBeDefined();
+ expect(seed!.decision).toEqual({ action: "drop" });
expect(seed!.traceFlags).toBe(0);
});
@@ -787,7 +793,12 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
installAgentOtelRuntime(new AgentSpanIdGenerator(), () => false);
mockBundleAndRun();
- const parentTrace = { spanId: "c".repeat(16), traceFlags: 1, traceId: "d".repeat(32) };
+ const parentTrace = {
+ decision: { action: "record", recordInputs: true, recordOutputs: false } as const,
+ spanId: "c".repeat(16),
+ traceFlags: 1,
+ traceId: "d".repeat(32),
+ };
startMock.mockResolvedValue({ runId: "child-run" });
getHookByTokenMock.mockResolvedValue({ runId: "child-run" });
await buildRuntime().createSession({
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 2ce6a4c55..fb11419ac 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -16,6 +16,7 @@ import type {
Runtime,
SessionCommand,
SessionCommandResult,
+ SessionTraceContext,
} from "#channel/types.js";
import { serializeContext } from "#context/serialize.js";
import {
@@ -57,7 +58,11 @@ import { sessionCommandHookToken } from "#execution/session-command-token.js";
import { resumeSessionInbox } from "#execution/wire/session-inbox-resume.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
-import { evaluateTracePolicy } from "#tracing/sampled-trace.js";
+import {
+ isSampledTrace,
+ resolveTracePolicy,
+ resolveTracePolicyDecision,
+} from "#tracing/sampled-trace.js";
import { normalizeChannelAudience } from "#shared/channel-audience.js";
const WORKFLOW_ENTRY_NAME = "workflowEntry";
@@ -458,14 +463,14 @@ function allocateSessionTraceSeed(input: {
readonly agentName?: string;
readonly audience: ReturnType<typeof normalizeChannelAudience>;
readonly channelType?: string;
- readonly parentTraceContext?: {
- readonly traceId: string;
- readonly spanId: string;
- readonly traceFlags: number;
- };
+ readonly parentTraceContext?: SessionTraceContext;
}): SessionTraceSeed | undefined {
if (input.parentTraceContext !== undefined) {
+ const decision =
+ input.parentTraceContext.decision ??
+ resolveTracePolicyDecision(isSampledTrace(input.parentTraceContext), input.audience);
return {
+ decision,
spanId: input.parentTraceContext.spanId,
traceFlags: input.parentTraceContext.traceFlags,
traceId: input.parentTraceContext.traceId,
@@ -474,14 +479,15 @@ function allocateSessionTraceSeed(input: {
const instrumentation = getInstrumentationRuntime();
if (instrumentation?.prepareSessionTrace === undefined) return undefined;
if (instrumentation.idGenerator === undefined) return undefined;
- const sampled = evaluateTracePolicy(instrumentation.otelSettings?.tracePolicy, {
+ const decision = resolveTracePolicy(instrumentation.otelSettings?.tracePolicy, {
agentName: input.agentName,
audience: input.audience,
channelType: input.channelType,
});
return {
+ decision,
spanId: instrumentation.idGenerator.allocateSpanId(),
- traceFlags: sampled ? 1 : 0,
+ traceFlags: decision.action === "record" ? 1 : 0,
traceId: instrumentation.idGenerator.generateTraceId(),
};
}
diff --git a/packages/eve/src/harness/channel-delivery-instrumentation.test.ts b/packages/eve/src/harness/channel-delivery-instrumentation.test.ts
index b26da50fe..7405323b0 100644
--- a/packages/eve/src/harness/channel-delivery-instrumentation.test.ts
+++ b/packages/eve/src/harness/channel-delivery-instrumentation.test.ts
@@ -1,7 +1,11 @@
import { describe, expect, it } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
-import { ChannelInstrumentationKey, ParentTraceContextKey } from "#context/keys.js";
+import {
+ ChannelInstrumentationKey,
+ ParentTraceContextKey,
+ SessionTraceSeedKey,
+} from "#context/keys.js";
import { instrumentChannelDelivery } from "#harness/channel-delivery-instrumentation.js";
import {
createInstrumentationHooks,
@@ -79,4 +83,55 @@ describe("channel delivery instrumentation", () => {
);
expect(metadata[0]).toMatchObject({ input: undefined });
});
+
+ it("keeps a private delivery redacted inside a content-enabled session", async () => {
+ const events: InstrumentationEvent[] = [];
+ const hooks = createInstrumentationHooks([
+ {
+ capture: "content",
+ events: {
+ "channel.delivery.started": (event) => {
+ events.push(event);
+ },
+ },
+ name: "content",
+ },
+ ]);
+ const ctx = new ContextContainer();
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:slack",
+ metadata: { audience: "private" },
+ });
+ ctx.set(SessionTraceSeedKey, {
+ decision: { action: "record", recordInputs: true, recordOutputs: true },
+ spanId: "2".repeat(16),
+ traceFlags: 1,
+ traceId: "1".repeat(32),
+ });
+
+ await contextStorage.run(ctx, () =>
+ instrumentChannelDelivery({
+ ctx,
+ delivery: {
+ deliveryMetadata: [
+ {
+ channelKind: "channel:slack",
+ channelName: "slack",
+ deliveryId: "delivery-1",
+ payloadIndex: 0,
+ },
+ ],
+ kind: "deliver",
+ payloads: [{ message: "secret" }],
+ },
+ hooks,
+ rootSessionId: "session-1",
+ sequence: 0,
+ sessionId: "session-1",
+ turnId: "turn_0",
+ }),
+ );
+
+ expect(events[0]).toMatchObject({ input: undefined });
+ });
});
diff --git a/packages/eve/src/harness/channel-delivery-instrumentation.ts b/packages/eve/src/harness/channel-delivery-instrumentation.ts
index 46d256c5e..2b7b24197 100644
--- a/packages/eve/src/harness/channel-delivery-instrumentation.ts
+++ b/packages/eve/src/harness/channel-delivery-instrumentation.ts
@@ -13,7 +13,10 @@ import type {
InstrumentationHooks,
} from "#harness/instrumentation/lifecycle.js";
import { channelDeliveryIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
-import { instrumentationHooksForAudience } from "#harness/instrumentation/content-policy.js";
+import {
+ instrumentationHooksForAudience,
+ instrumentationHooksForDecision,
+} from "#harness/instrumentation/content-policy.js";
import { normalizeChannelAudience } from "#shared/channel-audience.js";
interface ChannelDeliveryStartInstrumentation {
@@ -51,7 +54,8 @@ export async function instrumentChannelDelivery(
const type =
`channel.delivery.${input.outcome}` as InstrumentationChannelDeliveryTerminalEvent["type"];
for (const item of active) {
- const hooks = instrumentationHooksForAudience(
+ const hooks = hooksForContext(
+ input.ctx,
input.hooks,
normalizeChannelAudience(item.delivery.channelAudience),
);
@@ -79,7 +83,7 @@ export async function instrumentChannelDelivery(
const channelAudience = normalizeChannelAudience(
input.ctx.get(ChannelInstrumentationKey)?.metadata.audience,
);
- const hooks = instrumentationHooksForAudience(input.hooks, channelAudience);
+ const hooks = hooksForContext(input.ctx, input.hooks, channelAudience);
for (const metadata of input.delivery.deliveryMetadata) {
const payload = input.delivery.payloads[metadata.payloadIndex];
const delivery = {
@@ -116,6 +120,17 @@ export async function instrumentChannelDelivery(
if (active.length > 0) input.ctx.set(ActiveChannelDeliveriesKey, active);
}
+function hooksForContext(
+ ctx: AlsContext,
+ hooks: InstrumentationHooks,
+ audience: ReturnType<typeof normalizeChannelAudience>,
+): InstrumentationHooks | undefined {
+ const decision = ctx.get(SessionTraceSeedKey)?.decision;
+ return decision === undefined
+ ? instrumentationHooksForAudience(hooks, audience)
+ : instrumentationHooksForDecision(hooks, decision, audience);
+}
+
function projectDeliveryInput(payload: DeliverPayload) {
const projected: {
context?: DeliverPayload["context"];
diff --git a/packages/eve/src/harness/instrumentation/content-policy.test.ts b/packages/eve/src/harness/instrumentation/content-policy.test.ts
index 5275093a0..42f30e46f 100644
--- a/packages/eve/src/harness/instrumentation/content-policy.test.ts
+++ b/packages/eve/src/harness/instrumentation/content-policy.test.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import {
instrumentationHooksForAudience,
+ instrumentationHooksForDecision,
shouldCaptureInstrumentationContent,
} from "#harness/instrumentation/content-policy.js";
import type { InstrumentationHooks } from "#harness/instrumentation/lifecycle.js";
@@ -49,4 +50,80 @@ describe("instrumentation content policy", () => {
expect(restricted?.capturesContent).toBe(false);
expect(publish).toHaveBeenCalledWith(expect.objectContaining({ input: undefined }));
});
+
+ it("applies directional trace capture before publishing", async () => {
+ const publish = vi.fn();
+ const hooks: InstrumentationHooks = { capturesContent: true, publish };
+ const restricted = instrumentationHooksForDecision(
+ hooks,
+ {
+ action: "record",
+ recordInputs: true,
+ recordOutputs: false,
+ },
+ "public",
+ );
+
+ await restricted?.publish({
+ callId: "call-1",
+ idempotencyKey: "action-1",
+ input: { secret: "input" },
+ kind: "tool-call",
+ name: "lookup",
+ scope: {
+ attemptId: "attempt-1",
+ attemptIndex: 0,
+ sessionId: "session-1",
+ stepIndex: 0,
+ turnId: "turn-1",
+ },
+ type: "action.started",
+ });
+ await restricted?.publish({
+ idempotencyKey: "action-1",
+ outcome: "completed",
+ output: { output: { secret: "output" }, type: "result" },
+ scope: {
+ attemptId: "attempt-1",
+ attemptIndex: 0,
+ sessionId: "session-1",
+ stepIndex: 0,
+ turnId: "turn-1",
+ },
+ type: "action.completed",
+ });
+
+ expect(restricted?.capturesContent).toBe(true);
+ expect(publish.mock.calls[0]?.[0]).toEqual(
+ expect.objectContaining({ input: { secret: "input" } }),
+ );
+ expect(publish.mock.calls[1]?.[0]).toEqual(
+ expect.objectContaining({ output: { type: "result" } }),
+ );
+ });
+
+ it("keeps lifecycle delivery when the trace decision drops", async () => {
+ const publish = vi.fn();
+ const hooks: InstrumentationHooks = { capturesContent: true, publish };
+ const restricted = instrumentationHooksForDecision(hooks, { action: "drop" }, "private");
+
+ await restricted?.publish({
+ callId: "call-1",
+ idempotencyKey: "action-1",
+ input: { secret: "value" },
+ kind: "tool-call",
+ name: "lookup",
+ scope: {
+ attemptId: "attempt-1",
+ attemptIndex: 0,
+ sessionId: "session-1",
+ stepIndex: 0,
+ turnId: "turn-1",
+ },
+ type: "action.started",
+ });
+
+ expect(restricted).toBeDefined();
+ expect(publish).toHaveBeenCalledWith(expect.objectContaining({ input: undefined }));
+ });
});
diff --git a/packages/eve/src/harness/instrumentation/content-policy.ts b/packages/eve/src/harness/instrumentation/content-policy.ts
index be9c3f988..346535306 100644
--- a/packages/eve/src/harness/instrumentation/content-policy.ts
+++ b/packages/eve/src/harness/instrumentation/content-policy.ts
@@ -1,12 +1,35 @@
import type { InstrumentationHooks } from "#harness/instrumentation/lifecycle.js";
-import { withoutInstrumentationContent } from "#harness/instrumentation/content.js";
-import { isEveDevEnvironment } from "#internal/application/dev-environment.js";
+import {
+ withInstrumentationDecision,
+ withoutInstrumentationContent,
+} from "#harness/instrumentation/content.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
+import {
+ applyAudienceCeiling,
+ shouldCaptureInstrumentationContent,
+} from "#shared/instrumentation-content.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
+export { shouldCaptureInstrumentationContent } from "#shared/instrumentation-content.js";
-/** Hosted instrumentation records conversation content only for known-public channels. */
-export function shouldCaptureInstrumentationContent(audience: ChannelAudience): boolean {
- if (audience === "public") return true;
- return audience === "unknown" && isEveDevEnvironment();
+export function instrumentationHooksForDecision(
+ hooks: InstrumentationHooks | undefined,
+ decision: InstrumentationDecision,
+ audience: ChannelAudience,
+): InstrumentationHooks | undefined {
+ if (decision.action === "drop") return instrumentationHooksForAudience(hooks, audience);
+ const effective = applyAudienceCeiling(decision, audience);
+ if (
+ effective.action === "drop" ||
+ hooks === undefined ||
+ !hooks.capturesContent ||
+ (effective.recordInputs && effective.recordOutputs)
+ ) {
+ return hooks;
+ }
+ return {
+ capturesContent: effective.recordInputs || effective.recordOutputs,
+ publish: (event) => hooks.publish(withInstrumentationDecision(event, effective)),
+ };
}
/** Applies the audience ceiling before any content-capable provider sees an event. */
diff --git a/packages/eve/src/harness/instrumentation/content.test.ts b/packages/eve/src/harness/instrumentation/content.test.ts
new file mode 100644
index 000000000..da5cb44b9
--- /dev/null
+++ b/packages/eve/src/harness/instrumentation/content.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+
+import { withInstrumentationDecision } from "#harness/instrumentation/content.js";
+import type {
+ InstrumentationInputRequestedEvent,
+ InstrumentationInputResolvedEvent,
+} from "#harness/instrumentation/lifecycle.js";
+
+const scope = {
+ attemptId: "attempt-1",
+ attemptIndex: 0,
+ sessionId: "session-1",
+ stepIndex: 0,
+ turnId: "turn-1",
+};
+
+describe("withInstrumentationDecision", () => {
+ it("treats input requests as outputs and user responses as inputs", () => {
+ const requested = withInstrumentationDecision(
+ {
+ action: { callId: "call-1", name: "approve" },
+ idempotencyKey: "request-1",
+ kind: "tool-approval",
+ request: { prompt: "Approve?" },
+ requestId: "request-1",
+ scope,
+ type: "input.requested",
+ } satisfies InstrumentationInputRequestedEvent,
+ { action: "record", recordInputs: true, recordOutputs: false },
+ );
+ const resolved = withInstrumentationDecision(
+ {
+ error: new Error("failed"),
+ idempotencyKey: "request-1",
+ kind: "tool-approval",
+ outcome: "approved",
+ requestId: "request-1",
+ response: { text: "yes" },
+ scope,
+ type: "input.resolved",
+ } satisfies InstrumentationInputResolvedEvent,
+ { action: "record", recordInputs: true, recordOutputs: false },
+ );
+
+ expect(requested).toEqual(expect.objectContaining({ request: undefined }));
+ expect(resolved).toEqual(
+ expect.objectContaining({ error: undefined, response: { text: "yes" } }),
+ );
+ });
+
+ it("keeps output-side requests and errors while removing user responses", () => {
+ const requested = {
+ action: { callId: "call-1", name: "approve" },
+ idempotencyKey: "request-1",
+ kind: "tool-approval",
+ request: { prompt: "Approve?" },
+ requestId: "request-1",
+ scope,
+ type: "input.requested",
+ } satisfies InstrumentationInputRequestedEvent;
+ const error = new Error("failed");
+ const resolved = {
+ error,
+ idempotencyKey: "request-1",
+ kind: "tool-approval",
+ outcome: "failed",
+ requestId: "request-1",
+ response: { text: "no" },
+ scope,
+ type: "input.resolved",
+ } satisfies InstrumentationInputResolvedEvent;
+ const decision = { action: "record", recordInputs: false, recordOutputs: true } as const;
+
+ expect(withInstrumentationDecision(requested, decision)).toBe(requested);
+ expect(withInstrumentationDecision(resolved, decision)).toEqual(
+ expect.objectContaining({ error, response: undefined }),
+ );
+ });
+
+ it("reduces provider metadata to structural output when outputs are disabled", () => {
+ const projected = withInstrumentationDecision(
+ {
+ idempotencyKey: "attempt-1",
+ providerMetadata: {
+ gateway: { cost: "0.01", generationId: "gen-1", secret: "hidden" },
+ secret: "hidden",
+ },
+ scope,
+ type: "step.attempt.metadata",
+ },
+ { action: "record", recordInputs: true, recordOutputs: false },
+ );
+
+ expect(projected).toEqual(
+ expect.objectContaining({
+ providerMetadata: { gateway: { cost: "0.01", generationId: "gen-1" } },
+ }),
+ );
+ });
+});
diff --git a/packages/eve/src/harness/instrumentation/content.ts b/packages/eve/src/harness/instrumentation/content.ts
index 89c713836..284fedd29 100644
--- a/packages/eve/src/harness/instrumentation/content.ts
+++ b/packages/eve/src/harness/instrumentation/content.ts
@@ -1,31 +1,62 @@
import type { InstrumentationEvent } from "#harness/instrumentation/lifecycle.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
/** Returns an immutable event projection with conversation content removed. */
export function withoutInstrumentationContent(event: InstrumentationEvent): InstrumentationEvent {
+ return withInstrumentationDecision(event, {
+ action: "record",
+ recordInputs: false,
+ recordOutputs: false,
+ });
+}
+
+/**
+ * Projects lifecycle content by direction.
+ *
+ * Inputs are data entering the agent: delivery/action/tool/model starts and a
+ * resolved user's response. Outputs are data produced by the agent: requests
+ * for user input, action/tool/model terminals, provider metadata, and errors.
+ */
+export function withInstrumentationDecision(
+ event: InstrumentationEvent,
+ decision: Extract<InstrumentationDecision, { action: "record" }>,
+): InstrumentationEvent {
switch (event.type) {
case "channel.delivery.started":
- return Object.freeze({ ...event, input: undefined });
+ return decision.recordInputs ? event : Object.freeze({ ...event, input: undefined });
case "action.started":
- return Object.freeze({ ...event, input: undefined });
+ return decision.recordInputs ? event : Object.freeze({ ...event, input: undefined });
case "action.completed":
- return Object.freeze({ ...event, output: Object.freeze({ type: event.output.type }) });
+ return decision.recordOutputs
+ ? event
+ : Object.freeze({ ...event, output: Object.freeze({ type: event.output.type }) });
case "input.requested":
- return Object.freeze({ ...event, request: undefined });
+ return decision.recordOutputs ? event : Object.freeze({ ...event, request: undefined });
case "input.resolved":
- return Object.freeze({ ...event, error: undefined, response: undefined });
+ return decision.recordInputs && decision.recordOutputs
+ ? event
+ : Object.freeze({
+ ...event,
+ error: decision.recordOutputs ? event.error : undefined,
+ response: decision.recordInputs ? event.response : undefined,
+ });
case "tool.call.started":
- return Object.freeze({ ...event, input: undefined });
+ return decision.recordInputs ? event : Object.freeze({ ...event, input: undefined });
case "tool.call.completed":
- return Object.freeze({ ...event, output: Object.freeze({ type: event.output.type }) });
+ return decision.recordOutputs
+ ? event
+ : Object.freeze({ ...event, output: Object.freeze({ type: event.output.type }) });
case "model.call.started":
- return Object.freeze({ ...event, input: undefined });
+ return decision.recordInputs ? event : Object.freeze({ ...event, input: undefined });
case "model.call.completed":
- return Object.freeze({ ...event, content: undefined });
+ return decision.recordOutputs ? event : Object.freeze({ ...event, content: undefined });
case "step.attempt.metadata":
- return Object.freeze({
- ...event,
- providerMetadata: structuralProviderMetadata(event.providerMetadata),
- });
+ return decision.recordOutputs
+ ? event
+ : Object.freeze({
+ ...event,
+ providerMetadata: structuralProviderMetadata(event.providerMetadata),
+ });
case "action.failed":
case "model.call.failed":
case "session.failed":
@@ -33,7 +64,7 @@ export function withoutInstrumentationContent(event: InstrumentationEvent): Inst
case "tool.call.failed":
case "turn.failed":
case "channel.delivery.failed":
- return Object.freeze({ ...event, error: undefined });
+ return decision.recordOutputs ? event : Object.freeze({ ...event, error: undefined });
default:
return event;
}
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index aadf06330..e3e5393d0 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -10842,7 +10842,7 @@ describe("createToolLoopHarness", () => {
toolResults: [{ toolCallId: "call-1", toolName: "add", output: "42" }],
});
- declareTelemetry({});
+ declareTelemetry({ tracePolicy: () => true });
const step1Config = createTestConfig("conversation");
const step1 = createToolLoopHarness(step1Config);
const result1 = await step1(createTestSession(), { message: "add stuff" });
@@ -10916,7 +10916,138 @@ describe("createToolLoopHarness", () => {
expect(mockCreateAiSdkHookBridge).not.toHaveBeenCalled();
});
+ it("keeps lifecycle providers active when the trace policy rejects the trace", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ });
+ declareTelemetry({ tracePolicy: () => false });
+ const attemptCompleted = vi.fn();
+ const hooks = createInstrumentationHooks([
+ { events: { "step.attempt.completed": attemptCompleted }, name: "analytics" },
+ ]);
+ const runStep = createToolLoopHarness(
+ createTestConfig("conversation", undefined, {
+ instrumentation: { hooks, runInContext: (_operation, execute) => execute() },
+ }),
+ );
+
+ await runStep(createTestSession(), { message: "private" });
+
+ expect(attemptCompleted).toHaveBeenCalledOnce();
+ const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
+ telemetry?: unknown;
+ };
+ expect(agentCall.telemetry).toBeUndefined();
+ });
+
+ it.each([
+ [false, false],
+ [true, false],
+ [false, true],
+ [true, true],
+ ] as const)("applies the explicit %s/%s capture decision", async (inputs, outputs) => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ });
+ declareTelemetry({
+ recordInputs: true,
+ recordOutputs: true,
+ tracePolicy: () => ({
+ emit: true,
+ recordInputs: inputs,
+ recordOutputs: outputs,
+ }),
+ });
+ const runStep = createToolLoopHarness(createTestConfig());
+ const ctx = new ContextContainer();
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:public",
+ metadata: { audience: "public" },
+ });
+
+ await contextStorage.run(ctx, () => runStep(createTestSession(), { message: "hello" }));
+
+ const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
+ telemetry?: { recordInputs?: boolean; recordOutputs?: boolean };
+ };
+ expect(agentCall.telemetry).toMatchObject({
+ recordInputs: inputs,
+ recordOutputs: outputs,
+ });
+ });
+
+ it("lets destination capture settings narrow an explicit content decision", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ });
+ declareTelemetry({
+ recordInputs: false,
+ recordOutputs: true,
+ tracePolicy: () => ({
+ emit: true,
+ recordInputs: true,
+ recordOutputs: true,
+ }),
+ });
+ const runStep = createToolLoopHarness(createTestConfig());
+ const ctx = new ContextContainer();
+ ctx.set(ChannelInstrumentationKey, {
+ kind: "channel:public",
+ metadata: { audience: "public" },
+ });
+
+ await contextStorage.run(ctx, () => runStep(createTestSession(), { message: "hello" }));
+
+ const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
+ telemetry?: { recordInputs?: boolean; recordOutputs?: boolean };
+ };
+ expect(agentCall.telemetry).toMatchObject({
+ recordInputs: false,
+ recordOutputs: true,
+ });
+ });
+
it("reuses the persisted rejected trace decision", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ });
+ const tracePolicy = vi.fn(() => true);
+ declareTelemetry({ recordInputs: true, recordOutputs: true, tracePolicy });
+ const runStep = createToolLoopHarness(createTestConfig());
+ const ctx = new ContextContainer();
+ ctx.set(SessionTraceSeedKey, {
+ decision: { action: "drop" },
+ spanId: "1".repeat(16),
+ traceFlags: 0,
+ traceId: "2".repeat(32),
+ });
+
+ await contextStorage.run(ctx, () => runStep(createTestSession(), { message: "private" }));
+
+ const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {
+ telemetry?: unknown;
+ };
+ expect(agentCall.telemetry).toBeUndefined();
+ expect(tracePolicy).not.toHaveBeenCalled();
+ });
+
+ it("supports a persisted legacy seed without a decision", async () => {
setupMockAgent({
finishReason: "stop",
response: { messages: [{ content: "Hello!", role: "assistant" }] },
@@ -10961,7 +11092,7 @@ describe("createToolLoopHarness", () => {
toolResults: [],
});
const events: UnstampedMessageStreamEvent[] = [];
- declareTelemetry({});
+ declareTelemetry({ tracePolicy: () => true });
const runStep = createToolLoopHarness(
createTestConfig("conversation", async (event) => {
events.push(event);
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index f18d3e20c..2c757a139 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -154,6 +154,7 @@ import {
} from "#harness/approval-delivery-coordinator.js";
import { buildTelemetryRuntimeContext } from "#harness/instrumentation/runtime-context.js";
import {
+ instrumentationHooksForDecision,
instrumentationHooksForAudience,
shouldCaptureInstrumentationContent,
} from "#harness/instrumentation/content-policy.js";
@@ -186,8 +187,14 @@ import {
} from "#harness/stale-input-responses.js";
import { getInstrumentationConfig } from "#harness/instrumentation/config.js";
import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
+import { applyAudienceCeiling } from "#shared/instrumentation-content.js";
import type { OtelHarnessSettings } from "#tracing/otel-declaration.js";
-import { evaluateTracePolicy, isSampledTrace } from "#tracing/sampled-trace.js";
+import {
+ isSampledTrace,
+ resolveTracePolicy,
+ resolveTracePolicyDecision,
+} from "#tracing/sampled-trace.js";
import {
normalizeModelMessages,
normalizeUserContent,
@@ -339,14 +346,14 @@ const MODEL_CALL_MAX_ATTEMPTS = 3;
const MODEL_CALL_RETRY_BASE_DELAY_MS = 500;
function enrichTelemetry(
- enabled: boolean,
+ decision: InstrumentationDecision | undefined,
settings: OtelHarnessSettings | undefined,
channelAudience: ChannelAudience,
agentName: string | undefined,
runtimeContext?: Readonly<Record<string, unknown>>,
bridgeIntegration?: Telemetry,
): TelemetryOptions | undefined {
- if (!enabled) {
+ if (decision?.action === "drop") {
return undefined;
}
if (settings === undefined && bridgeIntegration === undefined) {
@@ -360,6 +367,8 @@ function enrichTelemetry(
includeRuntimeContext[key] = true;
}
+ const effectiveDecision =
+ decision === undefined ? undefined : applyAudienceCeiling(decision, channelAudience);
return {
functionId: settings?.functionId ?? agentName,
includeRuntimeContext,
@@ -371,9 +380,15 @@ function enrichTelemetry(
: [bridgeIntegration, ...getRegisteredTelemetryIntegrations()],
isEnabled: true,
recordInputs:
- shouldCaptureInstrumentationContent(channelAudience) && (settings?.recordInputs ?? false),
+ (effectiveDecision?.action === "record"
+ ? effectiveDecision.recordInputs
+ : shouldCaptureInstrumentationContent(channelAudience)) &&
+ (settings?.recordInputs ?? false),
recordOutputs:
- shouldCaptureInstrumentationContent(channelAudience) && (settings?.recordOutputs ?? false),
+ (effectiveDecision?.action === "record"
+ ? effectiveDecision.recordOutputs
+ : shouldCaptureInstrumentationContent(channelAudience)) &&
+ (settings?.recordOutputs ?? false),
};
}
@@ -619,13 +634,13 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
initialSession: Readonly<Parameters<StepFn>[0]>,
input?: StepInput,
): Promise<StepResult> {
- const aiSdkTelemetryEnabled = shouldEnableAiSdkTelemetry(otelSettings, agentName);
+ const instrumentationDecision = resolveStepInstrumentationDecision(otelSettings, agentName);
// --- Turn span lifecycle ------------------------------------------------
// First step of a turn: open a new parent span. Continuation steps
// restore the parent from session state via resolveStepOtelContext.
let turnSpan: Span | undefined;
- if (tracer && hasStepInput(input)) {
+ if (tracer && instrumentationDecision?.action !== "drop" && hasStepInput(input)) {
const functionId = otelSettings?.functionId ?? agentName;
const attributes: Record<string, string> = {
"eve.version": eveVersion,
@@ -642,7 +657,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// OTel context so AI SDK spans nest as children.
const parentContext = resolveStepOtelContext(tracer, turnSpan, initialSession);
const executeStep = () =>
- executeStepBody(initialSession, input, turnSpan, aiSdkTelemetryEnabled);
+ executeStepBody(initialSession, input, turnSpan, instrumentationDecision);
try {
if (parentContext) {
@@ -658,7 +673,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
initialSession: Readonly<Parameters<StepFn>[0]>,
input?: StepInput,
turnSpan?: Span,
- aiSdkTelemetryEnabled = true,
+ instrumentationDecision?: InstrumentationDecision,
): Promise<StepResult> {
let session = initialSession;
const prepareHistory = createHistoryViewPreparer({
@@ -681,10 +696,14 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const store = contextStorage.getStore();
const channelInstrumentation = store?.get(ChannelInstrumentationKey);
const channelAudience = normalizeChannelAudience(channelInstrumentation?.metadata.audience);
- const instrumentationHooks = instrumentationHooksForAudience(
- config.instrumentation?.hooks,
- channelAudience,
- );
+ const instrumentationHooks =
+ instrumentationDecision === undefined
+ ? instrumentationHooksForAudience(config.instrumentation?.hooks, channelAudience)
+ : instrumentationHooksForDecision(
+ config.instrumentation?.hooks,
+ instrumentationDecision,
+ channelAudience,
+ );
const parent = store?.get(ParentSessionKey);
const channel = store?.get(ChannelKey);
const callback = store?.get(SessionCallbackKey);
@@ -818,7 +837,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
runtimeIdentity: config.runtimeIdentity,
session,
telemetry:
- enrichTelemetry(aiSdkTelemetryEnabled, otelSettings, channelAudience, agentName) ??
+ enrichTelemetry(instrumentationDecision, otelSettings, channelAudience, agentName) ??
undefined,
});
@@ -1329,7 +1348,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
runtimeIdentity: config.runtimeIdentity,
session,
telemetry:
- enrichTelemetry(aiSdkTelemetryEnabled, otelSettings, channelAudience, agentName) ??
+ enrichTelemetry(instrumentationDecision, otelSettings, channelAudience, agentName) ??
undefined,
});
session = compaction.session;
@@ -1581,7 +1600,9 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
};
activeAttemptScope = attemptScope;
const bridgeIntegration =
- !aiSdkTelemetryEnabled || attemptScope === undefined || instrumentationHooks === undefined
+ instrumentationDecision?.action === "drop" ||
+ attemptScope === undefined ||
+ instrumentationHooks === undefined
? undefined
: createAiSdkHookBridge(
attemptScope,
@@ -1638,7 +1659,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
runtimeContext: telemetryRuntimeContext,
stopWhen: isStepCount(1),
telemetry: enrichTelemetry(
- aiSdkTelemetryEnabled,
+ instrumentationDecision,
otelSettings,
channelAudience,
agentName,
@@ -2067,20 +2088,24 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
return runStep;
}
-function shouldEnableAiSdkTelemetry(
+function resolveStepInstrumentationDecision(
settings: OtelHarnessSettings | undefined,
agentName: string | undefined,
-): boolean {
- if (settings === undefined) return true;
+): InstrumentationDecision | undefined {
+ if (settings === undefined) return undefined;
const store = contextStorage.getStore();
const traceSeed = store?.get(SessionTraceSeedKey);
- if (traceSeed !== undefined) return isSampledTrace(traceSeed);
+ if (traceSeed?.decision !== undefined) return traceSeed.decision;
const channel = store?.get(ChannelInstrumentationKey);
- return evaluateTracePolicy(settings.tracePolicy, {
+ const audience = normalizeChannelAudience(channel?.metadata.audience);
+ if (traceSeed !== undefined) {
+ return resolveTracePolicyDecision(isSampledTrace(traceSeed), audience);
+ }
+ return resolveTracePolicy(settings.tracePolicy, {
agentName,
- audience: normalizeChannelAudience(channel?.metadata.audience),
+ audience,
channelType: channel?.channelType,
});
}
diff --git a/packages/eve/src/public/instrumentation/otel.ts b/packages/eve/src/public/instrumentation/otel.ts
index 15c43e72b..4c5a282a2 100644
--- a/packages/eve/src/public/instrumentation/otel.ts
+++ b/packages/eve/src/public/instrumentation/otel.ts
@@ -38,6 +38,7 @@ export {
type SpanExportPredicate,
type TraceCaptureContext,
type TraceCapturePolicy,
+ type TracePolicyDecision,
} from "#tracing/otel-declaration.js";
export type { SpanExporter, SpanProcessor } from "#compiled/@vercel/otel/index.js";
diff --git a/packages/eve/src/shared/instrumentation-content.ts b/packages/eve/src/shared/instrumentation-content.ts
new file mode 100644
index 000000000..b500f6e5e
--- /dev/null
+++ b/packages/eve/src/shared/instrumentation-content.ts
@@ -0,0 +1,20 @@
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
+import { isEveDevEnvironment } from "#internal/application/dev-environment.js";
+
+/** Hosted instrumentation records conversation content only for known-public channels. */
+export function shouldCaptureInstrumentationContent(audience: ChannelAudience): boolean {
+ if (audience === "public") return true;
+ return audience === "unknown" && isEveDevEnvironment();
+}
+
+/** Per-delivery audience is a hard ceiling over the session-level trace decision. */
+export function applyAudienceCeiling(
+ decision: InstrumentationDecision,
+ audience: ChannelAudience,
+): InstrumentationDecision {
+ if (decision.action === "drop" || shouldCaptureInstrumentationContent(audience)) {
+ return decision;
+ }
+ return { action: "record", recordInputs: false, recordOutputs: false };
+}
diff --git a/packages/eve/src/shared/instrumentation-decision.ts b/packages/eve/src/shared/instrumentation-decision.ts
new file mode 100644
index 000000000..0b2520498
--- /dev/null
+++ b/packages/eve/src/shared/instrumentation-decision.ts
@@ -0,0 +1,9 @@
+export type InstrumentationDecision =
+ | { readonly action: "drop" }
+ | {
+ readonly action: "record";
+ readonly recordInputs: boolean;
+ readonly recordOutputs: boolean;
+ };
+
+export const DROP_INSTRUMENTATION: InstrumentationDecision = { action: "drop" };
diff --git a/packages/eve/src/tracing/agent-trace-context-store.test.ts b/packages/eve/src/tracing/agent-trace-context-store.test.ts
index 0a0f870a5..48dd467dd 100644
--- a/packages/eve/src/tracing/agent-trace-context-store.test.ts
+++ b/packages/eve/src/tracing/agent-trace-context-store.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
+import { SessionTraceSeedKey } from "#context/keys.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import {
ContextAgentTraceStateStore,
@@ -95,6 +96,12 @@ describe("readSessionTraceContext", () => {
it("reads one session's trace context out of a serialized context", async () => {
const context = new ContextContainer();
await contextStorage.run(context, () => {
+ context.set(SessionTraceSeedKey, {
+ decision: { action: "record", recordInputs: true, recordOutputs: false },
+ spanId: "2".repeat(16),
+ traceFlags: 1,
+ traceId: "1".repeat(32),
+ });
new ContextAgentTraceStateStore().setSession("session-1", {
context: spanContext("1", "2"),
rootSessionId: "session-1",
@@ -102,7 +109,10 @@ describe("readSessionTraceContext", () => {
});
const serialized = await serializeContext(context);
- expect(readSessionTraceContext(serialized, "session-1")).toEqual(spanContext("1", "2"));
+ expect(readSessionTraceContext(serialized, "session-1")).toEqual({
+ ...spanContext("1", "2"),
+ decision: { action: "record", recordInputs: true, recordOutputs: false },
+ });
expect(readSessionTraceContext(serialized, "session-2")).toBeUndefined();
expect(readSessionTraceContext({}, "session-1")).toBeUndefined();
});
@@ -112,6 +122,12 @@ describe("readActionTraceContext", () => {
it("reads the invoking action span out of a serialized context", async () => {
const context = new ContextContainer();
await contextStorage.run(context, () => {
+ context.set(SessionTraceSeedKey, {
+ decision: { action: "record", recordInputs: true, recordOutputs: false },
+ spanId: "2".repeat(16),
+ traceFlags: 1,
+ traceId: "1".repeat(32),
+ });
new ContextAgentTraceStateStore().setAction("action-1", {
attemptIndex: 0,
callId: "call-1",
@@ -129,6 +145,7 @@ describe("readActionTraceContext", () => {
const serialized = await serializeContext(context);
expect(readActionTraceContext(serialized, "session-1", "turn-1", "call-1")).toEqual({
+ decision: { action: "record", recordInputs: true, recordOutputs: false },
isRemote: false,
spanId: "3".repeat(16),
traceFlags: 1,
diff --git a/packages/eve/src/tracing/agent-trace-context-store.ts b/packages/eve/src/tracing/agent-trace-context-store.ts
index 8ef719627..9ff9068e5 100644
--- a/packages/eve/src/tracing/agent-trace-context-store.ts
+++ b/packages/eve/src/tracing/agent-trace-context-store.ts
@@ -1,7 +1,9 @@
import type { SpanContext } from "#compiled/@opentelemetry/api/index.js";
+import type { SessionTraceContext } from "#channel/types.js";
import { contextStorage, loadContext } from "#context/container.js";
import { ContextKey } from "#context/key.js";
+import { SessionTraceSeedKey, type SessionTraceSeed } from "#context/keys.js";
import type {
AgentActionTraceState,
AgentSessionTraceState,
@@ -42,10 +44,11 @@ export function preserveSerializedAgentTraceState(
export function readSessionTraceContext(
serializedContext: Readonly<Record<string, unknown>>,
sessionId: string,
-): SpanContext | undefined {
+): SessionTraceContext | undefined {
const raw = serializedContext[AgentTraceContextKey.name];
if (raw === undefined) return undefined;
- return deserializeState(raw).sessions[sessionId]?.context;
+ const context = deserializeState(raw).sessions[sessionId]?.context;
+ return context === undefined ? undefined : withTraceDecision(serializedContext, context);
}
/** Reads the durable action span that should parent a dispatched child agent. */
@@ -54,19 +57,27 @@ export function readActionTraceContext(
sessionId: string,
turnId: string,
callId: string,
-): SpanContext | undefined {
+): SessionTraceContext | undefined {
const raw = serializedContext[AgentTraceContextKey.name];
if (raw === undefined) return undefined;
const action = Object.values(deserializeState(raw).actions).find(
(state) => state.sessionId === sessionId && state.turnId === turnId && state.callId === callId,
);
if (action === undefined) return undefined;
- return {
+ return withTraceDecision(serializedContext, {
isRemote: false,
spanId: action.spanId,
traceFlags: action.parent.traceFlags,
traceId: action.parent.traceId,
- };
+ });
+}
+
+function withTraceDecision(
+ serializedContext: Readonly<Record<string, unknown>>,
+ context: SpanContext,
+): SessionTraceContext {
+ const seed = serializedContext[SessionTraceSeedKey.name] as SessionTraceSeed | undefined;
+ return seed?.decision === undefined ? context : { ...context, decision: seed.decision };
}
/** Durable trace state backed by eve's serialized Workflow context. */
diff --git a/packages/eve/src/tracing/otel-declaration.ts b/packages/eve/src/tracing/otel-declaration.ts
index a549e8ce5..f2effad03 100644
--- a/packages/eve/src/tracing/otel-declaration.ts
+++ b/packages/eve/src/tracing/otel-declaration.ts
@@ -60,8 +60,12 @@ export interface OtelOptions {
*/
readonly traceChannelRequests?: boolean;
/**
- * Process-wide head gate for an agent session trace. Defaults to retaining
- * only public conversations. A thrown error rejects the trace.
+ * Process-wide trace and content decision. Boolean returns preserve the
+ * existing audience-aware behavior; explicit decisions can disable emission
+ * or select input and output capture independently. Defaults to retaining
+ * public conversations with content. The result is a capture ceiling:
+ * per-delivery audience and destination settings can only narrow it. A thrown
+ * error rejects trace production without silencing lifecycle providers.
*/
readonly tracePolicy?: TraceCapturePolicy;
/**
@@ -110,7 +114,15 @@ export interface TraceCaptureContext {
readonly channelType?: string;
}
-export type TraceCapturePolicy = (trace: TraceCaptureContext) => boolean;
+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. */
export interface OtelIntegrationOptions extends ContentOptions {
diff --git a/packages/eve/src/tracing/sampled-trace.test.ts b/packages/eve/src/tracing/sampled-trace.test.ts
new file mode 100644
index 000000000..3b59b5c26
--- /dev/null
+++ b/packages/eve/src/tracing/sampled-trace.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveTracePolicy, resolveTracePolicyDecision } from "#tracing/sampled-trace.js";
+
+describe("resolveTracePolicyDecision", () => {
+ afterEach(() => vi.unstubAllEnvs());
+
+ it.each([
+ [{ emit: false }, { action: "drop" }],
+ [
+ { emit: true, recordInputs: false, recordOutputs: false },
+ { action: "record", recordInputs: false, recordOutputs: false },
+ ],
+ [
+ { emit: true, recordInputs: true, recordOutputs: false },
+ { action: "record", recordInputs: true, recordOutputs: false },
+ ],
+ [
+ { emit: true, recordInputs: false, recordOutputs: true },
+ { action: "record", recordInputs: false, recordOutputs: true },
+ ],
+ [
+ { emit: true, recordInputs: true, recordOutputs: true },
+ { action: "record", recordInputs: true, recordOutputs: true },
+ ],
+ ] as const)("normalizes the explicit $decision.emit decision", (decision, expected) => {
+ expect(resolveTracePolicyDecision(decision, "private")).toEqual(expected);
+ });
+
+ it("maps false to the legacy drop behavior", () => {
+ expect(resolveTracePolicyDecision(false, "public")).toEqual({ action: "drop" });
+ });
+
+ it.each([
+ ["public", true],
+ ["private", false],
+ ["unknown", false],
+ ] as const)("maps true through the hosted %s audience ceiling", (audience, content) => {
+ expect(resolveTracePolicyDecision(true, audience)).toEqual({
+ action: "record",
+ recordInputs: content,
+ recordOutputs: content,
+ });
+ });
+
+ it("preserves unknown local content for a legacy true decision", () => {
+ vi.stubEnv("EVE_DEV", "1");
+ expect(resolveTracePolicyDecision(true, "unknown")).toEqual({
+ action: "record",
+ recordInputs: true,
+ recordOutputs: true,
+ });
+ });
+
+ it("fails closed when the policy throws", () => {
+ expect(
+ resolveTracePolicy(
+ () => {
+ throw new Error("boom");
+ },
+ { audience: "public" },
+ ),
+ ).toEqual({ action: "drop" });
+ });
+});
diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.ts
index e443d3a6f..547b74d6e 100644
--- a/packages/eve/src/tracing/sampled-trace.ts
+++ b/packages/eve/src/tracing/sampled-trace.ts
@@ -1,5 +1,10 @@
import type { ChannelAudience } from "#shared/channel-audience.js";
-import type { TraceCapturePolicy } from "#tracing/otel-declaration.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";
// W3C sampled flag; written as a literal so this module stays out of the
// vendored OTel chunk, which the workflow driver bundle cannot include.
@@ -17,15 +22,44 @@ export function evaluateTracePolicy(
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 {
- return (
+ return resolveTracePolicyDecision(
policy?.({
agentName: trace.agentName,
audience: trace.audience,
channelType: trace.channelType,
- }) ?? trace.audience === "public"
+ }) ?? trace.audience === "public",
+ trace.audience,
);
} catch {
- return false;
+ 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/research/channel-audience-content-policy.md b/research/channel-audience-content-policy.md
index d88d730dc..d7336a92e 100644
--- a/research/channel-audience-content-policy.md
+++ b/research/channel-audience-content-policy.md
@@ -38,7 +38,15 @@ interface TraceCaptureContext {
readonly sessionId: string;
}
-type TraceCapturePolicy = (trace: TraceCaptureContext) => boolean;
+type TracePolicyDecision =
+ | { readonly emit: false }
+ | {
+ readonly emit: true;
+ readonly recordInputs: boolean;
+ readonly recordOutputs: boolean;
+ };
+
+type TraceCapturePolicy = (trace: TraceCaptureContext) => TracePolicyDecision | boolean;
interface OtelOptions {
// Other process-wide OTel settings are unchanged.
@@ -48,6 +56,11 @@ interface OtelOptions {
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.
+
Agent Runs and local traces expose the managed export policy:
```ts
@@ -101,25 +114,25 @@ declare function localTraces(options?: ManagedTraceOptions): OtelIntegration;
`composeSpanExportPolicies()` applies policies in declaration order. A later span or attribute policy sees the facade produced by earlier redactors. A span predicate returning `false` removes that span from one destination without suppressing the rest of its trace. Attribute policies run once for each attribute still visible at their stage.
-For example, this admits public and private conversations at the head gate while redacting private content before applying destination-specific filtering:
+For example, this retains every conversation while capturing content only for public audiences:
```ts
// agent/instrumentation/otel.ts
export default otel({
- tracePolicy: ({ audience }) => audience === "public" || audience === "private",
+ tracePolicy: ({ audience }) => ({
+ emit: true,
+ recordInputs: audience === "public",
+ recordOutputs: audience === "public",
+ }),
});
// agent/instrumentation/agent-runs.ts
export default agentRuns({
- exportPolicy: composeSpanExportPolicies(
- redactSpanInputs(({ audience }) => audience !== "public"),
- redactSpanOutputs(({ audience }) => audience !== "public"),
- {
- span: ({ name }) => name !== "internal.cache.refresh",
- attribute: ({ key }) =>
- key === "user.email" ? { action: "replace", value: "[redacted]" } : { action: "keep" },
- },
- ),
+ exportPolicy: composeSpanExportPolicies({
+ span: ({ name }) => name !== "internal.cache.refresh",
+ attribute: ({ key }) =>
+ key === "user.email" ? { action: "replace", value: "[redacted]" } : { action: "keep" },
+ }),
});
```