Documentation Index

Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Paymaster

• Metered — pay-per-token API-key calls. Real $ math, real budgets.
• Flat-rate — subscription credentials (Anthropic Max, ChatGPT Plus, etc.). The $200/mo is paid up front; the marginal cost of one more token is $0 from our perspective.

​

Data model

-- One row per LLM round-trip. Columns added in migration 62 marked [v62].
CREATE TABLE cost_ledger (
  id                    TEXT PRIMARY KEY,
  workspace_id          TEXT NOT NULL,
  crew_id               TEXT,
  agent_id              TEXT,
  mission_id            TEXT,
  provider              TEXT NOT NULL,
  model                 TEXT NOT NULL,
  input_tokens          INTEGER NOT NULL DEFAULT 0,
  output_tokens         INTEGER NOT NULL DEFAULT 0,
  cached_input_tokens   INTEGER NOT NULL DEFAULT 0,
  cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
  cost_usd              REAL NOT NULL DEFAULT 0,
  tags                  TEXT NOT NULL DEFAULT '{}',
  ts                    TEXT NOT NULL,
  -- [v62] Billing-mode discriminator. 'metered' (default) | 'flat_rate'.
  billing_mode          TEXT NOT NULL DEFAULT 'metered',
  -- [v62] Live rate-limit signal harvested from upstream response headers.
  -- NULL when the call had no rate-limit headers (e.g. local Ollama, errors).
  quota_remaining_pct   REAL,
  quota_window          TEXT,             -- 'requests_per_min' | 'tokens_per_min' | 'input_tokens_per_min' | 'output_tokens_per_min' (most-restrictive)
  -- [v62] Display label for flat-rate rows. NULL for metered.
  subscription_plan     TEXT,
  -- [v62] Rate-card snapshot at write time (Langfuse pattern). A future
  -- pricing.go change cannot retroactively rewrite history.
  -- Stored as plain REAL (nullable, no DEFAULT); the writer always
  -- supplies a non-NULL value so the column is effectively populated.
  rate_input_per_m      REAL,
  rate_output_per_m     REAL,
  rate_cached_in_per_m  REAL,
  rate_cache_write_per_m REAL NOT NULL DEFAULT 0,
  -- [v62] Provenance label per row (Helicone pattern). UI never renders a
  -- $ figure without telling the operator how trustworthy it is.
  cost_confidence       TEXT NOT NULL DEFAULT 'estimate'
);

-- [v62] Partial index for the Subscriptions panel — covers only flat-rate rows
-- (most rows are 'metered'), so the index stays small and Subscriptions queries
-- avoid a full-ledger scan. The (workspace_id, billing_mode, ts DESC) shape
-- means "newest flat-rate row in this workspace" is an index-only seek.
CREATE INDEX idx_cost_billing_mode
  ON cost_ledger (workspace_id, billing_mode, ts DESC)
  WHERE billing_mode = 'flat_rate';

-- Optional per-scope limit. Walked hierarchically before every call.
CREATE TABLE budget_limits (
  id           TEXT PRIMARY KEY,
  workspace_id TEXT NOT NULL,
  scope_kind   TEXT NOT NULL CHECK (scope_kind IN ('workspace','crew','mission','agent')),
  scope_id     TEXT NOT NULL,
  window       TEXT NOT NULL CHECK (window IN ('hour','day','week','month','mission')),
  limit_usd    REAL NOT NULL,
  mode         TEXT NOT NULL CHECK (mode IN ('soft','hard','tiered')),
  enabled      INTEGER NOT NULL DEFAULT 1
);

​

Budget scopes

​

Enforcement modes

const (
    ModeSoft   EnforcementMode = "soft"   // never blocks, reports state=exceeded
    ModeHard   EnforcementMode = "hard"   // blocks at 100%, no warn tier
    ModeTiered EnforcementMode = "tiered" // warn at 80%, block at 100%
)

• soft — Enforce never returns an error. Emits budget.warning when over 100% so the UI still paints it red. Use for cost-curious teams that want visibility without the platform pulling the plug.
• hard — BudgetExceededError at 100%. No warn band. Emits budget.exceeded.
• tiered — emits budget.warning at 80% (no block) and budget.exceeded at 100% (block). The default for new budgets; gives operators a window to react.

​

Billing modes

​

Cost confidence

