Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript

docs: add Gentle Dot design and ODD plan

Alan Buscaglia5ec596cd10e2
diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 0000000..f833aa0
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,178 @@
+# Gentle Dot — Design
+
+Gentle Dot is an always-available personal assistant. It floats on the macOS desktop, is summoned from the menu bar or a global shortcut, and is also reachable from a browser. Behind it runs Gentle Shell (Pi + Gentle extensions + Engram), hidden from the user.
+
+Status: design for local development. The VPS deployment is documented, not performed.
+
+## 1. Goals and non-goals
+
+Goals:
+
+- One assistant, always on, reachable from the desktop (floating Dot, menu bar, global shortcut) and from a web page.
+- The agent behaves exactly like Gentle Shell: same tools, ODD workflow, subagents, skills, and Engram memory.
+- The user never sees Gentle Shell: no Gentle branding, commands, or terminal in the product surface.
+- Everything runs locally first; the same daemon can later run on a VPS (HostGator) with Docker.
+
+Non-goals for this version:
+
+- Multi-user accounts, sharing, or teams.
+- Calls, Slack, scheduled jobs.
+- Pi Durable. Recovery relies on persisted Pi sessions plus Engram (see section 7).
+- Actual deployment to HostGator.
+
+## 2. Architecture
+
+```
+┌──────────────────────────────┐ ┌───────────────────────────┐
+│ Desktop app (Tauri 2, macOS) │ │ Browser │
+│ tray icon · floating Dot · │ │ http://127.0.0.1:4317 │
+│ global shortcut · webview │ │ (same React UI) │
+└──────────────┬───────────────┘ └─────────────┬─────────────┘
+ └────── WebSocket /ws + token ────┘
+ │
+┌─────────────────────────────▼─────────────────────────────────┐
+│ dot-daemon (Node 24) │
+│ gateway: HTTP (static UI, /health) + WebSocket protocol v1 │
+│ white-label layer: identity prompt, event sanitizer │
+│ agent supervisor: spawns and restarts the agent process │
+└─────────────────────────────┬─────────────────────────────────┘
+ │ stdin/stdout JSONL (Pi RPC)
+┌─────────────────────────────▼─────────────────────────────────┐
+│ gentle-shell --mode rpc --session-dir ~/.gentle-dot/sessions │
+│ Pi + Gentle extensions + Engram (unchanged, configured auth) │
+└───────────────────────────────────────────────────────────────┘
+```
+
+Repository layout (pnpm workspace):
+
+```
+packages/protocol shared TypeScript types for protocol v1 (client <-> daemon)
+packages/daemon supervisor, gateway, white-label layer, CLI `gentle-dot`
+packages/ui React + Vite web UI (served by the daemon, embedded by Tauri)
+apps/desktop Tauri 2 shell (Rust) for macOS
+docs/ design, deployment guide, security checklist
+```
+
+### Why these choices
+
+- **Pi RPC subprocess, not the SDK in process.** Gentle Shell is a launcher with its own home, auth, and extension loading. Spawning `gentle-shell --mode rpc` reuses all of it unchanged and isolates crashes from the daemon. Verified on 2026-10-08: the RPC process loads the Gentle extensions (82 commands) and answers `get_state`.
+- **One daemon, many faces.** The desktop app and the browser are thin clients over the same WebSocket protocol, so the VPS story is "run the same daemon in Docker".
+- **Tauri 2.** Native webview (small app), shares the React UI with the web, and has first-class tray, always-on-top windows, and global shortcuts.
+
+## 3. Agent supervisor
+
+- Spawns `gentle-shell --mode rpc --session-dir <dataDir>/sessions --append-system-prompt <identity file>` with `cwd` = configured workspace (default: home directory).
+- Parses stdout with strict LF framing on a byte stream. Never Node `readline` (it splits on U+2028/U+2029, which are valid inside JSON).
+- Correlates commands by `id`; stdout records without `id` are session events.
+- Reads stderr only as diagnostics (logged, never parsed).
+- On unexpected exit: state `restarting`, exponential backoff (1s, 2s, 4s, max 30s), then respawn and `switch_session` to the last active session file.
+- On daemon shutdown: closes child stdin, waits up to 5s, then SIGTERM.
+- The executable is configurable (`GENTLE_DOT_AGENT_BIN`) so tests can use a fake agent that speaks the same JSONL protocol.
+
+## 4. Protocol v1 (client <-> daemon)
+
+Transport: WebSocket at `/ws`. The first message must be `{"type":"hello","token":"…","protocol":1}`; otherwise the socket closes with code 4401.
+
+Client to daemon:
+
+| type | fields | maps to Pi RPC |
+|---|---|---|
+| `send` | `text`, `requestId` | `prompt` (or `follow_up` while busy) |
+| `steer` | `text` | `steer` |
+| `abort` | — | `abort` |
+| `ui_response` | `requestId`, `value` \| `confirmed` \| `cancelled` | `extension_ui_response` |
+| `new_conversation` | — | `new_session` |
+| `list_conversations` | — | daemon reads the session dir |
+| `open_conversation` | `conversationId` | `switch_session` |
+| `get_history` | — | `get_messages` |
+
+Daemon to client:
+
+| type | meaning |
+|---|---|
+| `ready` | `agentState`, `conversationId`, `model` (display name only) |
+| `agent_state` | `starting` \| `idle` \| `thinking` \| `working` \| `needs_you` \| `restarting` \| `error` |
+| `message_delta` | assistant text delta for message `messageId` |
+| `message_done` | final assistant message |
+| `activity` | sanitized tool activity: `id`, `kind` (`read`, `edit`, `run`, `search`, `memory`, `delegate`, `other`), `title`, `status` |
+| `ask` | sanitized `extension_ui_request` dialog: `requestId`, `method` (`select`, `confirm`, `input`, `editor`), `title`, `message`, `options`, `timeoutMs` |
+| `toast` | sanitized `notify` |
+| `history` | conversation messages for rendering |
+| `error` | `code`, `message` safe for the user |
+
+Every daemon message carries `seq` (monotonic per connection) so the UI can detect gaps and request `get_history`.
+
+## 5. White-label layer
+
+- **Identity**: `--append-system-prompt` with `identity.md`: the assistant is "Gentle Dot", a personal assistant; it must not mention Gentle Shell, Pi, el Gentleman, ODD, or Engram by name, and describes them as "my workflow" and "my memory" when needed. It keeps every behavior.
+- **Event sanitizer** (pure function, unit-tested): renames or drops branding in `notify`, `setStatus`, `setWidget`, `setTitle`; drops terminal-only requests; maps tool names to activity kinds and neutral titles (for example `mem_search` -> `memory` "Checking my notes").
+- **Commands**: `gentle:*` slash commands are never exposed; the UI has no command palette in this version.
+- **Errors**: provider or process errors become neutral messages; raw details go to the daemon log only.
+
+## 6. User experience
+
+### The Dot (collapsed)
+
+- A 56 px circular orb, always on top, draggable, snaps to the nearest screen edge; position is persisted.
+- The state is shown by motion and color:
+ - `idle`: slow breathing glow
+ - `thinking`: orbiting particle
+ - `working`: steady pulse with a small kind icon
+ - `needs_you`: amber ring with a badge
+ - `restarting` and `error`: grey and red ring
+- Click, the global shortcut `⌥ Space`, or the menu bar item expands it.
+
+### The panel (expanded)
+
+- 420 × 640 px, rounded 20 px, translucent (macOS vibrancy), anchored to the Dot.
+- Header: conversation title, new-conversation button, conversations list, collapse.
+- Body: message list with streaming Markdown and code blocks; activity rows are collapsed one-liners grouped under the assistant turn ("Read 3 files · Ran tests").
+- Ask cards: when the agent needs the user, an inline card with the question and buttons (select and confirm) or a text field (input and editor). The Dot turns amber until the user answers.
+- Composer: multiline, Enter sends, Shift+Enter adds a new line. While the agent works, the composer offers "Stop", and sending a message steers the current run.
+- `Esc` collapses back to the Dot; the conversation keeps running.
+
+### Menu bar
+
+- Template icon with a state dot.
+- Menu: Open (`⌥ Space`), New conversation, Open in browser, Restart assistant, Launch at login (toggle), Quit.
+
+### Web
+
+- The same UI at `http://127.0.0.1:4317`, full-height layout without the orb. The token is passed once through `/#token=…` and stored in `sessionStorage`.
+
+### Visual system
+
+- Dark-first, with a light theme that follows the system setting.
+- Tokens:
+ - `--bg` `#0E0F13`
+ - `--surface` `rgba(28,30,38,0.72)`
+ - `--text` `#ECEDEF`
+ - `--muted` `#8A8F98`
+ - `--accent` `#7C5CFF`
+ - `--amber` `#F5A524`
+ - `--danger` `#F0506E`
+- Type: system UI (SF Pro), 14/20 body, 12/16 meta; monospace SF Mono for code.
+- Motion: 180 ms ease-out for expand and collapse; the Dot animations respect "Reduce motion".
+
+## 7. Recovery
+
+- Pi sessions persist under `~/.gentle-dot/sessions`, and the daemon reopens the last active one after any restart.
+- After a crash, the turn that was in flight is lost. The conversation history remains, and the UI shows "I was interrupted. Continue?" with a Continue button that sends "Continue where you left off."
+- Engram keeps decisions and progress across conversations; the Gentle workflow already consults it when resuming.
+- Pi Durable is reconsidered only for unattended or scheduled work.
+
+## 8. Security (local)
+
+- The daemon binds `127.0.0.1` only. A random 256-bit token is stored in `~/.gentle-dot/token` (mode 0600). The desktop app reads it; the browser receives it once by URL fragment.
+- WebSocket upgrades check `Origin` against an allowlist (`http://127.0.0.1:4317`, `tauri://localhost`).
+- The VPS guide requires HTTPS, a reverse proxy with authentication, and a dedicated Docker container with no access to personal machines.
+
+## 9. Configuration
+
+`~/.gentle-dot/config.json`, all optional:
+
+```json
+{ "port": 4317, "workspace": "~", "shortcut": "Alt+Space", "launchAtLogin": false }
+```
+
+Environment overrides: `GENTLE_DOT_PORT`, `GENTLE_DOT_DATA_DIR`, `GENTLE_DOT_AGENT_BIN`, `GENTLE_DOT_WORKSPACE`.
diff --git a/odd/tasks/gentle-dot.md b/odd/tasks/gentle-dot.md
new file mode 100644
index 0000000..df9831f
--- /dev/null
+++ b/odd/tasks/gentle-dot.md
@@ -0,0 +1,60 @@
+# Gentle Dot — always-on desktop and web assistant backed by Gentle Shell
+
+Objective: a local, always-available assistant (floating Dot on macOS, menu bar, global shortcut, and browser) whose hidden engine is Gentle Shell with Engram. Design: `docs/design.md`.
+Branch: `feat/gentle-dot` · Delivery strategy: `single-pr` (user choice, L7; forecast ~3,500 authored lines, recorded as a size exception) · Test runner: Vitest (`pnpm test`), Playwright (`pnpm e2e`), `cargo test` for `apps/desktop`.
+
+## Specs
+
+- **S1 — Always available on the Mac desktop.** User: "un asistente que esté todo el tiempo disponible, que puedas levantarlo, por así decirlo, y ejecutarlo, por ejemplo, desde el escritorio, que esté flotando ahí en el escritorio, que lo puedas convocar también, no sé, en la barra de tareas". "Vamos a empezar con Mac, al principio."
+ - Acceptance: a Tauri 2 macOS app shows a floating, always-on-top, draggable Dot (design §6). It also has a menu bar item with the menu listed in §6 and a global shortcut (default `⌥ Space`) that expands and collapses the panel. The Dot position persists across restarts.
+ - Checks: `cargo test` for config and position persistence; a manual macOS checklist (T9) with observed results.
+- **S2 — Also from a web page.** User: "también que lo puedas levantar desde una web, también podría ser, sin ningún tipo de problema".
+ - Acceptance: the daemon serves the same React UI at `http://127.0.0.1:4317`. A browser with the token can chat, answer asks, and switch conversations exactly like the desktop panel.
+ - Checks: Playwright against the daemon with the fake agent.
+- **S3 — Gentle Shell runs behind it, unchanged.** User: "la idea es que por detrás corra GentlyAI, ¿bien? Gentle Shell, en este caso." "el agente va a hacer todo como lo hace Gentle Shell, literalmente. Todo lo mismo, usando Engram, usando todo."
+ - Acceptance: the daemon spawns `gentle-shell --mode rpc` with the Gentle extensions loaded and its existing configuration and auth. No Gentle Shell source is modified.
+ - Checks: an integration test with the real binary asserts that `get_state` succeeds and that `get_commands` lists the Gentle commands. Tag it `@real-agent`; it is skipped when `gentle-shell` is absent.
+- **S4 — The user does not know it is Gentle Shell.** User: "pero que el usuario no lo sepa."
+ - Acceptance: identity is appended through `--append-system-prompt` (design §5). The sanitizer removes Gentle, Pi, el Gentleman, ODD, and Engram names from every UI-bound event. `gentle:*` commands are never exposed, and asked "who are you", the agent answers as Gentle Dot.
+ - Checks: unit tests for the sanitizer over recorded real events; one `@real-agent` test that asserts the identity answer contains "Gentle Dot" and none of the hidden names.
+ - Assumption: the `gentle-shell` launcher forwards `--append-system-prompt` to Pi. T4 verifies it first; if it does not, T4 stops with **Needs your decision**.
+- **S5 — Resume after a cut.** User: "Lo que tú decías de que si se corta, después no puede volver, con Engram sí es que se puede volver. porque la gente lo primero que va a hacer es ir a consultar a Engram para continuar. o si no tiene los datos de la misma sesión donde él existe."
+ - Acceptance: sessions persist in `~/.gentle-dot/sessions`. After the agent process dies, the supervisor respawns it with backoff and reopens the same conversation. The UI shows "I was interrupted. Continue?" with a Continue action (design §7), and Engram stays enabled.
+ - Checks: an integration test kills the fake agent mid-run and asserts the respawn, the same conversation id, the history intact, and the interruption prompt.
+- **S6 — Local only, verified working.** User: "No lo vamos a desplegar en HostGator, solamente lo vamos a hacer a nivel local para probar y demás, bien, que todo funcione. Es más, quiero que vos también te fijes si funciona, ¿sí? Que todo ande correctamente."
+ - Acceptance: everything binds `127.0.0.1` with token auth (design §8). The agent itself runs the full verification: unit, integration, Playwright, and `@real-agent` tests, plus the desktop app build and launch. Every result is recorded in the Log; no deployment is performed.
+ - Checks: T9.
+- **S7 — VPS deployment explained, not executed.** User: "si tengo que hacer un video para HostGator o algo explicando esto, podría decirle, lo podés, por ejemplo, subir en la VPS de HostGator, taca taca taca, ¿bien? sin ningún tipo de drama."
+ - Acceptance: `docs/deploy-vps.md` covers the Dockerfile, `docker compose` service, reverse proxy with HTTPS and authentication, token handling, and the security warnings. It closes with a short step list suitable for a video.
+ - Checks: `docker build` of the image succeeds locally if Docker is available; otherwise the build is reported as not run.
+- **S8 — Design defined before implementation.** User: "quiero que me hagas un diseño, que me hagas ya todas las especificaciones, todo y ya lo dejes en el ODD". "dejamos todo, todo definido, cosa que la implementación sea muy bonita."
+ - Acceptance: `docs/design.md` holds the architecture, protocol v1, white-label layer, UX, visual system, recovery, and security, and this document holds the specs and tasks.
+ - Checks: structural readback (done in T0).
+
+## Tasks
+
+| ID | Specs | Route | Status | Commit / evidence | Scope |
+|---|---|---|---|---|---|
+| T0 | S8 | inline | done (uncommitted) | readback OK; no commit yet | Design (`docs/design.md`) and this plan |
+| T1 | S3, S6 | inline | pending | — | Scaffold the pnpm workspace (`packages/protocol`, `packages/daemon`, `packages/ui`, `apps/desktop` placeholder), TypeScript strict, Vitest, lint, README |
+| T2 | S3, S5 | inline | pending | — | Agent supervisor: spawn, strict JSONL framing, id correlation, fake agent for tests, restart with backoff, reopen last session |
+| T3 | S2, S6 | inline | pending | — | Gateway: HTTP static + `/health`, WebSocket protocol v1, token + Origin checks, Pi RPC mapping (design §4) |
+| T4 | S4 | inline | pending | — | White-label: verify `--append-system-prompt` passthrough, `identity.md`, event sanitizer, tool-kind mapping, error neutralization |
+| T5 | S2 | inline (writer only if parallel with T7) | pending | — | Web UI: chat, streaming Markdown, activity rows, conversations, composer with Stop/steer, visual tokens |
+| T6 | S2, S4, S5 | inline | pending | — | Ask cards (select/confirm/input/editor with timeout), toasts, interrupted-run Continue prompt, reconnect with `seq` gap recovery |
+| T7 | S1 | inline (writer only if parallel with T5) | pending | — | Tauri 2 app: tray menu, floating Dot window, expand panel, `⌥ Space` shortcut, daemon spawn/attach, position persistence, launch at login |
+| T8 | S7 | inline | pending | — | `Dockerfile`, `compose.yaml`, `docs/deploy-vps.md`, security checklist, video step list |
+| T9 | S1–S6 | delegated verifier (high risk: process supervision, auth) | pending | — | Full verification: unit, integration, Playwright, `@real-agent`, `tauri build` + launch, manual macOS checklist with observed results |
+
+Environment notes: Node v24.14.1 and pnpm are present. `cargo` is on PATH but `rustc` is not, so T7 must first install or repair the Rust toolchain (rustup) and asks before installing. Xcode is present.
+
+## Log
+
+- **L1 (2026-10-08, user, original request):** "quiero hacer algo, nuestro propio https://www.copilotkit.ai/opendots pero con gentle ai, se podra hacer algo asi que por detras use gentle shell ? con nuestro propio diseño y tambien evalua si pi durable vale la pena o engram ya esta bien"
+- **L2 (2026-10-08, user):** "Lo que yo quiero es un asistente, ¿bien? Es un asistente que esté todo el tiempo disponible, que puedas levantarlo, por así decirlo, y ejecutarlo, por ejemplo, desde el escritorio, que esté flotando ahí en el escritorio, que lo puedas convocar también, no sé, en la barra de tareas, algo así, ¿bien? Vamos a empezar con Mac, al principio. Entonces, esa sería la idea principal. Si no, también que lo puedas levantar desde una web, también podría ser, sin ningún tipo de problema, ¿bien? Que lo puedas levantar, desplegar, por ejemplo, en HostGator, se podría hacer sin ningún tipo de drama. y lo puedas también ejecutar desde ahí. Entonces puedes acceder a esa gente desde cualquier lugar. Bien, una cosa sí podríamos hacer. No sé qué te parece. Y la idea es que por detrás corra GentlyAI, ¿bien? Gentle Shell, en este caso. pero que el usuario no lo sepa. Entonces, el agente va a hacer todo como lo hace Gentle Shell, literalmente. Todo lo mismo, usando Engram, usando todo. Lo que tú decías de que si se corta, después no puede volver, con Engram sí es que se puede volver. porque la gente lo primero que va a hacer es ir a consultar a Engram para continuar. o si no tiene los datos de la misma sesión donde él existe."
+- **L3 (2026-10-08, user):** "No, no, lo que vamos a hacer es lo siguiente, mirá. No lo vamos a desplegar en HostGator, solamente lo vamos a hacer a nivel local para probar y demás, bien, que todo funcione. Es más, quiero que vos también te fijes si funciona, ¿sí? Que todo ande correctamente. Quiero que me crees un diseño y después yo, si tengo que hacer un video para HostGator o algo explicando esto, podría decirle, lo podés, por ejemplo, subir en la VPS de HostGator, taca taca taca, ¿bien? sin ningún tipo de drama. Entonces, yo lo que quiero ahora es que me hagas un diseño, que me hagas ya todas las especificaciones, todo y ya lo dejes en el ODD, porque vamos a tener que hacer con el ODD, es largo esto, ¿bien? y nada, dejamos todo, todo definido, cosa que la implementación sea muy bonita. ¿Te parece?"
+- **L4 (2026-10-08, user decisions):** Repository: "Repo nuevo ~/work/gentle-assistant (Recomendado)". Name: "Gentle Dot". Desktop: "Tauri 2 (Recomendado)".
+- **L5 (2026-10-08, evidence):** `gentle-shell --mode rpc --no-session` returned `get_state` success (model reported) and `get_commands` with 82 commands including `gentle:*`, and emitted `extension_ui_request` `setStatus`/`setWidget`/`notify` at startup, so branding reaches RPC clients and S4 needs the sanitizer. Pi RPC docs: `custom()` returns undefined in RPC mode, while `select`/`confirm`/`input`/`editor`/`notify`/`setStatus`/`setWidget`/`setTitle` are forwarded. `extensions/ask-user-choice.ts` already falls back to `ctx.ui.select` + `ctx.ui.input` for RPC hosts. Pi CLI has `--append-system-prompt` and `--session-dir`.
+- **L6 (2026-10-08, decision):** Pi Durable deferred. Recovery relies on persisted Pi sessions plus Engram, per L2; it is reconsidered only for unattended or scheduled work.
+- **L7 (2026-10-08, user):** "Un solo pr, instala lo que necesites y dale nomás" — plan approved, delivery `single-pr` with size exception, installs authorized (Rust stable via rustup).
+- **Next step:** T1.