diff --git a/docs/guides/capabilities.md b/docs/guides/capabilities.md index d1bcbdf..22b2823 100644 --- a/docs/guides/capabilities.md +++ b/docs/guides/capabilities.md @@ -1,211 +1,100 @@ -# Capabilities +# Skills, plugins and the marketplace -Capabilities are the extensions that make Waggle powerful: skills, plugins, MCP servers, workflow templates, hooks, and commands. This guide covers how to discover, install, and manage them. +Capabilities extend what the agent knows and can do. This guide covers the kinds of capability, +how to install them and how Waggle checks them. -## Capability Types +Most of the screens below appear at the **Everything** interface level (Settings → General). -| Type | What It Is | Storage | -|------|-----------|---------| -| **Skill** | Markdown file that extends the agent's system prompt with domain knowledge and instructions | `~/.waggle/skills/*.md` | -| **Plugin** | Structured package with a manifest that adds tools and behaviors | `~/.waggle/plugins/` | -| **MCP Server** | Model Context Protocol server that provides external tools | Configured in settings | -| **Workflow Template** | Multi-step agent orchestration (e.g., research-team, review-pair, plan-execute) | Built into `@waggle/agent` | -| **Hook** | Event-driven callback (before/after tool calls, session start/end, etc.) | Registered in agent state | -| **Command** | Slash command (`/research`, `/draft`, etc.) | Built into `@waggle/agent` | +## Kinds of capability -## Built-in Capability Packs +| Kind | What it is | Where it lives | +|---|---|---| +| Skill | A Markdown file with instructions and domain knowledge, added to the agent's prompt when active | `/skills/*.md` | +| Plugin | A package with a manifest that adds tools and skills | `/plugins/` | +| MCP server | A Model Context Protocol server that gives the agent external tools | Settings, MCP Hub | +| Workflow | A multi-agent recipe, such as `research-team`, `review-pair` or `plan-execute` | Built in, or created with `/workflow` | +| Command | A slash command such as `/research` or `/draft` | Built in ([reference](../reference/commands.md)) | -Waggle ships with 5 curated packs. Each pack bundles several skills that work together. +## Starter skills and capability packs -### Research Workflow +Waggle ships with starter skills in seven families: Writing & Docs, Research & Analysis, +Decision Support, Planning & Organization, Communication, Code & Engineering, and Creative & +Ideation. Install them one by one in **Skills Hub**, or as packs: -Skills for investigation and synthesis. Includes `research-synthesis`, `explain-concept`, and the `research-team` multi-agent workflow. +| Pack | Skills | +|---|---| +| Research Workflow | `research-synthesis`, `explain-concept`, `research-team` | +| Writing Suite | `draft-memo`, `compare-docs`, `extract-actions` | +| Planning Master | `daily-plan`, `task-breakdown`, `plan-execute`, `decision-matrix` | +| Team Collaboration | `catch-up`, `status-update`, `meeting-prep`, `review-pair` | +| Decision Framework | `decision-matrix`, `risk-assessment`, `retrospective` | -### Writing Suite +Installing a pack skips skills that are already installed. The "Team Collaboration" pack is a +set of skills for working with other people; it does not need team mode. -Skills for document creation and editing. Includes `draft-memo`, `compare-docs`, and `extract-actions`. +## Writing your own skill -### Planning Master - -Skills for task decomposition and execution. Includes `daily-plan`, `task-breakdown`, and the `plan-execute` workflow. - -### Team Collaboration - -Skills for coordination and communication. Includes `catch-up`, `status-update`, and `meeting-prep`. - -### Decision Framework - -Skills for structured decision-making. Includes `decision-matrix`, `risk-assessment`, and `retrospective`. - -## Installing Packs - -### From the UI - -1. Navigate to **Capabilities** in the sidebar (or click the grid icon) -2. Click **Browse Packs** -3. Each pack shows its skills, install state (available / incomplete / complete), and description -4. Click **Install** to install all skills in the pack at once -5. Already-installed skills are skipped - -### From the API - -```bash -# Install the Research Workflow pack -curl -X POST http://localhost:3333/api/skills/capability-packs/research-workflow - -# Install a single skill from the starter pack -curl -X POST http://localhost:3333/api/skills/starter-pack/draft-memo -``` - -## Installing Individual Skills - -### From the Starter Catalog - -1. Go to **Capabilities** > **Skills** -2. Browse by family: Writing & Docs, Research & Analysis, Decision Support, Planning & Organization, Communication, Code & Engineering, Creative & Ideation -3. Click **Install** on any skill -4. The skill is copied to `~/.waggle/skills/` and loaded immediately - -### Creating Custom Skills - -Skills are markdown files. Create a file in `~/.waggle/skills/`: +A skill is a Markdown file in `/skills/` (by default `~/.waggle/skills/`). Optional YAML +frontmatter gives it a name and other metadata: ```markdown -# My Custom Skill +--- +name: weekly-report +description: Write the weekly status report in our format +--- +# Weekly report -Instructions for the agent when this skill is active. - -## When to Use -- Trigger conditions - -## How to Respond -- Response format guidelines -- Quality standards +When asked for the weekly report: +- Start with the three most important changes. +- List risks with an owner each. +- Keep it under one page. ``` -Or use the API: - -```bash -curl -X POST http://localhost:3333/api/skills \ - -H "Content-Type: application/json" \ - -d '{"name": "my-skill", "content": "# My Skill\n\nInstructions here."}' -``` +You can also create and edit skills in **Skills Hub**. `/skills` lists the active skills in a +chat. ## Marketplace -The marketplace catalog contains 120+ packages across skills, plugins, and MCP servers from curated sources. +**Marketplace** lists skills, plugins and MCP servers from curated sources. Search it, read a +package's details and install it. `/marketplace search ` and +`/marketplace install ` do the same from a chat; `/marketplace sync` refreshes the catalog +from its sources. -### Searching +### Security scan -```bash -# Search by keyword -curl "http://localhost:3333/api/marketplace/search?query=research&limit=10" +Every marketplace install is scanned first for dangerous patterns, such as reading credentials, +unexpected network calls or destructive file operations. The result decides what happens: -# Filter by type -curl "http://localhost:3333/api/marketplace/search?type=skill&category=analysis" -``` +| Severity | Result | +|---|---| +| Clean, low | The install proceeds | +| Medium | The install proceeds with warnings | +| High | Blocked unless you confirm that you accept the risk | +| Critical | Always blocked | -Or use the `/marketplace search ` slash command in any workspace. +Installs, uninstalls and security decisions are recorded in the install audit trail in +`waggle.db`. -### Installing from Marketplace - -```bash -# Install by package ID -curl -X POST http://localhost:3333/api/marketplace/install \ - -H "Content-Type: application/json" \ - -d '{"packageId": 42}' -``` - -Or use `/marketplace install `. - -### Security Scanning - -Every marketplace install goes through the **SecurityGate** scanner. Results determine whether the install proceeds: - -| Severity | Action | -|----------|--------| -| CLEAN | Install proceeds immediately | -| LOW | Install proceeds, logged to audit trail | -| MEDIUM | Install proceeds with warnings in response | -| HIGH | Blocked unless `force=true` (override logged to audit) | -| CRITICAL | Always blocked, cannot override | - -### Syncing the Catalog - -```bash -# Sync from all configured sources -curl -X POST http://localhost:3333/api/marketplace/sync -``` - -Or use `/marketplace sync`. - -## Trust Model - -Waggle uses a multi-layer trust model: - -1. **Source trust** -- starter-pack skills are trusted by default; marketplace and user-created skills get assessed -2. **Content analysis** -- heuristic scan for dangerous patterns (credential access, network calls, file system mutations) -3. **Risk level** -- low, medium, high, critical based on what the capability does -4. **Approval class** -- standard (auto-approve), review (log), force-override (user acknowledged risk), blocked -5. **Content hash** -- SHA-256 hash of each skill file, checked at startup to detect unauthorized modifications - -### Audit Trail - -Every install, uninstall, and security decision is recorded in the audit store. View it: - -- **UI**: Capabilities > Cockpit > Trust Audit section -- **API**: `GET /api/audit/installs` - -### Hash Verification - -At startup, Waggle checks each installed skill's content hash against the stored hash. If a skill file was modified outside of Waggle, it is flagged in the hash status: - -```bash -curl http://localhost:3333/api/skills/hash-status -``` +If a skill or plugin you installed from the marketplace does not show up in the agent, restart +Waggle. The marketplace installer's reload request does not reach the running server yet. ## Plugins -Plugins are structured packages with manifests that can add tools and extend agent behavior. +A plugin is a directory with a manifest. Install one from the marketplace or from a local +directory, then enable or disable it. A disabled plugin stays installed but adds nothing to the +agent. -### Installing a Plugin +## MCP servers -```bash -curl -X POST http://localhost:3333/api/plugins/install \ - -H "Content-Type: application/json" \ - -d '{"sourceDir": "/path/to/my-plugin"}' -``` +**MCP Hub** shows the installed Model Context Protocol servers with their state, lets you start, +stop, test and remove them, and installs new ones from its catalog or from a server you +describe yourself. Catalog installs go through the same security scan as the marketplace. -### Enabling / Disabling +## Trust checks -```bash -# Enable -curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/enable - -# Disable -curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/disable -``` - -### Uninstalling - -```bash -curl -X DELETE http://localhost:3333/api/plugins/my-plugin -``` - -## Viewing Capability Status - -The **Cockpit** (accessible from the sidebar) shows a live dashboard of all capabilities: - -- **Plugins**: name, state, tool count, skill count -- **MCP Servers**: name, state, healthy status, tool count -- **Skills**: name, content length -- **Tools**: total count (native + plugin + MCP) -- **Commands**: all registered slash commands -- **Hooks**: registered count, recent activity log -- **Workflows**: available templates with step counts - -API equivalent: - -```bash -curl http://localhost:3333/api/capabilities/status -``` +- **Source**: starter skills are trusted; marketplace and your own skills are assessed. +- **Content scan**: the heuristic scan described above. +- **Approval**: capabilities that ask for risky actions go through the same approval rules as + any other tool call (Settings → Permissions). +- **Content hash**: Waggle records a SHA-256 hash of each installed skill and checks it at + startup, so a skill changed outside Waggle is flagged. diff --git a/docs/guides/connectors.md b/docs/guides/connectors.md index b40be2f..ad02591 100644 --- a/docs/guides/connectors.md +++ b/docs/guides/connectors.md @@ -1,195 +1,98 @@ -# Connectors +# Connectors and channels -Connectors let Waggle interact with external services -- GitHub, Slack, Google, Jira, and 25 others. Credentials are stored in the encrypted vault, and sensitive operations go through approval gates. +**Connectors** let the agent work with services you use, such as GitHub, Slack or Google Drive. +**Channels** let you talk to Waggle from a messaging app. Credentials for both are kept in the +encrypted Vault on your computer, and actions that change something go through approvals. -## Vault Setup +## The Vault -Before connecting any service, you need to understand the vault. The vault is Waggle's encrypted credential store, using AES-256-GCM encryption. It lives at `~/.waggle/vault.db` and is the single source of truth for all secrets. +The Vault stores provider keys, connector credentials and other secrets in +`/vault.json`. Each entry is encrypted with AES-256-GCM using a key kept in +`/.vault-key`. Open **Vault** to see the stored secrets (names only), add one, reveal a +value or delete it. -### Adding a Secret to the Vault +Provider keys added in Settings → Models land in the Vault too. -**From the UI:** -1. Go to **Settings** > **Vault** -2. Click **Add Secret** -3. Enter the name (e.g., `GITHUB_TOKEN`) and value -4. Click **Save** +## Native connectors -**From the API:** -```bash -curl -X POST http://localhost:3333/api/vault \ - -H "Content-Type: application/json" \ - -d '{"name": "GITHUB_TOKEN", "value": "ghp_your_token_here"}' -``` +Waggle has 30 built-in connectors: -### Suggested Keys +| Area | Connectors | +|---|---| +| Code | GitHub, GitLab, Bitbucket | +| Chat | Slack, Discord, Microsoft Teams | +| Email and calendar | Gmail, Google Calendar, Outlook (calendar and email), Email via SendGrid | +| Documents and files | Google Docs, Google Drive, Google Sheets, OneDrive, Microsoft OneNote, Dropbox, Notion, Confluence, Obsidian | +| Projects | Jira, Linear, Asana, Trello, Monday.com, Airtable | +| CRM | HubSpot, Salesforce, Pipedrive | +| Data | PostgreSQL | +| Other services | Composio, a bridge to many more services | -The vault suggests common API key names that are not yet configured: +### Connect a service -- `ANTHROPIC_API_KEY` -- LLM provider -- `OPENAI_API_KEY` -- LLM provider -- `GITHUB_TOKEN` -- GitHub API -- `SLACK_BOT_TOKEN` -- Slack Bot -- `JIRA_API_TOKEN` -- Jira Cloud -- `GOOGLE_API_KEY` -- Google services -- `TAVILY_API_KEY` -- Web search -- `BRAVE_API_KEY` -- Web search -- `SENDGRID_API_KEY` -- Email sending -- `GOOGLE_CALENDAR_TOKEN` -- Calendar access +1. Open **Connector Hub** (at the Everything interface level). +2. Choose the service and **Connect**. +3. Enter what the form asks for: a token, an API key, an email and token, a file path for + Obsidian, or a connection string for PostgreSQL. The form links to where the service issues + it. -## Native Connectors +When a service is connected, the agent gets tools for it, for example creating issues and +pull requests on GitHub or searching pages in Confluence. `/connectors` lists the connected +services in a chat. -Waggle registers 29 native connectors at startup. Each connector has a defined auth type and generates agent tools when credentials are available. +**Disconnect** removes the credentials from the Vault. Connector Hub also shows each +connector's health and a history of what was done with it. -| # | Connector | Service | Auth Type | -|---|-----------|---------|-----------| -| 1 | GitHub | GitHub API | Bearer token (PAT) | -| 2 | Slack | Slack Bot API | Bot token | -| 3 | Jira | Jira Cloud | Basic auth (email + API token) | -| 4 | Email (SendGrid) | SendGrid API | API key | -| 5 | Google Calendar | Google Calendar API | OAuth token | -| 6 | Discord | Discord Bot API | Bot token | -| 7 | Linear | Linear API | API key | -| 8 | Asana | Asana API | Bearer token | -| 9 | Trello | Trello API | API key | -| 10 | Monday | Monday.com API | API key | -| 11 | Notion | Notion API | Integration token | -| 12 | Confluence | Atlassian API | Basic auth | -| 13 | Obsidian | Local vault | File path | -| 14 | HubSpot | HubSpot API | Bearer token | -| 15 | Salesforce | Salesforce API | OAuth token | -| 16 | Pipedrive | Pipedrive API | API key | -| 17 | Airtable | Airtable API | Bearer token | -| 18 | GitLab | GitLab API | Bearer token (PAT) | -| 19 | Bitbucket | Bitbucket API | App password | -| 20 | Dropbox | Dropbox API | OAuth token | -| 21 | PostgreSQL | PostgreSQL | Connection string | -| 22 | Gmail | Gmail API | OAuth token | -| 23 | Google Docs | Google Docs API | OAuth token | -| 24 | Google Drive | Google Drive API | OAuth token | -| 25 | Google Sheets | Google Sheets API | OAuth token | -| 26 | MS Teams | Microsoft Graph API | OAuth token | -| 27 | Outlook | Microsoft Graph API | OAuth token | -| 28 | OneDrive | Microsoft Graph API | OAuth token | -| 29 | Composio | Composio Bridge | API key | +Composio keeps the credentials for the services behind it on Composio's side, not in Waggle's +Vault. -## Connecting a Service +## Approvals -### From the UI +When the agent wants to do something with an effect outside the chat, such as sending an email, +posting a message, creating a ticket or pushing a commit, it pauses and shows an approval card +with the tool and its input. Nothing happens until you choose **Approve** or **Deny**. -1. Open the **Cockpit** from the sidebar -2. Scroll to the **Connectors** section -3. Click **Connect** on the service you want -4. Enter your credentials (token, API key, or OAuth details) -5. Click **Save** +**Settings** → **Permissions** sets how often Waggle asks: -The connector status changes from "Disconnected" to "Connected". +| Mode | Behavior | +|---|---| +| Ask every time | Approve every write, edit and other action that changes something | +| Ask only for risky | Writes and edits pass; pushes, installs and cross-workspace actions still ask | +| Never ask | Everything passes except a fixed list of critical actions | -### From the API +## Channels -```bash -# Connect GitHub with a personal access token -curl -X POST http://localhost:3333/api/connectors/github/connect \ - -H "Content-Type: application/json" \ - -d '{"token": "ghp_your_token_here"}' +**Settings** → **Channels** connects messaging apps, so you can message Waggle from them. -# Connect Jira with email + API token -curl -X POST http://localhost:3333/api/connectors/jira/connect \ - -H "Content-Type: application/json" \ - -d '{"apiKey": "your_jira_token", "email": "you@company.com"}' -``` +| Channel | What you need | +|---|---| +| Telegram | A bot token from @BotFather | +| Discord | A bot token from the Discord developer portal | +| Slack | An app token (Socket Mode) and a bot token | +| WhatsApp | A phone to pair by QR code | -### Disconnecting +### WhatsApp -```bash -curl -X POST http://localhost:3333/api/connectors/github/disconnect -``` +WhatsApp runs through `whatsapp-web.js`, an unofficial client that drives WhatsApp Web in a +browser. WhatsApp does not allow this and may block the account: link a secondary number, not +your personal one. -This removes the credentials from the vault and any associated metadata. +- Waggle uses Chrome, Edge or Chromium if one is installed (or the browser named in + `CHROME_PATH`). Otherwise it downloads Chrome for Testing (about 170 MB) into + `/browsers` the first time you start WhatsApp. On Linux on ARM, install Chromium + yourself. +- Start the channel, then scan the pairing QR code with WhatsApp on your phone (Linked + devices). +- The session is kept as a browser profile in `/channels/whatsapp/session`. It is + protected by file permissions, not by the Vault. +- Only text messages are handled. Voice, video and other media are ignored. -## Checking Connector Health +## Troubleshooting -Each connector can report its health status: - -```bash -curl http://localhost:3333/api/connectors/github/health -``` - -Response: -```json -{ - "id": "github", - "name": "GitHub", - "status": "connected", - "lastChecked": "2026-03-19T10:30:00.000Z", - "tokenExpiresAt": null -} -``` - -Possible statuses: `connected`, `disconnected`, `expired`, `error`. - -## Connector Tools - -When a connector is connected (credentials in vault), the agent gains tools for that service. For example, connecting GitHub gives the agent: - -- Create issues -- List repositories -- Read file contents -- Create pull requests - -The exact tools depend on the connector implementation. Tools appear in the agent's tool list and are visible in the Cockpit capabilities dashboard. - -## Approval Gates - -Sensitive connector operations go through approval gates. When the agent wants to: - -- Send an email -- Create a Jira ticket -- Post a Slack message -- Push a git commit - -It pauses and shows an approval card in the chat. You see: - -- **Tool name** (e.g., `send_email`) -- **Input** (e.g., recipient, subject, body) -- **Approve** or **Deny** buttons - -The agent waits for your decision before proceeding. This prevents accidental or unwanted actions. - -### YOLO Mode - -If you trust the agent fully, you can enable **YOLO Mode** in Settings > Permissions. This auto-approves all tool executions without asking. You can also set per-workspace overrides for specific tools. - -## Composio Bridge - -The 29th connector, Composio, is a bridge to 250+ additional services. If you have a Composio account: - -1. Add your Composio API key to the vault -2. Connect the Composio connector -3. The agent gains access to Composio-managed services - -Composio manages its own credential lifecycle. Note: Composio credentials are stored and managed by Composio's infrastructure, not in Waggle's local vault. - -## Enterprise Connectors (KVARK) - -For enterprise deployments, KVARK provides an additional layer of governed connectors with: - -- 28+ document connectors (SharePoint, Box, Google Drive, etc.) -- Permission-aware retrieval (respects source system ACLs) -- Semantic search with reranking -- Full audit trail - -Enterprise connectors require a KVARK connection. See the [API Reference](../reference/api.md) for the `/api/marketplace/enterprise-packs` endpoint. - -## Troubleshooting Connectors - -### "Connector not found" -The connector ID must match exactly (lowercase). Check `GET /api/connectors` for the full list. - -### "Vault not available" -The vault database could not be initialized. Check that `~/.waggle/` is writable and the vault.db file is not corrupted. - -### Token Expired -Some OAuth-based connectors (Google, Microsoft) have tokens that expire. Re-connect the service to refresh. - -### No Tools Appearing -After connecting, the agent tools are regenerated on the next chat message. If tools still do not appear, restart the server. +- **A connector shows as disconnected after a restart.** Check its health in Connector Hub. If + the token expired (common with Google and Microsoft tokens), connect it again with a new one. +- **The agent has no tools for a connected service.** Tools are rebuilt on the next message. If + they still do not appear, restart Waggle. +- **"Vault not available".** Check that the data directory is writable. If `vault.json` cannot + be read, Waggle copies it to `vault.json.bak` and treats the Vault as empty; you then need to + enter the secrets again.