Web UI & REST API

The Flask app serves the console pages and a JSON/SSE REST API. Page routes live in routes_pages.py; the query stream in routes_query.py; workspaces/usage in routes_workspaces.py; the file explorer in routes_files.py; guest tokens in guests.py (+ management routes in routes_status.py).

Pages

Main page layout (templates/index.html)

Header: theme/font-size controls, Direct vs Agent toggle, agent-mode selector (explore / plan / write_test / write_no_test; index.html:49-64), links to Vision/Video/Help/Wiki, temperature slider, API-token input (only when API_TOKEN is set), server Start/Stop/Restart (via the supervisor on :5001, hidden when remote), role + guest-quota badges.

Workspace bar (index.html:139-204): workspace dropdown + tree picker, New/Subdir buttons, collapsible stats panel, and the voice header control (status dot, connect button, STS model/voice/verbosity selects, timer, cost readout).

Main area is a 4-column grid (<main class="app-main">, index.html:209):

1. Model column (app-col-models, index.html:212) — model list card, description, per-model prompt options.
2. Prompt column (app-col-prompt, index.html:280) — prompt textarea, drop zone, voice wake chip + cheat-sheet popover, dictation panel.
3. Response column (app-col-response, index.html:472) — streamed output, run stats, approval/question cards.
4. Console column (app-col-console, index.html:576) — tabbed capability console (below).

Hidden auxiliary columns: voice-commands column (app-col-voice, index.html:262), tool/skill runner columns (toolRunCol/skillRunCol, index.html:984,995), and the trace-analysis aside (traceAnalysisPanel, index.html:1065).

Console tabs

data-tab buttons at index.html:579-588: Tools (enable for agent runs / run directly), Sites (registered sites, ports, dev→beta→prod staging), Memory (STM/MTM/LTM recall + remember), Skills (browse/execute), Files (workspace explorer), Usage (per-project costs, per-query drill-down), Audio (provider TTS/STT/STS settings, personas, cloning, spend), Status (harness health/cost + guest-token management), History (completed runs).

Query API + SSE event stream

