--- path: /studio/isis/cost-tracking surface: studio domain: isis auth: signed-in + studio entitlement; direct legacy route is Studio-boundary hard-blocked unless the localhost E2E lane bypass is present source: apps/oshun/web/src/app/studio/isis/cost-tracking/page.tsx status: walked last_walked: '2026-07-01 real-infra Playwright route journey — Studio-boundary hard-block, localhost lane bypass, live `/v1/admin/isis/cost-tracking` pricing/usage rollup, valid record POST + duplicate/unknown-model rejection, loading / service-failure / malformed-catalog / malformed-record / unauthorized / network / anonymous states, route map, quick-actions, 44px hit targets, and shared axe gate. Evidence: apps/oshun/web/e2e/studio-isis-cost-tracking.spec.ts and WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md#259-2026-07-01-studio-isis-cost-tracking-coverage' --- # 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`): - `

` "Isis Cost Tracking Workspace" (`WorkspaceHeading`) - Summary paragraph (`data-cost-summary`) - Spend rollup (`data-cost-rollup`, `

`): 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`, `

`) of `data-cost-record-row` cards with per-record cost (`data-cost-record-cost`) - **Route map panel** (`data-isis-cost-tracking-route-map`): `

` "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 - [x] **Loading** — `data-cost-loading` "Loading cost tracking…" - [x] **Unauthorized** — `data-cost-unauthorized` (admin-scope fail-closed on 401/403) - [x] **Error** — `data-cost-error` on non-OK / malformed response - [x] **Ready (form)** — rollup + record form + record list render; empty list shows `data-cost-records-empty` - [x] **Result** — `data-cost-result` with `data-cost-status` (`ok` / `error`) ## Interactions ### Record a usage event (`data-cost-form`) - [x] **Record id** — `data-cost-recordid` text input - [x] **Model** — `data-cost-model` select (options from the response `pricingTable`) - [x] **Input tokens** — `data-cost-input-tokens` number input (min 0, step 1) - [x] **Output tokens** — `data-cost-output-tokens` number input (min 0, step 1) - [x] **Record usage** — `data-cost-record` submit; POSTs to `/v1/admin/isis/cost-tracking`, then reloads the rollup + records ### Route map - [x] **Route-map articles** — non-interactive path + purpose entries ### Quick-actions - [x] **Open Isis Budget Management workspace** → `/studio/isis/budget-management` - [x] **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`](../../studio-overview.md) - Sibling routes: - [`studio-isis-budget-management.md`](./studio-isis-budget-management.md) - [`studio-isis-resource-recommendations.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 - [x] 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