Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.
+
## Clients
The 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 === undefined
diff --git a/packages/eve/src/eve-channel/request.ts b/packages/eve/src/eve-channel/request.ts
index 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 | undefine
try {
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.ts
index 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.ts
index 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.ts
index 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,