The Open Framework for Building Agents
feat(eve): surface subagent usage to callers (#488)
Rui99c238083486
diff --git a/.changeset/local-subagent-usage-results.md b/.changeset/local-subagent-usage-results.mdnew file mode 100644index 000000000..00dc3dd30--- /dev/null+++ b/.changeset/local-subagent-usage-results.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Subagents now report their token usage back to the caller — local, runtime, and remote alike. A completed turn carries the session's token totals (`inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`) on its terminal result; remote agents transport the same totals over the session callback. The parent's turn emits one `invoke_agent` span per usage-bearing result (`gen_ai.operation.name=invoke_agent`, `gen_ai.agent.name`, `gen_ai.usage.*`, per the OpenTelemetry GenAI semantic conventions) in the caller's trace. Remote usage requires both sides to run this version; collection stays best-effort everywhere.diff --git a/packages/eve/src/execution/delegated-parent-notification.test.ts b/packages/eve/src/execution/delegated-parent-notification.test.tsnew file mode 100644index 000000000..c4969edf5--- /dev/null+++ b/packages/eve/src/execution/delegated-parent-notification.test.ts@@ -0,0 +1,116 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++import { ContextContainer } from "#context/container.js";+import { serializeContext } from "#context/serialize.js";+import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";+import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";+import { notifyDelegatedParentStep } from "#execution/delegated-parent-notification.js";+import { SUBAGENT_ADAPTER, SUBAGENT_ADAPTER_KIND } from "#execution/subagent-adapter.js";+import { resumeHook } from "#internal/workflow/runtime.js";+import type { RuntimeSubagentResultActionResult } from "#runtime/actions/types.js";++vi.mock("../runtime/sessions/compiled-agent-cache.js", () => ({+ getCompiledRuntimeAgentBundle: vi.fn(),+}));++vi.mock("#compiled/@workflow/core/runtime.js", () => ({+ resumeHook: vi.fn(),+}));++const resumeHookMock = vi.mocked(resumeHook);++const USAGE = { cacheReadTokens: 10, cacheWriteTokens: 5, inputTokens: 100, outputTokens: 50 };++function createSuccessResult(): RuntimeSubagentResultActionResult {+ return {+ callId: "call-1",+ kind: "subagent-result",+ output: "done",+ subagentName: "research",+ };+}++function createSerializedContext(): Record<string, unknown> {+ const bundle = {+ adapterRegistry: {+ adaptersByKind: new Map([[SUBAGENT_ADAPTER_KIND, SUBAGENT_ADAPTER]]),+ },+ compiledArtifactsSource: { kind: "test" },+ nodeId: undefined,+ } as never;+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);++ const ctx = new ContextContainer();+ ctx.set(BundleKey, bundle);+ ctx.set(ChannelKey, {+ ...SUBAGENT_ADAPTER,+ state: {+ callId: "call-1",+ parentContinuationToken: "parent-tok",+ parentSessionId: "parent-session",+ subagentName: "research",+ },+ });+ return serializeContext(ctx);+}++describe("notifyDelegatedParentStep", () => {+ beforeEach(() => {+ resumeHookMock.mockReset();+ resumeHookMock.mockResolvedValue(undefined as never);+ });++ it("attaches usage to a success result", async () => {+ await notifyDelegatedParentStep({+ result: createSuccessResult(),+ serializedContext: createSerializedContext(),+ usage: USAGE,+ });++ expect(resumeHookMock).toHaveBeenCalledWith("parent-tok", {+ kind: "runtime-action-result",+ results: [+ {+ callId: "call-1",+ kind: "subagent-result",+ output: "done",+ subagentName: "research",+ usage: USAGE,+ },+ ],+ });+ });++ it("omits usage when none is provided", async () => {+ await notifyDelegatedParentStep({+ result: createSuccessResult(),+ serializedContext: createSerializedContext(),+ });++ expect(resumeHookMock).toHaveBeenCalledWith("parent-tok", {+ kind: "runtime-action-result",+ results: [createSuccessResult()],+ });+ });++ it("never attaches usage to error results", async () => {+ const errorResult: RuntimeSubagentResultActionResult = {+ callId: "call-1",+ isError: true,+ kind: "subagent-result",+ output: { code: "SUBAGENT_EXECUTION_FAILED", message: "boom" },+ subagentName: "research",+ };++ await notifyDelegatedParentStep({+ result: errorResult,+ serializedContext: createSerializedContext(),+ usage: USAGE,+ });++ expect(resumeHookMock).toHaveBeenCalledWith("parent-tok", {+ kind: "runtime-action-result",+ results: [errorResult],+ });+ });+});diff --git a/packages/eve/src/execution/delegated-parent-notification.ts b/packages/eve/src/execution/delegated-parent-notification.tsindex 00d7ee63b..7fde04201 100644--- a/packages/eve/src/execution/delegated-parent-notification.ts+++ b/packages/eve/src/execution/delegated-parent-notification.ts@@ -9,15 +9,21 @@ import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";import { deserializeContext } from "#context/serialize.js";import type { RuntimeSubagentResultActionResult } from "#runtime/actions/types.js";import { SUBAGENT_ADAPTER_KIND } from "#execution/subagent-adapter.js";+import type { TokenUsage } from "#shared/token-usage.js";import { resumeHook } from "#internal/workflow/runtime.js";/*** Resumes the parent driver's hook with a delegated subagent result.* No-op for root sessions.+ *+ * `usage` — the completed child's session-total token spend — is+ * attached to success results so the caller can attribute the+ * subagent's tokens. Error results never carry usage.*/export async function notifyDelegatedParentStep(input: {readonly result: RuntimeSubagentResultActionResult | undefined;readonly serializedContext: Record<string, unknown>;+ readonly usage?: TokenUsage;}): Promise<void> {"use step";@@ -37,8 +43,13 @@ export async function notifyDelegatedParentStep(input: {return;}+ const result =+ input.usage === undefined || input.result.isError === true+ ? input.result+ : { ...input.result, usage: input.usage };+await resumeHook(parentContinuationToken, {kind: "runtime-action-result",- results: [input.result],+ results: [result],});}diff --git a/packages/eve/src/execution/next-driver-action.ts b/packages/eve/src/execution/next-driver-action.tsindex e1cc21add..accaa1d04 100644--- a/packages/eve/src/execution/next-driver-action.ts+++ b/packages/eve/src/execution/next-driver-action.ts@@ -12,6 +12,7 @@* strips unknown fields.*/import type { DurableSessionState } from "#execution/durable-session-store.js";+import type { TokenUsage } from "#shared/token-usage.js";/** Discriminated union the driver workflow body dispatches on. */export type NextDriverAction =@@ -21,6 +22,8 @@ export type NextDriverAction =readonly isError?: boolean;readonly sessionState: DurableSessionState;readonly serializedContext: Record<string, unknown>;+ /** Session-total token usage spent by the completed session. */+ readonly usage?: TokenUsage;}| {readonly kind: "park";diff --git a/packages/eve/src/execution/session-callback-step.test.ts b/packages/eve/src/execution/session-callback-step.test.tsindex 923eb6675..7ed5eb7cd 100644--- a/packages/eve/src/execution/session-callback-step.test.ts+++ b/packages/eve/src/execution/session-callback-step.test.ts@@ -2,6 +2,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { fireSessionCallbackStep } from "#execution/session-callback-step.js";+const USAGE = { cacheReadTokens: 10, cacheWriteTokens: 5, inputTokens: 100, outputTokens: 50 };+describe("fireSessionCallbackStep", () => {let errorSpy: ReturnType<typeof vi.spyOn>;@@ -92,6 +94,64 @@ describe("fireSessionCallbackStep", () => {});});+ it("includes usage on the completed callback when provided", async () => {+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 202 }));+ vi.stubGlobal("fetch", fetchMock);++ await fireSessionCallbackStep({+ output: "done",+ serializedContext: createSerializedContext(),+ status: "completed",+ usage: USAGE,+ });++ expect(fetchMock).toHaveBeenCalledWith("https://caller.example.com/eve/v1/callback/tok123", {+ body: JSON.stringify({+ callId: "call-1",+ kind: "session.completed",+ output: "done",+ sessionId: "remote-session",+ subagentName: "research",+ usage: USAGE,+ }),+ headers: {+ "content-type": "application/json",+ },+ method: "POST",+ redirect: "error",+ signal: expect.any(AbortSignal),+ });+ expect(errorSpy).not.toHaveBeenCalled();+ });++ it("omits usage when none is provided", async () => {+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 202 }));+ vi.stubGlobal("fetch", fetchMock);++ await fireSessionCallbackStep({+ output: "done",+ serializedContext: createSerializedContext(),+ status: "completed",+ });++ expect(parsePostedBody(fetchMock).usage).toBeUndefined();+ expect(errorSpy).not.toHaveBeenCalled();+ });++ it("never includes usage on failed callbacks", async () => {+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 202 }));+ vi.stubGlobal("fetch", fetchMock);++ await fireSessionCallbackStep({+ error: new Error("remote exploded"),+ serializedContext: createSerializedContext(),+ status: "failed",+ usage: USAGE,+ });++ expect(parsePostedBody(fetchMock).usage).toBeUndefined();+ });+it("posts the failed callback with the normalized error message", async () => {const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 202 }));vi.stubGlobal("fetch", fetchMock);@@ -238,6 +298,14 @@ describe("fireSessionCallbackStep", () => {});});+function parsePostedBody(fetchMock: ReturnType<typeof vi.fn>): { usage?: unknown } {+ const call = fetchMock.mock.calls[0];+ if (call === undefined) {+ throw new Error("expected fetch to have been called");+ }+ return JSON.parse((call[1] as { body: string }).body) as { usage?: unknown };+}+function createSerializedContext(): Record<string, unknown> {return {"eve.sessionCallback": {diff --git a/packages/eve/src/execution/session-callback-step.ts b/packages/eve/src/execution/session-callback-step.tsindex 6b8496171..f74b72245 100644--- a/packages/eve/src/execution/session-callback-step.ts+++ b/packages/eve/src/execution/session-callback-step.ts@@ -3,6 +3,7 @@ import { parseSessionCallback } from "#channel/session-callback.js";import { SessionCallbackKey } from "#context/keys.js";import { createLogger } from "#internal/logging.js";import { toErrorMessage } from "#shared/errors.js";+import type { TokenUsage } from "#shared/token-usage.js";const SESSION_CALLBACK_TIMEOUT_MS = 30_000;const log = createLogger("execution.session-callback");@@ -16,12 +17,17 @@ const log = createLogger("execution.session-callback");* intentional: this function runs as a durable Workflow step, so rejection* hands retry/failure policy back to the Workflow orchestrator rather than* letting eve falsely mark the callback delivery as complete.+ *+ * `usage` — the session's token totals — rides along on completed+ * callbacks so the caller can attribute this agent's spend. Failed+ * callbacks never carry usage.*/export async function fireSessionCallbackStep(input: {readonly error?: unknown;readonly output?: unknown;readonly serializedContext: Record<string, unknown>;readonly status: "completed" | "failed";+ readonly usage?: TokenUsage;}): Promise<void> {"use step";@@ -35,13 +41,12 @@ export async function fireSessionCallbackStep(input: {const callback = parseSerializedSessionCallback(value);const body =input.status === "completed"- ? {- callId: callback.callId,- kind: "session.completed" as const,- output: input.output ?? "",+ ? buildCompletedCallbackBody({+ callback,+ output: input.output,sessionId,- subagentName: callback.subagentName,- }+ usage: input.usage,+ }): {callId: callback.callId,error: {@@ -78,6 +83,22 @@ export async function fireSessionCallbackStep(input: {}}+function buildCompletedCallbackBody(input: {+ readonly callback: SessionCallback;+ readonly output: unknown;+ readonly sessionId: string;+ readonly usage: TokenUsage | undefined;+}): Record<string, unknown> {+ const base = {+ callId: input.callback.callId,+ kind: "session.completed" as const,+ output: input.output ?? "",+ sessionId: input.sessionId,+ subagentName: input.callback.subagentName,+ };+ return input.usage === undefined ? base : { ...base, usage: input.usage };+}+function parseSerializedSessionCallback(value: unknown): SessionCallback {const parsed = parseSessionCallback(value);if (!parsed.ok) {diff --git a/packages/eve/src/execution/subagent-usage-span.test.ts b/packages/eve/src/execution/subagent-usage-span.test.tsnew file mode 100644index 000000000..64a42ec85--- /dev/null+++ b/packages/eve/src/execution/subagent-usage-span.test.ts@@ -0,0 +1,88 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++import { recordSubagentUsageSpans } from "#execution/subagent-usage-span.js";+import type { RuntimeActionResult } from "#runtime/actions/types.js";++const startSpanMock = vi.fn();+const endSpanMock = vi.fn();++vi.mock("#compiled/@opentelemetry/api/index.js", async (importOriginal) => {+ const actual = await importOriginal<typeof import("#compiled/@opentelemetry/api/index.js")>();+ return {+ ...actual,+ trace: {+ getTracer: () => ({+ startSpan: (name: string, options: unknown) => {+ startSpanMock(name, options);+ return { end: endSpanMock };+ },+ }),+ },+ };+});++const USAGE = { cacheReadTokens: 10, cacheWriteTokens: 5, inputTokens: 100, outputTokens: 50 };++function subagentResult(+ overrides: Partial<Extract<RuntimeActionResult, { kind: "subagent-result" }>> = {},+): RuntimeActionResult {+ return {+ callId: "call-1",+ kind: "subagent-result",+ output: "done",+ subagentName: "research",+ ...overrides,+ };+}++describe("recordSubagentUsageSpans", () => {+ beforeEach(() => {+ startSpanMock.mockReset();+ endSpanMock.mockReset();+ });++ it("emits one invoke_agent span per successful result with usage", () => {+ recordSubagentUsageSpans([+ subagentResult({ usage: USAGE }),+ subagentResult({ callId: "call-2", subagentName: "writer", usage: USAGE }),+ ]);++ expect(startSpanMock).toHaveBeenCalledTimes(2);+ expect(startSpanMock).toHaveBeenCalledWith("invoke_agent research", {+ attributes: {+ "gen_ai.operation.name": "invoke_agent",+ "gen_ai.agent.name": "research",+ "gen_ai.usage.input_tokens": 100,+ "gen_ai.usage.output_tokens": 50,+ "gen_ai.usage.cache_read.input_tokens": 10,+ "gen_ai.usage.cache_creation.input_tokens": 5,+ },+ });+ expect(endSpanMock).toHaveBeenCalledTimes(2);+ });++ it("skips results without usage, error results, and non-subagent kinds", () => {+ recordSubagentUsageSpans([+ subagentResult(),+ subagentResult({ isError: true, usage: USAGE }),+ {+ callId: "call-3",+ kind: "tool-result",+ output: "ok",+ toolName: "search",+ },+ ]);++ expect(startSpanMock).not.toHaveBeenCalled();+ });++ it("does not throw when the tracer fails", () => {+ startSpanMock.mockImplementation(() => {+ throw new Error("tracer unavailable");+ });++ expect(() => {+ recordSubagentUsageSpans([subagentResult({ usage: USAGE })]);+ }).not.toThrow();+ });+});diff --git a/packages/eve/src/execution/subagent-usage-span.ts b/packages/eve/src/execution/subagent-usage-span.tsnew file mode 100644index 000000000..6cddd60fd--- /dev/null+++ b/packages/eve/src/execution/subagent-usage-span.ts@@ -0,0 +1,40 @@+import { trace } from "#compiled/@opentelemetry/api/index.js";++import { createLogger } from "#internal/logging.js";+import type { RuntimeActionResult } from "#runtime/actions/types.js";++const log = createLogger("execution.subagent-usage-span");++/**+ * Emits one caller-side `invoke_agent` span per successful delegated+ * subagent result that reports token usage, so the parent session's+ * observability can attribute a child agent's tokens. Runs in the+ * parent's turn step, so the span lands in the caller's trace.+ * Best-effort: a tracer failure never blocks the turn.+ */+export function recordSubagentUsageSpans(results: readonly RuntimeActionResult[]): void {+ for (const result of results) {+ if (result.kind !== "subagent-result" || result.isError === true) {+ continue;+ }+ const usage = result.usage;+ if (usage === undefined) {+ continue;+ }+ try {+ const span = trace.getTracer("eve").startSpan(`invoke_agent ${result.subagentName}`, {+ attributes: {+ "gen_ai.operation.name": "invoke_agent",+ "gen_ai.agent.name": result.subagentName,+ "gen_ai.usage.input_tokens": usage.inputTokens,+ "gen_ai.usage.output_tokens": usage.outputTokens,+ "gen_ai.usage.cache_read.input_tokens": usage.cacheReadTokens,+ "gen_ai.usage.cache_creation.input_tokens": usage.cacheWriteTokens,+ },+ });+ span.end();+ } catch (error) {+ log.warn("failed to emit subagent usage span", { error });+ }+ }+}diff --git a/packages/eve/src/execution/turn-execution-cursor.ts b/packages/eve/src/execution/turn-execution-cursor.tsindex 32724c70f..935796e1d 100644--- a/packages/eve/src/execution/turn-execution-cursor.ts+++ b/packages/eve/src/execution/turn-execution-cursor.ts@@ -3,6 +3,7 @@ import type { TurnControlPayload } from "#execution/turn-control-protocol.js";import { sendTurnControlStep } from "#execution/turn-control-protocol.js";import type { DurableSessionState } from "#execution/durable-session-store.js";import type { TurnStepInput } from "#execution/durable-session-migrations/turn-workflow.js";+import type { TokenUsage } from "#shared/token-usage.js";interface TurnTransition {readonly serializedContext?: Record<string, unknown>;@@ -14,6 +15,7 @@ type TurnTerminalAction =readonly isError?: boolean;readonly kind: "done";readonly output: unknown;+ readonly usage?: TokenUsage;}| {readonly authorizationNames?: readonly string[];diff --git a/packages/eve/src/execution/turn-workflow.ts b/packages/eve/src/execution/turn-workflow.tsindex 83e4e2bbd..2072a9b82 100644--- a/packages/eve/src/execution/turn-workflow.ts+++ b/packages/eve/src/execution/turn-workflow.ts@@ -77,7 +77,12 @@ async function runTurnOwnedWorkflow(input: TurnWorkflowInput): Promise<void> {if (result.action === "done") {await cursor.finish(result,- { kind: "done", output: result.output ?? "", isError: result.isError },+ {+ kind: "done",+ output: result.output ?? "",+ isError: result.isError,+ usage: result.usage,+ },bufferedDeliveries,);return;@@ -247,6 +252,7 @@ async function runLegacyTurnWorkflow(input: TurnWorkflowInput): Promise<void> {isError: result.isError,serializedContext: result.serializedContext,sessionState: result.sessionState,+ usage: result.usage,},kind: "turn-result",},diff --git a/packages/eve/src/execution/workflow-entry.ts b/packages/eve/src/execution/workflow-entry.tsindex d69aae0d3..9d2ab9ee9 100644--- a/packages/eve/src/execution/workflow-entry.ts+++ b/packages/eve/src/execution/workflow-entry.ts@@ -299,12 +299,14 @@ async function finalizeDone(input: {output: failed ? undefined : output,serializedContext,status: failed ? "failed" : "completed",+ usage: failed ? undefined : input.action.usage,});await notifyDelegatedParentStep({result: failed? createDelegatedSubagentErrorResult(serializedContext, output): createDelegatedSubagentSuccessResult(serializedContext, output),serializedContext,+ usage: failed ? undefined : input.action.usage,});return { output };}diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.tsindex a2f639c82..c57832e03 100644--- a/packages/eve/src/execution/workflow-steps.test.ts+++ b/packages/eve/src/execution/workflow-steps.test.ts@@ -704,6 +704,72 @@ describe("turnStep", () => {expect(second.serializedContext[ThreadKey.name]).toBe("alpha");});+ it("carries session-total usage on the done result, not the final turn's", async () => {+ // Flat fields are the *final turn's* usage; `session` carries the+ // session-lifetime totals. The done action must report the latter.+ const session = createStubSession({+ state: {+ "eve.harness.turnUsage": {+ turnId: "turn_1",+ inputTokens: 10,+ outputTokens: 5,+ cacheReadTokens: 1,+ cacheWriteTokens: 0,+ session: { inputTokens: 100, outputTokens: 50, cacheReadTokens: 10, cacheWriteTokens: 5 },+ },+ },+ });+ installSessionStoreMocks([session]);++ const compiledBundle = {+ adapterRegistry: {+ adaptersByKind: new Map([[threadContextAdapter.kind, threadContextAdapter]]),+ },+ compiledArtifactsSource: {} as never,+ graph: {+ nodesByNodeId: new Map(),+ root: {+ sandboxRegistry: { sandbox: null },+ turnAgent: TestTurnAgent,+ },+ },+ moduleMap: { nodes: {} },+ hookRegistry: createEmptyHookRegistry(),+ resolvedAgent: { config: {} },+ subagentRegistry: {},+ toolRegistry: {},+ turnAgent: TestTurnAgent,+ } as never;+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(compiledBundle);++ vi.mocked(createExecutionNodeStep).mockImplementation(() => {+ return async (stepSession): Promise<StepResult> => ({+ next: { done: true, output: "final" },+ session: stepSession,+ });+ });++ const result = await turnStep({+ input: {+ kind: "deliver",+ payloads: [{ message: "finish up" }],+ },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result.action).toBe("done");+ if (result.action === "done") {+ expect(result.usage).toEqual({+ cacheReadTokens: 10,+ cacheWriteTokens: 5,+ inputTokens: 100,+ outputTokens: 50,+ });+ }+ });+it("refreshes the system prompt from the current bundled deployment", async () => {const session = createStubSession({agent: {diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.tsindex 10e96a2f7..1a8c82f7d 100644--- a/packages/eve/src/execution/workflow-steps.ts+++ b/packages/eve/src/execution/workflow-steps.ts@@ -25,6 +25,8 @@ import {import { getPendingWorkflowInterrupt } from "#harness/workflow-interrupt-state.js";import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";+import { getTurnUsageState, toUsage } from "#harness/turn-tag-state.js";+import type { TokenUsage } from "#shared/token-usage.js";import type { JsonObject } from "#shared/json.js";import type { RunMode } from "#shared/run-mode.js";import { getRuntimeActionRequestKey } from "#runtime/actions/keys.js";@@ -58,6 +60,7 @@ import {} from "#execution/durable-session-migrations/turn-workflow.js";import { createExecutionNodeStep } from "#execution/node-step.js";import { emitProxiedInputRequest, routeDeliverPayload } from "#execution/subagent-hitl-proxy.js";+import { recordSubagentUsageSpans } from "#execution/subagent-usage-span.js";import { hydrateDurableSession, refreshSessionFromTurnAgent } from "#execution/session.js";import { buildTurnAttributes, readRootSessionId } from "#execution/eve-workflow-attributes.js";import { normalizeEveAttributes } from "#runtime/attributes/normalize.js";@@ -83,6 +86,8 @@ export type DurableStepResult =readonly isError?: boolean;readonly serializedContext: Record<string, unknown>;readonly sessionState: DurableSessionState;+ /** Session-total token usage; set on `done` when the session spent any. */+ readonly usage?: TokenUsage;}| {readonly action: "park";@@ -210,6 +215,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu}resolved = results.length === 0 ? undefined : results.reduce(coalesceTurnInputs);} else if (input.input?.kind === "runtime-action-result") {+ recordSubagentUsageSpans(input.input.results);resolved = { runtimeActionResults: input.input.results };}@@ -349,12 +355,14 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu"done" in stepResult.next) {await writer.close();+ const sessionTotals = getTurnUsageState(stepResult.session.state)?.session;return {action: "done",output: stepResult.next.output,isError: stepResult.next.isError,serializedContext: nextSerializedContext,sessionState: nextState,+ usage: sessionTotals === undefined ? undefined : toUsage(sessionTotals),};}diff --git a/packages/eve/src/harness/turn-tag-state.ts b/packages/eve/src/harness/turn-tag-state.tsindex 580c23d75..c9a143c8f 100644--- a/packages/eve/src/harness/turn-tag-state.ts+++ b/packages/eve/src/harness/turn-tag-state.ts@@ -14,8 +14,16 @@* `turnId` keys the turn totals so a fresh turn starts at zero without relying* on a separate "reset" code path. Session totals stay in the same state record* and keep accumulating until the durable session ends.+ *+ * `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.*/import type { HarnessSession, SessionStateMap } from "#harness/types.js";+import type { TokenUsage } from "#shared/token-usage.js";const HARNESS_TURN_USAGE_STATE_KEY = "eve.harness.turnUsage";@@ -72,6 +80,16 @@ export function getSessionTokenUsage(session: Pick<HarnessSession, "state">): Toreturn getTurnUsageState(session.state)?.session ?? ZERO_TOKEN_USAGE;}+/** Projects a {@link TokenUsageTotals} down to the cross-cutting {@link TokenUsage} shape. */+export function toUsage(totals: TokenUsageTotals): TokenUsage {+ return {+ cacheReadTokens: totals.cacheReadTokens,+ cacheWriteTokens: totals.cacheWriteTokens,+ inputTokens: totals.inputTokens,+ outputTokens: totals.outputTokens,+ };+}+export function getSessionTokenLimitViolation(session: Pick<HarnessSession, "limits" | "state">,): SessionTokenLimitViolation | null {diff --git a/packages/eve/src/runtime/actions/types.ts b/packages/eve/src/runtime/actions/types.tsindex 8d30ac9dd..0e17dd66c 100644--- a/packages/eve/src/runtime/actions/types.ts+++ b/packages/eve/src/runtime/actions/types.ts@@ -1,6 +1,7 @@import { z } from "#compiled/zod/index.js";import { jsonObjectSchema, jsonValueSchema } from "#shared/json-schemas.js";+import { tokenUsageSchema } from "#shared/token-usage.js";/*** Eve-owned `tool-call` action requested by the model.@@ -126,6 +127,9 @@ const runtimeToolResultActionResultSchema = z/*** Runtime-owned subagent result projected back into a harness resume call.+ *+ * `usage` carries the completed child session's token totals so the+ * caller can attribute the subagent's spend.*/export type RuntimeSubagentResultActionResult = z.infer<typeof runtimeSubagentResultActionResultSchema@@ -141,6 +145,7 @@ const runtimeSubagentResultActionResultSchema = zkind: z.literal("subagent-result"),output: jsonValueSchema,subagentName: z.string(),+ usage: tokenUsageSchema.optional(),}).strict();diff --git a/packages/eve/src/runtime/session-callback-route.test.ts b/packages/eve/src/runtime/session-callback-route.test.tsindex 3f13b8644..c3a61b270 100644--- a/packages/eve/src/runtime/session-callback-route.test.ts+++ b/packages/eve/src/runtime/session-callback-route.test.ts@@ -66,6 +66,112 @@ describe("session callback route", () => {],});});++ it("projects reported usage onto the resumed result", async () => {+ resumeHookMock.mockResolvedValue(undefined);++ const response = await handleSessionCallbackRequest(+ new Request("https://app.example.com/eve/v1/callback/tok123", {+ body: JSON.stringify({+ callId: "call-1",+ kind: "session.completed",+ output: "done",+ sessionId: "remote-session",+ subagentName: "research",+ usage: { cacheReadTokens: 10, cacheWriteTokens: 5, inputTokens: 100, outputTokens: 50 },+ }),+ method: "POST",+ }),+ createRouteContext({ token: "tok123" }),+ );++ expect(response.status).toBe(202);+ expect(resumeHookMock).toHaveBeenCalledWith("tok123", {+ kind: "runtime-action-result",+ results: [+ {+ callId: "call-1",+ kind: "subagent-result",+ output: "done",+ subagentName: "research",+ usage: { cacheReadTokens: 10, cacheWriteTokens: 5, inputTokens: 100, outputTokens: 50 },+ },+ ],+ });+ });++ it("strips unknown usage keys from a newer callee", async () => {+ resumeHookMock.mockResolvedValue(undefined);++ const response = await handleSessionCallbackRequest(+ new Request("https://app.example.com/eve/v1/callback/tok123", {+ body: JSON.stringify({+ callId: "call-1",+ kind: "session.completed",+ output: "done",+ sessionId: "remote-session",+ subagentName: "research",+ usage: {+ cacheReadTokens: 10,+ cacheWriteTokens: 5,+ inputTokens: 100,+ outputTokens: 50,+ reasoningOutputTokens: 7,+ },+ }),+ method: "POST",+ }),+ createRouteContext({ token: "tok123" }),+ );++ expect(response.status).toBe(202);+ const payload = resumeHookMock.mock.calls[0]?.[1] as {+ results: readonly { usage?: unknown }[];+ };+ expect(payload.results[0]?.usage).toEqual({+ cacheReadTokens: 10,+ cacheWriteTokens: 5,+ inputTokens: 100,+ outputTokens: 50,+ });+ });++ it("drops malformed usage but still resumes the result", async () => {+ resumeHookMock.mockResolvedValue(undefined);++ const response = await handleSessionCallbackRequest(+ new Request("https://app.example.com/eve/v1/callback/tok123", {+ body: JSON.stringify({+ callId: "call-1",+ kind: "session.completed",+ output: "done",+ sessionId: "remote-session",+ subagentName: "research",+ usage: {+ cacheReadTokens: 10,+ cacheWriteTokens: 5,+ inputTokens: "lots",+ outputTokens: 50,+ },+ }),+ method: "POST",+ }),+ createRouteContext({ token: "tok123" }),+ );++ expect(response.status).toBe(202);+ expect(resumeHookMock).toHaveBeenCalledWith("tok123", {+ kind: "runtime-action-result",+ results: [+ {+ callId: "call-1",+ kind: "subagent-result",+ output: "done",+ subagentName: "research",+ },+ ],+ });+ });});function createRouteContext(params: Record<string, string>): RouteContext {diff --git a/packages/eve/src/runtime/session-callback-route.ts b/packages/eve/src/runtime/session-callback-route.tsindex f7bc7fa18..499c88445 100644--- a/packages/eve/src/runtime/session-callback-route.ts+++ b/packages/eve/src/runtime/session-callback-route.ts@@ -4,6 +4,7 @@ import type { ChannelMethod, RouteContext } from "#public/definitions/channel.jsimport type { ResolvedChannelDefinition } from "#runtime/types.js";import type { RuntimeSubagentResultActionResult } from "#runtime/actions/types.js";import type { JsonValue } from "#shared/json.js";+import { tokenUsageSchema, type TokenUsage } from "#shared/token-usage.js";export const HTTP_SESSION_CALLBACK_CHANNEL_NAME_PREFIX = "eve/v1/callback";@@ -16,6 +17,7 @@ type SessionTerminalCallbackPayload =readonly output: string;readonly sessionId: string;readonly subagentName: string;+ readonly usage?: TokenUsage;}| {readonly callId: string;@@ -99,12 +101,14 @@ function projectSessionCallbackResult(}if (payload.kind === "session.completed") {- return {+ const base: RuntimeSubagentResultActionResult = {callId: payload.callId,kind: "subagent-result",output: payload.output ?? "",subagentName: payload.subagentName,};+ const usage = parseCallbackUsage((payload as { usage?: unknown }).usage);+ return usage === undefined ? base : { ...base, usage };}if (payload.kind === "session.failed") {@@ -125,3 +129,16 @@ function projectSessionCallbackResult(return Response.json({ error: "Unsupported callback kind.", ok: false }, { status: 400 });}++/**+ * TokenUsage arrives from a remote callee that may run a different eve version,+ * so it is validated independently and dropped — never rejected — when+ * malformed. The rest of the callback still resumes the parent.+ */+function parseCallbackUsage(value: unknown): TokenUsage | undefined {+ if (value === undefined) {+ return undefined;+ }+ const parsed = tokenUsageSchema.safeParse(value);+ return parsed.success ? parsed.data : undefined;+}diff --git a/packages/eve/src/shared/token-usage.ts b/packages/eve/src/shared/token-usage.tsnew file mode 100644index 000000000..b240c081c--- /dev/null+++ b/packages/eve/src/shared/token-usage.ts@@ -0,0 +1,24 @@+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>;++/**+ * 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.+ */+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(),+});