Jeffrey Smith
8fee53e440
Co-authored-by: Jeffrey Smith <jasafpro@gmail.com> Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>
409 lines
17 KiB
Markdown
409 lines
17 KiB
Markdown
# 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.<major>.<minor>` — 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.
|
||
|
||
- [x] `api_routes` manifest key, mounted at `/s/{id}/api/...`
|
||
- [x] Starlark request/response primitives
|
||
- [x] `http` outbound module with allowlist/blocklist
|
||
- [x] `requires_provider` manifest key (provider resolution via BYOK chain)
|
||
- [x] `capability_match` routing policy (cheapest model with required caps)
|
||
- [x] Config-file provider types (JSON, no code deploy)
|
||
|
||
**Deferred to v0.29.2:**
|
||
- Server-side tool execution in completion handler (requires tool
|
||
registry integration with sandbox; aligns with DB extensions scope)
|
||
|
||
### v0.29.2 — DB Extensions ✅
|
||
|
||
Namespaced tables for extension data. Structured API, not raw SQL.
|
||
Server-side tool execution (deferred from v0.29.1) included.
|
||
|
||
Depends on: v0.29.1.
|
||
|
||
- [x] `ext_{id}_*` tables, dialect-correct DDL (PG + SQLite)
|
||
- [x] `db` Starlark module: structured `query/insert/update/delete/list_tables/view`
|
||
(structured API instead of raw `exec()` — prevents SQL injection)
|
||
- [x] Views as read contract over platform tables (`ext_view_users`, `ext_view_channels`)
|
||
- [x] Schema creation on install, drop on uninstall
|
||
- [x] Server-side tool execution in completion handler (deferred from v0.29.1)
|
||
|
||
### 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).
|
||
|
||
- [x] Typed `form_template` schema (`text`, `email`, `select`, `number`,
|
||
`date`, `textarea`, `checkbox`, `file`) with validation rules
|
||
- [x] Stage renders as form when `form_template` has typed fields
|
||
- [x] LLM-optional stages: form-only, form+chat, chat-only
|
||
- [x] Starlark `validate` / `on_submit` hooks
|
||
- [x] Visitor form entry (branded page, no chat widget)
|
||
- [x] Form builder in workflow admin (visual field editor)
|
||
- [x] 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.
|
||
|
||
- [x] Schema versioning + migrations in manifest
|
||
- [x] Settings extension point (packages declare settings sections)
|
||
- [x] Export/import format for cross-instance sharing
|
||
- [x] Package marketplace (discovery, not hosting)
|
||
- [x] 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.
|
||
|
||
- [x] `sw.notes()`, `sw.chat()`, `sw.panels()` real factories
|
||
- [x] Core surface migration: chat, editor, notes, settings
|
||
- [x] Phase 5 FE decomp: `import`/`export` statements
|
||
- [x] 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)
|