v0.10

# v0.10 — Vexa goes cloud-native

**The biggest refactor ever.** v0.9 was a bot that joined meetings. v0.10 is a **cloud-native agent platform** where meeting bots are one workload type among many. From single-container all-in-one → first-class Kubernetes, scalable horizontally, with a general-purpose agent runtime on top.

723 commits · 1014 files changed · +142k / −44k lines.

---

## The new architecture

### Two-layer model: runtime + applications

v0.10 introduces a clean two-layer split that didn't exist before:

```
                 ┌──────────────┐  ┌────────────┐
  applications   │  meeting-api │  │ agent-api  │   … future workloads
                 └──────┬───────┘  └─────┬──────┘
                        │                │
                 ┌──────▼────────────────▼──────┐
  orchestration  │          runtime-api          │
                 │  process | docker | kubernetes │
                 └────────────────────────────────┘
```

**`runtime-api`** is the new lower-level primitive. Pluggable orchestrator backends: `process` (local dev), `docker` (compose / single-VM), `kubernetes` (LKE / any K8s). One scheduler, many workloads. Both meeting bots AND AI agents run on top of it.

**`meeting-api`** (application) — meeting bot orchestration, transcription aggregation, webhooks, recording pipeline. Asks runtime-api to spawn bot containers; owns meeting state.

**`agent-api`** (application, net-new) — general-purpose agent platform. Runs Claude Code / Codex / any AI agent sandboxed in containers, scaled by runtime-api. Workspace persistence, container isolation. Use cases span real-time meeting support, post-meeting AI processing, and anything else you'd want a containerized agent to do — **not limited to meeting intelligence.** This is the foundation for Vexa as an agent platform.

### Browser sessions on demand

New **`browser-session`** profile on runtime-api: on-demand Chromium containers with Playwright-connected CDP (Chrome DevTools Protocol). Any agent can request a browser, drive it programmatically, and the runtime tears it down when done. Powers interactive bots (authenticated login flows, web automation from agents) that couldn't exist before.

### WhisperLive retired

The separate `whisperlive` service is gone. Real-time audio buffering moved **into `vexa-bot`** directly. One less hop, one less service to deploy, simpler pod topology on K8s. The transcription backend (remote Fireworks / local faster-whisper) is now selected via `TRANSCRIPTION_SERVICE_URL` from inside the bot container.

### Kubernetes / Helm — first class

Previously helm was "experimental". v0.10 makes it the production-grade path:

- `deploy/helm/charts/vexa/` — full chart, 30+ templates, per-service deployments, StatefulSets for postgres/minio, PVCs, RBAC, ingress, PDB, priority class.
- Production-tuned `values.yaml` — explicit `requests` + `limits` (cpu + memory) on every service; global hardened `securityContext`; Redis memory cap + eviction; DB pool sized; PodDisruptionBudget templates (off by default, toggle per service).
- `imagePullPolicy: Always`, `imagePullSecrets`, external-postgres opt-in (`postgres.enabled: false` + `credentialsSecretName`).
- Upgrade path from existing dev clusters: `helm upgrade vexa deploy/helm/charts/vexa -f values-staging.yaml`.

### Dashboard in-tree

`services/dashboard/` — Next.js web UI brought into the monorepo. Magic-link login, meeting CRUD, bot control, live WebSocket updates, webhook config, recording playback, transcript search.

### More new services

- **`calendar-service`** — Google / Outlook calendar integrations.
- **`telegram-bot`** — Telegram interface to Vexa.
- **`vexa-agent`** — agent runtime.

### New top-level structure

- **`deploy/`** — `{compose, lite, helm}` (replaces old `docker/*` tree + root `docker-compose.yml` + `alembic.ini`).
- **`features/<name>/`** — prose README + machine-readable `dods.yaml` per feature (14 features tracked today).
- **`packages/`** — OSS npm packages: `vexa-client`, `vexa-cli`, `transcript-rendering`.
- **`libs/`** — shared Python libs.
- **`tests3/`** — release protocol (see below).
- **`CLAUDE.md`**, **`VERSION`** — AI-operator entry point + version pin.

---

## Release protocol (new primitive)

