The Open Framework for Building Agents
feat(eve): add per-session token limits (#424)
Rui2fdc5612eac6
diff --git a/.changeset/session-token-limits.md b/.changeset/session-token-limits.mdnew file mode 100644index 000000000..34aee946a--- /dev/null+++ b/.changeset/session-token-limits.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add `limits.maxInputTokensPerSession` and `limits.maxOutputTokensPerSession` to stop a durable session from starting more model calls after its accumulated provider-reported input or output token usage reaches the configured cap. Root sessions default to a 40M input-token budget, delegated subagent sessions default to 5M, and authored input limits override those defaults.diff --git a/docs/agent-config.md b/docs/agent-config.mdindex 4dcd55b0f..8a87a5a7e 100644--- a/docs/agent-config.md+++ b/docs/agent-config.md@@ -75,6 +75,32 @@ export default defineAgent({See [Default harness](./concepts/default-harness#compaction) for how the loop applies it.+## Runtime limits++Use `limits` for framework-owned runtime caps. Session token limits stop the+current durable session from starting another model call after accumulated+provider-reported input or output token usage reaches the configured limit:++```ts title="agent/agent.ts"+export default defineAgent({+ model: "anthropic/claude-opus-4.8",+ limits: {+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ },+});+```++Input and output budgets are checked independently. The model call that crosses+either limit is allowed to finish because providers only report exact token+usage after a call completes. Follow-up model calls in the same session fail+with `SESSION_TOKEN_LIMIT_REACHED`.++When `maxInputTokensPerSession` is omitted, eve applies a default input budget:+`40_000_000` provider-reported input tokens for root sessions and `5_000_000`+for delegated subagent sessions. `maxOutputTokensPerSession` is unset unless+configured.+## Workflow worldBy default, eve selects the Workflow SDK world for the host: Vercel Workflow on@@ -116,13 +142,14 @@ installed package must stay external in hosted output, list it in`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).-| Field | Type | Default | Description |-| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |-| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |-| `experimental` | `{ workflow?: { world?: string } }` | unset | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |-| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema. |-| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |+| Field | Type | Default | Description |+| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |+| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |+| `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. `maxSubagentDepth` defaults to `3`; `maxInputTokensPerSession` defaults to `40_000_000` for root sessions and `5_000_000` for delegated subagent sessions; `maxOutputTokensPerSession` is unset unless configured. |+| `experimental` | `{ workflow?: { world?: string } }` | unset | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |+| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema. |+| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |`externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.tsindex 2e96919f9..ab76d2446 100644--- a/packages/eve/src/compiler/manifest.test.ts+++ b/packages/eve/src/compiler/manifest.test.ts@@ -20,6 +20,30 @@ describe("compiledAgentManifestSchema", () => {expect(parsed.config.reasoning).toBe("high");});+ it("preserves runtime limits configuration", () => {+ const manifest = createCompiledAgentManifest({+ agentRoot: "/app/agent",+ appRoot: "/app",+ config: {+ limits: {+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ maxSubagentDepth: 4,+ },+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },+ name: "app",+ },+ });++ const parsed = compiledAgentManifestSchema.parse(manifest);++ expect(parsed.config.limits).toEqual({+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ maxSubagentDepth: 4,+ });+ });+it("accepts compiled workflow world configuration", () => {const manifest = createCompiledAgentManifest({agentRoot: "/app/agent",diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.tsindex 343d47277..19bc73a39 100644--- a/packages/eve/src/compiler/manifest.ts+++ b/packages/eve/src/compiler/manifest.ts@@ -360,6 +360,8 @@ const compiledAgentCompactionDefinitionSchema: z.ZodType<CompiledAgentCompactionconst compiledAgentLimitsDefinitionSchema = z.object({maxSubagentDepth: z.number().int().positive().optional(),+ maxInputTokensPerSession: z.number().int().positive().optional(),+ maxOutputTokensPerSession: z.number().int().positive().optional(),}).strict();@@ -724,6 +726,14 @@ export function createCompiledAgentNodeManifest(input: {name: input.config.name,outputSchema: input.config.outputSchema,reasoning: input.config.reasoning,+ limits:+ input.config.limits === undefined+ ? undefined+ : {+ maxInputTokensPerSession: input.config.limits.maxInputTokensPerSession,+ maxOutputTokensPerSession: input.config.limits.maxOutputTokensPerSession,+ maxSubagentDepth: input.config.limits.maxSubagentDepth,+ },source:input.config.source === undefined? undefineddiff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.tsindex a65d89f5e..ffab2600f 100644--- a/packages/eve/src/compiler/normalize-agent-config.ts+++ b/packages/eve/src/compiler/normalize-agent-config.ts@@ -107,6 +107,8 @@ export async function compileAgentConfig(if (definition.limits !== undefined) {compiledConfig.limits = {maxSubagentDepth: definition.limits.maxSubagentDepth,+ maxInputTokensPerSession: definition.limits.maxInputTokensPerSession,+ maxOutputTokensPerSession: definition.limits.maxOutputTokensPerSession,};}diff --git a/packages/eve/src/execution/create-session-step.test.ts b/packages/eve/src/execution/create-session-step.test.tsindex 8aa539ce0..c9eb0b090 100644--- a/packages/eve/src/execution/create-session-step.test.ts+++ b/packages/eve/src/execution/create-session-step.test.ts@@ -1,6 +1,10 @@import { describe, expect, it, vi } from "vitest";import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";+import {+ DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,+ DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION,+} from "#execution/session.js";import { createSessionStep } from "#execution/create-session-step.js";import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";@@ -17,6 +21,70 @@ const TestTurnAgent: RuntimeTurnAgent = {};describe("createSessionStep", () => {+ it("defaults root sessions to the root input token budget", async () => {+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({+ resolvedAgent: {+ config: {},+ },+ turnAgent: TestTurnAgent,+ } as never);++ const { state } = await createSessionStep({+ compiledArtifactsSource: { kind: "bundled" },+ continuationToken: "http:test",+ sessionId: "sess-root",+ });++ expect(state.snapshot?.session.limits?.maxInputTokensPerSession).toBe(+ DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,+ );+ });++ it("defaults delegated subagent sessions to the subagent input token budget", async () => {+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({+ resolvedAgent: {+ config: {},+ },+ turnAgent: TestTurnAgent,+ } as never);++ const { state } = await createSessionStep({+ compiledArtifactsSource: { kind: "bundled" },+ continuationToken: "subagent:test",+ sessionId: "sess-child",+ subagentDepth: 1,+ });++ expect(state.snapshot?.session.limits?.maxInputTokensPerSession).toBe(+ DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION,+ );+ });++ it("seeds session token limits from resolved agent config", async () => {+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({+ resolvedAgent: {+ config: {+ limits: {+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ },+ },+ },+ turnAgent: TestTurnAgent,+ } as never);++ const { state } = await createSessionStep({+ compiledArtifactsSource: { kind: "bundled" },+ continuationToken: "http:test",+ sessionId: "sess-root",+ });++ expect(state.snapshot?.session.limits).toMatchObject({+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ });+ });+it("seeds subagent max depth from resolved agent config", async () => {vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({resolvedAgent: {diff --git a/packages/eve/src/execution/create-session-step.ts b/packages/eve/src/execution/create-session-step.tsindex 270c43762..de734e219 100644--- a/packages/eve/src/execution/create-session-step.ts+++ b/packages/eve/src/execution/create-session-step.ts@@ -45,6 +45,10 @@ export async function createSessionStep(input: {thresholdPercent: bundle.resolvedAgent.config.compaction?.thresholdPercent,},continuationToken: input.continuationToken,+ limits: {+ maxInputTokensPerSession: bundle.resolvedAgent.config.limits?.maxInputTokensPerSession,+ maxOutputTokensPerSession: bundle.resolvedAgent.config.limits?.maxOutputTokensPerSession,+ },outputSchema: input.outputSchema,rootSessionId: input.rootSessionId,sessionId: input.sessionId,diff --git a/packages/eve/src/execution/durable-session-store.ts b/packages/eve/src/execution/durable-session-store.tsindex 30e2cd457..f605432da 100644--- a/packages/eve/src/execution/durable-session-store.ts+++ b/packages/eve/src/execution/durable-session-store.ts@@ -81,6 +81,7 @@ export interface DurableSession {readonly rootSessionId?: string;readonly continuationToken: string;readonly history: ModelMessage[];+ readonly limits?: HarnessSession["limits"];readonly outputSchema?: JsonObject;readonly state?: SessionStateMap;readonly sandboxState?: SandboxState;diff --git a/packages/eve/src/execution/session.test.ts b/packages/eve/src/execution/session.test.tsindex 989f6fbe5..675faaa4a 100644--- a/packages/eve/src/execution/session.test.ts+++ b/packages/eve/src/execution/session.test.ts@@ -4,6 +4,8 @@ import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";import {createCompactionConfig,createSession,+ DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,+ DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION,hydrateDurableSession,mintSubagentContinuationToken,projectToDurableSession,@@ -181,6 +183,64 @@ describe("createSession", () => {});});+ it("defaults root sessions to the root input token budget", () => {+ const session = createSession({+ continuationToken: "root-token",+ sessionId: "sess-root",+ turnAgent: createTestTurnAgent(),+ });++ expect(session.limits?.maxInputTokensPerSession).toBe(+ DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,+ );+ });++ it("defaults delegated subagent sessions to the subagent input token budget", () => {+ const session = createSession({+ continuationToken: "subagent-token",+ sessionId: "sess-child",+ subagentDepth: 1,+ turnAgent: createTestTurnAgent(),+ });++ expect(session.limits?.maxInputTokensPerSession).toBe(+ DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION,+ );+ });++ it("applies the root input token budget when hydrating a durable session without a stored limit", () => {+ const hydrated = hydrateDurableSession({+ durable: {+ agent: { system: "You are a helpful assistant." },+ continuationToken: "root-token",+ history: [],+ sessionId: "sess-root",+ },+ turnAgent: createTestTurnAgent(),+ });++ expect(hydrated.limits?.maxInputTokensPerSession).toBe(+ DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,+ );+ });++ it("applies the subagent input token budget when hydrating a durable child without a stored limit", () => {+ const hydrated = hydrateDurableSession({+ durable: {+ agent: { system: "You are a helpful assistant." },+ continuationToken: "subagent-token",+ history: [],+ sessionId: "sess-child",+ subagentDepth: 1,+ },+ turnAgent: createTestTurnAgent(),+ });++ expect(hydrated.limits?.maxInputTokensPerSession).toBe(+ DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION,+ );+ });+it("persists run outputSchema through durable session projection and hydration", () => {const agentOutputSchema = {properties: { ignored: { type: "string" } },@@ -230,6 +290,33 @@ describe("createSession", () => {expect(hydrated.subagentMaxDepth).toBe(4);});+ it("persists session token limits through durable session projection and hydration", () => {+ const session = createSession({+ continuationToken: "root-token",+ limits: {+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ },+ sessionId: "sess-root",+ turnAgent: createTestTurnAgent(),+ });++ const durable = projectToDurableSession(session);+ const hydrated = hydrateDurableSession({+ durable,+ turnAgent: createTestTurnAgent(),+ });++ expect(durable.limits).toEqual({+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ });+ expect(hydrated.limits).toEqual({+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ });+ });+it("restores current reasoning configuration when hydrating a durable session", () => {const session = createSession({continuationToken: "root-token",diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.tsindex 42da983ab..ea69f1d15 100644--- a/packages/eve/src/execution/session.ts+++ b/packages/eve/src/execution/session.ts@@ -1,10 +1,12 @@import type { DurableSession } from "#execution/durable-session-store.js";-import type { HarnessSession, SessionToolDefinition } from "#harness/types.js";+import type { HarnessSession, SessionLimits, SessionToolDefinition } from "#harness/types.js";import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";const DEFAULT_COMPACTION_RECENT_WINDOW_SIZE = 10;const DEFAULT_COMPACTION_THRESHOLD_PERCENT = 0.9;const FALLBACK_COMPACTION_THRESHOLD = 100_000;+export const DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION = 40_000_000;+export const DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION = 5_000_000;/*** Creates the durable compaction configuration used by one harness session.@@ -52,6 +54,7 @@ export interface CreateSessionInput {readonly rootSessionId?: string;readonly sessionId: string;readonly turnAgent: RuntimeTurnAgent;+ readonly limits?: SessionLimits;readonly outputSchema?: HarnessSession["outputSchema"];readonly subagentDepth?: number;readonly subagentMaxDepth?: number;@@ -84,6 +87,7 @@ export function createSession(input: CreateSessionInput): HarnessSession {if (input.rootSessionId !== undefined) {session.rootSessionId = input.rootSessionId;}+ session.limits = resolveSessionLimits(input);if (input.outputSchema !== undefined) {session.outputSchema = input.outputSchema;}@@ -152,6 +156,7 @@ export function projectToDurableSession(session: HarnessSession): DurableSession};continuationToken: string;history: HarnessSession["history"];+ limits?: HarnessSession["limits"];outputSchema?: HarnessSession["outputSchema"];rootSessionId?: string;sandboxState?: HarnessSession["sandboxState"];@@ -178,6 +183,9 @@ export function projectToDurableSession(session: HarnessSession): DurableSessionif (session.rootSessionId !== undefined) {durable.rootSessionId = session.rootSessionId;}+ if (session.limits !== undefined) {+ durable.limits = session.limits;+ }if (session.outputSchema !== undefined) {durable.outputSchema = session.outputSchema;}@@ -193,7 +201,6 @@ export function projectToDurableSession(session: HarnessSession): DurableSessionif (session.subagentMaxDepth !== undefined) {durable.subagentMaxDepth = session.subagentMaxDepth;}-return durable;}@@ -236,6 +243,7 @@ export function hydrateDurableSession(input: {if (durable.rootSessionId !== undefined) {session.rootSessionId = durable.rootSessionId;}+ session.limits = resolveSessionLimits(durable);if (durable.outputSchema !== undefined) {session.outputSchema = durable.outputSchema;}@@ -251,7 +259,6 @@ export function hydrateDurableSession(input: {if (durable.subagentMaxDepth !== undefined) {session.subagentMaxDepth = durable.subagentMaxDepth;}-return session;}@@ -263,3 +270,23 @@ function createSessionToolDefinitions(turnAgent: RuntimeTurnAgent): SessionToolDoutputSchema: tool.outputSchema,}));}++function resolveSessionLimits(input: {+ readonly limits?: SessionLimits;+ readonly subagentDepth?: number;+}): SessionLimits {+ const maxInputTokensPerSession =+ input.limits?.maxInputTokensPerSession ??+ (input.subagentDepth !== undefined && input.subagentDepth > 0+ ? DEFAULT_SUBAGENT_MAX_INPUT_TOKENS_PER_SESSION+ : DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION);++ if (input.limits?.maxOutputTokensPerSession === undefined) {+ return { maxInputTokensPerSession };+ }++ return {+ maxInputTokensPerSession,+ maxOutputTokensPerSession: input.limits.maxOutputTokensPerSession,+ };+}diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.tsindex 22a07f49d..01c3e6c36 100644--- a/packages/eve/src/harness/tool-loop.test.ts+++ b/packages/eve/src/harness/tool-loop.test.ts@@ -37,6 +37,7 @@ import { hasDeferredStepInput, setPendingInputBatch } from "#harness/input-requeimport { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";import { stashToolInterrupt } from "#harness/tool-interrupts.js";import { createToolLoopHarness } from "#harness/tool-loop.js";+import { getSessionTokenUsage, setTurnUsageState } from "#harness/turn-tag-state.js";import { DEFAULT_SUBAGENT_MAX_DEPTH } from "#harness/subagent-depth.js";import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";import {@@ -856,6 +857,104 @@ describe("createToolLoopHarness", () => {expect(vi.mocked(ToolLoopAgent).mock.calls[0]?.[0]).toMatchObject({ reasoning: "high" });});+ it("accumulates provider-reported token usage across the session", async () => {+ setupMockAgent({+ finishReason: "stop",+ response: { messages: [{ content: "Hello!", role: "assistant" }] },+ text: "Hello!",+ toolCalls: [],+ toolResults: [],+ usage: {+ inputTokenDetails: { cacheReadTokens: 2, cacheWriteTokens: 1 },+ inputTokens: 7,+ outputTokens: 3,+ },+ });++ const runStep = createToolLoopHarness(createTestConfig());+ const result = await runStep(createTestSession(), { message: "Hi" });++ expect(getSessionTokenUsage(result.session)).toEqual({+ cacheReadTokens: 2,+ cacheWriteTokens: 1,+ inputTokens: 7,+ outputTokens: 3,+ });+ });++ it.each([+ {+ details: {+ inputTokens: 12,+ kind: "input",+ limit: 12,+ outputTokens: 3,+ usedTokens: 12,+ },+ message: "The session reached its configured input token limit.",+ limits: {+ maxInputTokensPerSession: 12,+ },+ usage: {+ cacheReadTokens: 2,+ cacheWriteTokens: 1,+ inputTokens: 12,+ outputTokens: 3,+ },+ tokenKind: "input",+ },+ {+ details: {+ inputTokens: 7,+ kind: "output",+ limit: 3,+ outputTokens: 3,+ usedTokens: 3,+ },+ message: "The session reached its configured output token limit.",+ limits: {+ maxOutputTokensPerSession: 3,+ },+ usage: {+ cacheReadTokens: 2,+ cacheWriteTokens: 1,+ inputTokens: 7,+ outputTokens: 3,+ },+ tokenKind: "output",+ },+ ])(+ "blocks another model call after the session reaches its $tokenKind token limit",+ async (testCase) => {+ const { emit, events } = createEventCollector();+ const runStep = createToolLoopHarness(createTestConfig("conversation", emit));+ const session = setTurnUsageState(createTestSession({ limits: testCase.limits }), {+ turnId: "turn_previous",+ ...testCase.usage,+ session: testCase.usage,+ });++ const result = await runStep(session, { message: "Hi again" });++ expect(vi.mocked(ToolLoopAgent)).not.toHaveBeenCalled();+ expect(result.next).toEqual({ done: true, isError: undefined, output: "" });+ expect(events.map((event) => event.type)).toEqual([+ "session.started",+ "turn.started",+ "message.received",+ "step.started",+ "step.failed",+ "turn.failed",+ "session.failed",+ ]);+ expect(events.find((event) => event.type === "step.failed")?.data).toMatchObject({+ code: "SESSION_TOKEN_LIMIT_REACHED",+ details: testCase.details,+ message: testCase.message,+ });+ },+ );+it("preserves approval gates on step-scoped dynamic tools", async () => {setupMockAgent({finishReason: "stop",diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex 5debd46dd..923597db9 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -68,8 +68,12 @@ import {} from "#harness/compaction.js";import {accumulateTurnUsage,+ getSessionTokenLimitViolation,+ getSessionTokenUsage,getTurnUsageState,setTurnUsageState,+ type SessionTokenLimitViolation,+ type TokenUsageDelta,} from "#harness/turn-tag-state.js";import { setEveAttributes } from "#runtime/attributes/emit.js";import {@@ -847,6 +851,17 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {return pendingWorkflowInterrupt;}+ const tokenLimitViolation = getSessionTokenLimitViolation(session);+ if (tokenLimitViolation !== null) {+ return failSessionTokenLimit({+ config,+ emit,+ emissionState,+ session,+ violation: tokenLimitViolation,+ });+ }+let result: HarnessStepResult;try {result = await runOneModelCall({@@ -1028,7 +1043,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {const nextTurnUsage = accumulateTurnUsage({previous: getTurnUsageState(session.state),turnId: emissionState.turnId,- usage: result.usage ?? {},+ usage: extractTokenUsageDelta(result.usage),});session = setTurnUsageState(session, nextTurnUsage);// `formatLanguageModelGatewayId` requires `model.provider` to be a string;@@ -1066,6 +1081,63 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {return runStep;}+const SESSION_TOKEN_LIMIT_REACHED_CODE = "SESSION_TOKEN_LIMIT_REACHED";++function extractTokenUsageDelta(+ usage: HarnessStepResult["usage"] | undefined,+): TokenUsageDelta | undefined {+ if (usage === undefined) {+ return undefined;+ }++ return {+ cacheReadTokens: usage.inputTokenDetails?.cacheReadTokens,+ cacheWriteTokens: usage.inputTokenDetails?.cacheWriteTokens,+ inputTokens: usage.inputTokens,+ outputTokens: usage.outputTokens,+ };+}++function formatSessionTokenLimitMessage(kind: SessionTokenLimitViolation["kind"]): string {+ return `The session reached its configured ${kind} token limit.`;+}++async function failSessionTokenLimit(input: {+ readonly config: ToolLoopHarnessConfig;+ readonly emit?: ToolLoopHarnessConfig["handleEvent"];+ readonly emissionState: ReturnType<typeof getHarnessEmissionState>;+ readonly session: HarnessSession;+ readonly violation: SessionTokenLimitViolation;+}): Promise<StepResult> {+ const usage = getSessionTokenUsage(input.session);+ const message = formatSessionTokenLimitMessage(input.violation.kind);+ const details = {+ inputTokens: usage.inputTokens,+ kind: input.violation.kind,+ limit: input.violation.limit,+ outputTokens: usage.outputTokens,+ usedTokens: input.violation.usedTokens,+ };++ if (input.emit) {+ await emitFailedStep(input.emit, input.emissionState, {+ code: SESSION_TOKEN_LIMIT_REACHED_CODE,+ details,+ message,+ sessionId: input.session.sessionId,+ });+ }++ return {+ next: {+ done: true,+ isError: input.config.mode === "task" ? true : undefined,+ output: input.config.mode === "task" ? message : "",+ },+ session: input.session,+ };+}+// ---------------------------------------------------------------------------// Model-call failure projection// ---------------------------------------------------------------------------diff --git a/packages/eve/src/harness/turn-tag-state.test.ts b/packages/eve/src/harness/turn-tag-state.test.tsindex 8766d0557..8f7af0436 100644--- a/packages/eve/src/harness/turn-tag-state.test.ts+++ b/packages/eve/src/harness/turn-tag-state.test.ts@@ -2,11 +2,20 @@ import { describe, expect, it } from "vitest";import {accumulateTurnUsage,+ getSessionTokenLimitViolation,+ getSessionTokenUsage,getTurnUsageState,setTurnUsageState,} from "#harness/turn-tag-state.js";import type { HarnessSession } from "#harness/types.js";+const ZERO_SESSION_USAGE = {+ cacheReadTokens: 0,+ cacheWriteTokens: 0,+ inputTokens: 0,+ outputTokens: 0,+};+function makeSession(state?: HarnessSession["state"]): HarnessSession {return {agent: {@@ -27,7 +36,7 @@ describe("accumulateTurnUsage", () => {const next = accumulateTurnUsage({previous: undefined,turnId: "turn_0",- usage: { inputTokens: 10, outputTokens: 3, cachedInputTokens: 2 },+ usage: { cacheReadTokens: 2, inputTokens: 10, outputTokens: 3 },});expect(next).toEqual({@@ -36,18 +45,24 @@ describe("accumulateTurnUsage", () => {outputTokens: 3,cacheReadTokens: 2,cacheWriteTokens: 0,+ session: {+ ...ZERO_SESSION_USAGE,+ cacheReadTokens: 2,+ inputTokens: 10,+ outputTokens: 3,+ },});});- it("accumulates cacheWriteTokens from inputTokenDetails", () => {+ it("accumulates cache write tokens from normalized usage", () => {const next = accumulateTurnUsage({previous: undefined,turnId: "turn_0",usage: {+ cacheReadTokens: 800,+ cacheWriteTokens: 200,inputTokens: 1000,outputTokens: 50,- cachedInputTokens: 800,- inputTokenDetails: { cacheWriteTokens: 200 },},});@@ -57,6 +72,12 @@ describe("accumulateTurnUsage", () => {outputTokens: 50,cacheReadTokens: 800,cacheWriteTokens: 200,+ session: {+ cacheReadTokens: 800,+ cacheWriteTokens: 200,+ inputTokens: 1000,+ outputTokens: 50,+ },});});@@ -67,15 +88,21 @@ describe("accumulateTurnUsage", () => {outputTokens: 50,cacheReadTokens: 8,cacheWriteTokens: 5,+ session: {+ cacheReadTokens: 8,+ cacheWriteTokens: 5,+ inputTokens: 100,+ outputTokens: 50,+ },};const next = accumulateTurnUsage({previous,turnId: "turn_0",usage: {+ cacheReadTokens: 4,+ cacheWriteTokens: 3,inputTokens: 12,outputTokens: 7,- cachedInputTokens: 4,- inputTokenDetails: { cacheWriteTokens: 3 },},});@@ -85,16 +112,28 @@ describe("accumulateTurnUsage", () => {outputTokens: 57,cacheReadTokens: 12,cacheWriteTokens: 8,+ session: {+ cacheReadTokens: 12,+ cacheWriteTokens: 8,+ inputTokens: 112,+ outputTokens: 57,+ },});});- it("discards the previous totals when the turn id changes", () => {+ it("resets turn totals and keeps session totals when the turn id changes", () => {const previous = {turnId: "turn_0",inputTokens: 100,outputTokens: 50,cacheReadTokens: 8,cacheWriteTokens: 5,+ session: {+ cacheReadTokens: 80,+ cacheWriteTokens: 50,+ inputTokens: 1000,+ outputTokens: 500,+ },};const next = accumulateTurnUsage({previous,@@ -108,6 +147,12 @@ describe("accumulateTurnUsage", () => {outputTokens: 5,cacheReadTokens: 0,cacheWriteTokens: 0,+ session: {+ cacheReadTokens: 80,+ cacheWriteTokens: 50,+ inputTokens: 1020,+ outputTokens: 505,+ },});});@@ -124,6 +169,7 @@ describe("accumulateTurnUsage", () => {outputTokens: 0,cacheReadTokens: 0,cacheWriteTokens: 0,+ session: ZERO_SESSION_USAGE,});});});@@ -136,6 +182,11 @@ describe("session state round-trip", () => {outputTokens: 1,cacheReadTokens: 0,cacheWriteTokens: 0,+ session: {+ ...ZERO_SESSION_USAGE,+ inputTokens: 5,+ outputTokens: 1,+ },});expect(getTurnUsageState(seeded.state)).toEqual({@@ -144,6 +195,11 @@ describe("session state round-trip", () => {outputTokens: 1,cacheReadTokens: 0,cacheWriteTokens: 0,+ session: {+ ...ZERO_SESSION_USAGE,+ inputTokens: 5,+ outputTokens: 1,+ },});});@@ -159,8 +215,49 @@ describe("session state round-trip", () => {outputTokens: 1,cacheReadTokens: 1,cacheWriteTokens: 0,+ session: {+ ...ZERO_SESSION_USAGE,+ cacheReadTokens: 1,+ inputTokens: 1,+ outputTokens: 1,+ },});expect(seeded.state).toMatchObject({ other: "keep me" });});});++describe("session token limits", () => {+ it("reads zero session usage before token state exists", () => {+ expect(getSessionTokenUsage(makeSession())).toEqual(ZERO_SESSION_USAGE);+ });++ it.each([+ {+ expected: { kind: "input", limit: 10, usedTokens: 10 },+ limits: { maxInputTokensPerSession: 10 },+ },+ {+ expected: { kind: "output", limit: 3, usedTokens: 3 },+ limits: { maxOutputTokensPerSession: 3 },+ },+ ])("reports the first exhausted $expected.kind limit", (testCase) => {+ const session = setTurnUsageState(makeSession(), {+ turnId: "turn_0",+ cacheReadTokens: 0,+ cacheWriteTokens: 0,+ inputTokens: 10,+ outputTokens: 3,+ session: {+ cacheReadTokens: 0,+ cacheWriteTokens: 0,+ inputTokens: 10,+ outputTokens: 3,+ },+ });++ expect(getSessionTokenLimitViolation({ ...session, limits: testCase.limits })).toEqual(+ testCase.expected,+ );+ });+});diff --git a/packages/eve/src/harness/turn-tag-state.ts b/packages/eve/src/harness/turn-tag-state.tsindex 320510bc9..7f41809f4 100644--- a/packages/eve/src/harness/turn-tag-state.ts+++ b/packages/eve/src/harness/turn-tag-state.ts@@ -1,7 +1,7 @@/**- * Per-turn rolling token-usage accumulator for `$eve.*` observability- * tags. Lives on `session.state` so the totals survive workflow step- * boundaries the way the rest of the harness state does.+ * Token-usage accumulator for `$eve.*` observability tags and session limits.+ * Lives on `session.state` so the totals survive workflow step boundaries the+ * way the rest of the harness state does.** The harness runs each turn as a sequence of `"use step"` invocations* (one per tool-loop iteration). Each step knows its own@@ -11,30 +11,36 @@* `session.state`, add the new step's usage, write the running total* back. The most recent emit then carries the final per-turn total.*- * `turnId` keys the state so a fresh turn starts at zero without- * relying on a separate "reset" code path — when the harness moves to- * a new turn, the stale totals are discarded automatically.+ * `turnId` keys the turn totals so a fresh turn starts at zero without relying+ * on a separate "reset" code path. Session totals stay in the same state record+ * and keep accumulating until the durable session ends.*/import type { HarnessSession, SessionStateMap } from "#harness/types.js";const HARNESS_TURN_USAGE_STATE_KEY = "eve.harness.turnUsage";-/**- * Rolling token usage for the in-flight turn.- *- * `turnId` is the in-flight turn's stable id; when the harness step- * runs in a different turn (or with the empty-string between-turns- * sentinel), totals are reset.- */-export interface TurnUsageState {+export interface TokenUsageTotals {readonly cacheReadTokens: number;readonly cacheWriteTokens: number;readonly inputTokens: number;readonly outputTokens: number;+}++export type TokenUsageDelta = Partial<TokenUsageTotals>;++/**+ * Rolling token usage for the durable session and the in-flight turn.+ *+ * `turnId` is the in-flight turn's stable id; when the harness step+ * runs in a different turn, the flat turn totals reset. The nested+ * `session` totals do not reset.+ */+export interface TurnUsageState extends TokenUsageTotals {+ readonly session: TokenUsageTotals;readonly turnId: string;}-const ZERO_USAGE: Omit<TurnUsageState, "turnId"> = {+const ZERO_TOKEN_USAGE: TokenUsageTotals = {cacheReadTokens: 0,cacheWriteTokens: 0,inputTokens: 0,@@ -46,6 +52,45 @@ export function getTurnUsageState(state: SessionStateMap | undefined): TurnUsagereturn state?.[HARNESS_TURN_USAGE_STATE_KEY] as TurnUsageState | undefined;}+export type SessionTokenLimitViolation =+ | {+ readonly kind: "input";+ readonly limit: number;+ readonly usedTokens: number;+ }+ | {+ readonly kind: "output";+ readonly limit: number;+ readonly usedTokens: number;+ };++export function getSessionTokenUsage(session: Pick<HarnessSession, "state">): TokenUsageTotals {+ return getTurnUsageState(session.state)?.session ?? ZERO_TOKEN_USAGE;+}++export function getSessionTokenLimitViolation(+ session: Pick<HarnessSession, "limits" | "state">,+): SessionTokenLimitViolation | null {+ const usage = getSessionTokenUsage(session);+ const maxInputTokensPerSession = session.limits?.maxInputTokensPerSession;+ const maxOutputTokensPerSession = session.limits?.maxOutputTokensPerSession;+ if (maxInputTokensPerSession !== undefined && usage.inputTokens >= maxInputTokensPerSession) {+ return {+ kind: "input",+ limit: maxInputTokensPerSession,+ usedTokens: usage.inputTokens,+ };+ }+ if (maxOutputTokensPerSession !== undefined && usage.outputTokens >= maxOutputTokensPerSession) {+ return {+ kind: "output",+ limit: maxOutputTokensPerSession,+ usedTokens: usage.outputTokens,+ };+ }+ return null;+}+/** Writes per-turn token state onto a new copy of the session. */export function setTurnUsageState(session: HarnessSession, next: TurnUsageState): HarnessSession {return {@@ -66,26 +111,42 @@ export function setTurnUsageState(session: HarnessSession, next: TurnUsageState)export function accumulateTurnUsage(input: {readonly previous: TurnUsageState | undefined;readonly turnId: string;- readonly usage: {- readonly cachedInputTokens?: number;- readonly inputTokens?: number;- readonly inputTokenDetails?: {- readonly cacheWriteTokens?: number;- };- readonly outputTokens?: number;- };+ readonly usage: TokenUsageDelta | undefined;}): TurnUsageState {- const base =+ const delta = toTokenUsageDelta(input.usage);+ const previousSession = input.previous?.session ?? ZERO_TOKEN_USAGE;+ const turnBase =input.previous !== undefined && input.previous.turnId === input.turnId? input.previous- : { ...ZERO_USAGE, turnId: input.turnId };+ : ZERO_TOKEN_USAGE;return {+ ...addTokenUsage(turnBase, delta),turnId: input.turnId,- cacheReadTokens: base.cacheReadTokens + (input.usage.cachedInputTokens ?? 0),- cacheWriteTokens:- base.cacheWriteTokens + (input.usage.inputTokenDetails?.cacheWriteTokens ?? 0),- inputTokens: base.inputTokens + (input.usage.inputTokens ?? 0),- outputTokens: base.outputTokens + (input.usage.outputTokens ?? 0),+ session: addTokenUsage(previousSession, delta),+ };+}++function addTokenUsage(base: TokenUsageTotals, delta: TokenUsageTotals): TokenUsageTotals {+ return {+ cacheReadTokens: base.cacheReadTokens + delta.cacheReadTokens,+ cacheWriteTokens: base.cacheWriteTokens + delta.cacheWriteTokens,+ inputTokens: base.inputTokens + delta.inputTokens,+ outputTokens: base.outputTokens + delta.outputTokens,+ };+}++function toTokenUsageDelta(usage: TokenUsageDelta | undefined): TokenUsageTotals {+ if (usage === undefined) {+ return ZERO_TOKEN_USAGE;+ }++ const inputTokens = usage.inputTokens ?? 0;+ const outputTokens = usage.outputTokens ?? 0;+ return {+ cacheReadTokens: usage.cacheReadTokens ?? 0,+ cacheWriteTokens: usage.cacheWriteTokens ?? 0,+ inputTokens,+ outputTokens,};}diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.tsindex 46eee04a7..b879670b1 100644--- a/packages/eve/src/harness/types.ts+++ b/packages/eve/src/harness/types.ts@@ -60,6 +60,7 @@ export interface HarnessSession {readonly compaction: CompactionConfig;readonly continuationToken: string;readonly history: ModelMessage[];+ readonly limits?: SessionLimits;readonly outputSchema?: JsonObject;/*** Stable identifier of the top user-facing session in the dispatch@@ -86,6 +87,23 @@ export interface HarnessSession {readonly subagentMaxDepth?: number;}+/**+ * Token limits stored on one durable session.+ */+export interface SessionLimits {+ /**+ * Maximum provider-reported input tokens this durable session may spend before+ * eve refuses to start another model call. Defaults to 40M for root sessions+ * and 5M for delegated subagent sessions.+ */+ readonly maxInputTokensPerSession?: number;+ /**+ * Maximum provider-reported output tokens this durable session may spend before+ * eve refuses to start another model call.+ */+ readonly maxOutputTokensPerSession?: number;+}+/*** Input payload for a harness turn.*diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.tsindex 1217e6560..e0ccdeef7 100644--- a/packages/eve/src/internal/authored-definition/core.test.ts+++ b/packages/eve/src/internal/authored-definition/core.test.ts@@ -32,16 +32,24 @@ describe("normalizeAgentDefinition", () => {).toThrow(FAILURE_MESSAGE);});- it("accepts a positive subagent max depth", () => {+ it("accepts positive agent limits", () => {const definition = normalizeAgentDefinition({model: "openai/gpt-5.5",- limits: { maxSubagentDepth: 4 },+ limits: {+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ maxSubagentDepth: 4,+ },},FAILURE_MESSAGE,);- expect(definition.limits).toEqual({ maxSubagentDepth: 4 });+ expect(definition.limits).toEqual({+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ maxSubagentDepth: 4,+ });});it.each([0, 1.5, -1, "4"])("rejects invalid subagent max depth %j", (maxSubagentDepth) => {@@ -56,6 +64,27 @@ describe("normalizeAgentDefinition", () => {).toThrow(FAILURE_MESSAGE);});+ it.each([+ ["maxInputTokensPerSession", 0],+ ["maxInputTokensPerSession", 1.5],+ ["maxInputTokensPerSession", -1],+ ["maxInputTokensPerSession", "200000"],+ ["maxOutputTokensPerSession", 0],+ ["maxOutputTokensPerSession", 1.5],+ ["maxOutputTokensPerSession", -1],+ ["maxOutputTokensPerSession", "20000"],+ ])("rejects invalid session token limit %s=%j", (key, value) => {+ expect(() =>+ normalizeAgentDefinition(+ {+ model: "openai/gpt-5.5",+ limits: { [key]: value },+ },+ FAILURE_MESSAGE,+ ),+ ).toThrow(FAILURE_MESSAGE);+ });+it("rejects the old subagents maxDepth config", () => {expect(() =>normalizeAgentDefinition(diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.tsindex 6001ea5da..49e8a7a93 100644--- a/packages/eve/src/internal/authored-definition/core.ts+++ b/packages/eve/src/internal/authored-definition/core.ts@@ -133,9 +133,25 @@ function normalizeAgentLimitsDefinition(message: string,): NonNullable<NormalizedAgentDefinition["limits"]> {const record = expectObjectRecord(value, message);- expectOnlyKnownKeys(record, ["maxSubagentDepth"], message);+ expectOnlyKnownKeys(+ record,+ ["maxInputTokensPerSession", "maxOutputTokensPerSession", "maxSubagentDepth"],+ message,+ );const normalizedDefinition: Mutable<NonNullable<NormalizedAgentDefinition["limits"]>> = {};+ if (record.maxInputTokensPerSession !== undefined) {+ normalizedDefinition.maxInputTokensPerSession = expectPositiveInteger(+ record.maxInputTokensPerSession,+ message,+ );+ }+ if (record.maxOutputTokensPerSession !== undefined) {+ normalizedDefinition.maxOutputTokensPerSession = expectPositiveInteger(+ record.maxOutputTokensPerSession,+ message,+ );+ }if (record.maxSubagentDepth !== undefined) {normalizedDefinition.maxSubagentDepth = expectPositiveInteger(record.maxSubagentDepth, message);}diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.tsindex 4577e1b87..6419a5b63 100644--- a/packages/eve/src/public/definitions/exact.test.ts+++ b/packages/eve/src/public/definitions/exact.test.ts@@ -16,7 +16,11 @@ describe("definition helper exact inputs", () => {it("preserves literal inference for valid definitions", () => {const agent = defineAgent({description: "type-test",- limits: { maxSubagentDepth: 4 },+ limits: {+ maxInputTokensPerSession: 200_000,+ maxOutputTokensPerSession: 20_000,+ maxSubagentDepth: 4,+ },model: "anthropic/claude-sonnet-4.6",});@@ -26,6 +30,8 @@ describe("definition helper exact inputs", () => {});expect(agent.description).toBe("type-test");+ expect(agent.limits.maxInputTokensPerSession).toBe(200_000);+ expect(agent.limits.maxOutputTokensPerSession).toBe(20_000);expect(agent.limits.maxSubagentDepth).toBe(4);expect(schedule.cron).toBe("0 9 * * *");});diff --git a/packages/eve/src/runtime/resolve-agent.ts b/packages/eve/src/runtime/resolve-agent.tsindex c8491c053..ccc9b0a34 100644--- a/packages/eve/src/runtime/resolve-agent.ts+++ b/packages/eve/src/runtime/resolve-agent.ts@@ -234,6 +234,8 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolveif (manifest.config.limits !== undefined) {config.limits = {maxSubagentDepth: manifest.config.limits.maxSubagentDepth,+ maxInputTokensPerSession: manifest.config.limits.maxInputTokensPerSession,+ maxOutputTokensPerSession: manifest.config.limits.maxOutputTokensPerSession,};}diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.tsindex f1c65c9d4..af2001ccc 100644--- a/packages/eve/src/shared/agent-definition.ts+++ b/packages/eve/src/shared/agent-definition.ts@@ -109,6 +109,24 @@ export interface AgentLimitsDefinition {* @default 3*/readonly maxSubagentDepth?: number;+ /**+ * Maximum provider-reported input tokens accumulated by one durable session.+ *+ * eve checks this before starting each model call. The model call that crosses+ * the limit is allowed to finish because providers only report exact usage+ * after the call completes; later model calls in the same session are blocked.+ *+ * @default 40_000_000 for root sessions; 5_000_000 for delegated subagent sessions+ */+ readonly maxInputTokensPerSession?: number;+ /**+ * Maximum provider-reported output tokens accumulated by one durable session.+ *+ * eve checks this before starting each model call. The model call that crosses+ * the limit is allowed to finish because providers only report exact usage+ * after the call completes; later model calls in the same session are blocked.+ */+ readonly maxOutputTokensPerSession?: number;}/**