docs: rewrite the architecture overview for the community edition (P2.4)
Describe the web UI, the sidecar, the Tauri shell, waggle.db, the memory contract and mem0, models, the server installer and archive, and the staging chain that builds the desktop packages and the server archive. Drop the removed packages, KVARK, team mode, the .mind files and the knowledge graph.
This commit is contained in:
@@ -1,263 +1,218 @@
|
|||||||
# Architecture
|
# 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
|
## Overview
|
||||||
> 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
|
|
||||||
|
|
||||||
```
|
```
|
||||||
waggle-os/
|
Browser tab or Tauri window
|
||||||
apps/
|
┌──────────────────────────┐
|
||||||
web/ # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react)
|
│ Web UI (apps/web, React) │
|
||||||
browser-ext/ # Browser extension (unpacked; not an npm workspace)
|
└────────────┬─────────────┘
|
||||||
packages/
|
│ HTTP + Server-Sent Events, bearer session token
|
||||||
# Product packages (MIT)
|
▼
|
||||||
agent/ # Agent loop, tools, sub-agents, workflows, trust, hooks, personas, evolution
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
core/ # Config, vault (secrets), cron, file store, telemetry, compliance/audit
|
│ Sidecar: Fastify on Node.js, 127.0.0.1:3333 │
|
||||||
server/ # Fastify API server, local + team routes, daemons, KVARK client, scheduler
|
│ (packages/server/src/local) │
|
||||||
shared/ # Shared types, Zod schemas, tiers, MCP catalog
|
│ │
|
||||||
marketplace/ # Marketplace catalog, installer, security gate, sync
|
│ agent runtime ─────── built-in provider proxy ──► provider │
|
||||||
optimizer/ # Prompt optimization (GEPA engine)
|
│ (packages/agent) (/v1/chat/completions) APIs or │
|
||||||
weaver/ # Memory consolidation daemon
|
│ Ollama │
|
||||||
waggle-dance/ # Swarm orchestration protocol
|
│ MemoryStore ──► @waggle/memory-mem0 ──► <data>/memory/ │
|
||||||
worker/ # Background task processing (BullMQ)
|
│ WaggleDB ─────► <data>/waggle.db │
|
||||||
sdk/ # Plugin/skill SDK, capability packs, starter skills
|
│ vault ────────► <data>/vault.json │
|
||||||
cli/ # Command-line REPL
|
│ connectors, channels, scheduler, marketplace, skills │
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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
|
### Web UI (`apps/web`)
|
||||||
model and capability map, and its implementation on the open-source mem0 library,
|
|
||||||
running locally in the sidecar (ADR-0007).
|
|
||||||
|
|
||||||
### @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.
|
Product analytics (PostHog) start only after the user allows them, and only in builds that carry
|
||||||
- **Vault**: AES-256-GCM encrypted secret storage. Stores API keys, connector credentials, and sensitive metadata.
|
a key in `VITE_POSTHOG_KEY` (ADR-0006).
|
||||||
- **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/`).
|
|
||||||
|
|
||||||
### @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.
|
It holds:
|
||||||
- **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.
|
|
||||||
|
|
||||||
### @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
|
||||||
|
`<data>/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.
|
### Agent runtime (`packages/agent`)
|
||||||
- **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).
|
|
||||||
|
|
||||||
### 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`
|
### Other packages
|
||||||
(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:
|
|
||||||
|
|
||||||
- **ChatArea**: Main conversation interface with streaming, tool cards, approval gates, and file upload.
|
| Package | Role |
|
||||||
- **MemoryBrowser**: Frame list with search, importance filters, and knowledge graph visualization.
|
|---|---|
|
||||||
- **WorkspaceHome**: Context-rich home screen with summary, decisions, threads, and suggestions.
|
| `@waggle/core` | Config (`config.json`), the vault, `WaggleDB` (`waggle.db`), workspaces, file storage, embeddings, local telemetry, logger |
|
||||||
- **Settings**: Tabbed settings (Models, Permissions, Vault, Appearance, Advanced).
|
| `@waggle/shared` | Shared types, Zod schemas, the MCP server catalog |
|
||||||
- **Cockpit**: System dashboard showing health, schedules, runtime stats, connectors, trust audit.
|
| `@waggle/memory-contract` | The `MemoryStore` interface, record model, capability map, an in-memory store and the compatibility suite |
|
||||||
- **Capabilities**: Skill/pack browser with install state and family grouping.
|
| `@waggle/memory-mem0` | `MemoryStore` on the open-source mem0 library |
|
||||||
- **Events**: Tool event log with grouping and completion animations.
|
| `@waggle/marketplace` | Marketplace catalog (SQLite with full-text search), installer, security scan, sync |
|
||||||
- **Onboarding**: First-run setup flow (API key, workspace creation, starter skills, import).
|
| `@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.
|
A Tauri 2 shell in Rust (`app/src-tauri`). There is no separate frontend in `app/`: the window
|
||||||
- **MarketplaceInstaller**: Install/uninstall with dependency tracking.
|
loads the `apps/web` build. The shell:
|
||||||
- **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).
|
|
||||||
|
|
||||||
### @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 `<data>/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.
|
1. The UI sends `POST /api/chat` with the message, workspace and session, and reads the reply as
|
||||||
- **Dispatcher**: Routes work to available agents based on capability and load.
|
a Server-Sent Events stream.
|
||||||
- **HiveQuery**: Broadcast queries across multiple agents for parallel investigation.
|
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 `<data>/workspaces/<id>/sessions/<session>.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.
|
- **Memory** goes only through `MemoryStore` (`@waggle/memory-contract`). The shipped store keeps
|
||||||
- **Execution Strategies**: Parallel (fan-out), sequential (pipeline), and coordinator (master-worker).
|
its SQLite files in `<data>/memory/`. Embeddings come from an in-process model, so memory
|
||||||
- **Agent Worker**: Real `runAgentLoop` execution in background worker processes.
|
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
|
||||||
|
|
||||||
```
|
- **Provider keys.** The user enters keys in Settings → Models or in the Vault. The proxy calls
|
||||||
User Input
|
the provider directly from the user's computer.
|
||||||
--> POST /api/chat (Fastify route)
|
- **Local models.** The Waggle-managed Ollama runtime, or an Ollama the user already runs
|
||||||
--> Workspace context loaded (memory, state, persona)
|
(`OLLAMA_HOST`, default `http://localhost:11434`).
|
||||||
--> System prompt composed (core + persona + skills + context)
|
- **Cost tracking.** `CostTracker` prices each call and the execution traces are kept in
|
||||||
--> runAgentLoop() invoked
|
`waggle.db` (ADR-0004). Settings → Models sets an optional daily budget.
|
||||||
--> LLM API call (Anthropic proxy or direct)
|
|
||||||
--> Tool calls parsed and executed
|
## Installer and server archive
|
||||||
--> Approval gate check (if sensitive)
|
|
||||||
--> Tool result returned
|
The server installer (`packages/launcher`, ADR-0009) is one self-contained script that uses only
|
||||||
--> Memory auto-save (decisions, facts, preferences)
|
Node.js built-in modules. It downloads or reads a server archive, checks its SHA-256, unpacks it
|
||||||
--> SSE events streamed to client
|
into a per-user program directory and writes a `waggle-server` command. The command runs the
|
||||||
--> Session persisted to .jsonl file
|
archive's own Node.js, so the user's Node.js is needed only for the first `npx` call.
|
||||||
--> UI renders streaming response
|
|
||||||
|
A server archive (`waggle-server-<version>-<target>.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.
|
||||||
|
|
||||||
```
|
Shipped dependencies are checked for licenses that allow MIT distribution
|
||||||
Conversation
|
(`npm run check:licenses`, and `cargo deny` for the Rust crates), and their notices are in
|
||||||
--> Agent detects important information
|
[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md).
|
||||||
--> save_memory tool called
|
|
||||||
--> FrameStore.add() writes to workspace .mind
|
|
||||||
--> Embeddings generated (sqlite-vec)
|
|
||||||
--> Knowledge graph updated (entity extraction)
|
|
||||||
|
|
||||||
Later search:
|
## Extension points
|
||||||
--> search_memory tool called
|
|
||||||
--> MultiMind.search() queries personal + workspace minds
|
|
||||||
--> FTS5 + vector similarity results merged
|
|
||||||
--> Top results injected into agent context
|
|
||||||
```
|
|
||||||
|
|
||||||
### Workspace Startup Flow
|
- **Skills**: Markdown files with YAML frontmatter in `<data>/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`.
|
||||||
|
|
||||||
```
|
## Security
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Extension Points
|
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
|
||||||
### Adding a New Tool
|
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.
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user