Because v0.10 is this large, the release *process* got an overhaul too. The release cycle is now a **strict stage state machine** — every `make release-*` target and every AI skill guards on the current stage; illegal transitions hard-fail:

```
idle → groom → plan → develop → provision → deploy → validate ⇄ triage → human → ship → teardown
```

Five primitives documented in `tests3/README.md`:

1. **Scope** (`releases/<id>/scope.yaml`) — per-release contract declaring issues + `proves[]` bindings into the registry.
2. **README-as-contract** — every `features/<name>/README.md` references a `dods.yaml` sidecar (machine-readable DoDs).
3. **Registry** (`tests3/registry.yaml`) — one source of truth for checks (consolidated from two prior files).
4. **Fresh-infra lifecycle** — every cycle: provision from zero → validate → teardown. No shared staging that decays.
5. **Stage state machine** — `tests3/.current-stage` + `.state/stage-log.ndjson` + `lib/stage.py`; AI skills load per-stage prompts from `tests3/stages/*.md`.

Cycles shipped under the new protocol:
- **`260417-webhooks-dbpool`** — webhook gateway injection + meeting-api DB pool fix.
- **`260418-webhooks`** — non-`meeting.completed` status webhooks actually fire when opted-in.
- **`260419-helm`** — helm chart production-tuning + LKE cluster correctly sized for bot workload.

---

## Webhooks

- Gateway injects validated `X-User-Webhook-*` into `meeting.data` on `POST /bots`; client-supplied headers stripped first (spoof-resistant).
- Fixed: `meeting.completed` double-fire on status path.
- Fixed: `stop_requested` gate no longer silences non-terminal status webhooks.
- `bot.failed`, `meeting.started`, `meeting.status_change` now actually deliver when opted-in via `webhook_events` (prior release's green gate was false-positive).
- Dashboard `/webhooks` page shows all event types.

## Reliability

- Meeting-api DB pool exhaustion fixed (leaked `AsyncSession` transactions); pool sized 20/20/10s.
- `idle_in_transaction_session_timeout: 60s` guard on postgres.
- Reconciliation scheduler known-bug (kills prod bots on container-based deployments) disabled at runtime, pending topology-aware rewrite next cycle.

---

## Breaking / operator-visible

- **Layout**: `docker/*` → `deploy/*`. Compose users: `make -C deploy/compose all`. Lite: `make -C deploy/lite all`. Helm: `helm install vexa ./deploy/helm/charts/vexa`.
- **Services gone**: `bot-manager` (split into `meeting-api` + `runtime-api`), `transcription-collector` (absorbed into `meeting-api`), `whisperlive` (folded into `vexa-bot`).
- **API surface**: public routes unchanged on `meeting-api`. `runtime-api` is internal-only. `/transcripts/*` now served by `meeting-api`.
- **Env**: `.env` layout moved; see `deploy/env-example`.

---

## Upgrading

```bash
# Full stack via Docker Compose
make -C deploy/compose all

# Single container trial (Vexa Lite)
make -C deploy/lite all

# Production Kubernetes (Linode LKE / any K8s cluster)
helm install vexa deploy/helm/charts/vexa \
  -f deploy/helm/charts/vexa/values-staging.yaml
```

DockerHub `:latest` now points to `0.10.0-260419-1140`.

---

## Known gaps (scoped for next cycle)

- `HELM_VALUES_RESOURCES_SET` static check is grep-single-pattern; tighten to per-service verification.
- `release-build` doesn't propagate fresh image tag into `.env` automatically (stale-image risk on `helm upgrade`).
- `aggregate.py` reads all `.state-<mode>/reports/` regardless of `scope.deployments.modes` — stale out-of-scope reports can contaminate gate math on scope-narrowed cycles.
- `values-staging.yaml` retains hosted-environment identifiers; candidate for redaction or move to `-example.yaml`.
- Reconciliation scheduler is topology-unaware; rewrite to dispatch per orchestrator backend.

---

## Credits

Shipped via the new release protocol. Full audit trail under `tests3/releases/260417-webhooks-dbpool/`, `tests3/releases/260418-webhooks/`, `tests3/releases/260419-helm/` — each cycle's `scope.yaml`, `plan-approval.yaml`, `triage-log.md`, `code-review.md`, `human-approval.yaml`.