Fuel Control

Fuel is Mayros's cost tracking system. Every LLM call is recorded as a fuel event with provider, model, token counts, and cost in integer cents. No monthly reset needed — spend is computed on-the-fly from event history stored as Cortex triples.

What is Fuel?

A fuel event captures a single LLM interaction:

Field	Type	Description
`costCents`	integer	Cost in cents (e.g. 150 = $1.50)
`provider`	string	LLM provider (e.g. `anthropic`, `openai`)
`model`	string	Model identifier (e.g. `claude-sonnet-4-20250514`)
`inputTokens`	integer	Prompt tokens consumed
`outputTokens`	integer	Completion tokens generated
`ventureId`	string	Parent venture
`agentId`	string	Agent that incurred the cost
`missionId`	string?	Associated mission (if any)

Integer cents avoid floating-point drift across thousands of events. All events are stored as Cortex RDF triples — no denormalized counters, no cron jobs.

Recording Fuel Events

Fuel events are recorded automatically by the runtime when agents make LLM calls. You can also record events manually:

bash
# Record a fuel event via CLI
mayros kaneru fuel record \
  --venture <id> \
  --agent scanner \
  --provider anthropic \
  --model claude-sonnet-4-20250514 \
  --cost 42 \
  --input-tokens 1200 \
  --output-tokens 350

Summary

The summary aggregates all fuel events for a venture into a single view:

bash
mayros kaneru fuel summary --venture <id>

Output includes:

Total spent — sum of all costCents across events
Remaining — fuelLimit - totalSpent (zero if no limit set)
Burn rate — cents per hour, computed from first to last event timestamps
By agent — per-agent spend breakdown, sorted highest first
By mission — per-mission spend breakdown

Analytics

Cost analytics provide time-series trends, provider breakdowns, and efficiency metrics.

bash
# Daily time series (default)
mayros kaneru fuel analytics --venture <id>

# Weekly or monthly aggregation
mayros kaneru fuel analytics --venture <id> --period weekly
mayros kaneru fuel analytics --venture <id> --period monthly

Time Series

Events are bucketed into daily, weekly, or monthly intervals. Each point shows:

Date (or week/month start)
Cost in cents for that period
Number of fuel events

Provider Breakdown

Spend grouped by provider/model combination with token totals:

By provider:
  anthropic/claude-sonnet-4-20250514: 4200 cents (120 events)
  openai/gpt-4o: 1800 cents (45 events)

Efficiency Metrics

Metric	Description
Cost per mission	Total cents / completed missions
Avg cost per event	Total cents / total fuel events
Total input tokens	Sum across all events
Total output tokens	Sum across all events

Forecasting

Forecast projects future spend based on historical burn rate:

bash
mayros kaneru fuel forecast --venture <id>

Field	Description
`burnRateCentsPerHour`	Current burn rate extrapolated from event history
`projectedMonthlyCents`	Estimated 30-day spend at current rate
`daysUntilExhausted`	Days until fuel limit is reached (`null` if no limit)
`confidence`	`low`, `medium`, or `high` based on data volume

Confidence levels:

low — fewer than 10 fuel events
medium — 10–50 events
high — 50+ events with consistent patterns

Budget Limits

Fuel limits enforce spending caps at two levels:

Venture-Level Limits

Set when creating a venture:

bash
mayros kaneru venture create --name "Acme" --prefix ACM --fuel-limit 10000

When the limit is reached, new agent runs for that venture are blocked until the limit is raised.

Agent-Level Limits

Check an individual agent's spend against a custom threshold:

bash
# Check if agent exceeded a 2000-cent limit
mayros kaneru fuel check-agent --agent scanner --limit 2000

MCP Tools

📌

kaneru_fuel_summary

Get total spend, remaining budget, burn rate, and per-agent/per-mission breakdowns.

📌

kaneru_fuel_analytics

Time-series trends, provider breakdown, and efficiency metrics.

📌

kaneru_fuel_forecast

Projected monthly spend, days until exhausted, and confidence level.

Design Notes

No monthly reset — spend is computed on-the-fly from the full event history. Delete old events via Cortex triple management if you want a clean slate.
Integer cents — avoids floating-point drift. $1.50 is stored as 150.
Event-sourced — every fuel event is an immutable Cortex triple, DAG-committed for auditability.

Next Steps

Ventures & Missions — set fuel limits when creating ventures
Decisions — consensus decisions also track fuel context
DAG Audit Trail — fuel events are DAG-committed