diff --git a/docs/reference/api.md b/docs/reference/api.md index b929cd1..238b17d 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -1,22 +1,35 @@ -# API Reference +# Local API reference -The Waggle local server runs on `http://localhost:3333`. All endpoints accept and return JSON unless otherwise noted. +The Waggle server runs on `http://localhost:3333` and listens on `127.0.0.1` only. The web UI +uses this API; it is not a stable public interface and can change between releases. Endpoints +accept and return JSON unless noted otherwise. The routes live in +`packages/server/src/local/routes/`. + +## Authentication + +Every `/api/*` request needs the session token as `Authorization: Bearer `. Server-Sent +Event streams that cannot send headers accept it as `?token=`. The web UI gets the token from +`GET /api/auth/session-token`, which answers only same-origin requests from the page the server +serves (the desktop app gets it through its own launch credential). Requests with a `Host` +header other than a local one are refused. + +This page lists the main route groups, not every route. ## Chat | Method | Path | Description | |--------|------|-------------| -| POST | `/api/chat` | Send a message and receive an SSE stream of agent responses. Body: `{ message, workspaceId, sessionId, model? }` | +| POST | `/api/chat` | Send a message and receive an SSE stream of the agent's reply. Body: `{ message, workspaceId?, sessionId?, model?, persona? }` | | GET | `/api/history` | Get conversation history. Query: `?session=ID&workspace=ID` | -The chat endpoint streams responses via Server-Sent Events (SSE). Events include `message`, `tool_call`, `tool_result`, `approval_request`, `done`, and `error`. +The chat endpoint streams the reply as Server-Sent Events; see [Chat stream events](#chat-stream-events). ## Workspaces | Method | Path | Description | |--------|------|-------------| | GET | `/api/workspaces` | List all workspaces | -| POST | `/api/workspaces` | Create a workspace. Body: `{ name, group, icon?, model?, personaId?, directory?, teamId? }` | +| POST | `/api/workspaces` | Create a workspace. Body: `{ name, group, icon?, model?, personaId?, templateId?, storageType?: 'virtual' \| 'local', storagePath? }` | | GET | `/api/workspaces/:id` | Get workspace by ID | | PUT | `/api/workspaces/:id` | Update workspace. Body: `{ name?, group?, icon?, model?, personaId? }` | | DELETE | `/api/workspaces/:id` | Delete workspace | @@ -27,20 +40,40 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include | Method | Path | Description | |--------|------|-------------| -| GET | `/api/workspaces/:wid/sessions` | List sessions for a workspace, sorted by last active | -| POST | `/api/workspaces/:wid/sessions` | Create a new session. Body: `{ title? }` | -| GET | `/api/workspaces/:wid/sessions/search` | Search across sessions. Query: `?q=query&limit=20` | -| GET | `/api/workspaces/:wid/sessions/:sid/export` | Export session as Markdown. Returns `text/markdown` | -| PATCH | `/api/sessions/:id` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` | -| DELETE | `/api/sessions/:id` | Delete a session. Query: `?workspace=ID` | +| GET | `/api/workspaces/:workspaceId/sessions` | List sessions for a workspace, sorted by last active | +| POST | `/api/workspaces/:workspaceId/sessions` | Create a new session. Body: `{ title? }` | +| GET | `/api/workspaces/:workspaceId/sessions/search` | Search across sessions. Query: `?q=query&limit=20` | +| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/export` | Export a session as Markdown (`text/markdown`) | +| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/timeline` | Tool events of a session | +| PATCH | `/api/sessions/:sessionId` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` | +| DELETE | `/api/sessions/:sessionId` | Delete a session. Query: `?workspace=ID` | ## Memory +All memory routes go through the memory contract ([memory.md](../memory.md)). Some paths still +say "frames", the name used by the old memory engine; they return memory records. + | Method | Path | Description | |--------|------|-------------| -| GET | `/api/memory/search` | Search memory. Query: `?q=query&scope=all|personal|workspace&limit=20&workspace=ID` | -| GET | `/api/memory/frames` | Recent frames without search. Query: `?workspace=ID&limit=50` | -| GET | `/api/memory/graph` | Knowledge graph entities and relations. Query: `?workspace=ID` | +| GET | `/api/memory/capabilities` | What the memory store supports, and the extraction setting | +| PUT | `/api/memory/settings` | Turn background fact extraction on or off. Body: `{ extraction: boolean }` | +| GET | `/api/memory/search` | Search memory. Query: `?q=query&scope=all\|personal\|workspace\|global&workspace=ID&limit=20&since=&until=` (`all` is personal plus the given workspace; `global` is personal plus every workspace) | +| GET | `/api/memory/frames` | Newest personal and workspace memories. Query: `?workspace=ID&limit=50&since=&until=` | +| POST | `/api/memory/frames` | Save a memory. Body: `{ content, workspaceId?, importance?, kind?, source? }` | +| PUT | `/api/memory/frames/:id` | Edit a memory's text or importance | +| DELETE | `/api/memory/frames/:id` | Delete a memory | +| GET | `/api/memory/stats` | Memory counts. Query: `?workspace=ID` | +| GET | `/api/memory` | List memories. Query: `?mind=personal\|workspace&workspace=ID&kind=&status=&q=&limit=` | +| GET | `/api/memory/:id` | One memory | +| POST | `/api/memory` | Create a memory stated by the user | +| PATCH | `/api/memory/:id` | Edit text, importance, kind, title, tags, evidence or status | +| DELETE | `/api/memory/:id` | Delete a memory | +| POST | `/api/memory/:id/archive` | Archive a memory (reversible) | +| POST | `/api/memory/:id/confirm` | Mark a memory as confirmed by the user | +| GET | `/api/memory/:id/trace` | The execution that produced a memory ("why did you do that?") | +| POST | `/api/memory/erase` | Forget one memory (`{ id }`) or every memory saved from one chat (`{ sessionId }`) | +| POST | `/api/memory/merge` | Merge several memories of one scope into one | +| GET | `/api/memory/graph` | Always returns an empty graph: the knowledge graph is not part of this release | ## Agent @@ -67,9 +100,9 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include | GET | `/api/settings` | Read config: default model, providers (masked keys), paths | | PUT | `/api/settings` | Update config. Body: `{ defaultModel?, providers? }` | | POST | `/api/settings/test-key` | Validate API key format. Body: `{ provider, apiKey }` | -| POST | `/api/settings/probe-provider` | Live-probe a STORED provider key by id. Body: `{ provider }` → `{ configured, valid, verified, error? }` | -| GET | `/api/settings/permissions` | Read permission settings (YOLO mode, external gates) | -| PUT | `/api/settings/permissions` | Update permissions. Body: `{ yoloMode?, externalGates?, workspaceOverrides? }` | +| POST | `/api/settings/probe-provider` | Test a stored provider key with the provider. Body: `{ provider }` → `{ configured, valid, verified, error? }` | +| GET | `/api/settings/permissions` | Read the approval settings | +| PUT | `/api/settings/permissions` | Update the approval settings. Body: `{ defaultAutonomy?, externalGates?, workspaceOverrides? }` (`yoloMode` is still accepted) | ## Vault @@ -120,7 +153,6 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include | GET | `/api/marketplace/search` | Search catalog. Query: `?query=text&type=skill&category=cat&limit=20&offset=0` | | GET | `/api/marketplace/packs` | List all capability packs | | GET | `/api/marketplace/packs/:slug` | Pack detail with packages | -| GET | `/api/marketplace/enterprise-packs` | Enterprise packs (requires KVARK) | | POST | `/api/marketplace/install` | Install package. Body: `{ packageId, installPath?, settings?, force? }` | | POST | `/api/marketplace/uninstall` | Uninstall package. Body: `{ packageId }` | | GET | `/api/marketplace/installed` | List installed packages | @@ -176,23 +208,16 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include | Method | Path | Description | |--------|------|-------------| -| POST | `/api/ingest` | Ingest files. Body: `{ files: [{ name, content (base64) }], workspaceId? }`. Max 15MB. | +| POST | `/api/ingest` | Ingest files. Body: `{ files: [{ name, content (base64) }], workspaceId? }`. Up to 10 MB per file; the request body is limited to 15 MB. | Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), spreadsheets (XLSX, CSV), text/code (50+ extensions), archives (ZIP). -## Import - -| Method | Path | Description | -|--------|------|-------------| -| POST | `/api/import/preview` | Preview import from ChatGPT or Claude export. Body: `{ data, source: "chatgpt"|"claude" }` | -| POST | `/api/import/commit` | Import and save to personal memory. Body: `{ data, source }` | - ## Feedback | Method | Path | Description | |--------|------|-------------| -| POST | `/api/feedback` | Record feedback. Body: `{ sessionId, messageIndex, rating: "up"|"down", reason?, detail? }` | -| GET | `/api/feedback/stats` | Improvement stats: positive rate, top issues, corrections, trend | +| POST | `/api/feedback` | Record thumbs up or down on a reply. Body: `{ sessionId, messageIndex, rating: "up"\|"down", reason?, detail? }` | +| GET | `/api/feedback/stats` | Feedback statistics | ## Notifications @@ -206,19 +231,11 @@ Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), |--------|------|-------------| | GET | `/api/audit/installs` | Recent install audit trail. Query: `?limit=20` | -## Team +## Built-in provider proxy | Method | Path | Description | |--------|------|-------------| -| POST | `/api/team/connect` | Connect to team server. Body: `{ serverUrl, token }` | -| POST | `/api/team/disconnect` | Disconnect from team server | -| GET | `/api/team/status` | Current team connection status | - -## Anthropic Proxy - -| Method | Path | Description | -|--------|------|-------------| -| POST | `/v1/chat/completions` | OpenAI-compatible endpoint that translates to Anthropic API. Used by internal agent loop. | +| POST | `/v1/chat/completions` | OpenAI-compatible endpoint used by the agent loop and memory extraction. Translates Claude requests to Anthropic's Messages API and forwards other providers' models to their OpenAI-compatible APIs | ## Commands @@ -226,17 +243,20 @@ Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), |--------|------|-------------| | POST | `/api/commands/execute` | Execute a slash command. Body: `{ command, workspaceId, sessionId }` | -## SSE Streaming +## Chat stream events -The `/api/chat` endpoint uses Server-Sent Events for real-time streaming. Event types: +`POST /api/chat` answers with Server-Sent Events. The event names the chat route sends: | Event | Description | |-------|-------------| -| `message` | Agent text chunk | -| `tool_call` | Agent is calling a tool (shows tool name and input) | -| `tool_result` | Tool execution result | -| `approval_request` | Agent needs approval before proceeding | -| `approval_resolved` | Approval was granted or denied | -| `memory_saved` | A memory frame was auto-saved | -| `done` | Agent turn complete | -| `error` | Error occurred | +| `token` | A chunk of the agent's text | +| `step` | A progress step of the turn (recall, thinking, tool use and so on) | +| `tool` | The agent calls a tool | +| `tool_result` | The result of a tool call | +| `approval_required` | A tool call waits for the user's approval | +| `approval_held` | A tool call was held for later approval | +| `model_switch` | The turn moved to another model | +| `file_created` | A tool created a file | +| `notification` | A notification for the user | +| `done` | The turn is complete | +| `error` | The turn failed | diff --git a/docs/reference/commands.md b/docs/reference/commands.md index fe1ca42..720ae4b 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -1,27 +1,41 @@ -# Commands Reference +# Slash commands -Waggle provides 14 slash commands for quick actions. Type `/` in any workspace to see autocomplete suggestions. +Type `/` in a chat to see the commands with autocomplete. A command is `/name` followed by its +arguments; aliases work the same way as the name. Many commands hand a prepared request to the +agent, which then uses its normal tools and approvals. -## Command List +The commands are defined in `packages/agent/src/commands/` (`workflow-commands.ts` and +`marketplace-commands.ts`). -| Command | Aliases | Args | Description | -|---------|---------|------|-------------| -| `/catchup` | `/catch-up`, `/recap` | -- | Workspace restart summary. Shows recent activity, memories, and state so you can get up to speed instantly. | -| `/now` | `/current`, `/where` | -- | Current workspace state. What is happening right now -- active threads, recent changes, open items. | -| `/research` | `/investigate` | `` | Launch multi-agent research. Spawns the `research-team` workflow with multiple agents investigating the topic in parallel. | -| `/draft` | `/write` | ` [topic]` | Start a drafting workflow. Supports any document type: blog, report, email, proposal, memo. Uses the `review-pair` workflow for drafts with review. | -| `/decide` | `/decision`, `/weigh` | `` | Create a structured decision matrix with options, pros/cons, risk, and effort columns. Provides an evaluation framework for systematic decision-making. | -| `/review` | `/critique`, `/check` | -- | Review the last output with a critic agent. Spawns the `review-pair` workflow to analyze the most recent response for accuracy and completeness. | -| `/spawn` | `/agent`, `/summon` | ` [task]` | Spawn a specialist sub-agent. Available roles: `researcher`, `writer`, `coder`, `analyst`, `reviewer`, `planner`. | -| `/skills` | `/abilities`, `/tools` | -- | Show active skills in this workspace. Lists all loaded skill files with their names. | -| `/status` | `/report`, `/progress` | -- | Project status summary. Shows workspace state including tasks, progress, blockers, and recent activity. | -| `/memory` | `/remember`, `/recall` | `[query]` | Search workspace memory. Without arguments, shows usage help. With a query, searches both personal and workspace minds. | -| `/plan` | `/decompose`, `/break-down` | `` | Break a goal into actionable tasks. Uses the `plan-execute` workflow to create a structured task list with dependencies. | -| `/focus` | `/narrow`, `/scope` | `` | Narrow agent focus to a specific topic. Subsequent responses prioritize this context. Use again to change focus. | -| `/marketplace` | `/mp`, `/market` | ` [args]` | Marketplace operations. Sub-commands: `search`, `install`, `packs`, `installed`, `sync`. See details below. | -| `/help` | `/commands`, `/?` | -- | List all available commands with descriptions. | +## Command list -## Detailed Examples +| Command | Aliases | Arguments | What it does | +|---|---|---|---| +| `/catchup` | `/catch-up`, `/recap` | | Summary of where the workspace stands: recent activity, memories and state | +| `/now` | `/current`, `/where` | | What is happening in the workspace right now | +| `/status` | `/report`, `/progress` | | Project status: tasks, progress, blockers and recent activity | +| `/research` | `/investigate` | `` | Runs the `research-team` workflow on a topic | +| `/draft` | `/write` | ` [topic]` | Drafts a document (memo, report, email, proposal…) with a review cycle | +| `/decide` | `/decision`, `/weigh` | `` | Builds a decision matrix with options, pros, cons, risk and effort | +| `/review` | `/critique`, `/check` | | Has a critic agent review the last answer | +| `/plan` | `/decompose`, `/break-down` | `` | Breaks a goal into a task list | +| `/spawn` | `/agent`, `/summon` | ` [task]` | Starts a specialist sub-agent: `researcher`, `writer`, `coder`, `analyst`, `reviewer` or `planner` | +| `/focus` | `/narrow`, `/scope` | `` | Narrows the agent's focus to a topic until you change it | +| `/memory` | `/remember`, `/recall` | `` | Searches personal and workspace memory | +| `/search-all` | `/find-all` | `` | Searches personal memory and all workspaces | +| `/skills` | `/abilities`, `/tools` | | Lists the active skills | +| `/plugins` | | | Lists installed plugins and capabilities | +| `/connectors` | `/integrations`, `/connections` | | Lists connected services and their status | +| `/marketplace` | `/mp`, `/market` | ` [args]` | Marketplace: `search`, `install`, `packs`, `installed`, `sync` | +| `/workflow` | `/wf` | ` [args]` | Creates, lists or runs multi-agent workflows | +| `/export` | | `` | Exports workspace data with the agent's help | +| `/import` | | `` | Reads a file, URL or pasted text and saves what matters as workspace memories | +| `/cli` | `/cli-tools` | `[allow\|deny\|discover] [name]` | Shows or changes which command-line programs the agent may run | +| `/pr` | `/pull-request`, `/merge-request` | `` | Creates a pull request from the current branch of the workspace's repository | +| `/settings` | | | Shows the current workspace and agent settings | +| `/help` | `/commands`, `/?` | | Lists all commands | + +## Examples ### /catchup @@ -29,72 +43,55 @@ Waggle provides 14 slash commands for quick actions. Type `/` in any workspace t /catchup ``` -Output: A structured briefing with what this workspace is about, recent sessions, decisions, memory count, and suggested next steps. Use this every time you return to a workspace after a break. +A briefing for when you come back to a workspace: what it is about, recent sessions, decisions +and suggested next steps. ### /research ``` -/research quantum computing applications in drug discovery +/research applications of quantum computing in drug discovery ``` -Spawns the `research-team` multi-agent workflow: -1. A researcher agent investigates the topic -2. Findings are synthesized and cross-referenced -3. Results are presented with citations and confidence levels +Runs the `research-team` workflow: research agents investigate the topic and their findings are +combined into one answer. ### /draft ``` -/draft blog post about AI safety best practices -/draft report quarterly metrics for Q1 2026 -/draft email to client about project timeline changes +/draft report quarterly metrics for Q1 +/draft email to the client about the timeline change ``` -The agent determines the document type from the first word and adapts its formatting accordingly. If the `review-pair` workflow is available, the draft goes through a review cycle. +The first word is the document type. ### /decide ``` -/decide Should we use PostgreSQL or MongoDB for the new project? +/decide Should we use PostgreSQL or MongoDB for the new service? ``` -Produces a decision matrix template: - -| Option | Pros | Cons | Risk | Effort | -|--------|------|------|------|--------| -| PostgreSQL | | | | | -| MongoDB | | | | | - -Ask the agent to fill it in: "Please analyze this decision for me." +Produces a matrix with a row per option and columns for pros, cons, risk and effort. Ask the +agent to fill it in. ### /spawn ``` -/spawn researcher Find recent papers on transformer architectures -/spawn coder Implement a rate limiter middleware -/spawn analyst Compare our metrics against industry benchmarks +/spawn researcher Find recent papers on retrieval-augmented generation +/spawn coder Write a rate limiter middleware ``` -The sub-agent runs with the specified role and task, then returns its results to the main conversation. +The sub-agent works on the task and returns its result to the conversation. -### /memory +### /memory and /search-all ``` /memory architecture decisions -/memory last meeting notes -/memory project goals +/search-all project deadlines ``` -Searches both personal and workspace memory using FTS5 full-text search. Results include content, importance level, and dates. - -### /plan - -``` -/plan Build a user dashboard with analytics -/plan Migrate the database to PostgreSQL -``` - -Creates a structured plan with ordered steps, dependencies, and success criteria. The agent can then execute steps sequentially. +`/memory` searches personal memory and the current workspace's memory. `/search-all` also +searches every other workspace and groups the results by workspace. See +[memory.md](../memory.md). ### /marketplace @@ -106,33 +103,32 @@ Creates a structured plan with ordered steps, dependencies, and success criteria /marketplace sync ``` -| Sub-command | Description | -|-------------|-------------| -| `search <query>` | Search the marketplace catalog by keyword. Returns up to 10 results with name, type, category, and description. | -| `install <name>` | Install a package by name. Searches for the best match, runs SecurityGate scan, and installs. | -| `packs` | List all capability packs grouped by priority tier. | -| `installed` | Show all currently installed packages with status and install date. | -| `sync` | Trigger a manual sync from all configured marketplace sources. Reports added/updated counts. | +| Subcommand | What it does | +|---|---| +| `search <query>` | Searches the catalog, up to 10 results | +| `install <name>` | Finds the best match, runs the security scan and installs it | +| `packs` | Lists the capability packs | +| `installed` | Lists installed packages | +| `sync` | Refreshes the catalog from its sources | -## Command Parsing +### /workflow -Commands follow the format `/commandName arg1 arg2 ...`. The parser: +``` +/workflow list +/workflow run research-team +/workflow create Research competitors, summarize findings and draft an executive brief +``` -1. Strips the leading `/` -2. Splits on the first space to get the command name and arguments -3. Resolves aliases (e.g., `/mp` resolves to `/marketplace`) -4. Executes the handler with the argument string and workspace context +## Adding a command -Partial matching is supported for autocomplete but not for execution. You must type the full command name or alias. +Commands are `CommandDefinition` objects registered with the `CommandRegistry` +(`packages/agent/src/commands/command-registry.ts`): -## Adding Custom Commands +- `name`: the command name, lowercase, without `/`; +- `aliases`: other names, also without `/`; +- `description` and `usage`: shown in `/help`; +- `handler(args, context)`: returns the reply text. A reply that starts with + `AGENT_LOOP_REROUTE_PREFIX` is sent to the agent as a request instead of shown directly. -Commands are registered in the `CommandRegistry`. To add a custom command, create a `CommandDefinition` with: - -- `name` -- the primary command name (lowercase) -- `aliases` -- alternative names -- `description` -- shown in `/help` output -- `usage` -- usage string with argument placeholders -- `handler` -- async function receiving `(args: string, context: CommandContext)` - -See `packages/agent/src/commands/` for implementation examples. +Register a new command in `registerWorkflowCommands` or in a registration function of your +own, called from the sidecar (`packages/server/src/local/index.ts`).