@nathapp/nax 0.46.0 → 0.46.1

package/src/agents/claude/cost.ts

@@ -1,268 +1,16 @@
 /**
- * Cost Tracking
+ * Cost Tracking — re-exports from the shared src/agents/cost/ module.
  *
- * Token-based cost estimation for AI coding agents.
- * Parses agent output for token usage and calculates costs.
+ * Kept for zero-breakage backward compatibility.
+ * Import directly from src/agents/cost for new code.
  */
 
-import type { ModelTier } from "../../config/schema";
-
-/** Cost rates per 1M tokens (USD) */
-export interface ModelCostRates {
-  inputPer1M: number;
-  outputPer1M: number;
-}
-
-/** Token usage data */
-export interface TokenUsage {
-  inputTokens: number;
-  outputTokens: number;
-}
-
-/** Cost estimate with confidence indicator */
-export interface CostEstimate {
-  cost: number;
-  confidence: "exact" | "estimated" | "fallback";
-}
-
-/** Model tier cost rates (as of 2025-01) */
-export const COST_RATES: Record<ModelTier, ModelCostRates> = {
-  fast: {
-    // Haiku 4.5
-    inputPer1M: 0.8,
-    outputPer1M: 4.0,
-  },
-  balanced: {
-    // Sonnet 4.5
-    inputPer1M: 3.0,
-    outputPer1M: 15.0,
-  },
-  powerful: {
-    // Opus 4
-    inputPer1M: 15.0,
-    outputPer1M: 75.0,
-  },
-};
-
-/**
- * Token usage with confidence indicator.
- */
-export interface TokenUsageWithConfidence {
-  inputTokens: number;
-  outputTokens: number;
-  confidence: "exact" | "estimated";
-}
-
-/**
- * Parse Claude Code output for token usage.
- *
- * Supports multiple formats with varying confidence levels:
- * - JSON structured output → "exact" confidence
- * - Markdown/plain text patterns → "estimated" confidence
- *
- * Uses specific regex patterns to reduce false positives.
- *
- * @param output - Agent stdout + stderr combined
- * @returns Token usage with confidence indicator, or null if tokens cannot be parsed
- *
- * @example
- * ```ts
- * // JSON format (exact)
- * const usage1 = parseTokenUsage('{"usage": {"input_tokens": 1234, "output_tokens": 5678}}');
- * // { inputTokens: 1234, outputTokens: 5678, confidence: 'exact' }
- *
- * // Markdown format (estimated)
- * const usage2 = parseTokenUsage('Input tokens: 1234\nOutput tokens: 5678');
- * // { inputTokens: 1234, outputTokens: 5678, confidence: 'estimated' }
- *
- * // Unparseable
- * const usage3 = parseTokenUsage('No token data here');
- * // null
- * ```
- */
-export function parseTokenUsage(output: string): TokenUsageWithConfidence | null {
-  // Try JSON format first (most reliable) - confidence: exact
-  try {
-    const jsonMatch = output.match(
-      /\{[^}]*"usage"\s*:\s*\{[^}]*"input_tokens"\s*:\s*(\d+)[^}]*"output_tokens"\s*:\s*(\d+)[^}]*\}[^}]*\}/,
-    );
-    if (jsonMatch) {
-      return {
-        inputTokens: Number.parseInt(jsonMatch[1], 10),
-        outputTokens: Number.parseInt(jsonMatch[2], 10),
-        confidence: "exact",
-      };
-    }
-
-    // Try parsing as full JSON object
-    const lines = output.split("\n");
-    for (const line of lines) {
-      if (line.trim().startsWith("{")) {
-        try {
-          const parsed = JSON.parse(line);
-          if (parsed.usage?.input_tokens && parsed.usage?.output_tokens) {
-            return {
-              inputTokens: parsed.usage.input_tokens,
-              outputTokens: parsed.usage.output_tokens,
-              confidence: "exact",
-            };
-          }
-        } catch {
-          // Not valid JSON, continue
-        }
-      }
-    }
-  } catch {
-    // JSON parsing failed, try regex patterns
-  }
-
-  // Try specific markdown-style patterns (more specific to reduce false positives)
-  // Match "Input tokens: 1234" or "input_tokens: 1234" or "INPUT TOKENS: 1234"
-  // Use word boundary at start, require colon or space after keyword, then digits
-  // confidence: estimated (regex-based)
-  const inputMatch = output.match(/\b(?:input|input_tokens)\s*:\s*(\d{2,})|(?:input)\s+(?:tokens?)\s*:\s*(\d{2,})/i);
-  const outputMatch = output.match(
-    /\b(?:output|output_tokens)\s*:\s*(\d{2,})|(?:output)\s+(?:tokens?)\s*:\s*(\d{2,})/i,
-  );
-
-  if (inputMatch && outputMatch) {
-    // Extract token counts (may be in capture group 1 or 2)
-    const inputTokens = Number.parseInt(inputMatch[1] || inputMatch[2], 10);
-    const outputTokens = Number.parseInt(outputMatch[1] || outputMatch[2], 10);
-
-    // Sanity check: reject if tokens seem unreasonably large (> 1M each)
-    if (inputTokens > 1_000_000 || outputTokens > 1_000_000) {
-      return null;
-    }
-
-    return {
-      inputTokens,
-      outputTokens,
-      confidence: "estimated",
-    };
-  }
-
-  return null;
-}
-
-/**
- * Estimate cost in USD based on token usage.
- *
- * Calculates total cost using tier-specific rates per 1M tokens.
- *
- * @param modelTier - Model tier (fast/balanced/powerful)
- * @param inputTokens - Number of input tokens consumed
- * @param outputTokens - Number of output tokens generated
- * @returns Total cost in USD
- *
- * @example
- * ```ts
- * const cost = estimateCost("balanced", 10000, 5000);
- * // Sonnet 4.5: (10000/1M * $3.00) + (5000/1M * $15.00) = $0.105
- * ```
- */
-export function estimateCost(
-  modelTier: ModelTier,
-  inputTokens: number,
-  outputTokens: number,
-  customRates?: ModelCostRates,
-): number {
-  const rates = customRates ?? COST_RATES[modelTier];
-  const inputCost = (inputTokens / 1_000_000) * rates.inputPer1M;
-  const outputCost = (outputTokens / 1_000_000) * rates.outputPer1M;
-  return inputCost + outputCost;
-}
-
-/**
- * Estimate cost from agent output by parsing token usage.
- *
- * Attempts to extract token counts from stdout/stderr, then calculates cost.
- * Returns null if tokens cannot be parsed (caller should use fallback estimation).
- *
- * @param modelTier - Model tier for cost calculation
- * @param output - Agent stdout + stderr combined
- * @returns Cost estimate with confidence indicator, or null if unparseable
- *
- * @example
- * ```ts
- * const estimate = estimateCostFromOutput("balanced", agentOutput);
- * if (estimate) {
- *   console.log(`Cost: $${estimate.cost.toFixed(4)} (${estimate.confidence})`);
- * } else {
- *   // Fall back to duration-based estimation
- * }
- * ```
- */
-export function estimateCostFromOutput(modelTier: ModelTier, output: string): CostEstimate | null {
-  const usage = parseTokenUsage(output);
-  if (!usage) {
-    return null;
-  }
-  const cost = estimateCost(modelTier, usage.inputTokens, usage.outputTokens);
-  return {
-    cost,
-    confidence: usage.confidence,
-  };
-}
-
-/**
- * Fallback cost estimation based on runtime duration.
- *
- * Used when token usage cannot be parsed from agent output.
- * Provides conservative estimates using per-minute rates.
- *
- * @param modelTier - Model tier for cost calculation
- * @param durationMs - Agent runtime in milliseconds
- * @returns Cost estimate with 'fallback' confidence
- *
- * @example
- * ```ts
- * const estimate = estimateCostByDuration("balanced", 120000); // 2 minutes
- * // { cost: 0.10, confidence: 'fallback' }
- * // Sonnet: 2 min * $0.05/min = $0.10
- * ```
- */
-export function estimateCostByDuration(modelTier: ModelTier, durationMs: number): CostEstimate {
-  const costPerMinute: Record<ModelTier, number> = {
-    fast: 0.01,
-    balanced: 0.05,
-    powerful: 0.15,
-  };
-  const minutes = durationMs / 60000;
-  const cost = minutes * costPerMinute[modelTier];
-  return {
-    cost,
-    confidence: "fallback",
-  };
-}
-
-/**
- * Format cost estimate with confidence indicator for display.
- *
- * @param estimate - Cost estimate with confidence level
- * @returns Formatted cost string with confidence indicator
- *
- * @example
- * ```ts
- * formatCostWithConfidence({ cost: 0.12, confidence: 'exact' });
- * // "$0.12"
- *
- * formatCostWithConfidence({ cost: 0.15, confidence: 'estimated' });
- * // "~$0.15"
- *
- * formatCostWithConfidence({ cost: 0.05, confidence: 'fallback' });
- * // "~$0.05 (duration-based)"
- * ```
- */
-export function formatCostWithConfidence(estimate: CostEstimate): string {
-  const formattedCost = `$${estimate.cost.toFixed(2)}`;
-
-  switch (estimate.confidence) {
-    case "exact":
-      return formattedCost;
-    case "estimated":
-      return `~${formattedCost}`;
-    case "fallback":
-      return `~${formattedCost} (duration-based)`;
-  }
-}
+export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence } from "../cost";
+export {
+  COST_RATES,
+  parseTokenUsage,
+  estimateCost,
+  estimateCostFromOutput,
+  estimateCostByDuration,
+  formatCostWithConfidence,
+} from "../cost";

