The Open Framework for Building Agents
fix(eve): fail closed anonymous audience (#3365)
Chad Hietala7ea3b7a4acd5
diff --git a/.changeset/principal-api.md b/.changeset/principal-api.mdnew file mode 100644index 000000000..d2c053307--- /dev/null+++ b/.changeset/principal-api.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Classify anonymous eve channel sessions as `unknown` by default, so their content is not recorded in preview or production traces unless you mark the audience public explicitly. Also add `credentialOwner` for raw getToken-only auth and `caller` for audience callbacks while preserving existing `principalType` APIs, and fix token cache keys so user identifiers containing separators or percent sequences cannot collide.diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdxindex 686a0f142..fcb5fe882 100644--- a/docs/channels/custom.mdx+++ b/docs/channels/custom.mdx@@ -319,16 +319,26 @@ import { defineChannel, POST } from "eve/channels";export default defineChannel({state: { visibility: "workspace" as "workspace" | "private" | "unknown" },- audience({ state, auth }) {+ audience({ state, caller }) {if (state.visibility === "workspace") return "public";- if (auth?.principalType === "user") return "private";+ if (caller.type === "principal" && caller.principal.kind === "user") return "private";return "unknown";},routes: [POST("/webhook", async () => new Response("ok"))],});```-The input contains the channel's `state`, authenticated `auth` principal, `channel`, `mode`, and `environment`. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`.+The input contains the channel's `state`, `caller`, `channel`, `mode`, and `environment`. A principal caller omits `principalId`, `issuer`, and `subject`, but its `attributes` come from route auth and can still contain identifying values. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`.++When you explicitly annotate a callback, use `AudienceContext<TState>`. `AudienceInput<TState>` remains supported for existing callbacks while you migrate.++Existing callbacks can continue using `auth?.principalType` while you migrate:++```ts+audience({ auth }) {+ return auth?.principalType === "user" ? "private" : "unknown";+}+```Classification is fixed when the session is created. Continuation turns from a different caller do not reclassify an existing session. When a parent dispatches a local subagent, the child inherits the parent's audience while the framework forwards the parent's custom channel metadata separately.diff --git a/docs/channels/eve.mdx b/docs/channels/eve.mdxindex 064374b44..9af0b28ee 100644--- a/docs/channels/eve.mdx+++ b/docs/channels/eve.mdx@@ -163,11 +163,11 @@ The eve channel classifies who can observe a session when that session is create| Session creator | Default audience || ----------------------------------------- | ---------------- |-| Anonymous caller | `public` |+| Anonymous caller | `unknown` || `user`, `service`, or `runtime` principal | `private` || Any other principal type | `unknown` |-Anonymous HTTP surfaces are public because anyone who can reach the surface can read it. Authenticated `user`, `service`, and `runtime` sessions are private because they belong to one identified party. Other authenticated principal types remain `unknown`: trace consumers record metadata but omit content by default in preview and production.+Anonymous HTTP surfaces are `unknown` by default because reachability does not establish that their content is safe to record. Authenticated `user`, `service`, and `runtime` sessions are private because they belong to one identified party. Other authenticated principal types also remain `unknown`: trace consumers record metadata but omit content by default in preview and production. Set an explicit `audience: "public"` only for intentionally public traffic.Pass a constant or a function to override the default:@@ -187,14 +187,14 @@ import { eveChannel } from "eve/channels/eve";export default eveChannel({auth: [vercelOidc(), none()],- audience({ auth, environment }) {- if (auth === null) return environment === "development" ? "public" : "unknown";+ audience({ caller, environment }) {+ if (caller.type === "anonymous") return environment === "development" ? "public" : "unknown";return "private";},});```-The function receives the authenticated principal, channel, run mode, and deployment environment. Classification is fixed at session creation; a continuation turn from a different caller does not reclassify the session. When another eve deployment forwards a request without an accepted forwarded trace assertion, the calling deployment's principal is used for classification, so the session remains `private`. A custom [trace policy](../guides/instrumentation-providers#control-inputs-and-outputs) can still admit or deny content independently.+The function receives `caller`, channel, run mode, and deployment environment. `caller` is either `{ type: "anonymous" }` or a principal projection with `kind`, `authenticator`, and `attributes`. Classification is fixed at session creation; a continuation turn from a different caller does not reclassify the session. When another eve deployment forwards a request without an accepted forwarded trace assertion, the calling deployment's principal is used for classification, so the session remains `private`. A custom [trace policy](../guides/instrumentation-providers#control-inputs-and-outputs) can still admit or deny content independently.## Customizationdiff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdxindex cc7c21565..fa93063f6 100644--- a/docs/connections/mcp.mdx+++ b/docs/connections/mcp.mdx@@ -125,7 +125,10 @@ const publishesNow = (input: unknown): boolean => {export default defineMcpClientConnection({url: "https://mcp.example.com/mcp",description: "Social publishing: draft, schedule, and manage posts.",- auth: { getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }) },+ auth: {+ credentialOwner: "app",+ getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }),+ },approval: ({ toolName, toolInput }) => {if (DELETE_TOOLS.some((t) => toolName.includes(t))) return "user-approval";if (PUBLISH_TOOLS.some((t) => toolName.includes(t))) {diff --git a/docs/connections/openapi.mdx b/docs/connections/openapi.mdxindex 497689909..7fb7f69df 100644--- a/docs/connections/openapi.mdx+++ b/docs/connections/openapi.mdx@@ -17,7 +17,10 @@ import { defineOpenAPIConnection } from "eve/connections";export default defineOpenAPIConnection({spec: "https://petstore3.swagger.io/api/v3/openapi.json",description: "Pet store inventory and orders.",- auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },+ auth: {+ credentialOwner: "app",+ getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),+ },});```@@ -102,7 +105,10 @@ import { defineOpenAPIConnection } from "eve/connections";export default defineOpenAPIConnection({spec: "https://petstore3.swagger.io/api/v3/openapi.json",description: "Pet store inventory and orders.",- auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },+ auth: {+ credentialOwner: "app",+ getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),+ },operations: { allow: ["getInventory", "placeOrder"] },});```diff --git a/docs/connections/overview.mdx b/docs/connections/overview.mdxindex cdb7bc247..c7cf46bbb 100644--- a/docs/connections/overview.mdx+++ b/docs/connections/overview.mdx@@ -69,6 +69,7 @@ export default defineMcpClientConnection({url: "https://mcp.linear.app/mcp",description: "Linear workspace.",auth: {+ credentialOwner: "app",getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),},});@@ -76,7 +77,7 @@ export default defineMcpClientConnection({If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.-When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Switch to `principalType: "user"` when each end-user carries their own token.+When `getToken` is the only auth, `credentialOwner` defaults to `"app"`: one shared credential keyed across all sessions. Set `credentialOwner: "user"` when each end-user carries their own token.eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.@@ -86,11 +87,13 @@ A connection credential can belong to the agent or to the person using it. This| Credential owner | Use when | Auth shape || ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| App | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `principalType: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect. |-| User | Each end-user should authorize and use their own third-party account. | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { principalType: "user", getToken }`. |+| App | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `credentialOwner: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect. |+| User | Each end-user should authorize and use their own third-party account. | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { credentialOwner: "user", getToken }`. || User from a job | Background work should use the same user's OAuth grant that started the work. | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |-`principalType: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.+`credentialOwner: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.++`credentialOwner` is eve's field for raw getToken-only connection auth. Existing non-interactive raw `principalType` definitions still work, but are deprecated. Interactive auth and `connect()` from `@vercel/connect/eve` continue to use `principalType: "user"`; that field also remains correct for route-auth session identities.## No auth@@ -132,7 +135,7 @@ export default defineOpenAPIConnection({spec: "https://warehouse.example.com/openapi.json",description: "The caller's tenant-scoped warehouse.",auth: (ctx) => ({- principalType: "user",+ credentialOwner: "user",getToken: async () => ({token: await tenantToken(ctx.session.auth.current),}),@@ -151,7 +154,7 @@ headers: {}```-Use `principalType: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.+Use `credentialOwner: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.## Per-connection approval@@ -223,16 +226,16 @@ App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app t### Troubleshooting Vercel Connect auth-| Symptom | What it means | Fix |-| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |-| `reason: "principal_required"` | A user-scoped connection ran without an authenticated user on the active session. | Return `principalType: "user"` from the channel's route auth, or change the connection to `principalType: "app"` if it should be shared. |-| `authorization.required` appears but no UI | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge. | Render the challenge from the stream event and continue the same session after the callback. |-| OAuth works locally but fails after deploy | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`. |-| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal. | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work. |+| Symptom | What it means | Fix |+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `reason: "principal_required"` | A user-scoped connection ran without an authenticated user on the active session. | Return `principalType: "user"` from the channel's route auth, or use `connect({ connector, principalType: "app" })` if the Connect credential should be shared. |+| `authorization.required` appears but no UI | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge. | Render the challenge from the stream event and continue the same session after the callback. |+| OAuth works locally but fails after deploy | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`. |+| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal. | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work. |## Self-hosted interactive OAuth-To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`, and the factory pins that for you.+To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`; `credentialOwner` applies only to getToken-only auth, and the factory pins the interactive value for you.```ts title="agent/connections/linear.ts"import {diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.mdindex bf2a779f0..27fa46ba5 100644--- a/docs/guides/dynamic-capabilities.md+++ b/docs/guides/dynamic-capabilities.md@@ -178,7 +178,7 @@ export default defineDynamic({description: `${account.label} (${account.accountId})`,instanceKey: account.accountId,auth: {- principalType: "user",+ credentialOwner: "user",getToken: ({ principal }) => mintAccountToken(principal, account),},}),diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.mdindex d0f28b8cb..dc781dd36 100644--- a/docs/guides/instrumentation.md+++ b/docs/guides/instrumentation.md@@ -62,7 +62,7 @@ You are responsible for ensuring any observability or eval provider is approvedThe third configurable surface, [runtime context events](#runtime-context), attaches per-model-call values to these spans.-Channels classify their conversation with an `audience`: `public`, `private`, or `unknown`. The eve channel classifies anonymous callers as public and authenticated `user`, `service`, or `runtime` callers as private. Slack public-channel handoffs and Chat SDK workspace-visible threads are public; direct and private conversations are private; platform surfaces without enough visibility evidence remain unknown. Inbound Slack webhooks remain `unknown`; proactive Slack `receive` / `ctx.send` handoffs also stay `unknown` unless the caller passes `audience` on the target, for example when a webhook or schedule already knows the destination channel is public.+Channels classify their conversation with an `audience`: `public`, `private`, or `unknown`. The eve channel classifies anonymous callers as unknown and authenticated `user`, `service`, or `runtime` callers as private. Slack public-channel handoffs and Chat SDK workspace-visible threads are public; direct and private conversations are private; platform surfaces without enough visibility evidence remain unknown. Inbound Slack webhooks remain `unknown`; proactive Slack `receive` / `ctx.send` handoffs also stay `unknown` unless the caller passes `audience` on the target, for example when a webhook or schedule already knows the destination channel is public.## Channel delivery tracesdiff --git a/docs/patterns/multi-tenant-auth.md b/docs/patterns/multi-tenant-auth.mdindex cbaffc258..f455e81d7 100644--- a/docs/patterns/multi-tenant-auth.md+++ b/docs/patterns/multi-tenant-auth.md@@ -91,7 +91,7 @@ eve to require the authenticated user from route auth, key the step-local tokencache by that user, and pass the projected principal into `getToken`:```ts title="agent/lib/tenant-connection-auth.ts"-import type { ConnectionPrincipal, NonInteractiveAuthorizationDefinition } from "eve/connections";+import type { ConnectionAuthProvider, ConnectionPrincipal } from "eve/connections";import { tenantCredentials, type TenantService } from "./tenant-credentials";function requireTenantPrincipal(principal: ConnectionPrincipal): {@@ -107,9 +107,9 @@ function requireTenantPrincipal(principal: ConnectionPrincipal): {return { tenantId, userId: principal.id };}-export function tenantBearerAuth(service: TenantService): NonInteractiveAuthorizationDefinition {+export function tenantBearerAuth(service: TenantService): ConnectionAuthProvider {return {- principalType: "user",+ credentialOwner: "user",async getToken({ principal }) {const { tenantId, userId } = requireTenantPrincipal(principal);const credential = await tenantCredentials.getBearer(tenantId, service, { userId });diff --git a/e2e/fixtures/agent-channels/agent/channels/target.ts b/e2e/fixtures/agent-channels/agent/channels/target.tsindex cb72e08b8..163880caa 100644--- a/e2e/fixtures/agent-channels/agent/channels/target.ts+++ b/e2e/fixtures/agent-channels/agent/channels/target.ts@@ -6,6 +6,11 @@ import { defineChannel, POST } from "eve/channels";* "every channel mounts at least one route" requirement.*/export default defineChannel({+ audience({ caller }) {+ return caller.type === "principal" && caller.principal.kind === "service"+ ? "private"+ : "unknown";+ },routes: [POST("/target", async () => new Response("ok"))],async receive(input, { from }) {const sessionRef =diff --git a/e2e/fixtures/agent-subagents/agent/tools/read-workspace-label.ts b/e2e/fixtures/agent-subagents/agent/tools/read-workspace-label.tsindex 0b279a732..e36ef9fd8 100644--- a/e2e/fixtures/agent-subagents/agent/tools/read-workspace-label.ts+++ b/e2e/fixtures/agent-subagents/agent/tools/read-workspace-label.ts@@ -1,5 +1,4 @@-import type { NonInteractiveAuthorizationDefinition } from "eve/connections";-import { defineTool } from "eve/tools";+import { defineTool, type ToolAuthProvider } from "eve/tools";import { z } from "zod";const workspaceLabelByMembership: Readonly<Record<string, string>> = {@@ -13,8 +12,8 @@ const membershipByPrincipal: Readonly<Record<string, string>> = {};// Models a provider-side workspace membership store selected by eve for the current principal.-const userGrant: NonInteractiveAuthorizationDefinition = {- principalType: "user",+const userGrant: ToolAuthProvider = {+ credentialOwner: "user",async getToken({ principal }) {if (principal.type !== "user") throw new Error("A user workspace membership is required.");const token = membershipByPrincipal[principal.id];diff --git a/packages/eve/extension-contracts/compatibility/channel/v21.ts b/packages/eve/extension-contracts/compatibility/channel/v21.tsnew file mode 100644index 000000000..61e9bd3ba--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/channel/v21.ts@@ -0,0 +1,9 @@+import { defineChannel, POST, type AudienceInput } from "#public/channels/index.js";++const audience = ({ auth }: AudienceInput<undefined>) =>+ auth?.principalType === "user" ? "private" : "unknown";++export default defineChannel({+ audience,+ routes: [POST("/legacy-audience", async () => new Response("ok"))],+});diff --git a/packages/eve/extension-contracts/compatibility/connection/v18.ts b/packages/eve/extension-contracts/compatibility/connection/v18.tsnew file mode 100644index 000000000..2b93c834c--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/connection/v18.ts@@ -0,0 +1,10 @@+import { defineMcpClientConnection } from "#public/connections/index.js";++export default defineMcpClientConnection({+ auth: {+ getToken: async () => ({ token: "fixture-token" }),+ principalType: "user",+ },+ description: "Search support cases.",+ url: "https://support.example.com/mcp",+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v37.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v37.tsnew file mode 100644index 000000000..770e36591--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v37.ts@@ -0,0 +1,18 @@+import { defineDynamic, defineTool } from "#public/tools/index.js";++export default defineDynamic({+ events: {+ "session.started": () =>+ defineTool({+ description: "Read a token with legacy provider ownership.",+ inputSchema: { type: "object", properties: {} },+ async execute(_input, ctx) {+ const token = await ctx.getToken({+ getToken: async () => ({ token: "fixture-token" }),+ principalType: "app",+ });+ return { token: token.token };+ },+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/tool/v38.ts b/packages/eve/extension-contracts/compatibility/tool/v38.tsnew file mode 100644index 000000000..1a2d5d656--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v38.ts@@ -0,0 +1,13 @@+import { defineTool } from "#public/tools/index.js";++export default defineTool({+ description: "Read a token with legacy provider ownership.",+ inputSchema: { type: "object", properties: {} },+ async execute(_input, ctx) {+ const token = await ctx.getToken({+ getToken: async () => ({ token: "fixture-token" }),+ principalType: "app",+ });+ return { token: token.token };+ },+});diff --git a/packages/eve/extension-contracts/reports/channel/v22.json b/packages/eve/extension-contracts/reports/channel/v22.jsonnew file mode 100644index 000000000..6b31a4d41--- /dev/null+++ b/packages/eve/extension-contracts/reports/channel/v22.json@@ -0,0 +1,21 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "channel",+ "epoch": 22,+ "sha256": "c88c28c342db31c105328a36c9333562d6ac3dd7d47d8e513cf0e61656360c6c",+ "exports": [+ "DELETE",+ "GET",+ "HEAD",+ "OPTIONS",+ "PATCH",+ "POST",+ "PUT",+ "WS",+ "createWebSocketUpgradeServer",+ "defineChannel",+ "disableRoute",+ "isChannel",+ "isDisabledRouteSentinel"+ ]+}diff --git a/packages/eve/extension-contracts/reports/connection/v19.json b/packages/eve/extension-contracts/reports/connection/v19.jsonnew file mode 100644index 000000000..014555080--- /dev/null+++ b/packages/eve/extension-contracts/reports/connection/v19.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "connection",+ "epoch": 19,+ "sha256": "a60b033580e5f28cd496af0f7aceed6adc9b59e08f9596aeb98c50a3c374ed88",+ "exports": [+ "ConnectionAuthorizationFailedError",+ "ConnectionAuthorizationRequiredError",+ "defineDynamic",+ "defineInteractiveAuthorization",+ "defineMcpClientConnection",+ "defineOpenAPIConnection",+ "isConnectionAuthorizationFailedError",+ "isConnectionAuthorizationRequiredError"+ ]+}diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v38.json b/packages/eve/extension-contracts/reports/dynamicTool/v38.jsonnew file mode 100644index 000000000..9fe9de67f--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v38.json@@ -0,0 +1,14 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 38,+ "sha256": "c2a1ad74a4db2978bd09fbf0df05220bc232a2b76b6c9ef7bf00812204d3a252",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "defineDurableCallback",+ "defineDynamic"+ ]+}diff --git a/packages/eve/extension-contracts/reports/tool/v39.json b/packages/eve/extension-contracts/reports/tool/v39.jsonnew file mode 100644index 000000000..191346f64--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v39.json@@ -0,0 +1,20 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 39,+ "sha256": "dbaf16eac49518702a1cff6343d130460aa9092fa0329023bd8db6058584e313",+ "exports": [+ "defaultWebSearch",+ "defineTool",+ "defineWorkflowTool",+ "disableTool",+ "experimental_workflow",+ "isDisabledToolSentinel",+ "isExperimentalWorkflowToolDefinition",+ "isWebSearchToolDefinition",+ "toolOutput",+ "toolOutputPart",+ "toolResultFrom",+ "webSearch"+ ]+}diff --git a/packages/eve/src/channel/audience.ts b/packages/eve/src/channel/audience.tsindex 82947fc33..a375f7f9a 100644--- a/packages/eve/src/channel/audience.ts+++ b/packages/eve/src/channel/audience.ts@@ -1,5 +1,5 @@import type { ChannelAudience } from "#shared/channel-audience.js";-import type { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";import { normalizeChannelAudience } from "#shared/channel-audience.js";import { isThenable } from "#shared/guards.js";@@ -21,12 +21,12 @@ function warnDeprecatedMetadataAudience(kind: string): void {}export type ChannelAudienceProjector = (- input: AudienceInput<Record<string, unknown> | undefined>,+ input: AudienceContext<Record<string, unknown> | undefined>,) => ChannelAudience;export function resolveAudience(adapter: ChannelAudienceSource,- input: AudienceInput<Record<string, unknown> | undefined>,+ input: AudienceContext<Record<string, unknown> | undefined>,): ChannelAudience {return normalize(adapter, input);}@@ -48,7 +48,7 @@ export function createMetadataAudienceProjector(function normalize(adapter: ChannelAudienceSource,- input: AudienceInput<Record<string, unknown> | undefined>,+ input: AudienceContext<Record<string, unknown> | undefined>,): ChannelAudience {const instrumentation = adapter.instrumentation;const project = instrumentation?.audience;diff --git a/packages/eve/src/channel/conversation-context.ts b/packages/eve/src/channel/conversation-context.tsindex e99577664..c6b77913b 100644--- a/packages/eve/src/channel/conversation-context.ts+++ b/packages/eve/src/channel/conversation-context.ts@@ -1,9 +1,10 @@-import type { RunInput } from "#channel/types.js";+import type { RunInput, SessionAuthContext } from "#channel/types.js";import { resolveAudience } from "#channel/audience.js";import { buildChannelInstrumentationProjection } from "#channel/instrumentation.js";import { normalizeInstrumentationChannelKind } from "#shared/instrumentation-channel-kind.js";import {resolveConversationContext,+ type AudienceCaller,type ConversationContext,type ConversationEnvironment,} from "#shared/conversation-context.js";@@ -33,6 +34,7 @@ export function buildConversationContext(resolveAudience(run.adapter, {state: run.adapter.state,auth,+ caller: toAudienceCaller(auth),channel,mode: run.mode,environment,@@ -50,3 +52,18 @@ export function buildConversationContext(channel,};}++/** Projects route auth into the minimal identity audience classifiers need. */+export function toAudienceCaller(auth: SessionAuthContext | null | undefined): AudienceCaller {+ if (auth === null || auth === undefined || auth.principalType === "anonymous") {+ return { type: "anonymous" };+ }+ return {+ type: "principal",+ principal: {+ attributes: auth.attributes,+ authenticator: auth.authenticator,+ kind: auth.principalType,+ },+ };+}diff --git a/packages/eve/src/channel/instrumentation.test.ts b/packages/eve/src/channel/instrumentation.test.tsindex 717c5a29b..4466d4db1 100644--- a/packages/eve/src/channel/instrumentation.test.ts+++ b/packages/eve/src/channel/instrumentation.test.ts@@ -3,10 +3,11 @@ import { afterEach, describe, expect, it, vi } from "vitest";import type { ChannelAdapter } from "#channel/adapter.js";import { buildChannelInstrumentationProjection } from "#channel/instrumentation.js";import { resolveAudience } from "#channel/audience.js";-import type { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";-const audienceInput: AudienceInput<Record<string, unknown>> = {+const audienceInput: AudienceContext<Record<string, unknown>> = {auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:support", name: "support" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 6b20f0cc2..a20f967a7 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,8 +22,10 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 38,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38],+ current: 39,+ supported: [+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38, 39,+ ],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",15: "TaskExec replaces stageEffect with send",@@ -43,10 +45,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 37,+ current: 38,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 28, 29, 30, 31, 32,- 33, 34, 35, 36, 37,+ 33, 34, 35, 36, 37, 38,],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -58,8 +60,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},channel: {- current: 21,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21],+ current: 22,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22],dropped: {12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",},@@ -81,8 +83,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},connection: {- current: 18,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18],+ current: 19,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19],dropped: {9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",10: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",diff --git a/packages/eve/src/eve-channel/audience.test.ts b/packages/eve/src/eve-channel/audience.test.tsindex 9cfd96ce9..43d5ef720 100644--- a/packages/eve/src/eve-channel/audience.test.ts+++ b/packages/eve/src/eve-channel/audience.test.ts@@ -1,9 +1,9 @@import { describe, expect, it } from "vitest";import { defaultEveAudience } from "#eve-channel/audience.js";-import type { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";-function input(principalType: string | null): Omit<AudienceInput<undefined>, "state"> {+function input(principalType: string | null): Omit<AudienceContext<undefined>, "state"> {return {auth:principalType === null@@ -13,6 +13,13 @@ function input(principalType: string | null): Omit<AudienceInput<undefined>, "stauthenticator: "test",principalType,},+ caller:+ principalType === null || principalType === "anonymous"+ ? { type: "anonymous" }+ : {+ type: "principal",+ principal: { attributes: {}, authenticator: "test", kind: principalType },+ },channel: { kind: "http" },environment: "production",mode: "conversation",@@ -21,8 +28,8 @@ function input(principalType: string | null): Omit<AudienceInput<undefined>, "stdescribe("defaultEveAudience", () => {it.each([- [null, "public"],- ["anonymous", "public"],+ [null, "unknown"],+ ["anonymous", "unknown"],["user", "private"],["service", "private"],["runtime", "private"],diff --git a/packages/eve/src/eve-channel/audience.ts b/packages/eve/src/eve-channel/audience.tsindex 5f37bd318..a257afaa7 100644--- a/packages/eve/src/eve-channel/audience.ts+++ b/packages/eve/src/eve-channel/audience.ts@@ -1,12 +1,15 @@import type { ChannelAudience } from "#shared/channel-audience.js";-import type { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";export function defaultEveAudience(- input: Omit<AudienceInput<undefined>, "state">,+ input: Omit<AudienceContext<undefined>, "state">,): ChannelAudience {- const principalType = input.auth?.principalType ?? "anonymous";- if (principalType === "anonymous") return "public";- if (principalType === "user" || principalType === "service" || principalType === "runtime") {+ if (+ input.caller.type === "principal" &&+ (input.caller.principal.kind === "user" ||+ input.caller.principal.kind === "service" ||+ input.caller.principal.kind === "runtime")+ ) {return "private";}return "unknown";diff --git a/packages/eve/src/eve-channel/types.ts b/packages/eve/src/eve-channel/types.tsindex 68b02bbfa..ef4793552 100644--- a/packages/eve/src/eve-channel/types.ts+++ b/packages/eve/src/eve-channel/types.ts@@ -5,7 +5,7 @@ import type { TrustedForwarders } from "#channel/forwarded-principal.js";import type { AuthFn } from "#public/channels/auth.js";import type { UploadPolicyInput } from "#public/channels/upload-policy.js";import type {- AudienceInput,+ AudienceContext,Channel,ChannelContinuationOps,ChannelEvents,@@ -99,9 +99,9 @@ export interface EveChannelInput {/*** Conversation audience classification, fixed when the session is created.*- * By default, anonymous callers are `public` and `user`, `service`, or- * `runtime` principals are `private`. Every other principal type is- * `unknown`, which trace consumers treat as non-public.+ * By default, `user`, `service`, and `runtime` principals are `private`.+ * Anonymous callers and every other principal type are `unknown`, which+ * trace consumers treat as non-public.** Pass a constant audience, or a function receiving the authenticated* principal, channel, run mode, and deployment environment. Continuation@@ -109,7 +109,7 @@ export interface EveChannelInput {*/readonly audience?:| ChannelAudience- | ((input: Omit<AudienceInput<undefined>, "state">) => ChannelAudience);+ | ((input: Omit<AudienceContext<undefined>, "state">) => ChannelAudience);/*** The trusted-forwarders policy: which transport-authenticated callers may* assert a forwarded principal, callback-marked public trace audience, ordiff --git a/packages/eve/src/execution/tool-auth.integration.test.ts b/packages/eve/src/execution/tool-auth.integration.test.tsindex 4b5a6ea0c..fe47cb873 100644--- a/packages/eve/src/execution/tool-auth.integration.test.ts+++ b/packages/eve/src/execution/tool-auth.integration.test.ts@@ -204,8 +204,8 @@ describe("tool-hosted authorization", () => {it("resolves and caches an inline provider on a plain tool", async () => {let calls = 0;- const inlineAuth: AuthorizationDefinition = {- principalType: "app",+ const inlineAuth = {+ credentialOwner: "app" as const,async getToken(): Promise<TokenResult> {calls += 1;return { token: `inline-${calls}` };diff --git a/packages/eve/src/instrumentation/eve-channel-audience-production.scenario.test.ts b/packages/eve/src/instrumentation/eve-channel-audience-production.scenario.test.tsindex 32ebbb8c3..50f8a164f 100644--- a/packages/eve/src/instrumentation/eve-channel-audience-production.scenario.test.ts+++ b/packages/eve/src/instrumentation/eve-channel-audience-production.scenario.test.ts@@ -22,7 +22,7 @@ afterEach(() => {});describe("eve channel production audience", () => {- it("classifies callers and captures content only for public sessions", async () => {+ it("classifies anonymous callers as unknown and omits content in production", async () => {vi.stubEnv("EVE_DEV_WORKER_APP_ROOT", undefined);vi.stubEnv("VERCEL_ENV", "production");@@ -99,11 +99,8 @@ describe("eve channel production audience", () => {}expect(events).toHaveLength(4);- expect(events[0]).toMatchObject({ channelAudience: "public", type: "session.started" });- expect(events[1]).toMatchObject({- input: { instructions: "private instructions" },- type: "model.call.started",- });+ expect(events[0]).toMatchObject({ channelAudience: "unknown", type: "session.started" });+ expect(events[1]).toMatchObject({ input: undefined, type: "model.call.started" });expect(events[2]).toMatchObject({ channelAudience: "private", type: "session.started" });expect(events[3]).toMatchObject({ input: undefined, type: "model.call.started" });diff --git a/packages/eve/src/internal/authored-definition/connection.test.ts b/packages/eve/src/internal/authored-definition/connection.test.tsindex 27b1cd5b3..1c64bad43 100644--- a/packages/eve/src/internal/authored-definition/connection.test.ts+++ b/packages/eve/src/internal/authored-definition/connection.test.ts@@ -77,6 +77,17 @@ describe("normalizeMcpClientConnectionDefinition", () => {expect(result.auth).toMatchObject({ getToken, principalType: "app" });});+ it("normalizes credentialOwner into the runtime principalType", () => {+ const getToken = async () => ({ token: "x" });+ const result = normalizeMcpClientConnectionDefinition(+ validInput({ auth: { credentialOwner: "user", getToken } }),+ MSG,+ );++ expect(result.auth).toMatchObject({ getToken, principalType: "user" });+ expect(result.auth).not.toHaveProperty("credentialOwner");+ });+it("preserves a context-aware auth resolver without invoking it at build time", () => {let calls = 0;const auth = () => {@@ -279,6 +290,21 @@ describe("normalizeMcpClientConnectionDefinition", () => {).toThrow(/"auth\.principalType" field must be "app" or "user"/);});+ it("rejects both credential ownership fields", () => {+ expect(() =>+ normalizeMcpClientConnectionDefinition(+ validInput({+ auth: {+ credentialOwner: "app",+ getToken: async () => ({ token: "x" }),+ principalType: "app",+ },+ }),+ MSG,+ ),+ ).toThrow(/must not provide both "credentialOwner" and "principalType"/);+ });+it('rejects interactive auth with principalType "app"', () => {expect(() =>normalizeMcpClientConnectionDefinition(diff --git a/packages/eve/src/internal/authored-definition/connection.ts b/packages/eve/src/internal/authored-definition/connection.tsindex 458c97b95..fdf075006 100644--- a/packages/eve/src/internal/authored-definition/connection.ts+++ b/packages/eve/src/internal/authored-definition/connection.ts@@ -38,6 +38,7 @@ const KNOWN_OPENAPI_TOP_LEVEL_KEYS = [] as const;const KNOWN_AUTHORIZATION_KEYS = ["completeAuthorization",+ "credentialOwner","evict","getToken","principalType",diff --git a/packages/eve/src/public/channels/chat-sdk/audience.ts b/packages/eve/src/public/channels/chat-sdk/audience.tsindex fce2fd7a3..848678c37 100644--- a/packages/eve/src/public/channels/chat-sdk/audience.ts+++ b/packages/eve/src/public/channels/chat-sdk/audience.ts@@ -4,7 +4,7 @@ import type {ChatSdkChannelState,ChatSdkInstrumentationMetadata,} from "#public/channels/chat-sdk/chatSdkChannel.js";-import type { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";export function chatSdkInstrumentationMetadata(state: ChatSdkChannelState,@@ -27,6 +27,6 @@ export function chatSdkAudience(thread: SerializedThread | null): ChannelAudienc}export const chatSdkInstrumentation = {- audience: (input: AudienceInput<ChatSdkChannelState>) => chatSdkAudience(input.state.thread),+ audience: (input: AudienceContext<ChatSdkChannelState>) => chatSdkAudience(input.state.thread),metadata: chatSdkInstrumentationMetadata,} as const;diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.tsindex 17bf394de..a3726b7b1 100644--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts@@ -160,6 +160,7 @@ describe("chatSdkChannel", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:chat-sdk" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/channels/discord/discordChannel.test.ts b/packages/eve/src/public/channels/discord/discordChannel.test.tsindex e89479a45..141517187 100644--- a/packages/eve/src/public/channels/discord/discordChannel.test.ts+++ b/packages/eve/src/public/channels/discord/discordChannel.test.ts@@ -59,6 +59,7 @@ describe("discordChannel() audience classification", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:discord" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts b/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.tsindex 7a4ca6810..4f2bf557b 100644--- a/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts+++ b/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts@@ -223,7 +223,7 @@ describe("eveChannel forwarded principal → runtime principal", () => {type: "user",});// The audit attribute never enters Connect token-cache keying.- expect(principalKey(principal)).toBe("user:slack:slack:U123");+ expect(principalKey(principal)).toBe('["user","slack","slack:U123"]');expect(trustedForwarders).toHaveBeenCalledTimes(1);});diff --git a/packages/eve/src/public/channels/index.ts b/packages/eve/src/public/channels/index.tsindex f3f239983..4ec1a58be 100644--- a/packages/eve/src/public/channels/index.ts+++ b/packages/eve/src/public/channels/index.ts@@ -16,6 +16,8 @@ export {type ResetSessionResult,type Channel,type ChannelAudience,+ type AudienceCaller,+ type AudienceContext,type AudienceInput,type AudiencePrincipal,type ConversationEnvironment,diff --git a/packages/eve/src/public/channels/slack/slackChannel.test.ts b/packages/eve/src/public/channels/slack/slackChannel.test.tsindex 881134bd1..7bf503238 100644--- a/packages/eve/src/public/channels/slack/slackChannel.test.ts+++ b/packages/eve/src/public/channels/slack/slackChannel.test.ts@@ -440,6 +440,7 @@ describe("slackChannel()", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:slack" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/channels/teams/teamsChannel.test.ts b/packages/eve/src/public/channels/teams/teamsChannel.test.tsindex e77ed3ce5..d9ddbc018 100644--- a/packages/eve/src/public/channels/teams/teamsChannel.test.ts+++ b/packages/eve/src/public/channels/teams/teamsChannel.test.ts@@ -134,6 +134,7 @@ describe("teamsChannel", () => {expect(teamsAdapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:teams" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/channels/telegram/audience.ts b/packages/eve/src/public/channels/telegram/audience.tsindex 369888f37..c6c7d7eef 100644--- a/packages/eve/src/public/channels/telegram/audience.ts+++ b/packages/eve/src/public/channels/telegram/audience.ts@@ -1,7 +1,7 @@import type { ChannelAudience } from "#shared/channel-audience.js";import type { TelegramInstrumentationMetadata } from "#public/channels/telegram/index.js";import type { TelegramChannelState } from "#public/channels/telegram/telegramChannel.js";-import type { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";export function telegramInstrumentationMetadata(state: TelegramChannelState,@@ -18,7 +18,7 @@ export function telegramAudience(state: TelegramChannelState): ChannelAudience {}export const telegramInstrumentation = {- audience: (input: AudienceInput<TelegramChannelState>) => telegramAudience(input.state),+ audience: (input: AudienceContext<TelegramChannelState>) => telegramAudience(input.state),metadata: telegramInstrumentationMetadata,} as const;diff --git a/packages/eve/src/public/channels/telegram/telegramChannel.test.ts b/packages/eve/src/public/channels/telegram/telegramChannel.test.tsindex d24c69d83..c490bfce5 100644--- a/packages/eve/src/public/channels/telegram/telegramChannel.test.ts+++ b/packages/eve/src/public/channels/telegram/telegramChannel.test.ts@@ -156,6 +156,7 @@ describe("telegramChannel() inbound route", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:telegram" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/channels/twilio/twilioChannel.test.ts b/packages/eve/src/public/channels/twilio/twilioChannel.test.tsindex c48952cca..879f56e14 100644--- a/packages/eve/src/public/channels/twilio/twilioChannel.test.ts+++ b/packages/eve/src/public/channels/twilio/twilioChannel.test.ts@@ -185,6 +185,7 @@ describe("twilioChannel() inbound text pipeline", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:twilio" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/connections/index.ts b/packages/eve/src/public/connections/index.tsindex 7fcaed163..d62d0bb4f 100644--- a/packages/eve/src/public/connections/index.ts+++ b/packages/eve/src/public/connections/index.ts@@ -5,6 +5,7 @@export type {AuthorizationCallback,AuthorizationDefinition,+ CredentialOwner,ConnectionAuthDefinition,ConnectionAuthProvider,ConnectionAuthResolver,diff --git a/packages/eve/src/public/definitions/channel.test.ts b/packages/eve/src/public/definitions/channel.test.tsindex b59ab9c69..737614a01 100644--- a/packages/eve/src/public/definitions/channel.test.ts+++ b/packages/eve/src/public/definitions/channel.test.ts@@ -171,6 +171,7 @@ describe("defineChannel", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "http" },environment: "production",mode: "conversation",@@ -200,6 +201,7 @@ describe("defineChannel", () => {expect(adapter.instrumentation?.audience?.({auth: null,+ caller: { type: "anonymous" },channel: { kind: "channel:legacy" },environment: "production",mode: "conversation",diff --git a/packages/eve/src/public/definitions/channel.ts b/packages/eve/src/public/definitions/channel.tsindex 5660cd402..cc73a879d 100644--- a/packages/eve/src/public/definitions/channel.ts+++ b/packages/eve/src/public/definitions/channel.ts@@ -41,6 +41,8 @@ export type {export type { Session, SessionHandle } from "#channel/session.js";export type { ChannelAudience } from "#shared/channel-audience.js";export type {+ AudienceCaller,+ AudienceContext,AudienceInput,AudiencePrincipal,ConversationEnvironment,diff --git a/packages/eve/src/public/definitions/connections/mcp.test.ts b/packages/eve/src/public/definitions/connections/mcp.test.tsindex a49901bb6..41665972d 100644--- a/packages/eve/src/public/definitions/connections/mcp.test.ts+++ b/packages/eve/src/public/definitions/connections/mcp.test.ts@@ -14,6 +14,17 @@ describe("defineMcpClientConnection", () => {expect(definition.auth).toMatchObject({ getToken, principalType: "app" });});+ it("normalizes credentialOwner into the runtime principalType", () => {+ const getToken = async () => ({ token: "test-token" });+ const definition = defineMcpClientConnection({+ auth: { credentialOwner: "user", getToken },+ description: "test connection",+ url: "https://mcp.example.com",+ });++ expect(definition.auth).toEqual({ getToken, principalType: "user" });+ });+it("preserves context-aware auth resolvers for runtime resolution", () => {const definition = defineMcpClientConnection({auth: (ctx) => ({diff --git a/packages/eve/src/public/definitions/connections/mcp.ts b/packages/eve/src/public/definitions/connections/mcp.tsindex 0eea62781..a6f615612 100644--- a/packages/eve/src/public/definitions/connections/mcp.ts+++ b/packages/eve/src/public/definitions/connections/mcp.ts@@ -48,7 +48,7 @@ export interface McpClientConnectionDefinition {** - `getToken`-only: covers static API keys, pre-provisioned* JWTs, and out-of-band OAuth. Defaults to- * `principalType: "app"` when omitted.+ * `credentialOwner: "app"` when omitted.* - Three-method form: provide `startAuthorization` and* `completeAuthorization` together to opt into* interactive OAuth authorization.diff --git a/packages/eve/src/public/definitions/connections/openapi.test.ts b/packages/eve/src/public/definitions/connections/openapi.test.tsindex 831408568..e01e32805 100644--- a/packages/eve/src/public/definitions/connections/openapi.test.ts+++ b/packages/eve/src/public/definitions/connections/openapi.test.ts@@ -26,6 +26,18 @@ describe("defineOpenAPIConnection", () => {expect(definition.auth).toMatchObject({ getToken, principalType: "app" });});+ it("normalizes credentialOwner into the runtime principalType", () => {+ const getToken = async () => ({ token: "test-token" });+ const definition = defineOpenAPIConnection({+ auth: { credentialOwner: "user", getToken },+ baseUrl: "https://api.example.com",+ description: "test connection",+ spec: "https://api.example.com/openapi.json",+ });++ expect(definition.auth).toEqual({ getToken, principalType: "user" });+ });+it("preserves context-aware auth resolvers for runtime resolution", () => {const definition = defineOpenAPIConnection({auth: (ctx) => ({diff --git a/packages/eve/src/public/definitions/connections/openapi.ts b/packages/eve/src/public/definitions/connections/openapi.tsindex 01634c0b2..62c707030 100644--- a/packages/eve/src/public/definitions/connections/openapi.ts+++ b/packages/eve/src/public/definitions/connections/openapi.ts@@ -65,7 +65,7 @@ export interface OpenAPIConnectionDefinition {* `Authorization: Bearer <token>`.** - `getToken`-only: covers static API keys, pre-provisioned tokens,- * and out-of-band OAuth. Defaults to `principalType: "app"` when+ * and out-of-band OAuth. Defaults to `credentialOwner: "app"` when* omitted.* - Three-method form: provide `startAuthorization` and* `completeAuthorization` together to opt into interactive OAuth.diff --git a/packages/eve/src/runtime/connections/authorization-tokens.ts b/packages/eve/src/runtime/connections/authorization-tokens.tsindex ffcba8428..1f7461d0c 100644--- a/packages/eve/src/runtime/connections/authorization-tokens.ts+++ b/packages/eve/src/runtime/connections/authorization-tokens.ts@@ -27,10 +27,8 @@ type PrincipalTokenCache = Readonly<Record<string, TokenResult>>;* Virtual context key mapping authorization scope to a per-principal* {@link TokenResult} cache.*- * The principal sub-key is produced by- * {@link principalKey} so identical string keys (for example- * `"user:${issuer}:${id}"`) collide only when the resolved principal- * genuinely matches.+ * The principal sub-key is produced by {@link principalKey}, so JSON tuple+ * encoding only collides when the resolved principal genuinely matches.*/export const ConnectionAuthorizationTokensKey = new ContextKey<Readonly<Record<string, PrincipalTokenCache>>diff --git a/packages/eve/src/runtime/connections/mcp-client.test.ts b/packages/eve/src/runtime/connections/mcp-client.test.tsindex 92d6e4b85..a865e3e2c 100644--- a/packages/eve/src/runtime/connections/mcp-client.test.ts+++ b/packages/eve/src/runtime/connections/mcp-client.test.ts@@ -793,7 +793,7 @@ describe("resolveHeaders with an active context (principal resolution + cache)",});const cached = ctx.get(ConnectionAuthorizationTokensKey);- expect(cached).toEqual({ linear: { "user:idp:alice": { token: "t-1" } } });+ expect(cached).toEqual({ linear: { '["user","idp","alice"]': { token: "t-1" } } });});it("isolates cached tokens for same-named resolved connection instances", async () => {diff --git a/packages/eve/src/runtime/connections/principal.test.ts b/packages/eve/src/runtime/connections/principal.test.tsindex 08fd9957a..c70ad1f73 100644--- a/packages/eve/src/runtime/connections/principal.test.ts+++ b/packages/eve/src/runtime/connections/principal.test.ts@@ -45,9 +45,11 @@ describe("principalKey", () => {expect(principalKey({ type: "app" })).toBe("app");});- it("prefixes user principals with issuer to avoid cross-IdP collisions", () => {- expect(principalKey({ id: "u1", issuer: "google", type: "user" })).toBe("user:google:u1");- expect(principalKey({ id: "u1", issuer: "slack", type: "user" })).toBe("user:slack:u1");+ it("encodes user principals with their issuer to avoid cross-IdP collisions", () => {+ expect(principalKey({ id: "u1", issuer: "google", type: "user" })).toBe(+ '["user","google","u1"]',+ );+ expect(principalKey({ id: "u1", issuer: "slack", type: "user" })).toBe('["user","slack","u1"]');});it("differentiates two users from the same issuer", () => {@@ -57,7 +59,21 @@ describe("principalKey", () => {});it("keys an issuerless native Vercel user by its user id", () => {- expect(principalKey({ id: "user_123", type: "user" })).toBe("user:user_123");+ expect(principalKey({ id: "user_123", type: "user" })).toBe('["user",null,"user_123"]');+ });++ it("does not collide when issuer and id contain separators", () => {+ const first = principalKey({ id: "c", issuer: "a:b", type: "user" });+ const second = principalKey({ id: "b:c", issuer: "a", type: "user" });++ expect(first).not.toBe(second);+ });++ it("does not conflate percent sequences with their decoded separators", () => {+ const encoded = principalKey({ id: "user%3A1", issuer: "idp", type: "user" });+ const separator = principalKey({ id: "user:1", issuer: "idp", type: "user" });++ expect(encoded).not.toBe(separator);});});diff --git a/packages/eve/src/runtime/connections/principal.ts b/packages/eve/src/runtime/connections/principal.tsindex a504ce608..860645d43 100644--- a/packages/eve/src/runtime/connections/principal.ts+++ b/packages/eve/src/runtime/connections/principal.ts@@ -21,21 +21,18 @@ import { isVercelOidcIssuer } from "#shared/vercel-project.js";* per-principal token cache.** - `{ type: "app" }` → `"app"`. Shared across all sessions.- * - `{ type: "user", issuer, id }` → `"user:${issuer}:${id}"`. The- * issuer prefix prevents collisions when the same `id` across- * identity providers (for example Slack `U123` vs Google `U123`)- * would otherwise alias to the same cache slot.- * - `{ type: "user", id }` → `"user:${id}"`. This is the native- * Vercel Connect user projection.+ * - `{ type: "user", issuer, id }` → `["user", issuer, id]` JSON.+ * - `{ type: "user", id }` → `["user", null, id]` JSON. This is the+ * native Vercel Connect user projection.+ *+ * JSON tuple encoding preserves the boundaries between issuer and id, so+ * user-provided separators and percent sequences cannot alias cache entries.*/export function principalKey(principal: ConnectionPrincipal): string {if (principal.type === "app") {return "app";}- if (principal.issuer === undefined) {- return `user:${principal.id}`;- }- return `user:${principal.issuer}:${principal.id}`;+ return JSON.stringify(["user", principal.issuer ?? null, principal.id]);}/**diff --git a/packages/eve/src/runtime/connections/validate-authorization.test.ts b/packages/eve/src/runtime/connections/validate-authorization.test.tsindex 203db0f53..7ead833e2 100644--- a/packages/eve/src/runtime/connections/validate-authorization.test.ts+++ b/packages/eve/src/runtime/connections/validate-authorization.test.ts@@ -22,6 +22,10 @@ describe("validateAuthorizationSpec", () => {expect(validateAuthorizationSpec({ getToken, principalType: "user" })).toBeUndefined();});+ it("returns undefined for a getToken-only definition with credentialOwner", () => {+ expect(validateAuthorizationSpec({ credentialOwner: "user", getToken })).toBeUndefined();+ });+it("returns undefined for a getToken-only definition without principalType", () => {expect(validateAuthorizationSpec({ getToken })).toBeUndefined();});@@ -58,6 +62,30 @@ describe("validateAuthorizationSpec", () => {});});+ describe("credential owner rejection", () => {+ it("rejects an unknown credentialOwner value using the authored field name", () => {+ expect(validateAuthorizationSpec({ credentialOwner: "service", getToken })).toMatch(+ /"auth\.credentialOwner" field must be "app" or "user"/,+ );+ });++ it("rejects both ownership fields even when they agree", () => {+ expect(+ validateAuthorizationSpec({ credentialOwner: "user", getToken, principalType: "user" }),+ ).toMatch(/must not provide both "credentialOwner" and "principalType"/);+ });++ it("treats an undefined credentialOwner as omitted", () => {+ expect(+ validateAuthorizationSpec({+ credentialOwner: undefined,+ getToken,+ principalType: "user",+ }),+ ).toBeUndefined();+ });+ });+describe("getToken rejection", () => {it("rejects a missing getToken", () => {expect(validateAuthorizationSpec({ principalType: "app" })).toMatch(@@ -121,6 +149,17 @@ describe("validateAuthorizationSpec", () => {});});+ it("rejects credentialOwner on interactive authorization", () => {+ expect(+ validateAuthorizationSpec({+ completeAuthorization,+ credentialOwner: "user",+ getToken,+ startAuthorization,+ }),+ ).toMatch(/credentialOwner.*only supported by getToken-only authorization/);+ });+describe("displayName validation", () => {it("accepts a non-empty string displayName", () => {expect(validateAuthorizationSpec({ displayName: "Salesforce", getToken })).toBeUndefined();@@ -157,6 +196,19 @@ describe("normalizeAuthorizationSpec", () => {});});+ it("normalizes credentialOwner and legacy principalType identically", () => {+ const credentialOwner = normalizeAuthorizationSpec(+ { credentialOwner: "user", getToken },+ "testPrefix:",+ );+ const principalType = normalizeAuthorizationSpec(+ { getToken, principalType: "user" },+ "testPrefix:",+ );++ expect(credentialOwner).toEqual(principalType);+ });+it("carries displayName through the non-interactive branch", () => {expect(normalizeAuthorizationSpec({ displayName: "Salesforce", getToken }, "testPrefix:"),diff --git a/packages/eve/src/shared/channel-definition.ts b/packages/eve/src/shared/channel-definition.tsindex a48498936..8a8d04bfc 100644--- a/packages/eve/src/shared/channel-definition.ts+++ b/packages/eve/src/shared/channel-definition.ts@@ -5,7 +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 { AudienceInput } from "#shared/conversation-context.js";+import type { AudienceContext } from "#shared/conversation-context.js";import type { ChannelAudience } from "#shared/channel-audience.js";/**@@ -117,7 +117,7 @@ export interface GenericChannelDefinition<* and deployment environment. Return `"unknown"` when classification is not* confident; consumers treat it as non-public.*/- readonly audience?: (input: AudienceInput<TState>) => ChannelAudience;+ readonly audience?: (input: AudienceContext<TState>) => ChannelAudience;/*** Identifier of the adapter family this channel belongs to. Set bydiff --git a/packages/eve/src/shared/connection-types.ts b/packages/eve/src/shared/connection-types.tsindex ba729e268..67dd5f89e 100644--- a/packages/eve/src/shared/connection-types.ts+++ b/packages/eve/src/shared/connection-types.ts@@ -167,19 +167,36 @@ export type AuthorizationDefinition<Resume extends JsonValue = JsonValue> =| NonInteractiveAuthorizationDefinition| InteractiveAuthorizationDefinition<Resume>;+/** Declares whether a connection credential belongs to the agent or end user. */+export type CredentialOwner = "app" | "user";++type NonInteractiveCredentialOwner =+ | {+ readonly credentialOwner?: CredentialOwner;+ readonly principalType?: never;+ }+ | {+ readonly credentialOwner?: never;+ /**+ * @deprecated Use `credentialOwner` for connection credential ownership.+ * Session auth continues to use `principalType`.+ */+ readonly principalType?: CredentialOwner;+ };+/*** Auth provider returned directly from or resolved by a connection's `auth`* field.** Identical to {@link AuthorizationDefinition} except the- * non-interactive form may omit `principalType`; normalization- * defaults it to `"app"`. The resolved token is sent as+ * non-interactive form may omit `credentialOwner`; normalization+ * defaults it to `"app"`. Its legacy `principalType` remains supported+ * and deprecated for compatibility. Interactive definitions continue to+ * use `principalType: "user"`. The resolved token is sent as* `Authorization: Bearer <token>`.*/export type ConnectionAuthProvider =- | (Omit<NonInteractiveAuthorizationDefinition, "principalType"> & {- readonly principalType?: NonInteractiveAuthorizationDefinition["principalType"];- })+ | (Omit<NonInteractiveAuthorizationDefinition, "principalType"> & NonInteractiveCredentialOwner)| AuthorizationDefinition;/**@@ -217,8 +234,8 @@ interface AuthorizationDefinitionBase {* - `"user"`: the framework projects the active session's user* principal into `{ type: "user", id, issuer, ... }` and fails* fast with `reason: "principal_required"` when the session has- * no authenticated user. The token cache keys on- * `user:${issuer}:${id}` so concurrent users never share tokens.+ * no authenticated user. The token cache keys on a JSON tuple of+ * the issuer and id so concurrent users never share tokens.*/readonly principalType: "app" | "user";diff --git a/packages/eve/src/shared/conversation-context.test.ts b/packages/eve/src/shared/conversation-context.test.tsindex 4da1cdaf5..b41b7cec2 100644--- a/packages/eve/src/shared/conversation-context.test.ts+++ b/packages/eve/src/shared/conversation-context.test.ts@@ -3,8 +3,9 @@ import { afterEach, describe, expect, it, vi } from "vitest";import type { RunInput, SessionAuthContext } from "#channel/types.js";import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";import { resolveInstrumentationEnvironment } from "#internal/application/dev-environment.js";-import { buildConversationContext } from "#channel/conversation-context.js";+import { buildConversationContext, toAudienceCaller } from "#channel/conversation-context.js";import {+ type AudienceInput,ConversationContextKey,UNKNOWN_CONVERSATION_CONTEXT,} from "#shared/conversation-context.js";@@ -97,6 +98,75 @@ describe("buildConversationContext", () => {expect(context).toMatchObject({ audience: "private", principalType: "user" });});+ it("keeps callbacks using the deprecated auth input compatible", () => {+ const audience = ({ auth }: AudienceInput<Record<string, unknown> | undefined>) =>+ auth?.principalType === "user" ? "private" : "public";+ const context = buildConversationContext(+ run({+ adapter: { instrumentation: { audience }, kind: "http" },+ auth,+ }),+ "production",+ );++ expect(context.audience).toBe("private");+ });++ it("projects only audience-safe caller fields", () => {+ expect(+ toAudienceCaller({+ attributes: { role: ["admin"] },+ authenticator: "test-idp",+ issuer: "https://idp.example",+ principalId: "user-1",+ principalType: "user",+ subject: "subject-1",+ }),+ ).toEqual({+ type: "principal",+ principal: {+ attributes: { role: ["admin"] },+ authenticator: "test-idp",+ kind: "user",+ },+ });+ });++ it.each([+ [null, { type: "anonymous" }],+ [+ {+ attributes: {},+ authenticator: "none",+ principalId: "anonymous",+ principalType: "anonymous",+ },+ { type: "anonymous" },+ ],+ ] as const)("projects %j as %j", (input, expected) => {+ expect(toAudienceCaller(input)).toEqual(expected);+ });++ it("passes caller alongside auth to audience classifiers", () => {+ const context = buildConversationContext(+ run({+ adapter: {+ kind: "http",+ instrumentation: {+ audience: ({ caller }) =>+ caller.type === "principal" && caller.principal.kind === "user"+ ? "private"+ : "unknown",+ },+ },+ auth,+ }),+ "production",+ );++ expect(context.audience).toBe("private");+ });+it("treats an explicit null route principal as unauthenticated", () => {const context = buildConversationContext(run({diff --git a/packages/eve/src/shared/conversation-context.ts b/packages/eve/src/shared/conversation-context.tsindex dc8cfb2c8..26b225c13 100644--- a/packages/eve/src/shared/conversation-context.ts+++ b/packages/eve/src/shared/conversation-context.ts@@ -25,14 +25,31 @@ export interface AudiencePrincipal {readonly attributes: Readonly<Record<string, string | readonly string[]>>;}+export type AudienceCaller =+ | { readonly type: "anonymous" }+ | {+ readonly type: "principal";+ readonly principal: {+ readonly kind: string;+ readonly authenticator: string;+ readonly attributes: Readonly<Record<string, string | readonly string[]>>;+ };+ };+export interface AudienceInput<TState> {readonly state: TState;+ /** @deprecated Use `caller`; it excludes `principalId`, `issuer`, and `subject`. */readonly auth: AudiencePrincipal | null;readonly channel: ConversationContext["channel"];readonly mode: RunMode;readonly environment: ConversationEnvironment;}+/** Preferred input type for new audience callback annotations. */+export interface AudienceContext<TState> extends AudienceInput<TState> {+ readonly caller: AudienceCaller;+}+/** Safe projection for durable sessions created before `eve.conversation` existed. */export const UNKNOWN_CONVERSATION_CONTEXT: ConversationContext = {audience: "unknown",diff --git a/packages/eve/src/shared/validate-authorization.ts b/packages/eve/src/shared/validate-authorization.tsindex 621a86f69..b39034e74 100644--- a/packages/eve/src/shared/validate-authorization.ts+++ b/packages/eve/src/shared/validate-authorization.ts@@ -33,11 +33,17 @@ export function validateAuthorizationSpec(const hasStart = auth.startAuthorization !== undefined;const hasComplete = auth.completeAuthorization !== undefined;+ const hasCredentialOwner = auth.credentialOwner !== undefined;+ const hasPrincipalType = auth.principalType !== undefined;- if (!hasStart && !hasComplete && auth.principalType !== undefined) {- if (auth.principalType !== "app" && auth.principalType !== "user") {- return `The "${fieldName}.principalType" field must be "app" or "user".`;- }+ if (hasCredentialOwner && hasPrincipalType) {+ return `The "${fieldName}" field must not provide both "credentialOwner" and "principalType".`;+ }++ const credentialOwnerField = hasCredentialOwner ? "credentialOwner" : "principalType";+ const credentialOwner = hasCredentialOwner ? auth.credentialOwner : auth.principalType;+ if (credentialOwner !== undefined && credentialOwner !== "app" && credentialOwner !== "user") {+ return `The "${fieldName}.${credentialOwnerField}" field must be "app" or "user".`;}if (hasStart !== hasComplete) {@@ -52,6 +58,10 @@ export function validateAuthorizationSpec(return `The "${fieldName}.completeAuthorization" field must be a function when provided.`;}+ if (hasStart && hasCredentialOwner) {+ return `The "${fieldName}.credentialOwner" field is only supported by getToken-only authorization. Interactive authorization is restricted to "principalType": "user" in v1.`;+ }+if (hasStart && auth.principalType !== "user") {return `Interactive authorization (startAuthorization + completeAuthorization) is restricted to "principalType": "user" in v1. App-level credentials must use a getToken-only definition.`;}@@ -104,7 +114,8 @@ export function normalizeAuthorizationSpec(let nonInteractive: NonInteractiveAuthorizationDefinition = {getToken: auth.getToken as NonInteractiveAuthorizationDefinition["getToken"],- principalType: (auth.principalType ??+ principalType: (auth.credentialOwner ??+ auth.principalType ??"app") as NonInteractiveAuthorizationDefinition["principalType"],};if (vercelConnect !== undefined) nonInteractive = { ...nonInteractive, vercelConnect };diff --git a/packages/eve/src/tools/auth.ts b/packages/eve/src/tools/auth.tsindex 76947a8fc..06993225e 100644--- a/packages/eve/src/tools/auth.ts+++ b/packages/eve/src/tools/auth.ts@@ -1,22 +1,18 @@import type {- AuthorizationDefinition,ConnectionAuthorizationContext,- NonInteractiveAuthorizationDefinition,+ ConnectionAuthProvider,} from "#shared/connection-types.js";/*** Authorization provider passed to the tool context's `getToken` or* `requireAuth` method. Accepts the same shapes as a connection's `auth`:* - a `getToken`-only object (static API keys, pre-provisioned JWTs);- * `principalType` may be omitted and defaults to `"app"`.+ * `credentialOwner` may be omitted and defaults to `"app"`.* - a full interactive OAuth definition (e.g. `connect("okta/myagent")` from- * `@vercel/connect/eve`, or `defineInteractiveAuthorization`).+ * `@vercel/connect/eve`, or `defineInteractiveAuthorization`), which keeps+ * `principalType: "user"`.*/-export type ToolAuthDefinition =- | (Omit<NonInteractiveAuthorizationDefinition, "principalType"> & {- readonly principalType?: NonInteractiveAuthorizationDefinition["principalType"];- })- | AuthorizationDefinition;+export type ToolAuthDefinition = ConnectionAuthProvider;export type ToolAuthProvider = ToolAuthDefinition;diff --git a/packages/eve/src/tracing/local-traces.test.ts b/packages/eve/src/tracing/local-traces.test.tsindex 45026351b..d24d0a1c1 100644--- a/packages/eve/src/tracing/local-traces.test.ts+++ b/packages/eve/src/tracing/local-traces.test.ts@@ -118,6 +118,14 @@ describe("localTracePolicy", () => {authenticator: "vercel-oidc",principalType: "user",},+ caller: {+ type: "principal",+ principal: {+ attributes: {},+ authenticator: "vercel-oidc",+ kind: "user",+ },+ },channel: { kind: "http" },environment: "development",mode: "conversation",