Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): client context - prevent history leaks (#2795)

Andrew Barbaaafcb34fea12
diff --git a/.changeset/client-context-turn-scope.md b/.changeset/client-context-turn-scope.md
new file mode 100644
index 000000000..b07ebda98
--- /dev/null
+++ b/.changeset/client-context-turn-scope.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Keep `clientContext` scoped to its model call so earlier client context no longer accumulates in later session turns.
diff --git a/e2e/fixtures/agent-basic-runtime/evals/runtime/client-context.eval.ts b/e2e/fixtures/agent-basic-runtime/evals/runtime/client-context.eval.ts
index f6598aab7..8cc522de1 100644
--- a/e2e/fixtures/agent-basic-runtime/evals/runtime/client-context.eval.ts
+++ b/e2e/fixtures/agent-basic-runtime/evals/runtime/client-context.eval.ts
@@ -1,24 +1,34 @@
import { defineEval } from "eve/evals";
+import { equals } from "eve/evals/expect";
-const CLIENT_CONTEXT_TOKEN = "clientctx-ok-W7R2";
+const FIRST_CLIENT_CONTEXT_TOKEN = "clientctx-first-W7R2";
+const SECOND_CLIENT_CONTEXT_TOKEN = "clientctx-second-P9K4";
/**
* Core session-route runtime behavior: per-turn client context delivery.
*
- * clientContext strings become user-role context messages ahead of the
- * turn message. The prompt directs the model to echo an exact token from
- * the current turn's user batch, so the reply proves delivery.
+ * The first reply omits its context token. The second turn then asks the model
+ * to enumerate the token currently visible, proving that only fresh context
+ * reaches the model while ordinary session history remains durable.
*/
export default defineEval({
tags: ["real-model"],
- description: "Session runtime smoke: client context.",
+ description: "Session runtime smoke: client context stays turn-local.",
async test(t) {
- await t.send("Say hello.", {
- clientContext: [`include the exact token ${CLIENT_CONTEXT_TOKEN} verbatim`],
+ const first = await t.send('Acknowledge this context with exactly "READY".', {
+ clientContext: [`The client context token is ${FIRST_CLIENT_CONTEXT_TOKEN}.`],
});
+ first.messageIncludes("READY");
+
+ const second = await t.send(
+ "Reply with every token beginning with clientctx- that is visible anywhere in your model input, one per line, and nothing else.",
+ {
+ clientContext: [`The client context token is ${SECOND_CLIENT_CONTEXT_TOKEN}.`],
+ },
+ );
t.succeeded();
- t.messageIncludes(CLIENT_CONTEXT_TOKEN);
+ t.check(second.message?.trim(), equals(SECOND_CLIENT_CONTEXT_TOKEN));
},
});
diff --git a/packages/eve/src/channel/adapter.test.ts b/packages/eve/src/channel/adapter.test.ts
index e1a9e2810..2d67b5410 100644
--- a/packages/eve/src/channel/adapter.test.ts
+++ b/packages/eve/src/channel/adapter.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
import type { ChannelAdapter, ChannelAdapterContext, FetchFileResult } from "#channel/adapter.js";
import { callAdapterEventHandler, defaultDeliverResult, getAdapterKind } from "#channel/adapter.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
import { createSessionWaitingEvent } from "#protocol/message.js";
describe("ChannelAdapter (fetchFile field)", () => {
@@ -81,6 +82,18 @@ describe("ChannelAdapter helpers", () => {
});
});
+ it("defaultDeliverResult forwards ephemeral context separately", () => {
+ const ephemeralContext = ["Client context:\ncurrent page"];
+ const result = defaultDeliverResult(attachClientContext({ message: "hi" }, ephemeralContext));
+
+ expect(result).toMatchObject({
+ inputResponses: undefined,
+ message: "hi",
+ context: undefined,
+ });
+ expect(readClientContext(result)).toEqual(ephemeralContext);
+ });
+
it("defaultDeliverResult forwards context with inputResponses payloads", () => {
const context = ["thread background"];
const inputResponses = [{ requestId: "req-1", text: "yes" }];
diff --git a/packages/eve/src/channel/adapter.ts b/packages/eve/src/channel/adapter.ts
index 47b2c6487..1cf535237 100644
--- a/packages/eve/src/channel/adapter.ts
+++ b/packages/eve/src/channel/adapter.ts
@@ -1,5 +1,6 @@
import type { ContextAccessor } from "#context/key.js";
import type { StepInput } from "#harness/types.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
import { createLogger } from "#internal/logging.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { SessionHandle } from "#channel/session.js";
@@ -193,24 +194,36 @@ export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdap
*/
export function defaultDeliverResult(payload: DeliverPayload): StepInput | undefined {
if (payload.message !== undefined) {
- return {
- inputResponses: payload.inputResponses,
- message: payload.message,
- context: payload.context,
- outputSchema: payload.outputSchema,
- };
+ return attachClientContext(
+ {
+ inputResponses: payload.inputResponses,
+ message: payload.message,
+ context: payload.context,
+ outputSchema: payload.outputSchema,
+ },
+ readClientContext(payload),
+ );
}
if (payload.inputResponses !== undefined && payload.inputResponses.length > 0) {
- return {
- inputResponses: payload.inputResponses,
- context: payload.context,
- outputSchema: payload.outputSchema,
- };
+ return attachClientContext(
+ {
+ inputResponses: payload.inputResponses,
+ context: payload.context,
+ outputSchema: payload.outputSchema,
+ },
+ readClientContext(payload),
+ );
}
- if (payload.context !== undefined && payload.context.length > 0) {
- return { context: payload.context, outputSchema: payload.outputSchema };
+ if (
+ (payload.context !== undefined && payload.context.length > 0) ||
+ (readClientContext(payload)?.length ?? 0) > 0
+ ) {
+ return attachClientContext(
+ { context: payload.context, outputSchema: payload.outputSchema },
+ readClientContext(payload),
+ );
}
if (payload.outputSchema !== undefined) {
diff --git a/packages/eve/src/channel/session.test.ts b/packages/eve/src/channel/session.test.ts
index d33cc4515..703bc7ae9 100644
--- a/packages/eve/src/channel/session.test.ts
+++ b/packages/eve/src/channel/session.test.ts
@@ -9,6 +9,7 @@ import {
import type { Runtime } from "#channel/types.js";
import { ContextContainer } from "#context/container.js";
import { AuthKey, ContinuationTokenKey, InitiatorAuthKey, SessionIdKey } from "#context/keys.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
import { type InputResponse, parseInputResponses } from "#shared/input.js";
function fixedSessionRespondTypeChecks(session: Session): void {
@@ -84,6 +85,34 @@ describe("createSession#cancel", () => {
});
describe("fixed session operations", () => {
+ it("dispatches ephemeral context separately from durable channel context", async () => {
+ const runtime = createRuntime();
+ const session = createSession("sess_1", runtime);
+
+ await session.send(
+ "hello",
+ attachClientContext({ auth: null, context: ["durable"] }, ["ephemeral"]),
+ );
+
+ expect(runtime.dispatchSession).toHaveBeenCalledWith({
+ command: {
+ auth: null,
+ kind: "send",
+ payload: expect.objectContaining({
+ context: ["durable"],
+ message: "hello",
+ }),
+ requestId: undefined,
+ turnPolicy: "steer",
+ },
+ sessionId: "sess_1",
+ });
+ const call = vi.mocked(runtime.dispatchSession).mock.calls[0]?.[0];
+ expect(
+ readClientContext(call?.command.kind === "send" ? call.command.payload : undefined),
+ ).toEqual(["ephemeral"]);
+ });
+
it("keeps the session turn policy out of channel delivery metadata", async () => {
const runtime = createRuntime();
const session = createSession("sess_1", runtime, {
diff --git a/packages/eve/src/channel/session.ts b/packages/eve/src/channel/session.ts
index daae6c30b..9e28e4924 100644
--- a/packages/eve/src/channel/session.ts
+++ b/packages/eve/src/channel/session.ts
@@ -29,6 +29,7 @@ import {
} from "#shared/input.js";
import type { JsonObject } from "#shared/json.js";
import { toChannelLocalContinuationToken } from "#shared/continuation-token.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
/** Immutable-ID handle for one exact durable session. */
export interface Session {
@@ -96,11 +97,11 @@ export function createSession(
async send(message, options) {
const delivery = createDelivery(metadata);
const caller = sessionCallbackToTurnCaller(options.callback, options.activityObserver);
- const payload: {
+ const payload = attachClientContext<{
context?: readonly string[];
message: string | UserContent | undefined;
outputSchema?: JsonObject;
- } = { message: serializeUrlFilePartsInMessage(message) };
+ }>({ message: serializeUrlFilePartsInMessage(message) }, readClientContext(options));
if (options.context !== undefined) payload.context = options.context;
if (options.outputSchema !== undefined) payload.outputSchema = options.outputSchema;
const commandWithoutCaller = {
@@ -123,11 +124,11 @@ export function createSession(
const validatedInputResponses = parseInputResponses(inputResponses);
const caller = sessionCallbackToTurnCaller(options.callback, options.activityObserver);
const delivery = createDelivery(metadata);
- const payload: {
+ const payload = attachClientContext<{
context?: readonly string[];
inputResponses: readonly InputResponse[];
outputSchema?: JsonObject;
- } = { inputResponses: validatedInputResponses };
+ }>({ inputResponses: validatedInputResponses }, readClientContext(options));
if (options.context !== undefined) payload.context = options.context;
if (options.outputSchema !== undefined) payload.outputSchema = options.outputSchema;
const commandWithoutCaller = {
diff --git a/packages/eve/src/eve-channel/index.ts b/packages/eve/src/eve-channel/index.ts
index b7656fece..ff8979893 100644
--- a/packages/eve/src/eve-channel/index.ts
+++ b/packages/eve/src/eve-channel/index.ts
@@ -53,7 +53,6 @@ import {
checkUploadPolicy,
createSessionStreamResponse,
deriveOperationContinuationToken,
- mergeContext,
parseCancelTurnBody,
parseCreateBody,
parseIncludeTailIndex,
@@ -65,6 +64,7 @@ import {
rejectSessionContinuationToken,
requireSessionId,
} from "#eve-channel/request.js";
+import { attachClientContext } from "#internal/client-context.js";
import {
findRemoteSubagentBinding,
healthResponse,
@@ -201,11 +201,14 @@ export function eveChannel(input: EveChannelInput): EveChannel {
callback: body.callback,
continuationToken: operationToken,
initiatorAuth: forwarded.accepted ? forwarded.initiatorAuth : undefined,
- input: {
- message: body.message,
- context: mergeContext(body.context, messageResult.context),
- outputSchema: body.outputSchema,
- },
+ input: attachClientContext(
+ {
+ message: body.message,
+ context: messageResult.context,
+ outputSchema: body.outputSchema,
+ },
+ body.context,
+ ),
mode: body.mode ?? "conversation",
parentTraceContext,
title: messageResult.title,
@@ -264,7 +267,7 @@ export function eveChannel(input: EveChannelInput): EveChannel {
const policyRejection = checkUploadPolicy(body, uploadPolicy);
if (policyRejection !== null) return policyRejection;
- let context = body.context;
+ let context: readonly string[] | undefined;
let dispatchAuth: SessionAuthContext | null = forwarded.auth;
if (body.message !== undefined) {
const messageResult = await resolveOnMessage({
@@ -275,21 +278,24 @@ export function eveChannel(input: EveChannelInput): EveChannel {
sessionId,
});
if (messageResult instanceof Response) return messageResult;
- context = mergeContext(body.context, messageResult.context);
+ context = messageResult.context;
dispatchAuth = messageResult.auth;
}
let result: Awaited<ReturnType<Session["send"]>>;
try {
const session = attachSession(sessionId);
- const options = {
- activityObserver: body.activityObserver,
- auth: dispatchAuth,
- callback: body.callback,
- context,
- outputSchema: body.outputSchema,
- turnPolicy: body.turnPolicy,
- };
+ const options = attachClientContext(
+ {
+ activityObserver: body.activityObserver,
+ auth: dispatchAuth,
+ callback: body.callback,
+ context,
+ outputSchema: body.outputSchema,
+ turnPolicy: body.turnPolicy,
+ },
+ body.context,
+ );
result =
body.inputResponses === undefined
? await session.send(body.message!, options)
diff --git a/packages/eve/src/eve-channel/request.ts b/packages/eve/src/eve-channel/request.ts
index bf0804907..2499e2873 100644
--- a/packages/eve/src/eve-channel/request.ts
+++ b/packages/eve/src/eve-channel/request.ts
@@ -523,15 +523,6 @@ function parseInputResponses(
return inputResponses;
}
-export function mergeContext(
- existing: readonly string[] | undefined,
- added: readonly string[] | undefined,
-): readonly string[] | undefined {
- if (existing === undefined) return added;
- if (added === undefined) return existing;
- return [...existing, ...added];
-}
-
const CLIENT_CONTEXT_PREFIX = "Client context:\n";
function parseClientContextField(value: unknown): string[] | Response | undefined {
diff --git a/packages/eve/src/execution/workflow-entry.ts b/packages/eve/src/execution/workflow-entry.ts
index 8f9c76e4c..408be82a4 100644
--- a/packages/eve/src/execution/workflow-entry.ts
+++ b/packages/eve/src/execution/workflow-entry.ts
@@ -47,6 +47,7 @@ import { readSerializedSubagentDepth } from "#harness/subagent-depth.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
import type { TokenUsage } from "#shared/token-usage.js";
import { isTaskOwnedSerializedContext } from "#execution/tasks/child/instructions.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
const SAFE_OUTER_WORKFLOW_FAILURE_MESSAGE =
"Agent workflow failed. Inspect the private session trace for details.";
@@ -203,11 +204,14 @@ export async function workflowEntry(input: WorkflowEntryInput): Promise<Workflow
],
kind: "deliver",
payloads: [
- {
- message: input.input.message,
- context: input.input.context,
- outputSchema: input.input.outputSchema,
- },
+ attachClientContext(
+ {
+ message: input.input.message,
+ context: input.input.context,
+ outputSchema: input.input.outputSchema,
+ },
+ readClientContext(input.input),
+ ),
],
requestId: readChannelRequestId(input.serializedContext),
},
diff --git a/packages/eve/src/harness/hitl/pending-input-resolution.ts b/packages/eve/src/harness/hitl/pending-input-resolution.ts
index 4fa5d51ef..012214bf8 100644
--- a/packages/eve/src/harness/hitl/pending-input-resolution.ts
+++ b/packages/eve/src/harness/hitl/pending-input-resolution.ts
@@ -6,6 +6,7 @@ import type { ResolvedInputBatch } from "#harness/input-request-resolution.js";
import type { PendingInputBatch, PendingInputBatchEvent } from "#harness/pending-input-batches.js";
import { queueDeferredStepInput } from "#harness/pending-input-batches.js";
import type { HarnessSession, StepInput } from "#harness/types.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
export type ToolResponsePart = Extract<ModelMessage, { role: "tool" }>["content"][number];
@@ -78,6 +79,7 @@ export function finishResolvedInput(input: {
inputResponses?: StepInput["inputResponses"];
message?: StepInput["message"];
} = {};
+ let clientContext: readonly string[] | undefined;
if (input.leftoverResponses.length > 0) {
deferredInput.inputResponses = input.leftoverResponses;
}
@@ -85,15 +87,23 @@ export function finishResolvedInput(input: {
if ((input.resolvedStepInput?.context?.length ?? 0) > 0) {
deferredInput.context = input.resolvedStepInput?.context;
}
+ const resolvedClientContext = readClientContext(input.resolvedStepInput);
+ if ((resolvedClientContext?.length ?? 0) > 0) {
+ clientContext = resolvedClientContext;
+ }
if (input.resolvedStepInput?.message !== undefined) {
deferredInput.message = input.resolvedStepInput.message;
}
}
+ attachClientContext(deferredInput, clientContext);
if (Object.keys(deferredInput).length > 0) {
return {
consumedMessage: input.resolvedStepInput?.messageConsumed,
- deferredContext: deferredInput.context === undefined ? undefined : true,
+ deferredContext:
+ deferredInput.context === undefined && readClientContext(deferredInput) === undefined
+ ? undefined
+ : true,
deferredMessage: deferredInput.message === undefined ? undefined : true,
limitContinuation: input.limitContinuation,
outcome: "resolved",
@@ -134,5 +144,5 @@ export function compactStepInput(input: ResolvedStepInput | undefined): Resolved
if (input.messageConsumed === true) result.messageConsumed = true;
if (input.outputSchema !== undefined) result.outputSchema = input.outputSchema;
- return result;
+ return attachClientContext(result, readClientContext(input));
}
diff --git a/packages/eve/src/harness/input-requests.ts b/packages/eve/src/harness/input-requests.ts
index 6edd4c10b..bf30095ee 100644
--- a/packages/eve/src/harness/input-requests.ts
+++ b/packages/eve/src/harness/input-requests.ts
@@ -25,6 +25,7 @@ import {
resolveSessionLimitInput,
} from "#harness/hitl/session-limit-input-requests.js";
import type { HarnessSession, StepInput } from "#harness/types.js";
+import { readClientContext } from "#internal/client-context.js";
export { getApprovedTools, clearPendingSessionLimitPrompt };
export type { RejectedActionBatch };
@@ -97,7 +98,9 @@ export function resolvePendingInput(input: {
if (responses.length === 0 && resolvedStepInput?.message === undefined) {
const deferredInput = compactStepInput(resolvedStepInput);
const session =
- deferredInput.context !== undefined || deferredInput.outputSchema !== undefined
+ deferredInput.context !== undefined ||
+ readClientContext(deferredInput) !== undefined ||
+ deferredInput.outputSchema !== undefined
? queueDeferredStepInput(input.session, deferredInput)
: input.session;
return { outcome: "unresolved", messages: baseHistory, session };
diff --git a/packages/eve/src/harness/messages.test.ts b/packages/eve/src/harness/messages.test.ts
index 0f7c188ae..1470cd036 100644
--- a/packages/eve/src/harness/messages.test.ts
+++ b/packages/eve/src/harness/messages.test.ts
@@ -8,6 +8,7 @@ import {
resolveAssistantStepText,
} from "#harness/messages.js";
import type { StepInput } from "#harness/types.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
function textFilePart(overrides: {
readonly filename: string;
@@ -110,6 +111,16 @@ describe("coalesceTurnInputs", () => {
});
});
+ it("coalesces ephemeral context without making it durable context", () => {
+ const result = coalesceTurnInputs(
+ attachClientContext({}, ["first"]),
+ attachClientContext({}, ["second"]),
+ );
+
+ expect(readClientContext(result)).toEqual(["first", "second"]);
+ expect(result.context).toBeUndefined();
+ });
+
it("combines messages and inputResponses", () => {
const result = coalesceTurnInputs(
{ message: "hello", inputResponses: [{ requestId: "r1", optionId: "approve" }] },
diff --git a/packages/eve/src/harness/messages.ts b/packages/eve/src/harness/messages.ts
index acf4ab453..f154d0394 100644
--- a/packages/eve/src/harness/messages.ts
+++ b/packages/eve/src/harness/messages.ts
@@ -8,6 +8,7 @@ import type {
} from "#channel/types.js";
import type { InputResponse } from "#shared/input.js";
import type { StepInput } from "#harness/types.js";
+import { attachClientContext, readClientContext } from "#internal/client-context.js";
/**
* Merges two {@link StepInput} values into one.
@@ -29,6 +30,10 @@ export function coalesceTurnInputs(a: StepInput, b: StepInput): StepInput {
a: a.context,
b: b.context,
});
+ const ephemeralContext = coalesceContext({
+ a: readClientContext(a),
+ b: readClientContext(b),
+ });
const outputSchema = b.outputSchema ?? a.outputSchema;
const result: {
@@ -54,7 +59,7 @@ export function coalesceTurnInputs(a: StepInput, b: StepInput): StepInput {
result.outputSchema = outputSchema;
}
- return result;
+ return attachClientContext(result, ephemeralContext);
}
/**
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 8d503de79..75f52335d 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -35,6 +35,7 @@ import {
import { SCHEDULE_APP_AUTH } from "#channel/schedule-auth.js";
import { invocationOwnerKey } from "#internal/invocation/metadata.js";
import { decodeSandboxRef, isSandboxRefUrl } from "#internal/attachments/sandbox-refs.js";
+import { attachClientContext } from "#internal/client-context.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type {
@@ -8584,7 +8585,7 @@ describe("createToolLoopHarness", () => {
]);
});
- it("keeps channel context after the approval-response model call", async () => {
+ it("defers durable and ephemeral context past the approval-response model call", async () => {
setupMockAgent({
finishReason: "stop",
response: { messages: [{ content: "Approved.", role: "assistant" }] },
@@ -8645,16 +8646,24 @@ describe("createToolLoopHarness", () => {
});
const harness = createToolLoopHarness(config);
const context = "<linear_context>issue metadata</linear_context>";
+ const ephemeralContext = "Client context:\ncurrent page";
- const firstResult = await harness(createPendingBashApprovalSession(), {
- context: [context],
- inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
- });
+ const firstResult = await harness(
+ createPendingBashApprovalSession(),
+ attachClientContext(
+ {
+ context: [context],
+ inputResponses: [{ requestId: "approval-1", optionId: "approve" }],
+ },
+ [ephemeralContext],
+ ),
+ );
const firstMessages = readGenerateMessages(0);
expect(typeof firstResult.next).toBe("function");
expect(firstMessages.at(-1)?.role).toBe("tool");
expect(firstMessages).not.toContainEqual({ content: context, role: "user" });
+ expect(firstMessages).not.toContainEqual({ content: ephemeralContext, role: "user" });
expect((await readPreparedMessages(0)).at(-1)).toMatchObject({
providerOptions: {
anthropic: { cacheControl: { type: "ephemeral" } },
@@ -8667,7 +8676,10 @@ describe("createToolLoopHarness", () => {
const secondMessages = readGenerateMessages(1);
expect(secondResult.next).toBeNull();
expect(secondMessages.slice(0, firstMessages.length)).toEqual(firstMessages);
- expect(secondMessages.at(-1)).toEqual({ content: context, role: "user" });
+ expect(secondMessages.slice(-2)).toEqual([
+ { content: ephemeralContext, role: "user" },
+ { content: context, role: "user" },
+ ]);
expect((await readPreparedMessages(1)).at(-1)).toMatchObject({
content: context,
providerOptions: {
@@ -8675,6 +8687,10 @@ describe("createToolLoopHarness", () => {
},
role: "user",
});
+ expect(secondResult.session.history).not.toContainEqual({
+ content: ephemeralContext,
+ role: "user",
+ });
});
it("follow-up message precedes a late approval denial in committed history", async () => {
@@ -12013,7 +12029,7 @@ describe("createToolLoopHarness", () => {
});
});
- describe("ephemeral context routing", () => {
+ describe("context routing", () => {
function getLastAgentSettings(): {
instructions: unknown;
messages: Array<{ role: string; content: unknown }>;
@@ -12041,7 +12057,7 @@ describe("createToolLoopHarness", () => {
};
}
- it("appends context strings as user messages", async () => {
+ it("appends durable channel context as user messages", async () => {
setupMockAgent(defaultModelResult());
const runStep = createToolLoopHarness(createTestConfig("conversation"));
const session = createTestSession();
@@ -12092,6 +12108,68 @@ describe("createToolLoopHarness", () => {
]);
});
+ it("does not replay ephemeral client context on later turns", async () => {
+ setupMockAgent(defaultModelResult());
+ const runStep = createToolLoopHarness(createTestConfig("conversation"));
+ let session = createTestSession();
+
+ for (const token of ["CTX-A", "CTX-B", "CTX-C"]) {
+ const clientContext = `Client context:\n${token}`;
+ const result = await runStep(
+ session,
+ attachClientContext({ message: `Turn ${token}` }, [clientContext]),
+ );
+ const visibleClientContext = getLastAgentSettings().messages.filter(
+ (message) =>
+ typeof message.content === "string" && message.content.startsWith("Client context:"),
+ );
+
+ expect(visibleClientContext).toEqual([{ content: clientContext, role: "user" }]);
+ expect(result.session.history).not.toContainEqual({
+ content: clientContext,
+ role: "user",
+ });
+ session = result.session;
+ }
+ });
+
+ it("keeps ephemeral client context out of compaction and its token baseline", async () => {
+ vi.mocked(shouldCompact).mockReturnValueOnce(true);
+ vi.mocked(compactMessages).mockImplementationOnce(async (messages) => [...messages]);
+ setupMockAgent({
+ ...defaultModelResult(),
+ usage: { inputTokens: 321 },
+ });
+ const runStep = createToolLoopHarness(createTestConfig("conversation"));
+ const session = createTestSession({
+ history: [{ content: "earlier", role: "user" }],
+ });
+
+ const result = await runStep(
+ session,
+ attachClientContext({ message: "Hi" }, ["Client context:\ncurrent"]),
+ );
+
+ expect(vi.mocked(shouldCompact)).toHaveBeenCalledWith(
+ [
+ { content: "earlier", role: "user" },
+ { content: "Client context:\ncurrent", role: "user" },
+ { content: "Hi", role: "user" },
+ ],
+ session.compaction,
+ );
+ expect(vi.mocked(compactMessages).mock.calls[0]?.[0]).toEqual([
+ { content: "earlier", role: "user" },
+ { content: "Hi", role: "user" },
+ ]);
+ expect(result.session.history).not.toContainEqual({
+ content: "Client context:\ncurrent",
+ role: "user",
+ });
+ expect(result.session.compaction).not.toHaveProperty("lastKnownInputTokens");
+ expect(result.session.compaction).not.toHaveProperty("lastKnownPromptMessageCount");
+ });
+
it("leaves instructions unchanged when no context is provided", async () => {
setupMockAgent(defaultModelResult());
const runStep = createToolLoopHarness(createTestConfig("conversation"));
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 3af54ca2b..b5b4ee5cd 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -14,6 +14,7 @@ import {
} from "ai";
import type { SessionAuthContext } from "#channel/types.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { readClientContext } from "#internal/client-context.js";
import { resolveProviderHeaders } from "#internal/gateway.js";
import { createErrorId, createLogger, formatError, logError } from "#internal/logging.js";
import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
@@ -926,6 +927,11 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// --- Turn preamble ------------------------------------------------------
+ const clientContext = readClientContext(effectiveStepInput);
+ const ephemeralContextMessages: ModelMessage[] =
+ clientContext === undefined || pending.deferredContext === true
+ ? []
+ : clientContext.map((content) => ({ content, role: "user" }));
const preparedTurnInput: ModelMessage[] = [];
if (effectiveStepInput?.context !== undefined && pending.deferredContext !== true) {
for (const entry of effectiveStepInput.context) {
@@ -951,7 +957,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
);
prepareMemoryPreamble(store, {
history: pending.messages,
- input: preparedTurnInput,
+ input: [...ephemeralContextMessages, ...preparedTurnInput],
state: pending.session.state,
});
}
@@ -1039,7 +1045,17 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
messages = [...messages, ...preparedTurnInput];
- let projectedMessages = projectHistory(messages, session.state);
+ const createModelMessages = (durableMessages: readonly ModelMessage[]): ModelMessage[] => {
+ if (ephemeralContextMessages.length === 0) return [...durableMessages];
+
+ const insertionIndex = Math.max(0, durableMessages.length - preparedTurnInput.length);
+ return [
+ ...durableMessages.slice(0, insertionIndex),
+ ...ephemeralContextMessages,
+ ...durableMessages.slice(insertionIndex),
+ ];
+ };
+ let projectedMessages = projectHistory(createModelMessages(messages), session.state);
// --- Model + tools ------------------------------------------------------
@@ -1090,6 +1106,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
messages: [...messages],
model,
onCompaction: config.onCompaction,
+ promptMessages: createModelMessages(messages),
resolveModel: config.resolveModel,
runtimeIdentity: config.runtimeIdentity,
session,
@@ -1099,7 +1116,9 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
if (compaction.compacted) {
messages = compaction.messages;
}
- projectedMessages = normalizeModelMessages(projectHistory(messages, session.state));
+ projectedMessages = normalizeModelMessages(
+ projectHistory(createModelMessages(messages), session.state),
+ );
if (emit) {
await emitStepStarted(
@@ -1745,7 +1764,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
emit,
emissionState,
delegatedCaller: taskUpdatesEnabled,
- modelPromptMessageCount: projectedMessages.length,
+ durableModelPromptMessageCount:
+ ephemeralContextMessages.length === 0 ? projectedMessages.length : undefined,
promptMessages: messages,
result,
runStep,
@@ -2276,7 +2296,7 @@ async function handleStepResult(input: {
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly delegatedCaller: boolean;
- readonly modelPromptMessageCount: number;
+ readonly durableModelPromptMessageCount?: number;
readonly promptMessages: readonly ModelMessage[];
readonly result: HarnessStepResult;
readonly runStep: StepFn;
@@ -2331,7 +2351,7 @@ async function handleStepResult(input: {
...session,
compaction: createNextCompactionConfig(
session.compaction,
- input.modelPromptMessageCount,
+ input.durableModelPromptMessageCount,
result,
),
};
@@ -2994,7 +3014,7 @@ async function parkOnWorkflowInterrupt(input: {
function createNextCompactionConfig(
current: CompactionConfig,
- promptMessageCount: number,
+ durablePromptMessageCount: number | undefined,
result: HarnessStepResult,
): CompactionConfig {
const next: {
@@ -3009,9 +3029,9 @@ function createNextCompactionConfig(
thresholdPercent: current.thresholdPercent,
};
- if (result.usage?.inputTokens !== undefined) {
+ if (result.usage?.inputTokens !== undefined && durablePromptMessageCount !== undefined) {
next.lastKnownInputTokens = result.usage.inputTokens;
- next.lastKnownPromptMessageCount = promptMessageCount;
+ next.lastKnownPromptMessageCount = durablePromptMessageCount;
}
return next;
@@ -3036,6 +3056,8 @@ async function maybeCompact(input: {
readonly messages: ModelMessage[];
readonly model: LanguageModel;
readonly onCompaction?: ToolLoopHarnessConfig["onCompaction"];
+ /** Model-visible prompt used only to decide whether durable history needs compaction. */
+ readonly promptMessages?: readonly ModelMessage[];
readonly resolveModel: ToolLoopHarnessConfig["resolveModel"];
readonly runtimeIdentity?: ToolLoopHarnessConfig["runtimeIdentity"];
readonly session: HarnessSession;
@@ -3048,9 +3070,11 @@ async function maybeCompact(input: {
const { emit, emissionState } = input;
let messages = input.messages;
let session = input.session;
- const projectedMessages =
- input.historyProjector?.({ messages, state: session.state }) ?? messages;
- const needsSummary = input.force === true || shouldCompact(projectedMessages, session.compaction);
+ const promptMessages = input.promptMessages ?? messages;
+ const projectedPromptMessages =
+ input.historyProjector?.({ messages: promptMessages, state: session.state }) ?? promptMessages;
+ const needsSummary =
+ input.force === true || shouldCompact(projectedPromptMessages, session.compaction);
const needsMemoryCanonicalization = shouldCanonicalizeMemory(messages);
if (!needsSummary && !needsMemoryCanonicalization) {
@@ -3082,9 +3106,9 @@ async function maybeCompact(input: {
sequence: emissionState.sequence,
sessionId: session.sessionId,
turnId: emissionState.turnId,
- usageInputTokens: getInputTokenCount(projectedMessages, session.compaction),
+ usageInputTokens: getInputTokenCount(projectedPromptMessages, session.compaction),
}),
- projectedMessages,
+ projectedPromptMessages,
);
}
diff --git a/packages/eve/src/internal/client-context.ts b/packages/eve/src/internal/client-context.ts
new file mode 100644
index 000000000..903d97992
--- /dev/null
+++ b/packages/eve/src/internal/client-context.ts
@@ -0,0 +1,19 @@
+const clientContextKey = "__eveClientContext";
+
+type ClientContextCarrier = {
+ [clientContextKey]?: readonly string[];
+};
+
+export function attachClientContext<T extends object>(
+ target: T,
+ context: readonly string[] | undefined,
+): T {
+ if (context !== undefined) {
+ (target as T & ClientContextCarrier)[clientContextKey] = context;
+ }
+ return target;
+}
+
+export function readClientContext(target: object | undefined): readonly string[] | undefined {
+ return (target as ClientContextCarrier | undefined)?.[clientContextKey];
+}
diff --git a/packages/eve/src/public/channels/eve.test.ts b/packages/eve/src/public/channels/eve.test.ts
index 280ec7687..0c540a7ed 100644
--- a/packages/eve/src/public/channels/eve.test.ts
+++ b/packages/eve/src/public/channels/eve.test.ts
@@ -5,6 +5,7 @@ import { buildAdapterContext } from "#channel/adapter-context.js";
import { callAdapterEventHandler, type ChannelAdapter } from "#channel/adapter.js";
import { isCompiledChannel } from "#channel/compiled-channel.js";
import { RuntimeSessionOwnershipConflictError } from "#execution/runtime-errors.js";
+import { readClientContext } from "#internal/client-context.js";
import { attachRouteSessionCreator } from "#internal/nitro/routes/channel-route-context.js";
import { mockChannelContext } from "#internal/testing/mocks/mock-channel-operations.js";
import { type AuthFn, none } from "#public/channels/auth.js";
@@ -125,7 +126,9 @@ function createEveCreateHandler(
const mockSend = vi.fn().mockResolvedValue(createMockSession());
const createSession = vi.fn(async (runInput: RunInput) => {
const payload =
- runInput.input.context === undefined && runInput.input.outputSchema === undefined
+ runInput.input.context === undefined &&
+ readClientContext(runInput.input) === undefined &&
+ runInput.input.outputSchema === undefined
? runInput.input.message
: runInput.input;
await mockSend(payload, {
@@ -652,7 +655,7 @@ describe("eveChannel — stream cursor", () => {
});
describe("eveChannel — onMessage", () => {
- it("runs after auth on create requests and appends returned context", async () => {
+ it("runs after auth on create requests and keeps returned context durable", async () => {
const onMessage = vi.fn((ctx, message) => {
expect(ctx.eve.caller).toEqual(ACCEPTED_AUTH);
expect(defaultEveAuth(ctx)).toEqual(ACCEPTED_AUTH);
@@ -681,10 +684,11 @@ describe("eveChannel — onMessage", () => {
expect(onMessage).toHaveBeenCalledTimes(1);
expect(handler.send).toHaveBeenCalledTimes(1);
const payload = handler.send.mock.calls[0]?.[0] as SendPayload;
- expect(payload).toEqual({
+ expect(payload).toMatchObject({
message: "What word is selected?",
- context: ["Client context:\nselection: jazz", "Authenticated caller profile: enterprise"],
+ context: ["Authenticated caller profile: enterprise"],
});
+ expect(readClientContext(payload)).toEqual(["Client context:\nselection: jazz"]);
const options = handler.send.mock.calls[0]?.[1] as MockSendOptions;
expect(options.auth).toEqual(ACCEPTED_AUTH);
expect(options.title).toBe("HTTP run");
@@ -1197,10 +1201,8 @@ describe("eveChannel — create session (text)", () => {
expect(response.status).toBe(202);
expect(handler.send).toHaveBeenCalledTimes(1);
const payload = handler.send.mock.calls[0]?.[0] as SendPayload;
- expect(payload).toEqual({
- message: "What word is selected?",
- context: ['Client context:\n{"selectedWord":"jazz"}'],
- });
+ expect(payload).toMatchObject({ message: "What word is selected?" });
+ expect(readClientContext(payload)).toEqual(['Client context:\n{"selectedWord":"jazz"}']);
});
it("forwards outputSchema with a create-session message", async () => {
@@ -1254,7 +1256,7 @@ describe("eveChannel — create session (text)", () => {
expect(response.status).toBe(202);
expect(handler.send).toHaveBeenCalledTimes(1);
const payload = handler.send.mock.calls[0]?.[0] as SendPayload;
- expect(payload.context).toEqual([
+ expect(readClientContext(payload)).toEqual([
"Client context:\nroute: /editor",
"Client context:\nselection: jazz",
]);
@@ -1600,10 +1602,10 @@ describe("eveChannel — continue session HITL (inputResponses)", () => {
);
expect(response.status).toBe(202);
- expect(handler.send).toHaveBeenCalledWith(
- "yes please",
- expect.objectContaining({ context: ["Client context:\napproval modal open"] }),
- );
+ expect(handler.send).toHaveBeenCalledWith("yes please", expect.any(Object));
+ expect(readClientContext(handler.send.mock.calls[0]?.[1])).toEqual([
+ "Client context:\napproval modal open",
+ ]);
});
it("forwards outputSchema with a continue-session message", async () => {