docs: bring the command and local API references up to date (P2.4)

commands.md lists all 23 registered slash commands with their working
aliases and drops the FTS5 and two-mind wording. api.md explains the
bearer session token and that the API is internal, fixes the session
route parameters, lists the memory routes served through the memory
contract, the current chat stream events and the permissions body, and
removes the team, import and KVARK enterprise-pack routes.
This commit is contained in:
shumeiko.it
2026-11-01 02:01:57 +01:00
parent 94d54c4188
commit dd6564451a
2 changed files with 144 additions and 128 deletions

View File

@@ -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 <token>`. 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 |

View File

@@ -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` | `<topic>` | Launch multi-agent research. Spawns the `research-team` workflow with multiple agents investigating the topic in parallel. |
| `/draft` | `/write` | `<type> [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` | `<question>` | 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` | `<role> [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` | `<goal>` | Break a goal into actionable tasks. Uses the `plan-execute` workflow to create a structured task list with dependencies. |
| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrow agent focus to a specific topic. Subsequent responses prioritize this context. Use again to change focus. |
| `/marketplace` | `/mp`, `/market` | `<subcommand> [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` | `<topic>` | Runs the `research-team` workflow on a topic |
| `/draft` | `/write` | `<type> [topic]` | Drafts a document (memo, report, email, proposal…) with a review cycle |
| `/decide` | `/decision`, `/weigh` | `<question>` | 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` | `<goal>` | Breaks a goal into a task list |
| `/spawn` | `/agent`, `/summon` | `<role> [task]` | Starts a specialist sub-agent: `researcher`, `writer`, `coder`, `analyst`, `reviewer` or `planner` |
| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrows the agent's focus to a topic until you change it |
| `/memory` | `/remember`, `/recall` | `<query>` | Searches personal and workspace memory |
| `/search-all` | `/find-all` | `<query>` | 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` | `<subcommand> [args]` | Marketplace: `search`, `install`, `packs`, `installed`, `sync` |
| `/workflow` | `/wf` | `<create\|list\|run> [args]` | Creates, lists or runs multi-agent workflows |
| `/export` | | `<memories\|sessions\|all\|workspace>` | Exports workspace data with the agent's help |
| `/import` | | `<source>` | 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` | `<title>` | 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`).