[Epic] PAGS Admin / Operator Portal

[serge-ivo]

Epic: PAGS Admin / Operator Portal

PAGS has no working admin portal. Today there is only a static stub at platform/store/admin/index.html that lists published agents from the public /v1/agents endpoint; its "All Users" and "Recent Usage" tables are hard-coded placeholders that are never populated. requireAdmin() exists (workers/api/src/lib/auth.ts) but is called by zero routes — there is no cross-user/operator API of any kind. As the operator you cannot see: all users, all agents/instances, aggregate usage, or platform AI spend.

This is now urgent because PLATFORM_AI_ENABLED="true" (workers/api/wrangler.toml) means the platform pays for internal AI (embeddings + conversation summaries + translation fallback) on its own Cloudflare account, and that spend is invisible in-app — the ai_usage ledger records CF calls at cost_micros≈0, so today it only shows in the raw Cloudflare dashboard.

Goal

A real operator portal: all-users, all-agents/instances, aggregate usage + spending (with platform-paid-vs-BYOK split), errors/trace/ops monitoring, moderation, and an admin-action audit log — modeled on the sibling stores but fit to PAGS's data model.

Cross-store reference (surveyed 2026-08-01)

• FGS (fgs/admin/) — the most complete: React SPA served by a CF Worker (hash routing, Tailwind). Pages: Overview, Ops (stuck/failed sessions), Games, Errors, Users, User Detail, Sessions, Session View (+ inject prompt), Provision. Auth = Google sign-in + ADMIN_EMAILS allowlist. Endpoints: /api/stats, /api/users, /api/allusers, /api/errors, /api/sessions, /api/comp (grants), /api/userkey.
• FAS (fas/admin/ + packages/backend/routes/content-admin.ts) — adds CF-Access JWT gating, moderation (browse/delete KV/collections/counters), traffic analytics (CF Analytics Engine), deprovision, /v1/admin/{users,apps,stats,agent-sessions,agent-errors} behind requireAdmin (ADMIN_GITHUB_LOGINS).
• PAS (pas/console AdminView + packages/backend) — the financial layer: submission review (approve/reject → provision), platform analytics (/v1/analytics/admin/platform, ClickHouse), Stripe Connect payouts. PAS's own documented gaps (no all-users list, no error UI, no usage/cost admin, no moderation, no audit trail) are exactly what this epic should NOT repeat.

Architecture decision (PAGS-fit)

Do not stand up a separate admin worker/DNS like FAS/FGS. PAGS is a single self-contained monorepo; the host worker already serves store/ (incl. /admin). Plan:

• Gating: reuse the existing requireAdmin + session.roles model (admin role lives in users.roles JSON, baked into the session JWT at sign-in). No new auth system.
• API: new /v1/admin/* route group in workers/api, every handler behind requireAdmin.
• UI: a React admin app (mirror store/console — React 19 + Tailwind v4 + Vite) served at /admin by the host worker, replacing the static stub. Client-side gate via /v1/auth/me roles; the real enforcement is server-side.

Child issues

Non-goals (for this epic)

• Enabling PAGS paid billing (deferred — PAS owns the paid launch). Surfacing subscription/billing state read-only is in scope; charging is not.
• Building a new analytics pipeline. Reuse the existing ai_usage/usage/agent_events/error_log tables.
  Foundation & infra (do first):
• [Admin] Foundation: access control gating + admin-action audit log #28 Foundation: access control gating + admin-action audit log — blocks everything
• [Admin] Infra: admin SPA packaging + host serving at /admin #29 Infra: admin SPA packaging + host serving at /admin

Backend APIs (need #28):

• [Admin][API] Users — cross-user list + detail #30 Users — cross-user list + detail
• [Admin][API] Agents & Instances — cross-tenant list + detail #31 Agents & Instances — cross-tenant list + detail
• [Admin][API] Usage & Spending — ledger, platform-paid vs BYOK, cost + AI kill switch #32 Usage & Spending — ledger, platform-paid vs BYOK, cost + AI kill switch ⭐ (spend concern)
• [Admin][API] Errors, Trace & Ops queue + MCP audit surfacing #33 Errors, Trace & Ops queue + MCP audit surfacing
• [Admin][API] Moderation — suspend user, unpublish/delete agent, cancel instance, roles/keys #34 Moderation — suspend/unpublish/cancel/roles/keys

Frontend (need #29 + #35):

• [Admin][UI] SPA scaffold — auth gate, shell, navigation #35 SPA scaffold — auth gate, shell, navigation — blocks other UI
• [Admin][UI] Overview dashboard #36 Overview dashboard
• [Admin][UI] Users page + User Detail #37 Users page + User Detail
• [Admin][UI] Agents & Instances page #38 Agents & Instances page
• [Admin][UI] Usage & Spending dashboard (+ platform-AI kill switch) #39 Usage & Spending dashboard (+ platform-AI kill switch) ⭐ (spend concern)
• [Admin][UI] Errors & Ops page #40 Errors & Ops page
• [Admin][UI] Moderation controls + admin audit-log viewer #41 Moderation controls + admin audit-log viewer

Suggested order: #28 → #29 → APIs (#30–#34, parallel) → #35 → UI pages (#36–#41, parallel). Start #32/#39 early — they close the invisible-platform-spend gap that motivated this epic.

Spend-metering follow-ups (split out of #32):

• [Admin][API] Meter platform-paid AI into the ledger (embeddings/summaries/translation) #44 Meter platform-paid AI into the ledger (embeddings/summaries/translation)
• [Admin][API] Cloudflare billing-actuals for authoritative platform AI spend #45 Cloudflare billing-actuals for authoritative platform AI spend
• [Admin][API] Runtime kill switch for platform-paid AI (platform_settings override) #46 Runtime kill switch for platform-paid AI (platform_settings override)

Progress: API tier #28/#32/#44/#30 + admin SPA (#29/#35/#36/#37/#39) all live on main + deployed. proagentstore.online/admin is up. Remaining: #31 Agents/Instances, #33 Errors/Ops, #34 Moderation, #38/#40/#41 UI; spend follow-ups #45/#46; CF Access with #35 note.

[serge-ivo]

Closing — every sub-issue is done.

#28 ✓  #31 ✓  #34 ✓  #38 ✓  #41 ✓  #46 ✓  #109 ✓

Shipped: cross-tenant agent/instance list + detail with filters and live runtime status (#31), seven moderation routes with audit rows (#34), the Agents/Instances pages (#38), moderation controls + audit viewer (#41), the platform-paid AI kill switch (#46), and the admin rate-limit bucket (#109). Plus, outside the original list: the external-vs-operator usage split (#269) and the admin app's first tests (#280).

Two items remain and stand alone rather than needing an epic:

• Enable Cloudflare Access on the /v1/admin perimeter before paid launch #108 — Cloudflare Access on the /v1/admin perimeter. Now MORE load-bearing than when this epic was written, because the moderation routes that just shipped perform irreversible cross-tenant operations behind a perimeter that is not yet hardened. Each route guards itself with requireAdmin + an audit row, so this is defence in depth rather than the only control — but it should land before any paid launch.
• [Admin][API] Cloudflare billing-actuals for authoritative platform AI spend #45 — see its own close comment.