• precise — provider returned a usage block we trust verbatim (e.g. Anthropic non-streaming).
• estimate — we computed it from pricing.go rates against parsed token counts.
• unknown — flat-rate row, or we couldn’t parse the response body (streaming with no body buffer, opaque proxy).

​

Quota enforcement

• anthropic-ratelimit-{requests,input-tokens,output-tokens}-{limit,remaining,reset}
• x-ratelimit-{remaining-tokens,remaining-requests,reset-tokens} (OpenAI / xAI / DeepSeek)

func EnforceQuota(
    ctx context.Context,
    j journal.Emitter,
    scope Scope,
    remainingPct float64,   // 0.0–1.0; smallest of the parsed windows
    window QuotaWindow,     // requests_per_min | tokens_per_min | input_tokens_per_min | output_tokens_per_min — display only
    hadStatus429 bool,      // upstream sent 429 → authoritative "out"
) error

​

Prompt-cache token flow

1. Provider returns usage — Anthropic emits cache_read_input_tokens + cache_creation_input_tokens in the usage block (both non-streaming and message_start SSE events); OpenAI emits prompt_tokens_details.cached_tokens (no separate creation counter — caching is opaque on their side).
2. internal/llm/{anthropic,openai}.go parses the fields into Response.CachedInputToks + Response.CacheCreationToks.
3. internal/llm/middleware.go plumbs them through providerCaller / streamCaller into paymaster.CallResponse.CachedInputTokens + .CacheCreationTokens.
4. paymaster.Middleware records them into the matching cost_ledger columns alongside the rate-card snapshot. Cache reads bill at rate_cached_in_per_m; cache creates at rate_cache_write_per_m.
5. telemetry.LLMMiddleware stamps the same counts as gen_ai.usage.cached_input_tokens + gen_ai.usage.cache_creation_tokens on the llm.call span — see Tracing.

​

Rate-card snapshotting (Langfuse pattern)

​

Pricing — current rates

​

The call path

1. Enforce — Check resolves every applicable budget; a hard/tiered breach short-circuits with *BudgetExceededError. The underlying call is never made, no ledger row is written, but budget.exceeded lands in the journal.
2. Call — delegate to the inner caller.
3. Record — fill cost_usd via Estimate(provider, model, tokens) if the provider didn’t price the call inline, then INSERT the row and emit llm.call + cost.incurred.

​

Read endpoints

• GET /api/v1/paymaster/spend/by-crew?range=7d — one row per crew (metered only).
• GET /api/v1/paymaster/spend/by-agent/{crewId}?range=24h — per-agent rollup inside a crew (metered only).
• GET /api/v1/paymaster/spend/by-mission/{missionId} — single-mission total (metered only).
• GET /api/v1/paymaster/top-spenders?limit=10&range=7d — highest-cost scopes (metered only).
• GET /api/v1/paymaster/subscriptions?range=30d — flat-rate credentials grouped by (plan, provider) with call count, token count, last-used timestamp. No $ figure — see “Billing modes” above for why.

​

Internal write endpoint

​

CLI

crewship paymaster by-crew --range 7d
crewship paymaster by-agent backend-team --range 24h
crewship paymaster top --limit 5 --range 30d

​

Creating a budget

INSERT INTO budget_limits (id, workspace_id, scope_kind, scope_id, window, limit_usd, mode, enabled)
VALUES ('bl_default_daily', 'ws_123', 'workspace', 'ws_123', 'day', 250.0, 'hard', 1);

​

Sidecar coverage of agent CLI calls

​

Gotchas

• Soft budgets still emit entries. A soft budget at 120% still writes budget.warning to the journal — the UI uses this to paint red. Don’t filter out “soft” when looking for “who was over”.
• Stream path is unmetered. wrappedProvider.Stream() bypasses the full middleware (token counts arrive in the terminal message_delta event, which the sync CallResponse shape can’t carry). Streaming callers pay through orchestrator-level accounting that predates this package.
• Pricing is estimated. pricing.go hard-codes per-token prices per (provider, model). When the provider ships a new model the estimate falls to zero until pricing is added — check internal/paymaster/pricing.go after any provider upgrade.

​

Related

• LLM middleware — layer order and composition.
• crewship paymaster — CLI.
• Paymaster API.
• Crew Journal — llm.call, cost.incurred, budget.* entry types.