The Open Framework for Building Agents
feat(eve): let eve channel onMessage replace a turn's client context (#5008)
Matan Kushnerf9ea5460d74c
diff --git a/.changeset/on-message-turn-context.md b/.changeset/on-message-turn-context.mdnew file mode 100644index 000000000..28741a257--- /dev/null+++ b/.changeset/on-message-turn-context.md@@ -0,0 +1,5 @@+---+"eve": patch+---++The eve channel's `onMessage` can now read the request's `clientContext` as `ctx.eve.clientContext` and return its own `clientContext` to replace it for that turn, so the model sees server-checked context without it being kept in session history.diff --git a/docs/channels/eve.mdx b/docs/channels/eve.mdxindex 078f3039d..0597dc0e0 100644--- a/docs/channels/eve.mdx+++ b/docs/channels/eve.mdx@@ -341,6 +341,33 @@ export default eveChannel({`onMessage` must return an auth result. Return `title` alongside `auth` to set the title when the dispatch creates a session or sends the first message to a prewarmed session. A successful canonical eve HTTP message always dispatches and therefore always produces or continues a session.+### Turn context++`context` strings become user messages in durable session history. For context that applies to one turn only, return `clientContext` instead. It replaces the request's [`clientContext`](../guides/client/messages) for that turn: it reaches every model call in the turn and is not kept in session history.++`ctx.eve.clientContext` holds the request's `clientContext` exactly as the client sent it, or `undefined` when it sent none. Use it to check or correct client-supplied state before the model sees it:++```ts title="agent/channels/eve.ts"+import { eveChannel, defaultEveAuth } from "eve/channels/eve";+import { vercelOidc } from "eve/channels/auth";++import { getVerifiedPlan } from "../lib/billing";++export default eveChannel({+ auth: [vercelOidc()],+ async onMessage(ctx) {+ const auth = defaultEveAuth(ctx);+ const plan = await getVerifiedPlan(auth);+ return { auth, clientContext: [`The user's plan is ${plan}.`] };+ },+});+```++- Omit `clientContext` to keep the request's context. Return `[]` to drop it.+- The returned value takes the same shape as request `clientContext` (`ClientContextValue`, exported from `eve/channels/eve`): a string, an array of strings, or a JSON object. eve turns it into model messages the same way.+- eve labels client-supplied entries `Client context:` for the model. Returned context is sent without the label.+- `onMessage` runs only for requests with a message. An input response keeps the context its request sent.+## ClientsThe browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.diff --git a/e2e/fixtures/agent-basic-runtime/agent/channels/eve.ts b/e2e/fixtures/agent-basic-runtime/agent/channels/eve.tsindex 96fc1af45..a66018b04 100644--- a/e2e/fixtures/agent-basic-runtime/agent/channels/eve.ts+++ b/e2e/fixtures/agent-basic-runtime/agent/channels/eve.ts@@ -1,5 +1,5 @@import type { AuthFn } from "eve/channels/auth";-import { eveChannel } from "eve/channels/eve";+import { defaultEveAuth, eveChannel } from "eve/channels/eve";import type { SessionAuthContext } from "eve/context";import { authenticateWorkspaceMember } from "../lib/workspace";@@ -29,6 +29,10 @@ const authenticateRetentionCheck: AuthFn<Request> = (request) =>? { ...principal("retention-check"), principalType: "metadata-only" }: null;+/** Client context entry that asks the channel to replace the turn's context with its own. */+const REPLACE_CLIENT_CONTEXT_MARKER = "e2e:replace-client-context";+const SERVER_CONTEXT_TOKEN = "serverctx-K3M8";+export default eveChannel({auth: [authenticateA,@@ -37,4 +41,12 @@ export default eveChannel({authenticateRetentionCheck,authenticateEvalDriver,],+ onMessage(ctx) {+ const auth = defaultEveAuth(ctx);+ const { clientContext } = ctx.eve;+ if (!Array.isArray(clientContext) || !clientContext.includes(REPLACE_CLIENT_CONTEXT_MARKER)) {+ return { auth };+ }+ return { auth, clientContext: [`The server context token is ${SERVER_CONTEXT_TOKEN}.`] };+ },});diff --git a/e2e/fixtures/agent-basic-runtime/evals/runtime/channel-client-context.eval.ts b/e2e/fixtures/agent-basic-runtime/evals/runtime/channel-client-context.eval.tsnew file mode 100644index 000000000..484005c2e--- /dev/null+++ b/e2e/fixtures/agent-basic-runtime/evals/runtime/channel-client-context.eval.ts@@ -0,0 +1,48 @@+import { defineEval } from "eve/evals";+import { satisfies } from "eve/evals/expect";++// Must match the fixture's `agent/channels/eve.ts`.+const REPLACE_CLIENT_CONTEXT_MARKER = "e2e:replace-client-context";+const SERVER_CONTEXT_TOKEN = "serverctx-K3M8";+const CLIENT_CONTEXT_TOKEN = "clientctx-replaced-T5N1";+const CONTEXT_TOKEN_PATTERN = /\b(?:clientctx|serverctx)-[A-Za-z0-9-]+\b/g;++/**+ * The eve channel's `onMessage` replaces a turn's client context. The fixture+ * channel swaps the client's entries for its own token when the marker entry+ * is present, so the model should see the server's token and none of the+ * client's.+ */+export default defineEval({+ tags: ["real-model"],+ description: "Session runtime smoke: onMessage replaces a turn's client context.",++ async test(t) {+ const reply = await t.send(+ "Reply with every token beginning with clientctx- or serverctx- that is visible anywhere in your model input, one per line, and nothing else.",+ {+ clientContext: [+ REPLACE_CLIENT_CONTEXT_MARKER,+ `The client context token is ${CLIENT_CONTEXT_TOKEN}.`,+ ],+ },+ );++ t.succeeded();+ const tokens = reply.message?.match(CONTEXT_TOKEN_PATTERN) ?? [];+ await t.require(+ tokens,+ satisfies<readonly string[]>(+ (observed) => observed.includes(SERVER_CONTEXT_TOKEN),+ "contains the channel's context token",+ ),+ );+ await t.require(+ tokens,+ satisfies<readonly string[]>(+ (observed) => !observed.includes(CLIENT_CONTEXT_TOKEN),+ "does not contain the replaced client context token",+ ),+ );+ },+});diff --git a/packages/eve/src/eve-channel/create-request.ts b/packages/eve/src/eve-channel/create-request.tsindex d0dc64408..5d20f7925 100644--- a/packages/eve/src/eve-channel/create-request.ts+++ b/packages/eve/src/eve-channel/create-request.ts@@ -2,6 +2,7 @@ import type { UserContent } from "ai";import type { SessionCallback, SessionCapabilities } from "#channel/types.js";import type { LegacyRemoteAgentCaller } from "#execution/legacy-remote-agent/protocol.js";+import type { ClientContextValue } from "#eve-channel/types.js";import type { JsonObject } from "#shared/json.js";import type { ToolStub } from "#tool-stubs/types.js";@@ -10,7 +11,7 @@ export interface ParsedCreateBody {callback?: SessionCallback;capabilities?: SessionCapabilities;message?: string | UserContent;- context?: readonly string[];+ context?: ClientContextValue;operationId?: string;outputSchema?: JsonObject;/** Remote agent protocol of a delegating caller; set only with {@link callback}. */diff --git a/packages/eve/src/eve-channel/index.ts b/packages/eve/src/eve-channel/index.tsindex 180abea59..068a57eeb 100644--- a/packages/eve/src/eve-channel/index.ts+++ b/packages/eve/src/eve-channel/index.ts@@ -81,6 +81,7 @@ import {type RemoteAgentBinding,normalizeEveCors,resolveOnMessage,+ resolveTurnClientContext,strandedSessionResponse,} from "#eve-channel/support.js";import type { EveChannel, EveChannelInput, EveEventContext } from "#eve-channel/types.js";@@ -309,9 +310,13 @@ export function eveChannel(input: EveChannelInput): EveChannel {const messageResult =body.message === undefined- ? { auth: forwarded.auth }+ ? {+ auth: forwarded.auth,+ clientContext: resolveTurnClientContext(undefined, body.context),+ }: await resolveOnMessage({auth: forwarded.auth,+ clientContext: body.context,config: input,invocation:parent === undefined || body.operationId === undefined@@ -362,7 +367,7 @@ export function eveChannel(input: EveChannelInput): EveChannel {context: messageResult.context,outputSchema: body.outputSchema,},- body.context,+ messageResult.clientContext,),conversationId,parent,@@ -414,18 +419,21 @@ export function eveChannel(input: EveChannelInput): EveChannel {const policyRejection = checkUploadPolicy(body, uploadPolicy);if (policyRejection !== null) return policyRejection;+ let clientContext = resolveTurnClientContext(undefined, body.context);let context: readonly string[] | undefined;let title: string | undefined;let dispatchAuth: SessionAuthContext | null = forwarded.auth;if (body.message !== undefined) {const messageResult = await resolveOnMessage({auth: forwarded.auth,+ clientContext: body.context,config: input,message: body.message,request: req,sessionId,});if (messageResult instanceof Response) return messageResult;+ clientContext = messageResult.clientContext;context = messageResult.context;title = messageResult.title;dispatchAuth = messageResult.auth;@@ -443,7 +451,7 @@ export function eveChannel(input: EveChannelInput): EveChannel {turnPolicy: body.turnPolicy,title,},- body.context,+ clientContext,);result =body.inputResponses === undefineddiff --git a/packages/eve/src/eve-channel/request.ts b/packages/eve/src/eve-channel/request.tsindex 559661b95..8b1f92f2d 100644--- a/packages/eve/src/eve-channel/request.ts+++ b/packages/eve/src/eve-channel/request.ts@@ -27,6 +27,7 @@ import {EVE_STREAM_TAIL_INDEX_HEADER,EVE_STREAM_VERSION_HEADER,} from "#protocol/message.js";+import type { ClientContextValue } from "#eve-channel/types.js";import {REMOTE_AGENT_PROTOCOL_MISMATCH,REMOTE_AGENT_PROTOCOL_VERSION,@@ -142,7 +143,7 @@ interface ParsedSessionMessageBody {callback?: SessionCallback;message?: string | UserContent;inputResponses?: readonly ValidatedInputResponse[];- context?: readonly string[];+ context?: ClientContextValue;outputSchema?: JsonObject;turnPolicy?: TurnPolicy;}@@ -572,13 +573,11 @@ function parseInputResponses(return inputResponses;}-const CLIENT_CONTEXT_PREFIX = "Client context:\n";--function parseClientContextField(value: unknown): string[] | Response | undefined {+function parseClientContextField(value: unknown): ClientContextValue | Response | undefined {if (value === undefined) return undefined;if (typeof value === "string") {- return value.length > 0 ? [toClientContextMessage(value)] : undefined;+ return value.length > 0 ? value : undefined;}if (Array.isArray(value)) {@@ -591,7 +590,7 @@ function parseClientContextField(value: unknown): string[] | Response | undefine);}- return value.map((entry) => toClientContextMessage(entry));+ return value;}if (value === null || typeof value !== "object") {@@ -606,7 +605,7 @@ function parseClientContextField(value: unknown): string[] | Response | undefinetry {const json = parseJsonObject(value);- return [toClientContextMessage(JSON.stringify(json))];+ return json;} catch {return Response.json({ error: "Expected 'clientContext' to be a JSON-serializable object.", ok: false },@@ -615,10 +614,6 @@ function parseClientContextField(value: unknown): string[] | Response | undefine}}-function toClientContextMessage(content: string): string {- return `${CLIENT_CONTEXT_PREFIX}${content}`;-}-export function parseIncludeTailIndex(request: Request): boolean {const raw = new URL(request.url).searchParams.get("includeTailIndex");return raw === "1" || raw === "true";diff --git a/packages/eve/src/eve-channel/support.ts b/packages/eve/src/eve-channel/support.tsindex d1d9ba088..1aa1bb149 100644--- a/packages/eve/src/eve-channel/support.ts+++ b/packages/eve/src/eve-channel/support.ts@@ -7,6 +7,7 @@ import { createLogger, logError } from "#internal/logging.js";import type { MessageStreamEvent } from "#protocol/message.js";import type { ChannelCors } from "#public/definitions/channel.js";import {+ type ClientContextValue,defaultEveAuth,type EveChannelCors,type EveChannelCorsOptions,@@ -18,6 +19,8 @@ import {const log = createLogger("eve.channel");+const CLIENT_CONTEXT_PREFIX = "Client context:\n";+export function healthResponse(): Response {return Response.json({ok: true,@@ -156,12 +159,15 @@ function normalizeEveCorsOrigin(interface OnMessageOutcome {readonly auth: SessionAuthContext | null;+ /** Model-ready turn context: `onMessage`'s replacement, or the request's labeled entries. */+ readonly clientContext?: readonly string[];readonly context?: readonly string[];readonly title?: string;}export async function resolveOnMessage(input: {readonly auth: SessionAuthContext | null;+ readonly clientContext?: ClientContextValue;readonly config: EveChannelInput;readonly invocation?: EveHandle["invocation"];readonly message: string | UserContent;@@ -172,7 +178,11 @@ export async function resolveOnMessage(input: {let result: EveMessageResult;try {- const base = { caller: input.auth, request: input.request };+ const base: EveHandle = {+ caller: input.auth,+ clientContext: input.clientContext,+ request: input.request,+ };const eve: EveHandle =input.sessionId === undefined? input.invocation === undefined@@ -194,7 +204,35 @@ export async function resolveOnMessage(input: {);}- return { auth: result.auth, context: result.context, title: result.title };+ return {+ auth: result.auth,+ clientContext: resolveTurnClientContext(result.clientContext, input.clientContext),+ context: result.context,+ title: result.title,+ };+}++/**+ * The turn's model context messages: `onMessage`'s replacement as written, otherwise+ * the request's entries labeled as client-supplied. Empty means none.+ */+export function resolveTurnClientContext(+ replacement: ClientContextValue | undefined,+ requested: ClientContextValue | undefined,+): readonly string[] | undefined {+ const messages =+ replacement === undefined+ ? toContextEntries(requested).map((entry) => `${CLIENT_CONTEXT_PREFIX}${entry}`)+ : toContextEntries(replacement);+ return messages.length === 0 ? undefined : messages;+}++/** One model message per string; an object is JSON-serialized into one. */+function toContextEntries(value: ClientContextValue | undefined): readonly string[] {+ if (value === undefined || value === "") return [];+ if (typeof value === "string") return [value];+ if (Array.isArray(value)) return value;+ return [JSON.stringify(value)];}function defaultOnMessage(ctx: EveMessageContext): EveMessageResult {diff --git a/packages/eve/src/eve-channel/types.ts b/packages/eve/src/eve-channel/types.tsindex 352446b8e..9dfef74a8 100644--- a/packages/eve/src/eve-channel/types.ts+++ b/packages/eve/src/eve-channel/types.ts@@ -5,6 +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 { FetchFileFunction } from "#shared/channel-definition.js";+import type { JsonObject } from "#shared/json.js";import type {AudienceContext,Channel,@@ -52,10 +53,18 @@ export interface EveChannelCorsOptions {*/export type EveChannelCors = boolean | EveChannelCorsOptions;+/**+ * Turn-scoped context: a string, an array of strings, or a JSON object. The same+ * shape the eve client sends as `clientContext`.+ */+export type ClientContextValue = string | readonly string[] | JsonObject;+/** Low-level eve HTTP handle exposed to `eveChannel({ onMessage })`. */export interface EveHandle {/** Route-auth result for the request; `onMessage` chooses session auth by returning `{ auth }`. */readonly caller: SessionAuthContext | null;+ /** The request's `clientContext`, exactly as the client sent it. `undefined` when it sent none. */+ readonly clientContext?: ClientContextValue;/** Replay-stable identity of a trusted remote-subagent create operation. */readonly invocation?: { readonly operationId: string };readonly request: Request;@@ -74,7 +83,17 @@ export interface EveMessageContext {*/export type EveMessageResult = {readonly auth: SessionAuthContext | null;+ /** Context strings prepended as user messages and kept in session history. */readonly context?: readonly string[];+ /**+ * Context for this turn only, replacing the request's `clientContext`. Like+ * request `clientContext`, it reaches every model call in the turn and is not+ * kept in session history. It takes the same shape as request `clientContext`+ * and becomes model messages the same way, without the `Client context:` label+ * eve adds to client-supplied entries. Return `[]` to drop the request's+ * context; omit it to keep the request's context.+ */+ readonly clientContext?: ClientContextValue;/** Sets the title when creating a workflow or sending its first message after prewarming. */readonly title?: string;};diff --git a/packages/eve/src/public/channels/eve.test.ts b/packages/eve/src/public/channels/eve.test.tsindex e1aa1c69b..ed6d1faef 100644--- a/packages/eve/src/public/channels/eve.test.ts+++ b/packages/eve/src/public/channels/eve.test.ts@@ -18,6 +18,7 @@ import {eveChannel,defaultEveAuth,type EveChannelInput,+ type EveMessageContext,type ForwardedAssertion,type TrustedForwarders,} from "#public/channels/eve.js";@@ -781,6 +782,82 @@ describe("eveChannel — onMessage", () => {expect(options.title).toBe("HTTP run");});+ it("shows onMessage the client's context and lets it replace that context for the turn", async () => {+ const onMessage = vi.fn((ctx: EveMessageContext) => {+ expect(ctx.eve.clientContext).toEqual({ plan: "pro" });+ return { auth: defaultEveAuth(ctx), clientContext: ["Verified plan: hobby"] };+ });+ const handler = createEveCreateHandler({ auth: () => ACCEPTED_AUTH, onMessage });++ const response = await handler.fetch(+ createJsonMessageRequest({ clientContext: { plan: "pro" }, message: "What plan am I on?" }),+ );++ expect(response.status).toBe(202);+ expect(onMessage).toHaveBeenCalledTimes(1);+ const payload = handler.send.mock.calls[0]?.[0] as SendPayload;+ expect(payload).toMatchObject({ message: "What plan am I on?" });+ expect(payload.context).toBeUndefined();+ expect(readClientContext(payload)).toEqual(["Verified plan: hobby"]);+ });++ it("serializes an object returned from onMessage the same way as client objects", async () => {+ const handler = createEveCreateHandler({+ auth: () => ACCEPTED_AUTH,+ onMessage: (ctx) => ({ auth: defaultEveAuth(ctx), clientContext: { plan: "hobby" } }),+ });++ const response = await handler.fetch(+ createJsonMessageRequest({ clientContext: "plan: pro", message: "What plan am I on?" }),+ );++ expect(response.status).toBe(202);+ const payload = handler.send.mock.calls[0]?.[0] as SendPayload;+ expect(readClientContext(payload)).toEqual(['{"plan":"hobby"}']);+ });++ it("shows onMessage no client context when the request sent none", async () => {+ const onMessage = vi.fn((ctx: EveMessageContext) => {+ expect(ctx.eve.clientContext).toBeUndefined();+ return { auth: defaultEveAuth(ctx) };+ });+ const handler = createEveCreateHandler({ auth: () => ACCEPTED_AUTH, onMessage });++ expect((await handler.fetch(createJsonMessageRequest({ message: "hi" }))).status).toBe(202);+ expect(onMessage).toHaveBeenCalledTimes(1);+ expect(readClientContext(handler.send.mock.calls[0]?.[0] as SendPayload)).toBeUndefined();+ });++ it("replaces the client's context on continue requests", async () => {+ const handler = createEveContinueHandler({+ auth: () => ACCEPTED_AUTH,+ onMessage: (ctx) => ({ auth: defaultEveAuth(ctx), clientContext: ["Verified team: acme"] }),+ });++ const response = await handler.fetch(+ createJsonMessageRequest({ clientContext: "team: other", message: "Hello" }),+ );++ expect(response.status).toBe(202);+ const options = handler.send.mock.calls[0]?.[1] as object;+ expect(readClientContext(options)).toEqual(["Verified team: acme"]);+ });++ it("drops the client's context when onMessage returns an empty clientContext", async () => {+ const handler = createEveContinueHandler({+ auth: () => ACCEPTED_AUTH,+ onMessage: (ctx) => ({ auth: defaultEveAuth(ctx), clientContext: [] }),+ });++ const response = await handler.fetch(+ createJsonMessageRequest({ clientContext: "team: other", message: "Hello" }),+ );++ expect(response.status).toBe(202);+ const options = handler.send.mock.calls[0]?.[1] as object;+ expect(readClientContext(options)).toBeUndefined();+ });+it("passes first-message auth, context, and title to a prewarmed session", async () => {const handler = createEveContinueHandler({auth: () => ACCEPTED_AUTH,