bopodev-agent-sdk 0.1.14 → 0.1.15

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
 
-> bopodev-agent-sdk@0.1.14 build /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
+> bopodev-agent-sdk@0.1.15 build /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopodev/packages/agent-sdk
 > tsc -p tsconfig.json --emitDeclarationOnly
 

package/dist/adapters/claude-code/src/server/parse.d.ts

@@ -1,2 +1,13 @@
-export { parseClaudeStreamOutput as parseClaudeOutput } from "../../../../agent-sdk/src/runtime-parsers";
+import type { AdapterRuntimeUsageResolution } from "../../../../agent-sdk/src/adapters";
 export { isClaudeRunIncomplete, isUnknownSessionError as isClaudeUnknownSessionError } from "../../../../agent-sdk/src/adapters";
+export declare function resolveClaudeRuntimeUsage(input: {
+    stdout: string;
+    stderr: string;
+    parsedUsage?: {
+        tokenInput?: number;
+        tokenOutput?: number;
+        usdCost?: number;
+        summary?: string;
+    };
+    structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution;

package/dist/adapters/codex/src/server/parse.d.ts

@@ -1,2 +1,13 @@
-export { parseStructuredUsage as parseCodexOutput } from "../../../../agent-sdk/src/runtime-parsers";
+import type { AdapterRuntimeUsageResolution } from "../../../../agent-sdk/src/adapters";
 export { isUnknownSessionError as isCodexUnknownSessionError } from "../../../../agent-sdk/src/adapters";
+export declare function resolveCodexRuntimeUsage(input: {
+    stdout: string;
+    stderr: string;
+    parsedUsage?: {
+        tokenInput?: number;
+        tokenOutput?: number;
+        usdCost?: number;
+        summary?: string;
+    };
+    structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution;

package/dist/adapters/cursor/src/server/parse.d.ts

@@ -1,2 +1,13 @@
-export { parseCursorStreamOutput as parseCursorOutput } from "../../../../agent-sdk/src/runtime-parsers";
+import type { AdapterRuntimeUsageResolution } from "../../../../agent-sdk/src/adapters";
 export { isUnknownSessionError as isCursorUnknownSessionError, readRuntimeSessionId } from "../../../../agent-sdk/src/adapters";
+export declare function resolveCursorRuntimeUsage(input: {
+    stdout: string;
+    stderr: string;
+    parsedUsage?: {
+        tokenInput?: number;
+        tokenOutput?: number;
+        usdCost?: number;
+        summary?: string;
+    };
+    structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution;

package/dist/adapters/gemini-cli/src/server/parse.d.ts

@@ -1 +1,13 @@
+import type { AdapterRuntimeUsageResolution } from "../../../../agent-sdk/src/adapters";
 export { parseGeminiOutput, isGeminiUnknownSessionError } from "../../../../agent-sdk/src/adapters";
+export declare function resolveGeminiRuntimeUsage(input: {
+    stdout: string;
+    stderr: string;
+    parsedUsage?: {
+        tokenInput?: number;
+        tokenOutput?: number;
+        usdCost?: number;
+        summary?: string;
+    };
+    structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution;

package/dist/agent-sdk/src/adapters.d.ts

@@ -1,5 +1,25 @@
-import type { AdapterEnvironmentCheck, AdapterEnvironmentResult, AdapterExecutionResult, AdapterMetadata, AdapterModelOption, AgentAdapter, AgentProviderType, AgentRuntimeConfig, HeartbeatContext } from "./types";
+import type { AdapterEnvironmentCheck, AdapterEnvironmentResult, AdapterExecutionResult, AdapterMetadata, AdapterModelOption, AdapterNormalizedUsage, AgentAdapter, AgentProviderType, AgentRuntimeConfig, HeartbeatContext } from "./types";
 import { type DirectApiProvider } from "./runtime-http";
+type RuntimeParsedUsage = {
+    tokenInput?: number;
+    tokenOutput?: number;
+    usdCost?: number;
+    summary?: string;
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+};
+export type AdapterRuntimeUsageResolution = {
+    parsedUsage?: RuntimeParsedUsage;
+    structuredOutputSource?: "stdout" | "stderr";
+};
+export type AdapterRuntimeUsageResolver = (runtime: {
+    stdout: string;
+    stderr: string;
+    parsedUsage?: RuntimeParsedUsage;
+    structuredOutputSource?: "stdout" | "stderr";
+}) => AdapterRuntimeUsageResolution;
 export declare class ClaudeCodeAdapter implements AgentAdapter {
     providerType: "claude_code";
     execute(context: HeartbeatContext): Promise<AdapterExecutionResult>;
@@ -47,17 +67,18 @@ export declare function testDirectApiEnvironment(providerType: DirectApiProvider
 export declare function runProviderWork(context: HeartbeatContext, provider: "claude_code" | "codex", pricing: {
     inputRate: number;
     outputRate: number;
+}, options?: {
+    usageResolver?: AdapterRuntimeUsageResolver;
+}): Promise<AdapterExecutionResult>;
+export declare function runCursorWork(context: HeartbeatContext, options?: {
+    usageResolver?: AdapterRuntimeUsageResolver;
 }): Promise<AdapterExecutionResult>;
-export declare function runCursorWork(context: HeartbeatContext): Promise<AdapterExecutionResult>;
 export declare function runOpenCodeWork(context: HeartbeatContext): Promise<AdapterExecutionResult>;
-export declare function runGeminiCliWork(context: HeartbeatContext): Promise<AdapterExecutionResult>;
+export declare function runGeminiCliWork(context: HeartbeatContext, options?: {
+    usageResolver?: AdapterRuntimeUsageResolver;
+}): Promise<AdapterExecutionResult>;
 export declare function resolveFailedUsage(runtime: {
-    parsedUsage?: {
-        tokenInput?: number;
-        tokenOutput?: number;
-        usdCost?: number;
-        summary?: string;
-    };
+    parsedUsage?: RuntimeParsedUsage;
     failureType?: "timeout" | "spawn_error" | "nonzero_exit";
     stdout: string;
     stderr: string;
@@ -65,11 +86,13 @@ export declare function resolveFailedUsage(runtime: {
     tokenInput: number;
     tokenOutput: number;
     usdCost: number;
+    usage: AdapterNormalizedUsage | undefined;
     source: "structured";
 } | {
     tokenInput: number;
     tokenOutput: number;
     usdCost: number;
+    usage: AdapterNormalizedUsage;
     source: "none";
 };
 export declare function toProviderResult(context: HeartbeatContext, provider: AgentProviderType, prompt: string, runtime: {
@@ -90,12 +113,7 @@ export declare function toProviderResult(context: HeartbeatContext, provider: Ag
         spawnErrorCode?: string;
         forcedKill: boolean;
     }>;
-    parsedUsage?: {
-        tokenInput?: number;
-        tokenOutput?: number;
-        usdCost?: number;
-        summary?: string;
-    };
+    parsedUsage?: RuntimeParsedUsage;
     structuredOutputSource?: "stdout" | "stderr";
     structuredOutputDiagnostics?: {
         stdoutJsonObjectCount: number;

package/dist/agent-sdk/src/runtime-parsers.d.ts

@@ -1 +1 @@
-export { parseClaudeStreamOutput, parseCursorStreamOutput, parseRuntimeTranscript, parseStructuredUsage } from "./runtime";
+export { parseClaudeStreamOutput, parseCursorStreamOutput, parseGeminiStreamOutput, parseRuntimeTranscript, parseStructuredUsage } from "./runtime";

package/dist/agent-sdk/src/runtime.d.ts

@@ -97,13 +97,9 @@ export declare function containsRateLimitFailure(text: string): boolean;
 export declare function checkRuntimeCommandHealth(command: string, options?: {
     cwd?: string;
     timeoutMs?: number;
+    env?: Record<string, string>;
 }): Promise<RuntimeCommandHealth>;
-export declare function parseStructuredUsage(stdout: string): {
-    tokenInput: number | undefined;
-    tokenOutput: number | undefined;
-    usdCost: number | undefined;
-    summary: string | undefined;
-} | undefined;
+export declare function parseStructuredUsage(stdout: string): ParsedUsageRecord | undefined;
 export declare function parseClaudeStreamOutput(stdout: string): {
     usage: {
         summary: string | undefined;

package/dist/agent-sdk/src/types.d.ts

@@ -58,12 +58,29 @@ export interface HeartbeatContext {
     memoryContext?: AgentMemoryContext;
     runtime?: AgentRuntimeConfig;
 }
+/**
+ * Normalized usage contract produced by adapter execution.
+ *
+ * Invariants:
+ * - `inputTokens` excludes cache reads.
+ * - `cachedInputTokens` tracks cache-hit prompt tokens only.
+ * - persisted `tokenInput` = `inputTokens + cachedInputTokens` for backwards compatibility.
+ * - `outputTokens` reflects generated/completion tokens.
+ */
+export interface AdapterNormalizedUsage {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    costUsd?: number;
+    summary?: string;
+}
 export interface AdapterExecutionResult {
     status: "ok" | "skipped" | "failed";
     summary: string;
     tokenInput: number;
     tokenOutput: number;
     usdCost: number;
+    usage?: AdapterNormalizedUsage;
     pricingProviderType?: string | null;
     pricingModelId?: string | null;
     outcome?: ExecutionOutcome;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "bopodev-agent-sdk",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "dependencies": {
-    "bopodev-contracts": "0.1.14"
+    "bopodev-contracts": "0.1.15"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json --emitDeclarationOnly",

package/src/adapters.ts

@@ -4,6 +4,7 @@ import type {
   AdapterExecutionResult,
   AdapterMetadata,
   AdapterModelOption,
+  AdapterNormalizedUsage,
   AgentAdapter,
   AgentProviderType,
   AgentRuntimeConfig,
@@ -11,6 +12,12 @@ import type {
 } from "./types";
 import { ExecutionOutcomeSchema, type ExecutionOutcome } from "bopodev-contracts";
 import { checkRuntimeCommandHealth, containsRateLimitFailure, executeAgentRuntime, executePromptRuntime } from "./runtime-core";
+import {
+  parseClaudeStreamOutput,
+  parseCursorStreamOutput,
+  parseGeminiStreamOutput,
+  parseStructuredUsage
+} from "./runtime-parsers";
 import {
   executeDirectApiRuntime,
   probeDirectApiEnvironment,
@@ -39,6 +46,195 @@ function isRateLimitedRuntimeFailure(runtime: { stdout: string; stderr: string }
   return containsRateLimitFailure(`${detail ?? ""}\n${runtime.stderr}\n${runtime.stdout}`);
 }
 
+type RuntimeParsedUsage = {
+  tokenInput?: number;
+  tokenOutput?: number;
+  usdCost?: number;
+  summary?: string;
+  inputTokens?: number;
+  cachedInputTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+};
+
+export type AdapterRuntimeUsageResolution = {
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+};
+
+export type AdapterRuntimeUsageResolver = (runtime: {
+  stdout: string;
+  stderr: string;
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+}) => AdapterRuntimeUsageResolution;
+
+function withResolvedRuntimeUsage<
+  T extends {
+    stdout: string;
+    stderr: string;
+    parsedUsage?: RuntimeParsedUsage;
+    structuredOutputSource?: "stdout" | "stderr";
+  }
+>(
+  runtime: T,
+  usageResolver?: AdapterRuntimeUsageResolver
+): Omit<T, "parsedUsage" | "structuredOutputSource"> & {
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+} {
+  if (!usageResolver) {
+    return runtime;
+  }
+  const resolution = usageResolver({
+    stdout: runtime.stdout,
+    stderr: runtime.stderr,
+    parsedUsage: runtime.parsedUsage,
+    structuredOutputSource: runtime.structuredOutputSource
+  });
+  if (!resolution.parsedUsage && !resolution.structuredOutputSource) {
+    return runtime;
+  }
+  return {
+    ...runtime,
+    parsedUsage: resolution.parsedUsage ?? runtime.parsedUsage,
+    structuredOutputSource: resolution.structuredOutputSource ?? runtime.structuredOutputSource
+  };
+}
+
+function toNormalizedUsage(usage: RuntimeParsedUsage | undefined): AdapterNormalizedUsage | undefined {
+  if (!usage) {
+    return undefined;
+  }
+  const inputTokens = usage.inputTokens ?? usage.tokenInput ?? 0;
+  const cachedInputTokens = usage.cachedInputTokens ?? 0;
+  const outputTokens = usage.outputTokens ?? usage.tokenOutput ?? 0;
+  const costUsd = usage.costUsd ?? usage.usdCost;
+  const summary = usage.summary;
+  return {
+    inputTokens: Math.max(0, inputTokens),
+    cachedInputTokens: Math.max(0, cachedInputTokens),
+    outputTokens: Math.max(0, outputTokens),
+    ...(costUsd !== undefined ? { costUsd } : {}),
+    ...(summary ? { summary } : {})
+  };
+}
+
+function usageTokenInputTotal(usage: RuntimeParsedUsage | undefined) {
+  if (!usage) {
+    return 0;
+  }
+  if (usage.inputTokens !== undefined || usage.cachedInputTokens !== undefined) {
+    return Math.max(0, (usage.inputTokens ?? 0) + (usage.cachedInputTokens ?? 0));
+  }
+  return Math.max(0, usage.tokenInput ?? 0);
+}
+
+function hasUsageMetrics(usage: RuntimeParsedUsage | undefined) {
+  if (!usage) {
+    return false;
+  }
+  return usage.tokenInput !== undefined || usage.tokenOutput !== undefined || usage.usdCost !== undefined;
+}
+
+function resolveCodexDefaultRuntimeUsage(input: {
+  stdout: string;
+  stderr: string;
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution {
+  const stdoutUsage = parseStructuredUsage(input.stdout);
+  const stderrUsage = parseStructuredUsage(input.stderr);
+  if (!hasUsageMetrics(stdoutUsage) && hasUsageMetrics(stderrUsage)) {
+    return { parsedUsage: { ...stdoutUsage, ...stderrUsage }, structuredOutputSource: "stderr" };
+  }
+  if (hasUsageMetrics(stdoutUsage)) {
+    return { parsedUsage: stdoutUsage, structuredOutputSource: "stdout" };
+  }
+  if (hasUsageMetrics(stderrUsage)) {
+    return { parsedUsage: stderrUsage, structuredOutputSource: "stderr" };
+  }
+  return {
+    parsedUsage: stdoutUsage ?? stderrUsage ?? input.parsedUsage,
+    structuredOutputSource: input.structuredOutputSource
+  };
+}
+
+function resolveClaudeDefaultRuntimeUsage(input: {
+  stdout: string;
+  stderr: string;
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution {
+  const parsed = parseClaudeStreamOutput(input.stdout);
+  if (parsed?.usage) {
+    return {
+      parsedUsage: {
+        summary: parsed.usage.summary ?? input.parsedUsage?.summary,
+        tokenInput: parsed.usage.tokenInput,
+        tokenOutput: parsed.usage.tokenOutput,
+        usdCost: parsed.usage.usdCost,
+        inputTokens: parsed.usage.tokenInput ?? 0,
+        cachedInputTokens: 0,
+        outputTokens: parsed.usage.tokenOutput ?? 0,
+        costUsd: parsed.usage.usdCost
+      },
+      structuredOutputSource: "stdout"
+    };
+  }
+  return resolveCodexDefaultRuntimeUsage(input);
+}
+
+function resolveCursorDefaultRuntimeUsage(input: {
+  stdout: string;
+  stderr: string;
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution {
+  const parsed = parseCursorStreamOutput(input.stdout);
+  if (parsed?.usage) {
+    return {
+      parsedUsage: {
+        summary: parsed.usage.summary ?? input.parsedUsage?.summary,
+        tokenInput: parsed.usage.tokenInput,
+        tokenOutput: parsed.usage.tokenOutput,
+        usdCost: parsed.usage.usdCost,
+        inputTokens: parsed.usage.tokenInput ?? 0,
+        cachedInputTokens: 0,
+        outputTokens: parsed.usage.tokenOutput ?? 0,
+        costUsd: parsed.usage.usdCost
+      },
+      structuredOutputSource: "stdout"
+    };
+  }
+  return resolveCodexDefaultRuntimeUsage(input);
+}
+
+function resolveGeminiDefaultRuntimeUsage(input: {
+  stdout: string;
+  stderr: string;
+  parsedUsage?: RuntimeParsedUsage;
+  structuredOutputSource?: "stdout" | "stderr";
+}): AdapterRuntimeUsageResolution {
+  const parsed = parseGeminiStreamOutput(input.stdout, input.stderr);
+  if (parsed?.usage) {
+    return {
+      parsedUsage: {
+        summary: parsed.usage.summary ?? input.parsedUsage?.summary,
+        tokenInput: parsed.usage.tokenInput,
+        tokenOutput: parsed.usage.tokenOutput,
+        usdCost: parsed.usage.usdCost,
+        inputTokens: parsed.usage.tokenInput ?? 0,
+        cachedInputTokens: 0,
+        outputTokens: parsed.usage.tokenOutput ?? 0,
+        costUsd: parsed.usage.usdCost
+      },
+      structuredOutputSource: "stdout"
+    };
+  }
+  return resolveCodexDefaultRuntimeUsage(input);
+}
+
 export class ClaudeCodeAdapter implements AgentAdapter {
   providerType = "claude_code" as const;
 
@@ -699,11 +895,27 @@ export async function testDirectApiEnvironment(
 export async function runProviderWork(
   context: HeartbeatContext,
   provider: "claude_code" | "codex",
-  pricing: { inputRate: number; outputRate: number }
+  pricing: { inputRate: number; outputRate: number },
+  options?: { usageResolver?: AdapterRuntimeUsageResolver }
 ): Promise<AdapterExecutionResult> {
+  const usageResolver =
+    options?.usageResolver ?? (provider === "claude_code" ? resolveClaudeDefaultRuntimeUsage : resolveCodexDefaultRuntimeUsage);
   const pricingProviderType = resolveCanonicalPricingProviderKey(provider);
   const prompt = createPrompt(context);
-  const runtime = await executeAgentRuntime(provider, prompt, context.runtime);
+  const hasCodexResume = provider === "codex" && hasCodexResumeArgs(context.runtime?.args ?? []);
+  let runtimeOutput = await executeAgentRuntime(
+    provider,
+    prompt,
+    hasCodexResume ? { ...context.runtime, retryCount: 0 } : context.runtime
+  );
+  if (provider === "codex" && !runtimeOutput.ok && hasCodexResume) {
+    runtimeOutput = await executeAgentRuntime(provider, prompt, {
+      ...context.runtime,
+      retryCount: 0,
+      args: stripCodexResumeArgs(context.runtime?.args ?? [])
+    });
+  }
+  const runtime = withResolvedRuntimeUsage(runtimeOutput, usageResolver);
   const pricingModelId = resolvePricingModelId(context.runtime?.model, runtime);
   if (runtime.ok) {
     if (!runtime.parsedUsage) {
@@ -746,12 +958,14 @@ export async function runProviderWork(
     }
     if (provider === "claude_code" && isClaudeRunIncomplete(runtime)) {
       const detail = "Claude run reached max-turns before completing execution for this issue.";
+      const usage = toNormalizedUsage(runtime.parsedUsage);
       return {
         status: "failed",
         summary: runtime.parsedUsage?.summary ?? `${provider} runtime failed: ${detail}`,
-        tokenInput: runtime.parsedUsage?.tokenInput ?? 0,
-        tokenOutput: runtime.parsedUsage?.tokenOutput ?? 0,
-        usdCost: runtime.parsedUsage?.usdCost ?? 0,
+        tokenInput: usageTokenInputTotal(runtime.parsedUsage),
+        tokenOutput: runtime.parsedUsage?.outputTokens ?? runtime.parsedUsage?.tokenOutput ?? 0,
+        usdCost: runtime.parsedUsage?.costUsd ?? runtime.parsedUsage?.usdCost ?? 0,
+        usage,
         pricingProviderType,
         pricingModelId,
         outcome: toOutcome({
@@ -783,9 +997,10 @@ export async function runProviderWork(
         nextState: context.state
       };
     }
-    const tokenInput = runtime.parsedUsage?.tokenInput ?? 0;
-    const tokenOutput = runtime.parsedUsage?.tokenOutput ?? 0;
-    const usdCost = runtime.parsedUsage?.usdCost ?? 0;
+    const usage = toNormalizedUsage(runtime.parsedUsage);
+    const tokenInput = usageTokenInputTotal(runtime.parsedUsage);
+    const tokenOutput = runtime.parsedUsage?.outputTokens ?? runtime.parsedUsage?.tokenOutput ?? 0;
+    const usdCost = runtime.parsedUsage?.costUsd ?? runtime.parsedUsage?.usdCost ?? 0;
     const summary = runtime.parsedUsage?.summary ?? `${provider} runtime finished in ${runtime.elapsedMs}ms.`;
 
     return {
@@ -794,6 +1009,7 @@ export async function runProviderWork(
       tokenInput,
       tokenOutput,
       usdCost,
+      usage,
       pricingProviderType,
       pricingModelId,
       outcome: toOutcome({
@@ -834,6 +1050,7 @@ export async function runProviderWork(
     tokenInput: failedUsage.tokenInput,
     tokenOutput: failedUsage.tokenOutput,
     usdCost: failedUsage.usdCost,
+    usage: failedUsage.usage,
     pricingProviderType,
     pricingModelId,
     outcome: toOutcome({
@@ -872,7 +1089,11 @@ export async function runProviderWork(
   };
 }
 
-export async function runCursorWork(context: HeartbeatContext): Promise<AdapterExecutionResult> {
+export async function runCursorWork(
+  context: HeartbeatContext,
+  options?: { usageResolver?: AdapterRuntimeUsageResolver }
+): Promise<AdapterExecutionResult> {
+  const usageResolver = options?.usageResolver ?? resolveCursorDefaultRuntimeUsage;
   const prompt = createPrompt(context);
   const cursorLaunch = await resolveCursorLaunchConfig(context.runtime);
   const cwd = context.runtime?.cwd?.trim() || process.cwd();
@@ -892,16 +1113,19 @@ export async function runCursorWork(context: HeartbeatContext): Promise<AdapterE
     }
     return [...baseArgs, ...(context.runtime?.args ?? [])];
   };
-  const runtime = await executePromptRuntime(
-    cursorLaunch.command,
-    prompt,
-    {
-      ...context.runtime,
-      timeoutMs: runtimeTimeoutMs,
-      retryCount: 0,
-      args: buildArgs(resumeState.resumeSessionId)
-    },
-    { provider: "cursor" }
+  const runtime = withResolvedRuntimeUsage(
+    await executePromptRuntime(
+      cursorLaunch.command,
+      prompt,
+      {
+        ...context.runtime,
+        timeoutMs: runtimeTimeoutMs,
+        retryCount: 0,
+        args: buildArgs(resumeState.resumeSessionId)
+      },
+      { provider: "cursor" }
+    ),
+    usageResolver
   );
   const initialSessionId = readRuntimeSessionId(
     runtime,
@@ -913,16 +1137,19 @@ export async function runCursorWork(context: HeartbeatContext): Promise<AdapterE
     !isRateLimitedRuntimeFailure(runtime) &&
     isUnknownSessionError(runtime.stderr, runtime.stdout)
   ) {
-    const retry = await executePromptRuntime(
-      cursorLaunch.command,
-      prompt,
-      {
-        ...context.runtime,
-        timeoutMs: runtimeTimeoutMs,
-        retryCount: 0,
-        args: buildArgs(null)
-      },
-      { provider: "cursor" }
+    const retry = withResolvedRuntimeUsage(
+      await executePromptRuntime(
+        cursorLaunch.command,
+        prompt,
+        {
+          ...context.runtime,
+          timeoutMs: runtimeTimeoutMs,
+          retryCount: 0,
+          args: buildArgs(null)
+        },
+        { provider: "cursor" }
+      ),
+      usageResolver
     );
     return toProviderResult(context, "cursor", prompt, retry, {
       inputRate: 0.0000015,
@@ -1066,7 +1293,11 @@ function resolveGeminiResumeState(state: HeartbeatContext["state"], cwd: string,
   return { resumeSessionId: savedSessionId, resumeAttempted: true, resumeSkippedReason: null };
 }
 
-export async function runGeminiCliWork(context: HeartbeatContext): Promise<AdapterExecutionResult> {
+export async function runGeminiCliWork(
+  context: HeartbeatContext,
+  options?: { usageResolver?: AdapterRuntimeUsageResolver }
+): Promise<AdapterExecutionResult> {
+  const usageResolver = options?.usageResolver ?? resolveGeminiDefaultRuntimeUsage;
   const prompt = createPrompt(context);
   const cwd = context.runtime?.cwd?.trim() || process.cwd();
   const command = context.runtime?.command?.trim() || "gemini";
@@ -1089,16 +1320,19 @@ export async function runGeminiCliWork(context: HeartbeatContext): Promise<Adapt
     return base;
   };
 
-  const runtime = await executePromptRuntime(
-    command,
-    prompt,
-    {
-      ...context.runtime,
-      timeoutMs: runtimeTimeoutMs,
-      retryCount: 0,
-      args: buildArgs(resumeState.resumeSessionId)
-    },
-    { provider: "gemini_cli" }
+  const runtime = withResolvedRuntimeUsage(
+    await executePromptRuntime(
+      command,
+      prompt,
+      {
+        ...context.runtime,
+        timeoutMs: runtimeTimeoutMs,
+        retryCount: 0,
+        args: buildArgs(resumeState.resumeSessionId)
+      },
+      { provider: "gemini_cli" }
+    ),
+    usageResolver
   );
 
   const parsed = parseGeminiOutput(runtime.stdout);
@@ -1109,16 +1343,19 @@ export async function runGeminiCliWork(context: HeartbeatContext): Promise<Adapt
     !isRateLimitedRuntimeFailure(runtime) &&
     isGeminiUnknownSessionError(runtime.stdout, runtime.stderr)
   ) {
-    const retry = await executePromptRuntime(
-      command,
-      prompt,
-      {
-        ...context.runtime,
-        timeoutMs: runtimeTimeoutMs,
-        retryCount: 0,
-        args: buildArgs(null)
-      },
-      { provider: "gemini_cli" }
+    const retry = withResolvedRuntimeUsage(
+      await executePromptRuntime(
+        command,
+        prompt,
+        {
+          ...context.runtime,
+          timeoutMs: runtimeTimeoutMs,
+          retryCount: 0,
+          args: buildArgs(null)
+        },
+        { provider: "gemini_cli" }
+      ),
+      usageResolver
     );
     const retryParsed = parseGeminiOutput(retry.stdout);
     return toProviderResult(context, "gemini_cli", prompt, retry, {
@@ -1147,22 +1384,19 @@ export async function runGeminiCliWork(context: HeartbeatContext): Promise<Adapt
 
 export function resolveFailedUsage(
   runtime: {
-    parsedUsage?: {
-      tokenInput?: number;
-      tokenOutput?: number;
-      usdCost?: number;
-      summary?: string;
-    };
+    parsedUsage?: RuntimeParsedUsage;
     failureType?: "timeout" | "spawn_error" | "nonzero_exit";
     stdout: string;
     stderr: string;
   }
 ) {
   if (runtime.parsedUsage) {
+    const usage = toNormalizedUsage(runtime.parsedUsage);
     return {
-      tokenInput: runtime.parsedUsage.tokenInput ?? 0,
-      tokenOutput: runtime.parsedUsage.tokenOutput ?? 0,
-      usdCost: runtime.parsedUsage.usdCost ?? 0,
+      tokenInput: usageTokenInputTotal(runtime.parsedUsage),
+      tokenOutput: runtime.parsedUsage.outputTokens ?? runtime.parsedUsage.tokenOutput ?? 0,
+      usdCost: runtime.parsedUsage.costUsd ?? runtime.parsedUsage.usdCost ?? 0,
+      usage,
       source: "structured" as const
     };
   }
@@ -1171,6 +1405,11 @@ export function resolveFailedUsage(
       tokenInput: 0,
       tokenOutput: 0,
       usdCost: 0,
+      usage: {
+        inputTokens: 0,
+        cachedInputTokens: 0,
+        outputTokens: 0
+      } as AdapterNormalizedUsage,
       source: "none" as const
     };
   }
@@ -1178,6 +1417,11 @@ export function resolveFailedUsage(
     tokenInput: 0,
     tokenOutput: 0,
     usdCost: 0,
+    usage: {
+      inputTokens: 0,
+      cachedInputTokens: 0,
+      outputTokens: 0
+    } as AdapterNormalizedUsage,
     source: "none" as const
   };
 }
@@ -1204,12 +1448,7 @@ export function toProviderResult(
       spawnErrorCode?: string;
       forcedKill: boolean;
     }>;
-    parsedUsage?: {
-      tokenInput?: number;
-      tokenOutput?: number;
-      usdCost?: number;
-      summary?: string;
-    };
+    parsedUsage?: RuntimeParsedUsage;
     structuredOutputSource?: "stdout" | "stderr";
     structuredOutputDiagnostics?: {
       stdoutJsonObjectCount: number;
@@ -1301,16 +1540,17 @@ export function toProviderResult(
         nextState: applyProviderSessionState(context, provider, sessionUpdate)
       };
     }
-    const tokenInput = runtime.parsedUsage?.tokenInput ?? 0;
-    const tokenOutput = runtime.parsedUsage?.tokenOutput ?? 0;
-    const usdCost = runtime.parsedUsage?.usdCost ?? 0;
+    const tokenOutput = runtime.parsedUsage?.outputTokens ?? runtime.parsedUsage?.tokenOutput ?? 0;
+    const usdCost = runtime.parsedUsage?.costUsd ?? runtime.parsedUsage?.usdCost ?? 0;
+    const usage = toNormalizedUsage(runtime.parsedUsage);
     const summary = runtime.parsedUsage?.summary ?? `${provider} runtime finished in ${runtime.elapsedMs}ms.`;
     return {
       status: "ok",
       summary,
-      tokenInput,
+      tokenInput: usageTokenInputTotal(runtime.parsedUsage),
       tokenOutput,
       usdCost,
+      usage,
       pricingProviderType,
       pricingModelId,
       outcome: toOutcome({
@@ -1352,6 +1592,7 @@ export function toProviderResult(
     tokenInput: failedUsage.tokenInput,
     tokenOutput: failedUsage.tokenOutput,
     usdCost: failedUsage.usdCost,
+    usage: failedUsage.usage,
     pricingProviderType,
     pricingModelId,
     outcome: toOutcome({
@@ -1537,6 +1778,40 @@ export function isUnknownSessionError(stderr: string, stdout: string) {
   );
 }
 
+function hasCodexResumeArgs(args: string[]) {
+  for (let index = 0; index < args.length; index += 1) {
+    const current = (args[index] ?? "").trim().toLowerCase();
+    if (current === "--resume" || current.startsWith("--resume=")) {
+      return true;
+    }
+    if (current === "resume") {
+      return true;
+    }
+  }
+  return false;
+}
+
+function stripCodexResumeArgs(args: string[]) {
+  const next: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const current = (args[index] ?? "").trim();
+    const lowered = current.toLowerCase();
+    if (lowered === "--resume") {
+      index += 1;
+      continue;
+    }
+    if (lowered.startsWith("--resume=")) {
+      continue;
+    }
+    if (lowered === "resume") {
+      index += 1;
+      continue;
+    }
+    next.push(args[index] ?? "");
+  }
+  return next;
+}
+
 export function hasTrustFlag(args: string[]) {
   return args.includes("--trust") || args.includes("--yolo") || args.includes("-f");
 }
@@ -1970,13 +2245,18 @@ export function createPrompt(context: HeartbeatContext) {
   const controlPlaneApiBaseUrl =
     context.runtime?.env?.BOPODEV_API_BASE_URL?.trim() || context.runtime?.env?.BOPODEV_API_URL?.trim() || "";
   const hasControlPlaneHeaders = Boolean(context.runtime?.env?.BOPODEV_REQUEST_HEADERS_JSON?.trim());
+  const safeControlPlaneCurl =
+    'curl -sS -H "x-company-id: $BOPODEV_COMPANY_ID" -H "x-actor-type: $BOPODEV_ACTOR_TYPE" -H "x-actor-id: $BOPODEV_ACTOR_ID" -H "x-actor-companies: $BOPODEV_ACTOR_COMPANIES" -H "x-actor-permissions: $BOPODEV_ACTOR_PERMISSIONS" "$BOPODEV_API_BASE_URL/agents"';
   const controlPlaneDirectives = [
     "Control-plane API directives:",
     controlPlaneApiBaseUrl
       ? `- Use BOPODEV_API_BASE_URL (or BOPODEV_API_URL) for API calls. Current value: ${controlPlaneApiBaseUrl}`
       : "- BOPODEV_API_BASE_URL is missing. Report this as blocker instead of guessing URLs.",
     "- Never guess fallback URLs such as localhost:3000.",
-    "- Include actor headers via BOPODEV_REQUEST_HEADERS_JSON for curl requests.",
+    "- For curl requests, pass control-plane headers directly from env vars (`BOPODEV_COMPANY_ID`, `BOPODEV_ACTOR_TYPE`, `BOPODEV_ACTOR_ID`, `BOPODEV_ACTOR_COMPANIES`, `BOPODEV_ACTOR_PERMISSIONS`).",
+    "- Use BOPODEV_REQUEST_HEADERS_JSON only as a compatibility fallback when direct vars are unavailable.",
+    `- Safe example command (copy and edit path only): ${safeControlPlaneCurl}`,
+    "- Avoid building curl headers by parsing JSON in shell unless direct header env vars are unavailable.",
     hasControlPlaneHeaders
       ? "- BOPODEV_REQUEST_HEADERS_JSON is present in env."
       : "- BOPODEV_REQUEST_HEADERS_JSON is missing. Report this as blocker."

package/src/registry.ts

@@ -1,4 +1,3 @@
-import { listAdapterModels, testAdapterEnvironment } from "./adapters";
 import type {
   AdapterEnvironmentResult,
   AdapterMetadata,
@@ -85,7 +84,7 @@ export async function getAdapterModels(
   if (fromModule) {
     return fromModule;
   }
-  return adapterModules[providerType].models ? [...adapterModules[providerType].models] : listAdapterModels(providerType, runtime);
+  return adapterModules[providerType].models ? [...adapterModules[providerType].models] : [];
 }
 
 export function getAdapterMetadata(): AdapterMetadata[] {
@@ -100,5 +99,10 @@ export async function runAdapterEnvironmentTest(
   if (testEnvironment) {
     return testEnvironment(runtime);
   }
-  return testAdapterEnvironment(providerType, runtime);
+  return {
+    providerType,
+    status: "warn",
+    testedAt: new Date().toISOString(),
+    checks: [{ code: "test_environment_unavailable", level: "warn", message: "Adapter does not expose testEnvironment." }]
+  };
 }

package/src/runtime-http.ts

@@ -378,7 +378,7 @@ function isRetryableFailure(
   failureType: NonNullable<DirectApiExecutionOutput["failureType"]>,
   statusCode: number
 ) {
-  if (failureType === "timeout" || failureType === "network") {
+  if (failureType === "timeout" || failureType === "network" || failureType === "rate_limit") {
     return true;
   }
   if (failureType === "http_error" && statusCode >= 500) {

package/src/runtime-parsers.ts

@@ -1,6 +1,7 @@
 export {
   parseClaudeStreamOutput,
   parseCursorStreamOutput,
+  parseGeminiStreamOutput,
   parseRuntimeTranscript,
   parseStructuredUsage
 } from "./runtime";

package/src/runtime.ts

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { access, cp, lstat, mkdir, mkdtemp, readdir, rm, symlink } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AgentRuntimeConfig } from "./types";
 
@@ -27,6 +27,11 @@ type ParsedUsageRecord = {
   summary?: string;
 };
 
+type UsageSourceResolution = {
+  usage?: ParsedUsageRecord;
+  source?: "stdout" | "stderr";
+};
+
 type CursorParsedStream = {
   usage: ParsedUsageRecord;
   sessionId?: string;
@@ -142,6 +147,10 @@ function providerConfigArgs(provider: "claude_code" | "codex", config?: AgentRun
     if (config?.model?.trim()) {
       args.push("--model", config.model.trim());
     }
+    if (!hasCliFlag(config?.args ?? [], "--json")) {
+      // Codex JSON events carry usage metrics we need for reliable cost accounting.
+      args.push("--json");
+    }
     if (config?.thinkingEffort && config.thinkingEffort !== "auto") {
       args.push("--reasoning-effort", config.thinkingEffort);
     }
@@ -199,7 +208,11 @@ export async function executeAgentRuntime(
   prompt: string,
   config?: AgentRuntimeConfig
 ): Promise<RuntimeExecutionOutput> {
-  const command = resolveProviderCommand(provider, config?.command);
+  const mergedEnv = {
+    ...process.env,
+    ...(config?.env ?? {})
+  };
+  const command = await resolveProviderCommand(provider, config?.command, mergedEnv);
   const commandOverride = Boolean(config?.command && config.command.trim().length > 0);
   const effectiveRetryCount = config?.retryCount ?? (provider === "codex" ? 1 : 0);
   const candidateArgs = [
@@ -364,8 +377,9 @@ export async function executePromptRuntime(
         const claudeStream = provider === "claude_code" ? parseClaudeStreamOutput(stdout) : undefined;
         const cursorStream = provider === "cursor" ? parseCursorStreamOutput(stdout) : undefined;
         const geminiStream = provider === "gemini_cli" ? parseGeminiStreamOutput(stdout, stderr) : undefined;
-        const stdoutUsage = cursorStream?.usage ?? claudeStream?.usage ?? geminiStream?.usage ?? parseStructuredUsage(stdout);
+        const stdoutUsage = parseStructuredUsage(stdout);
         const stderrUsage = parseStructuredUsage(stderr);
+        const usageResolution = resolveUsageSource(stdoutUsage, stderrUsage);
         return {
           ok: true,
           code: attemptResult.code,
@@ -375,8 +389,8 @@ export async function executePromptRuntime(
           elapsedMs: attempts.reduce((sum, item) => sum + item.elapsedMs, 0),
           attemptCount: attempts.length,
           attempts,
-          parsedUsage: stdoutUsage ?? stderrUsage,
-          structuredOutputSource: stdoutUsage ? "stdout" : stderrUsage ? "stderr" : undefined,
+          parsedUsage: usageResolution.usage,
+          structuredOutputSource: usageResolution.source,
           structuredOutputDiagnostics: {
             stdoutJsonObjectCount: extractJsonObjectBlocks(stdout).length,
             stderrJsonObjectCount: extractJsonObjectBlocks(stderr).length,
@@ -422,8 +436,9 @@ export async function executePromptRuntime(
     const claudeStream = provider === "claude_code" ? parseClaudeStreamOutput(stdout) : undefined;
     const cursorStream = provider === "cursor" ? parseCursorStreamOutput(stdout) : undefined;
     const geminiStream = provider === "gemini_cli" ? parseGeminiStreamOutput(stdout, stderr) : undefined;
-    const stdoutUsage = cursorStream?.usage ?? claudeStream?.usage ?? geminiStream?.usage ?? parseStructuredUsage(stdout);
+    const stdoutUsage = parseStructuredUsage(stdout);
     const stderrUsage = parseStructuredUsage(stderr);
+    const usageResolution = resolveUsageSource(stdoutUsage, stderrUsage);
     return {
       ok: false,
       code: lastResult?.code ?? null,
@@ -434,8 +449,8 @@ export async function executePromptRuntime(
       attemptCount: attempts.length,
       attempts,
       failureType: classifyFailure(lastResult?.timedOut ?? false, lastResult?.spawnErrorCode, lastResult?.code ?? null),
-      parsedUsage: stdoutUsage ?? stderrUsage,
-      structuredOutputSource: stdoutUsage ? "stdout" : stderrUsage ? "stderr" : undefined,
+      parsedUsage: usageResolution.usage,
+      structuredOutputSource: usageResolution.source,
       structuredOutputDiagnostics: {
         stdoutJsonObjectCount: extractJsonObjectBlocks(stdout).length,
         stderrJsonObjectCount: extractJsonObjectBlocks(stderr).length,
@@ -536,14 +551,62 @@ function inspectClaudeOutputContract(command: string, args: string[], commandOve
   };
 }
 
-function resolveProviderCommand(provider: "claude_code" | "codex", configuredCommand: string | undefined) {
+function isBareCommandToken(command: string) {
+  return command.length > 0 && !command.includes("/") && !command.includes("\\");
+}
+
+function splitPathEntries(pathValue: string | undefined) {
+  return (pathValue ?? "")
+    .split(delimiter)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+}
+
+async function pathExists(path: string) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveClaudeBinaryCommand(env: NodeJS.ProcessEnv) {
+  const binaryName = process.platform === "win32" ? "claude.exe" : "claude";
+  const candidates = new Set<string>();
+  for (const entry of splitPathEntries(env.PATH)) {
+    candidates.add(join(entry, binaryName));
+  }
+  const home = (env.HOME ?? "").trim() || homedir();
+  if (home) {
+    candidates.add(join(home, ".local", "bin", binaryName));
+  }
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  return "claude";
+}
+
+async function resolveProviderCommand(
+  provider: "claude_code" | "codex",
+  configuredCommand: string | undefined,
+  env: NodeJS.ProcessEnv
+) {
   const trimmed = configuredCommand?.trim();
   if (!trimmed) {
+    if (provider === "claude_code") {
+      return resolveClaudeBinaryCommand(env);
+    }
     return pickDefaultCommand(provider);
   }
   // Normalize accidental provider id aliases used as command strings.
   if (provider === "claude_code" && trimmed === "claude_code") {
-    return "claude";
+    return resolveClaudeBinaryCommand(env);
+  }
+  if (provider === "claude_code" && isBareCommandToken(trimmed) && trimmed.toLowerCase() === "claude") {
+    return resolveClaudeBinaryCommand(env);
   }
   return trimmed;
 }
@@ -1259,13 +1322,22 @@ export function containsRateLimitFailure(text: string) {
 
 export async function checkRuntimeCommandHealth(
   command: string,
-  options?: { cwd?: string; timeoutMs?: number }
+  options?: { cwd?: string; timeoutMs?: number; env?: Record<string, string> }
 ): Promise<RuntimeCommandHealth> {
   const startedAt = Date.now();
+  const mergedEnv: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...(options?.env ?? {})
+  };
+  const trimmedCommand = command.trim();
+  const normalizedCommand =
+    trimmedCommand === "claude_code" || trimmedCommand.toLowerCase() === "claude" || trimmedCommand.toLowerCase() === "claude.exe"
+      ? await resolveClaudeBinaryCommand(mergedEnv)
+      : command;
   return new Promise((resolve) => {
-    const child = spawn(command, ["--version"], {
+    const child = spawn(normalizedCommand, ["--version"], {
       cwd: options?.cwd ?? process.cwd(),
-      env: process.env,
+      env: mergedEnv,
       shell: false
     });
 
@@ -1277,7 +1349,7 @@ export async function checkRuntimeCommandHealth(
       resolved = true;
       child.kill("SIGTERM");
       resolve({
-        command,
+        command: normalizedCommand,
         available: false,
         exitCode: null,
         elapsedMs: Date.now() - startedAt,
@@ -1292,7 +1364,7 @@ export async function checkRuntimeCommandHealth(
       resolved = true;
       clearTimeout(timeout);
       resolve({
-        command,
+        command: normalizedCommand,
         available: true,
         exitCode: code,
         elapsedMs: Date.now() - startedAt
@@ -1306,7 +1378,7 @@ export async function checkRuntimeCommandHealth(
       resolved = true;
       clearTimeout(timeout);
       resolve({
-        command,
+        command: normalizedCommand,
         available: false,
         exitCode: null,
         elapsedMs: Date.now() - startedAt,
@@ -3149,10 +3221,13 @@ function tryParseUsage(candidate: string) {
   try {
     const parsed = JSON.parse(candidate) as Record<string, unknown>;
     const direct = toUsageRecord(parsed);
+    const nested = findNestedUsage(parsed);
+    if (direct && nested) {
+      return mergeUsageRecords(direct, nested);
+    }
     if (direct) {
       return direct;
     }
-    const nested = findNestedUsage(parsed);
     if (nested) {
       return nested;
     }
@@ -3163,22 +3238,119 @@ function tryParseUsage(candidate: string) {
 }
 
 function toUsageRecord(parsed: Record<string, unknown>) {
-    const tokenInput = toNumber(parsed.tokenInput);
-    const tokenOutput = toNumber(parsed.tokenOutput);
-    const usdCost = toNumber(parsed.usdCost);
-    const summary = typeof parsed.summary === "string" ? parsed.summary : undefined;
-    if (isPromptTemplateUsage(summary, tokenInput, tokenOutput, usdCost)) {
+    const directInputTokens =
+      toNumber(parsed.tokenInput) ??
+      toNumber(parsed.input_tokens) ??
+      toNumber(parsed.inputTokens) ??
+      toNumber(parsed.prompt_tokens) ??
+      toNumber(parsed.promptTokens) ??
+      toNumber(parsed.promptTokenCount);
+    const cachedInputTokens =
+      toNumber(parsed.cached_input_tokens) ??
+      toNumber(parsed.cachedInputTokens) ??
+      toNumber(parsed.cache_read_input_tokens) ??
+      toNumber(parsed.cacheReadInputTokens) ??
+      toNumber(parsed.cache_read_tokens) ??
+      toNumber(parsed.cacheReadTokens) ??
+      toNumber(parsed.cachedContentTokenCount);
+    const tokenInput =
+      directInputTokens !== undefined || cachedInputTokens !== undefined
+        ? (directInputTokens ?? 0) + (cachedInputTokens ?? 0)
+        : undefined;
+    const tokenOutput =
+      toNumber(parsed.tokenOutput) ??
+      toNumber(parsed.output_tokens) ??
+      toNumber(parsed.outputTokens) ??
+      toNumber(parsed.completion_tokens) ??
+      toNumber(parsed.completionTokens) ??
+      toNumber(parsed.candidatesTokenCount) ??
+      toNumber(parsed.generated_tokens) ??
+      toNumber(parsed.generatedTokens);
+    const estimatedOutputFromTotals =
+      tokenOutput === undefined &&
+      tokenInput !== undefined &&
+      (toNumber(parsed.total_tokens) ?? toNumber(parsed.totalTokens) ?? toNumber(parsed.totalTokenCount)) !== undefined
+        ? Math.max(
+            0,
+            (toNumber(parsed.total_tokens) ?? toNumber(parsed.totalTokens) ?? toNumber(parsed.totalTokenCount) ?? 0) -
+              tokenInput
+          )
+        : undefined;
+    const resolvedTokenOutput = tokenOutput ?? estimatedOutputFromTotals;
+    const usdCost = toNumber(parsed.usdCost) ?? toNumber(parsed.total_cost_usd) ?? toNumber(parsed.cost_usd) ?? toNumber(parsed.cost);
+    const summary =
+      (typeof parsed.summary === "string" ? parsed.summary : undefined) ??
+      (typeof parsed.result === "string" ? parsed.result : undefined) ??
+      (typeof parsed.message === "string" ? parsed.message : undefined);
+    if (isPromptTemplateUsage(summary, tokenInput, resolvedTokenOutput, usdCost)) {
       return undefined;
     }
     if (
       tokenInput === undefined &&
-      tokenOutput === undefined &&
+      resolvedTokenOutput === undefined &&
       usdCost === undefined &&
       !summary
     ) {
       return undefined;
     }
-    return { tokenInput, tokenOutput, usdCost, summary };
+    return { tokenInput, tokenOutput: resolvedTokenOutput, usdCost, summary };
+}
+
+function hasUsageMetrics(usage: ParsedUsageRecord | undefined) {
+  if (!usage) {
+    return false;
+  }
+  return usage.tokenInput !== undefined || usage.tokenOutput !== undefined || usage.usdCost !== undefined;
+}
+
+function mergeUsageRecords(primary: ParsedUsageRecord, secondary: ParsedUsageRecord): ParsedUsageRecord {
+  return {
+    summary: primary.summary ?? secondary.summary,
+    tokenInput: primary.tokenInput ?? secondary.tokenInput,
+    tokenOutput: primary.tokenOutput ?? secondary.tokenOutput,
+    usdCost: primary.usdCost ?? secondary.usdCost
+  };
+}
+
+function resolveUsageSource(
+  stdoutUsage: ParsedUsageRecord | undefined,
+  stderrUsage: ParsedUsageRecord | undefined
+): UsageSourceResolution {
+  if (!stdoutUsage && !stderrUsage) {
+    return {};
+  }
+  if (stdoutUsage && !stderrUsage) {
+    return { usage: stdoutUsage, source: "stdout" };
+  }
+  if (!stdoutUsage && stderrUsage) {
+    return { usage: stderrUsage, source: "stderr" };
+  }
+  const stdoutRecord = stdoutUsage as ParsedUsageRecord;
+  const stderrRecord = stderrUsage as ParsedUsageRecord;
+  const stdoutHasMetrics = hasUsageMetrics(stdoutUsage);
+  const stderrHasMetrics = hasUsageMetrics(stderrUsage);
+  if (!stdoutHasMetrics && stderrHasMetrics) {
+    return {
+      usage: mergeUsageRecords(stderrRecord, stdoutRecord),
+      source: "stderr"
+    };
+  }
+  if (stdoutHasMetrics && !stderrHasMetrics) {
+    return {
+      usage: mergeUsageRecords(stdoutRecord, stderrRecord),
+      source: "stdout"
+    };
+  }
+  if (stdoutHasMetrics && stderrHasMetrics) {
+    return {
+      usage: mergeUsageRecords(stdoutRecord, stderrRecord),
+      source: "stdout"
+    };
+  }
+  return {
+    usage: mergeUsageRecords(stdoutRecord, stderrRecord),
+    source: "stdout"
+  };
 }
 
 function findNestedUsage(parsed: Record<string, unknown>) {
@@ -3266,15 +3438,15 @@ function tailLine(value: string) {
 function classifyStructuredOutputLikelyCause(
   stdout: string,
   stderr: string,
-  stdoutUsage: { summary?: string } | undefined,
-  stderrUsage: { summary?: string } | undefined
+  stdoutUsage: ParsedUsageRecord | undefined,
+  stderrUsage: ParsedUsageRecord | undefined
 ) {
   const hasStdout = stdout.trim().length > 0;
   const hasStderr = stderr.trim().length > 0;
   if (!hasStdout && !hasStderr) {
     return "no_output_from_runtime" as const;
   }
-  if (!stdoutUsage && stderrUsage) {
+  if (!hasUsageMetrics(stdoutUsage) && hasUsageMetrics(stderrUsage)) {
     return "json_on_stderr_only" as const;
   }
   const jsonLike = /[\{\}\[\]\"]/m.test(stdout) || /[\{\}\[\]\"]/m.test(stderr);

package/src/types.ts

@@ -64,12 +64,30 @@ export interface HeartbeatContext {
   runtime?: AgentRuntimeConfig;
 }
 
+/**
+ * Normalized usage contract produced by adapter execution.
+ *
+ * Invariants:
+ * - `inputTokens` excludes cache reads.
+ * - `cachedInputTokens` tracks cache-hit prompt tokens only.
+ * - persisted `tokenInput` = `inputTokens + cachedInputTokens` for backwards compatibility.
+ * - `outputTokens` reflects generated/completion tokens.
+ */
+export interface AdapterNormalizedUsage {
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+  costUsd?: number;
+  summary?: string;
+}
+
 export interface AdapterExecutionResult {
   status: "ok" | "skipped" | "failed";
   summary: string;
   tokenInput: number;
   tokenOutput: number;
   usdCost: number;
+  usage?: AdapterNormalizedUsage;
   pricingProviderType?: string | null;
   pricingModelId?: string | null;
   outcome?: ExecutionOutcome;

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> bopodev-agent-sdk@0.1.12 typecheck /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
-> tsc -p tsconfig.json --noEmit
-