Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

[2/2] refactor(eve): run compaction summaries as model calls (#4550)

Ben Pankow6189eea5ee7e
diff --git a/.changeset/compaction-model-call.md b/.changeset/compaction-model-call.md
new file mode 100644
index 000000000..7a328ff7c
--- /dev/null
+++ b/.changeset/compaction-model-call.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Context compaction now calls its model the way a step does: it streams the summary, retries transient provider failures with the same policy, and counts the summary call's tokens and cost toward session usage limits. Automatic compaction reports that usage with the turn it ran in. Manual compaction runs between turns, so it counts toward session totals without being added to the next turn's usage.
diff --git a/packages/eve/src/harness/compaction/engine.test.ts b/packages/eve/src/harness/compaction/engine.test.ts
index 49ca49214..d3915e20d 100644
--- a/packages/eve/src/harness/compaction/engine.test.ts
+++ b/packages/eve/src/harness/compaction/engine.test.ts
@@ -1,27 +1,14 @@
import type { ModelMessage } from "ai";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
import { COMPACTION_PROMPT_ENVELOPE } from "#harness/compaction/prompt.js";
-import {
- compactMessages,
- getInputTokenCount,
- resolveCompactionModel,
- shouldCompact,
-} from "#harness/compaction/engine.js";
+import { compactMessages, getInputTokenCount, shouldCompact } from "#harness/compaction/engine.js";
import { createFrameworkUserMessage } from "#harness/messages.js";
import { estimateTokens } from "#harness/token-estimate.js";
import type { CompactionConfig } from "#harness/types.js";
import { encodeSandboxRef } from "#internal/attachments/sandbox-refs.js";
import { pngBytes } from "#internal/testing/media-fixtures.js";
-vi.mock("ai", () => ({
- generateText: vi.fn(),
-}));
-
-afterEach(() => {
- vi.clearAllMocks();
-});
-
const config: CompactionConfig = {
recentWindowSize: 2,
threshold: 100,
@@ -342,59 +329,6 @@ describe("shouldCompact", () => {
});
});
-describe("resolveCompactionModel", () => {
- it("reuses the active model when compaction uses the same reference", async () => {
- const model = {} as Parameters<typeof resolveCompactionModel>[0]["model"];
- const resolveModel = vi.fn();
-
- const result = await resolveCompactionModel({
- model,
- modelReference: { id: "main", providerOptions: { openai: { reasoning: { effort: "low" } } } },
- resolveModel,
- });
-
- expect(result.model).toBe(model);
- expect(result.providerOptions).toEqual({
- openai: { reasoning: { effort: "low" } },
- });
- expect(resolveModel).not.toHaveBeenCalled();
- });
-
- it("resolves the authored compaction model when configured", async () => {
- const model = {} as Parameters<typeof resolveCompactionModel>[0]["model"];
- const summaryModel = {} as Parameters<typeof resolveCompactionModel>[0]["model"];
- const resolveModel = vi.fn().mockResolvedValue(summaryModel);
-
- const compactionModelReference = {
- id: "summary",
- providerOptions: {
- anthropic: {
- thinking: {
- budget_tokens: 128,
- },
- },
- },
- } as Parameters<typeof resolveCompactionModel>[0]["compactionModelReference"];
-
- const result = await resolveCompactionModel({
- compactionModelReference,
- model,
- modelReference: { id: "main" },
- resolveModel,
- });
-
- expect(result.model).toBe(summaryModel);
- expect(result.providerOptions).toEqual({
- anthropic: {
- thinking: {
- budget_tokens: 128,
- },
- },
- });
- expect(resolveModel).toHaveBeenCalledWith(compactionModelReference);
- });
-});
-
// --- compactMessages ---------------------------------------------------
//
// compactMessages escalates through heuristics before summarizing, and which
@@ -491,12 +425,8 @@ function expectWellFormedCompaction(result: ModelMessage[], threshold: number):
async function compact(
messages: ModelMessage[],
overrides: Partial<CompactionConfig> & { readonly summary?: string } = {},
-): Promise<{ result: ModelMessage[]; summarizer: ReturnType<typeof vi.mocked<never>> }> {
- const { generateText } = await import("ai");
- const summarizer = vi.mocked(generateText);
- summarizer.mockResolvedValue({
- text: overrides.summary ?? "checkpoint text",
- } as Awaited<ReturnType<typeof generateText>>);
+): Promise<{ result: ModelMessage[]; summarizer: ReturnType<typeof summarizeWith> }> {
+ const summarizer = summarizeWith(overrides.summary ?? "checkpoint text");
const compactionConfig: CompactionConfig = {
lastKnownInputTokens: overrides.lastKnownInputTokens,
@@ -504,14 +434,16 @@ async function compact(
recentWindowSize: overrides.recentWindowSize ?? 4,
threshold: overrides.threshold ?? ROOMY,
};
- const result = await compactMessages(
- messages,
- {} as Parameters<typeof compactMessages>[1],
- compactionConfig,
- );
+ const result = await compactMessages(messages, compactionConfig, summarizer);
expectWellFormedCompaction(result, compactionConfig.threshold);
- return { result, summarizer: summarizer as ReturnType<typeof vi.mocked<never>> };
+ return { result, summarizer };
+}
+
+function summarizeWith(summary: string) {
+ return vi.fn(
+ async (_prompt: { readonly messages: ModelMessage[]; readonly system: string }) => summary,
+ );
}
describe("compactMessages: tool-result cap heuristic", () => {
@@ -582,42 +514,31 @@ describe("compactMessages: tool-result cap heuristic", () => {
},
);
it("credits removed history against an explicit history-only token floor", async () => {
- const { generateText } = await import("ai");
+ const summarize = summarizeWith("summary");
const [call, resultMsg] = toolExchange({ callId: "large", payloadChars: 40_000 });
const messages = [user("investigate"), call, resultMsg, user("continue")];
const result = await compactMessages(
messages,
- {} as Parameters<typeof compactMessages>[1],
{ threshold: 10_000, recentWindowSize: 1 },
- undefined,
- undefined,
- undefined,
- undefined,
+ summarize,
false,
15_000,
);
- expect(generateText).not.toHaveBeenCalled();
+ expect(summarize).not.toHaveBeenCalled();
expect(estimateTokens(result)).toBeLessThan(2_000);
expect(result.map((entry) => entry.role)).toEqual(messages.map((entry) => entry.role));
});
it("summarizes when a no-op cannot satisfy the explicit history-only token floor", async () => {
- const { generateText } = await import("ai");
- vi.mocked(generateText).mockResolvedValue({ text: "summary" } as Awaited<
- ReturnType<typeof generateText>
- >);
+ const summarize = summarizeWith("summary");
await compactMessages(
[user("earlier"), assistant("reply"), user("continue")],
- {} as Parameters<typeof compactMessages>[1],
{ threshold: 2_000, recentWindowSize: 0 },
- undefined,
- undefined,
- undefined,
- undefined,
+ summarize,
false,
8_000,
);
- expect(generateText).toHaveBeenCalledOnce();
+ expect(summarize).toHaveBeenCalledOnce();
});
it("caps oversized older tool results in place without calling the summarizer", async () => {
@@ -885,80 +806,18 @@ describe("compactMessages: tool-result cap heuristic", () => {
});
describe("compactMessages: forced summary", () => {
- it("uses the model's default temperature when summarizing", async () => {
- const { generateText } = await import("ai");
- const summarizer = vi.mocked(generateText);
- summarizer.mockResolvedValue({
- text: "forced checkpoint",
- } as Awaited<ReturnType<typeof generateText>>);
-
- await compactMessages(
- [user("old message"), assistant("old reply")],
- {} as Parameters<typeof compactMessages>[1],
- { recentWindowSize: 10, threshold: ROOMY },
- undefined,
- undefined,
- undefined,
- undefined,
- true,
- );
-
- expect(summarizer).toHaveBeenCalledOnce();
- expect(summarizer.mock.calls[0]?.[0]).not.toHaveProperty("temperature");
- });
-
- it.each(["", " \n\t"])(
- "rejects a blank checkpoint without replacing history (%j)",
- async (text) => {
- const { generateText } = await import("ai");
- vi.mocked(generateText).mockResolvedValue({
- finishReason: "content-filter",
- text,
- } as Awaited<ReturnType<typeof generateText>>);
- const messages = [
- user("Keep the original request."),
- assistant("Work is in progress."),
- user("A scheduled report completed."),
- ];
- const original = structuredClone(messages);
-
- await expect(
- compactMessages(
- messages,
- {} as Parameters<typeof compactMessages>[1],
- { recentWindowSize: 10, threshold: ROOMY },
- undefined,
- undefined,
- undefined,
- undefined,
- true,
- ),
- ).rejects.toThrow(
- "The compaction model returned an empty summary. Finish reason: content-filter.",
- );
- expect(messages).toEqual(original);
- },
- );
-
it("summarizes the full conversation even when it is already under the threshold", async () => {
- const { generateText } = await import("ai");
- vi.mocked(generateText).mockResolvedValue({
- text: "forced checkpoint",
- } as Awaited<ReturnType<typeof generateText>>);
+ const summarize = summarizeWith("forced checkpoint");
const messages = [user("old message"), assistant("old reply")];
const result = await compactMessages(
messages,
- {} as Parameters<typeof compactMessages>[1],
{ recentWindowSize: 10, threshold: ROOMY },
- undefined,
- undefined,
- undefined,
- undefined,
+ summarize,
true,
);
- expect(generateText).toHaveBeenCalledOnce();
+ expect(summarize).toHaveBeenCalledOnce();
expect(result).toContainEqual({ content: "forced checkpoint", role: "assistant" });
});
});
@@ -1151,36 +1010,4 @@ describe("compactMessages: summarization fallback", () => {
expect(result.at(-1)).toEqual(user("latest question"));
expect(result.filter((m) => m.content === "Continue.")).toHaveLength(0);
});
-
- it("forwards model options to the summarization call", async () => {
- const { generateText } = await import("ai");
- vi.mocked(generateText).mockResolvedValue({
- text: "summary",
- } as Awaited<ReturnType<typeof generateText>>);
-
- const messages = [user("old message"), assistant("old reply"), user("continue")];
- const model = {} as Parameters<typeof compactMessages>[1];
- const providerOptions = { anthropic: { thinking: { budget_tokens: 128 } } };
- const headers = { "x-title": "My Agent" };
- const abortController = new AbortController();
-
- await compactMessages(
- messages,
- model,
- { recentWindowSize: 1, threshold: HEURISTICS_FORBIDDEN },
- providerOptions,
- undefined,
- headers,
- abortController.signal,
- );
-
- expect(generateText).toHaveBeenCalledWith(
- expect.objectContaining({
- abortSignal: abortController.signal,
- headers,
- model,
- providerOptions,
- }),
- );
- });
});
diff --git a/packages/eve/src/harness/compaction/engine.ts b/packages/eve/src/harness/compaction/engine.ts
index 771fdb742..01824958e 100644
--- a/packages/eve/src/harness/compaction/engine.ts
+++ b/packages/eve/src/harness/compaction/engine.ts
@@ -1,4 +1,4 @@
-import { generateText, type LanguageModel, type ModelMessage, type TelemetryOptions } from "ai";
+import type { ModelMessage } from "ai";
import {
COMPACTION_CHECKPOINT_MARKER,
@@ -11,8 +11,7 @@ import {
} from "#harness/compaction/prompt.js";
import { createFrameworkUserMessage, isFrameworkUserMessage } from "#harness/messages.js";
import { estimateTokens } from "#harness/token-estimate.js";
-import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
-import type { CompactionConfig, ToolLoopHarnessConfig } from "#harness/types.js";
+import type { CompactionConfig } from "#harness/types.js";
const COMPACTION_SUMMARY_RESERVE_TOKENS = 2_048;
@@ -78,32 +77,11 @@ export function shouldCompact(
);
}
-/**
- * Resolves the model used to summarize older context during compaction.
- *
- * Reuses the active turn model when compaction should summarize with the same
- * reference, and resolves the authored compaction model only when configured.
- */
-export async function resolveCompactionModel(input: {
- readonly compactionModelReference?: RuntimeModelReference;
- readonly model: LanguageModel;
- readonly modelReference: RuntimeModelReference;
- readonly resolveModel: ToolLoopHarnessConfig["resolveModel"];
-}): Promise<{
- readonly model: LanguageModel;
- readonly providerOptions: Parameters<typeof generateText>[0]["providerOptions"];
-}> {
- const reference = input.compactionModelReference ?? input.modelReference;
- const model =
- reference === input.modelReference ? input.model : await input.resolveModel(reference);
-
- return {
- model,
- providerOptions: reference.providerOptions as Parameters<
- typeof generateText
- >[0]["providerOptions"],
- };
-}
+/** Summarizes one compaction prompt with the compaction model, returning the summary text. */
+export type CompactionSummarizer = (prompt: {
+ readonly messages: ModelMessage[];
+ readonly system: string;
+}) => Promise<string>;
/** Conversation regions and config handed to each compaction heuristic. */
interface CompactionHeuristicInput {
@@ -197,12 +175,8 @@ function evaluateThreshold(
*/
export async function compactMessages(
messages: ModelMessage[],
- model: LanguageModel,
config: CompactionConfig,
- providerOptions?: Parameters<typeof generateText>[0]["providerOptions"],
- telemetry?: TelemetryOptions,
- headers?: Record<string, string>,
- abortSignal?: AbortSignal,
+ summarize: CompactionSummarizer,
forceSummary = false,
historyInputTokenCount?: number,
): Promise<ModelMessage[]> {
@@ -247,25 +221,14 @@ export async function compactMessages(
transcriptBudgetTokens: config.threshold,
});
- const result = await generateText({
- abortSignal,
- headers,
+ const summary = await summarize({
messages: [createFrameworkUserMessage("context.compaction", summaryPrompt.prompt)],
- model,
- providerOptions,
system: summaryPrompt.system,
- telemetry: telemetry ? { ...telemetry, functionId: "eve.compaction" } : undefined,
});
- if (result.text.trim().length === 0) {
- throw new Error(
- `The compaction model returned an empty summary. Finish reason: ${result.finishReason}.`,
- );
- }
-
const summaryHead: ModelMessage[] = [
createFrameworkUserMessage("context.compaction", COMPACTION_CHECKPOINT_MARKER),
- { content: result.text, role: "assistant" },
+ { content: summary, role: "assistant" },
];
// Prefer keeping the recent tail verbatim — surviving tool results are the
diff --git a/packages/eve/src/harness/compaction/step.integration.test.ts b/packages/eve/src/harness/compaction/step.integration.test.ts
new file mode 100644
index 000000000..dc7c33079
--- /dev/null
+++ b/packages/eve/src/harness/compaction/step.integration.test.ts
@@ -0,0 +1,136 @@
+import { MockLanguageModelV3 } from "ai/test";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createToolLoopHarness } from "#harness/tool-loop.js";
+import { getTurnUsageState, takeSessionUsageDelta } from "#harness/turn-tag-state.js";
+import type { HarnessSession } from "#harness/types.js";
+
+type StreamResult = Awaited<ReturnType<MockLanguageModelV3["doStream"]>>;
+type StreamPart = StreamResult["stream"] extends ReadableStream<infer Part> ? Part : never;
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+function streamOf(parts: readonly StreamPart[]): StreamResult {
+ return {
+ stream: new ReadableStream<StreamPart>({
+ start(controller) {
+ for (const part of parts) controller.enqueue(part);
+ controller.close();
+ },
+ }),
+ };
+}
+
+const summaryStream = (): StreamResult =>
+ streamOf([
+ { type: "stream-start", warnings: [] },
+ { id: "summary", type: "text-start" },
+ { delta: "Alice asked for the quarterly report.", id: "summary", type: "text-delta" },
+ { id: "summary", type: "text-end" },
+ {
+ finishReason: { raw: undefined, unified: "stop" },
+ type: "finish",
+ usage: {
+ inputTokens: { cacheRead: 0, cacheWrite: 0, noCache: 120, total: 120 },
+ outputTokens: { reasoning: 0, text: 8, total: 8 },
+ },
+ },
+ ]);
+
+/** Manually compacts a short conversation with `model`, as `session.compact()` does. */
+async function compactWith(model: MockLanguageModelV3) {
+ const session: HarnessSession = {
+ agent: { modelReference: { id: "summary-model" }, system: "You help Alice.", tools: [] },
+ compaction: { recentWindowSize: 1, threshold: 100_000 },
+ continuationToken: "http:compaction-session",
+ history: [
+ { content: "Please prepare the quarterly report.", kind: "user", role: "user" },
+ { content: "I started the report.", role: "assistant" },
+ { content: "Thanks, keep going.", kind: "user", role: "user" },
+ ],
+ sessionId: "compaction-session",
+ };
+ return createToolLoopHarness({
+ compactOnly: true,
+ handleEvent: async () => {},
+ resolveModel: async () => model,
+ tools: new Map(),
+ })(session, {});
+}
+
+describe("compaction summary call", () => {
+ it("streams a manual summary and counts its usage outside any turn", async () => {
+ const doGenerate = vi.fn(async () => {
+ throw new Error("Stream must be set to true");
+ });
+ const model = new MockLanguageModelV3({
+ doGenerate,
+ doStream: async () => summaryStream(),
+ });
+
+ const result = await compactWith(model);
+
+ expect(doGenerate).not.toHaveBeenCalled();
+ expect(result.session.history).toContainEqual({
+ content: "Alice asked for the quarterly report.",
+ role: "assistant",
+ });
+ // Session limits see the summary call; a manual compaction has no turn to report it.
+ expect(getTurnUsageState(result.session.state)?.session).toMatchObject({
+ inputTokens: 120,
+ outputTokens: 8,
+ });
+ expect(takeSessionUsageDelta(result.session).delta).toMatchObject({
+ inputTokens: 0,
+ outputTokens: 0,
+ });
+ });
+
+ it("retries a transient stream failure like a model step", async () => {
+ vi.spyOn(Math, "random").mockReturnValue(0);
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ const doStream = vi
+ .fn<MockLanguageModelV3["doStream"]>()
+ .mockResolvedValueOnce(
+ streamOf([
+ { type: "stream-start", warnings: [] },
+ { error: { message: "Overloaded", type: "overloaded_error" }, type: "error" },
+ ]),
+ )
+ .mockImplementation(async () => summaryStream());
+
+ const result = await compactWith(new MockLanguageModelV3({ doStream }));
+
+ expect(doStream).toHaveBeenCalledTimes(2);
+ expect(result.session.history).toContainEqual({
+ content: "Alice asked for the quarterly report.",
+ role: "assistant",
+ });
+ });
+
+ it("keeps the history but counts the call when the model returns a blank summary", async () => {
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const model = new MockLanguageModelV3({
+ doStream: async () =>
+ streamOf([
+ { type: "stream-start", warnings: [] },
+ {
+ finishReason: { raw: undefined, unified: "content-filter" },
+ type: "finish",
+ usage: {
+ inputTokens: { cacheRead: 0, cacheWrite: 0, noCache: 120, total: 120 },
+ outputTokens: { reasoning: 0, text: 0, total: 0 },
+ },
+ },
+ ]),
+ });
+
+ const result = await compactWith(model);
+
+ expect(result.session.history).toHaveLength(3);
+ expect(JSON.stringify(result.session.history)).not.toContain("context.compaction");
+ expect(getTurnUsageState(result.session.state)?.session).toMatchObject({ inputTokens: 120 });
+ });
+});
diff --git a/packages/eve/src/harness/compaction/step.ts b/packages/eve/src/harness/compaction/step.ts
index 120a6d7f8..c4a547377 100644
--- a/packages/eve/src/harness/compaction/step.ts
+++ b/packages/eve/src/harness/compaction/step.ts
@@ -1,4 +1,4 @@
-import type { LanguageModel, TelemetryOptions } from "ai";
+import { type LanguageModel, type ModelMessage, streamText, type TelemetryOptions } from "ai";
import { createLogger, logError } from "#internal/logging.js";
import { AuthKey, HistoryStateKey } from "#context/keys.js";
@@ -23,8 +23,8 @@ import {
import { canonicalizeMemoryRecords, shouldCanonicalizeMemory } from "#shared/memory-state.js";
import {
compactMessages,
+ type CompactionSummarizer,
getInputTokenCount,
- resolveCompactionModel,
shouldCompact,
} from "#harness/compaction/engine.js";
import { contextStorage } from "#context/container.js";
@@ -33,8 +33,19 @@ import {
createCompactionRequestedEvent,
} from "#protocol/message.js";
import { drainMemoryCommit, prepareMemoryCompaction } from "#context/memory-lifecycle.js";
-import { gatewayModelId } from "#harness/model-call/usage.js";
+import { normalizeModelStreamError } from "#harness/model-call/errors.js";
+import { runModelCallWithRetries } from "#harness/model-call/retry.js";
+import {
+ extractGatewayCostUsd,
+ extractTokenUsageDelta,
+ gatewayModelId,
+} from "#harness/model-call/usage.js";
import { resolveModelProfile } from "#harness/model-profile.js";
+import {
+ addTurnUsage,
+ addUsageOutsideTurns,
+ type TokenUsageDelta,
+} from "#harness/turn-tag-state.js";
import { getRequestEnvelopeTokens } from "#harness/request-envelope.js";
import { idle } from "#harness/session-machine/transitions.js";
import { resolveCallProviderOptions } from "#harness/provider-safety.js";
@@ -74,6 +85,7 @@ export async function compactHistory(step: Step): Promise<StepResult> {
const compacted = await maybeCompact({
abortSignal: config.abortSignal,
auth: step.ctx?.get(AuthKey) ?? null,
+ betweenTurns: true,
emissionState: { ...position, turnId: activeTurnId(position) },
force: true,
historyProjector: config.historyProjector,
@@ -87,6 +99,7 @@ export async function compactHistory(step: Step): Promise<StepResult> {
telemetry: step.instrumentation?.telemetry(),
});
step.session = compacted.session;
+ if (compacted.failure !== undefined) throw compacted.failure.error;
} catch (error) {
logError(log, "manual session compaction failed", error, {
sessionId: step.session.sessionId,
@@ -125,6 +138,8 @@ export function replaceSessionHistory(
export async function maybeCompact(input: {
readonly abortSignal?: AbortSignal;
readonly auth: SessionAuthContext | null;
+ /** A manual compaction runs between turns, so no turn's usage reports its summary calls. */
+ readonly betweenTurns?: boolean;
readonly emissionState: TurnPosition;
readonly force?: boolean;
readonly historyProjector?: HistoryViewProjector;
@@ -140,6 +155,8 @@ export async function maybeCompact(input: {
readonly telemetry?: TelemetryOptions;
}): Promise<{
readonly compacted: boolean;
+ /** The summary failed; `session` still counts the summary calls that finished. */
+ readonly failure?: { readonly error: unknown };
readonly messages: HarnessModelMessage[];
readonly session: HarnessSession;
}> {
@@ -164,19 +181,41 @@ export async function maybeCompact(input: {
return { compacted: false, messages, session };
}
- const compaction = await resolveCompactionModel({
- compactionModelReference: session.agent.compactionModelReference,
- model: input.model,
- modelReference: requireSessionModelReference(session),
- resolveModel: input.resolveModel,
- });
- const profile = resolveModelProfile(compaction.model);
+ const modelReference = requireSessionModelReference(session);
+ const compactionModelReference = session.agent.compactionModelReference ?? modelReference;
+ const model =
+ compactionModelReference === modelReference
+ ? input.model
+ : await input.resolveModel(compactionModelReference);
+ const profile = resolveModelProfile(model);
const providerOptions = resolveCallProviderOptions({
auth: input.auth,
conversationId: resolveConversationId(session.rootSessionId ?? session.sessionId),
profile,
- providerOptions: compaction.providerOptions,
- }) as Parameters<typeof compactMessages>[3];
+ providerOptions: compactionModelReference.providerOptions,
+ }) as Parameters<typeof streamText>[0]["providerOptions"];
+ const call = {
+ abortSignal: input.abortSignal,
+ headers: buildGatewayAttributionHeaders(profile, input.runtimeIdentity),
+ model,
+ providerOptions,
+ telemetry: input.telemetry && { ...input.telemetry, functionId: "eve.compaction" },
+ };
+ const summaryUsage: (TokenUsageDelta | undefined)[] = [];
+ const summarize = async (prompt: CompactionSummaryPrompt) => {
+ const summary = await runModelCallWithRetries(
+ () => streamCompactionSummary({ ...call, ...prompt }),
+ { sessionId: session.sessionId, turnId: emissionState.turnId },
+ input.abortSignal,
+ );
+ summaryUsage.push(summary.usage);
+ if (summary.text.trim().length === 0) {
+ throw new Error(
+ `The compaction model returned an empty summary. Finish reason: ${summary.finishReason}.`,
+ );
+ }
+ return summary.text;
+ };
{
const ctx = contextStorage.getStore();
@@ -185,7 +224,7 @@ export async function maybeCompact(input: {
}
await publish(
createCompactionRequestedEvent({
- modelId: gatewayModelId(compaction.model) ?? "unknown",
+ modelId: gatewayModelId(model) ?? "unknown",
sequence: emissionState.sequence,
sessionId: session.sessionId,
stepIndex: emissionState.stepIndex,
@@ -219,15 +258,14 @@ export async function maybeCompact(input: {
Math.min(getRequestEnvelopeTokens(session) ?? 0, requestEnvelopeTokens),
),
};
- const compactedOrdinary = needsSummary
- ? await compactMessages(
+ let compactedOrdinary: ModelMessage[] = [...ordinary];
+ let failure: { readonly error: unknown } | undefined;
+ try {
+ if (needsSummary) {
+ compactedOrdinary = await compactMessages(
[...ordinary],
- compaction.model,
historyCompaction,
- providerOptions,
- input.telemetry,
- buildGatewayAttributionHeaders(profile, input.runtimeIdentity),
- input.abortSignal,
+ summarize,
input.force === true,
input.requestEnvelopeTokens === undefined
? undefined
@@ -240,8 +278,20 @@ export async function maybeCompact(input: {
getRequestEnvelopeTokens(session),
) - requestEnvelopeTokens,
),
- )
- : [...ordinary];
+ );
+ }
+ } catch (error) {
+ failure = { error };
+ }
+ for (const usage of summaryUsage) {
+ session =
+ input.betweenTurns === true
+ ? addUsageOutsideTurns(session, usage)
+ : addTurnUsage(session, emissionState.turnId, usage);
+ }
+ if (failure !== undefined) {
+ return { compacted: false, failure, messages: input.messages, session };
+ }
messages = validateHarnessModelMessages([...canonical.memory, ...compactedOrdinary]);
{
@@ -251,7 +301,7 @@ export async function maybeCompact(input: {
}
await publish(
createCompactionCompletedEvent({
- modelId: gatewayModelId(compaction.model) ?? "unknown",
+ modelId: gatewayModelId(model) ?? "unknown",
sequence: emissionState.sequence,
sessionId: session.sessionId,
stepIndex: emissionState.stepIndex,
@@ -270,3 +320,38 @@ export async function maybeCompact(input: {
return { compacted: true, messages, session: replaceSessionHistory(session, messages) };
}
+
+type CompactionSummaryPrompt = Parameters<CompactionSummarizer>[0];
+
+/**
+ * Calls the compaction model the way a step calls its model: streamed, with stream errors
+ * thrown in the same shape, so the caller's retries classify them alike.
+ */
+async function streamCompactionSummary(
+ input: CompactionSummaryPrompt &
+ Pick<
+ Parameters<typeof streamText>[0],
+ "abortSignal" | "headers" | "model" | "providerOptions" | "telemetry"
+ >,
+): Promise<{
+ readonly finishReason: string;
+ readonly text: string;
+ readonly usage: TokenUsageDelta | undefined;
+}> {
+ // The stream's error part is rethrown below; the default handler would also log it.
+ const result = streamText({ ...input, onError: () => {} });
+ for await (const part of result.fullStream) {
+ if (part.type === "error") throw normalizeModelStreamError(part.error);
+ }
+ const [text, finishReason, usage, providerMetadata] = await Promise.all([
+ result.text,
+ result.finishReason,
+ result.usage,
+ result.providerMetadata,
+ ]);
+ return {
+ finishReason,
+ text,
+ usage: extractTokenUsageDelta({ costUsd: extractGatewayCostUsd(providerMetadata), usage }),
+ };
+}
diff --git a/packages/eve/src/harness/model-call/call.ts b/packages/eve/src/harness/model-call/call.ts
index fea086b37..63c4aa893 100644
--- a/packages/eve/src/harness/model-call/call.ts
+++ b/packages/eve/src/harness/model-call/call.ts
@@ -45,12 +45,7 @@ import {
import { estimateTokens } from "#harness/token-estimate.js";
import { buildToolApproval } from "#harness/tools.js";
import { throwIfTurnAborted } from "#harness/turn-cancellation.js";
-import {
- accumulateTurnUsage,
- getTurnUsageState,
- setTurnUsageState,
- type TokenUsageDelta,
-} from "#harness/turn-tag-state.js";
+import { addTurnUsage, type TokenUsageDelta } from "#harness/turn-tag-state.js";
import type { StepResult } from "#harness/types.js";
import type { InstrumentationAttempt } from "#instrumentation/runtime.js";
import { createLogger, logError } from "#internal/logging.js";
@@ -191,14 +186,7 @@ export class ModelCaller {
throwIfTurnAborted(step.config.abortSignal);
step.ctx?.set(HistoryStateKey, this.request.historyState);
if (this.interruptedUsage !== undefined) {
- step.session = setTurnUsageState(
- step.session,
- accumulateTurnUsage({
- previous: getTurnUsageState(step.session.state),
- turnId: step.position().turnId,
- usage: this.interruptedUsage,
- }),
- );
+ step.session = addTurnUsage(step.session, step.position().turnId, this.interruptedUsage);
}
await step.emit?.(
createStepCompletedEvent({
@@ -278,6 +266,7 @@ export class ModelCaller {
session: step.session,
telemetry: step.instrumentation?.telemetry(),
});
+ if (compaction.failure !== undefined) throw compaction.failure.error;
} catch (error) {
this.compactionFailure = { error };
throw error;
diff --git a/packages/eve/src/harness/model-call/retry.ts b/packages/eve/src/harness/model-call/retry.ts
index 091e83d60..2c69a2cb9 100644
--- a/packages/eve/src/harness/model-call/retry.ts
+++ b/packages/eve/src/harness/model-call/retry.ts
@@ -33,14 +33,14 @@ export async function runModelCallWithRetries<T>(
readonly turnId: string;
readonly canRetry?: () => boolean;
},
- signal: AbortSignal,
+ signal?: AbortSignal,
): Promise<T> {
for (let attempt = 1; ; attempt++) {
- signal.throwIfAborted();
+ signal?.throwIfAborted();
try {
return await fn(attempt);
} catch (error) {
- signal.throwIfAborted();
+ signal?.throwIfAborted();
if (
diag.canRetry?.() === false ||
attempt === MODEL_CALL_MAX_ATTEMPTS ||
diff --git a/packages/eve/src/harness/model-call/usage.ts b/packages/eve/src/harness/model-call/usage.ts
index 1888e6f32..0c89e7c07 100644
--- a/packages/eve/src/harness/model-call/usage.ts
+++ b/packages/eve/src/harness/model-call/usage.ts
@@ -1,12 +1,7 @@
import type { LanguageModel, ProviderMetadata } from "ai";
import type { HarnessStepResult } from "#harness/step-hooks.js";
-import {
- accumulateTurnUsage,
- getTurnUsageState,
- setTurnUsageState,
- type TokenUsageDelta,
-} from "#harness/turn-tag-state.js";
+import { addTurnUsage, getTurnUsageState, type TokenUsageDelta } from "#harness/turn-tag-state.js";
import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
import type { Step } from "#harness/step/context.js";
import { setEveAttributes } from "#runtime/attributes/emit.js";
@@ -71,22 +66,22 @@ export async function recordModelUsage(
step: Step,
input: { readonly model: LanguageModel; readonly result: HarnessStepResult },
): Promise<void> {
- const usage = accumulateTurnUsage({
- previous: getTurnUsageState(step.session.state),
- turnId: step.position().turnId,
- usage: extractTokenUsageDelta({
+ step.session = addTurnUsage(
+ step.session,
+ step.position().turnId,
+ extractTokenUsageDelta({
costUsd: extractGatewayCostUsd(input.result.providerMetadata),
usage: input.result.usage,
}),
- });
- step.session = setTurnUsageState(step.session, usage);
+ );
+ const usage = getTurnUsageState(step.session.state);
const attributes = {
"$eve.model": gatewayModelId(input.model),
- "$eve.input_tokens": usage.inputTokens,
- "$eve.output_tokens": usage.outputTokens,
- "$eve.cache_read_tokens": usage.cacheReadTokens,
- "$eve.cache_write_tokens": usage.cacheWriteTokens,
- "$eve.cost_usd": usage.sawCost ? usage.costUsd : undefined,
+ "$eve.input_tokens": usage?.inputTokens,
+ "$eve.output_tokens": usage?.outputTokens,
+ "$eve.cache_read_tokens": usage?.cacheReadTokens,
+ "$eve.cache_write_tokens": usage?.cacheWriteTokens,
+ "$eve.cost_usd": usage?.sawCost ? usage.costUsd : undefined,
"$eve.tool_count": step.config.tools.size,
};
await step.config.titleAttributeWrite;
diff --git a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
index 0ae6bad01..fa31ed58f 100644
--- a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
+++ b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
@@ -1,5 +1,6 @@
import { getRequestEnvelopeTokens } from "#harness/request-envelope.js";
-import { generateText, jsonSchema, type LanguageModel, ToolLoopAgent } from "ai";
+import { getTurnUsageState } from "#harness/turn-tag-state.js";
+import { jsonSchema, type LanguageModel, streamText, ToolLoopAgent } from "ai";
import { afterEach, describe, expect, it, vi } from "vitest";
import { withParkedStep } from "#internal/testing/session-machine.js";
@@ -19,7 +20,7 @@ vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async ()
vi.mock("ai", async (importOriginal) => ({
...(await importOriginal<typeof import("ai")>()),
- generateText: vi.fn(),
+ streamText: vi.fn(),
ToolLoopAgent: vi.fn(),
isStepCount: vi.fn((value: number) => value),
tool: vi.fn((definition: unknown) => definition),
@@ -29,6 +30,19 @@ afterEach(() => {
vi.clearAllMocks();
});
+function mockSummary(text: string): void {
+ vi.mocked(streamText).mockImplementation(
+ () =>
+ ({
+ finishReason: Promise.resolve("stop"),
+ fullStream: (async function* () {})(),
+ providerMetadata: Promise.resolve(undefined),
+ text: Promise.resolve(text),
+ usage: Promise.resolve({ inputTokens: 10, outputTokens: 2 }),
+ }) as never,
+ );
+}
+
function createTestSession(overrides?: Partial<HarnessSession>): HarnessSession {
return {
agent: {
@@ -156,9 +170,7 @@ function expectStepFn(value: StepNext): StepFn {
describe("tool-loop structured compaction accounting", () => {
it("keeps private memory out of the summary while retaining its attributed record", async () => {
- vi.mocked(generateText).mockResolvedValue({
- text: "ordinary summary",
- } as Awaited<ReturnType<typeof generateText>>);
+ mockSummary("ordinary summary");
setupMockAgentSequence([
{
finishReason: "stop",
@@ -210,8 +222,8 @@ describe("tool-loop structured compaction accounting", () => {
{ message: "continue" },
);
- expect(vi.mocked(generateText)).toHaveBeenCalledOnce();
- const prompt = vi.mocked(generateText).mock.calls[0]?.[0].messages?.[0]?.content;
+ expect(vi.mocked(streamText)).toHaveBeenCalledOnce();
+ const prompt = vi.mocked(streamText).mock.calls[0]?.[0].messages?.[0]?.content;
if (typeof prompt !== "string") throw new Error("Expected the compaction prompt text.");
expect(prompt).not.toContain("PRIVATE_MEMORY_SENTINEL");
expect(JSON.stringify(result.session.history)).toContain("PRIVATE_MEMORY_SENTINEL");
@@ -219,9 +231,7 @@ describe("tool-loop structured compaction accounting", () => {
});
it("compacts before the continuation step when structured tool results were appended", async () => {
- vi.mocked(generateText).mockResolvedValue({
- text: "summary",
- } as Awaited<ReturnType<typeof generateText>>);
+ mockSummary("summary");
setupMockAgentSequence([
{
@@ -318,7 +328,7 @@ describe("tool-loop structured compaction accounting", () => {
const second = await expectStepFn(first.next)(first.session);
- expect(vi.mocked(generateText)).toHaveBeenCalledTimes(1);
+ expect(vi.mocked(streamText)).toHaveBeenCalledTimes(1);
expect(second.session.history[0]).toEqual({
content: "Summary of our conversation so far:",
kind: "context.compaction",
@@ -331,9 +341,7 @@ describe("tool-loop structured compaction accounting", () => {
});
it("counts an approved call's committed step when checking for compaction", async () => {
- vi.mocked(generateText).mockResolvedValue({
- text: "summary",
- } as Awaited<ReturnType<typeof generateText>>);
+ mockSummary("summary");
setupMockAgentSequence([
{
@@ -417,7 +425,7 @@ describe("tool-loop structured compaction accounting", () => {
],
});
- expect(vi.mocked(generateText)).toHaveBeenCalledTimes(1);
+ expect(vi.mocked(streamText)).toHaveBeenCalledTimes(1);
expect(result.session.history[0]).toEqual({
content: "Summary of our conversation so far:",
kind: "context.compaction",
@@ -501,9 +509,7 @@ describe("tool-loop structured compaction accounting", () => {
it("compacts history when dynamic instructions grow the request envelope", async () => {
const { ContextContainer, contextStorage } = await import("#context/container.js");
const { SessionDynamicInstructionsKey } = await import("#context/keys.js");
- vi.mocked(generateText).mockResolvedValue({ text: "summary" } as Awaited<
- ReturnType<typeof generateText>
- >);
+ mockSummary("summary");
setupMockAgentSequence([
{
finishReason: "stop",
@@ -519,7 +525,7 @@ it("compacts history when dynamic instructions grow the request envelope", async
tenant: [{ role: "system", content: dynamicInstructions }],
});
const runStep = createToolLoopHarness(createTestConfig());
- await contextStorage.run(ctx, () =>
+ const result = await contextStorage.run(ctx, () =>
runStep(
createTestSession({
compaction: {
@@ -536,7 +542,13 @@ it("compacts history when dynamic instructions grow the request envelope", async
expect(JSON.stringify(vi.mocked(ToolLoopAgent).mock.calls[0]?.[0].instructions)).toContain(
dynamicInstructions,
);
- expect(generateText).toHaveBeenCalledOnce();
+ expect(streamText).toHaveBeenCalledOnce();
+ // The summary call is part of the turn it compacted for.
+ expect(getTurnUsageState(result.session.state)).toMatchObject({
+ inputTokens: 10,
+ outputTokens: 2,
+ turnId: "turn_0",
+ });
});
describe("final request envelope compaction", () => {
@@ -557,9 +569,7 @@ describe("final request envelope compaction", () => {
tenant: [{ role: "system", content: "tenant policy ".repeat(1_000) }],
});
setupMockAgentSequence([completed(), completed(), completed()]);
- vi.mocked(generateText).mockResolvedValue({ text: "summary" } as Awaited<
- ReturnType<typeof generateText>
- >);
+ mockSummary("summary");
const runStep = createToolLoopHarness(createTestConfig());
const first = await contextStorage.run(ctx, () =>
runStep(
@@ -573,13 +583,13 @@ describe("final request envelope compaction", () => {
const second = await contextStorage.run(ctx, () =>
runStep(first.session, { message: "Second" }),
);
- expect(generateText).not.toHaveBeenCalled();
+ expect(streamText).not.toHaveBeenCalled();
expect(getRequestEnvelopeTokens(second.session)).toBe(getRequestEnvelopeTokens(first.session));
ctx.set(SessionDynamicInstructionsKey, {
tenant: [{ role: "system", content: "tenant policy ".repeat(2_000) }],
});
await contextStorage.run(ctx, () => runStep(second.session, { message: "Third" }));
- expect(generateText).toHaveBeenCalledOnce();
+ expect(streamText).toHaveBeenCalledOnce();
});
it("counts dynamic schemas resolved by step.started before calling the model", async () => {
@@ -590,9 +600,7 @@ describe("final request envelope compaction", () => {
const schemaDescription = "connector catalog field ".repeat(1_000);
const events: string[] = [];
setupMockAgentSequence([completed()]);
- vi.mocked(generateText).mockResolvedValue({ text: "summary" } as Awaited<
- ReturnType<typeof generateText>
- >);
+ mockSummary("summary");
const runStep = createToolLoopHarness(
createTestConfig({
resolveModel: vi
@@ -628,7 +636,7 @@ describe("final request envelope compaction", () => {
{ message: "continue" },
),
);
- expect(generateText).toHaveBeenCalledOnce();
+ expect(streamText).toHaveBeenCalledOnce();
expect(events.indexOf("compaction.requested")).toBeGreaterThan(events.indexOf("step.started"));
expect(vi.mocked(ToolLoopAgent).mock.calls[0]?.[0].tools).toHaveProperty("catalog");
});
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 7e0e0c8a5..7234ae71d 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -4,6 +4,7 @@ import {
jsonSchema,
type LanguageModel,
type ModelMessage,
+ streamText,
ToolLoopAgent,
type UserContent,
} from "ai";
@@ -103,6 +104,7 @@ vi.mock("#runtime/attributes/emit.js", () => ({ setEveAttributes: vi.fn(async ()
vi.mock("ai", async (importOriginal) => ({
...(await importOriginal<typeof import("ai")>()),
ToolLoopAgent: vi.fn(),
+ streamText: vi.fn(),
gateway: {
tools: {
exaSearch: vi.fn(() => ({})),
@@ -247,18 +249,28 @@ vi.mock("#harness/compaction/engine.js", () => ({
compactMessages: vi.fn(),
estimateTokens: vi.fn().mockReturnValue(5000),
getInputTokenCount: vi.fn().mockReturnValue(5000),
- resolveCompactionModel: vi.fn(
- async ({ compactionModelReference, model, modelReference, resolveModel }) => ({
- model:
- compactionModelReference === undefined
- ? model
- : ((await resolveModel(compactionModelReference)) as LanguageModel),
- providerOptions: (compactionModelReference ?? modelReference).providerOptions,
- }),
- ),
shouldCompact: vi.fn().mockReturnValue(false),
}));
+/** Compacts to `messages` through one summary call, which {@link summaryCall} reads. */
+function mockCompaction(messages: ModelMessage[]): void {
+ vi.mocked(streamText).mockReturnValue({
+ finishReason: Promise.resolve("stop"),
+ fullStream: (async function* () {})(),
+ providerMetadata: Promise.resolve(undefined),
+ text: Promise.resolve("summary"),
+ usage: Promise.resolve({ inputTokens: 10, outputTokens: 2 }),
+ } as never);
+ vi.mocked(compactMessages).mockImplementation(async (_messages, _config, summarize) => {
+ await summarize({ messages: [], system: "" });
+ return messages;
+ });
+}
+
+function summaryCall(): Parameters<typeof streamText>[0] | undefined {
+ return vi.mocked(streamText).mock.calls[0]?.[0];
+}
+
afterEach(() => {
vi.clearAllMocks();
vi.mocked(shouldCompact).mockReset().mockReturnValue(false);
@@ -8015,7 +8027,7 @@ describe("createToolLoopHarness", () => {
it("emits compaction.requested and compaction.completed when compaction triggers", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
- vi.mocked(compactMessages).mockResolvedValue([
+ mockCompaction([
createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
createUserMessage("user", "recent message"),
@@ -8091,7 +8103,7 @@ describe("createToolLoopHarness", () => {
stepIndex: 0,
turnId: "turn_0",
});
- expect(vi.mocked(compactMessages).mock.calls[0]?.[3]).toEqual({
+ expect(summaryCall()?.providerOptions).toEqual({
openai: {
safetyIdentifier: invocationOwnerKey(auth),
store: false,
@@ -8101,7 +8113,7 @@ describe("createToolLoopHarness", () => {
it("groups Gateway compaction under the forwarded trace conversation", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
- vi.mocked(compactMessages).mockResolvedValue([
+ mockCompaction([
createFrameworkUserMessage("context.compaction", "Summary"),
{ content: "summary", role: "assistant" },
]);
@@ -8122,7 +8134,7 @@ describe("createToolLoopHarness", () => {
await contextStorage.run(ctx, () => createToolLoopHarness(config)(session, { message: "Hi" }));
- expect(vi.mocked(compactMessages).mock.calls[0]?.[3]).toEqual({
+ expect(summaryCall()?.providerOptions).toEqual({
gateway: { sessionId: "forwarded-conversation" },
});
});
@@ -8429,7 +8441,7 @@ describe("createToolLoopHarness", () => {
it("uses the authored compaction model when one is configured", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
- vi.mocked(compactMessages).mockResolvedValue([
+ mockCompaction([
createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
createUserMessage("user", "recent message"),
@@ -8476,19 +8488,19 @@ describe("createToolLoopHarness", () => {
{ content: "old reply", role: "assistant" },
{ content: "Hi", kind: "user" as const, role: "user" },
]);
- expect(call?.[1]).toMatchObject({
+ expect(summaryCall()?.model).toMatchObject({
modelId: "summary-model",
provider: "openai",
});
- expect(call?.[2]).toEqual(
+ expect(call?.[1]).toEqual(
expect.objectContaining({
recentWindowSize: 10,
threshold: expect.any(Number),
}),
);
- expect(call?.[2].threshold).toBeLessThan(100_000);
- expect(call?.[2].threshold).toBeGreaterThan(99_000);
- expect(call?.[3]).toBeUndefined();
+ expect(call?.[1].threshold).toBeLessThan(100_000);
+ expect(call?.[1].threshold).toBeGreaterThan(99_000);
+ expect(summaryCall()?.providerOptions).toBeUndefined();
});
it("emits reasoning.completed when reasoning text is available", async () => {
@@ -9545,7 +9557,7 @@ describe("createToolLoopHarness", () => {
it("derives compaction attribution from the compaction model", async () => {
vi.mocked(shouldCompact).mockReturnValueOnce(true);
- vi.mocked(compactMessages).mockResolvedValueOnce([
+ mockCompaction([
createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
]);
@@ -9587,8 +9599,7 @@ describe("createToolLoopHarness", () => {
const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0];
expect(agentCall?.headers).toBeUndefined();
- const compactCall = vi.mocked(compactMessages).mock.calls[0];
- expect(compactCall?.[5]).toEqual({
+ expect(summaryCall()?.headers).toEqual({
"x-title": "Weather Agent",
"http-referer": "https://my-agent.vercel.app",
"user-agent": expect.stringMatching(/^eve\/.+/),
@@ -9791,7 +9802,7 @@ describe("createToolLoopHarness", () => {
it("keeps compaction telemetry metadata-only on a rejected trace", async () => {
vi.mocked(shouldCompact).mockReturnValueOnce(true);
- vi.mocked(compactMessages).mockResolvedValueOnce([
+ mockCompaction([
createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
]);
@@ -9814,7 +9825,8 @@ describe("createToolLoopHarness", () => {
await runStep(createTestSession(), { message: "private" });
- expect(vi.mocked(compactMessages).mock.calls[0]?.[4]).toMatchObject({
+ expect(summaryCall()?.telemetry).toMatchObject({
+ functionId: "eve.compaction",
isEnabled: true,
recordInputs: false,
recordOutputs: false,
diff --git a/packages/eve/src/harness/turn-tag-state.ts b/packages/eve/src/harness/turn-tag-state.ts
index e09fa788a..15d402971 100644
--- a/packages/eve/src/harness/turn-tag-state.ts
+++ b/packages/eve/src/harness/turn-tag-state.ts
@@ -250,6 +250,44 @@ export function accumulateTurnUsage(input: {
};
}
+/** Folds one model call's usage into the session's turn and session totals. */
+export function addTurnUsage<T extends { readonly state?: SessionStateMap }>(
+ session: T,
+ turnId: string,
+ usage: TokenUsageDelta | undefined,
+): T {
+ return setTurnUsageState(
+ session,
+ accumulateTurnUsage({ previous: getTurnUsageState(session.state), turnId, usage }),
+ );
+}
+
+/**
+ * Counts usage that belongs to no turn, such as a manual compaction between turns. It adds to
+ * session totals, so session limits see it, and is marked reported so a later turn's usage delta
+ * doesn't claim it.
+ */
+export function addUsageOutsideTurns<T extends { readonly state?: SessionStateMap }>(
+ session: T,
+ usage: TokenUsageDelta | undefined,
+): T {
+ if (usage === undefined) return session;
+ const counted = setTurnUsageState(
+ session,
+ accumulateSessionUsage({ previous: getTurnUsageState(session.state), usage }),
+ );
+ const reported =
+ (session.state?.[REPORTED_SESSION_USAGE_STATE_KEY] as TokenUsageTotals | undefined) ??
+ ZERO_TOKEN_USAGE;
+ return {
+ ...counted,
+ state: {
+ ...counted.state,
+ [REPORTED_SESSION_USAGE_STATE_KEY]: addTokenUsage(reported, toTokenUsageDelta(usage)),
+ },
+ };
+}
+
/**
* Adds usage to session totals without touching the in-flight turn totals:
* the delegated spend a parent counts, or a run's tally of what its