Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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">): To
return 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.ts
index 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 = z
kind: 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.ts
index 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.ts
index 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.js
import 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.ts
new file mode 100644
index 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(),
+});