Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add per-session model token-cost limits (#2950)

Casey Gowrie73aec259ca98
diff --git a/.changeset/curvy-token-cost-limits.md b/.changeset/curvy-token-cost-limits.md
new file mode 100644
index 000000000..9e33c7aff
--- /dev/null
+++ b/.changeset/curvy-token-cost-limits.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add an optional per-session model token-cost limit in US dollars. Sessions pause for approval before another model call after reported cost reaches the limit, following the existing token-limit continuation flow.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 01c57326c..9b72447cf 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -147,9 +147,9 @@ See [Default harness](./concepts/default-harness#compaction) for how the loop ap
## Runtime limits
-Use `limits` for framework-owned runtime caps. Session token limits stop the
+Use `limits` for framework-owned runtime caps. Session usage limits stop the
current durable session from starting another model call after accumulated
-provider-reported input or output token usage reaches the configured limit:
+provider-reported tokens or model token cost reaches a configured limit:
```ts title="agent/agent.ts"
export default defineAgent({
@@ -157,6 +157,7 @@ export default defineAgent({
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
sessionTimeoutMs: 7 * 24 * 60 * 60 * 1_000,
},
});
@@ -169,14 +170,13 @@ then emits `session.completed` and releases the continuation; the next
qualifying channel message starts fresh. Set it to `false` to disable the
timeout. Expiration does not delete stored session data.
-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. Before the next model call, eve pauses the
+Input tokens, output tokens, and model token cost are checked independently.
+The model call that crosses a limit is allowed to finish because exact usage
+arrives after the call completes. Before the next model call, eve pauses the
session and sends a deterministic continuation prompt with two options:
-**Approve** grants a fresh budget window of the configured size (both input
-and output windows reset together), and **Stop** cancels the in-flight turn
-through the standard cancellation path (`turn.cancelled` → `session.waiting`)
-— a user decision, not an error. The session stays resumable; because it is
+**Approve** grants a fresh window of each configured size, and **Stop**
+cancels the in-flight turn through the standard cancellation path
+(`turn.cancelled` → `session.waiting`) — a user decision, not an error. The session stays resumable; because it is
still over budget, the next message re-raises the prompt. Declining a
delegated child's prompt cancels the root turn, which cascades to the whole
delegation tree — the delegating parent never receives an error result it
@@ -186,23 +186,28 @@ copy. The reply is processed once the budget is granted.
Sessions that cannot reach a human — task-mode runs such as schedules and
delegated runs without input proxying — skip the prompt and fail the next model
-call with `SESSION_TOKEN_LIMIT_REACHED`. A delegated task with no inherited
-quota also fails instead of raising a continuation prompt that could only
-grant another zero-token window.
+call with `SESSION_TOKEN_LIMIT_REACHED` for token budgets or
+`SESSION_TOKEN_COST_LIMIT_REACHED` for model token cost. A delegated task with
+no inherited quota also fails instead of raising a continuation prompt that
+could only grant another zero-value window.
When `maxInputTokensPerSession` is omitted, root sessions apply a default
input budget of `40_000_000` provider-reported input tokens.
-`maxOutputTokensPerSession` is unset unless configured. Setting either limit
-to `false` uncaps that axis — the session never stops on it.
+`maxOutputTokensPerSession` and `maxTokenCostUsdPerSession` are unset by
+default. `maxTokenCostUsdPerSession` is a US-dollar limit on model token cost,
+not tool or infrastructure spend. It uses the cost reported with each model
+step; AI Gateway supplies this value, while model steps without reported cost
+do not add to the limit. Set any usage limit to `false` to uncap that axis.
Delegated subagent sessions have no fixed default. Each child receives a
share of the delegating parent's remaining quota at dispatch time — the
remainder in the current budget window split evenly across the batch's local
subagent calls — and a completed child's usage counts against the parent's
-quota, so a delegation tree can never outspend the budget configured at its
-root. Approving a continuation opens a fresh parent window for later child
-grants without erasing lifetime usage. An authored child limit applies only
-when it is tighter than the parent's grant; an uncapped parent delegates
+quota. Token-cost budgets follow the same rules, including splitting the
+remaining US-dollar budget across a batch and adding completed child cost back
+to the parent. Approving a continuation opens a fresh parent window for later
+child grants without erasing lifetime usage. An authored child limit applies
+only when it is tighter than the parent's grant; an uncapped parent delegates
uncapped children.
## Workflow world
@@ -250,7 +255,7 @@ installed package must stay external in hosted output, list it in
| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. Sessions complete after 30 days by default; token-limit defaults and inheritance are described above. Set a limit to `false` to disable it. |
+| `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it. |
| `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 function-like invocations such as a subagent turn, schedule, or remote job. Ordinary interactive 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. |
diff --git a/packages/eve/extension-contracts/compatibility/channel/v14.ts b/packages/eve/extension-contracts/compatibility/channel/v14.ts
new file mode 100644
index 000000000..67e58f0bb
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v14.ts
@@ -0,0 +1,3 @@
+import { disableRoute } from "#public/channels/index.js";
+
+export default disableRoute();
diff --git a/packages/eve/extension-contracts/compatibility/connection/v12.ts b/packages/eve/extension-contracts/compatibility/connection/v12.ts
new file mode 100644
index 000000000..c9adb6c9f
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/connection/v12.ts
@@ -0,0 +1,6 @@
+import { defineMcpClientConnection } from "#public/connections/index.js";
+
+export default defineMcpClientConnection({
+ description: "Call-aware MCP service",
+ url: "https://example.com/mcp",
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v16.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v16.ts
new file mode 100644
index 000000000..745446593
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v16.ts
@@ -0,0 +1,8 @@
+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";
+
+export default defineDynamic({
+ events: {
+ "session.started": (_event, ctx) =>
+ defineInstructions({ markdown: `Use session ${ctx.session.id} for correlation.` }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v15.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v15.ts
new file mode 100644
index 000000000..bd9ab80cf
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v15.ts
@@ -0,0 +1,11 @@
+import { defineDynamic, defineSkill } from "#public/skills/index.js";
+
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineSkill({
+ description: `Review session ${ctx.session.id}.`,
+ markdown: "# Review\n\nCheck each claim.",
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v25.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v25.ts
new file mode 100644
index 000000000..1e9382581
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v25.ts
@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+import { defineDynamic, defineTool } from "#public/tools/index.js";
+
+export default defineDynamic({
+ events: {
+ "session.started": () =>
+ defineTool({
+ description: "Delegate a background report.",
+ execution: "background",
+ inputSchema: z.object({ reportId: z.string() }),
+ execute({ reportId }, _ctx, task) {
+ return task.delegated({
+ executor: { data: { reportId }, kind: "report" },
+ receipt: { reportId },
+ });
+ },
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/hook/v18.ts b/packages/eve/extension-contracts/compatibility/hook/v18.ts
new file mode 100644
index 000000000..c32db5c59
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/hook/v18.ts
@@ -0,0 +1,9 @@
+import { defineHook } from "#public/hooks/index.js";
+
+export default defineHook({
+ events: {
+ "subagent.completed"(event, ctx) {
+ console.info(event.data.subagentName, ctx.session.id);
+ },
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/schedule/v7.ts b/packages/eve/extension-contracts/compatibility/schedule/v7.ts
new file mode 100644
index 000000000..58d9be225
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/schedule/v7.ts
@@ -0,0 +1,8 @@
+import { defineSchedule } from "#public/schedules/index.js";
+
+export default defineSchedule({
+ cron: "0 0 * * *",
+ run({ waitUntil }) {
+ waitUntil(Promise.resolve());
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/subagent/v7.ts b/packages/eve/extension-contracts/compatibility/subagent/v7.ts
new file mode 100644
index 000000000..344e5db11
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/subagent/v7.ts
@@ -0,0 +1,6 @@
+import { defineAgent } from "#public/index.js";
+
+export default defineAgent({
+ description: "Delegate research tasks.",
+ model: "anthropic/claude-sonnet-5",
+});
diff --git a/packages/eve/extension-contracts/compatibility/tool/v25.ts b/packages/eve/extension-contracts/compatibility/tool/v25.ts
new file mode 100644
index 000000000..c8dabaad9
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v25.ts
@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+import { defineTool } from "#public/tools/index.js";
+
+export default defineTool({
+ description: "Start a durable report task.",
+ execution: "background",
+ inputSchema: z.object({ reportId: z.string() }),
+ execute(input, _ctx, task) {
+ return task.delegated({
+ executor: { data: { reportId: input.reportId }, kind: "report" },
+ receipt: { reportId: input.reportId },
+ });
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/channel/v15.json b/packages/eve/extension-contracts/reports/channel/v15.json
new file mode 100644
index 000000000..f83e12cb6
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v15.json
@@ -0,0 +1,21 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 15,
+ "sha256": "910218da61aa276f656b6e503a5889b17df475eae39447403f21ce75b496a714",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/connection/v13.json b/packages/eve/extension-contracts/reports/connection/v13.json
new file mode 100644
index 000000000..2fcd2031b
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v13.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 13,
+ "sha256": "447be9cb2cd90373eb075f73d94c7ea85c6908cf87bab51a07a92b376e8498ec",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineDynamic",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v17.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v17.json
new file mode 100644
index 000000000..8d715cfd4
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v17.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicInstructions",
+ "epoch": 17,
+ "sha256": "163356a47b3a63dd87250f394ab6ff6885469ce3d95a44af3eaa8514c1f8760f",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v16.json b/packages/eve/extension-contracts/reports/dynamicSkill/v16.json
new file mode 100644
index 000000000..0d584175c
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v16.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicSkill",
+ "epoch": 16,
+ "sha256": "834ad2b9b5e6e4c51e51aaa0c0f414cfb0ab9b9820b8e6449bf5d496d992eac5",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v26.json b/packages/eve/extension-contracts/reports/dynamicTool/v26.json
new file mode 100644
index 000000000..c23973d7e
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v26.json
@@ -0,0 +1,13 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 26,
+ "sha256": "a2a024f7e2baec7e2d9739fde250c03d0331480e731f534293dcb4535c57ba53",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v19.json b/packages/eve/extension-contracts/reports/hook/v19.json
new file mode 100644
index 000000000..668ab3c34
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v19.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 19,
+ "sha256": "5aebb4657f04fd4fab8e05797f4fecf9b2fdf92ef3ff47d975fa7873d8c03960",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/extension-contracts/reports/schedule/v8.json b/packages/eve/extension-contracts/reports/schedule/v8.json
new file mode 100644
index 000000000..e97615f82
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/schedule/v8.json
@@ -0,0 +1,14 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "schedule",
+ "epoch": 8,
+ "sha256": "a6266bbca0139bed5ba0f7f4f2ebeb7c49a91ada63e25736115cfbcb4da3c811",
+ "exports": [
+ "ScheduleDefinition",
+ "ScheduleHandlerArgs",
+ "ScheduleRunHandler",
+ "ScheduleToFn",
+ "TypedReceiveTarget",
+ "defineSchedule"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/subagent/v8.json b/packages/eve/extension-contracts/reports/subagent/v8.json
new file mode 100644
index 000000000..f339d5b80
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/subagent/v8.json
@@ -0,0 +1,20 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "subagent",
+ "epoch": 8,
+ "sha256": "d57bcf2dc3949952f9f8ef632701c179a6462ee0bb08314cbb99f54b7572c6f1",
+ "exports": [
+ "AgentCompactionDefinition",
+ "AgentDefinition",
+ "AgentModelDefinition",
+ "AgentStaticModelDefinition",
+ "DefinedAgent",
+ "DynamicLocalSubagentDefinition",
+ "DynamicSubagentDefinition",
+ "RemoteAgentDefinition",
+ "RemoteAgentDefinitionInput",
+ "defineAgent",
+ "defineDynamic",
+ "defineRemoteAgent"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v26.json b/packages/eve/extension-contracts/reports/tool/v26.json
new file mode 100644
index 000000000..a94a1e5b0
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v26.json
@@ -0,0 +1,19 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 26,
+ "sha256": "4dfff8c34551fd16609f490de077292a1b3957e919510c3e983f56f6b1a6d9c0",
+ "exports": [
+ "defaultWebSearch",
+ "defineTool",
+ "disableTool",
+ "experimental_workflow",
+ "isDisabledToolSentinel",
+ "isExperimentalWorkflowToolDefinition",
+ "isWebSearchToolDefinition",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch"
+ ]
+}
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index c84bd7091..86d5e08bf 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -28,7 +28,7 @@ import type { ChannelInstrumentationProjection } from "#channel/instrumentation.
export type RunSessionLimits = Pick<
AgentLimitsDefinition,
- "maxInputTokensPerSession" | "maxOutputTokensPerSession"
+ "maxInputTokensPerSession" | "maxOutputTokensPerSession" | "maxTokenCostUsdPerSession"
>;
/** Identifies the session turn to cancel. */
diff --git a/packages/eve/src/compiler/compile-from-memory.ts b/packages/eve/src/compiler/compile-from-memory.ts
index 39cc8cf2d..6f617cbd2 100644
--- a/packages/eve/src/compiler/compile-from-memory.ts
+++ b/packages/eve/src/compiler/compile-from-memory.ts
@@ -27,6 +27,7 @@ export interface CompileFromMemoryInput {
readonly limits?: {
readonly maxInputTokensPerSession?: number | false;
readonly maxOutputTokensPerSession?: number | false;
+ readonly maxTokenCostUsdPerSession?: number | false;
readonly sessionTimeoutMs?: number | false;
};
readonly outputSchema?: JsonObject;
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 329f20b79..2f66db611 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,38 +22,38 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 25,
+ current: 26,
supported: [
- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
],
dropped: { 15: "TaskExec replaces stageEffect with send" },
},
dynamicTool: {
- current: 25,
+ current: 26,
supported: [
- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25,
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25, 26,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
},
},
channel: {
- current: 14,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14],
+ current: 15,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
},
},
schedule: {
- current: 7,
- supported: [1, 2, 3, 4, 6, 7],
+ current: 8,
+ supported: [1, 2, 3, 4, 6, 7, 8],
dropped: {
5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
},
},
subagent: {
- current: 7,
- supported: [3, 4, 6, 7],
+ current: 8,
+ supported: [3, 4, 6, 7, 8],
dropped: {
1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",
2: "Persistent subagent sessions are now the default and the experimental opt-in was removed",
@@ -61,16 +61,16 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
connection: {
- current: 12,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12],
+ current: 13,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13],
dropped: {
9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",
10: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
},
},
hook: {
- current: 18,
- supported: [10, 11, 12, 13, 14, 15, 17, 18],
+ current: 19,
+ supported: [10, 11, 12, 13, 14, 15, 17, 18, 19],
dropped: {
1: "Model identity moved from session.started runtime metadata to step.started call attribution.",
2: "Model identity moved from session.started runtime metadata to step.started call attribution.",
@@ -86,16 +86,16 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
skill: { current: 1, supported: [1], dropped: {} },
dynamicSkill: {
- current: 15,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15],
+ current: 16,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16],
dropped: {
13: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
},
},
instructions: { current: 2, supported: [1, 2], dropped: {} },
dynamicInstructions: {
- current: 16,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16],
+ current: 17,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17],
dropped: {
14: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
},
diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.ts
index 90d380579..a647273f2 100644
--- a/packages/eve/src/compiler/manifest.test.ts
+++ b/packages/eve/src/compiler/manifest.test.ts
@@ -11,15 +11,17 @@ import {
validateCompiledModuleMap,
} from "#compiler/validate-artifact.js";
-describe("compiled agent manifest v44", () => {
+describe("compiled agent manifest v48", () => {
it("round-trips a real compiled graph through the serialized schema", async () => {
const { manifest } = await compileFromMemory({
+ limits: { maxTokenCostUsdPerSession: 1.5 },
model: "openai/gpt-5.4",
tools: [{ name: "weather" }],
});
const parsed = compiledAgentManifestSchema.parse(JSON.parse(JSON.stringify(manifest)));
expect(parsed.version).toBe(COMPILED_AGENT_MANIFEST_VERSION);
+ expect(parsed.config.limits?.maxTokenCostUsdPerSession).toBe(1.5);
expect(() => validateCompiledAgentManifest(parsed)).not.toThrow();
});
diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.ts
index 9cc208fce..f989e26f2 100644
--- a/packages/eve/src/compiler/manifest.ts
+++ b/packages/eve/src/compiler/manifest.ts
@@ -54,7 +54,7 @@ export const ROOT_COMPILED_AGENT_NODE_ID = "__root__";
/**
* Current compiled manifest schema version.
*/
-export const COMPILED_AGENT_MANIFEST_VERSION = 47;
+export const COMPILED_AGENT_MANIFEST_VERSION = 48;
/**
* Compiled channel entry preserved in the compiled manifest.
@@ -581,12 +581,14 @@ const compiledAgentCompactionDefinitionSchema: z.ZodType<CompiledAgentCompaction
.strict();
const sessionTokenLimitSchema = z.union([z.number().int().positive(), z.literal(false)]);
+const sessionTokenCostLimitSchema = z.union([z.number().finite().positive(), z.literal(false)]);
const sessionTimeoutSchema = z.union([z.number().int().positive(), z.literal(false)]);
const compiledAgentLimitsDefinitionSchema = z
.object({
maxInputTokensPerSession: sessionTokenLimitSchema.optional(),
maxOutputTokensPerSession: sessionTokenLimitSchema.optional(),
+ maxTokenCostUsdPerSession: sessionTokenCostLimitSchema.optional(),
sessionTimeoutMs: sessionTimeoutSchema.optional(),
})
.strict();
@@ -1215,6 +1217,7 @@ function cloneCompiledAgentDefinition(config: CompiledAgentDefinition): Compiled
: {
maxInputTokensPerSession: config.limits.maxInputTokensPerSession,
maxOutputTokensPerSession: config.limits.maxOutputTokensPerSession,
+ maxTokenCostUsdPerSession: config.limits.maxTokenCostUsdPerSession,
sessionTimeoutMs: config.limits.sessionTimeoutMs,
},
source: { ...config.source },
diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.ts
index 9113bcc0f..a4aceac4b 100644
--- a/packages/eve/src/compiler/normalize-agent-config.ts
+++ b/packages/eve/src/compiler/normalize-agent-config.ts
@@ -136,6 +136,7 @@ export async function compileAgentConfig(
compiledConfig.limits = {
maxInputTokensPerSession: definition.limits.maxInputTokensPerSession,
maxOutputTokensPerSession: definition.limits.maxOutputTokensPerSession,
+ maxTokenCostUsdPerSession: definition.limits.maxTokenCostUsdPerSession,
sessionTimeoutMs: definition.limits.sessionTimeoutMs,
};
}
diff --git a/packages/eve/src/execution/create-session-step.test.ts b/packages/eve/src/execution/create-session-step.test.ts
index 9c997ee96..51bd8688e 100644
--- a/packages/eve/src/execution/create-session-step.test.ts
+++ b/packages/eve/src/execution/create-session-step.test.ts
@@ -155,6 +155,25 @@ describe("createSessionStep", () => {
expect(state.snapshot?.session.limits?.maxInputTokensPerSession).toBe(2_000_000);
});
+ it("caps a configured child token-cost limit at the inherited budget", async () => {
+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
+ resolvedAgent: {
+ config: { limits: { maxTokenCostUsdPerSession: 2 } },
+ },
+ turnAgent: TestTurnAgent,
+ } as never);
+
+ const { state } = await createSessionStep({
+ compiledArtifactsSource: { kind: "bundled" },
+ continuationToken: "subagent:test",
+ inheritedLimits: { maxTokenCostUsdPerSession: 0.75 },
+ rootSessionId: "sess-root",
+ sessionId: "sess-child",
+ });
+
+ expect(state.snapshot?.session.limits?.maxTokenCostUsdPerSession).toBe(0.75);
+ });
+
it("keeps tighter configured child token limits under inherited token budget", async () => {
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
resolvedAgent: {
@@ -204,6 +223,7 @@ describe("createSessionStep", () => {
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
},
},
},
@@ -219,6 +239,7 @@ describe("createSessionStep", () => {
expect(state.snapshot?.session.limits).toMatchObject({
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
});
});
diff --git a/packages/eve/src/execution/create-session-step.ts b/packages/eve/src/execution/create-session-step.ts
index 7401ea2d1..2aae3078c 100644
--- a/packages/eve/src/execution/create-session-step.ts
+++ b/packages/eve/src/execution/create-session-step.ts
@@ -81,6 +81,10 @@ export async function createSessionStep(input: {
configured: effectiveAgent.limits?.maxOutputTokensPerSession,
inherited: input.inheritedLimits?.maxOutputTokensPerSession,
}),
+ maxTokenCostUsdPerSession: resolveInheritedTokenLimit({
+ configured: effectiveAgent.limits?.maxTokenCostUsdPerSession,
+ inherited: input.inheritedLimits?.maxTokenCostUsdPerSession,
+ }),
},
outputSchema: input.outputSchema,
rootSessionId: input.rootSessionId,
diff --git a/packages/eve/src/execution/run-session-limits.ts b/packages/eve/src/execution/run-session-limits.ts
index bf012e4da..9969af03e 100644
--- a/packages/eve/src/execution/run-session-limits.ts
+++ b/packages/eve/src/execution/run-session-limits.ts
@@ -1,18 +1,19 @@
import type { AgentLimitsDefinition } from "#shared/agent-definition.js";
-type TokenLimit =
+type UsageLimit =
| AgentLimitsDefinition["maxInputTokensPerSession"]
- | AgentLimitsDefinition["maxOutputTokensPerSession"];
+ | AgentLimitsDefinition["maxOutputTokensPerSession"]
+ | AgentLimitsDefinition["maxTokenCostUsdPerSession"];
/**
- * Resolves an authored token cap against an inherited parent cap. `false`
+ * Resolves an authored usage cap against an inherited parent cap. `false`
* only means "uncapped" before inheritance; an actual inherited cap still
* bounds the child.
*/
export function resolveInheritedTokenLimit(input: {
- readonly configured: TokenLimit | undefined;
- readonly inherited: TokenLimit | undefined;
-}): TokenLimit | undefined {
+ readonly configured: UsageLimit | undefined;
+ readonly inherited: UsageLimit | undefined;
+}): UsageLimit | undefined {
if (input.inherited === undefined || input.inherited === false) {
return input.configured;
}
diff --git a/packages/eve/src/execution/session-command-inbox.test.ts b/packages/eve/src/execution/session-command-inbox.test.ts
index 8fee18b18..021deb5af 100644
--- a/packages/eve/src/execution/session-command-inbox.test.ts
+++ b/packages/eve/src/execution/session-command-inbox.test.ts
@@ -123,7 +123,7 @@ describe("createSessionCommandInbox", () => {
);
expect(createHookMock).toHaveBeenCalledOnce();
expect(createHookMock).toHaveBeenCalledWith({
- metadata: { sessionInboxWireVersion: 4 },
+ metadata: { sessionInboxWireVersion: 5 },
token: "stable",
});
await inbox.dispose();
diff --git a/packages/eve/src/execution/session.test.ts b/packages/eve/src/execution/session.test.ts
index 5f3d69931..2a67320b3 100644
--- a/packages/eve/src/execution/session.test.ts
+++ b/packages/eve/src/execution/session.test.ts
@@ -365,6 +365,7 @@ describe("createSession", () => {
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
},
sessionId: "sess-root",
turnAgent: createTestTurnAgent(),
@@ -379,10 +380,12 @@ describe("createSession", () => {
expect(durable.limits).toEqual({
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
});
expect(hydrated.limits).toEqual({
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
});
});
diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.ts
index 775138afe..9568e79ef 100644
--- a/packages/eve/src/execution/session.ts
+++ b/packages/eve/src/execution/session.ts
@@ -21,6 +21,7 @@ export const DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION = 40_000_000;
export interface AuthoredSessionLimits {
readonly maxInputTokensPerSession?: number | false;
readonly maxOutputTokensPerSession?: number | false;
+ readonly maxTokenCostUsdPerSession?: number | false;
}
/**
@@ -337,13 +338,25 @@ function resolveSessionLimits(input: {
fallback: undefined,
});
- const limits: { maxInputTokensPerSession?: number; maxOutputTokensPerSession?: number } = {};
+ const maxTokenCostUsdPerSession = resolveSessionTokenLimit({
+ authored: input.limits?.maxTokenCostUsdPerSession,
+ fallback: undefined,
+ });
+
+ const limits: {
+ maxInputTokensPerSession?: number;
+ maxOutputTokensPerSession?: number;
+ maxTokenCostUsdPerSession?: number;
+ } = {};
if (maxInputTokensPerSession !== undefined) {
limits.maxInputTokensPerSession = maxInputTokensPerSession;
}
if (maxOutputTokensPerSession !== undefined) {
limits.maxOutputTokensPerSession = maxOutputTokensPerSession;
}
+ if (maxTokenCostUsdPerSession !== undefined) {
+ limits.maxTokenCostUsdPerSession = maxTokenCostUsdPerSession;
+ }
return limits;
}
diff --git a/packages/eve/src/execution/wire/__snapshots__/session-inbox-wire.v5.test.ts.snap b/packages/eve/src/execution/wire/__snapshots__/session-inbox-wire.v5.test.ts.snap
new file mode 100644
index 000000000..15932d3d5
--- /dev/null
+++ b/packages/eve/src/execution/wire/__snapshots__/session-inbox-wire.v5.test.ts.snap
@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`session inbox wire v5 > pins the complete schema byte for byte 1`] = `"{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"additionalProperties":false,"properties":{"auth":{"anyOf":[{"additionalProperties":false,"properties":{"attributes":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"propertyNames":{"type":"string"},"type":"object"},"authenticator":{"type":"string"},"issuer":{"type":"string"},"principalId":{"type":"string"},"principalType":{"type":"string"},"subject":{"type":"string"}},"required":["attributes","authenticator","principalId","principalType"],"type":"object"},{"type":"null"}]},"caller":{"additionalProperties":false,"properties":{"activityObserver":{"additionalProperties":false,"properties":{"sink":{"additionalProperties":false,"properties":{"url":{"type":"string"},"version":{"const":1,"type":"number"}},"required":["url","version"],"type":"object"},"workIdentity":{"additionalProperties":false,"properties":{"callId":{"type":"string"},"id":{"type":"string"},"kind":{"enum":["root-turn","subagent","remote-agent","task"],"type":"string"},"name":{"type":"string"},"parentId":{"type":"string"},"rootSessionId":{"type":"string"},"rootTurnId":{"type":"string"},"sessionId":{"type":"string"},"turnId":{"type":"string"}},"required":["id","kind","rootSessionId","rootTurnId"],"type":"object"}},"required":["sink"],"type":"object"},"callId":{"type":"string"},"replyTo":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"hook","type":"string"},"token":{"type":"string"}},"required":["kind","token"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"callback","type":"string"},"token":{"type":"string"},"url":{"type":"string"}},"required":["kind","token","url"],"type":"object"}]},"subagentName":{"type":"string"},"taskId":{"type":"string"}},"required":["callId","replyTo","subagentName"],"type":"object"},"deliveryMetadata":{"items":{"additionalProperties":false,"properties":{"acceptedDeploymentId":{"type":"string"},"channelKind":{"type":"string"},"channelName":{"type":"string"},"deliveryId":{"type":"string"},"payloadIndex":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"requestId":{"type":"string"},"requestTraceContext":{"additionalProperties":false,"properties":{"spanId":{"type":"string"},"traceFlags":{"type":"number"},"traceId":{"type":"string"}},"required":["spanId","traceFlags","traceId"],"type":"object"}},"required":["channelKind","channelName","deliveryId","payloadIndex"],"type":"object"},"type":"array"},"kind":{"const":"deliver","type":"string"},"payload":{"additionalProperties":{},"properties":{"context":{"items":{"type":"string"},"type":"array"},"inputResponses":{"items":{"additionalProperties":false,"properties":{"optionId":{"type":"string"},"requestId":{"type":"string"},"text":{"type":"string"}},"required":["requestId"],"type":"object"},"type":"array"},"message":{"anyOf":[{"type":"string"},{"items":{"oneOf":[{"additionalProperties":false,"properties":{"providerOptions":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"text":{"type":"string"},"type":{"const":"text","type":"string"}},"required":["text","type"],"type":"object"},{"additionalProperties":false,"properties":{"image":{},"mediaType":{"type":"string"},"providerOptions":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"type":{"const":"image","type":"string"}},"required":["image","type"],"type":"object"},{"additionalProperties":false,"properties":{"data":{},"filename":{"type":"string"},"mediaType":{"type":"string"},"providerOptions":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"type":{"const":"file","type":"string"}},"required":["data","mediaType","type"],"type":"object"}]},"type":"array"}]},"outputSchema":{},"task":{"additionalProperties":false,"properties":{"agentRequests":{"items":{"additionalProperties":false,"properties":{"replyTo":{"type":"string"},"request":{"oneOf":[{"additionalProperties":false,"properties":{"input":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"message":{"type":"string"},"outputSchema":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"target":{"type":"string"}},"required":["message","target"],"type":"object"},"invocationId":{"type":"string"},"kind":{"const":"agent-invoke","type":"string"}},"required":["input","invocationId","kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"agent-settled","type":"string"},"result":{"additionalProperties":false,"properties":{"backgroundTask":{"additionalProperties":false,"properties":{"status":{"const":"working","type":"string"},"taskId":{"type":"string"}},"required":["status","taskId"],"type":"object"},"callId":{"type":"string"},"isError":{"type":"boolean"},"kind":{"const":"subagent-result","type":"string"},"origin":{"const":"child","type":"string"},"outcome":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"parked","type":"string"},"result":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"succeeded","type":"string"},"output":{}},"required":["kind","output"],"type":"object"},{"additionalProperties":false,"properties":{"error":{},"kind":{"const":"failed","type":"string"}},"required":["error","kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"cancelled","type":"string"}},"required":["kind"],"type":"object"}]},"usageDelta":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["kind","result","usageDelta"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"terminal","type":"string"},"result":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"succeeded","type":"string"},"output":{}},"required":["kind","output"],"type":"object"},{"additionalProperties":false,"properties":{"error":{},"kind":{"const":"failed","type":"string"}},"required":["error","kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"cancelled","type":"string"}},"required":["kind"],"type":"object"}]},"usageDelta":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["kind","result","usageDelta"],"type":"object"}]},"output":{},"subagentName":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["callId","kind","origin","outcome","output","subagentName"],"type":"object"}},"required":["kind","result"],"type":"object"}]},"taskId":{"type":"string"}},"required":["replyTo","request","taskId"],"type":"object"},"type":"array"},"authorizationEvents":{"items":{"additionalProperties":false,"properties":{"hookPayload":{"additionalProperties":false,"properties":{"callId":{"type":"string"},"childSessionId":{"type":"string"},"event":{},"kind":{"const":"subagent-authorization-event","type":"string"},"subagentName":{"type":"string"}},"required":["callId","childSessionId","event","kind","subagentName"],"type":"object"},"taskId":{"type":"string"}},"required":["hookPayload","taskId"],"type":"object"},"type":"array"},"inputRequests":{"items":{"anyOf":[{"additionalProperties":{},"properties":{"replyTo":{"type":"string"},"request":{},"sequence":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"stepIndex":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"taskId":{"type":"string"},"turnId":{"type":"string"}},"required":["replyTo","sequence","stepIndex","taskId","turnId","request"],"type":"object"},{"additionalProperties":{},"properties":{"replyTo":{"type":"string"},"requests":{"items":{},"type":"array"},"sequence":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"stepIndex":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"taskId":{"type":"string"},"turnId":{"type":"string"}},"required":["replyTo","sequence","stepIndex","taskId","turnId","requests"],"type":"object"}]},"type":"array"},"views":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"working","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"inputRequests":{"items":{},"type":"array"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"input_required","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","inputRequests","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"lastOutput":{"additionalProperties":false,"properties":{"data":{},"type":{"const":"result","type":"string"}},"required":["data","type"],"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"completed","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","lastOutput","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"lastOutput":{"additionalProperties":false,"properties":{"data":{},"type":{"const":"error","type":"string"}},"required":["data","type"],"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"failed","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","lastOutput","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"cancelled","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","status"],"type":"object"}]},"type":"array"}},"type":"object"}},"type":"object"},"payloads":{"items":{"additionalProperties":{},"properties":{"context":{"items":{"type":"string"},"type":"array"},"inputResponses":{"items":{"additionalProperties":false,"properties":{"optionId":{"type":"string"},"requestId":{"type":"string"},"text":{"type":"string"}},"required":["requestId"],"type":"object"},"type":"array"},"message":{"anyOf":[{"type":"string"},{"items":{"oneOf":[{"additionalProperties":false,"properties":{"providerOptions":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"text":{"type":"string"},"type":{"const":"text","type":"string"}},"required":["text","type"],"type":"object"},{"additionalProperties":false,"properties":{"image":{},"mediaType":{"type":"string"},"providerOptions":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"type":{"const":"image","type":"string"}},"required":["image","type"],"type":"object"},{"additionalProperties":false,"properties":{"data":{},"filename":{"type":"string"},"mediaType":{"type":"string"},"providerOptions":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"type":{"const":"file","type":"string"}},"required":["data","mediaType","type"],"type":"object"}]},"type":"array"}]},"outputSchema":{},"task":{"additionalProperties":false,"properties":{"agentRequests":{"items":{"additionalProperties":false,"properties":{"replyTo":{"type":"string"},"request":{"oneOf":[{"additionalProperties":false,"properties":{"input":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"message":{"type":"string"},"outputSchema":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"target":{"type":"string"}},"required":["message","target"],"type":"object"},"invocationId":{"type":"string"},"kind":{"const":"agent-invoke","type":"string"}},"required":["input","invocationId","kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"agent-settled","type":"string"},"result":{"additionalProperties":false,"properties":{"backgroundTask":{"additionalProperties":false,"properties":{"status":{"const":"working","type":"string"},"taskId":{"type":"string"}},"required":["status","taskId"],"type":"object"},"callId":{"type":"string"},"isError":{"type":"boolean"},"kind":{"const":"subagent-result","type":"string"},"origin":{"const":"child","type":"string"},"outcome":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"parked","type":"string"},"result":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"succeeded","type":"string"},"output":{}},"required":["kind","output"],"type":"object"},{"additionalProperties":false,"properties":{"error":{},"kind":{"const":"failed","type":"string"}},"required":["error","kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"cancelled","type":"string"}},"required":["kind"],"type":"object"}]},"usageDelta":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["kind","result","usageDelta"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"terminal","type":"string"},"result":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"succeeded","type":"string"},"output":{}},"required":["kind","output"],"type":"object"},{"additionalProperties":false,"properties":{"error":{},"kind":{"const":"failed","type":"string"}},"required":["error","kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"cancelled","type":"string"}},"required":["kind"],"type":"object"}]},"usageDelta":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["kind","result","usageDelta"],"type":"object"}]},"output":{},"subagentName":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["callId","kind","origin","outcome","output","subagentName"],"type":"object"}},"required":["kind","result"],"type":"object"}]},"taskId":{"type":"string"}},"required":["replyTo","request","taskId"],"type":"object"},"type":"array"},"authorizationEvents":{"items":{"additionalProperties":false,"properties":{"hookPayload":{"additionalProperties":false,"properties":{"callId":{"type":"string"},"childSessionId":{"type":"string"},"event":{},"kind":{"const":"subagent-authorization-event","type":"string"},"subagentName":{"type":"string"}},"required":["callId","childSessionId","event","kind","subagentName"],"type":"object"},"taskId":{"type":"string"}},"required":["hookPayload","taskId"],"type":"object"},"type":"array"},"inputRequests":{"items":{"anyOf":[{"additionalProperties":{},"properties":{"replyTo":{"type":"string"},"request":{},"sequence":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"stepIndex":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"taskId":{"type":"string"},"turnId":{"type":"string"}},"required":["replyTo","sequence","stepIndex","taskId","turnId","request"],"type":"object"},{"additionalProperties":{},"properties":{"replyTo":{"type":"string"},"requests":{"items":{},"type":"array"},"sequence":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"stepIndex":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"taskId":{"type":"string"},"turnId":{"type":"string"}},"required":["replyTo","sequence","stepIndex","taskId","turnId","requests"],"type":"object"}]},"type":"array"},"views":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"working","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"inputRequests":{"items":{},"type":"array"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"input_required","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","inputRequests","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"lastOutput":{"additionalProperties":false,"properties":{"data":{},"type":{"const":"result","type":"string"}},"required":["data","type"],"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"completed","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","lastOutput","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"lastOutput":{"additionalProperties":false,"properties":{"data":{},"type":{"const":"error","type":"string"}},"required":["data","type"],"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"failed","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","lastOutput","status"],"type":"object"},{"additionalProperties":false,"properties":{"executor":{"additionalProperties":false,"properties":{"binding":{"additionalProperties":false,"properties":{"data":{"additionalProperties":{},"propertyNames":{"type":"string"},"type":"object"},"kind":{"type":"string"}},"required":["data","kind"],"type":"object"}},"type":"object"},"metadata":{"additionalProperties":false,"properties":{"agentId":{"type":"string"},"kind":{"type":"string"},"mode":{"enum":["local","remote"],"type":"string"},"name":{"type":"string"}},"required":["kind","name"],"type":"object"},"status":{"const":"cancelled","type":"string"},"taskId":{"type":"string"},"usage":{"properties":{"cacheReadTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"cacheWriteTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"costUsd":{"minimum":0,"type":"number"},"inputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"outputTokens":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["cacheReadTokens","cacheWriteTokens","inputTokens","outputTokens"],"type":"object"}},"required":["metadata","taskId","status"],"type":"object"}]},"type":"array"}},"type":"object"}},"type":"object"},"type":"array"},"requestId":{"type":"string"},"taskDeliveryId":{"type":"string"},"turnPolicy":{"enum":["queue","steer"],"type":"string"},"version":{"const":5,"type":"number"}},"required":["kind","payload","payloads","version"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"session-timeout","type":"string"},"version":{"const":5,"type":"number"}},"required":["kind","version"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"clear","type":"string"},"version":{"const":5,"type":"number"}},"required":["kind","version"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"compact","type":"string"},"version":{"const":5,"type":"number"}},"required":["kind","version"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"reset","type":"string"},"reason":{"type":"string"},"version":{"const":5,"type":"number"}},"required":["kind","version"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"cancel","type":"string"},"taskId":{"type":"string"},"turnId":{"type":"string"},"version":{"const":5,"type":"number"}},"required":["kind","version"],"type":"object"}]}"`;
diff --git a/packages/eve/src/execution/wire/session-inbox-contract.ts b/packages/eve/src/execution/wire/session-inbox-contract.ts
index c8b03cedd..fef334457 100644
--- a/packages/eve/src/execution/wire/session-inbox-contract.ts
+++ b/packages/eve/src/execution/wire/session-inbox-contract.ts
@@ -1,5 +1,5 @@
/** Every explicit session-inbox wire version still supported by producers. */
-export const SESSION_INBOX_WIRE_VERSIONS = [1, 2, 3, 4] as const;
+export const SESSION_INBOX_WIRE_VERSIONS = [1, 2, 3, 4, 5] as const;
export type SessionInboxWireVersion = (typeof SESSION_INBOX_WIRE_VERSIONS)[number];
diff --git a/packages/eve/src/execution/wire/session-inbox-encoder.ts b/packages/eve/src/execution/wire/session-inbox-encoder.ts
index ea1153667..5afa9c9e4 100644
--- a/packages/eve/src/execution/wire/session-inbox-encoder.ts
+++ b/packages/eve/src/execution/wire/session-inbox-encoder.ts
@@ -26,11 +26,15 @@ import {
encodeSessionCommandV4,
type SessionInboxWireV4,
} from "#execution/wire/session-inbox-wire.v4.js";
+import {
+ encodeSessionCommandV5,
+ type SessionInboxWireV5,
+} from "#execution/wire/session-inbox-wire.v5.js";
type SessionInboxCommand = DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload;
/** Current wire type consumed after migration. */
-export type SessionInboxWire = SessionInboxWireV4;
+export type SessionInboxWire = SessionInboxWireV5;
type LegacySessionInboxWireTarget = Extract<SessionInboxWireTarget, { readonly version: 0 }>;
type VersionedSessionInboxEncoder = (command: SessionInboxCommand) => unknown;
@@ -40,6 +44,7 @@ const versionedEncoders = {
2: (command: SessionInboxCommand) => encodeSessionCommandV2(withoutAcceptedDeployment(command)),
3: encodeSessionCommandV3,
4: encodeSessionCommandV4,
+ 5: encodeSessionCommandV5,
} satisfies Record<SessionInboxWireVersion, VersionedSessionInboxEncoder>;
/** Encodes a command for the selected session-inbox consumer. */
@@ -47,6 +52,7 @@ function encode(command: SessionInboxCommand, target: { readonly version: 1 }):
function encode(command: SessionInboxCommand, target: { readonly version: 2 }): SessionInboxWireV2;
function encode(command: SessionInboxCommand, target: { readonly version: 3 }): SessionInboxWireV3;
function encode(command: SessionInboxCommand, target: { readonly version: 4 }): SessionInboxWireV4;
+function encode(command: SessionInboxCommand, target: { readonly version: 5 }): SessionInboxWireV5;
function encode(
command: SessionInboxCommand,
target: { readonly version: SessionInboxWireVersion },
@@ -63,6 +69,7 @@ function encode(
| SessionInboxWireV2
| SessionInboxWireV3
| SessionInboxWireV4
+ | SessionInboxWireV5
| Record<string, unknown>;
function encode(
command: SessionInboxCommand,
@@ -72,11 +79,12 @@ function encode(
| SessionInboxWireV2
| SessionInboxWireV3
| SessionInboxWireV4
+ | SessionInboxWireV5
| Record<string, unknown> {
if (target.version === 0) {
const currentTaskWire =
target.variant === "send" && command.kind === "send" && command.payload.task !== undefined
- ? encodeSessionCommandV4(command)
+ ? encodeSessionCommandV5(command)
: undefined;
let legacy = encodeSessionCommandV0(
encodeSessionCommandV1(withoutCurrentTaskMessages(withoutAcceptedDeployment(command))),
@@ -107,7 +115,8 @@ function encode(
| SessionInboxWireV1
| SessionInboxWireV2
| SessionInboxWireV3
- | SessionInboxWireV4;
+ | SessionInboxWireV4
+ | SessionInboxWireV5;
}
throw new SessionInboxWireError(
`Cannot encode session inbox payload for unknown wire version ${JSON.stringify((target as { version?: unknown }).version)}.`,
diff --git a/packages/eve/src/execution/wire/session-inbox-wire.ts b/packages/eve/src/execution/wire/session-inbox-wire.ts
index fd7b3c04e..f5819a93f 100644
--- a/packages/eve/src/execution/wire/session-inbox-wire.ts
+++ b/packages/eve/src/execution/wire/session-inbox-wire.ts
@@ -18,6 +18,7 @@ import { normalizeSessionInboxWireV2 } from "#execution/wire/session-inbox-wire.
import { sessionInboxWireV1Migration } from "#execution/wire/session-inbox-wire.v2.migration.js";
import { sessionInboxWireV2Migration } from "#execution/wire/session-inbox-wire.v3.migration.js";
import { sessionInboxWireV3Migration } from "#execution/wire/session-inbox-wire.v4.migration.js";
+import { sessionInboxWireV4Migration } from "#execution/wire/session-inbox-wire.v5.migration.js";
import { isObject } from "#shared/guards.js";
/**
@@ -48,6 +49,7 @@ const sessionInboxMigrations: readonly VersionMigration[] = [
sessionInboxWireV1Migration,
sessionInboxWireV2Migration,
sessionInboxWireV3Migration,
+ sessionInboxWireV4Migration,
];
/**
diff --git a/packages/eve/src/execution/wire/session-inbox-wire.v5.migration.test.ts b/packages/eve/src/execution/wire/session-inbox-wire.v5.migration.test.ts
new file mode 100644
index 000000000..8906b1a7d
--- /dev/null
+++ b/packages/eve/src/execution/wire/session-inbox-wire.v5.migration.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { sessionInboxWireV4Migration } from "#execution/wire/session-inbox-wire.v5.migration.js";
+
+describe("session inbox wire v5 migration", () => {
+ it("rejects malformed direct migration input", () => {
+ expect(() => sessionInboxWireV4Migration.migrate(null)).toThrow(
+ "session inbox wire v4 value is not an object",
+ );
+ });
+
+ it("preserves a version-4 payload while advancing its version", () => {
+ expect(
+ sessionInboxWireV4Migration.migrate({
+ kind: "deliver",
+ payload: { message: "hello" },
+ payloads: [{ message: "hello" }],
+ version: 4,
+ }),
+ ).toEqual({
+ kind: "deliver",
+ payload: { message: "hello" },
+ payloads: [{ message: "hello" }],
+ version: 5,
+ });
+ });
+});
diff --git a/packages/eve/src/execution/wire/session-inbox-wire.v5.migration.ts b/packages/eve/src/execution/wire/session-inbox-wire.v5.migration.ts
new file mode 100644
index 000000000..0f618ac90
--- /dev/null
+++ b/packages/eve/src/execution/wire/session-inbox-wire.v5.migration.ts
@@ -0,0 +1,12 @@
+import type { VersionMigration } from "#execution/durable-session-migrations/chain.js";
+import { isObject } from "#shared/guards.js";
+
+/** Advances version-4 payloads to the additive token-cost schema. */
+export const sessionInboxWireV4Migration: VersionMigration = {
+ from: 4,
+ migrate(prior) {
+ if (!isObject(prior)) throw new Error("session inbox wire v4 value is not an object.");
+ return { ...prior, version: 5 };
+ },
+ to: 5,
+};
diff --git a/packages/eve/src/execution/wire/session-inbox-wire.v5.test.ts b/packages/eve/src/execution/wire/session-inbox-wire.v5.test.ts
new file mode 100644
index 000000000..c4e39a253
--- /dev/null
+++ b/packages/eve/src/execution/wire/session-inbox-wire.v5.test.ts
@@ -0,0 +1,230 @@
+import { describe, expect, it } from "vitest";
+import { z } from "#compiled/zod/index.js";
+
+import { sessionInboxWire } from "#execution/wire/session-inbox-encoder.js";
+import { sessionInboxWire as sessionInboxWireDecoder } from "#execution/wire/session-inbox-wire.js";
+import { sessionInboxWireV5Schema } from "#execution/wire/session-inbox-wire.v5.js";
+
+const agentRequest = {
+ replyTo: "agent-reply",
+ request: {
+ input: { message: "Find it", target: "research" },
+ invocationId: "call-1:research",
+ kind: "agent-invoke" as const,
+ },
+ taskId: "task-1",
+};
+const authorizationEvent = {
+ hookPayload: {
+ callId: "call-1",
+ childSessionId: "child-1",
+ event: {
+ data: {
+ description: "Authorize Linear",
+ name: "linear",
+ sequence: 1,
+ stepIndex: 2,
+ turnId: "turn-child",
+ },
+ type: "authorization.required" as const,
+ },
+ kind: "subagent-authorization-event" as const,
+ subagentName: "research",
+ },
+ taskId: "task-1",
+};
+const inputRequest = {
+ replyTo: "answer-hook",
+ request: { kind: "question", prompt: "Continue?", requestId: "request-1" },
+ sequence: 2,
+ stepIndex: 3,
+ taskId: "task-1",
+ turnId: "turn-1",
+};
+
+describe("session inbox wire v5", () => {
+ it("round-trips task-owned agent requests, authorization events, and input requests", () => {
+ const task = {
+ agentRequests: [
+ agentRequest,
+ {
+ replyTo: "agent-reply",
+ request: {
+ kind: "agent-settled" as const,
+ result: {
+ callId: "call-1",
+ kind: "subagent-result" as const,
+ origin: "child" as const,
+ outcome: {
+ kind: "terminal" as const,
+ result: { kind: "succeeded" as const, output: "done" },
+ usageDelta: {
+ cacheReadTokens: 0,
+ cacheWriteTokens: 0,
+ costUsd: 0.25,
+ inputTokens: 10,
+ outputTokens: 2,
+ },
+ },
+ output: "done",
+ subagentName: "research",
+ },
+ },
+ taskId: "task-1",
+ },
+ ],
+ authorizationEvents: [authorizationEvent],
+ inputRequests: [inputRequest],
+ };
+ const wire = sessionInboxWire.encode({ kind: "send", payload: { task } }, { version: 5 });
+
+ expect(sessionInboxWireDecoder.decode(wire)).toMatchObject({
+ kind: "deliver",
+ payloads: [{ task }],
+ });
+ });
+
+ it("rejects malformed task authorization events", () => {
+ expect(() =>
+ sessionInboxWire.encode(
+ {
+ kind: "send",
+ payload: {
+ task: { authorizationEvents: [{ hookPayload: { kind: "other" }, taskId: "task-1" }] },
+ } as never,
+ },
+ { version: 5 },
+ ),
+ ).toThrow(/wire version 5/);
+ });
+
+ it.each([1, 2, 3, 4] as const)("omits token cost for v%i consumers", (version) => {
+ const wire = sessionInboxWire.encode(
+ {
+ kind: "send",
+ payload: {
+ task: {
+ views: [
+ {
+ metadata: { kind: "subagent", name: "research" },
+ status: "working",
+ taskId: "task-1",
+ usage: {
+ cacheReadTokens: 0,
+ cacheWriteTokens: 0,
+ costUsd: 0.25,
+ inputTokens: 10,
+ outputTokens: 2,
+ },
+ },
+ ],
+ },
+ },
+ } as never,
+ { version },
+ ) as { payload: { task: { views: Array<{ usage: object }> } } };
+
+ expect(wire.payload.task.views[0]?.usage).not.toHaveProperty("costUsd");
+ });
+
+ it.each([1, 2, 3] as const)(
+ "rejects v5 task agent requests falsely declared as immutable v%i",
+ (version) => {
+ expect(() =>
+ sessionInboxWireDecoder.decode({
+ kind: "deliver",
+ payload: { task: { agentRequests: [agentRequest] } },
+ payloads: [{ task: { agentRequests: [agentRequest] } }],
+ version,
+ }),
+ ).toThrow(new RegExp(`does not match wire version ${version}`));
+ },
+ );
+
+ it.each([1, 2, 3] as const)(
+ "rejects v5 task input requests falsely declared as immutable v%i",
+ (version) => {
+ const { request: _request, ...inputRequestBase } = inputRequest;
+ for (const request of [inputRequest, { ...inputRequestBase, requests: [] }]) {
+ expect(() =>
+ sessionInboxWireDecoder.decode({
+ kind: "deliver",
+ payload: { task: { inputRequests: [request] } },
+ payloads: [{ task: { inputRequests: [request] } }],
+ version,
+ }),
+ ).toThrow(new RegExp(`does not match wire version ${version}`));
+ }
+ },
+ );
+
+ it("round-trips batched task input requests", () => {
+ const { request: _request, ...batch } = inputRequest;
+ const batchedRequest = { ...batch, requests: [inputRequest.request] };
+
+ expect(
+ sessionInboxWireDecoder.decode({
+ kind: "deliver",
+ payload: { task: { inputRequests: [batchedRequest] } },
+ payloads: [{ task: { inputRequests: [batchedRequest] } }],
+ version: 5,
+ }),
+ ).toMatchObject({
+ payloads: [{ task: { inputRequests: [batchedRequest] } }],
+ });
+ });
+
+ it("carries current task messages through the stable raw-send fast path", () => {
+ const wire = sessionInboxWire.encode(
+ {
+ kind: "send",
+ payload: { task: { agentRequests: [agentRequest], inputRequests: [inputRequest] } },
+ },
+ { variant: "send", version: 0 },
+ );
+
+ expect(wire).toMatchObject({
+ kind: "send",
+ payload: { task: { agentRequests: [agentRequest], inputRequests: [inputRequest] } },
+ });
+ expect(sessionInboxWireDecoder.decode(wire)).toMatchObject({
+ kind: "deliver",
+ payloads: [{ task: { agentRequests: [agentRequest], inputRequests: [inputRequest] } }],
+ });
+ });
+
+ it("round-trips accepted deployment provenance", () => {
+ const delivery = {
+ acceptedDeploymentId: "dpl_current",
+ channelKind: "channel:webhook",
+ channelName: "webhook",
+ deliveryId: "delivery-1",
+ };
+ const wire = sessionInboxWire.encode(
+ { delivery, kind: "send", payload: { message: "hello" } },
+ { version: 5 },
+ );
+
+ expect(sessionInboxWireDecoder.decode(wire)).toMatchObject({
+ deliveryMetadata: [{ ...delivery, payloadIndex: 0 }],
+ kind: "deliver",
+ });
+ });
+
+ it("pins the complete schema byte for byte", () => {
+ expect(
+ stableStringify(
+ z.toJSONSchema(sessionInboxWireV5Schema, { io: "input", unrepresentable: "any" }),
+ ),
+ ).toMatchSnapshot();
+ });
+});
+
+function stableStringify(value: unknown): string {
+ return JSON.stringify(value, (_key, item) => {
+ if (item === null || typeof item !== "object" || Array.isArray(item)) return item;
+ return Object.fromEntries(
+ Object.entries(item).sort(([left], [right]) => left.localeCompare(right)),
+ );
+ });
+}
diff --git a/packages/eve/src/execution/wire/session-inbox-wire.v5.ts b/packages/eve/src/execution/wire/session-inbox-wire.v5.ts
new file mode 100644
index 000000000..5acb0ecef
--- /dev/null
+++ b/packages/eve/src/execution/wire/session-inbox-wire.v5.ts
@@ -0,0 +1,231 @@
+import { z } from "#compiled/zod/index.js";
+
+import type {
+ DeliverHookPayload,
+ SessionCommand,
+ SessionTimeoutHookPayload,
+} from "#channel/types.js";
+import { coalesceDeliverPayloads } from "#execution/deliver-payloads.js";
+import { SessionInboxWireError } from "#execution/wire/session-inbox-contract.js";
+import { sessionInboxWireV3Schema } from "#execution/wire/session-inbox-wire.v3.js";
+import { formatValidationError } from "#runtime/validation.js";
+import { jsonValueSchema } from "#shared/json-schemas.js";
+import { tokenUsageWithCostSchema } from "#shared/token-usage.js";
+import type { TaskView } from "#tasks/types.js";
+
+const taskMetadataSchema = z
+ .object({
+ agentId: z.string().optional(),
+ kind: z.string(),
+ mode: z.enum(["local", "remote"]).optional(),
+ name: z.string(),
+ })
+ .strict();
+const taskExecutorSchema = z
+ .object({
+ binding: z
+ .object({
+ data: z.record(z.string(), jsonValueSchema),
+ kind: z.string(),
+ })
+ .strict()
+ .optional(),
+ })
+ .strict();
+const taskViewBase = {
+ executor: taskExecutorSchema.optional(),
+ metadata: taskMetadataSchema,
+ taskId: z.string(),
+ usage: tokenUsageWithCostSchema.optional(),
+};
+const taskViewSchema: z.ZodType<TaskView> = z.discriminatedUnion("status", [
+ z.object({ ...taskViewBase, status: z.literal("working") }).strict(),
+ z
+ .object({
+ ...taskViewBase,
+ inputRequests: z.array(jsonValueSchema),
+ status: z.literal("input_required"),
+ })
+ .strict(),
+ z
+ .object({
+ ...taskViewBase,
+ lastOutput: z.object({ data: jsonValueSchema, type: z.literal("result") }).strict(),
+ status: z.literal("completed"),
+ })
+ .strict(),
+ z
+ .object({
+ ...taskViewBase,
+ lastOutput: z.object({ data: jsonValueSchema, type: z.literal("error") }).strict(),
+ status: z.literal("failed"),
+ })
+ .strict(),
+ z.object({ ...taskViewBase, status: z.literal("cancelled") }).strict(),
+]);
+const eventCoordinateSchema = z.number().int().nonnegative();
+const taskInputRequestBase = {
+ replyTo: z.string(),
+ sequence: eventCoordinateSchema,
+ stepIndex: eventCoordinateSchema,
+ taskId: z.string(),
+ turnId: z.string(),
+};
+const taskInputRequestSchema = z.union([
+ z
+ .object({
+ ...taskInputRequestBase,
+ request: jsonValueSchema,
+ })
+ .loose(),
+ z
+ .object({
+ ...taskInputRequestBase,
+ requests: z.array(jsonValueSchema),
+ })
+ .loose(),
+]);
+const agentInvocationInputSchema = z
+ .object({
+ agentId: z.string().optional(),
+ message: z.string(),
+ outputSchema: z.record(z.string(), jsonValueSchema).optional(),
+ target: z.string(),
+ })
+ .strict();
+const agentTurnResultSchema = z.discriminatedUnion("kind", [
+ z.strictObject({ kind: z.literal("succeeded"), output: jsonValueSchema }),
+ z.strictObject({ error: jsonValueSchema, kind: z.literal("failed") }),
+ z.strictObject({ kind: z.literal("cancelled") }),
+]);
+const agentTurnOutcomeSchema = z.discriminatedUnion("kind", [
+ z.strictObject({
+ kind: z.literal("parked"),
+ result: agentTurnResultSchema,
+ usageDelta: tokenUsageWithCostSchema,
+ }),
+ z.strictObject({
+ kind: z.literal("terminal"),
+ result: agentTurnResultSchema,
+ usageDelta: tokenUsageWithCostSchema,
+ }),
+]);
+const runtimeSubagentChildResultSchema = z
+ .object({
+ backgroundTask: z.strictObject({ status: z.literal("working"), taskId: z.string() }).optional(),
+ callId: z.string(),
+ isError: z.boolean().optional(),
+ kind: z.literal("subagent-result"),
+ origin: z.literal("child"),
+ outcome: agentTurnOutcomeSchema,
+ output: jsonValueSchema,
+ subagentName: z.string(),
+ usage: tokenUsageWithCostSchema.optional(),
+ })
+ .strict();
+const taskAgentRequestSchema = z
+ .object({
+ replyTo: z.string(),
+ request: z.discriminatedUnion("kind", [
+ z
+ .object({
+ input: agentInvocationInputSchema,
+ invocationId: z.string(),
+ kind: z.literal("agent-invoke"),
+ })
+ .strict(),
+ z
+ .object({
+ kind: z.literal("agent-settled"),
+ result: runtimeSubagentChildResultSchema,
+ })
+ .strict(),
+ ]),
+ taskId: z.string(),
+ })
+ .strict();
+const subagentAuthorizationEventHookPayloadSchema = z
+ .object({
+ callId: z.string(),
+ childSessionId: z.string(),
+ event: z.custom<Record<string, unknown>>(
+ (value) => typeof value === "object" && value !== null && !Array.isArray(value),
+ "Expected an object.",
+ ),
+ kind: z.literal("subagent-authorization-event"),
+ subagentName: z.string(),
+ })
+ .strict();
+const taskAuthorizationEventSchema = z
+ .object({
+ hookPayload: subagentAuthorizationEventHookPayloadSchema,
+ taskId: z.string(),
+ })
+ .strict();
+const taskPayloadV5Schema = z
+ .object({
+ agentRequests: z.array(taskAgentRequestSchema).optional(),
+ authorizationEvents: z.array(taskAuthorizationEventSchema).optional(),
+ inputRequests: z.array(taskInputRequestSchema).optional(),
+ views: z.array(taskViewSchema).optional(),
+ })
+ .strict();
+
+const v3 = sessionInboxWireV3Schema.options;
+const v3Deliver = v3[0];
+const deliverPayloadV5Schema = v3Deliver.shape.payload.extend({
+ task: taskPayloadV5Schema.optional(),
+});
+const VERSION = 5;
+const version = z.literal(VERSION);
+
+/** Version 5 adds model token cost to delegated usage reports. */
+export const sessionInboxWireV5Schema = z.discriminatedUnion("kind", [
+ v3Deliver.extend({
+ payload: deliverPayloadV5Schema,
+ payloads: z.array(deliverPayloadV5Schema),
+ version,
+ }),
+ v3[1].extend({ version }),
+ v3[2].extend({ version }),
+ v3[3].extend({ version }),
+ v3[4].extend({ version }),
+ v3[5].extend({ version }),
+]);
+
+export type SessionInboxWireV5 = z.infer<typeof sessionInboxWireV5Schema>;
+
+/** Builds and validates one complete version-5 wire value. */
+export function encodeSessionCommandV5(
+ command: DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload,
+): SessionInboxWireV5 {
+ const wire =
+ command.kind === "send"
+ ? {
+ auth: command.auth,
+ caller: command.caller,
+ deliveryMetadata:
+ command.delivery === undefined ? undefined : [{ ...command.delivery, payloadIndex: 0 }],
+ kind: "deliver" as const,
+ payload: command.payload,
+ payloads: [command.payload],
+ requestId: command.requestId,
+ taskDeliveryId: command.taskDeliveryId,
+ turnPolicy: command.turnPolicy,
+ version: VERSION,
+ }
+ : command.kind === "deliver"
+ ? {
+ ...command,
+ payload: coalesceDeliverPayloads(command.payloads),
+ version: VERSION,
+ }
+ : { ...command, version: VERSION };
+ const parsed = sessionInboxWireV5Schema.safeParse(wire);
+ if (!parsed.success) {
+ throw new SessionInboxWireError(
+ `Produced a session inbox payload that does not match wire version ${VERSION}: ${formatValidationError(parsed.error)}`,
+ );
+ }
+ return parsed.data;
+}
diff --git a/packages/eve/src/harness/session-limit-continuation.test.ts b/packages/eve/src/harness/session-limit-continuation.test.ts
index f415dd898..d41623d36 100644
--- a/packages/eve/src/harness/session-limit-continuation.test.ts
+++ b/packages/eve/src/harness/session-limit-continuation.test.ts
@@ -54,6 +54,25 @@ describe("createSessionLimitContinuationRequest", () => {
});
});
+ it("creates a token-cost continuation prompt", () => {
+ const request = createSessionLimitContinuationRequest({
+ sessionId: "sess-test",
+ violation: { kind: "token-cost", limitUsd: 1.5, usedCostUsd: 1.5123 },
+ });
+
+ expect(request).toMatchObject({
+ action: {
+ callId: "sess-test:limit:token-cost:1.5123",
+ input: { kind: "token-cost", limitUsd: 1.5, usedCostUsd: 1.5123 },
+ },
+ prompt:
+ "This session has hit the $1.5 model token-cost limit per session. This is a guardrail " +
+ "against defective long-running sessions. If session activity looks fine, just " +
+ "approve to keep going.",
+ requestId: "sess-test:limit:token-cost:1.5123",
+ });
+ });
+
it("formats the limit compactly in the prompt copy", () => {
const promptFor = (limit: number): string =>
createSessionLimitContinuationRequest({
@@ -66,6 +85,13 @@ describe("createSessionLimitContinuationRequest", () => {
expect(promptFor(200_000)).toContain("(200K)");
expect(promptFor(1_500)).toContain("(1.5K)");
expect(promptFor(999)).toContain("(999)");
+
+ const tinyCost = createSessionLimitContinuationRequest({
+ sessionId: "sess-test",
+ violation: { kind: "token-cost", limitUsd: 5e-7, usedCostUsd: 6e-7 },
+ });
+ expect(tinyCost.prompt).toContain("$5e-7 model token-cost limit");
+ expect(isSessionLimitContinuationRequestId(tinyCost.requestId)).toBe(true);
});
it("gives each violation instance its own id as the session total grows", () => {
@@ -86,6 +112,7 @@ describe("createSessionLimitContinuationRequest", () => {
it("mints ids recognized by isSessionLimitContinuationRequestId", () => {
expect(isSessionLimitContinuationRequestId(createTestRequest().requestId)).toBe(true);
expect(isSessionLimitContinuationRequestId("sess-test:limit:output:12")).toBe(true);
+ expect(isSessionLimitContinuationRequestId("sess-test:limit:token-cost:1.5123")).toBe(true);
expect(isSessionLimitContinuationRequestId("approval-1")).toBe(false);
expect(isSessionLimitContinuationRequestId("sess-test:limit:input:")).toBe(false);
});
diff --git a/packages/eve/src/harness/session-limit-continuation.ts b/packages/eve/src/harness/session-limit-continuation.ts
index 7198919bb..69182a83c 100644
--- a/packages/eve/src/harness/session-limit-continuation.ts
+++ b/packages/eve/src/harness/session-limit-continuation.ts
@@ -1,14 +1,15 @@
/**
- * Deterministic HITL continuation prompt for session token limits.
+ * Deterministic HITL continuation prompt for session usage limits.
*
- * When a durable session reaches its configured token budget, the harness
+ * When a durable session reaches its configured token or token-cost budget, the harness
* parks on a harness-authored input request instead of failing the session.
* The request is derived only from the session identity and violation, so
* identical session state always produces an identical prompt — no model call
* is involved.
*/
import type { InputRequest, InputResponse } from "#shared/input.js";
-import type { SessionTokenLimitViolation } from "#harness/turn-tag-state.js";
+import type { JsonObject } from "#shared/json.js";
+import type { SessionUsageLimitViolation } from "#harness/turn-tag-state.js";
/** Synthetic action tool name carried by session-limit continuation requests. */
export const SESSION_LIMIT_CONTINUATION_TOOL_NAME = "session_limit_continuation";
@@ -20,30 +21,36 @@ export const SESSION_LIMIT_CONTINUE_OPTION_ID = "continue";
export const SESSION_LIMIT_STOP_OPTION_ID = "stop";
/**
- * Builds the deterministic continuation prompt for one session token limit
+ * Builds the deterministic continuation prompt for one session usage-limit
* violation.
*/
export function createSessionLimitContinuationRequest(input: {
readonly sessionId: string;
- readonly violation: SessionTokenLimitViolation;
+ readonly violation: SessionUsageLimitViolation;
}): InputRequest {
const { sessionId, violation } = input;
- // `usedTokens` is the absolute session total, which is strictly increasing
- // across violations, so each prompt gets its own id while staying
- // deterministic: stale chat controls from an earlier, already-resolved
- // prompt carry an unknown requestId, resolve nothing, and the harness
- // harmlessly re-prompts instead of letting an old "Stop" button end a
- // freshly granted session.
- const requestId = `${sessionId}:limit:${violation.kind}:${String(violation.usedTokens)}`;
+ const used = violation.kind === "token-cost" ? violation.usedCostUsd : violation.usedTokens;
+ // The absolute session usage is strictly increasing across violations, so
+ // each prompt gets a deterministic id and stale controls cannot resolve a
+ // later prompt.
+ const requestId = `${sessionId}:limit:${violation.kind}:${String(used)}`;
+ const actionInput: JsonObject =
+ violation.kind === "token-cost"
+ ? {
+ kind: violation.kind,
+ limitUsd: violation.limitUsd,
+ usedCostUsd: violation.usedCostUsd,
+ }
+ : {
+ kind: violation.kind,
+ limit: violation.limit,
+ usedTokens: violation.usedTokens,
+ };
return {
action: {
callId: requestId,
- input: {
- kind: violation.kind,
- limit: violation.limit,
- usedTokens: violation.usedTokens,
- },
+ input: actionInput,
kind: "tool-call",
toolName: SESSION_LIMIT_CONTINUATION_TOOL_NAME,
},
@@ -52,7 +59,10 @@ export function createSessionLimitContinuationRequest(input: {
kind: "session-limit",
options: [
{
- description: "Grant a fresh token budget",
+ description:
+ violation.kind === "token-cost"
+ ? "Grant a fresh model token-cost budget"
+ : "Grant a fresh token budget",
id: SESSION_LIMIT_CONTINUE_OPTION_ID,
label: "Approve",
style: "primary",
@@ -64,11 +74,7 @@ export function createSessionLimitContinuationRequest(input: {
style: "danger",
},
],
- prompt:
- `This session has hit the ${violation.kind}-token limit ` +
- `(${formatCompactTokenCount(violation.limit)}) per session. This is a guardrail ` +
- `against defective long-running sessions. If session activity looks fine, ` +
- `just approve to keep going.`,
+ prompt: formatSessionLimitPrompt(violation),
requestId,
};
}
@@ -92,6 +98,23 @@ function trimTrailingZero(value: number): string {
return rounded.endsWith(".0") ? rounded.slice(0, -2) : rounded;
}
+function formatSessionLimitPrompt(violation: SessionUsageLimitViolation): string {
+ const reachedLimit =
+ violation.kind === "token-cost"
+ ? `${formatUsd(violation.limitUsd)} model token-cost limit per session`
+ : `${violation.kind}-token limit (${formatCompactTokenCount(violation.limit)}) per session`;
+ return (
+ `This session has hit the ${reachedLimit}. This is a guardrail ` +
+ `against defective long-running sessions. If session activity looks fine, ` +
+ `just approve to keep going.`
+ );
+}
+
+function formatUsd(costUsd: number): string {
+ const value = costUsd < 0.000001 ? String(costUsd) : costUsd.toFixed(6);
+ return `$${value.replace(/0+$/u, "").replace(/\.$/u, "")}`;
+}
+
/**
* Returns true when a request is a harness-authored session-limit
* continuation prompt.
@@ -108,7 +131,10 @@ export function isSessionLimitContinuationRequest(request: InputRequest): boolea
* stale continuation answer after its request left the pending batch.
*/
export function isSessionLimitContinuationRequestId(requestId: string): boolean {
- return /:limit:(?:input|output):\d+$/u.test(requestId);
+ return (
+ /:limit:(?:input|output):\d+$/u.test(requestId) ||
+ /:limit:token-cost:\d+(?:\.\d+)?(?:e[+-]?\d+)?$/iu.test(requestId)
+ );
}
/**
diff --git a/packages/eve/src/harness/session-limit-enforcement.ts b/packages/eve/src/harness/session-limit-enforcement.ts
index 7a30b5827..2212c7b9e 100644
--- a/packages/eve/src/harness/session-limit-enforcement.ts
+++ b/packages/eve/src/harness/session-limit-enforcement.ts
@@ -1,12 +1,12 @@
/**
- * Session token limit policy for the tool-loop harness.
+ * Session token and token-cost limit policy for the tool-loop harness.
*
* Two seams into the harness step:
*
* 1. {@link applySessionLimitContinuation} runs after pending-input
* resolution and acts on the user's answer to a continuation prompt —
* grant a fresh budget window, or cancel the in-flight turn tree.
- * 2. {@link enforceSessionTokenLimit} runs before each model call and, when
+ * 2. {@link enforceSessionUsageLimit} runs before each model call and, when
* the session is over budget, parks it on the deterministic continuation
* prompt (sessions that can reach a human) or fails it (task-mode sessions
* without HITL — nobody can answer the prompt).
@@ -24,14 +24,15 @@ import { appendPendingInputBatch } from "#harness/input-requests.js";
import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
import { SessionLimitDeclinedError } from "#harness/turn-cancellation.js";
import {
- bumpSessionRuntimeTokenLimits,
- getSessionTokenLimitViolation,
+ bumpSessionRuntimeUsageLimits,
+ getSessionUsageLimitViolation,
getSessionTokenUsage,
- type SessionTokenLimitViolation,
+ type SessionUsageLimitViolation,
} from "#harness/turn-tag-state.js";
import type { HarnessSession, StepResult, ToolLoopHarnessConfig } from "#harness/types.js";
const SESSION_TOKEN_LIMIT_REACHED_CODE = "SESSION_TOKEN_LIMIT_REACHED";
+const SESSION_TOKEN_COST_LIMIT_REACHED_CODE = "SESSION_TOKEN_COST_LIMIT_REACHED";
interface SessionLimitPolicyInput {
readonly config: ToolLoopHarnessConfig;
@@ -44,7 +45,7 @@ interface SessionLimitPolicyInput {
* Acts on a resolved session-limit continuation answer.
*
* Granted: bumps the runtime token limits via
- * {@link bumpSessionRuntimeTokenLimits} and lets the step continue
+ * {@link bumpSessionRuntimeUsageLimits} and lets the step continue
* transparently.
* Declined: a user decision, not an error — the decline cancels the
* in-flight turn tree through the standard cancellation path, settling as
@@ -67,7 +68,7 @@ export async function applySessionLimitContinuation(
}
if (input.limitContinuation.granted) {
- return { result: null, session: bumpSessionRuntimeTokenLimits(input.session) };
+ return { result: null, session: bumpSessionRuntimeUsageLimits(input.session) };
}
// A session parked on the continuation prompt always satisfies the
@@ -79,12 +80,12 @@ export async function applySessionLimitContinuation(
const canSettleCancelledPark =
input.config.mode === "conversation" || input.session.continuationToken !== "";
if (!canSettleCancelledPark) {
- const violation = getSessionTokenLimitViolation(input.session);
+ const violation = getSessionUsageLimitViolation(input.session);
return {
result:
violation === null
? { next: { done: true, output: "" }, session: input.session }
- : await failSessionTokenLimit({ ...input, violation }),
+ : await failSessionUsageLimit({ ...input, violation }),
session: input.session,
};
}
@@ -100,10 +101,10 @@ export async function applySessionLimitContinuation(
* task-mode sessions without HITL fail fast with
* `SESSION_TOKEN_LIMIT_REACHED`.
*/
-export async function enforceSessionTokenLimit(
+export async function enforceSessionUsageLimit(
input: SessionLimitPolicyInput & { readonly messages: readonly ModelMessage[] },
): Promise<StepResult | null> {
- const violation = getSessionTokenLimitViolation(input.session);
+ const violation = getSessionUsageLimitViolation(input.session);
if (violation === null) {
return null;
}
@@ -113,14 +114,14 @@ export async function enforceSessionTokenLimit(
// Approving would bump the runtime limit by the configured limit -- zero --
// so fail the child and let its parent reach the resumable limit gate.
if (
- violation.limit > 0 &&
+ violationWindow(violation) > 0 &&
emit !== undefined &&
(input.config.mode === "conversation" || input.config.capabilities?.requestInput === true)
) {
- return parkOnSessionTokenLimit({ ...input, emit, violation });
+ return parkOnSessionUsageLimit({ ...input, emit, violation });
}
- return failSessionTokenLimit({ ...input, violation });
+ return failSessionUsageLimit({ ...input, violation });
}
/**
@@ -129,13 +130,13 @@ export async function enforceSessionTokenLimit(
* carries the step's accumulated messages so the triggering user message
* survives into the resumed turn.
*/
-async function parkOnSessionTokenLimit(input: {
+async function parkOnSessionUsageLimit(input: {
readonly config: ToolLoopHarnessConfig;
readonly emit: NonNullable<ToolLoopHarnessConfig["handleEvent"]>;
readonly emissionState: HarnessEmissionState;
readonly messages: readonly ModelMessage[];
readonly session: HarnessSession;
- readonly violation: SessionTokenLimitViolation;
+ readonly violation: SessionUsageLimitViolation;
}): Promise<StepResult> {
const request = createSessionLimitContinuationRequest({
sessionId: input.session.sessionId,
@@ -173,30 +174,47 @@ async function parkOnSessionTokenLimit(input: {
};
}
-function formatSessionTokenLimitMessage(kind: SessionTokenLimitViolation["kind"]): string {
- return `The session reached its configured ${kind} token limit.`;
+function violationWindow(violation: SessionUsageLimitViolation): number {
+ return violation.kind === "token-cost" ? violation.limitUsd : violation.limit;
}
-async function failSessionTokenLimit(input: {
+function formatSessionLimitMessage(kind: SessionUsageLimitViolation["kind"]): string {
+ return kind === "token-cost"
+ ? "The session reached its configured model token-cost limit."
+ : `The session reached its configured ${kind} token limit.`;
+}
+
+async function failSessionUsageLimit(input: {
readonly config: ToolLoopHarnessConfig;
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
readonly emissionState: HarnessEmissionState;
readonly session: HarnessSession;
- readonly violation: SessionTokenLimitViolation;
+ readonly violation: SessionUsageLimitViolation;
}): 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,
- };
+ const message = formatSessionLimitMessage(input.violation.kind);
+ const details: import("#shared/json.js").JsonObject =
+ input.violation.kind === "token-cost"
+ ? {
+ costUsd: usage.costUsd,
+ kind: input.violation.kind,
+ limitUsd: input.violation.limitUsd,
+ usedCostUsd: input.violation.usedCostUsd,
+ }
+ : {
+ 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,
+ code:
+ input.violation.kind === "token-cost"
+ ? SESSION_TOKEN_COST_LIMIT_REACHED_CODE
+ : SESSION_TOKEN_LIMIT_REACHED_CODE,
details,
message,
sessionId: input.session.sessionId,
diff --git a/packages/eve/src/harness/session-token-limits.test.ts b/packages/eve/src/harness/session-token-limits.test.ts
deleted file mode 100644
index 02b6ccb2b..000000000
--- a/packages/eve/src/harness/session-token-limits.test.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
- findRuntimeTokenLimitViolation,
- grantRuntimeTokenLimits,
- remainingRuntimeTokenQuota,
- resolveRuntimeTokenLimits,
-} from "#harness/session-token-limits.js";
-
-const CONFIGURED = { inputTokens: 100, outputTokens: 50 };
-
-describe("session token-limit transitions", () => {
- it.each([
- { configured: {}, expected: {}, stored: undefined },
- { configured: CONFIGURED, expected: CONFIGURED, stored: undefined },
- {
- configured: CONFIGURED,
- expected: { inputTokens: 250, outputTokens: 50 },
- stored: { inputTokens: 250 },
- },
- ])("resolves configured and granted ceilings", ({ configured, expected, stored }) => {
- expect(resolveRuntimeTokenLimits({ configured, stored })).toEqual(expected);
- });
-
- it.each([
- {
- configured: CONFIGURED,
- expected: { inputTokens: 100, outputTokens: 50 },
- usage: { inputTokens: 0, outputTokens: 0 },
- },
- {
- configured: CONFIGURED,
- expected: { inputTokens: 450, outputTokens: 170 },
- usage: { inputTokens: 350, outputTokens: 120 },
- },
- {
- configured: { inputTokens: 100 },
- expected: { inputTokens: 140 },
- usage: { inputTokens: 40, outputTokens: 999 },
- },
- ])("grants one full window from current usage", ({ configured, expected, usage }) => {
- expect(grantRuntimeTokenLimits({ configured, usage })).toEqual(expected);
- });
-
- it.each([
- {
- expected: { inputTokens: false, outputTokens: false },
- runtime: {},
- usage: { inputTokens: 1_000, outputTokens: 1_000 },
- },
- {
- expected: { inputTokens: 60, outputTokens: 40 },
- runtime: CONFIGURED,
- usage: { inputTokens: 40, outputTokens: 10 },
- },
- {
- expected: { inputTokens: 0, outputTokens: 0 },
- runtime: CONFIGURED,
- usage: { inputTokens: 150, outputTokens: 80 },
- },
- ])("computes remaining quota without negative values", ({ expected, runtime, usage }) => {
- expect(remainingRuntimeTokenQuota({ runtime, usage })).toEqual(expected);
- });
-
- it.each([
- {
- configured: CONFIGURED,
- expected: null,
- runtime: CONFIGURED,
- usage: { inputTokens: 99, outputTokens: 49 },
- },
- {
- configured: CONFIGURED,
- expected: { kind: "input", limit: 100, usedTokens: 100 },
- runtime: CONFIGURED,
- usage: { inputTokens: 100, outputTokens: 50 },
- },
- {
- configured: CONFIGURED,
- expected: { kind: "output", limit: 50, usedTokens: 50 },
- runtime: CONFIGURED,
- usage: { inputTokens: 0, outputTokens: 50 },
- },
- {
- configured: { inputTokens: 0 },
- expected: { kind: "input", limit: 0, usedTokens: 0 },
- runtime: { inputTokens: 0 },
- usage: { inputTokens: 0, outputTokens: 0 },
- },
- {
- configured: CONFIGURED,
- expected: { kind: "input", limit: 100, usedTokens: 200 },
- runtime: { inputTokens: 200, outputTokens: 100 },
- usage: { inputTokens: 200, outputTokens: 0 },
- },
- ])("finds the first exhausted axis", ({ configured, expected, runtime, usage }) => {
- expect(
- findRuntimeTokenLimitViolation({
- configured,
- runtime,
- usage,
- }),
- ).toEqual(expected);
- });
-});
diff --git a/packages/eve/src/harness/session-token-limits.ts b/packages/eve/src/harness/session-token-limits.ts
deleted file mode 100644
index 91afae671..000000000
--- a/packages/eve/src/harness/session-token-limits.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-export interface SessionTokenAmounts {
- readonly inputTokens: number;
- readonly outputTokens: number;
-}
-
-export interface SessionRuntimeTokenLimits {
- readonly inputTokens?: number;
- readonly outputTokens?: number;
-}
-
-export type SessionTokenLimitViolation =
- | {
- readonly kind: "input";
- readonly limit: number;
- readonly usedTokens: number;
- }
- | {
- readonly kind: "output";
- readonly limit: number;
- readonly usedTokens: number;
- };
-
-/** Resolves per-axis lifetime ceilings, preferring a previously granted ceiling. */
-export function resolveRuntimeTokenLimits(input: {
- readonly configured: SessionRuntimeTokenLimits;
- readonly stored?: SessionRuntimeTokenLimits;
-}): SessionRuntimeTokenLimits {
- const limits: { inputTokens?: number; outputTokens?: number } = {};
- const inputTokens = input.stored?.inputTokens ?? input.configured.inputTokens;
- if (inputTokens !== undefined) {
- limits.inputTokens = inputTokens;
- }
- const outputTokens = input.stored?.outputTokens ?? input.configured.outputTokens;
- if (outputTokens !== undefined) {
- limits.outputTokens = outputTokens;
- }
- return limits;
-}
-
-/** Grants one full configured window from the current lifetime usage. */
-export function grantRuntimeTokenLimits(input: {
- readonly configured: SessionRuntimeTokenLimits;
- readonly usage: SessionTokenAmounts;
-}): SessionRuntimeTokenLimits {
- const limits: { inputTokens?: number; outputTokens?: number } = {};
- if (input.configured.inputTokens !== undefined) {
- limits.inputTokens = input.usage.inputTokens + input.configured.inputTokens;
- }
- if (input.configured.outputTokens !== undefined) {
- limits.outputTokens = input.usage.outputTokens + input.configured.outputTokens;
- }
- return limits;
-}
-
-/** Returns the unspent quota for each capped axis. */
-export function remainingRuntimeTokenQuota(input: {
- readonly runtime: SessionRuntimeTokenLimits;
- readonly usage: SessionTokenAmounts;
-}): {
- readonly inputTokens: number | false;
- readonly outputTokens: number | false;
-} {
- return {
- inputTokens:
- input.runtime.inputTokens === undefined
- ? false
- : Math.max(0, input.runtime.inputTokens - input.usage.inputTokens),
- outputTokens:
- input.runtime.outputTokens === undefined
- ? false
- : Math.max(0, input.runtime.outputTokens - input.usage.outputTokens),
- };
-}
-
-/** Returns the first exhausted axis, with input taking precedence. */
-export function findRuntimeTokenLimitViolation(input: {
- readonly configured: SessionRuntimeTokenLimits;
- readonly runtime: SessionRuntimeTokenLimits;
- readonly usage: SessionTokenAmounts;
-}): SessionTokenLimitViolation | null {
- if (
- input.runtime.inputTokens !== undefined &&
- input.configured.inputTokens !== undefined &&
- input.usage.inputTokens >= input.runtime.inputTokens
- ) {
- return {
- kind: "input",
- limit: input.configured.inputTokens,
- usedTokens: input.usage.inputTokens,
- };
- }
- if (
- input.runtime.outputTokens !== undefined &&
- input.configured.outputTokens !== undefined &&
- input.usage.outputTokens >= input.runtime.outputTokens
- ) {
- return {
- kind: "output",
- limit: input.configured.outputTokens,
- usedTokens: input.usage.outputTokens,
- };
- }
- return null;
-}
diff --git a/packages/eve/src/harness/session-usage-limits.test.ts b/packages/eve/src/harness/session-usage-limits.test.ts
new file mode 100644
index 000000000..37bde419a
--- /dev/null
+++ b/packages/eve/src/harness/session-usage-limits.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ findRuntimeUsageLimitViolation,
+ grantRuntimeUsageLimits,
+ remainingRuntimeUsageQuota,
+ resolveRuntimeUsageLimits,
+} from "#harness/session-usage-limits.js";
+
+const CONFIGURED = { costUsd: 1.5, inputTokens: 100, outputTokens: 50 };
+
+describe("session usage-limit transitions", () => {
+ it.each([
+ { configured: {}, expected: {}, stored: undefined },
+ { configured: CONFIGURED, expected: CONFIGURED, stored: undefined },
+ {
+ configured: CONFIGURED,
+ expected: { costUsd: 3, inputTokens: 250, outputTokens: 50 },
+ stored: { costUsd: 3, inputTokens: 250 },
+ },
+ ])("resolves configured and granted ceilings", ({ configured, expected, stored }) => {
+ expect(resolveRuntimeUsageLimits({ configured, stored })).toEqual(expected);
+ });
+
+ it.each([
+ {
+ configured: CONFIGURED,
+ expected: { costUsd: 1.5, inputTokens: 100, outputTokens: 50 },
+ usage: { costUsd: 0, inputTokens: 0, outputTokens: 0 },
+ },
+ {
+ configured: CONFIGURED,
+ expected: { costUsd: 3.25, inputTokens: 450, outputTokens: 170 },
+ usage: { costUsd: 1.75, inputTokens: 350, outputTokens: 120 },
+ },
+ {
+ configured: { inputTokens: 100 },
+ expected: { inputTokens: 140 },
+ usage: { inputTokens: 40, outputTokens: 999 },
+ },
+ ])("grants one full window from current usage", ({ configured, expected, usage }) => {
+ expect(grantRuntimeUsageLimits({ configured, usage })).toEqual(expected);
+ });
+
+ it.each([
+ {
+ expected: { costUsd: false, inputTokens: false, outputTokens: false },
+ runtime: {},
+ usage: { costUsd: 2, inputTokens: 1_000, outputTokens: 1_000 },
+ },
+ {
+ expected: { costUsd: 1, inputTokens: 60, outputTokens: 40 },
+ runtime: CONFIGURED,
+ usage: { costUsd: 0.5, inputTokens: 40, outputTokens: 10 },
+ },
+ {
+ expected: { costUsd: 0, inputTokens: 0, outputTokens: 0 },
+ runtime: CONFIGURED,
+ usage: { costUsd: 2, inputTokens: 150, outputTokens: 80 },
+ },
+ ])("computes remaining quota without negative values", ({ expected, runtime, usage }) => {
+ expect(remainingRuntimeUsageQuota({ runtime, usage })).toEqual(expected);
+ });
+
+ it.each([
+ {
+ configured: CONFIGURED,
+ expected: null,
+ runtime: CONFIGURED,
+ usage: { costUsd: 1.49, inputTokens: 99, outputTokens: 49 },
+ },
+ {
+ configured: CONFIGURED,
+ expected: { kind: "input", limit: 100, usedTokens: 100 },
+ runtime: CONFIGURED,
+ usage: { costUsd: 1.5, inputTokens: 100, outputTokens: 50 },
+ },
+ {
+ configured: CONFIGURED,
+ expected: { kind: "output", limit: 50, usedTokens: 50 },
+ runtime: CONFIGURED,
+ usage: { costUsd: 1.5, inputTokens: 0, outputTokens: 50 },
+ },
+ {
+ configured: { costUsd: 1.5 },
+ expected: { kind: "token-cost", limitUsd: 1.5, usedCostUsd: 1.5 },
+ runtime: { costUsd: 1.5 },
+ usage: { costUsd: 1.5, inputTokens: 0, outputTokens: 0 },
+ },
+ {
+ configured: { inputTokens: 0 },
+ expected: { kind: "input", limit: 0, usedTokens: 0 },
+ runtime: { inputTokens: 0 },
+ usage: { inputTokens: 0, outputTokens: 0 },
+ },
+ {
+ configured: CONFIGURED,
+ expected: { kind: "input", limit: 100, usedTokens: 200 },
+ runtime: { costUsd: 3, inputTokens: 200, outputTokens: 100 },
+ usage: { costUsd: 2, inputTokens: 200, outputTokens: 0 },
+ },
+ ])("finds the first exhausted axis", ({ configured, expected, runtime, usage }) => {
+ expect(findRuntimeUsageLimitViolation({ configured, runtime, usage })).toEqual(expected);
+ });
+});
diff --git a/packages/eve/src/harness/session-usage-limits.ts b/packages/eve/src/harness/session-usage-limits.ts
new file mode 100644
index 000000000..31dbdb25d
--- /dev/null
+++ b/packages/eve/src/harness/session-usage-limits.ts
@@ -0,0 +1,128 @@
+export interface SessionUsageAmounts {
+ readonly costUsd?: number;
+ readonly inputTokens: number;
+ readonly outputTokens: number;
+}
+
+export interface SessionRuntimeUsageLimits {
+ readonly costUsd?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+}
+
+export type SessionUsageLimitViolation =
+ | {
+ readonly kind: "input";
+ readonly limit: number;
+ readonly usedTokens: number;
+ }
+ | {
+ readonly kind: "output";
+ readonly limit: number;
+ readonly usedTokens: number;
+ }
+ | {
+ readonly kind: "token-cost";
+ readonly limitUsd: number;
+ readonly usedCostUsd: number;
+ };
+
+/** Resolves per-axis lifetime ceilings, preferring a previously granted ceiling. */
+export function resolveRuntimeUsageLimits(input: {
+ readonly configured: SessionRuntimeUsageLimits;
+ readonly stored?: SessionRuntimeUsageLimits;
+}): SessionRuntimeUsageLimits {
+ const limits: { costUsd?: number; inputTokens?: number; outputTokens?: number } = {};
+ const inputTokens = input.stored?.inputTokens ?? input.configured.inputTokens;
+ if (inputTokens !== undefined) limits.inputTokens = inputTokens;
+ const outputTokens = input.stored?.outputTokens ?? input.configured.outputTokens;
+ if (outputTokens !== undefined) limits.outputTokens = outputTokens;
+ const costUsd = input.stored?.costUsd ?? input.configured.costUsd;
+ if (costUsd !== undefined) limits.costUsd = costUsd;
+ return limits;
+}
+
+/** Grants one full configured window from the current lifetime usage. */
+export function grantRuntimeUsageLimits(input: {
+ readonly configured: SessionRuntimeUsageLimits;
+ readonly usage: SessionUsageAmounts;
+}): SessionRuntimeUsageLimits {
+ const limits: { costUsd?: number; inputTokens?: number; outputTokens?: number } = {};
+ if (input.configured.inputTokens !== undefined) {
+ limits.inputTokens = input.usage.inputTokens + input.configured.inputTokens;
+ }
+ if (input.configured.outputTokens !== undefined) {
+ limits.outputTokens = input.usage.outputTokens + input.configured.outputTokens;
+ }
+ if (input.configured.costUsd !== undefined) {
+ limits.costUsd = (input.usage.costUsd ?? 0) + input.configured.costUsd;
+ }
+ return limits;
+}
+
+/** Returns the unspent quota for each capped axis. */
+export function remainingRuntimeUsageQuota(input: {
+ readonly runtime: SessionRuntimeUsageLimits;
+ readonly usage: SessionUsageAmounts;
+}): {
+ readonly costUsd: number | false;
+ readonly inputTokens: number | false;
+ readonly outputTokens: number | false;
+} {
+ return {
+ costUsd:
+ input.runtime.costUsd === undefined
+ ? false
+ : Math.max(0, input.runtime.costUsd - (input.usage.costUsd ?? 0)),
+ inputTokens:
+ input.runtime.inputTokens === undefined
+ ? false
+ : Math.max(0, input.runtime.inputTokens - input.usage.inputTokens),
+ outputTokens:
+ input.runtime.outputTokens === undefined
+ ? false
+ : Math.max(0, input.runtime.outputTokens - input.usage.outputTokens),
+ };
+}
+
+/** Returns the first exhausted axis: input tokens, output tokens, then token cost. */
+export function findRuntimeUsageLimitViolation(input: {
+ readonly configured: SessionRuntimeUsageLimits;
+ readonly runtime: SessionRuntimeUsageLimits;
+ readonly usage: SessionUsageAmounts;
+}): SessionUsageLimitViolation | null {
+ if (
+ input.runtime.inputTokens !== undefined &&
+ input.configured.inputTokens !== undefined &&
+ input.usage.inputTokens >= input.runtime.inputTokens
+ ) {
+ return {
+ kind: "input",
+ limit: input.configured.inputTokens,
+ usedTokens: input.usage.inputTokens,
+ };
+ }
+ if (
+ input.runtime.outputTokens !== undefined &&
+ input.configured.outputTokens !== undefined &&
+ input.usage.outputTokens >= input.runtime.outputTokens
+ ) {
+ return {
+ kind: "output",
+ limit: input.configured.outputTokens,
+ usedTokens: input.usage.outputTokens,
+ };
+ }
+ if (
+ input.runtime.costUsd !== undefined &&
+ input.configured.costUsd !== undefined &&
+ (input.usage.costUsd ?? 0) >= input.runtime.costUsd
+ ) {
+ return {
+ kind: "token-cost",
+ limitUsd: input.configured.costUsd,
+ usedCostUsd: input.usage.costUsd ?? 0,
+ };
+ }
+ return null;
+}
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 20b0dfc85..fe8ce4e8e 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -74,7 +74,7 @@ import { stashToolInterrupt } from "#harness/tool-interrupts.js";
import { appendMissingToolResultMessages, createToolLoopHarness } from "#harness/tool-loop.js";
import { isSessionLimitDecline, TurnCancelledError } from "#harness/turn-cancellation.js";
import {
- getSessionTokenLimitViolation,
+ getSessionUsageLimitViolation,
getSessionTokenUsage,
setTurnUsageState,
} from "#harness/turn-tag-state.js";
@@ -1914,9 +1914,10 @@ describe("createToolLoopHarness", () => {
expect(vi.mocked(ToolLoopAgent).mock.calls[0]?.[0]).toMatchObject({ reasoning: "high" });
});
- it("accumulates provider-reported token usage across the session", async () => {
+ it("accumulates provider-reported token usage and cost across the session", async () => {
setupMockAgent({
finishReason: "stop",
+ providerMetadata: { gateway: { cost: "0.0123" } },
response: { messages: [{ content: "Hello!", role: "assistant" }] },
text: "Hello!",
toolCalls: [],
@@ -1934,10 +1935,10 @@ describe("createToolLoopHarness", () => {
expect(getSessionTokenUsage(result.session)).toEqual({
cacheReadTokens: 2,
cacheWriteTokens: 1,
- costUsd: 0,
+ costUsd: 0.0123,
inputTokens: 7,
outputTokens: 3,
- sawCost: false,
+ sawCost: true,
});
});
@@ -1962,6 +1963,7 @@ describe("createToolLoopHarness", () => {
outputTokens: 3,
sawCost: false,
},
+ errorCode: "SESSION_TOKEN_LIMIT_REACHED",
tokenKind: "input",
},
{
@@ -1984,10 +1986,33 @@ describe("createToolLoopHarness", () => {
outputTokens: 3,
sawCost: false,
},
+ errorCode: "SESSION_TOKEN_LIMIT_REACHED",
tokenKind: "output",
},
+ {
+ details: {
+ costUsd: 1.51,
+ kind: "token-cost",
+ limitUsd: 1.5,
+ usedCostUsd: 1.51,
+ },
+ message: "The session reached its configured model token-cost limit.",
+ limits: {
+ maxTokenCostUsdPerSession: 1.5,
+ },
+ usage: {
+ cacheReadTokens: 2,
+ cacheWriteTokens: 1,
+ costUsd: 1.51,
+ inputTokens: 7,
+ outputTokens: 3,
+ sawCost: true,
+ },
+ errorCode: "SESSION_TOKEN_COST_LIMIT_REACHED",
+ tokenKind: "model token-cost",
+ },
])(
- "fails fast after the $tokenKind token limit when the session cannot request input",
+ "fails fast after the $tokenKind limit when the session cannot request input",
async (testCase) => {
const { emit, events } = createEventCollector();
const runStep = createToolLoopHarness(createTestConfig("task", emit));
@@ -2011,7 +2036,7 @@ describe("createToolLoopHarness", () => {
"session.failed",
]);
expect(events.find((event) => event.type === "step.failed")?.data).toMatchObject({
- code: "SESSION_TOKEN_LIMIT_REACHED",
+ code: testCase.errorCode,
details: testCase.details,
message: testCase.message,
});
@@ -2080,6 +2105,50 @@ describe("createToolLoopHarness", () => {
});
});
+ it("parks and grants a fresh model token-cost budget", async () => {
+ const usage = {
+ cacheReadTokens: 0,
+ cacheWriteTokens: 0,
+ costUsd: 1.51,
+ inputTokens: 12,
+ outputTokens: 3,
+ sawCost: true,
+ };
+ const reached = setTurnUsageState(
+ createTestSession({ limits: { maxTokenCostUsdPerSession: 1.5 } }),
+ { turnId: "turn_previous", ...usage, session: usage },
+ );
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
+
+ const parked = await runStep(reached, { message: "Hi again" });
+ expect(events.find((event) => event.type === "input.requested")?.data).toMatchObject({
+ requests: [
+ {
+ action: {
+ input: { kind: "token-cost", limitUsd: 1.5, usedCostUsd: 1.51 },
+ },
+ prompt: expect.stringContaining("$1.5 model token-cost limit"),
+ requestId: "test-session:limit:token-cost:1.51",
+ },
+ ],
+ });
+
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ });
+ const resumed = await runStep(parked.session, {
+ inputResponses: [{ optionId: "continue", requestId: "test-session:limit:token-cost:1.51" }],
+ });
+
+ expect(vi.mocked(ToolLoopAgent)).toHaveBeenCalledTimes(1);
+ expect(getSessionUsageLimitViolation(resumed.session)).toBeNull();
+ });
+
it("grants a fresh token budget when the user continues past the limit prompt", async () => {
setupMockAgent({
finishReason: "stop",
@@ -2101,7 +2170,7 @@ describe("createToolLoopHarness", () => {
expect(vi.mocked(ToolLoopAgent)).toHaveBeenCalledTimes(1);
expect(resumed.next).toBeNull();
- expect(getSessionTokenLimitViolation(resumed.session)).toBeNull();
+ expect(getSessionUsageLimitViolation(resumed.session)).toBeNull();
// The parked user message survives into model history for the resumed call.
expect(resumed.session.history).toContainEqual({ content: "Hi again", role: "user" });
const resolutionIndex = events.findIndex((event) => event.type === "input.resolved");
@@ -2144,7 +2213,7 @@ describe("createToolLoopHarness", () => {
expect(vi.mocked(ToolLoopAgent)).toHaveBeenCalledTimes(1);
expect(resumed.next).toBeNull();
- expect(getSessionTokenLimitViolation(resumed.session)).toBeNull();
+ expect(getSessionUsageLimitViolation(resumed.session)).toBeNull();
});
it("cancels the turn when the user declines the limit continuation prompt", async () => {
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index a25f9c81a..e269fe956 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -107,7 +107,7 @@ import {
} from "#harness/turn-tag-state.js";
import {
applySessionLimitContinuation,
- enforceSessionTokenLimit,
+ enforceSessionUsageLimit,
} from "#harness/session-limit-enforcement.js";
import { setEveAttributes } from "#runtime/attributes/emit.js";
import {
@@ -1517,7 +1517,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
return pendingWorkflowInterrupt;
}
- const limitResult = await enforceSessionTokenLimit({
+ const limitResult = await enforceSessionUsageLimit({
config,
emit,
emissionState,
diff --git a/packages/eve/src/harness/turn-tag-state.test.ts b/packages/eve/src/harness/turn-tag-state.test.ts
index ecca6e5f5..285177be0 100644
--- a/packages/eve/src/harness/turn-tag-state.test.ts
+++ b/packages/eve/src/harness/turn-tag-state.test.ts
@@ -3,10 +3,10 @@ import { describe, expect, it } from "vitest";
import {
accumulateSessionUsage,
accumulateTurnUsage,
- bumpSessionRuntimeTokenLimits,
- getSessionRemainingTokenQuota,
- getSessionRuntimeTokenLimits,
- getSessionTokenLimitViolation,
+ bumpSessionRuntimeUsageLimits,
+ getSessionRemainingUsageQuota,
+ getSessionRuntimeUsageLimits,
+ getSessionUsageLimitViolation,
getSessionTokenUsage,
getTurnUsageState,
setTurnUsageState,
@@ -322,7 +322,7 @@ describe("session token limits", () => {
},
});
- expect(getSessionTokenLimitViolation({ ...session, limits: testCase.limits })).toEqual(
+ expect(getSessionUsageLimitViolation({ ...session, limits: testCase.limits })).toEqual(
testCase.expected,
);
});
@@ -341,17 +341,17 @@ describe("session token limits", () => {
limits: { maxInputTokensPerSession: 10, maxOutputTokensPerSession: 3 },
};
- expect(getSessionTokenLimitViolation(session)).toEqual({
+ expect(getSessionUsageLimitViolation(session)).toEqual({
kind: "input",
limit: 10,
usedTokens: 10,
});
- const bumped = bumpSessionRuntimeTokenLimits(session);
+ const bumped = bumpSessionRuntimeUsageLimits(session);
// Both axes bump together so a session near two limits gets one prompt.
- expect(getSessionRuntimeTokenLimits(bumped)).toEqual({ inputTokens: 20, outputTokens: 6 });
- expect(getSessionTokenLimitViolation({ ...bumped, limits: session.limits })).toBeNull();
+ expect(getSessionRuntimeUsageLimits(bumped)).toEqual({ inputTokens: 20, outputTokens: 6 });
+ expect(getSessionUsageLimitViolation({ ...bumped, limits: session.limits })).toBeNull();
const laterUsage = { ...usage, inputTokens: 20, outputTokens: 3 };
const later = setTurnUsageState(bumped, {
@@ -361,7 +361,7 @@ describe("session token limits", () => {
});
// `limit` reports the configured window size; `usedTokens` the lifetime total.
- expect(getSessionTokenLimitViolation({ ...later, limits: session.limits })).toEqual({
+ expect(getSessionUsageLimitViolation({ ...later, limits: session.limits })).toEqual({
kind: "input",
limit: 10,
usedTokens: 20,
@@ -383,13 +383,13 @@ describe("session token limits", () => {
limits: { maxInputTokensPerSession: 10 },
};
- expect(getSessionTokenLimitViolation(session)?.usedTokens).toBe(35);
+ expect(getSessionUsageLimitViolation(session)).toMatchObject({ usedTokens: 35 });
// One approval always unblocks: the runtime limit re-anchors to
// usage + configured limit rather than incrementing by the limit.
- const bumped = bumpSessionRuntimeTokenLimits(session);
- expect(getSessionRuntimeTokenLimits(bumped)).toEqual({ inputTokens: 45 });
- expect(getSessionTokenLimitViolation({ ...bumped, limits: session.limits })).toBeNull();
+ const bumped = bumpSessionRuntimeUsageLimits(session);
+ expect(getSessionRuntimeUsageLimits(bumped)).toEqual({ inputTokens: 45 });
+ expect(getSessionUsageLimitViolation({ ...bumped, limits: session.limits })).toBeNull();
// A second grant cycle moves the ceiling again -- never idempotent.
const laterUsage = { ...usage, inputTokens: 45 };
@@ -398,10 +398,10 @@ describe("session token limits", () => {
...laterUsage,
session: laterUsage,
});
- expect(getSessionTokenLimitViolation({ ...later, limits: session.limits })).not.toBeNull();
- const bumpedAgain = bumpSessionRuntimeTokenLimits(later);
- expect(getSessionRuntimeTokenLimits(bumpedAgain)).toEqual({ inputTokens: 55 });
- expect(getSessionTokenLimitViolation({ ...bumpedAgain, limits: session.limits })).toBeNull();
+ expect(getSessionUsageLimitViolation({ ...later, limits: session.limits })).not.toBeNull();
+ const bumpedAgain = bumpSessionRuntimeUsageLimits(later);
+ expect(getSessionRuntimeUsageLimits(bumpedAgain)).toEqual({ inputTokens: 55 });
+ expect(getSessionUsageLimitViolation({ ...bumpedAgain, limits: session.limits })).toBeNull();
});
it("reports remaining quota from the runtime limit", () => {
@@ -418,11 +418,13 @@ describe("session token limits", () => {
limits: { maxInputTokensPerSession: 10 },
};
- expect(getSessionRemainingTokenQuota(session)).toEqual({
+ expect(getSessionRemainingUsageQuota(session)).toEqual({
+ costUsd: false,
inputTokens: 6,
outputTokens: false,
});
- expect(getSessionRemainingTokenQuota(makeSession())).toEqual({
+ expect(getSessionRemainingUsageQuota(makeSession())).toEqual({
+ costUsd: false,
inputTokens: false,
outputTokens: false,
});
diff --git a/packages/eve/src/harness/turn-tag-state.ts b/packages/eve/src/harness/turn-tag-state.ts
index 036409068..18f8a75eb 100644
--- a/packages/eve/src/harness/turn-tag-state.ts
+++ b/packages/eve/src/harness/turn-tag-state.ts
@@ -15,29 +15,27 @@
* on a separate "reset" code path. Session totals stay in the same state record
* and keep accumulating until the durable session ends.
*
- * `TokenUsageTotals` carries `costUsd`/`sawCost` alongside the token counts
- * for the `$eve.*` dashboard tags and session limits — fields the
- * cross-cutting {@link TokenUsage} contract (subagent results, callback
- * bodies, usage spans) does not carry. {@link toUsage} projects a total down
- * to that shared shape at the one site (the driver's `done` action) where a
- * session total crosses into it.
+ * `TokenUsageTotals` carries `sawCost` alongside the shared token and token-cost
+ * fields so observability can distinguish an unreported cost from a reported
+ * zero. {@link toUsage} drops that internal marker when a total crosses into
+ * the shared {@link TokenUsage} contract.
*/
import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import {
- findRuntimeTokenLimitViolation,
- grantRuntimeTokenLimits,
- remainingRuntimeTokenQuota,
- resolveRuntimeTokenLimits,
- type SessionRuntimeTokenLimits,
- type SessionTokenLimitViolation,
-} from "#harness/session-token-limits.js";
+ findRuntimeUsageLimitViolation,
+ grantRuntimeUsageLimits,
+ remainingRuntimeUsageQuota,
+ resolveRuntimeUsageLimits,
+ type SessionRuntimeUsageLimits,
+ type SessionUsageLimitViolation,
+} from "#harness/session-usage-limits.js";
import type { TokenUsage } from "#shared/token-usage.js";
-export type { SessionRuntimeTokenLimits, SessionTokenLimitViolation };
+export type { SessionRuntimeUsageLimits, SessionUsageLimitViolation };
const HARNESS_TURN_USAGE_STATE_KEY = "eve.harness.turnUsage";
const REPORTED_SESSION_USAGE_STATE_KEY = "eve.harness.reportedSessionUsage";
-const SESSION_RUNTIME_TOKEN_LIMIT_KEY = "eve.harness.sessionRuntimeTokenLimit";
+const SESSION_RUNTIME_USAGE_LIMIT_KEY = "eve.harness.sessionRuntimeTokenLimit";
export interface TokenUsageTotals {
readonly cacheReadTokens: number;
@@ -85,6 +83,7 @@ export function toUsage(totals: TokenUsageTotals): TokenUsage {
return {
cacheReadTokens: totals.cacheReadTokens,
cacheWriteTokens: totals.cacheWriteTokens,
+ costUsd: totals.sawCost ? totals.costUsd : undefined,
inputTokens: totals.inputTokens,
outputTokens: totals.outputTokens,
};
@@ -95,73 +94,73 @@ export function toUsage(totals: TokenUsageTotals): TokenUsage {
* absent when the configured limit leaves it uncapped. Before any granted
* continuation the runtime limit equals the configured limit; each grant
* re-anchors it to `usage + configured limit` via
- * {@link bumpSessionRuntimeTokenLimits}.
+ * {@link bumpSessionRuntimeUsageLimits}.
*/
-export function getSessionRuntimeTokenLimits(
+export function getSessionRuntimeUsageLimits(
session: Pick<HarnessSession, "limits" | "state">,
-): SessionRuntimeTokenLimits {
- const stored = session.state?.[SESSION_RUNTIME_TOKEN_LIMIT_KEY] as
- | SessionRuntimeTokenLimits
+): SessionRuntimeUsageLimits {
+ const stored = session.state?.[SESSION_RUNTIME_USAGE_LIMIT_KEY] as
+ | SessionRuntimeUsageLimits
| undefined;
- return resolveRuntimeTokenLimits({
- configured: configuredSessionTokenLimits(session),
+ return resolveRuntimeUsageLimits({
+ configured: configuredSessionUsageLimits(session),
stored,
});
}
/**
- * Bumps the runtime token limits after the user grants a continuation:
- * each capped axis is re-anchored to `current usage + configured limit`, so
- * one approval always buys one full configured window from the moment of
- * the grant (even when the last model call overshot by more than a window).
- * Both axes bump together so a session near two limits gets one prompt, not
- * two back-to-back. The configured limits never change.
+ * Bumps the runtime usage limits after the user grants a continuation. Each
+ * capped axis is re-anchored to `current usage + configured limit`, so one
+ * approval buys one full configured window even after an overshoot. All axes
+ * bump together to avoid back-to-back prompts. Configured limits never change.
*/
-export function bumpSessionRuntimeTokenLimits(session: HarnessSession): HarnessSession {
+export function bumpSessionRuntimeUsageLimits(session: HarnessSession): HarnessSession {
const usage = getSessionTokenUsage(session);
- const bumped = grantRuntimeTokenLimits({
- configured: configuredSessionTokenLimits(session),
+ const bumped = grantRuntimeUsageLimits({
+ configured: configuredSessionUsageLimits(session),
usage,
});
return {
...session,
state: {
...session.state,
- [SESSION_RUNTIME_TOKEN_LIMIT_KEY]: bumped satisfies SessionRuntimeTokenLimits,
+ [SESSION_RUNTIME_USAGE_LIMIT_KEY]: bumped satisfies SessionRuntimeUsageLimits,
},
};
}
/**
- * Remaining lifetime-token quota under the runtime limits, per axis.
+ * Remaining lifetime usage quota under the runtime limits, per axis.
* `false` marks an uncapped axis. This is the pool a delegated child's
* budget is granted from.
*/
-export function getSessionRemainingTokenQuota(session: Pick<HarnessSession, "limits" | "state">): {
+export function getSessionRemainingUsageQuota(session: Pick<HarnessSession, "limits" | "state">): {
+ costUsd: number | false;
inputTokens: number | false;
outputTokens: number | false;
} {
const usage = getSessionTokenUsage(session);
- const runtime = getSessionRuntimeTokenLimits(session);
- return remainingRuntimeTokenQuota({ runtime, usage });
+ const runtime = getSessionRuntimeUsageLimits(session);
+ return remainingRuntimeUsageQuota({ runtime, usage });
}
-export function getSessionTokenLimitViolation(
+export function getSessionUsageLimitViolation(
session: Pick<HarnessSession, "limits" | "state">,
-): SessionTokenLimitViolation | null {
+): SessionUsageLimitViolation | null {
const usage = getSessionTokenUsage(session);
- const runtime = getSessionRuntimeTokenLimits(session);
- return findRuntimeTokenLimitViolation({
- configured: configuredSessionTokenLimits(session),
+ const runtime = getSessionRuntimeUsageLimits(session);
+ return findRuntimeUsageLimitViolation({
+ configured: configuredSessionUsageLimits(session),
runtime,
usage,
});
}
-function configuredSessionTokenLimits(
+function configuredSessionUsageLimits(
session: Pick<HarnessSession, "limits">,
-): SessionRuntimeTokenLimits {
+): SessionRuntimeUsageLimits {
return {
+ costUsd: session.limits?.maxTokenCostUsdPerSession,
inputTokens: session.limits?.maxInputTokensPerSession,
outputTokens: session.limits?.maxOutputTokensPerSession,
};
@@ -191,6 +190,7 @@ export function takeSessionUsageDelta(session: HarnessSession): {
delta: {
cacheReadTokens: totals.cacheReadTokens - reported.cacheReadTokens,
cacheWriteTokens: totals.cacheWriteTokens - reported.cacheWriteTokens,
+ costUsd: totals.sawCost || reported.sawCost ? totals.costUsd - reported.costUsd : undefined,
inputTokens: totals.inputTokens - reported.inputTokens,
outputTokens: totals.outputTokens - reported.outputTokens,
},
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 60f9b422b..e4fde1157 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -129,6 +129,11 @@ export interface SessionLimits {
* eve refuses to start another model call.
*/
readonly maxOutputTokensPerSession?: number;
+ /**
+ * Maximum provider-reported model token cost this durable session may spend,
+ * in US dollars, before eve refuses to start another model call.
+ */
+ readonly maxTokenCostUsdPerSession?: number;
}
/**
diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.ts
index f0a8aebdf..7df139524 100644
--- a/packages/eve/src/internal/authored-definition/core.test.ts
+++ b/packages/eve/src/internal/authored-definition/core.test.ts
@@ -109,6 +109,7 @@ describe("normalizeAgentDefinition", () => {
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
sessionTimeoutMs: 86_400_000,
},
},
@@ -118,6 +119,7 @@ describe("normalizeAgentDefinition", () => {
expect(definition.limits).toEqual({
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
sessionTimeoutMs: 86_400_000,
});
});
@@ -129,6 +131,7 @@ describe("normalizeAgentDefinition", () => {
limits: {
maxInputTokensPerSession: false,
maxOutputTokensPerSession: false,
+ maxTokenCostUsdPerSession: false,
sessionTimeoutMs: false,
},
},
@@ -138,6 +141,7 @@ describe("normalizeAgentDefinition", () => {
expect(definition.limits).toEqual({
maxInputTokensPerSession: false,
maxOutputTokensPerSession: false,
+ maxTokenCostUsdPerSession: false,
sessionTimeoutMs: false,
});
});
@@ -175,6 +179,10 @@ describe("normalizeAgentDefinition", () => {
["maxOutputTokensPerSession", 1.5],
["maxOutputTokensPerSession", -1],
["maxOutputTokensPerSession", "20000"],
+ ["maxTokenCostUsdPerSession", 0],
+ ["maxTokenCostUsdPerSession", -0.01],
+ ["maxTokenCostUsdPerSession", Number.POSITIVE_INFINITY],
+ ["maxTokenCostUsdPerSession", "1.50"],
["sessionTimeoutMs", 0],
["sessionTimeoutMs", 1.5],
["sessionTimeoutMs", -1],
diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.ts
index 4dbfda88f..8ff76cf72 100644
--- a/packages/eve/src/internal/authored-definition/core.ts
+++ b/packages/eve/src/internal/authored-definition/core.ts
@@ -172,6 +172,16 @@ function expectPositiveIntegerOrFalse(value: unknown, message: string): number |
return expectPositiveInteger(value, message);
}
+function expectPositiveNumberOrFalse(value: unknown, message: string): number | false {
+ if (value === false) {
+ return false;
+ }
+ if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+ throw new Error(message);
+ }
+ return value;
+}
+
function normalizeAgentLimitsDefinition(
value: unknown,
message: string,
@@ -179,7 +189,12 @@ function normalizeAgentLimitsDefinition(
const record = expectObjectRecord(value, message);
expectOnlyKnownKeys(
record,
- ["maxInputTokensPerSession", "maxOutputTokensPerSession", "sessionTimeoutMs"],
+ [
+ "maxInputTokensPerSession",
+ "maxOutputTokensPerSession",
+ "maxTokenCostUsdPerSession",
+ "sessionTimeoutMs",
+ ],
message,
);
const normalizedDefinition: Mutable<NonNullable<NormalizedAgentDefinition["limits"]>> = {};
@@ -202,6 +217,12 @@ function normalizeAgentLimitsDefinition(
message,
);
}
+ if (record.maxTokenCostUsdPerSession !== undefined) {
+ normalizedDefinition.maxTokenCostUsdPerSession = expectPositiveNumberOrFalse(
+ record.maxTokenCostUsdPerSession,
+ message,
+ );
+ }
return normalizedDefinition;
}
diff --git a/packages/eve/src/internal/testing/app-harness.ts b/packages/eve/src/internal/testing/app-harness.ts
index d265f3ed9..1e0b0495a 100644
--- a/packages/eve/src/internal/testing/app-harness.ts
+++ b/packages/eve/src/internal/testing/app-harness.ts
@@ -42,6 +42,7 @@ export interface TestAppDescriptor {
readonly limits?: {
readonly maxInputTokensPerSession?: number | false;
readonly maxOutputTokensPerSession?: number | false;
+ readonly maxTokenCostUsdPerSession?: number | false;
readonly sessionTimeoutMs?: number | false;
};
readonly model?: string;
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 3347f778d..828025ba1 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -40,6 +40,7 @@ describe("definition helper exact inputs", () => {
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
+ maxTokenCostUsdPerSession: 1.5,
sessionTimeoutMs: 86_400_000,
},
model: "anthropic/claude-sonnet-5",
@@ -53,6 +54,7 @@ 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.maxTokenCostUsdPerSession).toBe(1.5);
expect(agent.limits.sessionTimeoutMs).toBe(86_400_000);
expect(experimental_workflow({ maxSubagents: 6 }).maxSubagents).toBe(6);
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 fba4a0f99..86cfc8a7d 100644
--- a/packages/eve/src/runtime/resolve-agent.ts
+++ b/packages/eve/src/runtime/resolve-agent.ts
@@ -260,6 +260,7 @@ function createResolvedAgentConfig(
config.limits = {
maxInputTokensPerSession: manifest.config.limits.maxInputTokensPerSession,
maxOutputTokensPerSession: manifest.config.limits.maxOutputTokensPerSession,
+ maxTokenCostUsdPerSession: manifest.config.limits.maxTokenCostUsdPerSession,
sessionTimeoutMs: manifest.config.limits.sessionTimeoutMs,
};
}
diff --git a/packages/eve/src/shared/action-types.ts b/packages/eve/src/shared/action-types.ts
index 2b28364f9..86eac57be 100644
--- a/packages/eve/src/shared/action-types.ts
+++ b/packages/eve/src/shared/action-types.ts
@@ -1,8 +1,11 @@
import { z } from "#compiled/zod/index.js";
-import { agentTurnOutcomeSchema } from "#shared/agent-turn-outcome.js";
+import {
+ agentTurnOutcomeSchema,
+ agentTurnOutcomeWithCostSchema,
+} from "#shared/agent-turn-outcome.js";
import { jsonObjectSchema, jsonValueSchema } from "#shared/json-schemas.js";
-import { tokenUsageSchema } from "#shared/token-usage.js";
+import { tokenUsageSchema, tokenUsageWithCostSchema } from "#shared/token-usage.js";
/**
* Eve-owned `tool-call` action requested by the model.
@@ -228,11 +231,37 @@ const runtimeToolResultActionResultSchema = z
* the child settles. Stream consumers use the marker to keep child lifecycle
* open while still recording the receipt as the tool result.
*/
-export type RuntimeSubagentChildResult = z.infer<typeof runtimeSubagentChildResultSchema>;
+export interface RuntimeSubagentChildResult {
+ readonly backgroundTask?: {
+ readonly status: "working";
+ readonly taskId: string;
+ };
+ readonly callId: string;
+ readonly isError?: boolean;
+ readonly kind: "subagent-result";
+ readonly origin: "child";
+ readonly outcome: import("#shared/agent-turn-outcome.js").AgentTurnOutcome;
+ readonly output: import("#shared/json.js").JsonValue;
+ readonly subagentName: string;
+ readonly usage?: import("#shared/token-usage.js").TokenUsage;
+}
-/**
- * Zod schema for one child-produced subagent result.
- */
+const runtimeSubagentChildResultFields = {
+ backgroundTask: z
+ .strictObject({
+ status: z.literal("working"),
+ taskId: z.string(),
+ })
+ .optional(),
+ callId: z.string(),
+ isError: z.boolean().optional(),
+ kind: z.literal("subagent-result"),
+ origin: z.literal("child"),
+ output: jsonValueSchema,
+ subagentName: z.string(),
+};
+
+/** Token-only subagent result schema retained for historical wire formats. */
export const runtimeSubagentChildResultSchema = z
.object({
backgroundTask: z
@@ -252,6 +281,15 @@ export const runtimeSubagentChildResultSchema = z
})
.strict();
+/** Current subagent result schema, including optional model token cost. */
+export const runtimeSubagentChildResultWithCostSchema: z.ZodType<RuntimeSubagentChildResult> = z
+ .object({
+ ...runtimeSubagentChildResultFields,
+ outcome: agentTurnOutcomeWithCostSchema,
+ usage: tokenUsageWithCostSchema.optional(),
+ })
+ .strict();
+
/**
* Subagent failure synthesized on the parent side when no child produced a
* result: dispatch rejections, start failures, and agentId-continuation
diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.ts
index 1ff61d245..c933ed604 100644
--- a/packages/eve/src/shared/agent-definition.ts
+++ b/packages/eve/src/shared/agent-definition.ts
@@ -183,6 +183,19 @@ export interface AgentLimitsDefinition {
* inherit the parent's remaining output quota when the parent has one.
*/
readonly maxOutputTokensPerSession?: number | false;
+ /**
+ * Maximum provider-reported model token cost accumulated by one durable
+ * session, in US dollars.
+ *
+ * eve checks this before starting each model call. The model call that
+ * crosses the limit is allowed to finish because providers report cost only
+ * after the call completes; later model calls in the same session are
+ * blocked.
+ *
+ * `false` disables the limit. Unset by default; delegated subagent sessions
+ * inherit the parent's remaining token-cost quota when the parent has one.
+ */
+ readonly maxTokenCostUsdPerSession?: number | false;
}
/**
diff --git a/packages/eve/src/shared/agent-turn-outcome.ts b/packages/eve/src/shared/agent-turn-outcome.ts
index ff1a5d4cd..b6a15ea5f 100644
--- a/packages/eve/src/shared/agent-turn-outcome.ts
+++ b/packages/eve/src/shared/agent-turn-outcome.ts
@@ -1,7 +1,11 @@
import { z } from "#compiled/zod/index.js";
import type { JsonValue } from "#shared/json.js";
-import { tokenUsageSchema, type TokenUsage } from "#shared/token-usage.js";
+import {
+ tokenUsageSchema,
+ tokenUsageWithCostSchema,
+ type TokenUsage,
+} from "#shared/token-usage.js";
/**
* What one delegated child turn produced, independent of whether the child
@@ -82,3 +86,20 @@ export const agentTurnOutcomeSchema: z.ZodType<AgentTurnOutcome> = z.discriminat
usageDelta: tokenUsageSchema,
}),
]);
+
+/** Current outcome schema, including optional model token cost. */
+export const agentTurnOutcomeWithCostSchema: z.ZodType<AgentTurnOutcome> = z.discriminatedUnion(
+ "kind",
+ [
+ z.strictObject({
+ kind: z.literal("parked"),
+ result: agentTurnResultSchema,
+ usageDelta: tokenUsageWithCostSchema,
+ }),
+ z.strictObject({
+ kind: z.literal("terminal"),
+ result: agentTurnResultSchema,
+ usageDelta: tokenUsageWithCostSchema,
+ }),
+ ],
+);
diff --git a/packages/eve/src/shared/token-usage.ts b/packages/eve/src/shared/token-usage.ts
index b240c081c..fc7402954 100644
--- a/packages/eve/src/shared/token-usage.ts
+++ b/packages/eve/src/shared/token-usage.ts
@@ -1,24 +1,17 @@
import { z } from "#compiled/zod/index.js";
-/**
- * Provider-reported token usage totals.
- *
- * The single usage shape across eve: harness accumulation
- * (`turn-tag-state`), delegated subagent results, remote session
- * callbacks, and usage spans all carry this type.
- */
-export type TokenUsage = z.infer<typeof tokenUsageSchema>;
+/** Provider-reported token usage and optional model token cost totals. */
+export type TokenUsage = z.infer<typeof tokenUsageWithCostSchema>;
-/**
- * Zod schema for {@link TokenUsage}.
- *
- * Validates the `usage` field of remote session callbacks, which may come
- * from a callee on a different eve version — unknown keys are stripped
- * rather than rejected so a newer sender never voids the whole payload.
- */
+/** Token-only schema retained for historical wire formats. */
export const tokenUsageSchema = z.object({
cacheReadTokens: z.number().int().nonnegative(),
cacheWriteTokens: z.number().int().nonnegative(),
inputTokens: z.number().int().nonnegative(),
outputTokens: z.number().int().nonnegative(),
});
+
+/** Current schema for provider-reported token usage and model token cost. */
+export const tokenUsageWithCostSchema = tokenUsageSchema.extend({
+ costUsd: z.number().finite().nonnegative().optional(),
+});
diff --git a/packages/eve/src/subagents/callback-route.ts b/packages/eve/src/subagents/callback-route.ts
index 82b77ba36..a3e9d425c 100644
--- a/packages/eve/src/subagents/callback-route.ts
+++ b/packages/eve/src/subagents/callback-route.ts
@@ -8,11 +8,11 @@ import type {
SubagentInputRequestHookPayload,
} from "#channel/types.js";
import type { RuntimeSubagentChildResult } from "#shared/action-types.js";
-import { agentTurnOutcomeSchema } from "#shared/agent-turn-outcome.js";
+import { agentTurnOutcomeWithCostSchema } from "#shared/agent-turn-outcome.js";
import { jsonValueSchema } from "#shared/json-schemas.js";
import type { JsonValue } from "#shared/json.js";
import { isInputRequest } from "#shared/input.js";
-import { tokenUsageSchema, type TokenUsage } from "#shared/token-usage.js";
+import { tokenUsageWithCostSchema, type TokenUsage } from "#shared/token-usage.js";
import type { TaskInboundUpdate } from "#tasks/types.js";
import { readTaskIdFromInboxToken } from "#tasks/task-inbox-token.js";
@@ -147,7 +147,7 @@ const sessionResultCallbackSchema = z.discriminatedUnion("kind", [
z.object({
callId: z.string().min(1),
kind: z.literal("turn.completed"),
- outcome: agentTurnOutcomeSchema,
+ outcome: agentTurnOutcomeWithCostSchema,
output: jsonValueSchema.optional(),
subagentName: z.string().min(1),
}),
@@ -155,7 +155,7 @@ const sessionResultCallbackSchema = z.discriminatedUnion("kind", [
callId: z.string().min(1),
error: jsonValueSchema,
kind: z.literal("turn.failed"),
- outcome: agentTurnOutcomeSchema,
+ outcome: agentTurnOutcomeWithCostSchema,
subagentName: z.string().min(1),
}),
]);
@@ -413,6 +413,6 @@ function parseCallbackUsage(value: unknown): TokenUsage | undefined {
if (value === undefined) {
return undefined;
}
- const parsed = tokenUsageSchema.safeParse(value);
+ const parsed = tokenUsageWithCostSchema.safeParse(value);
return parsed.success ? parsed.data : undefined;
}
diff --git a/packages/eve/src/subagents/token-budget.test.ts b/packages/eve/src/subagents/token-budget.test.ts
index c0624b294..512d6554e 100644
--- a/packages/eve/src/subagents/token-budget.test.ts
+++ b/packages/eve/src/subagents/token-budget.test.ts
@@ -1,11 +1,12 @@
import { describe, expect, it } from "vitest";
import { resolveRemainingSessionTokenLimits } from "#subagents/token-budget.js";
-import { bumpSessionRuntimeTokenLimits, setTurnUsageState } from "#harness/turn-tag-state.js";
+import { bumpSessionRuntimeUsageLimits, setTurnUsageState } from "#harness/turn-tag-state.js";
import type { HarnessSession, SessionLimits } from "#harness/types.js";
function createSessionWithUsage(input: {
readonly limits?: SessionLimits;
+ readonly usedCostUsd?: number;
readonly usedInputTokens?: number;
readonly usedOutputTokens?: number;
}): HarnessSession {
@@ -22,17 +23,21 @@ function createSessionWithUsage(input: {
base.limits = input.limits;
}
- if (input.usedInputTokens === undefined && input.usedOutputTokens === undefined) {
+ if (
+ input.usedCostUsd === undefined &&
+ input.usedInputTokens === undefined &&
+ input.usedOutputTokens === undefined
+ ) {
return base;
}
const usage = {
cacheReadTokens: 0,
cacheWriteTokens: 0,
- costUsd: 0,
+ costUsd: input.usedCostUsd ?? 0,
inputTokens: input.usedInputTokens ?? 0,
outputTokens: input.usedOutputTokens ?? 0,
- sawCost: false,
+ sawCost: input.usedCostUsd !== undefined,
};
return setTurnUsageState(base, { ...usage, session: usage, turnId: "turn_0" });
}
@@ -75,7 +80,7 @@ describe("resolveRemainingSessionTokenLimits", () => {
usedInputTokens: 1_100_000,
usedOutputTokens: 110_000,
});
- const continued = bumpSessionRuntimeTokenLimits(exhausted);
+ const continued = bumpSessionRuntimeUsageLimits(exhausted);
expect(resolveRemainingSessionTokenLimits(continued)).toEqual({
maxInputTokensPerSession: 1_000_000,
@@ -108,6 +113,20 @@ describe("resolveRemainingSessionTokenLimits", () => {
});
});
+ it("splits the remaining model token-cost budget across delegated calls", () => {
+ const session = createSessionWithUsage({
+ limits: { maxTokenCostUsdPerSession: 1.5 },
+ usedCostUsd: 0.3,
+ });
+
+ const limits = resolveRemainingSessionTokenLimits(session, 3);
+ expect(limits).toMatchObject({
+ maxInputTokensPerSession: false,
+ maxOutputTokensPerSession: false,
+ });
+ expect(limits.maxTokenCostUsdPerSession).toBeCloseTo(0.4);
+ });
+
it("floors uneven splits so a batch can never exceed the remainder", () => {
const session = createSessionWithUsage({
limits: { maxInputTokensPerSession: 100 },
diff --git a/packages/eve/src/subagents/token-budget.ts b/packages/eve/src/subagents/token-budget.ts
index 271a0e133..12783b598 100644
--- a/packages/eve/src/subagents/token-budget.ts
+++ b/packages/eve/src/subagents/token-budget.ts
@@ -1,5 +1,5 @@
import type { RunSessionLimits } from "#channel/types.js";
-import { getSessionRemainingTokenQuota } from "#harness/turn-tag-state.js";
+import { getSessionRemainingUsageQuota } from "#harness/turn-tag-state.js";
import type { HarnessSession } from "#harness/types.js";
/**
@@ -20,17 +20,29 @@ export function resolveRemainingSessionTokenLimits(
fanoutSize = 1,
): RunSessionLimits {
const normalizedFanoutSize = Math.max(1, Math.floor(fanoutSize));
- const remaining = getSessionRemainingTokenQuota(session);
+ const remaining = getSessionRemainingUsageQuota(session);
- return {
- maxInputTokensPerSession: grantShare(remaining.inputTokens, normalizedFanoutSize),
- maxOutputTokensPerSession: grantShare(remaining.outputTokens, normalizedFanoutSize),
+ const limits: {
+ maxInputTokensPerSession: number | false;
+ maxOutputTokensPerSession: number | false;
+ maxTokenCostUsdPerSession?: number;
+ } = {
+ maxInputTokensPerSession: grantTokenShare(remaining.inputTokens, normalizedFanoutSize),
+ maxOutputTokensPerSession: grantTokenShare(remaining.outputTokens, normalizedFanoutSize),
};
+ const maxTokenCostUsdPerSession = grantCostShare(remaining.costUsd, normalizedFanoutSize);
+ if (maxTokenCostUsdPerSession !== false) {
+ limits.maxTokenCostUsdPerSession = maxTokenCostUsdPerSession;
+ }
+ return limits;
}
-function grantShare(remaining: number | false, fanOut: number): number | false {
- if (remaining === false) {
- return false;
- }
+function grantTokenShare(remaining: number | false, fanOut: number): number | false {
+ if (remaining === false) return false;
return Math.floor(remaining / fanOut);
}
+
+function grantCostShare(remaining: number | false, fanOut: number): number | false {
+ if (remaining === false) return false;
+ return remaining / fanOut;
+}
diff --git a/packages/eve/src/tasks/types.test.ts b/packages/eve/src/tasks/types.test.ts
index 84dc6638a..a7e118599 100644
--- a/packages/eve/src/tasks/types.test.ts
+++ b/packages/eve/src/tasks/types.test.ts
@@ -24,7 +24,13 @@ describe("task kernel types", () => {
});
it("accepts complete non-negative usage and drops malformed usage", () => {
- const usage = { cacheReadTokens: 1, cacheWriteTokens: 2, inputTokens: 3, outputTokens: 4 };
+ const usage = {
+ cacheReadTokens: 1,
+ cacheWriteTokens: 2,
+ costUsd: 0.25,
+ inputTokens: 3,
+ outputTokens: 4,
+ };
expect(readTaskUsage(usage)).toEqual(usage);
expect(readTaskUsage({ ...usage, inputTokens: -1 })).toBeUndefined();
expect(readTaskUsage({ inputTokens: 1 })).toBeUndefined();
diff --git a/packages/eve/src/tasks/types.ts b/packages/eve/src/tasks/types.ts
index 025b4e394..33b609c7d 100644
--- a/packages/eve/src/tasks/types.ts
+++ b/packages/eve/src/tasks/types.ts
@@ -30,6 +30,7 @@ export type TaskInputRequest = JsonValue;
export interface TaskUsage {
readonly cacheReadTokens: number;
readonly cacheWriteTokens: number;
+ readonly costUsd?: number;
readonly inputTokens: number;
readonly outputTokens: number;
}
@@ -39,6 +40,7 @@ export function readTaskUsage(value: unknown): TaskUsage | undefined {
if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
const cacheReadTokens = readUsageAxis(value, "cacheReadTokens");
const cacheWriteTokens = readUsageAxis(value, "cacheWriteTokens");
+ const costUsd = readUsageAxis(value, "costUsd");
const inputTokens = readUsageAxis(value, "inputTokens");
const outputTokens = readUsageAxis(value, "outputTokens");
if (
@@ -49,7 +51,15 @@ export function readTaskUsage(value: unknown): TaskUsage | undefined {
) {
return undefined;
}
- return { cacheReadTokens, cacheWriteTokens, inputTokens, outputTokens };
+ const usage: {
+ cacheReadTokens: number;
+ cacheWriteTokens: number;
+ costUsd?: number;
+ inputTokens: number;
+ outputTokens: number;
+ } = { cacheReadTokens, cacheWriteTokens, inputTokens, outputTokens };
+ if (costUsd !== undefined) usage.costUsd = costUsd;
+ return usage;
}
function readUsageAxis(value: object, key: string): number | undefined {
diff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
index 2aef2b0b2..1ba272ae5 100644
--- a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
+++ b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
@@ -249,7 +249,7 @@ describe("mounted extension installed under node_modules", () => {
);
expect(
JSON.parse(extensionFiles[`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`]!),
- ).toMatchObject({ requires: { channel: 14, schedule: 7, subagent: 7 } });
+ ).toMatchObject({ requires: { channel: 15, schedule: 8, subagent: 8 } });
const app = await scenarioApp({
name: "mounted-extension-installed",
installDependencies: true,
diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjs
index d931678d3..884d71c8d 100644
--- a/scripts/guard-invariants.mjs
+++ b/scripts/guard-invariants.mjs
@@ -635,6 +635,7 @@ const WORKFLOW_DECODER_RUNTIME_IMPORTS = new Set([
"#execution/wire/session-inbox-wire.v2.migration.js",
"#execution/wire/session-inbox-wire.v3.migration.js",
"#execution/wire/session-inbox-wire.v4.migration.js",
+ "#execution/wire/session-inbox-wire.v5.migration.js",
"#shared/guards.js",
]);