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:
@@ -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
|
## Chat
|
||||||
|
|
||||||
| Method | Path | Description |
|
| 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` |
|
| 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
|
## Workspaces
|
||||||
|
|
||||||
| Method | Path | Description |
|
| Method | Path | Description |
|
||||||
|--------|------|-------------|
|
|--------|------|-------------|
|
||||||
| GET | `/api/workspaces` | List all workspaces |
|
| 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 |
|
| GET | `/api/workspaces/:id` | Get workspace by ID |
|
||||||
| PUT | `/api/workspaces/:id` | Update workspace. Body: `{ name?, group?, icon?, model?, personaId? }` |
|
| PUT | `/api/workspaces/:id` | Update workspace. Body: `{ name?, group?, icon?, model?, personaId? }` |
|
||||||
| DELETE | `/api/workspaces/:id` | Delete workspace |
|
| 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 |
|
| Method | Path | Description |
|
||||||
|--------|------|-------------|
|
|--------|------|-------------|
|
||||||
| GET | `/api/workspaces/:wid/sessions` | List sessions for a workspace, sorted by last active |
|
| GET | `/api/workspaces/:workspaceId/sessions` | List sessions for a workspace, sorted by last active |
|
||||||
| POST | `/api/workspaces/:wid/sessions` | Create a new session. Body: `{ title? }` |
|
| POST | `/api/workspaces/:workspaceId/sessions` | Create a new session. Body: `{ title? }` |
|
||||||
| GET | `/api/workspaces/:wid/sessions/search` | Search across sessions. Query: `?q=query&limit=20` |
|
| GET | `/api/workspaces/:workspaceId/sessions/search` | Search across sessions. Query: `?q=query&limit=20` |
|
||||||
| GET | `/api/workspaces/:wid/sessions/:sid/export` | Export session as Markdown. Returns `text/markdown` |
|
| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/export` | Export a session as Markdown (`text/markdown`) |
|
||||||
| PATCH | `/api/sessions/:id` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` |
|
| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/timeline` | Tool events of a session |
|
||||||
| DELETE | `/api/sessions/:id` | Delete a session. Query: `?workspace=ID` |
|
| PATCH | `/api/sessions/:sessionId` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` |
|
||||||
|
| DELETE | `/api/sessions/:sessionId` | Delete a session. Query: `?workspace=ID` |
|
||||||
|
|
||||||
## Memory
|
## 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 |
|
| Method | Path | Description |
|
||||||
|--------|------|-------------|
|
|--------|------|-------------|
|
||||||
| GET | `/api/memory/search` | Search memory. Query: `?q=query&scope=all|personal|workspace&limit=20&workspace=ID` |
|
| GET | `/api/memory/capabilities` | What the memory store supports, and the extraction setting |
|
||||||
| GET | `/api/memory/frames` | Recent frames without search. Query: `?workspace=ID&limit=50` |
|
| PUT | `/api/memory/settings` | Turn background fact extraction on or off. Body: `{ extraction: boolean }` |
|
||||||
| GET | `/api/memory/graph` | Knowledge graph entities and relations. Query: `?workspace=ID` |
|
| 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
|
## 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 |
|
| GET | `/api/settings` | Read config: default model, providers (masked keys), paths |
|
||||||
| PUT | `/api/settings` | Update config. Body: `{ defaultModel?, providers? }` |
|
| PUT | `/api/settings` | Update config. Body: `{ defaultModel?, providers? }` |
|
||||||
| POST | `/api/settings/test-key` | Validate API key format. Body: `{ provider, apiKey }` |
|
| 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? }` |
|
| POST | `/api/settings/probe-provider` | Test a stored provider key with the provider. Body: `{ provider }` → `{ configured, valid, verified, error? }` |
|
||||||
| GET | `/api/settings/permissions` | Read permission settings (YOLO mode, external gates) |
|
| GET | `/api/settings/permissions` | Read the approval settings |
|
||||||
| PUT | `/api/settings/permissions` | Update permissions. Body: `{ yoloMode?, externalGates?, workspaceOverrides? }` |
|
| PUT | `/api/settings/permissions` | Update the approval settings. Body: `{ defaultAutonomy?, externalGates?, workspaceOverrides? }` (`yoloMode` is still accepted) |
|
||||||
|
|
||||||
## Vault
|
## 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/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` | List all capability packs |
|
||||||
| GET | `/api/marketplace/packs/:slug` | Pack detail with packages |
|
| 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/install` | Install package. Body: `{ packageId, installPath?, settings?, force? }` |
|
||||||
| POST | `/api/marketplace/uninstall` | Uninstall package. Body: `{ packageId }` |
|
| POST | `/api/marketplace/uninstall` | Uninstall package. Body: `{ packageId }` |
|
||||||
| GET | `/api/marketplace/installed` | List installed packages |
|
| 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 |
|
| 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).
|
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
|
## Feedback
|
||||||
|
|
||||||
| Method | Path | Description |
|
| Method | Path | Description |
|
||||||
|--------|------|-------------|
|
|--------|------|-------------|
|
||||||
| POST | `/api/feedback` | Record feedback. Body: `{ sessionId, messageIndex, rating: "up"|"down", reason?, detail? }` |
|
| POST | `/api/feedback` | Record thumbs up or down on a reply. Body: `{ sessionId, messageIndex, rating: "up"\|"down", reason?, detail? }` |
|
||||||
| GET | `/api/feedback/stats` | Improvement stats: positive rate, top issues, corrections, trend |
|
| GET | `/api/feedback/stats` | Feedback statistics |
|
||||||
|
|
||||||
## Notifications
|
## 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` |
|
| GET | `/api/audit/installs` | Recent install audit trail. Query: `?limit=20` |
|
||||||
|
|
||||||
## Team
|
## Built-in provider proxy
|
||||||
|
|
||||||
| Method | Path | Description |
|
| Method | Path | Description |
|
||||||
|--------|------|-------------|
|
|--------|------|-------------|
|
||||||
| POST | `/api/team/connect` | Connect to team server. Body: `{ serverUrl, token }` |
|
| 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 |
|
||||||
| 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. |
|
|
||||||
|
|
||||||
## Commands
|
## 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 }` |
|
| 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 |
|
| Event | Description |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| `message` | Agent text chunk |
|
| `token` | A chunk of the agent's text |
|
||||||
| `tool_call` | Agent is calling a tool (shows tool name and input) |
|
| `step` | A progress step of the turn (recall, thinking, tool use and so on) |
|
||||||
| `tool_result` | Tool execution result |
|
| `tool` | The agent calls a tool |
|
||||||
| `approval_request` | Agent needs approval before proceeding |
|
| `tool_result` | The result of a tool call |
|
||||||
| `approval_resolved` | Approval was granted or denied |
|
| `approval_required` | A tool call waits for the user's approval |
|
||||||
| `memory_saved` | A memory frame was auto-saved |
|
| `approval_held` | A tool call was held for later approval |
|
||||||
| `done` | Agent turn complete |
|
| `model_switch` | The turn moved to another model |
|
||||||
| `error` | Error occurred |
|
| `file_created` | A tool created a file |
|
||||||
|
| `notification` | A notification for the user |
|
||||||
|
| `done` | The turn is complete |
|
||||||
|
| `error` | The turn failed |
|
||||||
|
|||||||
@@ -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 |
|
## Command list
|
||||||
|---------|---------|------|-------------|
|
|
||||||
| `/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. |
|
|
||||||
|
|
||||||
## 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
|
### /catchup
|
||||||
|
|
||||||
@@ -29,72 +43,55 @@ Waggle provides 14 slash commands for quick actions. Type `/` in any workspace t
|
|||||||
/catchup
|
/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
|
||||||
|
|
||||||
```
|
```
|
||||||
/research quantum computing applications in drug discovery
|
/research applications of quantum computing in drug discovery
|
||||||
```
|
```
|
||||||
|
|
||||||
Spawns the `research-team` multi-agent workflow:
|
Runs the `research-team` workflow: research agents investigate the topic and their findings are
|
||||||
1. A researcher agent investigates the topic
|
combined into one answer.
|
||||||
2. Findings are synthesized and cross-referenced
|
|
||||||
3. Results are presented with citations and confidence levels
|
|
||||||
|
|
||||||
### /draft
|
### /draft
|
||||||
|
|
||||||
```
|
```
|
||||||
/draft blog post about AI safety best practices
|
/draft report quarterly metrics for Q1
|
||||||
/draft report quarterly metrics for Q1 2026
|
/draft email to the client about the timeline change
|
||||||
/draft email to client about project timeline changes
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
```
|
```
|
||||||
/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:
|
Produces a matrix with a row per option and columns for pros, cons, risk and effort. Ask the
|
||||||
|
agent to fill it in.
|
||||||
| Option | Pros | Cons | Risk | Effort |
|
|
||||||
|--------|------|------|------|--------|
|
|
||||||
| PostgreSQL | | | | |
|
|
||||||
| MongoDB | | | | |
|
|
||||||
|
|
||||||
Ask the agent to fill it in: "Please analyze this decision for me."
|
|
||||||
|
|
||||||
### /spawn
|
### /spawn
|
||||||
|
|
||||||
```
|
```
|
||||||
/spawn researcher Find recent papers on transformer architectures
|
/spawn researcher Find recent papers on retrieval-augmented generation
|
||||||
/spawn coder Implement a rate limiter middleware
|
/spawn coder Write a rate limiter middleware
|
||||||
/spawn analyst Compare our metrics against industry benchmarks
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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 architecture decisions
|
||||||
/memory last meeting notes
|
/search-all project deadlines
|
||||||
/memory project goals
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Searches both personal and workspace memory using FTS5 full-text search. Results include content, importance level, and dates.
|
`/memory` searches personal memory and the current workspace's memory. `/search-all` also
|
||||||
|
searches every other workspace and groups the results by workspace. See
|
||||||
### /plan
|
[memory.md](../memory.md).
|
||||||
|
|
||||||
```
|
|
||||||
/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.
|
|
||||||
|
|
||||||
### /marketplace
|
### /marketplace
|
||||||
|
|
||||||
@@ -106,33 +103,32 @@ Creates a structured plan with ordered steps, dependencies, and success criteria
|
|||||||
/marketplace sync
|
/marketplace sync
|
||||||
```
|
```
|
||||||
|
|
||||||
| Sub-command | Description |
|
| Subcommand | What it does |
|
||||||
|-------------|-------------|
|
|---|---|
|
||||||
| `search <query>` | Search the marketplace catalog by keyword. Returns up to 10 results with name, type, category, and description. |
|
| `search <query>` | Searches the catalog, up to 10 results |
|
||||||
| `install <name>` | Install a package by name. Searches for the best match, runs SecurityGate scan, and installs. |
|
| `install <name>` | Finds the best match, runs the security scan and installs it |
|
||||||
| `packs` | List all capability packs grouped by priority tier. |
|
| `packs` | Lists the capability packs |
|
||||||
| `installed` | Show all currently installed packages with status and install date. |
|
| `installed` | Lists installed packages |
|
||||||
| `sync` | Trigger a manual sync from all configured marketplace sources. Reports added/updated counts. |
|
| `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 `/`
|
## Adding a command
|
||||||
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
|
|
||||||
|
|
||||||
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:
|
Register a new command in `registerWorkflowCommands` or in a registration function of your
|
||||||
|
own, called from the sidecar (`packages/server/src/local/index.ts`).
|
||||||
- `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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user