diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8c30efb..5a9c83e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,263 +1,218 @@ # Architecture -Waggle is a monorepo with **28 packages** under `packages/` organized around a layered architecture: the memory substrate, agent intelligence, server API, and UI presentation. This document covers the package structure, data flow, and extension points. +How the community edition of Waggle is put together: the parts, how a chat turn flows through +them, where data lives and how a release is built. The decisions behind it are in +[`docs/oss/adr/`](oss/adr/README.md); [`AGENTS.md`](../AGENTS.md) lists the status of every +package. -> **Note:** memory goes through `@waggle/memory-contract`, implemented on local -> mem0 by `@waggle/memory-mem0` (ADR-0007). The React UI is **not** a package — it -> lives in `apps/web/src`. There is no `@waggle/ui` package. This document predates -> the community edition and is rewritten in P2.4. - -## Package Overview +## Overview ``` -waggle-os/ - apps/ - web/ # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react) - browser-ext/ # Browser extension (unpacked; not an npm workspace) - packages/ - # Product packages (MIT) - agent/ # Agent loop, tools, sub-agents, workflows, trust, hooks, personas, evolution - core/ # Config, vault (secrets), cron, file store, telemetry, compliance/audit - server/ # Fastify API server, local + team routes, daemons, KVARK client, scheduler - shared/ # Shared types, Zod schemas, tiers, MCP catalog - marketplace/ # Marketplace catalog, installer, security gate, sync - optimizer/ # Prompt optimization (GEPA engine) - weaver/ # Memory consolidation daemon - waggle-dance/ # Swarm orchestration protocol - worker/ # Background task processing (BullMQ) - sdk/ # Plugin/skill SDK, capability packs, starter skills - cli/ # Command-line REPL - launcher/ # AI-tool launcher / dock backend - memory-contract/ # MemoryStore interface, record model, capability map - memory-mem0/ # MemoryStore on local mem0 - sidecar/ # Node.js sidecar for Tauri desktop app - app/ # Tauri 2.0 desktop shell (Rust + WebView2) — loads the apps/web build + Browser tab or Tauri window + ┌──────────────────────────┐ + │ Web UI (apps/web, React) │ + └────────────┬─────────────┘ + │ HTTP + Server-Sent Events, bearer session token + ▼ + ┌─────────────────────────────────────────────────────────────┐ + │ Sidecar: Fastify on Node.js, 127.0.0.1:3333 │ + │ (packages/server/src/local) │ + │ │ + │ agent runtime ─────── built-in provider proxy ──► provider │ + │ (packages/agent) (/v1/chat/completions) APIs or │ + │ Ollama │ + │ MemoryStore ──► @waggle/memory-mem0 ──► /memory/ │ + │ WaggleDB ─────► /waggle.db │ + │ vault ────────► /vault.json │ + │ connectors, channels, scheduler, marketplace, skills │ + └─────────────────────────────────────────────────────────────┘ ``` -## Package Details +Everything runs on the user's computer. The only outside calls are the ones the user sets up: +model providers, connectors, messaging channels, marketplace sources, downloads of local +models and the embedding model, and analytics if the user allows them. -### @waggle/memory-contract and @waggle/memory-mem0 +## Parts -`MemoryStore` (remember, search, list, get, update, forget, history) with its record -model and capability map, and its implementation on the open-source mem0 library, -running locally in the sidecar (ADR-0007). +### Web UI (`apps/web`) -### @waggle/core +React 19, TypeScript, Vite 6, Tailwind CSS 3.4 and Radix UI primitives. It is an application, +not a package. `npm run build` builds it into the root `dist/`, which the sidecar serves; the +desktop build uses `apps/web/dist`. -The foundation layer for the desktop/server runtime. Zero network dependencies. +The UI talks to the sidecar over HTTP, with Server-Sent Events for chat streaming and +notifications. Every `/api/*` request carries a bearer session token. A page served by the +sidecar gets the token from `GET /api/auth/session-token`, which answers same-origin requests +only; the desktop window gets it through a per-launch credential from the Tauri shell. -- **WaggleConfig**: Configuration management (`~/.waggle/config.json`). Provider keys, default model, team server config. -- **Vault**: AES-256-GCM encrypted secret storage. Stores API keys, connector credentials, and sensitive metadata. -- **MultiMind**: Manages personal + workspace minds simultaneously — routes searches to both and merges results. -- **FileStore**: Workspace filesystem access with a segment-boundary + symlink-aware containment guard and a secret deny-list (see the [threat model](../THREAT_MODEL.md)). -- **CronStore**: Schedule management for the cron service. CRUD on cron expressions with last/next run tracking. -- **ImportParser** (`memory-import.ts`): parses ChatGPT and Claude export files into importable knowledge items. -- **Telemetry / Compliance**: telemetry pipeline and compliance reporting (`compliance/`). +Product analytics (PostHog) start only after the user allows them, and only in builds that carry +a key in `VITE_POSTHOG_KEY` (ADR-0006). -### @waggle/agent +### Sidecar (`packages/server/src/local`) -The intelligence layer. Orchestrates tool execution, sub-agents, and workflows. +A Fastify server on Node.js. In development it runs from TypeScript source with tsx; for +release it is bundled into one `service.js` with esbuild. It listens on `127.0.0.1` port 3333 +by default (`WAGGLE_PORT`, `WAGGLE_HOST`), rejects requests whose `Host` header is not local, +and serves the web UI from `WAGGLE_FRONTEND_DIR` or the root `dist/`. -- **AgentLoop**: Core loop that sends messages to the LLM, parses tool calls, executes tools, and streams results. Supports up to 200 turns per conversation. -- **Tools (97+)**: Organized across 12 categories: - - System tools: `bash`, `read_file`, `write_file`, `edit_file`, `search_files`, `search_content`, `list_directory` - - Memory tools: `search_memory`, `save_memory`, `forget_memory` - - Web tools: `web_search`, `web_fetch` - - Git tools: `git_status`, `git_diff`, `git_log`, `git_commit` - - Plan tools: `create_plan`, `add_plan_step`, `execute_step`, `show_plan` - - Document tools: `generate_docx` - - Sub-agent tools: `spawn_agent`, `coordinate_agents` - - Skill tools: dynamically generated from installed skills - - KVARK tools: `kvark_search`, `kvark_ask_document`, `kvark_feedback`, `kvark_action` - - Team tools: `request_team_capability`, `assign_task`, `update_task` - - Audit tools: `audit_trail`, `trust_assessment` - - Connector tools: dynamically generated from connected services -- **CapabilityRouter**: Routes user intents to the appropriate tool or workflow based on context. -- **WorkflowComposer**: Dynamically composes multi-step workflows from templates. -- **Workflow Templates**: `research-team` (parallel research), `review-pair` (draft + review), `plan-execute` (plan + execute steps). -- **SubagentOrchestrator**: Manages sub-agent lifecycle -- spawning, monitoring, result collection. -- **CommandRegistry**: Slash command registration and execution (14 commands). -- **HookRegistry**: Event-driven hooks (before/after tool calls, session start/end, etc.). -- **Personas**: 8 predefined agent configurations with system prompts and tool presets. -- **TrustModel**: Assesses capability risk level, trust source, and approval class. -- **SkillRecommender**: Context-aware skill suggestions based on conversation content. +It holds: -### @waggle/server +- the HTTP routes (`routes/`) for chat, workspaces, sessions, memory, settings, vault, skills, + plugins, connectors, marketplace, automations and the rest; +- the **built-in provider proxy** (`routes/anthropic-proxy.ts`): an OpenAI-compatible + `/v1/chat/completions` endpoint that translates Claude requests to Anthropic's Messages API + and forwards requests for other providers to their OpenAI-compatible APIs. The agent loop and + memory extraction call cloud models through it (or through LiteLLM when the user runs it); +- the **managed Ollama runtime** (`managed-ollama-runtime.ts`): downloads the official Ollama + build, checks its SHA-256 and size, and runs it on `127.0.0.1:11434` with models in + `/models/ollama`; +- the scheduler for automations (`cron.ts`), notifications, held actions and approvals; +- messaging channels (`channels/`): Telegram, Discord, Slack, and WhatsApp through + `whatsapp-web.js` (ADR-0005); +- the memory store and background fact extraction (`memory-runtime.ts`, + `memory-extraction.ts`). -The API layer. Fastify server exposing 29 route modules. +An optional LiteLLM proxy runs only when `config.json` contains `"litellm": { "enabled": true }`, +on the user's own Python. Nothing else needs Python. -- **Local Server** (`src/local/`): Solo mode on localhost:3333. Routes for chat, workspaces, sessions, memory, settings, vault, skills, plugins, connectors, marketplace, cron, fleet, etc. -- **InstallAuditStore** (`src/local/install-audit.ts`): append-only capability-install trail (proposed / approved / installed / rejected / uninstalled) in `waggle.db`, shown in the Audit and Activity tabs. -- **Team Server** (`src/routes/`): Multi-user mode with PostgreSQL (Drizzle ORM), Redis, Clerk auth, and WebSocket presence. -- **SSE Streaming**: Chat responses stream via Server-Sent Events. -- **Anthropic Proxy**: Built-in `/v1/chat/completions` endpoint that translates OpenAI format to Anthropic API. -- **KVARK Client** (`src/kvark/`): HTTP facade for enterprise retrieval. User-level Bearer tokens. -- **Daemons**: Background processes (memory consolidation, proactive checks). -- **Scheduler** (`src/scheduler/`): LocalScheduler that ticks cron schedules and dispatches jobs. -- **ConnectorRegistry**: Registers and manages 29 native connectors. Generates agent tools from connected services. -- **Session Manager**: Manages parallel workspace sessions for Mission Control. -- **Notification System**: Event bus + SSE stream for real-time notifications (cron, approval, task, agent events). +### Agent runtime (`packages/agent`) -### apps/web (UI) +The agent loop (`agent-loop.ts`), the orchestrator that builds the system prompt and recalls +memory (`orchestrator.ts`), personas (`persona-data.ts`, `personas.ts`), tools, slash +commands (`commands/`), sub-agents and workflow templates, connectors (`connectors/`), MCP +client support (`mcp/`), the injection scanner and cost tracking (`cost-tracker.ts`). -The React UI is an application, not a package — it lives in `apps/web/src` -(React 19 + Vite + Tailwind 4 + base-ui/react). There is no `@waggle/ui` -package. The desktop binary (`app/`) loads the `apps/web` build. Representative -surfaces: +### Other packages -- **ChatArea**: Main conversation interface with streaming, tool cards, approval gates, and file upload. -- **MemoryBrowser**: Frame list with search, importance filters, and knowledge graph visualization. -- **WorkspaceHome**: Context-rich home screen with summary, decisions, threads, and suggestions. -- **Settings**: Tabbed settings (Models, Permissions, Vault, Appearance, Advanced). -- **Cockpit**: System dashboard showing health, schedules, runtime stats, connectors, trust audit. -- **Capabilities**: Skill/pack browser with install state and family grouping. -- **Events**: Tool event log with grouping and completion animations. -- **Onboarding**: First-run setup flow (API key, workspace creation, starter skills, import). +| Package | Role | +|---|---| +| `@waggle/core` | Config (`config.json`), the vault, `WaggleDB` (`waggle.db`), workspaces, file storage, embeddings, local telemetry, logger | +| `@waggle/shared` | Shared types, Zod schemas, the MCP server catalog | +| `@waggle/memory-contract` | The `MemoryStore` interface, record model, capability map, an in-memory store and the compatibility suite | +| `@waggle/memory-mem0` | `MemoryStore` on the open-source mem0 library | +| `@waggle/marketplace` | Marketplace catalog (SQLite with full-text search), installer, security scan, sync | +| `@waggle/sdk` | Skill and plugin SDK, starter skills, capability packs | +| `@waggle/cli` | A terminal REPL on the same memory store and `waggle.db` | +| `@waggle-ai/waggle` (`packages/launcher`) | The server installer (`install`, `run`, `doctor`, `update`, `uninstall`) | -### @waggle/marketplace +`packages/team-server`, `packages/waggle-dance` and `packages/worker` hold team mode. They stay +in the repository but are not built, tested in the root run, or shipped (ADR-0003). +`apps/browser-ext` is not part of the release. -Marketplace infrastructure. SQLite-based catalog with FTS5 search. +### Desktop shell (`app/`) -- **MarketplaceDB**: 120+ packages across skills, plugins, and MCP servers. Auto-seeded from bundled data. -- **MarketplaceInstaller**: Install/uninstall with dependency tracking. -- **SecurityGate**: Heuristic-based security scanner. Scans for dangerous patterns before install. -- **MarketplaceSync**: Syncs catalog from configured sources. -- **Enterprise Packs**: KVARK-dependent packs (only available with enterprise connection). +A Tauri 2 shell in Rust (`app/src-tauri`). There is no separate frontend in `app/`: the window +loads the `apps/web` build. The shell: -### @waggle/waggle-dance +- starts the bundled sidecar with the bundled Node.js, on port 3333 or a free port if 3333 is + taken, waits until it reports ready, and stops it (SIGTERM first) when the app quits; +- writes the sidecar's output to `/logs/service.log`; +- keeps one instance running, adds a tray icon, and toggles the window with Ctrl+Shift+W; +- exposes a short list of IPC commands, allowed explicitly in `app/src-tauri/capabilities/`. -Swarm orchestration protocol for multi-agent coordination. +## A chat turn -- **Protocol**: Message types for task assignment, status updates, and result collection. -- **Dispatcher**: Routes work to available agents based on capability and load. -- **HiveQuery**: Broadcast queries across multiple agents for parallel investigation. +1. The UI sends `POST /api/chat` with the message, workspace and session, and reads the reply as + a Server-Sent Events stream. +2. The orchestrator recalls memory for the message (see [memory.md](memory.md)) and builds the + system prompt from the core rules, the persona, active skills and workspace context. +3. The agent loop calls the model through the built-in proxy (local Ollama models are called + directly). When the model asks for a tool, + the loop checks the approval rules (some actions wait for the user to approve), runs the + tool, and scans the tool output for prompt injection before the model sees it. External + output is passed to the model as data, never as instructions. +4. Text, tool calls and approval requests stream to the UI as they happen. +5. The session is appended to `/workspaces//sessions/.jsonl`. Costs go into + the execution traces in `waggle.db`, and the finished turn is queued for background fact + extraction. -### @waggle/worker +## Data -Background task processing for team mode. +One data directory per user: `WAGGLE_DATA_DIR`, or `~/.waggle`. [install.md](install.md#where-your-data-lives) +lists what it contains. -- **BullMQ Integration**: Redis-backed job queues. -- **Execution Strategies**: Parallel (fan-out), sequential (pipeline), and coordinator (master-worker). -- **Agent Worker**: Real `runAgentLoop` execution in background worker processes. +- **Memory** goes only through `MemoryStore` (`@waggle/memory-contract`). The shipped store keeps + its SQLite files in `/memory/`. Embeddings come from an in-process model, so memory + works offline. See [memory.md](memory.md). +- **`waggle.db`** holds Waggle's own data, which is not memory: automations, notifications, + held actions, skill hashes, thumbs feedback, cost tracking, the install audit trail, the file + index, and the profile card and task list per scope. +- **The vault** (`vault.json`, key in `.vault-key`) keeps provider keys and connector credentials, + each encrypted with AES-256-GCM. +- Local telemetry (`telemetry.db`, off by default) and the audit log (`audit.db`) have their own + files. -## Data Flow +The SQLite files are opened with better-sqlite3, a native module (ADR-0008). -### Chat Message Flow +## Models -``` -User Input - --> POST /api/chat (Fastify route) - --> Workspace context loaded (memory, state, persona) - --> System prompt composed (core + persona + skills + context) - --> runAgentLoop() invoked - --> LLM API call (Anthropic proxy or direct) - --> Tool calls parsed and executed - --> Approval gate check (if sensitive) - --> Tool result returned - --> Memory auto-save (decisions, facts, preferences) - --> SSE events streamed to client - --> Session persisted to .jsonl file - --> UI renders streaming response +- **Provider keys.** The user enters keys in Settings → Models or in the Vault. The proxy calls + the provider directly from the user's computer. +- **Local models.** The Waggle-managed Ollama runtime, or an Ollama the user already runs + (`OLLAMA_HOST`, default `http://localhost:11434`). +- **Cost tracking.** `CostTracker` prices each call and the execution traces are kept in + `waggle.db` (ADR-0004). Settings → Models sets an optional daily budget. + +## Installer and server archive + +The server installer (`packages/launcher`, ADR-0009) is one self-contained script that uses only +Node.js built-in modules. It downloads or reads a server archive, checks its SHA-256, unpacks it +into a per-user program directory and writes a `waggle-server` command. The command runs the +archive's own Node.js, so the user's Node.js is needed only for the first `npx` call. + +A server archive (`waggle-server--.tar.gz`) contains the same sidecar payload +the desktop app ships, the built web UI under `web/`, and a `manifest.json` with the version, +target and Node.js version. `run` starts `service.js` with the environment the desktop shell +uses, plus `WAGGLE_FRONTEND_DIR` pointing at `web/`. + +## How a release is built + +Native modules (`better-sqlite3`, `onnxruntime-node`) must match the bundled Node.js, so each +target is built on its own system (ADR-0008). The desktop build scripts in `app/package.json` +run one staging chain into `app/src-tauri/resources/`: + +1. `scripts/bundle-node.mjs` downloads and verifies the pinned Node.js (22.23.2); +2. `scripts/build-sidecar.mjs` bundles the sidecar into `service.js`; +3. `scripts/bundle-native-deps.mjs` copies the native modules for the target; +4. `scripts/stage-sidecar-deps.mjs` stages the packages the bundle keeps external; +5. `apps/web` is built with Vite into `apps/web/dist`; +6. `tauri build` produces the installers: `.exe` (NSIS) and `.msi` on Windows, `.app` and + `.dmg` on macOS, `.deb` and `.AppImage` on Linux. + +Then `npm run build:server-archive` (`scripts/build-server-archive.mjs`) packs the same staged +payload and `apps/web/dist` into the server archive for that target, with a `.sha256` next to it. + +```bash +npm ci +(cd app && npm ci) +(cd app && npm run tauri:build:mac:arm64) # or tauri:build:mac:x64, tauri:build:win, tauri:build +npm run build:server-archive # set TARGET_ARCH=x64 after an x64 macOS build ``` -### Memory Flow +The Windows build must run on Windows; see [docs/oss/build-windows.md](oss/build-windows.md). +The first community release is unsigned ([docs/oss/signing.md](oss/signing.md)). The release +workflow for the community edition is not set up yet, so releases are built by hand on each +system. -``` -Conversation - --> Agent detects important information - --> save_memory tool called - --> FrameStore.add() writes to workspace .mind - --> Embeddings generated (sqlite-vec) - --> Knowledge graph updated (entity extraction) +Shipped dependencies are checked for licenses that allow MIT distribution +(`npm run check:licenses`, and `cargo deny` for the Rust crates), and their notices are in +[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md). -Later search: - --> search_memory tool called - --> MultiMind.search() queries personal + workspace minds - --> FTS5 + vector similarity results merged - --> Top results injected into agent context -``` +## Extension points -### Workspace Startup Flow +- **Skills**: Markdown files with YAML frontmatter in `/skills/`, added to the system + prompt when active. See [guides/capabilities.md](guides/capabilities.md). +- **Plugins and MCP servers**: installed from the marketplace or a local directory. +- **Connectors**: classes in `packages/agent/src/connectors/`, registered in + `packages/server/src/local/setup-connectors.ts`. A connected service adds tools to the agent. +- **Slash commands**: `CommandDefinition`s in `packages/agent/src/commands/`, registered with the + `CommandRegistry`. +- **Memory backends**: an implementation of `MemoryStore` that passes the compatibility suite in + `@waggle/memory-contract`. -``` -Open workspace - --> GET /api/workspaces/:id/context - --> Load workspace mind (MindDB) - --> Read recent memory frames - --> Extract decisions from memories - --> Read session files (titles, summaries) - --> Extract progress items (tasks, completions, blockers) - --> Build workspace state summary - --> Generate contextual suggested prompts - --> UI renders Home screen -``` +## Security -## Extension Points - -### Adding a New Tool - -1. Define the tool in the appropriate category under `packages/agent/src/` -2. Follow the `ToolDefinition` interface: name, description, parameters (JSON Schema), handler function -3. Register the tool in the agent's tool list -4. If the tool is sensitive, add it to the approval gate check list - -### Adding a New Connector - -1. Implement the `ConnectorCapability` interface in `packages/server/src/services/connectors/` -2. Define `id`, `name`, `service`, `authType`, `connect()`, `healthCheck()`, and `generateTools()` -3. Register in `packages/server/src/local/index.ts` with `connectorRegistry.register()` -4. The connector's tools are automatically available when credentials are in the vault - -### Adding a Skill - -Create a markdown file in `~/.waggle/skills/`. The skill content is appended to the agent's system prompt. Use YAML frontmatter for metadata: - -```markdown ---- -name: my-skill -permissions: - - read_file - - web_search ---- -# My Skill - -Instructions for the agent... -``` - -### Adding a Slash Command - -1. Create a `CommandDefinition` in `packages/agent/src/commands/` -2. Implement `name`, `aliases`, `description`, `usage`, and `handler` -3. Register with `registry.register()` in the appropriate registration function - -### Adding a Workflow Template - -1. Define a factory function that returns a `WorkflowTemplate` with steps -2. Register in the `WORKFLOW_TEMPLATES` map in `packages/agent/src/` -3. Each step defines a role, instructions, and optional tool restrictions - -## Storage Locations - -| Data | Location | Format | -|------|----------|--------| -| Personal memory | `~/.waggle/default.mind` | SQLite | -| Workspace memory | `~/.waggle/workspaces/{id}/workspace.mind` | SQLite | -| Sessions | `~/.waggle/workspaces/{id}/sessions/*.jsonl` | JSON Lines | -| Tasks | `~/.waggle/workspaces/{id}/tasks.jsonl` | JSON Lines | -| File registry | `~/.waggle/workspaces/{id}/files.jsonl` | JSON Lines | -| Config | `~/.waggle/config.json` | JSON | -| Vault | `~/.waggle/vault.db` | SQLite (encrypted values) | -| Marketplace | `~/.waggle/marketplace.db` | SQLite | -| Skills | `~/.waggle/skills/*.md` | Markdown | -| Plugins | `~/.waggle/plugins/` | Package directories | -| Permissions | `~/.waggle/permissions.json` | JSON | - -## Security Model - -- **Vault**: AES-256-GCM encryption for all secrets. Keys never stored in plain text after vault migration. -- **Approval Gates**: Sensitive tool executions require explicit user approval. -- **SecurityGate**: Marketplace installs scanned for dangerous patterns. CRITICAL severity always blocked. -- **Content Hashing**: SHA-256 hashes detect unauthorized skill modifications. -- **Audit Trail**: Every capability install, uninstall, and security decision is recorded. -- **Input Validation**: All route parameters validated against path traversal and injection. -- **YOLO Mode**: Opt-in auto-approval, disabled by default. +The threat model, the controls and the known gaps are in [`THREAT_MODEL.md`](../THREAT_MODEL.md). +In short: the user is trusted, external content is not. Connector input, tool output and recalled +memory pass the injection scanner; secrets live in the vault; sensitive tools wait for approval; +the sidecar answers only local requests that carry the session token.