How Maka Tracks Token Usage and Project Costs: A Complete Technical Guide

Maka tracks token usage by emitting token_usage session events after each model interaction, looking up per-model pricing from a metadata catalog, computing per-call costs in USD, and aggregating these values into session and project-level cost reports.

The Apache Maka project implements a comprehensive token usage tracking and project cost calculation pipeline that records every interaction with a language model. This system enables precise cost attribution for AI-powered applications, giving developers visibility into their spending across model providers and project runs.

Token Usage Event Creation

Every model interaction in Maka is captured as a session event. When a language model returns a response, the runtime kernel emits a token_usage event containing the input and output token counts.

In packages/runtime/src/runtime-kernel.ts at line 1013, the kernel emits this event after the model stream finishes:

emit({
  type: 'token_usage',
  input: nInput,
  output: nOutput,
  total: nInput + nOutput,
  runtimeSteps: 1,
  ts: Date.now(),
});

The event type is formally defined in packages/core/src/events.ts at line 1065 as type: 'token_usage', ensuring type safety across the codebase.

This event captures the raw token consumption data that serves as the foundation for all subsequent cost calculations.

Model Price Lookup and Cost Attribution

To translate tokens into monetary cost, Maka maintains a model metadata catalog with pricing information for supported providers. The sync-model-metadata.mjs script (lines 636-647) loads this data and provides helper functions for cost retrieval:

const inputUsdPer1M  = priceNumber(provider, modelId, cost.input,  'input');
const outputUsdPer1M = priceNumber(provider, modelId, cost.output, 'output');

These rates represent the price per 1 million tokens for both input and output, as published by model providers.

Using these rates, the runtime computes a costUsd value for each call. This calculation happens in packages/runtime/src/runtime-event-read-model.ts, where events are enriched with financial data:

// Compute cost for this call
const callCostUsd =
  (event.input / 1_000_000) * inputRate +
  (event.output / 1_000_000) * outputRate;

// Attach cost to the event
event.costUsd = callCostUsd;
event.costBasis = 'priced';

The costBasis field distinguishes between:

• ** 'priced'** — cost was successfully calculated using known pricing data
• 'unpriced' — pricing information was unavailable for this model

This distinction prevents missing pricing data from silently inflating reported costs with zero values.

Session-Level Cost Aggregation

As a session progresses, the session manager aggregates individual token_usage events into running totals. In packages/runtime/src/session-manager.ts, this aggregation sums the costUsd values across all token usage events:

session.costUsd = session.events
  .filter(e => e.type === 'token_usage')
  .reduce((sum, e) => sum + (e.costUsd ?? 0), 0);

The test suite in packages/runtime/src/__tests__/session-trace-projection.test.ts (lines 56-58 and 115-116) validates this behavior, verifying that aggregated usage records contain the expected costUsd and costBasis fields.

This aggregation produces an accurate running total that updates throughout the session lifecycle.

Project-Level Cost Reporting

Aggregated usage data persists in the project ledger, Maka's durable storage for historical run data. The PI (Project Insight) subsystem surfaces this information through both the UI and CLI, giving developers real-time visibility into their spending.

The ledger's design handles edge cases gracefully:

• Priced calls contribute their calculated costUsd to totals
• Unpriced calls are tracked separately to maintain transparency about data quality
• Mixed sessions partially contribute when some model pricing is available

This architecture ensures that project cost tracking remains accurate even as model providers update pricing or new models are introduced without immediate cost data.

Token Usage Tracking Pipeline

// Complete flow: model response → cost calculation → aggregation

// 1. Kernel emits token usage (runtime-kernel.ts)
const tokenEvent = emit({
  type: 'token_usage',
  input: 120,
  output: 30,
  total: 150,
  ts: Date.now(),
});

// 2. Pricing lookup (sync-model-metadata.mjs)
const modelCost = lookupPricing(provider, modelId);
const inputRate = modelCost.input;   // e.g., $2.50 per 1M tokens
const outputRate = modelCost.output; // e.g., $10.00 per 1M tokens

// 3. Cost computation (runtime-event-read-model.ts)
tokenEvent.costUsd = (120/1e6 * inputRate) + (30/1e6 * outputRate);
tokenEvent.costBasis = 'priced';

// 4. Session aggregation (session-manager.ts)
session.totalCostUsd += tokenEvent.costUsd;

// 5. Project persistence (project ledger)
persistToLedger(session);

Key Implementation Files

File	Purpose
packages/runtime/src/runtime-kernel.ts	Emits token_usage events after model streams complete
packages/core/src/events.ts	Defines the token_usage event type contract
scripts/sync-model-metadata.mjs	Loads and updates model pricing metadata
packages/runtime/src/runtime-event-read-model.ts	Enriches events with computed cost data
packages/runtime/src/__tests__/session-trace-projection.test.ts	Validates cost field presence on usage records
packages/runtime/src/__tests__/session-manager.test.ts	Tests session-level cost aggregation

Summary

• Event-driven architecture: Every model interaction generates a token_usage event with raw token counts
• External pricing source: Model costs are loaded from a metadata catalog, not hardcoded
• Explicit cost basis: The costBasis field tracks data quality and prevents misleading totals
• Hierarchical aggregation: Costs roll up from individual calls → sessions → project-level reports
• PI subsystem integration: Costs surface in both UI and CLI for operational visibility

Frequently Asked Questions

How does Maka handle models without known pricing?

Maka marks these calls with costBasis: 'unpriced' and excludes them from cost totals. This prevents unreliable estimates from distorting financial reports while maintaining transparency about coverage gaps.

Where does Maka's pricing data come from?

The sync-model-metadata.mjs script maintains the model-metadata catalog, which aggregates official pricing from providers. This externalized approach allows pricing updates without code changes.

Can developers override or customize pricing calculations?

The source architecture supports custom pricing through the model metadata system. Developers can extend the catalog or implement alternative priceNumber logic for private model deployments or negotiated rate cards.

What happens if a session is interrupted mid-run?

Partial session data is preserved in the project ledger. The aggregation logic in session-manager.ts only sums completed token_usage events, so interrupted runs report costs for confirmed interactions only.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}