# Roadmap — Chat Switchboard **See also:** - [ARCHITECTURE.md](ARCHITECTURE.md) — Core services design, store layer, scope model - [EXTENSIONS.md](EXTENSIONS.md) — Extension system spec (Browser/Starlark/Sidecar tiers, manifests, browser tool bridge, surfaces/modes, model roles) - [EXTENSION-SURFACES.md](EXTENSION-SURFACES.md) — Extension surface authoring guide (manifest format, platform API, CSS properties, install workflow) - [CHANGELOG.md](../CHANGELOG.md) — Detailed release notes for all completed versions **Versioning (pre-1.0):** `0..` — hotfixes use quad: `0.x.y.z` No compatibility guarantees before 1.0. --- ## Dependency Graph Two parallel implementation tracks converge at v0.50.0 (MVP). The extension track builds the package ecosystem and workflow capabilities. The operations track builds production readiness for multi-team deployment. Neither blocks the other until the MVP gate. ``` v0.9.x–v0.28.7 Foundation through Platform Polish ✅ (see CHANGELOG.md for full history) │ v0.28.8 ICD Green Board ✅ │ ┌───────────────┴───────────────┐ │ │ Extension Track Operations Track │ │ v0.29.0 Starlark Sandbox ✅ v0.32.0 Multi-Replica HA v0.29.1 API Extensions v0.33.0 Observability v0.29.2 DB Extensions v0.34.0 Data Portability v0.29.3 Workflow Forms │ v0.30.0 Package Lifecycle │ v0.30.1 SDK Adoption │ v0.30.2 Workflow Packages │ v0.31.0 Editor Package │ │ │ ══════╪═══════════════════════════════╪══════ │ MVP v0.50.0 │ │ (v0.31.0 + v0.34.0 │ │ + mobile + deployment docs) │ ══════╪═══════════════════════════════╪══════ │ v0.50.0+ Rich Media + Beyond (image gen, code sandbox, STT/TTS, desktop app) ``` ## Completed: v0.28.0 — Platform Polish Audit arc, frontend decomposition, security, infrastructure. Eight sub-versions, all complete. See CHANGELOG.md for detailed release notes. | Version | Summary | Key Deliverables | |---------|---------|------------------| | v0.28.1 | Surfaces ICD Audit ✅ | 6 ICD fixes, 19 E2E tests, 36 Go tests | | v0.28.2 | ICD Audit: All Domains ✅ | 469/469 (100%), full methodology documented | | v0.28.3 | ICD Close-out + FE Decomp ✅ | WebSocket ICD rewrite, 47 JS files → ES modules, `sb.js` registry | | v0.28.4 | Security Tier ✅ | 58 red-team tests, 5 real bugs found+fixed, JWT role from DB | | v0.28.5 | Frontend SDK + Pipes ✅ | `switchboard-sdk.js`, 3-stage pipe/filter pipeline, 36 SDK tests | | v0.28.6 | Infrastructure ✅ | Virtual scroll, Helm chart, system tasks, git keygen, broadcast | | v0.28.7 | Unified Packaging ✅ | `.pkg` format, `packages` table, task RBAC, `task.starlark` gate | **Deferred from v0.28.x (relocated with version pins):** - `sw.notes()` factory → v0.30.1 - Phase 5 FE decomp (`import`/`export`) → v0.30.1 - Cross-visitor isolation E2E test → v0.29.3 - Admin UI task permission management → v0.29.0 - ICD runner packaging test tier → v0.29.0 --- ## v0.28.8 — ICD Green Board ✅ Close out pre-existing ICD test failures and infrastructure issues discovered during the green board push. Depends on: v0.28.7 (unified packaging). **Root cause analysis (discovered during deployment):** The 502/503 cascade that failed 8–10 ICD tests across provider, BYOK, and SDK tiers was caused by **OOMKilled** — the dev backend pod had a 256Mi memory limit. The Go process peaked at ~216Mi during the 569-test ICD suite and exceeded 256Mi during SSE completion streams, triggering exit code 137. Traefik returned `503 no available server` until the pod restarted (~15s). Memory profile (measured on cluster via `kubectl top`): - 17Mi idle after fresh start - 216Mi peak during full ICD suite (569 requests, SSE streams) - 60Mi post-test (Go GC ran, heap arena retained) - 34Mi settled (~3 min, OS reclaimed freed pages via MADV_DONTNEED) - Zero leak — memory returns to baseline, flat steady state **Infrastructure fixes:** - [x] Backend memory limits: dev/test 128Mi/256Mi → 256Mi/512Mi - [x] Batched `UpsertFromSync`: single transaction, prepared `INSERT ON CONFLICT DO UPDATE` (300 round-trips → 2, PG + SQLite) - [x] DB connection lifecycle: `SetConnMaxLifetime(5m)` + `SetConnMaxIdleTime(1m)` - [x] HTTP transport pool: `sync.Map` keyed by proxy config - [x] Provider sync timeout: `context.WithTimeout(30s)`, 504 on timeout - [x] ICD runner: `apiPostRetry`, environment-aware CORS test, ticket exchange verification test **Security transport:** - [x] CORS startup warning, `GetAllowedOrigins()`, WebSocket `CheckOrigin` - [x] WebSocket ticket exchange: `POST /api/v1/ws/ticket`, `WsAuth` middleware, `TicketStore` with TTL reaper - [x] `events.js` async ticket-first auth with legacy fallback **Kubernetes:** - [x] Traefik retry `Middleware` CRD + Helm template - [x] RBAC for Gitea runner → `traefik.io` middleware resources - [x] CI non-fatal middleware apply with post-success ingress annotation --- ## Extension Track Sequential. Each version builds on the previous. Delivers the package ecosystem, workflow capabilities, and SDK-based surface architecture. ### v0.29.0 — Starlark Sandbox + Permission Model ✅ Server-side extension runtime. Eval loop, permission pipeline, pre-completion filter chain, and admin review workflow. Depends on: v0.28.8. **Phase 0 — Store cleanup (prerequisite): ✅** - [x] Raw SQL hunt: all ~242 `database.DB.*` calls outside `store/` migrated to store interface methods (CS0–CS7b, 12 changesets) - [x] CI green on both PG and SQLite pipelines - [x] ICD runner: 579/580 pass, 1 expected skip - [x] Documented exception: `events/pg_broadcast.go` (`pg_notify`, PG-only, no store abstraction needed) **Phase 1 — Starlark runtime: ✅** - [x] Pre-completion filter chain: composable `PreCompletionFilter` interface + `Chain` registry. KB auto-inject refactored as first built-in filter. Extension filters register at order 100+ (CS0) - [x] `go.starlark.net` integration: sandboxed eval with step limits (1M ops default), context timeout, captured print output, disabled `load()`. `MakeModule` helper for Go→Starlark (CS1) - [x] Permission model: `extension_permissions` table (in 016), `status` column on `packages` (`active`/`pending_review`/ `suspended`). Manifest `"permissions"` array parsed on install. Admin review, grant, revoke, grant-all endpoints (CS2) - [x] Runtime enforcement: `Runner.buildModules()` injects only granted modules into sandbox namespace (CS3) - [x] Extension lifecycle: `install → pending_review → grant-all → active`, revoke → `suspended`. Auto-transitions on grant/revoke. - [x] Initial modules: `secrets` (GlobalConfig-backed, per-package key-value store, admin CRUD), `notifications` (wraps notification service, `send(user_id, title, body?, type?)`) (CS3) - [x] `task_type: "starlark"`: executor `executeStarlark` loads package by ID, calls `on_run()` entry point via runner. RBAC gate `task.starlark` enforced. `system_function` field holds package ID (CS4) - [x] KB auto-injection: server-side pre-completion filter chain. Reference implementation for the filter model Starlark extensions mirror via `on_pre_completion(ctx)` (CS0+CS3) - [x] Starlark filter discovery: `DiscoverStarlarkFilters` scans active packages with `filters.pre_completion` grant (CS3) - [x] ICD runner: `packaging` test tier — 18 tests covering permission lifecycle + secrets CRUD (CS5) ### v0.29.1 — API Extensions Starlark route handlers. Surfaces serve custom JSON endpoints. Depends on: v0.29.0. - [ ] `api_routes` manifest key, mounted at `/s/{id}/api/...` - [ ] Starlark request/response primitives - [ ] `http` outbound module with allowlist/blocklist - [ ] `requires_provider` manifest key (provider resolution via BYOK chain) - [ ] Server-side tool execution in completion handler - [ ] `capability_match` routing policy (cheapest model with required caps) - [ ] Config-file provider types (YAML/JSON, no code deploy) ### v0.29.2 — DB Extensions Namespaced tables for extension data. Create-only (no migrations yet). Depends on: v0.29.1. - [ ] `ext_{id}_*` tables, dialect-correct DDL (PG + SQLite) - [ ] `db` Starlark module: `query()`, `exec()` scoped to extension tables - [ ] Views as read contract over platform tables (column allowlist) - [ ] Schema creation on install, drop on uninstall ### v0.29.3 — Workflow Forms `form_template` renders as real UI. LLM is optional for data collection. Depends on: v0.29.2, v0.29.0 (Starlark validators). - [ ] Typed `form_template` schema (`text`, `email`, `select`, `number`, `date`, `textarea`, `checkbox`, `file`) with validation rules - [ ] Stage renders as form when `form_template` has typed fields - [ ] LLM-optional stages: form-only, form+chat, chat-only - [ ] Starlark `validate` / `on_submit` hooks - [ ] Visitor form entry (branded page, no chat widget) - [ ] Form builder in workflow admin (visual field editor) - [ ] Cross-visitor isolation E2E test (deferred from v0.28.4) ### v0.30.0 — Package Lifecycle Lifecycle sophistication for `.pkg` format. Depends on: v0.29.2. - [ ] Schema versioning + migrations in manifest - [ ] Settings extension point (packages declare settings sections) - [ ] Export/import format for cross-instance sharing - [ ] Package marketplace (discovery, not hosting) - [ ] User-installable packages (RBAC-gated, team/personal scope) ### v0.30.1 — SDK Adoption Migrate core surfaces to `sw.*` SDK. Depends on: v0.28.5, v0.30.0. - [ ] `sw.notes()`, `sw.chat()`, `sw.panels()` real factories - [ ] Core surface migration: chat, editor, notes, settings - [ ] Phase 5 FE decomp: `import`/`export` statements - [ ] Memory compaction: summarize, confidence decay, prune ### v0.30.2 — Workflow Packages Workflows as installable packages. Visual builder for team admins. Depends on: v0.29.3, v0.30.0, v0.30.1. - [ ] Stage surfaces: form, chat, review, custom `.pkg` - [ ] `.pkg` type `"workflow"` bundles definition + surfaces + handlers - [ ] Team admin workflow builder (visual, no JSON editing) - [ ] `sw.workflow` SDK namespace ### v0.31.0 — Editor Package E2E proof: rebuild editor as installable `.pkg`. Zero platform special-casing. Validates the full v0.28.7–v0.30.2 stack. Depends on: v0.30.2. - [ ] Editor `.pkg` (type: `full`), settings via extension point - [ ] State persistence via `ext_editor_*` tables - [ ] Remove editor from core (`surface-editor` template, data loader) --- ## Operations Track Parallel to extension track. No Starlark dependency. Delivers production readiness for the target multi-team deployment. ### v0.32.0 — Multi-Replica HA Run 2–3 backend replicas across nodes for node-level availability. Depends on: v0.28.8. **What already works multi-replica:** - REST API (stateless, JWT auth) ✅ - PG + S3 + CephFS (shared infrastructure) ✅ - `pg_broadcast` LISTEN/NOTIFY (cross-pod event bus) ✅ **What needs work:** - [ ] WebSocket fan-out: wire `Bus.Subscribe` to `pg_broadcast` listener so events from other pods reach local WebSocket connections. LISTEN/NOTIFY plumbing exists — bridge inbound NOTIFY into per-pod hub for local delivery. - [ ] Task scheduler leader election: Kubernetes `Lease`-based. Only leader runs cron scheduler. Prevents duplicate execution. - [ ] Shared ticket store: `TicketStore` from `sync.Map` → PG table with 30s TTL. Ensures WS ticket from pod-1 validates on pod-2. - [ ] Shared rate limiter: in-memory → PG or Redis counter. Without this, effective rate limit = N × configured across N replicas. - [ ] Health check refinement: readiness probe fails fast on PG connection loss. - [ ] Helm: `backend.replicaCount` > 1 tested. Pod anti-affinity to spread across nodes. **Sizing (measured on v0.28.8):** | Metric | Value | |--------|-------| | Idle memory | 17Mi | | Peak (569 reqs, 4 users, SSE) | 216Mi | | Settled after GC | 34Mi | | Per-SSE stream | ~500KB–1MB | | Per-WebSocket | ~64KB | | DB pool | 25 max (shared) | ### v0.33.0 — Observability Metrics, dashboards, alerting. Operate the platform without reading Go source code. Depends on: v0.32.0 (multi-replica metrics aggregation). - [ ] Prometheus `/metrics` endpoint: request latency, active WebSocket gauge, completion token counters, DB pool stats, provider health - [ ] Grafana dashboard template: system overview, per-team usage, provider latency, error rates - [ ] Structured logging: `LOG_FORMAT=json`, request ID propagation, correlation IDs in completion chains - [ ] Alerting rules: OOM recovery, provider down, pool exhaustion, task failure rate - [ ] Admin dashboard surface: real-time health (built-in, no Grafana) ### v0.34.0 — Data Portability Export, import, backup, compliance. Depends on: v0.29.2 (DB extensions — extension data in exports). - [ ] Bulk export/import: account data, conversations, settings, files - [ ] GDPR "download my data" + "delete my data" (cascade + audit trail) - [ ] ChatGPT/other tool import (conversation format mapping) - [ ] Backup/restore CronJob manifests for K8s - [ ] Admin export: team/user config (excludes vault-encrypted keys) --- ## MVP v0.50.0 **Gate:** deploy for 5–10 teams, ~50 users, 100+ anonymous visitors on a 3-node cluster. An IT team can operate the platform without reading Go source code. Team admins build workflows visually. **Requires all of:** - Extension track through v0.31.0 (full package ecosystem, visual workflow builder, SDK-based surfaces, editor package proving E2E) - Operations track through v0.34.0 (multi-replica HA, observability, data portability) **Additionally requires:** - [ ] Deployment guide: step-by-step for IT team (PG cluster, S3/MinIO, CephFS/NFS, Helm install, TLS, OIDC) - [ ] Admin guide: team setup, provider config, workflow creation, package management, backup/restore - [ ] Mobile-responsive layouts (proper mobile navigation, touch-optimized chat, not just CSS responsive) - [ ] Project creation dialog (replace `prompt()` with modal) - [ ] Admin-level project management (cross-instance visibility) --- ## v0.50.0+ — Rich Media + Beyond Post-MVP. Each item is a standalone `.pkg` or platform primitive. No ordering constraints between items. **Media + Generation** - Image generation tool (browser or sidecar, provider-agnostic) - STT input (browser extension, Web Speech API) - TTS output (browser extension, provider API) - Code execution sandbox (server-side, container isolation) **Desktop + Mobile** - Desktop app (Tauri — native wrapper around existing web UI) - Full PWA with offline capability **Platform** - Multi-tenant SaaS mode (tenant isolation, billing, onboarding) - Surface IDE (built-in surface for building surfaces) - Sidecar HTTP tool protocol (container-isolated tool execution) - Latency-aware provider routing (response time percentiles) - Cost-aware routing with budget ceiling per request - Fallback chain visualizer (drag-to-reorder provider priority) **Knowledge + Memory** - Hybrid KB search (vector + `tsvector` + re-rank) - Semantic chunking (embedding-based boundary detection) - HNSW index (replaces IVFFlat for large datasets) - Web scraping KB source (ingest URLs via `url_fetch`) - Scheduled re-indexing (periodic rebuild when sources update) - Memory export/import (portable format across instances) - Cross-persona memory sharing (opt-in) - Memory analytics dashboard **Projects** - `/p/:id` shared project view - Project-specific file uploads (own endpoint, storage path) - Project templates (predefined configurations) - Sub-projects / nested hierarchy **UX** - "Group" scope badge on model selector / KB list - Article drag-to-reorder outline sections - Article AI tools (suggest_outline, expand_section, check_citations) - Rate limiting per user/team/tier (token budgets)