Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 world
By 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.ts
index 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.ts
index 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<CompiledAgentCompaction
const 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
? undefined
diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): DurableSession
if (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): DurableSession
if (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): SessionToolD
outputSchema: 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.ts
index 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-reque
import { 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.ts
index 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.ts
index 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.ts
index 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): TurnUsage
return 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): Resolve
if (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.ts
index 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;
}
/**