POST /api/query (routes_query.py:212) — body fields: prompt (required), model, use_agent, agent_type (react/planner/reflective), tools, temperature, session_id, mode (explore/plan/write_test/write_no_test; invalid → explore; forced to explore when the active workspace is the app's own source tree, routes_query.py:230), auto_confirm, images (≤4 data-URLs, ≤10 MB total), context_files (≤20 workspace-relative text files, 200 KB total, 20 KB kept per file, routes_query.py:97-101), reasoning_effort, thinking, memory_recall, max_steps (default 60), max_time_sec (0 = unlimited).

Response: text/event-stream with SSE_HEADERS (Cache-Control: no-cache, X-Accel-Buffering: no, Connection: keep-alive, streaming.py:109). Wire format: data: {"event": <name>, "data": <payload>}\n\n (streaming.py:38-46).

SSE event types

Related endpoints: POST /api/permissions/respond ({request_id, approved} or {request_id, answer}, routes_query.py:356); POST /api/agent/auto-approve flips auto_confirm_tools on a live run (404 when none, routes_query.py:380); POST /api/agent/instruct queues a mid-run instruction (routes_query.py:402); POST /api/agent/continue resumes a capped run from its persisted message history as a fresh SSE stream (routes_query.py:426). Plan-mode runs persist output to Plan-N.md in the workspace root (routes_query.py:71-89).

Workspaces + usage stats

A workspace is any subdirectory of the workspaces root (WORKSPACE_DIR env, else <parent of data dir>/workspace, routes_workspaces.py:57). Activation calls set_workspace_root() and persists to <DATA_DIR>/active_workspace.json (routes_workspaces.py:405).

Every finished query (direct, agent, or audio) appends one JSONL record to <DATA_DIR>/workspace_stats/<slug>.jsonl via record_workspace_stats() (routes_workspaces.py:112). Keys: workspace rel path, or project:<name> for a registered projects.json root (_usage_rel_for, routes_workspaces.py:83).

• GET /api/workspaces — list with per-workspace stat summaries + active marker (routes_workspaces.py:297).
• GET /api/workspaces/tree?depth=1..5 — picker tree; skips hidden/noise dirs (.git, node_modules, …), 500-node cap (routes_workspaces.py:333).
• POST /api/workspaces/create / POST /api/workspaces/activate — create under root / activate (routes_workspaces.py:384, 405).
• GET /api/workspaces/stats?workspace= — aggregate totals: queries, tokens, cost, elapsed, per-model breakdown, skilldag injections, audio bucket, first/last activity (_aggregate_stats, routes_workspaces.py:147).
• GET /api/workspaces/usage?workspace=&limit=&offset= — aggregate + by_provider breakdown + newest-first page of raw records (≤500 per page) (routes_workspaces.py:445).
• GET /api/workspaces/usage/export?workspace= — writes the full log as TSV to <project>/docs/costs/usage-<slug>-<timestamp>.tsv; columns _EXPORT_COLUMNS (routes_workspaces.py:476): ts, workspace, mode, kind, provider, model, temperature, thinking, reasoning_effort, prompt/completion/cached/total tokens, cost_usd, elapsed_s, skilldag_chars, audio_chars/seconds, prompt, response (tabs/newlines sanitized, routes_workspaces.py:485).
• GET /api/projects, POST /api/projects/activate — registered Kucatoo-Sites projects only (never arbitrary paths); the app's own tree is flagged self and locks agent mode to explore (routes_workspaces.py:529-598).

Files API (routes_files.py)

All paths are resolved inside the active workspace via resolve_path() — traversal is rejected (routes_files.py:43). .git, venv, .venv, __pycache__, node_modules, .kucatoo_backups are excluded from listings/zips/backups (routes_files.py:34).

• GET /api/files/list?path=&show_hidden= — directory entries (dirs first).
• GET /api/files/read?path= — UTF-8 text ≤512 KB; images return {kind: "image", url} instead (routes_files.py:148).
• GET /api/files/image?path= — serves an image after PIL verification.
• POST /api/files/write — overwrite with automatic pre-write snapshot into .kucatoo_backups/<id>/ (routes_files.py:179, 88).
• POST /api/files/mkdir, POST /api/files/delete ({paths: []}), POST /api/files/upload (multipart, filenames stripped to basename).
• POST /api/files/zip ({paths}, ≤100) — zip download.
• POST /api/files/backup, GET /api/files/backups?path=, POST /api/files/restore — manual snapshots; restore snapshots current state first (routes_files.py:369-395).
• POST /api/files/gitignore — {action: add|remove, paths} edits the workspace .gitignore.

Guest tokens

guests.py is a SQLite store at <DATA_DIR>/guests.db, one guest_tokens table, no ORM (guests.py:21-33). Tokens are 32-byte urlsafe random strings with primary-key exact lookup (no enumeration). Defaults (env-overridable): GUEST_DEFAULT_DAYS=2, GUEST_DEFAULT_QUERIES=10, GUEST_DEFAULT_TOKENS=50000 (guests.py:76-86). GUEST_MODELS (default deepseek-v4-flash,glm-5.2) is the guest model allowlist (guests.py:195).

Enforcement path:

• Role resolution owner > token > guest in auth.resolve_role(); a presented guest token yields g.user_role="guest" + g.guest_record (auth.py:142-160).
• Guests get 403 guest_forbidden on /api/vision and /api/video prefixes (GUEST_BLOCKED_PREFIXES, auth.py:46), and 403 on voice chat (/api/audio/voice-key, routes_audio.py:424-426).
• /api/query gates: model allowlist (400 listing allowed models), quota check → 429 {event:"error", data:"quota_exceeded", usage}, then record_query() per accepted query and record_tokens() at stream done (routes_query.py:268-286, 812, 1124).
• Guests are sandboxed to <workspace>/guests/<token-prefix>/ via guest_scoped_root (auth.py:18-21).

Management (owner/token role, routes_status.py:156-184): GET /api/guests lists all tokens with computed expired flag; POST /api/guests mints one ({label, days, max_queries, max_tokens}) and returns the share link <host>/?token=<token>; POST /api/guests/<token>/revoke revokes (idempotent).

Full REST route table

The table below is generated by scripts/wiki_tables.py — do not hand-edit; re-run the script to refresh.

<!-- AUTO:routes -->

verified against code: 2026-08-09