2026-04-27 — Admin AI Assistant (Lantern Chat)

Outcome: Complete — backend + UI + wiring shipped, admin build green, smoke-tested locally.

Scope

Add an agentic Claude-powered chat assistant to the admin portal. The assistant answers questions contextually and may, when it decides it's needed, read repo files (docs/code), grep the repo, list directories, list registered API services, or query a small allow-list of Firestore collections.

Files Added

Backend — services/api/assistant/ (new Cloud Run service)

• services/api/assistant/package.json — workspace lantern-assistant-api. @anthropic-ai/sdk@^0.91.1.
• services/api/assistant/Dockerfile — Node 22-slim, bundles repo-snapshot/ + .shared-pkg/.
• services/api/assistant/openapi.json — OpenAPI 3.0 spec, served at /openapi.json.
• services/api/assistant/README.md, services/api/assistant/.gitignore
• services/api/assistant/src/index.js — Express app. CORS via ALLOWED_ORIGINS, JSON 256kb. Routes: /health (public), /openapi.json + /api-docs Scalar (public, per CLAUDE.md rule #8), /assistant/* (admin-authed + rate-limited).
• src/middleware/auth.js — verifyFirebaseToken + requireAdmin (mirrors services/api/auth/src/middleware/auth.js).
• src/middleware/rateLimiter.js — 30 turns / 5 min per user.
• src/middleware/errorHandler.js
• src/routes/health.js, src/routes/chat.js — Zod-validated POST /assistant/chat.
• src/services/anthropic.js — agentic loop. Default model claude-sonnet-4-5 (ASSISTANT_MODEL overrides). max_tokens 2048, MAX_AGENT_ITERATIONS=8. System prompt instructs the model to prefer direct knowledge and use tools only when necessary.
• src/services/tools.js — 5 tools: list_dir, read_file, grep_repo, list_api_services, query_firestore.
• src/services/repoFs.js — sandboxed FS helpers: allow-list of repo prefixes (docs/, apps/, services/, packages/, tooling/, scripts/, select .github/ subpaths) + specific root files; deny-list (node_modules, .git, .env*, dist, build, coverage, *.pem/*.key, service-account*.json, credentials*.json). Caps: 200 KB read, 100 grep matches, 200 dir entries.

Admin UI — apps/admin/

• src/components/LanternChat/LanternChat.jsx — floating bubble (bottom-right) + slide-up panel. Persists last 30 messages to localStorage (lantern-chat:messages:v1). Page context (useLocation) sent every turn. AbortController for in-flight cancel. Markdown rendering (react-markdown + remark-gfm). 4 starter suggestions.
• src/components/LanternChat/LanternChat.css — 56×56 amber radial-gradient bubble, lantern-glow keyframe pulse (3.2s), 420×640 panel, dark #0f172a surface, amber accent. Tool-call <details> collapsible.
• src/components/LanternChat/index.js
• src/lib/assistantApi.js — sendAssistantChat() via authRequest. URL from VITE_ASSISTANT_API_URL (defaults to /api proxy → http://localhost:8086).

Files Modified

• packages/shared/services/index.js — added assistant-api entry (auto-surfaces in admin API Reference page; CLAUDE.md rule #8).
• package.json — added services/api/assistant workspace; scripts assistant-api:dev, assistant-api:start, assistant-api:test, assistant-api:deploy:dev, logs:assistant-api, logs:assistant-api:prod. Extended apis:dev, apis:kill, kill:ports to include 8086 (also backfilled missing 8081/8084/8085).
• tooling/vscode-extension/src/config.js — Assistant API in PORT_MAP.apis (8086); assistant-api:dev + log scripts in DEV_SERVER_SCRIPTS; INPUT_PROMPTS entries.
• apps/admin/vite.config.mjs — /api/assistant proxy → env.ASSISTANT_API_ORIGIN.
• .env.local.example — added ASSISTANT_API_ORIGIN, VITE_ASSISTANT_API_URL, commented ASSISTANT_MODEL / ASSISTANT_MAX_TOKENS.
• apps/admin/src/components/AdminDashboard.jsx — renders <LanternChat /> for admin users only.

Architecture Notes

• API-first (CLAUDE.md rule #9): new HTTP service, not a Cloud Function.
• Stateless backend: full conversation passed each turn. Server runs the agentic loop, executes tool calls, feeds tool_result blocks back until the model returns a non-tool_use stop_reason.
• Auth model: admin only. Merchant access intentionally deferred to a future phase (different system prompt + tighter tool allow-list expected).
• Rate limit: 30 chat turns / 5 minutes per user (UID-keyed in-memory window — fine for single-instance Cloud Run; replace with Redis if we scale horizontally).
• Repo root resolution: env ASSISTANT_REPO_ROOT → /app/repo-snapshot (production Docker layout) → repo root (dev). The repo-snapshot/ directory must be populated before gcloud run deploy (the deploy script needs to copy a sanitized snapshot — TODO before first deploy).

Verification

• npm install clean ✅
• node --check on all new JS files ✅
• ESLint on all new code: clean (one warning auto-fixed) ✅
• Boot smoke test: /health returns ok with anthropic: false (no key set) ✅; /openapi.json serves spec ✅; POST /assistant/chat without auth → 401 UNAUTHORIZED ✅; with fake bearer → 401 Invalid or expired token ✅.
• npm run build -w apps/admin ✅ (LanternChat included in main bundle).

Outstanding / Future

• Smoke test against real Anthropic: requires ANTHROPIC_API_KEY env. Verify model id claude-sonnet-4-5 resolves; if not, override via ASSISTANT_MODEL.
• Deploy script: needs a step to copy a sanitized repo-snapshot/ (excluding .env*, node_modules, secrets, build artifacts) before gcloud run deploy.
• Merchant assistant: separate system prompt + narrower tool allow-list (no query_firestore cross-tenant; scope read_file/grep_repo to merchant-facing docs).
• Telemetry: log token usage per turn for cost tracking once we go live.
• Persistence: if we ever want cross-device chat history, move localStorage persistence to Firestore under the user's record.