package/src/agents/claude/execution.ts

@@ -4,6 +4,8 @@
  * Handles building commands, preparing environment, and process execution.
  */
 
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
 import { resolvePermissions } from "../../config/permissions";
 import type { PidRegistry } from "../../execution/pid-registry";
 import { withProcessTimeout } from "../../execution/timeout-handler";
@@ -65,13 +67,22 @@ export function buildCommand(binary: string, options: AgentRunOptions): string[]
 export function buildAllowedEnv(options: AgentRunOptions): Record<string, string | undefined> {
   const allowed: Record<string, string | undefined> = {};
 
-  const essentialVars = ["PATH", "HOME", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
+  const essentialVars = ["PATH", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
   for (const varName of essentialVars) {
     if (process.env[varName]) {
       allowed[varName] = process.env[varName];
     }
   }
 
+  // Sanitize HOME — must be absolute path. Unexpanded "~" causes literal ~/dir in cwd.
+  const rawHome = process.env.HOME ?? "";
+  const safeHome = rawHome && isAbsolute(rawHome) ? rawHome : homedir();
+  if (rawHome !== safeHome) {
+    const logger = getLogger();
+    logger.warn("env", `HOME env is not absolute ("${rawHome}"), falling back to os.homedir(): ${safeHome}`);
+  }
+  allowed.HOME = safeHome;
+
   const apiKeyVars = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
   for (const varName of apiKeyVars) {
     if (process.env[varName]) {

package/src/agents/cost/calculate.ts

@@ -0,0 +1,154 @@
+/**
+ * Cost calculation functions for all agent adapters.
+ */
+
+import type { ModelTier } from "../../config/schema";
+import { parseTokenUsage } from "./parse";
+import { COST_RATES, MODEL_PRICING } from "./pricing";
+import type { CostEstimate, ModelCostRates, SessionTokenUsage } from "./types";
+
+/**
+ * Estimate cost in USD based on token usage and model tier.
+ *
+ * @param modelTier - Model tier (fast/balanced/powerful)
+ * @param inputTokens - Number of input tokens consumed
+ * @param outputTokens - Number of output tokens generated
+ * @param customRates - Optional custom rates (overrides tier defaults)
+ * @returns Total cost in USD
+ *
+ * @example
+ * ```ts
+ * const cost = estimateCost("balanced", 10000, 5000);
+ * // Sonnet 4.5: (10000/1M * $3.00) + (5000/1M * $15.00) = $0.105
+ * ```
+ */
+export function estimateCost(
+  modelTier: ModelTier,
+  inputTokens: number,
+  outputTokens: number,
+  customRates?: ModelCostRates,
+): number {
+  const rates = customRates ?? COST_RATES[modelTier];
+  const inputCost = (inputTokens / 1_000_000) * rates.inputPer1M;
+  const outputCost = (outputTokens / 1_000_000) * rates.outputPer1M;
+  return inputCost + outputCost;
+}
+
+/**
+ * Estimate cost from agent output by parsing token usage.
+ *
+ * Attempts to extract token counts from stdout/stderr, then calculates cost.
+ * Returns null if tokens cannot be parsed.
+ *
+ * @param modelTier - Model tier for cost calculation
+ * @param output - Agent stdout + stderr combined
+ * @returns Cost estimate with confidence indicator, or null if unparseable
+ */
+export function estimateCostFromOutput(modelTier: ModelTier, output: string): CostEstimate | null {
+  const usage = parseTokenUsage(output);
+  if (!usage) {
+    return null;
+  }
+  const cost = estimateCost(modelTier, usage.inputTokens, usage.outputTokens);
+  return {
+    cost,
+    confidence: usage.confidence,
+  };
+}
+
+/**
+ * Fallback cost estimation based on runtime duration.
+ *
+ * Used when token usage cannot be parsed from agent output.
+ * Provides conservative estimates using per-minute rates.
+ *
+ * @param modelTier - Model tier for cost calculation
+ * @param durationMs - Agent runtime in milliseconds
+ * @returns Cost estimate with 'fallback' confidence
+ *
+ * @example
+ * ```ts
+ * const estimate = estimateCostByDuration("balanced", 120000); // 2 minutes
+ * // { cost: 0.10, confidence: 'fallback' }
+ * // Sonnet: 2 min * $0.05/min = $0.10
+ * ```
+ */
+export function estimateCostByDuration(modelTier: ModelTier, durationMs: number): CostEstimate {
+  const costPerMinute: Record<ModelTier, number> = {
+    fast: 0.01,
+    balanced: 0.05,
+    powerful: 0.15,
+  };
+  const minutes = durationMs / 60000;
+  const cost = minutes * costPerMinute[modelTier];
+  return {
+    cost,
+    confidence: "fallback",
+  };
+}
+
+/**
+ * Format cost estimate with confidence indicator for display.
+ *
+ * @param estimate - Cost estimate with confidence level
+ * @returns Formatted cost string with confidence indicator
+ *
+ * @example
+ * ```ts
+ * formatCostWithConfidence({ cost: 0.12, confidence: 'exact' });
+ * // "$0.12"
+ *
+ * formatCostWithConfidence({ cost: 0.15, confidence: 'estimated' });
+ * // "~$0.15"
+ *
+ * formatCostWithConfidence({ cost: 0.05, confidence: 'fallback' });
+ * // "~$0.05 (duration-based)"
+ * ```
+ */
+export function formatCostWithConfidence(estimate: CostEstimate): string {
+  const formattedCost = `$${estimate.cost.toFixed(2)}`;
+
+  switch (estimate.confidence) {
+    case "exact":
+      return formattedCost;
+    case "estimated":
+      return `~${formattedCost}`;
+    case "fallback":
+      return `~${formattedCost} (duration-based)`;
+  }
+}
+
+/**
+ * Calculate USD cost from ACP session token counts using per-model pricing.
+ *
+ * @param usage - Token counts from cumulative_token_usage
+ * @param model - Model identifier (e.g., 'claude-sonnet-4', 'claude-haiku-4-5')
+ * @returns Estimated cost in USD
+ */
+export function estimateCostFromTokenUsage(usage: SessionTokenUsage, model: string): number {
+  const pricing = MODEL_PRICING[model];
+
+  if (!pricing) {
+    // Fallback: use average rate for unknown models
+    const fallbackInputRate = 3 / 1_000_000;
+    const fallbackOutputRate = 15 / 1_000_000;
+    const inputCost = (usage.input_tokens ?? 0) * fallbackInputRate;
+    const outputCost = (usage.output_tokens ?? 0) * fallbackOutputRate;
+    const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * (0.5 / 1_000_000);
+    const cacheCreationCost = (usage.cache_creation_input_tokens ?? 0) * (2 / 1_000_000);
+    return inputCost + outputCost + cacheReadCost + cacheCreationCost;
+  }
+
+  // Convert $/1M rates to $/token
+  const inputRate = pricing.input / 1_000_000;
+  const outputRate = pricing.output / 1_000_000;
+  const cacheReadRate = (pricing.cacheRead ?? pricing.input * 0.1) / 1_000_000;
+  const cacheCreationRate = (pricing.cacheCreation ?? pricing.input * 0.33) / 1_000_000;
+
+  const inputCost = (usage.input_tokens ?? 0) * inputRate;
+  const outputCost = (usage.output_tokens ?? 0) * outputRate;
+  const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * cacheReadRate;
+  const cacheCreationCost = (usage.cache_creation_input_tokens ?? 0) * cacheCreationRate;
+
+  return inputCost + outputCost + cacheReadCost + cacheCreationCost;
+}

package/src/agents/cost/index.ts

@@ -0,0 +1,10 @@
+export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence, SessionTokenUsage } from "./types";
+export { COST_RATES, MODEL_PRICING } from "./pricing";
+export { parseTokenUsage } from "./parse";
+export {
+  estimateCost,
+  estimateCostFromOutput,
+  estimateCostByDuration,
+  formatCostWithConfidence,
+  estimateCostFromTokenUsage,
+} from "./calculate";

package/src/agents/cost/parse.ts

@@ -0,0 +1,97 @@
+/**
+ * Token usage parsing from raw agent output strings.
+ */
+
+import type { TokenUsageWithConfidence } from "./types";
+
+/**
+ * Parse Claude Code output for token usage.
+ *
+ * Supports multiple formats with varying confidence levels:
+ * - JSON structured output → "exact" confidence
+ * - Markdown/plain text patterns → "estimated" confidence
+ *
+ * Uses specific regex patterns to reduce false positives.
+ *
+ * @param output - Agent stdout + stderr combined
+ * @returns Token usage with confidence indicator, or null if tokens cannot be parsed
+ *
+ * @example
+ * ```ts
+ * // JSON format (exact)
+ * const usage1 = parseTokenUsage('{"usage": {"input_tokens": 1234, "output_tokens": 5678}}');
+ * // { inputTokens: 1234, outputTokens: 5678, confidence: 'exact' }
+ *
+ * // Markdown format (estimated)
+ * const usage2 = parseTokenUsage('Input tokens: 1234\nOutput tokens: 5678');
+ * // { inputTokens: 1234, outputTokens: 5678, confidence: 'estimated' }
+ *
+ * // Unparseable
+ * const usage3 = parseTokenUsage('No token data here');
+ * // null
+ * ```
+ */
+export function parseTokenUsage(output: string): TokenUsageWithConfidence | null {
+  // Try JSON format first (most reliable) - confidence: exact
+  try {
+    const jsonMatch = output.match(
+      /\{[^}]*"usage"\s*:\s*\{[^}]*"input_tokens"\s*:\s*(\d+)[^}]*"output_tokens"\s*:\s*(\d+)[^}]*\}[^}]*\}/,
+    );
+    if (jsonMatch) {
+      return {
+        inputTokens: Number.parseInt(jsonMatch[1], 10),
+        outputTokens: Number.parseInt(jsonMatch[2], 10),
+        confidence: "exact",
+      };
+    }
+
+    // Try parsing as full JSON object
+    const lines = output.split("\n");
+    for (const line of lines) {
+      if (line.trim().startsWith("{")) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.usage?.input_tokens && parsed.usage?.output_tokens) {
+            return {
+              inputTokens: parsed.usage.input_tokens,
+              outputTokens: parsed.usage.output_tokens,
+              confidence: "exact",
+            };
+          }
+        } catch {
+          // Not valid JSON, continue
+        }
+      }
+    }
+  } catch {
+    // JSON parsing failed, try regex patterns
+  }
+
+  // Try specific markdown-style patterns (more specific to reduce false positives)
+  // Match "Input tokens: 1234" or "input_tokens: 1234" or "INPUT TOKENS: 1234"
+  // Use word boundary at start, require colon or space after keyword, then digits
+  // confidence: estimated (regex-based)
+  const inputMatch = output.match(/\b(?:input|input_tokens)\s*:\s*(\d{2,})|(?:input)\s+(?:tokens?)\s*:\s*(\d{2,})/i);
+  const outputMatch = output.match(
+    /\b(?:output|output_tokens)\s*:\s*(\d{2,})|(?:output)\s+(?:tokens?)\s*:\s*(\d{2,})/i,
+  );
+
+  if (inputMatch && outputMatch) {
+    // Extract token counts (may be in capture group 1 or 2)
+    const inputTokens = Number.parseInt(inputMatch[1] || inputMatch[2], 10);
+    const outputTokens = Number.parseInt(outputMatch[1] || outputMatch[2], 10);
+
+    // Sanity check: reject if tokens seem unreasonably large (> 1M each)
+    if (inputTokens > 1_000_000 || outputTokens > 1_000_000) {
+      return null;
+    }
+
+    return {
+      inputTokens,
+      outputTokens,
+      confidence: "estimated",
+    };
+  }
+
+  return null;
+}

