tinybeeai 0.0.0-stage → 0.16.1

package/docs/tinybee/01-PRD.md

@@ -0,0 +1,216 @@
+# TinyBeeAI — Product Requirements Document
+
+**Version:** 0.1 (draft)
+**Date:** 2026-10-24
+**Status:** For review
+**Related docs:** `02-architecture-pairing.md`, `03-local-agent.md`, `04-local-setup-ui.md`, `05-mobile-app-ux.md`
+
+---
+
+## 1. One-line summary
+
+TinyBeeAI turns any spare laptop into a personal AI agent that runs 24/7, watches the user's work accounts, and is controlled entirely from a mobile app — with a two-step setup: **install on the laptop, scan a QR code on the phone.**
+
+## 2. Problem
+
+Small business owners, freelancers and busy professionals have workflows spread across Gmail, Google Drive/Sheets, Zalo, Facebook pages, banking notifications and spreadsheets. Checking them is manual, repetitive and interrupt-driven. Cloud "AI assistant" products exist, but:
+
+- They require handing all account access to a third-party cloud.
+- They charge per seat per month for compute the user already owns (an idle laptop).
+- Setting up a self-hosted alternative (n8n, Docker, tunnels, OAuth apps) takes a weekend and technical skill most people do not have.
+
+## 3. Vision
+
+> Your own AI employee, living on your own laptop, reachable from your pocket.
+
+The user's data and credentials stay on hardware they own. TinyBeeAI provides only what the laptop cannot do alone: identity, a public address, pairing, push notifications and a polished mobile UI. Because we relay rather than compute, our marginal cost per user is low, which lets us offer a free first month and cheap plans.
+
+## 4. Goals and non-goals
+
+### Goals (v1)
+1. Setup takes under 5 minutes for a non-technical user, with no router, DNS, Docker or terminal interaction.
+2. Each user has an isolated **tenant**: their own subdomain, auth, agent, workflows and data. Nothing is shared between tenants.
+3. The agent runs unattended 24/7 and survives reboots, power cuts and internet drops.
+4. All workflow configuration, chat, logs and alerts are done from the mobile app.
+5. Credentials to third-party services (Gmail, Drive, etc.) are stored **only on the user's laptop**, never persisted in our cloud.
+6. Clear, honest status at all times: the user always knows if the agent is online, what it did, and what it costs.
+
+### Non-goals (v1)
+- Running a large local LLM. v1 uses cloud model APIs (via our relay or the user's own key). Local models (Ollama) are detected and offered as an optional provider but are not required or tuned for.
+- Multi-user tenants / teams. One tenant = one person = one laptop. Team features are v2.
+- Windows support. v1 targets **macOS 13 Ventura+ (Apple Silicon and Intel)** only. Windows is not supported and not on the roadmap until demand is proven. (Linux users can run the daemon manually.)
+- A web dashboard. Mobile app only in v1; the laptop UI is setup-and-health only.
+- Marketplace of third-party workflows (v2).
+
+## 5. Target users and personas
+
+### Persona A — "Ms. Lan", small business owner (primary)
+- Runs a 2-location education centre, ~10 staff. Lives in Zalo, Gmail, Google Sheets, Facebook page inbox.
+- Has an old Dell laptop in a drawer.
+- Wants: "Tell me when a parent emails about tuition, when the monthly attendance sheet is missing rows, when the FB page gets a message after hours." Does not want to learn automation tools.
+- Fear: giving a random cloud company her Gmail.
+
+### Persona B — "Minh", freelancer / solo consultant
+- Multiple client inboxes, invoices in Drive, deadlines in Calendar.
+- Comfortable with tech but values time. Would happily bring his own OpenAI key.
+- Wants: a daily digest, deadline nudges, "draft a reply to this" from his phone.
+
+### Persona C — "Tuấn", tinkerer (secondary)
+- Already runs Home Assistant. Wants the pairing/tunnel convenience and will write his own workflows in YAML.
+- Will be loud on forums if the product is good or bad. Needs an "advanced mode" but must not dictate the default UX.
+
+## 6. Core concepts and vocabulary
+
+| Term | Meaning |
+|---|---|
+| **Bee** | The local agent/daemon installed on the laptop. One Bee per laptop. |
+| **Hive** | Our cloud: identity, pairing, tunnel provisioning, relay, push. Stateless with respect to user content. |
+| **Tenant** | One user's isolated space: `<slug>.tinybee.app` subdomain, auth realm, one or more Bees (v1: exactly one). |
+| **Workflow** | A monitor + condition + action the Bee runs on a schedule or trigger. |
+| **Skill** | A reusable workflow template (e.g. "Watch Gmail for keyword", "Daily Sheets summary"). |
+| **Connection** | An authorized third-party account (Gmail, Drive, Zalo OA…). Tokens live on the Bee. |
+| **Relay** | Hive forwarding mobile ↔ Bee traffic through the tunnel, and model API calls when the user has no own key. |
+
+## 7. Tenancy model
+
+- A tenant is created when a user signs up in the mobile app (email + OTP, Google, or Apple sign-in).
+- Tenant gets a slug (`hong`, `hong-2` if taken), hence `https://hong.tinybee.app`.
+- Tenant has exactly one active Bee in v1. Re-pairing a new laptop replaces the old Bee (old tunnel revoked).
+- Tenant data in Hive is limited to: account identity, tenant slug, tunnel ID, device public key, plan/billing state, push tokens, aggregated usage counters. **No workflow definitions, no connection tokens, no message contents** are stored in Hive.
+- Tenant deletion revokes the tunnel, deletes Hive records within 24h, and sends a wipe command to the Bee.
+
+## 8. Pricing and the free month
+
+Positioning: *"We only relay, so we can afford to be cheap."*
+
+| Plan | Price (indicative) | Includes |
+|---|---|---|
+| **Trial** | Free, first 30 days | Everything in Standard, incl. 200k bundled model tokens. No card required. |
+| **Standard** | ~99,000 VND / ~US$4 per month | Tenant subdomain, tunnel, push, mobile app, 5 workflows, bring-your-own-key for models **or** 500k bundled tokens/month. |
+| **Pro** | ~249,000 VND / ~US$10 per month | Unlimited workflows, 3M bundled tokens, priority relay, 90-day log retention on device, early access to new skills. |
+| **Bring-your-own-model add-on** | Free | User enters OpenAI/Anthropic/Gemini key or uses local Ollama; no bundled tokens consumed. |
+
+Rules:
+- Trial converts to Standard only on explicit opt-in; no silent charges. If the trial lapses, the Bee keeps running **locally** (workflows still execute) but the tunnel and push are suspended — the user loses remote access, not their agent. This is a deliberate trust signal.
+- Bundled token overage: soft stop with a notification; user can top up or add own key.
+- Payment: local methods first (MoMo, ZaloPay, bank transfer via gateway), then card (Stripe) for international.
+
+## 9. User journeys
+
+### 9.1 First-time setup (the "install + scan" promise)
+1. User downloads the mobile app, signs up → tenant created, slug chosen (editable once).
+2. App shows: "Now install TinyBee on the laptop you want to use." with a short URL and a 6-char install code.
+3. On the laptop, user runs the installer. It installs the Bee as a launchd daemon, runs a health check, and shows a QR code.
+4. User scans the QR with the app. App confirms the laptop name and health results. User taps **Connect**.
+5. Hive provisions the tunnel and auth; Bee comes online. App shows "🟢 Your Bee is online at hong.tinybee.app".
+6. App offers 3 starter skills based on sign-up answers (e.g. "I use Gmail", "I run a business"). User picks one, connects the account, done.
+
+Target: ≤ 5 minutes, ≤ 8 taps on phone, 2 clicks on laptop.
+
+### 9.2 Daily use
+- Morning push: "Your Bee's overnight report: 3 new parent emails, 1 flagged urgent."
+- User opens app, reads the summary, taps "Draft reply" → chat with the Bee, approves, Bee sends via Gmail connection.
+- User adds a new workflow from a skill template in under 1 minute.
+
+### 9.3 Something goes wrong
+- Laptop lid closed → Bee offline → within 5 min push: "Your Bee has been offline for 5 minutes. Last seen 14:02. Is the laptop asleep?" with a link to the "keep awake" guide.
+- Token exhausted → in-app banner, workflows pause, no surprise bill.
+- Gmail token expired → push with one-tap "Reconnect Gmail".
+
+### 9.4 Leaving
+- Settings → Delete tenant → confirm → Bee wipes local data, tunnel revoked, account deleted. Export of workflow definitions (YAML) offered first.
+
+## 10. Functional requirements
+
+### 10.1 Hive (cloud)
+- **FR-H1** Account sign-up/sign-in: email OTP, Google, Apple. 2FA optional.
+- **FR-H2** Tenant lifecycle: create, rename slug (once), suspend (billing), delete.
+- **FR-H3** Pairing service: issue install codes, verify QR pairing payloads, exchange device keys (see `02-architecture-pairing.md`).
+- **FR-H4** Tunnel provisioning via Cloudflare API: create Tunnel, DNS CNAME `<slug>.tinybee.app`, issue tunnel token to Bee, revoke on unpair.
+- **FR-H5** Auth gateway: every request to `<slug>.tinybee.app` must carry a valid tenant session token issued by Hive; enforced at the edge (Cloudflare Access service token or Worker) **and** re-verified by the Bee.
+- **FR-H6** Model relay: proxy chat/completion requests from Bee to model providers using Hive's keys, metered per tenant. Bee-side BYOK requests bypass the relay entirely.
+- **FR-H7** Push notification service (FCM/APNs) triggered by the Bee through an authenticated Hive endpoint. Payloads are titles/summaries only; full content is fetched from the Bee.
+- **FR-H8** Presence: Bee heartbeats every 60s; Hive flags offline after 5 min and notifies.
+- **FR-H9** Billing: plan state, trial countdown, token metering, payment gateways, invoices.
+- **FR-H10** Admin console (internal): tenant list, tunnel health, relay usage, abuse flags. No access to user content.
+
+### 10.2 Bee (local agent) — summarized; full spec in `03-local-agent.md`
+- **FR-B1** One-click macOS installer (signed + notarized `.pkg`); runs as a service; auto-start; auto-update with rollback.
+- **FR-B2** Health check: runtime, internet, disk, RAM, power settings, model providers reachable, local Ollama detection.
+- **FR-B3** Pairing UI (QR) and menu bar app.
+- **FR-B4** Tunnel client (bundled `cloudflared`) managed by the Bee.
+- **FR-B5** Workflow engine: scheduled and event-triggered workflows, retries, backoff, concurrency limits.
+- **FR-B6** Connections: OAuth token storage encrypted at rest (macOS Keychain-wrapped key), refresh handling, scoped permissions.
+- **FR-B7** Agent runtime: tool-calling LLM loop with a fixed tool set (read mail, search Drive, read/write Sheets, send message, web fetch, etc.) under per-workflow permission scopes.
+- **FR-B8** Local API served to the mobile app over the tunnel (REST + WebSocket/SSE for chat and live logs).
+- **FR-B9** Local storage: SQLite for workflows, runs, logs, chat history; configurable retention.
+- **FR-B10** Safety: action approval gates ("ask me before sending"), rate limits on outbound actions, kill switch from mobile.
+
+### 10.3 Mobile app — summarized; full spec in `05-mobile-app-ux.md`
+- **FR-M1** Onboarding, sign-up, slug selection, QR scanning.
+- **FR-M2** Home: Bee status, today's digest, pending approvals.
+- **FR-M3** Chat with the Bee (streaming), with attachments and quick actions.
+- **FR-M4** Workflows: list, create from skill, edit (natural-language + guided form), enable/disable, run now, run history.
+- **FR-M5** Connections: add/remove third-party accounts via OAuth, with scope display.
+- **FR-M6** Activity log and run details with inputs/outputs.
+- **FR-M7** Notifications settings: quiet hours, per-workflow channels.
+- **FR-M8** Account & billing: plan, usage meter, payment, delete tenant.
+- **FR-M9** Offline/degraded states: last-seen, troubleshooting, re-pair.
+- **FR-M10** Localization: Vietnamese and English at launch.
+
+## 11. Non-functional requirements
+
+| Area | Requirement |
+|---|---|
+| Setup time | P50 ≤ 5 min, P90 ≤ 10 min from app download to first workflow. |
+| Availability (Hive) | 99.9% monthly for pairing, auth, relay, push. |
+| Latency | Mobile → Bee round-trip P50 ≤ 400 ms within VN; chat first token ≤ 2 s. |
+| Offline resilience | Bee continues executing workflows without Hive; queues pushes; reconnects tunnel with exponential backoff. |
+| Security | TLS everywhere; device-bound keys (Ed25519); tokens encrypted at rest; least-privilege OAuth scopes; signed updates. |
+| Privacy | No user content stored in Hive. Relay logs contain metadata only (tenant, tokens used, timestamps), retained 30 days. |
+| Resource footprint | Bee idle ≤ 300 MB RAM, ≤ 2% CPU; installer ≤ 150 MB. |
+| Compatibility | macOS 13+ on Apple Silicon or Intel, 8 GB RAM recommended, 4 GB minimum. No Windows support. |
+| Accessibility | Mobile app meets WCAG 2.1 AA contrast and dynamic type. |
+| Localization | vi-VN and en-US strings; dates/currency localized. |
+
+## 12. Success metrics
+
+| Metric | Target (6 months post-launch) |
+|---|---|
+| Install → paired conversion | ≥ 70% |
+| Paired → first workflow within 24 h | ≥ 60% |
+| Trial → paid conversion | ≥ 15% |
+| 30-day Bee uptime (median tenant) | ≥ 95% |
+| Weekly active tenants / paired tenants | ≥ 55% |
+| Support tickets per 100 tenants per month | ≤ 8 |
+| NPS | ≥ 40 |
+
+## 13. Risks and mitigations
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Laptop sleeps / is closed | Agent offline; user blames product | Installer sets `pmset` (no sleep on AC, wake on lid open) and offers `caffeinate`-style keep-awake; menu bar app warns; offline push with fix guide; "nightly reboot check". |
+| Desktop packaging complexity (Docker dependency, notarization) | Install failures | Ship the Bee as a single native binary (Go/Rust) with embedded runtime; **no Docker requirement** for end users. |
+| Cloudflare ToS / limits | Service disruption | HTTP-only traffic; monitor account limits; abstract tunnel provider behind an interface so Tailscale/own relay can replace it. |
+| Model cost blowout on bundled plans | Negative margin | Hard token caps, cheap-model default for monitoring, expensive model only on user request. |
+| OAuth app verification (Google) | Delayed launch | Start Google verification early; restrict scopes; ship Gmail read-only first. |
+| Abuse (spam sending via Bee) | Reputation, provider bans | Outbound rate limits, approval gates default-on for send actions, abuse reporting. |
+| Users expect it to "do anything" | Churn | Clear skill library, honest capability copy, examples in onboarding. |
+
+## 14. Release plan
+
+| Phase | Scope | Exit criteria |
+|---|---|---|
+| **Alpha** (internal, 10 users) | macOS Bee, pairing, tunnel, Gmail read-only skill, chat, iOS/Android TestFlight builds | Setup ≤ 10 min for 8/10 testers |
+| **Beta** (invite, 200 users, VN) | + Drive/Sheets, Zalo OA, approvals, billing in test mode, vi/en | Trial→paid ≥ 10%; uptime ≥ 90% |
+| **v1 Launch** | + payments live, Facebook Page inbox, auto-update, support site | Metrics in §12 trending to target |
+| **v1.5** | Calendar, scheduled reports as PDF | — |
+| **v2** | Windows Bee (if demand), team tenants, skill marketplace, local-model tuning, web dashboard | — |
+
+## 15. Open questions
+
+1. Slug domain: `tinybee.app` vs a `.vn` domain for local trust? (Can do both with a redirect.)
+2. Should the Bee *ever* run without pairing (offline-only mode) as a free tier? It costs us nothing and builds a funnel.
+3. Zalo API access terms for OA vs personal accounts — personal Zalo has no official API; scope to Zalo OA only?
+4. Default model for monitoring tasks: cheapest capable tier from one provider, or auto-select by task?
+5. Do we need a desktop-browser fallback UI at `<slug>.tinybee.app` for users without their phone? (Leaning yes for v1.5, read-only.)

package/docs/tinybee/02-architecture-pairing.md

@@ -0,0 +1,199 @@
+# TinyBeeAI — System Architecture & Pairing Flow
+
+**Version:** 0.1 (draft) · **Date:** 2026-10-24
+**Companion to:** `01-PRD.md`
+
+---
+
+## 1. Components
+
+```
+┌──────────────────┐        HTTPS         ┌──────────────────────────────┐
+│   Mobile App     │◄────────────────────►│  HIVE (cloud)                │
+│  iOS / Android   │   sign-in, pairing,  │  • Identity & tenants        │
+│                  │   billing, push reg. │  • Pairing service           │
+└────────┬─────────┘                      │  • Tunnel provisioner (CF)   │
+         │                                │  • Auth gateway (edge)       │
+         │  HTTPS / WSS                   │  • Model relay (metered)     │
+         │  https://<slug>.tinybee.app    │  • Push (FCM/APNs)           │
+         ▼                                │  • Presence                  │
+┌──────────────────┐                      └──────────────┬───────────────┘
+│ Cloudflare edge  │  Access check (tenant token)        │ control plane
+│  <slug>.tinybee  │─────────────────────────────────────┘ (heartbeat, push,
+└────────┬─────────┘                                        relay, updates)
+         │ Cloudflare Tunnel (outbound from laptop)
+         ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  BEE (user's laptop, launchd daemon on macOS)                    │
+│  • cloudflared (bundled)   • Local API (REST + WS)               │
+│  • Workflow engine         • Agent runtime (LLM tool loop)       │
+│  • Connections (OAuth tokens, Keychain-wrapped encryption)       │
+│  • SQLite (workflows, runs, logs, chat)                          │
+│  • Menu bar app + local setup page (http://localhost:7331)       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Ownership matrix
+
+| Concern | Mobile | Hive | Bee |
+|---|---|---|---|
+| User identity | sign-in UI | **owner** | verifies Hive-issued tokens |
+| Tenant slug, plan, billing | UI | **owner** | reads plan state |
+| Pairing | scans QR | **broker** | shows QR, holds device key |
+| Tunnel | — | **provisions** | **runs** `cloudflared` |
+| Workflow definitions | edit UI | — | **owner (SQLite)** |
+| Third-party tokens | starts OAuth | transient callback only | **owner (encrypted)** |
+| Chat history, logs, run data | view | — | **owner** |
+| Model calls | — | relay (bundled) | direct (BYOK / Ollama) |
+| Push | receives | **sends** | requests |
+| Presence | displays | **derives** | heartbeats |
+
+Design rule: **Hive is a control plane, never a data plane for user content.** Everything that would embarrass us in a breach lives on the laptop.
+
+## 2. Data flow paths
+
+1. **Mobile ↔ Bee (data path)** — `https://<slug>.tinybee.app` → Cloudflare edge → Tunnel → Bee local API. Hive is not in this path except for edge auth validation (JWT signature check, no round trip).
+2. **Bee → Hive (control path)** — heartbeat, push requests, plan check, update manifest, pairing completion, relay model calls (only when bundled tokens are used).
+3. **Mobile → Hive** — sign-in, tenant management, billing, push token registration, pairing initiation.
+
+## 3. Identity and keys
+
+| Key | Where created | Purpose |
+|---|---|---|
+| **Tenant session JWT** (user) | Hive, on sign-in; RS256; 7-day refresh | Sent by mobile on every Bee request; validated at edge and by Bee against Hive's public JWKS. Contains `tenant_id`, `user_id`, `scopes`. |
+| **Device key pair** (Ed25519) | Bee, first run | Bee identity. Public key registered to tenant during pairing. Bee signs heartbeats and push requests. |
+| **Pairing code** | Hive | 6-char code (install flow) and/or one-time QR nonce; 10-min TTL, single use. |
+| **Tunnel token** | Cloudflare, via Hive | Lets `cloudflared` connect the tunnel. Delivered to Bee once, stored encrypted (Keychain-wrapped key). Rotatable. |
+| **Relay token** | Hive | Bee-to-Hive auth for metered model calls; short-lived (1 h), refreshed with device signature. |
+| **Third-party OAuth tokens** | Provider | Stored only on Bee. Hive sees them once in the callback and forwards; never persisted. |
+
+Edge auth: a Cloudflare Worker (or Access with a custom IdP) in front of every `*.tinybee.app` hostname validates the tenant JWT and checks `tenant_id` matches the hostname's slug. Unauthenticated requests never reach the laptop.
+
+## 4. Pairing flow (detailed)
+
+### 4.1 Pre-conditions
+- User signed up in mobile app → tenant `T` exists with slug `hong`.
+- App shows the install page URL (`tinybee.app/get`) and a 6-char install code `K7M2PQ` (10-min TTL, refreshable).
+
+### 4.2 Sequence
+
+```
+Mobile App          Hive                      Bee (laptop)                 Cloudflare
+   |                 |                            |                            |
+   |-- POST /pair/init (tenant T) --------------->|                            |
+   |<-- install_code K7M2PQ, expires 10m ---------|                            |
+   |                 |                            |                            |
+   |   (user runs installer on laptop)            |                            |
+   |                 |                            |-- generate device keypair  |
+   |                 |                            |-- run health check         |
+   |                 |                            |-- show QR {v,nonce,pub,host,hc}
+   |                 |                            |   + "or enter code" box    |
+   |                 |                            |                            |
+   |-- scan QR ----->|                            |                            |
+   |-- POST /pair/complete {nonce, pub, hostname, health, install_code?} ----->|
+   |                 |-- verify nonce/code, bind pub to T                     |
+   |                 |-- CF API: create tunnel "bee-<tenant>" ---------------------------->|
+   |                 |<-- tunnel_id, tunnel_token ---------------------------------------- |
+   |                 |-- CF API: DNS CNAME hong.tinybee.app → <tunnel>.cfargotunnel.com -->|
+   |                 |-- CF API: ensure edge auth rule for hostname ---------------------->|
+   |<-- 200 {bee_name, slug, status: provisioning} |                            |
+   |                 |                            |                            |
+   |                 |<-- Bee polls GET /pair/status?nonce (every 2s, signed) --|
+   |                 |-- 200 {tunnel_token, relay_token, tenant_id, slug} ----->|
+   |                 |                            |-- store tokens (encrypted) |
+   |                 |                            |-- start cloudflared -------------------->|
+   |                 |                            |-- POST /presence/heartbeat (signed) ---->|
+   |<-- push "Your Bee is online" -----------------|                            |
+   |-- GET https://hong.tinybee.app/api/health (tenant JWT) --------------------------------->Bee
+   |<-- 200 {bee_name, version, uptime, providers} -------------------------------------------|
+```
+
+### 4.3 QR payload
+
+```json
+{
+  "v": 1,
+  "nonce": "b4f2…(32 bytes, base64url)",
+  "pub": "ed25519:…",
+  "host": "DESKTOP-LAN-01",
+  "hc": { "ok": true, "ram_gb": 8, "disk_free_gb": 112, "power_ok": false, "providers": ["ollama"] },
+  "lan": "http://192.168.1.23:7331"
+}
+```
+- Encoded as a `tinybee://pair?d=<base64url(json)>` deep link so a non-app QR scanner still opens the app (or the store).
+- Signed by the device key over `nonce|pub|host` to prevent QR substitution.
+- `lan` lets the app verify same-network presence optionally (not required; many users will pair over mobile data).
+
+### 4.4 Fallback: install code instead of QR
+If the camera is unavailable, the laptop UI shows the same 6-char code the app displayed. Bee calls `POST /pair/claim {install_code, pub, host, hc}`; Hive binds it to the tenant that generated the code. The app then shows "Found DESKTOP-LAN-01 — Connect?".
+
+### 4.5 Failure handling
+
+| Failure | Behaviour |
+|---|---|
+| Nonce expired | Laptop UI regenerates QR automatically every 10 min; app shows "QR expired, scan the new one". |
+| Tenant already has a Bee | App asks "Replace existing Bee `OLD-NAME`? It will be disconnected." Old tunnel revoked on confirm. |
+| Cloudflare API error | Hive retries 3× with backoff; app shows "Setting up your address…" up to 60 s, then "We hit a snag — retry" (no partial state left: tunnel create and DNS are idempotent by name). |
+| Bee cannot reach Hive after scan | Laptop UI shows "Waiting for connection… check internet"; app shows "Laptop not responding — is it online?". |
+| Health check red (e.g. no internet) | Pairing still allowed except for hard blockers (no internet, unsupported OS); app shows warnings with fix links. |
+
+## 5. Tunnel provisioning details
+
+- One Cloudflare account, one zone (`tinybee.app`), wildcard-ready.
+- Per tenant: `POST /accounts/{acct}/cfd_tunnel` named `bee-{tenant_id}`; `PUT …/configurations` with ingress `hong.tinybee.app → http://localhost:7331` (Bee local API) and catch-all 404; DNS CNAME record proxied.
+- Hostname-level auth enforced by a Worker route `*.tinybee.app/*` validating JWT and slug ↔ tenant mapping (KV cache).
+- Revocation: delete tunnel + DNS record; Bee receives `unpaired` on next heartbeat and wipes tunnel token.
+- Rotation: tunnel token rotated on re-pair and on demand from admin console.
+- Provider abstraction: `TunnelProvider` interface (`Provision`, `Revoke`, `Rotate`, `Status`) so a Tailscale-based or self-hosted relay implementation can be swapped in.
+
+## 6. Connections (third-party OAuth) flow
+
+```
+Mobile: tap "Connect Gmail"
+  → GET https://hong.tinybee.app/api/connections/gmail/start   (Bee builds auth URL with PKCE, state bound to tenant)
+  → opens provider consent in system browser
+Provider → redirect to https://auth.tinybee.app/cb?code&state     (Hive, because providers need a stable registered redirect)
+Hive → verifies state → forwards {code, verifier_ref} to Bee via Bee's outbound long-poll channel (no storage)
+Bee → exchanges code for tokens directly with provider → stores encrypted (Keychain-wrapped key)
+Bee → notifies mobile via WS: connection ready, scopes granted
+```
+Hive never holds the refresh token; the code is single-use and expires in minutes.
+
+## 7. Model access paths
+
+Dots provides no AI for host work. Everything a workflow reads or writes on the laptop runs on a backend the user set up there; the phone only picks among what the Bee found. The Bee never sends host content through the Hive (Phase A, 2026-10-25).
+
+| Backend | Path | Metering |
+|---|---|---|
+| Claude subscription (`claude` CLI, signed in) | Bee → CLI on the laptop | The user's subscription |
+| Codex subscription (`codex` CLI, ChatGPT login) | Bee → CLI on the laptop | The user's subscription |
+| Anthropic / OpenAI / Gemini API key | Bee → provider directly | The user's own bill |
+| Ollama, LM Studio | Bee → `127.0.0.1:11434` / `127.0.0.1:1234` | None |
+| Custom OpenAI-compatible endpoint | Bee → the saved base URL | Whatever the endpoint bills |
+
+The Bee scans the laptop for these (`GET /api/v1/models`, `src/bee/models.ts`) and the phone's AI screen shows what is found, what each needs (install, sign in, key, server, model) and which one is in use. Keys and endpoints typed on the phone go through the tunnel into the laptop's encrypted store, are never returned, and never reach the Hive. The Hive's own bundled model (Phase 6 relay) serves app-side features only, never a workflow on the host; a laptop with no backend set up runs nothing until one is picked.
+
+The tier map (`TINYBEE_MODEL_TIERS`) routes `cheap` / `strong` / `local` to a backend each; an unmapped tier uses the active backend. `LOCALDOST_LLM` set in the laptop's environment overrides the pick and the screen says so.
+
+## 8. Presence and push
+
+- Heartbeat every 60 s: `{device_sig, version, uptime, queue_depth, last_run_at}`.
+- Hive marks `offline` after 5 missed heartbeats, sends one push, then a daily reminder while offline; marks `online` on return and sends "back online" push.
+- Push requests from Bee are title + short body + deep link; the app fetches full content from the Bee.
+
+## 9. Updates
+
+- Bee checks a signed update manifest every 6 h; downloads delta, verifies signature, installs on next idle window (no running workflow), keeps previous version for one-click rollback from the menu bar app and from mobile.
+- Mobile app updates via stores; API versioned (`/api/v1`), Bee advertises supported versions in `/health`.
+
+## 10. Security checklist (v1)
+
+- [ ] TLS 1.2+ everywhere; HSTS on `*.tinybee.app`.
+- [ ] Edge rejects any request without valid tenant JWT; Bee independently re-validates.
+- [ ] Device-bound Ed25519 identity; private key never leaves machine.
+- [ ] All secrets on Bee encrypted with an app key stored in macOS Keychain; secret store abstracted per OS for the future.
+- [ ] Outbound action rate limits (send mail ≤ 30/h default) and approval gates.
+- [ ] Signed, reproducible Bee builds; update manifest signed with offline key.
+- [ ] Hive stores no prompt content, no third-party tokens, no workflow bodies.
+- [ ] Tenant deletion = tunnel revoke + Hive purge + Bee wipe command.
+- [ ] Abuse hooks: relay anomaly detection (sudden token spikes), hostname takedown.

package/docs/tinybee/03-local-agent.md

@@ -0,0 +1,222 @@
+# TinyBeeAI — Local Agent ("Bee") Design
+
+**Version:** 0.1 (draft) · **Date:** 2026-10-24
+**Companion to:** `01-PRD.md`, `02-architecture-pairing.md`
+
+> In this repo, the Bee is localdost itself (one Node process + SQLite). Sections below describe the target design; where localdost already has the piece (rule gate, Inbox approvals, dots/Watches, SQLite, demo mode) treat this as the integration contract, not a rewrite.
+
+---
+
+## 1. Design principles
+
+1. **Single binary, zero dependencies.** No Docker, no Python, no Node for the end user. Ship a native executable (recommended: Go — universal macOS binaries, static linking, easy launchd support, strong HTTP/SQLite ecosystem; Rust is the alternative). `cloudflared` is bundled as a managed child process. *(localdost note: a Node runtime can be bundled into a single executable via pkg/SEA; evaluate before rewriting.)*
+2. **Boring and durable.** Runs as a launchd daemon, restarts on crash, resumes work after reboot, tolerates offline Hive for days.
+3. **Local-first data.** Everything the user cares about lives in one folder they can back up or delete.
+4. **Safe by default.** Reads are free; writes/sends go through permission scopes and, by default, user approval.
+5. **Observable.** Every workflow run is logged with inputs, decisions, tool calls, outputs and cost, viewable from the phone.
+
+## 2. Process model
+
+```
+LaunchDaemon: ai.tinybee.bee (runs as a dedicated `_tinybee` system user; no GUI session needed)
+ ├── supervisor
+ │    ├── api-server        (localhost:7331; REST + WebSocket)
+ │    ├── scheduler         (cron + event triggers → job queue)
+ │    ├── worker pool       (N=2 default; executes workflow runs)
+ │    ├── connections mgr   (token refresh, provider clients, webhooks poller)
+ │    ├── tunnel mgr        (spawns/monitors bundled cloudflared)
+ │    ├── hive client       (heartbeat, push, relay, updates, long-poll channel)
+ │    └── updater
+ └── Menu bar app (LaunchAgent, per-user, auto-start): status icon, menu, opens local setup page
+```
+
+- Daemon and menu bar app communicate over a Unix domain socket in `/var/run/tinybee/`; the menu bar app is optional (daemon runs headless if no user is logged in — important for Macs left at the login screen).
+- `KeepAlive` + `RunAtLoad` in the LaunchDaemon plist so launchd restarts the daemon on crash and after reboot.
+- Supervisor restarts any crashed subsystem with backoff; writes crash reports locally; uploads only an anonymized stack trace if the user opted in.
+
+## 3. Installation
+
+### 3.1 Installer (macOS, signed + notarized `.pkg`, universal binary)
+Steps performed silently with progress:
+1. Install binaries to `/Library/TinyBeeAI/` (daemon, bundled `cloudflared`) and `/Applications/TinyBee.app` (menu bar app).
+2. Create data dir `/Library/Application Support/TinyBeeAI/` owned by `_tinybee` (SQLite, logs, secrets); create the `_tinybee` system user.
+3. Install `/Library/LaunchDaemons/ai.tinybee.bee.plist` (`RunAtLoad`, `KeepAlive`) and `launchctl bootstrap` it.
+4. Install `/Library/LaunchAgents/ai.tinybee.menubar.plist` so the menu bar app starts at login for every user.
+5. Bind the API to `127.0.0.1` only (no inbound from LAN by default; no firewall rule needed).
+6. Power settings **with user consent** (checkbox, default on): `pmset -c sleep 0 disksleep 0` (never sleep on AC), `pmset -c womp 1`; lid-closed-on-AC works via clamshell mode only with an external display, so the health check also recommends an external display or a "lid open, screen dimmed" setup (`pmset -c displaysleep 10`). Battery settings untouched. Requires admin password once (installer already has it).
+7. Launch menu bar app → opens `http://localhost:7331/setup`.
+
+Uninstaller (`/Library/TinyBeeAI/uninstall.sh`, also from menu bar "Advanced"): `launchctl bootout`, removes plists and binaries, offers "Keep my data" vs "Delete everything (secure wipe)".
+
+Code signing: Developer ID Application + Installer certificates, notarized via `notarytool` in CI; Gatekeeper must not prompt.
+
+### 3.2 First run
+- Generate Ed25519 device key → encrypt with Keychain-held app key → `secrets.db`.
+- Generate 8-char Bee name suggestion from hostname.
+- Run health check (§4), serve setup page with QR (see `04-local-setup-ui.md`).
+
+## 4. Health check module
+
+Runs at first start, every 6 h, on demand from mobile, and before pairing. Each check returns `ok | warn | fail` + message + fix hint + fix action id (if auto-fixable).
+
+| Check | Pass | Warn | Fail | Auto-fix |
+|---|---|---|---|---|
+| OS version | macOS 13+ | — | older | — |
+| CPU/RAM | ≥ 8 GB | 4–8 GB | < 4 GB | — |
+| Free disk | ≥ 10 GB | 3–10 GB | < 3 GB | — |
+| Internet | reachable, latency < 300 ms | high latency | none | — |
+| Hive reachable | 200 from `/ping` | — | blocked | — |
+| Cloudflare edge reachable | QUIC/HTTP2 handshake OK | fallback to HTTP2 only | blocked | switch protocol |
+| Power settings | `pmset` sleep on AC = 0, lid-closed on AC keeps running (clamshell with power) | not set | — | apply pmset |
+| On AC power | yes | on battery | — | — |
+| Clock skew | < 60 s | 60–300 s | > 300 s (breaks JWT) | trigger time sync |
+| Antivirus interference | binaries not quarantined | — | blocked | show exclusion guide |
+| Model providers | Hive relay OK | — | — | — |
+| BYOK keys (if any) | valid | rate-limited | invalid | — |
+| Local Ollama | detected at :11434, models listed | detected, no models | not present (info only) | — |
+| Daemon running as expected | yes | — | menu bar app cannot reach daemon | restart daemon |
+
+Results are included in the QR payload (summary) and available at `GET /api/v1/health`.
+
+## 5. Storage layout
+
+```
+~/Library/Application Support/TinyBeeAI/
+  bee.db          SQLite: tenants, workflows, runs, run_steps, chat_threads, chat_messages, approvals, connections (metadata), settings
+  secrets.db      SQLite, every value encrypted with the Keychain-held app key: device_key, tunnel_token, relay_token, oauth tokens, byok keys
+  logs\           rolling JSONL (app.log, cloudflared.log), 14 days
+  cache\          downloaded attachments / fetched pages, LRU 2 GB
+  updates\        staged + previous version
+  exports\        user-requested YAML/CSV exports
+```
+
+Retention defaults: runs & logs 30 days (Standard), 90 days (Pro), chat forever until deleted. All configurable from mobile. "Delete everything" overwrites secrets before unlinking.
+
+## 6. Workflow engine
+
+### 6.1 Workflow definition (stored as JSON/YAML in `bee.db`)
+
+```yaml
+id: wf_8f21
+name: Parent tuition emails
+enabled: true
+trigger:
+  type: schedule          # schedule | event | manual
+  cron: "*/10 7-21 * * *" # every 10 min, 07:00–21:00
+  timezone: Asia/Ho_Chi_Minh
+inputs:
+  - connection: gmail_main
+    query: "newer_than:15m (học phí OR tuition OR fee)"
+agent:
+  model_tier: cheap        # cheap | strong | local
+  instructions: >
+    You monitor incoming parent emails about tuition. For each new email,
+    classify urgency (low/normal/urgent), extract student name and amount if present,
+    and summarise in one line in Vietnamese.
+  tools: [gmail.read, gmail.label, notify.push]
+  permissions:
+    gmail.label: auto
+    notify.push: auto
+    gmail.send: ask        # not granted here anyway
+outputs:
+  - on: urgent
+    action: notify.push
+    template: "🔴 Urgent tuition email from {{sender}}: {{summary}}"
+  - on: any
+    action: digest.append  # goes into the morning digest
+limits:
+  max_runtime_s: 120
+  max_tokens: 4000
+  max_actions: 10
+```
+
+### 6.2 Trigger types
+- **schedule** — cron with timezone, jitter ±30 s to avoid provider bursts.
+- **event** — provider push where available (Gmail Pub/Sub via Hive relay webhook → long-poll to Bee; Sheets change via Drive push), otherwise polling with ETag/historyId.
+- **manual** — from mobile "Run now" or chat ("run the tuition check").
+- **chain** — on completion of another workflow.
+
+### 6.3 Execution
+- Scheduler enqueues `run` rows; worker pool pulls with per-connection concurrency = 1 (avoid provider rate limits).
+- Each run: snapshot inputs → build context → agent loop (max N tool calls) → outputs → persist steps with token/cost.
+- Retries: transient errors 3× exponential backoff; auth errors → mark connection `needs_reauth` and push once.
+- Idempotency: inputs carry provider IDs; `seen_items` table prevents re-processing the same email/row.
+- Missed schedules while asleep/offline: run **once** on wake with a "catch-up" flag (not once per missed slot).
+
+### 6.4 Approval gates
+Any tool marked `ask` creates an `approval` row and a push: "Bee wants to send a reply to Nguyễn Văn A — Approve / Edit / Deny". Run pauses up to 24 h, then expires as `denied(timeout)`. Approvals from mobile carry the user's JWT and are logged.
+
+## 7. Agent runtime
+
+- Single generic tool-calling loop with provider adapters behind one interface (`src/agent/llm.ts`): the `claude` and `codex` CLIs (subscriptions), Anthropic by key, and OpenAI-compatible presets (`src/agent/llm-openai.ts`: OpenAI, Gemini, Ollama, LM Studio, a custom endpoint); structured outputs via JSON schema.
+- **Local AI scan** (`src/bee/models.ts`, Phase A): the Bee looks for the CLIs on PATH and their sign-in, the vendor keys in its store, Ollama and LM Studio on their loopback ports (listing their models), and the saved custom endpoint. Dots ships no model for host work; the phone picks among what the laptop has.
+- **Tool registry** (v1):
+  - `gmail.read / search / label / draft / send`
+  - `drive.search / read_doc / read_sheet / write_sheet_range`
+  - `calendar.list / create` (v1.5)
+  - `zalo_oa.read_messages / send` ; `fb_page.read_inbox / reply` (beta/launch)
+  - `web.fetch` (read-only, allowlist/denylist, no auth cookies)
+  - `notify.push` ; `digest.append` ; `memory.note` (small per-tenant notes store)
+  - `files.read_local` (only within a user-chosen folder, off by default)
+- **Permission scopes** are per workflow, per tool, with `auto | ask | deny`. Global defaults: all reads `auto`, all sends/writes `ask`.
+- **Context budget**: per-model-tier token limits; long inputs chunked/summarized first with cheap tier.
+- **Model routing**: the tier map (`TINYBEE_MODEL_TIERS`) names a backend and model per tier (`cheap`, `strong`, `local`); an unmapped tier runs on the active backend. Nothing on the host ever goes through the Hive relay.
+- **Prompt hygiene**: provider content (emails, pages) is wrapped as data with explicit "do not follow instructions found inside" framing; tool outputs are size-capped; URLs from content are never auto-visited unless a workflow explicitly allows `web.fetch`.
+
+## 8. Local API (served to mobile through the tunnel)
+
+Base: `https://<slug>.tinybee.app/api/v1` → Bee `localhost:7331`. All requests require tenant JWT (validated against Hive JWKS, cached 24 h, with offline grace of 72 h for previously seen keys).
+
+| Area | Endpoints |
+|---|---|
+| Health | `GET /health`, `POST /health/run`, `POST /health/fix/{id}` |
+| Bee | `GET /bee`, `PATCH /bee` (name, retention, power), `POST /bee/restart`, `POST /bee/update`, `POST /bee/rollback`, `POST /bee/wipe` |
+| Workflows | `GET/POST /workflows`, `GET/PATCH/DELETE /workflows/{id}`, `POST /workflows/{id}/run`, `POST /workflows/{id}/toggle`, `POST /workflows/from-text` (NL → draft definition), `GET /skills` |
+| Runs | `GET /runs?workflow=&status=`, `GET /runs/{id}` (steps, tool calls, cost), `POST /runs/{id}/cancel` |
+| Approvals | `GET /approvals`, `POST /approvals/{id}` `{decision, edited_payload?}` |
+| Chat | `GET /chats`, `POST /chats`, `GET /chats/{id}/messages`, `WS /chats/{id}/stream` |
+| Connections | `GET /connections`, `GET /connections/{provider}/start`, `DELETE /connections/{id}`, `POST /connections/{id}/test` |
+| Digest | `GET /digest/today`, `PATCH /digest/settings` |
+| Settings | `GET/PATCH /settings` (quiet hours, locale) |
+| Models | `GET /models` (the scan: backends with `found`, `ready`, `needs`, `models`, the active one, the tier map, an env override), `PUT /models` `{active?, model?, tiers?, custom?, servers?, keys?}` (keys write-only; a pick of a backend that is not ready answers 409 and is rolled back). Settings: `LOCALDOST_LLM`, `TINYBEE_MODEL_BACKEND`, `TINYBEE_MODEL_TIERS`, `TINYBEE_MODEL_<PRESET>`, `OLLAMA_HOST`, `LMSTUDIO_URL`, `TINYBEE_CUSTOM_BASE_URL` / `_API_KEY` / `_EXTRA_BODY`, the vendor `*_API_KEY`s |
+| Logs | `GET /logs?level=&since=` (tail), `GET /export/workflows.yaml` |
+| Events | `WS /events` (bee status, run updates, approvals, connection changes) |
+
+Rate limit: 60 req/min per tenant at edge; WS max 3 concurrent.
+
+## 9. Tunnel manager
+
+- Spawns bundled `cloudflared tunnel run --token <t>` with `--protocol quic`, falls back to `http2` on repeated failure.
+- Monitors stdout for connection state; exposes `tunnel.status` to health and events.
+- Backoff on disconnect: 2 s → 4 s → … → 5 min cap, forever.
+- If Hive reports `unpaired` or `suspended` (billing): stop tunnel, keep executing local workflows, show banner in menu bar app/setup page, keep heartbeat (so re-activation is instant).
+
+## 10. Hive client
+
+- Heartbeat 60 s (signed). Includes version, uptime, pending approvals count, last run time, queue depth, bundled tokens used since last ack.
+- Long-poll channel `GET /bee/channel` (30 s) for: OAuth callbacks, pairing status, remote commands (`restart`, `update`, `wipe`, `run_health`, `kill_switch`), plan changes.
+- Push: `POST /push {tenant, title, body, deeplink, collapse_key}`; queued locally up to 24 h if Hive is unreachable, then dropped with a local log entry.
+- Relay: `POST /relay/chat` with provider-agnostic payload; Hive adds its provider key, returns stream; Bee records usage; Hive meters.
+
+## 11. Menu bar app
+
+Menu: status line (🟢 Online · hong.tinybee.app / 🟡 Local only / 🔴 Offline), "Open setup page", "Pause all workflows", "Run health check", "Check for updates", "View logs folder", "Quit menu bar app (daemon keeps running)".
+macOS notifications: paired, offline > 5 min (local), update installed, approval waiting (optional mirror of push).
+
+## 12. Updates
+
+- Manifest at `https://updates.tinybee.app/bee/stable.json` (signed, Ed25519 offline key); channels `stable | beta`.
+- Download delta → verify → stage → apply when idle (no running runs for ≥ 2 min, or at 03:00 local) → restart service → self-test (`/health`) → if failing twice, auto-rollback and notify.
+
+## 13. Telemetry (opt-in, default **off**)
+
+Anonymized counters only: version, OS build, health check pass/fail by type, crash signature. Never: hostnames, email addresses, workflow names, prompts, outputs.
+
+## 14. Edge cases & decisions
+
+- **Mac at login screen (no user session)**: the daemon runs as a system LaunchDaemon; the app key lives in the System keychain (not the login keychain) so secrets decrypt without a logged-in user. Menu bar app simply isn't shown. FileVault: the disk is locked before first login after a cold boot, so the Bee only resumes once someone logs in — health check warns if FileVault is on and auto-login is off.
+- **Two laptops**: v1 rejects second pairing unless user replaces. v2: multiple Bees per tenant with role routing.
+- **Changing Wi-Fi / mobile hotspot**: tunnel reconnects automatically; nothing for the user to do.
+- **Corporate laptop with proxy**: honour system proxy; health check reports blocked QUIC and switches to HTTP2.
+- **Clock wrong**: fail-closed on JWT validation but keep local workflows running; show fix.
+- **User deletes app data manually**: Bee restarts in unpaired mode, generates new key, shows QR; Hive detects new key for same tenant → prompts user to confirm replacement.