Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): define channel audience metadata (#2333)

Chad Hietalae43d9cbd8e10
diff --git a/.changeset/tidy-cats-observe.md b/.changeset/tidy-cats-observe.md
new file mode 100644
index 000000000..f7ab76620
--- /dev/null
+++ b/.changeset/tidy-cats-observe.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add an optional audience classification to channel instrumentation metadata.
diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdx
index 3ce52c272..b66e8fe3a 100644
--- a/docs/channels/custom.mdx
+++ b/docs/channels/custom.mdx
@@ -306,6 +306,8 @@ export default defineChannel({
The projection is re-evaluated whenever adapter state changes after channel event handlers run. Dynamic tool resolvers read it via `ctx.channel.metadata` and narrow it with `isChannel`. See [Dynamic capabilities](../guides/dynamic-capabilities) for the full consumption pattern.
+Metadata may include an `audience` classification: `public`, `private`, or `unknown`. Omit it when the channel cannot classify the conversation confidently; eve normalizes missing and invalid values to `unknown`. Consumers must treat `unknown` as non-public.
+
When a parent agent dispatches a subagent, the framework forwards the parent's channel metadata projection to the child. The same `metadata(state)` projector also serves instrumentation metadata resolvers.
## Continuation tokens
diff --git a/packages/eve/extension-contracts/compatibility/channel/v6.ts b/packages/eve/extension-contracts/compatibility/channel/v6.ts
new file mode 100644
index 000000000..b4c7a5fd2
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v6.ts
@@ -0,0 +1,17 @@
+import { defineChannel, POST } from "#public/channels/index.js";
+
+export default defineChannel({
+ state: { threadId: null as string | null },
+ metadata(state) {
+ return { threadId: state.threadId };
+ },
+ routes: [
+ POST("/input", async (_request, { from }) => {
+ await from("thread-1").respond([{ optionId: "approve", requestId: "approval-1" }], {
+ auth: null,
+ });
+ return new Response("ok");
+ }),
+ ],
+ turnPolicy: "queue",
+});
diff --git a/packages/eve/extension-contracts/reports/channel/v7.json b/packages/eve/extension-contracts/reports/channel/v7.json
new file mode 100644
index 000000000..dd3ae35dd
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v7.json
@@ -0,0 +1,17 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 7,
+ "sha256": "029903355993c6bff222c8c9922e193d471d52e3644f906dbf31a4d30384864a",
+ "exports": [
+ "DELETE",
+ "GET",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "isChannel"
+ ]
+}
diff --git a/packages/eve/src/channel/adapter.ts b/packages/eve/src/channel/adapter.ts
index aa9ad1765..096b9409f 100644
--- a/packages/eve/src/channel/adapter.ts
+++ b/packages/eve/src/channel/adapter.ts
@@ -5,6 +5,7 @@ import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { SessionHandle } from "#channel/session.js";
import type { DeliverPayload } from "#channel/types.js";
import type { FetchFileResult, FetchFileFunction } from "#shared/channel-definition.js";
+import type { ChannelAudienceMetadata } from "#shared/channel-audience.js";
const log = createLogger("channel.adapter");
@@ -97,7 +98,9 @@ export type ChannelEventHandlers<TCtx extends ChannelAdapterContext<any> = Chann
*/
export type { FetchFileResult };
-export type ChannelInstrumentationMetadata = Readonly<Record<string, unknown>>;
+export type ChannelInstrumentationMetadata = Readonly<
+ Record<string, unknown> & ChannelAudienceMetadata
+>;
export type ChannelInstrumentationMetadataProjector = (
state: Record<string, unknown> | undefined,
diff --git a/packages/eve/src/channel/instrumentation.test.ts b/packages/eve/src/channel/instrumentation.test.ts
index 7455b9a08..1ed6a3bbe 100644
--- a/packages/eve/src/channel/instrumentation.test.ts
+++ b/packages/eve/src/channel/instrumentation.test.ts
@@ -12,7 +12,32 @@ describe("channel instrumentation", () => {
expect(buildChannelInstrumentationProjection({ adapter, channelName: "support" })).toEqual({
kind: "channel:support",
- metadata: {},
+ metadata: { audience: "unknown" },
+ });
+ });
+
+ it.each(["public", "private", "unknown"] as const)("preserves the %s audience", (audience) => {
+ const adapter: ChannelAdapter = {
+ instrumentation: { metadata: () => ({ audience }) },
+ kind: "slack",
+ state: {},
+ };
+
+ expect(buildChannelInstrumentationProjection({ adapter }).metadata).toEqual({ audience });
+ });
+
+ it("normalizes an invalid audience to unknown without dropping other metadata", () => {
+ const adapter: ChannelAdapter = {
+ instrumentation: {
+ metadata: () => ({ audience: "everyone", threadId: "thread-1" }) as never,
+ },
+ kind: "slack",
+ state: {},
+ };
+
+ expect(buildChannelInstrumentationProjection({ adapter }).metadata).toEqual({
+ audience: "unknown",
+ threadId: "thread-1",
});
});
@@ -36,7 +61,7 @@ describe("channel instrumentation", () => {
expect(buildChannelInstrumentationProjection({ adapter, channelName: "support" })).toEqual({
kind: "channel:support",
- metadata: {},
+ metadata: { audience: "unknown" },
});
await Promise.resolve();
diff --git a/packages/eve/src/channel/instrumentation.ts b/packages/eve/src/channel/instrumentation.ts
index c7074d8c2..b44e0e1d0 100644
--- a/packages/eve/src/channel/instrumentation.ts
+++ b/packages/eve/src/channel/instrumentation.ts
@@ -5,6 +5,7 @@ import {
resolveInstrumentationProjection,
} from "#internal/instrumentation.js";
import { createLogger } from "#internal/logging.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
const log = createLogger("channel.instrumentation");
@@ -48,7 +49,7 @@ function resolveKind(input: {
function resolveMetadata(adapter: ChannelAdapter): ChannelInstrumentationMetadata {
const project = adapter.instrumentation?.metadata;
if (project === undefined) {
- return {};
+ return { audience: "unknown" };
}
const projection = resolveInstrumentationProjection({
@@ -57,5 +58,8 @@ function resolveMetadata(adapter: ChannelAdapter): ChannelInstrumentationMetadat
source: getAdapterKind(adapter),
});
- return projection ?? {};
+ return {
+ ...projection,
+ audience: normalizeChannelAudience(projection?.audience),
+ };
}
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 176291c97..29c5e0554 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -31,7 +31,7 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18],
dropped: {},
},
- channel: { current: 6, supported: [1, 2, 3, 4, 5, 6], dropped: {} },
+ channel: { current: 7, supported: [1, 2, 3, 4, 5, 6, 7], dropped: {} },
schedule: { current: 3, supported: [1, 2, 3], dropped: {} },
subagent: { current: 2, supported: [1, 2], dropped: {} },
connection: { current: 5, supported: [1, 2, 3, 4, 5], dropped: {} },
diff --git a/packages/eve/src/execution/runtime-context.test.ts b/packages/eve/src/execution/runtime-context.test.ts
index f4d7d8f4c..72a1b0c57 100644
--- a/packages/eve/src/execution/runtime-context.test.ts
+++ b/packages/eve/src/execution/runtime-context.test.ts
@@ -259,6 +259,6 @@ describe("buildRunContext", () => {
const projection = ctx.get(ChannelInstrumentationKey);
expect(projection).toBeDefined();
expect(projection!.kind).toBe("http");
- expect(projection!.metadata).toEqual({});
+ expect(projection!.metadata).toEqual({ audience: "unknown" });
});
});
diff --git a/packages/eve/src/public/channels/index.ts b/packages/eve/src/public/channels/index.ts
index 9be512ab1..b25a89b02 100644
--- a/packages/eve/src/public/channels/index.ts
+++ b/packages/eve/src/public/channels/index.ts
@@ -12,6 +12,8 @@ export {
type CompactSessionResult,
type ResetSessionResult,
type Channel,
+ type ChannelAudience,
+ type ChannelAudienceMetadata,
type ChannelFrom,
type ChannelReceiveContext,
type ChannelResolveSession,
@@ -48,11 +50,14 @@ export {
import { getChannelInstrumentationKind } from "#channel/compiled-channel.js";
import type { Channel, InferChannelMetadata } from "#public/definitions/channel.js";
+import type { ChannelAudienceMetadata } from "#shared/channel-audience.js";
/**
* Base channel metadata shape used by framework channel kinds.
*/
-export type InstrumentationChannelMetadata = Readonly<Record<string, unknown>>;
+export type InstrumentationChannelMetadata = Readonly<
+ Record<string, unknown> & ChannelAudienceMetadata
+>;
/**
* Kind discriminator exposed to instrumentation and dynamic resolvers.
diff --git a/packages/eve/src/public/definitions/channel.ts b/packages/eve/src/public/definitions/channel.ts
index 82fbc7f72..8b7a7e65e 100644
--- a/packages/eve/src/public/definitions/channel.ts
+++ b/packages/eve/src/public/definitions/channel.ts
@@ -35,6 +35,7 @@ export type {
TurnPolicy,
} from "#channel/types.js";
export type { Session, SessionHandle } from "#channel/session.js";
+export type { ChannelAudience, ChannelAudienceMetadata } from "#shared/channel-audience.js";
export type { SessionRespondOptions, SessionSendOptions } from "#channel/session.js";
export type {
ChannelFrom,
diff --git a/packages/eve/src/shared/channel-audience.ts b/packages/eve/src/shared/channel-audience.ts
new file mode 100644
index 000000000..8dce2d281
--- /dev/null
+++ b/packages/eve/src/shared/channel-audience.ts
@@ -0,0 +1,14 @@
+export const CHANNEL_AUDIENCES = ["public", "private", "unknown"] as const;
+
+/** Who can observe the conversation on its originating channel. */
+export type ChannelAudience = (typeof CHANNEL_AUDIENCES)[number];
+
+export interface ChannelAudienceMetadata {
+ readonly audience?: ChannelAudience;
+}
+
+export function normalizeChannelAudience(value: unknown): ChannelAudience {
+ return typeof value === "string" && CHANNEL_AUDIENCES.includes(value as ChannelAudience)
+ ? (value as ChannelAudience)
+ : "unknown";
+}
diff --git a/packages/eve/src/shared/channel-definition.ts b/packages/eve/src/shared/channel-definition.ts
index d94b98788..b54a24d39 100644
--- a/packages/eve/src/shared/channel-definition.ts
+++ b/packages/eve/src/shared/channel-definition.ts
@@ -5,6 +5,7 @@ import type { RouteDefinition } from "#channel/routes.js";
import type { Session, SessionHandle } from "#channel/session.js";
import type { DeliverPayload, SessionAuthContext, TurnPolicy } from "#channel/types.js";
import type { StepInput } from "#harness/types.js";
+import type { ChannelAudienceMetadata } from "#shared/channel-audience.js";
/**
* Enriched return shape from a channel's {@link ChannelAdapter.fetchFile}
@@ -49,7 +50,7 @@ export interface GenericChannelDefinition<
TState = undefined,
TCtx = void,
TReceiveTarget = Record<string, unknown>,
- TMetadata extends Record<string, unknown> = Record<string, unknown>,
+ TMetadata extends Record<string, unknown> & ChannelAudienceMetadata = Record<string, unknown>,
> {
/** Policy used by message sends that do not provide an explicit override. */
readonly turnPolicy?: TurnPolicy;
diff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
index c7f0d3e74..20e8c8824 100644
--- a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
+++ b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
@@ -249,7 +249,7 @@ describe("mounted extension installed under node_modules", () => {
);
expect(
JSON.parse(extensionFiles[`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`]!),
- ).toMatchObject({ requires: { channel: 6, schedule: 3, subagent: 2 } });
+ ).toMatchObject({ requires: { channel: 7, schedule: 3, subagent: 2 } });
const app = await scenarioApp({
name: "mounted-extension-installed",
installDependencies: true,
diff --git a/research/channel-audience-content-policy.md b/research/channel-audience-content-policy.md
new file mode 100644
index 000000000..d88d730dc
--- /dev/null
+++ b/research/channel-audience-content-policy.md
@@ -0,0 +1,164 @@
+---
+issue: https://github.com/vercel/eve/issues/2331
+status: proposed
+last_updated: "2026-08-20"
+---
+
+# Audience-aware trace content policy
+
+## Summary
+
+Messaging agents need different trace behavior for public and private conversations. Public messages may be traced with model and tool content; private conversations should not produce traces unless an author explicitly admits them. Zero-config local tracing additionally retains unclassified HTTP/TUI sessions for debugging.
+
+This proposal adds a fail-closed audience classification to channel instrumentation metadata, classifies built-in messaging channels from durable platform state, and separates the process-wide trace gate from each destination's ordered export pipeline.
+
+## Channel contract
+
+Channels may project one of three values from their existing synchronous `metadata(state)` callback:
+
+```ts
+type ChannelAudience = "public" | "private" | "unknown";
+```
+
+The field is optional for authored channels. Eve normalizes absent, malformed, and unsupported values to `unknown`. Built-in channel metadata interfaces require the field and classify only from platform evidence already captured during dispatch; ambiguous and proactive destinations remain `unknown` rather than performing observability-only network requests.
+
+The normalized audience is persisted with session trace state and exported as `agent.channel.audience` only on each `agent.session` window. Durable Eve state and an internal OpenTelemetry context key make the same value available to descendant export policies without duplicating a public attribute onto every span. Local subagents inherit the parent audience. Remote agents classify their receiving channel independently rather than trusting opaque metadata across deployment boundaries.
+
+## Public tracing API
+
+This surface is available only when `experimental.instrumentationProviders` is enabled.
+
+The process-wide declaration owns trace creation:
+
+```ts
+interface TraceCaptureContext {
+ readonly agentName?: string;
+ readonly audience: ChannelAudience;
+ readonly rootSessionId: string;
+ readonly sessionId: string;
+}
+
+type TraceCapturePolicy = (trace: TraceCaptureContext) => boolean;
+
+interface OtelOptions {
+ // Other process-wide OTel settings are unchanged.
+ readonly tracePolicy?: TraceCapturePolicy;
+}
+
+declare function otel(options?: OtelOptions): OtelDeclaration;
+```
+
+Agent Runs and local traces expose the managed export policy:
+
+```ts
+interface SpanExportContext {
+ readonly attributes: Readonly<Record<string, unknown>>;
+ readonly audience: ChannelAudience;
+ readonly name: string;
+ readonly spanId: string;
+ readonly traceId: string;
+}
+
+type SpanExportPredicate = (span: SpanExportContext) => boolean;
+
+type SpanAttributeDecision =
+ | { readonly action: "keep" }
+ | { readonly action: "drop" }
+ | {
+ readonly action: "replace";
+ readonly value:
+ string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+ };
+
+interface SpanExportPolicy {
+ readonly span?: SpanExportPredicate;
+ readonly attribute?: (input: {
+ readonly key: string;
+ readonly span: SpanExportContext;
+ readonly value: unknown;
+ }) => SpanAttributeDecision;
+}
+
+declare function redactSpanInputs(when?: SpanExportPredicate): SpanExportPolicy;
+declare function redactSpanOutputs(when?: SpanExportPredicate): SpanExportPolicy;
+declare function composeSpanExportPolicies(
+ ...policies: readonly SpanExportPolicy[]
+): SpanExportPolicy;
+
+interface ManagedTraceOptions {
+ readonly exportPolicy?: SpanExportPolicy;
+ /** @deprecated Use redactSpanInputs() in exportPolicy. */
+ readonly recordInputs?: boolean;
+ /** @deprecated Use redactSpanOutputs() in exportPolicy. */
+ readonly recordOutputs?: boolean;
+}
+
+declare function agentRuns(options?: ManagedTraceOptions): OtelIntegration;
+declare function localTraces(options?: ManagedTraceOptions): OtelIntegration;
+```
+
+`redactSpanInputs()` removes known prompt, instruction, document, and tool-argument attributes from matching spans. `redactSpanOutputs()` removes known response, reasoning, embedding, ranking, and tool-result attributes, plus exception details, event attributes, and status messages. Neither mutates the shared OpenTelemetry span; each destination receives a filtered facade.
+
+`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:
+
+```ts
+// agent/instrumentation/otel.ts
+export default otel({
+ tracePolicy: ({ audience }) => audience === "public" || audience === "private",
+});
+
+// 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" },
+ },
+ ),
+});
+```
+
+## Defaults and ordering
+
+The default authored and production head policy is equivalent to:
+
+```ts
+({ audience }) => audience === "public";
+```
+
+| Audience | Trace created by default | Content when admitted by a custom trace policy |
+| --------- | ------------------------ | ---------------------------------------------- |
+| `public` | Yes | Unchanged unless an export policy redacts it |
+| `private` | No | Unchanged unless an export policy redacts it |
+| `unknown` | No | Unchanged unless an export policy redacts it |
+
+The default policy for local tracing for `eve dev` is equivalent to:
+
+```ts
+({ audience }) => audience === "public" || audience === "unknown";
+```
+
+This keeps unclassified local HTTP/TUI sessions observable while still rejecting channels classified as `private`.
+
+The runtime order is:
+
+1. Derive and normalize the channel audience.
+2. Evaluate the process-wide `tracePolicy` before creating `agent.session`.
+3. For accepted traces, capture complete Eve and AI SDK spans.
+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.
+
+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.
+
+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.