CRM API — Dokumentacja endpointów

Arc OS — The Orchestration System for AI Teams

Informacje ogólne

Uwierzytelnianie

Wszystkie endpointy (poza /docs/*) wymagają tokenu JWT w nagłówku Authorization: Bearer <token>.

Dla połączeń SSE i WebSocket token przekazywany jest przez parametr query ?token=<JWT>.

Błędy autoryzacji

Endpointy według kategorii

Konto i ustawienia

Onboarding + Trial Credits (Phase 50.1)

Onboarding Checklist (Phase 54.1, issue #56)

Post-wizard 5-krokowa lista kontrolna zaangażowania. Każdy krok (workers, cli, skill, bot, issue) przyjmuje status completed lub skipped. Mutacje są idempotentne: ponowny identyczny POST zwraca ten sam stan, nie zapisuje duplikatu w activity_log. Replay nie resetuje stanu, jedynie usuwa dismissed_at — UI ponownie wyświetla panel z tym samym postępem.

SSOT dla metryk lejka (Phase 54.6 / issue #61) — zdarzenia w activity_log (event_type LIKE 'onboarding_%'). Tabela onboarding_progress — derived cache: UI renderuje się jednym zapytaniem zamiast agregacji po zdarzeniach.

Beta Feedback (Phase 53.3)

POST /feedback — walidacja body: type ∈ {bug,feature,other}, title ≤200 znaków, description ≤5000 znaków. Sukces → {ok: true, type, title}. Ping Telegram formatowany jako 🐞/💡/📝 New <type> feedback ... From: <user> Title: <title> + pierwsze 400 znaków opisu.

Pływający widget w FeedbackWidget.jsx (dashboard CRM) automatycznie przekazuje browser (UA + viewport + locale) i project (technical_name aktywnego projektu).

Beta Invites (Phase 52.1, tylko admin)

Aktualizacja flow auth: POST /api/auth/register wymaga teraz pola invite_code (zamknięta beta Phase 52.1). Bez kodu → 403 {error: "invite_required"}. Nieprawidłowy/użyty kod → 403 {error: "invalid_invite"}.

Billing (Phase 51)

Limity planu (semantyka OR):

• Free: 1 projekt AND 5 workerów
• Min ($4.99/mies.): 5 projektów OR 25 workerów łącznie
• Max ($11.99/mies.): 20 projektów OR 150 workerów łącznie

Odpowiedź 402 na POST /onboarding/setup lub POST /projects/:name/workers gdy limit przekroczony: { error: "plan_limit_reached", reason: "projects_limit"|"workers_limit", current, limit, plan, message }

Użytkownicy admin (role=admin) całkowicie pomijają sprawdzanie limitu planu — są operatorami, nie płatnymi tenantami.

Testerzy beta (subscriptions.plan='beta', Phase 52 F&F) również pomijają — nieograniczona liczba projektów/workerów plus wszystkie funkcje Max. Przypisywane ręcznie: UPDATE subscriptions SET plan='beta' WHERE user_id=?.

Bugfix (issue #25): POST /projects/create (Quick Start, Phase 50.2) wcześniej rzucał błąd ownerChatId is not defined przez literówkę — naprawione, aktor audytu jest teraz poprawnie zapisywany.

Bugfix (issue #26): allocatePort() dla nowych projektów sprawdza teraz rzeczywiste powiązania TCP (ss -tln), a nie tylko registry. Wcześniej mógł zwrócić port zajęty przez serwis spoza registry (NotebookLM bridge :19213, internal bridges) → workspace bot padał na EADDRINUSE.

Flow auth (Phase 50.1): /api/auth/register i /api/auth/login zwracają teraz JWT nawet dla niezweryfikowanego emaila + flaga needs_verification: true. Wrażliwe operacje (przyznanie wersji próbnej, billing, kody zaproszenia) sprawdzają email_verified osobno. Rate limit na rejestrację: 3 / IP / 24h.

Projekty (9 endpointów)

POST /projects/create — body:

{
  "technical_name": "string",
  "displayName": "string",
  "description": "string",
  "icon": "string",
  "color": "string"
}

GET /projects/:name/logs — query: category, lines

GET /projects/:name/metrics — query: since, until

Workery (11 endpointów)

POST /projects/:name/workers — body:

{
  "label": "string",
  "icon": "string",
  "type": "terminal | telegram",
  "model": "string",
  "max_turns": 20,
  "tools": ["Read", "Write", "Bash"],
  "system_prompt": "string",
  "focus_dirs": ["src/", "docs/"]
}

max_turns domyślnie 20 (wcześniej było 5, powodowało błąd "Reached max turns" w wieloetapowych dialogach z wywołaniami narzędzi).

POST /projects/:name/restart — query: worker_id

Pliki i przechowywanie (8 endpointów)

GET /projects/:name/files — query: path

GET /projects/:name/files/read — query: path, raw

Skille (18 endpointów)

Skille projektu

Globalny marketplace

Ewolucja i aktualizacje

Forki skilli

Chat i wiadomości

Wiki (4 endpointy)

Analityka (4 endpointy)

Marketplace i Sage (8 endpointów)

Pamięć i wiedza

Dokumentacja (globalna, bez auth)

GET /docs/tree — query: lang (opcjonalny)

• Najpierw szuka docs/public/<lang>/index.md, fallback na docs/public/index.md
• Response zawiera: sections, files, served_lang, is_fallback, requested_lang

GET /docs/file — query: path (wymagany), lang (opcjonalny)

• Kolejność rozwiązywania: docs/public/<lang>/<path> → docs/public/<path> (EN fallback)
• Response zawiera: path, content, size, modified, served_lang, is_fallback, requested_lang
• 403 na path traversal, 404 na brakujący plik
• Phase 52.1.3 — dodano parametr lang dla tłumaczenia UK

System

Kody błędów

GitHub Integration (Phase 49.3)

Obsługiwane zdarzenia: push, pull_request, workflow_run, issues. Powiadomienia kierowane do Telegram właściciela projektu.

Account Security (Phase 45.4)

Bezpieczeństwo

• Multi-tenancy: każdy endpoint :name sprawdza własność przez chatId z JWT
• Walidacja nazwy projektu: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ (max 64 znaki)
• Ochrona przed path traversal: safePath() na wszystkich ścieżkach kontrolowanych przez użytkownika
• Przesyłanie plików: max 100MB, zablokowane rozszerzenia (.exe, .bat, .sh)
• CORS: allowlist origins przez CRM_ALLOWED_ORIGINS
• Ochrona SSRF: allowlist na handleScoutAnalyze — tylko HTTPS + dozwolone hosty
• Endpointy wewnętrzne: odrzucają żądania z nagłówkami proxy (X-Forwarded-For, X-Real-IP)
• Szyfrowanie at-rest (Phase 45): klucze API i wiadomości czatu zaszyfrowane AES-256-GCM
• Nagłówki bezpieczeństwa: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff
• Sanityzacja PII: emaile, klucze API, JWT są automatycznie redagowane z logów JSONL

Phase 53.13 — type-safety baseline (2026-05-10)

Brak zmiany zachowania endpointów — tylko typy wewnętrzne. tsc --noEmit blokuje teraz push/CI:

• Interfejs ChildBot skonsolidowany w shared/routes/_utils.ts (3× duplikaty połączone). bot_username, heartbeat_file, health_endpoint, status stały się opcjonalne — odzwierciedlają runtime-state (wpisy workspace wzbogacone przez DB często ich nie mają).
• requireAdmin() w shared/routes/system.ts zwraca teraz Response | { userId } zamiast { ok, ... } — prostsze zawężanie przez instanceof Response. Zewnętrzne zachowanie (kody 401/403, treści odpowiedzi) niezmienione.
• workers.ts DEFAULT_WORKERS stracił as const (dla zgodności z mutable callsites); parsowanie body dla tools / focus_dirs teraz ściśle przez Array.isArray zamiast ||-fallback.

Phase 53.15 — Sentinel Sprint 1 (2026-05-10)

Zmiany zachowania endpointów auth + admin (Sentinel audit P0 fixes):

• POST /api/auth/login — gdy requires2fa=true, odpowiedź to teraz {requires2fa: true, challenge_token} zamiast {requires2fa: true, userId}. Frontend musi przekazywać challenge_token w kolejnym kroku.
• POST /api/auth/2fa/login — kształt body: {challenge_token, code} zamiast {userId, code}. Token jednorazowy, TTL 5 min. Bez prawidłowego tokenu endpoint zwraca 401 "Invalid or expired challenge — restart login". Rate-limit per userId 5 prób / 15 min → 429.
• POST /api/crm/skills + PUT /api/crm/skills/:id + DELETE /api/crm/skills/:id + POST /api/crm/skill-updates/:id/approve + POST /api/crm/skill-updates/:id/reject — tylko admin. Nie-admin → 403 Forbidden — admin only. Bez auth → 401.
• Rate-limit Nginx na /api/auth/* — 5 req/min/IP (burst=10 nodelay → 429). Tak samo na /api/webhooks/github (30 req/min/IP, burst=20).
• HSTS — nagłówek Strict-Transport-Security: max-age=31536000; includeSubDomains; preload wysyłany jest teraz przy każdej odpowiedzi HTTPS. Żądania HTTP → 301 redirect na HTTPS.
• X-Frame-Options: DENY zamiast SAMEORIGIN.

Phase 53.21 — Sentinel P2 batch 2 (2026-05-12)

• POST /api/crm/feedback — teraz wymaga, aby wywołujący miał dostęp do body.project (sprawdzenie canAccessProject). Nie-właściciel projektu → 403 "Project not accessible". Puste/brakujące project jest nadal dozwolone (globalny feedback).
• POST /api/internal/trial/consume — zmieniony kształt body: {project, owner_id, tokens} zamiast {project, tokens}. owner_id wymagany, weryfikowany względem projects.owner_id w DB. 404 na nieznany projekt, 403 na niezgodność właściciela. Wywołujący (child-bot/claude-runner.ts) propaguje ARC_TRIAL_OWNER env wstrzyknięty przez worker-spawn.ts.

Phase 53.18 — tmux secret-leak fix (2026-05-11)

Brak zmiany zachowania endpointów — tylko refactor wewnętrznych ścieżek spawn.

• POST /api/crm/onboarding/setup (przez shared/routes/onboarding.ts:startWorkspaceBot) — sposób uruchamiania workspace-mode child-bota zmieniony z bash -c "export X='val'; bun run bot.ts" na tmux -e VAR=val ... bun run bot.ts. Wartości tokenów nie trafiają już do /proc/PID/cmdline. Zewnętrznie: 0 zmian (treść odpowiedzi, kody statusu, zachowanie identyczne).

Phase 53.16 — Sentinel Sprint 2 (2026-05-10)

Zmiany zachowania endpointów po hardeningu 13 × P1:

• OAuth callback — Redirect URL używa teraz fragmentu #token= zamiast query ?token= (Sentinel P1-8). Frontend czyta z window.location.hash (z fallback na ?token= przez jeden cykl deploy).
• /api/crm/analytics/activity + /api/crm/analytics/sidebar — query teraz jest ograniczone do owner_id zalogowanego użytkownika. Nie-admin widzi tylko swoje projekty. Wcześniej wyciekały pierwsze 80 znaków każdej wiadomości asystenta + nazwy projektów + IDs workerów wszystkich tenantów (Sentinel P1-4).
• PUT /api/crm/projects/:name/files/save — dodano sprawdzenie isProtectedPath(). .env / CLAUDE.md / .git/* / .claude/* zwracają teraz 403 "Protected path" (wcześniej można było nadpisać) (Sentinel P1-3).
• POST /api/crm/projects/:name/files/mkdir + /files/create — body.name zawierające .., ., /, \ → 400. Ponowne wykonanie safePath() po join() (Sentinel P1-2).
• /ws/local-bridge — chatId z JWT zachowywane przy upgrade. Wiadomość init z project_name nienależącym do użytkownika → close 1008 Forbidden — project not accessible. Wcześniej dowolny użytkownik mógł zainicjować bridge na cudzy projekt (Sentinel P1-5).
• CSP — frontend HTML (przez docker/nginx.conf) wysyła teraz ścisły CSP: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; font-src 'self' data:; connect-src 'self' https://arc-os.co wss://arc-os.co; frame-ancestors 'none'; base-uri 'self'; form-action 'self'. API JSON CSP stracił 'unsafe-inline' (Sentinel P1-10).
• Wewnętrzny helper extractChatId — teraz weryfikuje podpis przez verifyToken przed dekodowaniem (Sentinel P1-6, defense-in-depth dla przyszłych tras skipAuth).
• Zaszyfrowany format klucza odzyskiwania — nowe klucze przechowywane jako v2:<base64-salt>:<payload> (losowy 16-bajtowy salt per klucz). Stare (bez prefiksu v2:) działają przez legacy fallback (Sentinel P1-13).
• CEO_CHAT_ID — teraz env-first (z ostrzeżeniem fallback na bot_registry). Hardcoded 474903718 usunięty z 6 plików (Sentinel P1-14).
• Nginx X-Forwarded-For — nadpisywanie zamiast dołączania we wszystkich 17 callsites (Sentinel P1-11). Helper clientIp czyta OSTATNI segment XFF (Sentinel P1-7).

Phase 55 — Cosmic Editorial login (2026-05-13)

Nowe endpointy dla logowania magic-link:

• POST /api/auth/magic-link/request — body { email }. Generuje jednorazowy token ważny 10 minut w ephemeral_tokens (typ magic_link), wysyła link https://<host>/?magic_token=<token> przez dostawcę email. Anti-enumeration: zawsze 200 OK z treścią { ok: true, message: "If the account exists, a magic link has been sent" } (nawet jeśli email nie istnieje). Rate-limit: 3/min per (IP+email) + 5/10min per email — ten sam kontrakt co forgot-password. Nieudana ścieżka przechodzi timing pad.
• POST /api/auth/magic-link/verify — body { token }. Konsumuje jednorazowy token, zwraca { ok: true, token: <jwt>, userId } przy sukcesie lub 401 "Invalid or expired magic link". Efekt uboczny: user.email_verified = true + aktualizacja last_login (dowód odbioru w skrzynce = weryfikacja).

Union EphemeralTokenType rozszerzony: zawiera teraz "magic_link" obok istniejących oauth_state / password_reset / email_verification / tfa_challenge.

Frontend (CosmicCard.jsx) obsługuje stan magic (60-sekundowy countdown do ponownego wysłania) oraz parametr URL ?magic_token= (auto-consume → login → animacja sukcesu).

Phase 56 — AI Interop / Project Context Export (2026-05-13)

Eksport dostępny tylko dla właściciela — sanitizowany snapshot projektu jako .md do przekazania zewnętrznemu AI (Gemini / ChatGPT / Perplexity / Claude.ai).

• GET /api/crm/projects/:name/context-export — parametry: include=section1,section2,... (sekcje: identity / workers / architecture / issues / activity / commits / learnings; domyślnie wszystkie 7), scanOnly=true|false, activityHours=N (1-720, domyślnie 168), commitLimit=N (1-200, domyślnie 20), issueStatus=open|closed|all. Tylko właściciel — rola admin NIE omija (zgodnie z projektem). Bypass CEO działa. Zwraca { project, exportedAt, filename: "<project>-context-YYYY-MM-DD.md", scanOnly, sections, markdown, findings, stats, alertFired, preferences }. Auto-redaguje krytyczne findings chyba że preferences.auto_redact_critical = false. Wywołania nie-scanOnly zapisują do export_audit_log.
• GET /api/crm/projects/:name/exports — lista audytu (tylko właściciel). Parametry: limit=N (1-200, domyślnie 50). Zwraca { project, exports: [{ id, owner_id, exported_at, sections[], findings_critical/high/medium/low, bytes }] }.
• GET /api/crm/projects/:name/settings/export — odczyt preferencji (tylko właściciel). Zwraca { project_name, always_include_emails, auto_redact_critical, notify_on_export, updated_at }.
• PATCH /api/crm/projects/:name/settings/export — aktualizacja preferencji (tylko właściciel). Body przyjmuje dowolny podzbiór { always_include_emails, auto_redact_critical, notify_on_export } (wartości boolowskie). Zwraca zaktualizowane preferencje.
• GET /api/crm/analytics/exports — zagregowane statystyki (wymagana autoryzacja, brak blokady właściciela — karta analityczna). Parametr: hours=N (1-720, domyślnie 168). Zwraca { total, byProject: [{ project_name, n, last }], severitySums: { critical, high, medium, low } }.

Alert: gdy właściciel przekroczy 3 eksporty w ciągu 24h AND prefs.notify_on_export = true (domyślnie OFF) — logActivity("export_alert", ...) przechodzi przez istniejący pipeline powiadomień TG Phase 53.10 (alertFired: true w treści odpowiedzi).

Multi-tier scanner (shared/secret-scanner.ts) — Tier 1 regex (PATTERN_REGISTRY z sanitizerem PII), Tier 2 entropia Shannona ≥4,5 bitów/znak na ciągach ≥20 znaków, Tier 3 heurystyki kontekstowe (key=/token:/secret=/password=). Allowlist: UUID / git SHA / SHA-256 / powtarzające się znaki / krótki hex / base58 o niskiej entropii. Poziomy ważności (critical/high/medium/low). Wydajność: <500 ms / 1 MB.

Migracja DB 024 — tabele export_audit_log + export_preferences.

Phase 57 — Platform Settings (Sentinel #103 follow-up, 2026-05-15)

Zarządzanie sekretami super-admina przez UI CRM zamiast ssh/edycji-.env/wklejania-na-chacie. Backend MVP (Stage 1 z 4 stages). Wszystkie endpointy bramkowane przez requireAdmin (Phase 53.15) — zwracają 403 Forbidden — admin only dla nie-admina, 401 Unauthorized bez JWT.

• GET /api/crm/platform/settings — zwraca { items: [{ name, label, description, testable, restartTargets[], set, preview, length, lastRotated, lastRotatedBy }] }. Allowlist 9 kluczy (ANTHROPIC_API_KEY, PLATFORM_ANTHROPIC_KEY, GITHUB_CLIENT_ID/SECRET, GOOGLE_CLIENT_ID/SECRET, MASTER_BOT_TOKEN, CITADEL_BOT_TOKEN, RESEND_API_KEY). Redacted preview: prefix(12)…suffix(4) + długość. Pełna wartość nigdy nie opuszcza serwera.
• PUT /api/crm/platform/settings/:name — body { value: string ≥ 8 chars }. Atomowo zapisuje do vault przez storeSecret(name, value) + wiersz audytu. 400 jeśli name nie jest na allowliście; 400 jeśli value < 8 znaków; 500 przy błędzie zapisu vault.
• POST /api/crm/platform/settings/:name/test — weryfikacja względem SaaS API. Anthropic → GET /v1/models z x-api-key; TG → getMe; Resend → /api-keys. Samodzielne sekrety klientów OAuth nie są testowalne → 501. Zwraca { ok: bool, reason?: string, detail?: string }. Timeout 8 sekund przez AbortController.
• POST /api/crm/platform/settings/:name/restart — Bun.spawn(["nohup", "bash", "-c", "sleep 1 && tmux kill-session ... && bash start-*.sh"], { detach: true }) na powiązanych sesjach tmux. Detached aby restart mastera nie zabił odpowiedzi w locie. Zwraca { ok: true, restarted: [sessions], note }.
• GET /api/crm/platform/audit?limit=50&key=ANTHROPIC_API_KEY — ostatnie wpisy logu audytu od najnowszego (limit max 500). Opcjonalny filtr po kluczu.

Lista twardych wykluczeń NEVER_EXPOSE: CRM_SECRET (podpisywanie JWT) + SECRET_ENCRYPTION_KEY (meta-klucz vault) — nawet żądanie admina z prawidłowym tokenem zwraca 400 "not managed". Log audytu tylko do dołączania (brak handlera UPDATE/DELETE), każda akcja (wliczając nieudane) zapisuje wiersz z IP + UA + email.

Migracja DB 026 — tabela platform_audit_log. Stage 2 (frontend PlatformSettings.jsx) — dostarczony 2026-05-15 (cbc8bac): siatka kart tylko dla adminów + modal rotacji (<input type="password"> + potwierdzenie przez powtórzenie) + szuflada audytu; wpis w sidebarze filtrowany przez userRole === "admin" pobierany z /api/auth/me.

Polish (2026-05-15, commit 56191b0) — Restrukturyzacja UI Platform Settings. Elementy odpowiedzi GET /api/crm/platform/settings zyskują 5 nowych pól: category (anthropic|oauth|telegram|email), usedIn (string[] — pliki/przepływy korzystające z klucza), getFromUrl (skąd pobrać nową wartość), effectAfterRotate, riskIfLeaked. Używane przez frontend do renderowania 4 pogrupowanych sekcji kart + zwijany panel pomocy per karta ze strukturalnym kontekstem (Used in / Get from / Effect / Risk). Brak zmian behawioralnych endpointów mutujących (PUT/POST/restart/test).

Refactor (2026-05-16) — wewnętrzne porządki shared/routes/platform.ts. Usunięto 39 linii (dodano 16), brak zmian w publicznym API. Sygnatury i odpowiedzi endpointów PUT/POST/restart/test/audit niezmienione. Udokumentowane tutaj tylko dlatego, że pre-push gate doc-coverage wyzwala na każdym diffie shared/routes/*.ts.

Backdated activity (#117, 2026-05-16) — POST /api/mcp/issues/:project/:id/log akceptuje teraz opcjonalne pole ts (ciąg ISO-8601). Używane przez arc retro do rekonstrukcji historycznych wpisów z ich oryginalnymi znacznikami czasu. Wartości z przyszłości są po cichu obcinane do teraz wewnątrz addActivity() (ochrona przed grubymi palcami). Nieprawidłowy ISO → 400.

Stage 3 (2026-05-15) — hot-reload sekretów OAuth + Resend bez restartu. shared/auth.ts loadOAuthConfig() teraz czyta getSecret("GITHUB_CLIENT_ID/SECRET" | "GOOGLE_CLIENT_ID/SECRET") per wywołanie zamiast process.env. Callsites w master-bot/routes/auth.ts już wywoływały getOAuthConfig() per żądanie → 0 zmian callsites. RESEND_API_KEY już hot-reload przez shared/email.ts:47. Zmiana behawioralna: PUT /api/crm/platform/settings/{GITHUB_CLIENT_ID|GITHUB_CLIENT_SECRET|GOOGLE_CLIENT_ID|GOOGLE_CLIENT_SECRET|RESEND_API_KEY} wchodzi teraz w życie od następnego żądania, nie wymaga restartu. restartTargets dla tych 5 kluczy jest pusty → przycisk Restart w UI jest ukryty. Edge case: flow OAuth z state-tokenem wydanym przed rotacją może otrzymać 400 na callbacku przy wymianie kodu — ponowna próba użytkownika rozwiązuje problem. ANTHROPIC_API_KEY, PLATFORM_ANTHROPIC_KEY, MASTER_BOT_TOKEN, CITADEL_BOT_TOKEN pozostają wymagające restartu (czytane przy spawn child-bota / inicjalizacji TG long-poll).

Phase 57.3.5 cleanup (2026-05-16) — allowlist MANAGED_KEYS skrócony z 9 do 6. Usunięto: ANTHROPIC_API_KEY (operatorzy używają teraz jednego PLATFORM_ANTHROPIC_KEY zarówno dla trial-credits jak i platform inference; fallback .env nadal działa dla starszych ścieżek kodu dopóki Sage/Karpathy nie zmigrują), CITADEL_BOT_TOKEN (bot per-projekt należy do wpisów vault child:<name>:token, zarządzanych przez flow onboardingu workera — nie Platform Settings). MASTER_BOT_TOKEN zmienił przeznaczenie: label → "Telegram — System Monitor Bot", description → "Server health alerts + on-demand status probes (admin-only, not a chat bot)". Phase 58 doda pętlę monitorowania (alerty push dla crashu workera / dysku / RAM / brute-force SSH / bypass CF + polecenia /status, /health, /errors, /restart). Finalny zestaw: PLATFORM_ANTHROPIC_KEY + GITHUB×2 + GOOGLE×2 + MASTER_BOT_TOKEN + RESEND_API_KEY (refs #103).

Phase 63 — Konsolidacja UI/UX + Śledzenie zużycia tokenów (2026-05-21, #148)

Nowy endpoint:

• POST /api/internal/usage/log (tylko loopback) — zapisuje wiersz do token_usage_log. Body: { project_name, owner_id, worker_id?, input_tokens, output_tokens, cache_tokens, total_tokens }. Wywoływany z child-bot/bot.ts jako fire-and-forget po każdym wywołaniu Claude (callClaudeOnce + callWorker text path). Nie wymaga nagłówka auth — /api/internal/* dostępny tylko z localhost i blokowany przez nginx dla zewnętrznych żądań.
• GET /api/crm/account/usage — historia zużycia tokenów dla autoryzowanego użytkownika (opisana w tabeli Onboarding powyżej).

Zmiany w claude-runner.ts:

• callClaudeOnce + callWorker text path: teraz zawsze --output-format json (wcześniej text dla non-trial). Parse JSON wyodrębnia result jako tekst wyjściowy i usage do logowania. Przepływ trial consume bez zmian.
• Nowy dep logUsage? w ClaudeRunnerDeps — callback (workerId, { input, output, cache }) => void.

Zmiany UI (nie API):

• UserDropdown: komponent UsageCard z całkowitą liczbą tokenów + „Details →" przy otwieraniu; kropka ostrzeżenia na awatarze gdy saldo trial < 20%.
• BillingPage: sekcja Token Usage z paskiem sumy + tabela 50 wierszy. Plan Enterprise (w opracowaniu). Toggle details na każdej karcie.
• OnboardingProgressPill: przeprojektowany jako inline dropdown w nagłówku (nie ma już wizard modal).
• WorkerSelector: semantyczne zmienne CSS --worker-{role} zamiast tokenów Tailwind chart.