docs: document agent, chat, and api endpoints

docs/api.md

@@ -0,0 +1,156 @@
+# API Documentation
+
+This document documents all WebSocket actions and HTTP paths used by the WebSocket server.
+
+## HTTP Paths
+
+- `/` - Serves the frontend `index.html`
+- `/user`, `/models`, `/remotes`, `/runs`, `/chat`, `/agent` - SPA routes
+- `/chat/<path:subpath>`, `/agent/<path:subpath>` - SPA routes (subpaths handled by Vue router)
+- `/<path:path>` - Static file routes
+- `POST /user/login` - User login (supports token or username/password auth)
+- `POST /user/signup` - User signup (creates default data after registration)
+- `POST /api/openai/v1/chat/completions` - OpenAI-compatible chat completion endpoint
+- `GET /api/openai/v1/models` - OpenAI-compatible models list endpoint
+
+---
+
+## WebSocket Actions (Client → Server)
+
+### Authentication
+
+- `ping` - Heartbeat; server responds with `"pong"`
+
+### Agent Management
+
+- `create-agent` - Creates a new agent
+  - Payload: `name`, `agentname` (optional), `description` (optional), `picture` (optional), `kind`, `data` (optional), `temporary` (optional)
+  - Response: `agentId`, `nonce`
+
+- `update-agent` - Updates an existing agent
+  - Payload: `agentId` or `agentname`, `name` (optional), `agentname` (optional), `description` (optional), `picture` (optional), `data` (optional)
+  - Response: `agentId`, `nonce`
+
+- `get-agent-config-fields` - Returns configuration schema fields for an agent
+  - Payload: `agentId` or `agentname`
+  - Response: `fields`, `nonce`
+
+- `get-agent-kinds` - Returns all registered agent kinds
+  - Response: `kinds`, `nonce`
+
+- `get-agent-kind-info` - Returns details for a specific agent kind
+  - Payload: `kind`
+  - Response: `info`, `nonce`
+
+- `get-agents` - Returns all agents for the authenticated user
+  - Response: `agents`, `nonce`
+
+- `get-agent-resources` - Returns agent resources
+  - Payload: `agentId` or `agentname`, `kind` (optional), `key` (optional)
+  - Response: `resources` list with `kind`, `key`, `value`
+
+- `save-agent-resource` - Saves an agent resource
+  - Payload: `agentId` or `agentname`, `kind`, `key`, `value`
+  - Response: `nonce`
+
+- `get-agent-runs` - Returns agent runs (optionally filtered by agent or user)
+  - Payload: `agentId` or `agentname` (optional), `runId` (optional)
+  - Response: `runs`, `nonce`
+
+- `cancel-agent-run` - Cancels an agent run
+  - Payload: `runId`
+
+- `send-agent-prompt` - Sends a prompt to an agent
+  - Payload: `agentId` or `agentname`, `instruction` or `input`, `options` (optional), `stream` (optional)
+  - Response: `response` (stream ID if streaming, final content otherwise), `nonce`
+
+### Model Management
+
+- `get-models` - Returns all available models
+  - Response: `models` list with `id`, `name`, `value`, `kind`, `nonce`
+
+- `save-model` - Creates or deletes a model
+  - Payload: `modelId` (optional), `name`, `kind`, `value`
+  - Response: `message`, `modelId` or `message` with deletion, `nonce`
+
+### Remote Management
+
+- `remote-list` - Lists remotes for the authenticated user
+  - Response: `remotes`, `nonce`
+
+- `remote-connect` - Connects a new remote (served by this session)
+  - Payload: `remotename`, `functions` array of `{name, description, parameters}`
+  - Response: `remotename`, `nonce` (or error)
+
+- `remote-disconnect` - Disconnects a remote
+  - Payload: `remotename`
+  - Response: `remotename`, `nonce` (or error if not found)
+
+- `remote-call` - Invokes a function on a connected remote
+  - Payload: `remotename`, `function`, `args`
+  - Response: `result` or `error`, `nonce`
+
+### Chat Management
+
+- `create-chat` - Creates a new chat
+  - Payload: `name`, `description` (optional), `picture` (optional), `members` (optional array of agent IDs), `temporary` (optional)
+  - Response: `chatId`, `nonce`
+
+- `get-chats` - Returns all chats for the authenticated user
+  - Response: `chats`, `nonce`
+
+- `delete-chat` - Deletes a chat
+  - Payload: `chatId`
+  - Response: `chatId`, `nonce`
+
+- `get-chat-messages` - Returns messages for a chat (paginated)
+  - Payload: `chatId`, `earliestIndex` (optional, defaults to 0)
+  - Response: `messages`, `nonce`
+
+- `send-chat-message` - Sends a chat message
+  - Payload: `chatId`, `threadId` (optional), `content`, `kind` (optional), `subkind` (optional), `format` (optional)
+  - Response: `messageId`, `nonce`
+
+- `update-chat-message` - Updates a chat message
+  - Payload: `messageId`, `content`, `kind` (optional), `subkind` (optional), `format` (optional)
+  - Response: `messageId`, `nonce`
+
+- `create-chat-thread` - Creates a new chat thread
+  - Payload: `chatId`, `name` (optional)
+  - Response: `threadId`, `nonce`
+
+### Streaming
+
+- `read-stream` - Reads the content of a stream incrementally
+  - Payload: `streamId`
+  - Response: `data` (chunks), `eof` (boolean), `fullData` (when eof is true), `nonce`
+
+---
+
+## WebSocket Actions (Server → Client)
+
+### Agent Events
+
+- `run-event` - Agent run event (used during chat messages and prompts)
+  - Payload: event data, includes output, reasoning, tool calls, done state
+
+### Remote Events
+
+- `remote-call-result` - Result of a remote function call
+  - Payload: `requestId`, `result`, `error`
+
+### Authentication
+
+- Server sends `"message": "authentication successful"` after successful authentication
+
+### User Notifications
+
+- `message` - Generic message type for various responses
+
+---
+
+## Common Response Fields
+
+- `nonce` - Optional request identifier for matching responses
+- `error` - Optional error message when an operation fails
+- `message` - Confirmation message for successful operations