Isis Cost Tracking

Purpose#

Admin lane console for recording LLM usage and seeing the real dollar cost. Each record is priced from the model's published per-1K input/output rates and rolled up by provider and model. Models without a pricing entry are rejected — costs are computed from the rate table, never guessed.

Entry points#

• Sibling quick-action card from /studio/isis/budget-management
• Studio index (/studio)
• Direct URL / bookmark

Layout regions#

page.tsx mounts ShellLayout active="studio" and three panels (no breadcrumb panel).

• Workspace panel (data-isis-cost-tracking-workspace):
  • <h1> "Isis Cost Tracking Workspace" (WorkspaceHeading)
  • Summary paragraph (data-cost-summary)
  • Spend rollup (data-cost-rollup, <h2>): total (data-cost-total) and per-provider cards (data-cost-provider)
  • The "Record a usage event" form (data-cost-form)
  • Usage-record list (data-cost-records, <h2>) of data-cost-record-row cards with per-record cost (data-cost-record-cost)
• Route map panel (data-isis-cost-tracking-route-map): <h2> "Route Map" enumerating STUDIO_ISIS_COST_TRACKING_ROUTE_MAP
• Quick-actions panel: quickAction links to /studio/isis/budget-management and "Back to Studio workspace index" → /studio

States#

• Loading — data-cost-loading "Loading cost tracking…"
• Unauthorized — data-cost-unauthorized (admin-scope fail-closed on 401/403)
• Error — data-cost-error on non-OK / malformed response
• Ready (form) — rollup + record form + record list render; empty list shows data-cost-records-empty
• Result — data-cost-result with data-cost-status (ok / error)

Interactions#

Record a usage event (data-cost-form)#

• Record id — data-cost-recordid text input
• Model — data-cost-model select (options from the response pricingTable)
• Input tokens — data-cost-input-tokens number input (min 0, step 1)
• Output tokens — data-cost-output-tokens number input (min 0, step 1)
• Record usage — data-cost-record submit; POSTs to /v1/admin/isis/cost-tracking, then reloads the rollup + records

Route map#

• Route-map articles — non-interactive path + purpose entries

Quick-actions#

• Open Isis Budget Management workspace → /studio/isis/budget-management
• Back to Studio workspace index → /studio

Data & contracts#

• Reads: GET /v1/admin/isis/cost-tracking (COST_ENDPOINT) on mount — rollup + records + pricingTable
• Writes: POST /v1/admin/isis/cost-tracking — record a usage event
• Realtime: None
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders()
• Auth: admin-scoped fail-closed (401/403 → unauthorized state); route behind the signed-in + studio proxy gate; direct legacy URL hard-blocked by the Studio Isis boundary unless the localhost E2E lane bypass is present
• Validation: strict client-side response guard rejects malformed pricing rows, usage records, provider/model rollups, total-record mismatches, and malformed successful record responses before rendering or acknowledging a write
• Component sources:
  • apps/oshun/web/src/components/studio/StudioIsisCostTrackingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioIsisCostTrackingRouteMap.ts

Automated coverage#

• apps/oshun/web/e2e/studio-isis-cost-tracking.spec.ts drives the direct hard-block, localhost-only lane bypass, live BFF pricing/rollup catalog, real claude-3.5-sonnet usage POST and readback, duplicate-record rejection, unknown-model rejection, client validation, pending-submit lockout, route-map, quick-actions, loading, service-failure, malformed catalog, malformed record response, unauthorized, network, anonymous redirect, 44px hit targets, and shared axe gate.
• apps/oshun/bff/src/__tests__/admin-isis-cost-tracking-route.test.ts covers auth/scope enforcement, published pricing-table exposure, exact known-cost calculations, total/provider/model rollup semantics, duplicate rejection, and unknown-model rejection.

Cross-references#

• Studio overview: ../../studio-overview.md
• Sibling routes:
  • studio-isis-budget-management.md
  • studio-isis-resource-recommendations.md

Open questions / known gaps#

• Recorded usage is held in the service's session store — confirm durability / persistence of recorded events in production
• Pricing table is the source of truth; models absent from it are rejected rather than estimated
• Route-map sub-paths are declared but not yet implemented as separate pages
• Manual AT, real touch-device, offline replay, and telemetry-delivery passes remain product-hardening items beyond this automated route journey