package/src/agents/cost/pricing.ts

@@ -0,0 +1,59 @@
+/**
+ * Cost rate tables for all supported model tiers and specific models.
+ */
+
+import type { ModelTier } from "../../config/schema";
+import type { ModelCostRates } from "./types";
+
+/** Model tier cost rates (as of 2025-01) */
+export const COST_RATES: Record<ModelTier, ModelCostRates> = {
+  fast: {
+    // Haiku 4.5
+    inputPer1M: 0.8,
+    outputPer1M: 4.0,
+  },
+  balanced: {
+    // Sonnet 4.5
+    inputPer1M: 3.0,
+    outputPer1M: 15.0,
+  },
+  powerful: {
+    // Opus 4
+    inputPer1M: 15.0,
+    outputPer1M: 75.0,
+  },
+};
+
+/** Per-model pricing in $/1M tokens: { input, output } */
+export const MODEL_PRICING: Record<
+  string,
+  { input: number; output: number; cacheRead?: number; cacheCreation?: number }
+> = {
+  // Anthropic Claude models (short aliases)
+  sonnet: { input: 3, output: 15 },
+  haiku: { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  opus: { input: 15, output: 75 },
+
+  // Anthropic Claude models (full names)
+  "claude-sonnet-4": { input: 3, output: 15 },
+  "claude-sonnet-4-5": { input: 3, output: 15 },
+  "claude-sonnet-4-6": { input: 3, output: 15 },
+  "claude-haiku": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  "claude-haiku-4-5": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  "claude-opus": { input: 15, output: 75 },
+  "claude-opus-4": { input: 15, output: 75 },
+  "claude-opus-4-6": { input: 15, output: 75 },
+
+  // OpenAI models
+  "gpt-4.1": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+
+  // Google Gemini
+  "gemini-2.5-pro": { input: 0.075, output: 0.3 },
+  "gemini-2-pro": { input: 0.075, output: 0.3 },
+
+  // OpenAI Codex
+  codex: { input: 0.02, output: 0.06 },
+  "code-davinci-002": { input: 0.02, output: 0.06 },
+};

package/src/agents/cost/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Cost tracking types — shared across all agent adapters.
+ */
+
+import type { ModelTier } from "../../config/schema";
+
+export type { ModelTier };
+
+/** Cost rates per 1M tokens (USD) */
+export interface ModelCostRates {
+  inputPer1M: number;
+  outputPer1M: number;
+}
+
+/** Token usage data (camelCase — nax-internal representation) */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/** Cost estimate with confidence indicator */
+export interface CostEstimate {
+  cost: number;
+  confidence: "exact" | "estimated" | "fallback";
+}
+
+/** Token usage with confidence indicator */
+export interface TokenUsageWithConfidence {
+  inputTokens: number;
+  outputTokens: number;
+  confidence: "exact" | "estimated";
+}
+
+/**
+ * Token usage from an ACP session's cumulative_token_usage field.
+ * Uses snake_case to match the ACP wire format.
+ */
+export interface SessionTokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  /** Cache read tokens — billed at a reduced rate */
+  cache_read_input_tokens?: number;
+  /** Cache creation tokens — billed at a higher creation rate */
+  cache_creation_input_tokens?: number;
+}