[DOCS] Inconsistency in `total_cost_usd` property location between TypeScript Reference and Cost Tracking Guide

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/typescript - https://platform.claude.com/docs/en/agent-sdk/cost-tracking

Section/Topic

• SDKResultMessage type definition in the TypeScript Reference - CostTracker implementation example in the Cost Tracking Guide

Current Documentation

In docs/en/agent-sdk/typescript.md, the type definition shows total_cost_usd at the root of the result object:

type SDKResultMessage = | {
      type: 'result';
      subtype: 'success';
      // ...
      total_cost_usd: number;
      usage: NonNullableUsage;
      // ...
    }

However, in docs/en/agent-sdk/cost-tracking.md, the implementation example accesses it via the usage property:

async trackConversation(prompt: string) {
  // ...
  return {
    result,
    stepUsages: this.stepUsages,
    totalCost: result.usage?.total_cost_usd || 0
  };
}

What's Wrong or Missing?

There is a cross-reference inconsistency. The official API reference defines total_cost_usd as a property of the SDKResultMessage root, but the guide's code example treats it as a nested property within usage. This is confusing for developers trying to implement authoritative cost tracking, as it is unclear which structure the SDK actually returns.

Suggested Improvement

The examples in docs/en/agent-sdk/cost-tracking.md (for both TypeScript and Python) should be updated to match the authoritative type definition.

Suggested change for the TypeScript example:

// From:
totalCost: result.usage?.total_cost_usd || 0

// To:
totalCost: result.total_cost_usd || 0

Suggested change for the Python example:

# From:
"total_cost": result.total_cost_usd if result else 0

# To:
# (Verify if Python SDK also puts this at root; if so, update to match)
"total_cost": result.total_cost_usd if result else 0

Impact

High - Prevents users from using a feature

Additional Context

• This inconsistency exists in the "Implementation: Cost Tracking System" section of the guide.
• Correcting this is important because the guide specifically mentions that total_cost_usd in the result message is "authoritative," making accuracy in its access path critical.