@newsails/veil-cli 1.0.1

package/docs/api/09-websocket.md

@@ -0,0 +1,350 @@
+# WebSocket Event Stream (`/ws`)
+
+Connect once — receive every runtime event from every agent, session, and task in real time.
+
+**Trigger-path parity**: Message content and tool activity are emitted to WS regardless of how a session was triggered:
+- **SSE-triggered sessions** → `session.stream` events (mirrors the SSE stream exactly, including live token chunks)
+- **All other triggers** (HTTP JSON, `agent_message`, `agent_spawn`) → `chat.message` and `chat.inference_tool` events
+
+The only WS-exclusive gap vs SSE is `inference.chunk` (live streaming tokens), which is SSE-only by design. All other content — assistant messages, tool results, tool indicators — reaches WS in all cases.
+
+---
+
+## Connecting
+
+```js
+const ws = new WebSocket('ws://localhost:5050/ws');
+
+ws.onopen  = () => console.log('Connected');
+ws.onmessage = (msg) => {
+  const ev = JSON.parse(msg.data);
+  // ev.type identifies the event category
+};
+```
+
+On connection the server sends an initial handshake:
+```json
+{ "type": "connected", "timestamp": 1709550000000 }
+```
+
+**Authentication** — include the secret as a query parameter or header (same as HTTP endpoints):
+```js
+// Query param
+new WebSocket('ws://localhost:5050/ws?secret=my-secret');
+
+// Header (Node.js / server-side clients)
+new WebSocket('ws://localhost:5050/ws', [], {
+  headers: { 'X-Veil-Secret': 'my-secret' }
+});
+```
+
+---
+
+## Event Envelope
+
+Every event follows this structure:
+
+```json
+{
+  "type": "<event_type>",
+  "sessionId": "sess_abc123",
+  "taskId":    "task_xyz789",
+  "agentName": "assistant",
+  "event":     { ... },
+  "eventType": "<sub_type>"
+}
+```
+
+| Field | Present when | Description |
+|-------|-------------|-------------|
+| `type` | Always | Top-level event category |
+| `sessionId` | Chat/session events | Identifies the session |
+| `taskId` | Task events | Identifies the task |
+| `agentName` | Always (except `connected`) | Agent that generated the event |
+| `event` | All except `session.stream` | Event-specific payload |
+| `eventType` | `session.stream` only | SSE event sub-type (see below) |
+| `data` | `session.stream` only | SSE event payload |
+
+`sessionId` and `taskId` are `undefined` where not applicable — filter on the client.
+
+---
+
+## Event Reference
+
+### Session Lifecycle
+
+| `type` | When | `event` fields |
+|--------|------|----------------|
+| `session.created` | A new chat session is started | `{ mode: 'chat', timestamp }` |
+| `session.closed` | Session soft-closed (`DELETE /sessions/:id`) | `{ timestamp }` |
+| `session.deleted` | Session hard-deleted (`DELETE /sessions/:id?hard=true`) | `{ timestamp }` |
+
+```json
+{ "type": "session.created", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "mode": "chat", "timestamp": 1709550000000 } }
+
+{ "type": "session.closed",  "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "timestamp": 1709550999000 } }
+```
+
+---
+
+### Chat — Streaming (session.stream)
+
+`session.stream` mirrors every event that the SSE endpoint (`POST /agents/:name/chat` with `sse: true`) sends to a directly connected SSE client. **Only emitted when the session was triggered via SSE.** For sessions triggered by other means, see `chat.message` and `chat.inference_tool` below.
+
+The sub-type is in `eventType`; the payload is in `data`.
+
+| `eventType` | When | `data` fields |
+|-------------|------|---------------|
+| `inference.chunk` | Each streaming text token from the LLM | `{ content: string }` |
+| `inference.tool` | LLM is about to call a tool (before execution) | `{ name: string }` |
+| `message` | A message was persisted (assistant reply, tool result) | Full message object (see below) |
+| `done` | Chat turn completed | `{ session, agentName, model, iterations, durationMs, tokenUsage, toolCalls }` |
+| `error` | Run-level error during the turn | `{ error: string, code: string }` |
+
+```json
+{ "type": "session.stream", "sessionId": "sess_abc123", "agentName": "assistant",
+  "eventType": "inference.chunk", "data": { "content": "Hello" } }
+
+{ "type": "session.stream", "sessionId": "sess_abc123", "agentName": "assistant",
+  "eventType": "inference.tool", "data": { "name": "bash" } }
+
+{ "type": "session.stream", "sessionId": "sess_abc123", "agentName": "assistant",
+  "eventType": "done",
+  "data": { "agentName": "assistant", "model": "anthropic/claude-opus-4-5",
+            "iterations": 2, "durationMs": 3412,
+            "tokenUsage": { "input": 820, "output": 310, "cache": 0, "cost": 0.0045 },
+            "toolCalls": [{ "name": "bash", "durationMs": 124, "success": true }],
+            "session": { "id": "sess_abc123", "status": "open", ... } } }
+```
+
+**`message` object fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Message ID |
+| `session_id` | string | Session this message belongs to |
+| `role` | string | `"assistant"` or `"tool"` |
+| `content` | string | Message content |
+| `tool_calls` | array | Tool calls made (assistant messages) |
+| `tool_call_id` | string | Which tool call this is a result for (tool messages) |
+| `finishReason` | string | LLM stop reason (`"end_turn"`, `"tool_use"`, etc.) |
+| `iteration` | number | Loop iteration this message was generated in |
+| `tokenUsage` | object | `{ input, output, cache, cost }` for this message |
+
+---
+
+### Chat — Messages (non-SSE sessions)
+
+When a session is triggered via HTTP JSON, `agent_message`, `agent_spawn`, or any path that does not use SSE streaming, message content is delivered via these events instead of `session.stream`.
+
+| `type` | When | `event` fields |
+|--------|------|----------------|
+| `chat.message` | An assistant or tool-result message was persisted | Same fields as `session.stream` → `message` (see message object table above) |
+| `chat.inference_tool` | LLM is about to call a tool (before execution) | `{ name: string, timestamp }` |
+
+```json
+{ "type": "chat.message", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "id": "msg_001", "session_id": "sess_abc123", "role": "assistant",
+             "content": "Here is the analysis...", "tool_calls": null,
+             "finishReason": "end_turn", "iteration": 1,
+             "tokenUsage": { "input": 820, "output": 310, "cache": 0, "cost": 0.0045 },
+             "timestamp": 1709550003000 } }
+
+{ "type": "chat.inference_tool", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "name": "bash", "timestamp": 1709550002500 } }
+```
+
+> **Rule of thumb**: filter on both `session.stream` (eventType `message`) and `chat.message` if you want to catch all persisted messages regardless of trigger path.
+
+---
+
+### Chat — User Message
+
+Emitted when a user message is received, before the AI starts processing. Use this to render the user's turn in a UI.
+
+| `type` | When | `event` fields |
+|--------|------|----------------|
+| `chat.user_message` | User message added to a session | `{ content: string, timestamp }` |
+
+```json
+{ "type": "chat.user_message", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "content": "Summarise this file please", "timestamp": 1709550001000 } }
+```
+
+---
+
+### Chat — Internal Loop Events
+
+Lower-level events emitted during each loop iteration. Useful for debugging or building detailed progress UIs.
+
+| `type` | When | `event` fields |
+|--------|------|----------------|
+| `chat.event` | Iteration start, LLM error | `{ type: 'iteration.start'\|'llm.error', iteration?, error? }` |
+| `chat.tool` | Tool starts or ends inside a chat turn | `{ type: 'tool.start'\|'tool.end', toolName, toolInput?, durationMs?, success?, outputPreview? }` |
+| `chat.response` | Chat turn fully complete (summary) | `{ content: string (≤500 chars), toolCount, timestamp }` |
+
+> These events fire for **all** trigger paths (SSE, HTTP JSON, `agent_message`, `agent_spawn`, etc.).
+
+```json
+{ "type": "chat.event", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "type": "iteration.start", "iteration": 1, "tokensSoFar": 0, "timestamp": 1709550002000 } }
+
+{ "type": "chat.tool", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "type": "tool.end", "toolName": "read_file", "durationMs": 14, "success": true,
+             "outputPreview": "# README\n...", "timestamp": 1709550003000 } }
+
+{ "type": "chat.response", "sessionId": "sess_abc123", "agentName": "assistant",
+  "event": { "content": "The file contains a README with...", "toolCount": 1, "timestamp": 1709550004000 } }
+```
+
+---
+
+### Task Events
+
+Emitted for background tasks (created via `POST /tasks`, `task_create`, or `task_spawn`).
+
+| `type` | When | `event` fields |
+|--------|------|----------------|
+| `task.status` | Task transitions state | `{ status: 'processing'\|'finished'\|'failed'\|'canceled', sessionId?, output?, error?, reason? }` |
+| `task.event` | Iteration, tool calls, LLM errors inside the task | `{ type, toolName?, toolInput?, durationMs?, success?, outputPreview?, iteration?, error? }` |
+
+**Status values:** `pending` → `processing` → `finished` / `failed` / `canceled`
+
+```json
+{ "type": "task.status", "taskId": "task_xyz789", "agentName": "researcher",
+  "event": { "status": "processing", "sessionId": "sess_def456", "timestamp": 1709550010000 } }
+
+{ "type": "task.event", "taskId": "task_xyz789", "agentName": "researcher",
+  "event": { "type": "tool.start", "toolName": "bash",
+             "toolInput": { "command": "grep -r 'TODO' ." }, "timestamp": 1709550011000 } }
+
+{ "type": "task.status", "taskId": "task_xyz789", "agentName": "researcher",
+  "event": { "status": "finished", "output": "Found 12 TODOs across 4 files.", "timestamp": 1709550045000 } }
+```
+
+---
+
+### Daemon Events
+
+Emitted on every scheduled daemon tick.
+
+| `type` | When | `event` fields |
+|--------|------|----------------|
+| `daemon.tick` | Tick starts, finishes, or errors | `{ status: 'running'\|'done'\|'error', sessionId?, error? }` |
+
+```json
+{ "type": "daemon.tick", "agentName": "monitor",
+  "event": { "status": "running", "sessionId": "sess_ghi789", "timestamp": 1709550100000 } }
+
+{ "type": "daemon.tick", "agentName": "monitor",
+  "event": { "status": "done", "sessionId": "sess_ghi789", "timestamp": 1709550108000 } }
+```
+
+---
+
+## Building a Full Conversation UI on WS Alone
+
+A WS-only client can render a complete, real-time conversation UI for any number of sessions without any SSE connections or polling:
+
+```js
+const ws = new WebSocket('ws://localhost:5050/ws?secret=my-secret');
+
+// Keyed by sessionId
+const sessions = {};
+
+ws.onmessage = (msg) => {
+  const ev = JSON.parse(msg.data);
+  const { type, sessionId, agentName, event, eventType, data } = ev;
+
+  switch (type) {
+
+    // ── Session lifecycle ──────────────────────────────────────────────────
+    case 'session.created':
+      sessions[sessionId] = { agentName, messages: [], streaming: false };
+      renderSessionTab(sessionId, agentName);
+      break;
+
+    case 'session.closed':
+    case 'session.deleted':
+      markSessionClosed(sessionId);
+      break;
+
+    // ── User message (render immediately, before AI responds) ────────────
+    case 'chat.user_message':
+      appendMessage(sessionId, { role: 'user', content: event.content });
+      break;
+
+    // ── Streaming (SSE-triggered sessions) ─────────────────────────────
+    case 'session.stream':
+      if (eventType === 'inference.chunk') {
+        appendStreamingChunk(sessionId, data.content);    // live token-by-token
+      } else if (eventType === 'inference.tool') {
+        showToolIndicator(sessionId, data.name);           // "Using bash…"
+      } else if (eventType === 'message' && data.role === 'assistant') {
+        finalizeAssistantMessage(sessionId, data);         // full message persisted
+      } else if (eventType === 'done') {
+        hideLoader(sessionId);
+        updateUsage(sessionId, data.tokenUsage);
+      } else if (eventType === 'error') {
+        showError(sessionId, data.error);
+      }
+      break;
+
+    // ── Messages (non-SSE sessions: HTTP JSON, agent_message, agent_spawn)
+    case 'chat.message':
+      if (event.role === 'assistant') finalizeAssistantMessage(sessionId, event);
+      break;
+
+    case 'chat.inference_tool':
+      showToolIndicator(sessionId, event.name);            // "Using bash…"
+      break;
+
+    // ── Loading indicator (AI started thinking) ──────────────────────────
+    case 'chat.event':
+      if (event.type === 'iteration.start') showLoader(sessionId);
+      break;
+
+    // ── Tasks ──────────────────────────────────────────────────────────────
+    case 'task.status':
+      updateTaskStatus(ev.taskId, event.status, event.output);
+      break;
+  }
+};
+```
+
+---
+
+## Filtering Events
+
+The WebSocket receives events for **all** agents and sessions. Filter by any combination of `sessionId`, `taskId`, or `agentName`:
+
+```js
+// Watch only one session
+if (ev.sessionId !== mySessionId) return;
+
+// Watch all sessions for one agent
+if (ev.agentName !== 'researcher') return;
+
+// Watch only task completions
+if (ev.type !== 'task.status' || ev.event?.status !== 'finished') return;
+```
+
+---
+
+## Reconnection
+
+The WebSocket is stateless — the server stores no subscription state. On reconnect:
+
+1. Fetch missed messages: `GET /sessions/:id/messages`
+2. Fetch missed task events: `GET /tasks/:id/events`
+3. Reconnect to WS and resume live updates
+
+```js
+async function reconnect() {
+  const { messages } = await api.get(`/sessions/${sessionId}/messages`);
+  renderHistory(messages);
+  connectWS(); // then subscribe to live updates
+}
+```

package/docs/api/10-completions.md

@@ -0,0 +1,134 @@
+# Completions
+
+A standalone chat completion endpoint for independent LLM calls. No agent config, no session, no tool-execution loop — just a direct call to the configured LLM provider.
+
+Intended for apps built on Veil that need raw AI completions without setting up an agent workflow.
+
+---
+
+## POST /completions
+
+**Request body**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `messages` | array | ✅ | OpenAI-compatible messages array |
+| `model` | string | — | Model ID to use. Overrides the default model from settings |
+| `temperature` | number | — | Sampling temperature |
+| `max_tokens` | number | — | Maximum output tokens |
+| `tools` | array | — | OpenAI-compatible tool definitions |
+| `reasoning` | string | — | Reasoning effort level (e.g. `"high"`) |
+| `thinking` | object | — | Extended thinking config (e.g. `{ "type": "enabled", "budget_tokens": 10000 }`) |
+| `sse` | boolean | — | Stream the response via SSE (default: `false`) |
+
+The `base_url` and `api_key` are always taken from the server's configured main model — they cannot be overridden per-request.
+
+**Standard JSON response**
+
+```json
+{
+  "message": {
+    "role": "assistant",
+    "content": "The capital of France is Paris.",
+    "tool_calls": []
+  },
+  "usage": {
+    "input": 18,
+    "output": 9,
+    "cache": 0
+  },
+  "cost": 0.0000000432,
+  "finish_reason": "stop"
+}
+```
+
+**Response fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message.content` | string\|null | Assistant reply text |
+| `message.tool_calls` | array | Tool calls requested by the model (may be empty) |
+| `usage.input` | integer | Prompt tokens consumed |
+| `usage.output` | integer | Completion tokens generated |
+| `usage.cache` | integer | Cached prompt tokens (subset of `input`) |
+| `cost` | number | Estimated USD cost. Uses the value returned by the API if present, otherwise calculated from `config/models.json` pricing |
+| `finish_reason` | string | Why the model stopped (`stop`, `tool_calls`, `length`, etc.) |
+
+**Example**
+
+```bash
+curl -X POST http://localhost:5050/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "messages": [
+      { "role": "user", "content": "What is the capital of France?" }
+    ]
+  }'
+```
+
+With an explicit model override:
+
+```bash
+curl -X POST http://localhost:5050/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "google/gemini-2.5-flash",
+    "messages": [
+      { "role": "system", "content": "You are a concise assistant." },
+      { "role": "user",   "content": "Summarise the water cycle in one sentence." }
+    ],
+    "temperature": 0.3,
+    "max_tokens": 120
+  }'
+```
+
+---
+
+## SSE streaming
+
+Set `"sse": true` in the request body to receive a streamed response.
+
+The connection emits three event types:
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `chunk` | `{ "content": "..." }` | Incremental text delta |
+| `done` | Full response object (same as JSON mode) | Final message, usage, and cost |
+| `error` | `{ "error": "...", "code": "..." }` | Emitted if the LLM call fails |
+
+**Example**
+
+```bash
+curl -X POST http://localhost:5050/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "messages": [{ "role": "user", "content": "Tell me a short story." }],
+    "sse": true
+  }'
+```
+
+**Sample stream output**
+
+```
+event: chunk
+data: {"content":"Once"}
+
+event: chunk
+data: {"content":" upon"}
+
+event: chunk
+data: {"content":" a time..."}
+
+event: done
+data: {"message":{"role":"assistant","content":"Once upon a time...","tool_calls":[]},"usage":{"input":12,"output":5,"cache":0},"cost":0.0000000075,"finish_reason":"stop"}
+```
+
+---
+
+## Error responses
+
+| Code | Condition |
+|------|-----------|
+| `400 VALIDATION_ERROR` | `messages` is missing or not an array |
+| `400 VALIDATION_ERROR` | No model specified and no default model configured in settings |
+| `500 INTERNAL_ERROR` | LLM provider returned an error |

package/docs/api/README.md

@@ -0,0 +1,116 @@
+# VeilCLI — REST API Reference
+
+The VeilCLI server exposes a local HTTP REST API. All requests use JSON. The default port is **5050**.
+
+---
+
+## Base URL
+
+```
+http://localhost:5050
+```
+
+Set a custom port in `.veil/settings.json` (`"port": 5051`) or via `veil start --port 5051`.
+
+---
+
+## Authentication
+
+Authentication is **optional**. If you set `secret` in `settings.json`, every request must include the header:
+
+```
+X-Veil-Secret: <your-secret>
+```
+
+If no secret is configured, the API is open (localhost only by default).
+
+---
+
+## Request Format
+
+All request bodies must be JSON with `Content-Type: application/json`.
+
+---
+
+## Response Format
+
+All responses are JSON. Successful responses vary by endpoint. Error responses always use:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable description"
+  }
+}
+```
+
+### Error Codes
+
+| HTTP Status | Code | Meaning |
+|-------------|------|---------|
+| 400 | `VALIDATION_ERROR` | Missing or invalid request body field |
+| 400 | `MODE_NOT_SUPPORTED` | Agent does not support the requested mode |
+| 400 | `SESSION_CLOSED` | Session has been closed |
+| 400 | `TASK_NOT_WAITING` | Task is not in `waiting` status |
+| 400 | `TASK_ALREADY_TERMINAL` | Task is already finished/failed/canceled |
+| 401 | `UNAUTHORIZED` | Invalid or missing `X-Veil-Secret` |
+| 404 | `AGENT_NOT_FOUND` | No agent with that name |
+| 404 | `TASK_NOT_FOUND` | No task with that ID |
+| 404 | `SESSION_NOT_FOUND` | No session with that ID |
+| 404 | `NOT_FOUND` | Resource (e.g. memory file) not found |
+| 500 | `INTERNAL_ERROR` | Unexpected server error |
+
+---
+
+## Endpoints Overview
+
+| Method | Path | Description |
+|--------|------|-------------|
+| WS | `/ws` | Real-time event stream |
+| GET | `/health` | Liveness check |
+| GET | `/status` | Full server status |
+| POST | `/shutdown` | Graceful shutdown |
+| GET | `/agents` | List all agents |
+| GET | `/agents/:name` | Get agent details |
+| GET | `/agents/:name/sessions` | Sessions scoped to agent |
+| GET | `/agents/:name/tasks` | Tasks scoped to agent |
+| GET | `/agents/:name/skills` | Skills and custom tools for agent |
+| GET | `/agents/:name/memory` | List agent memory files |
+| GET | `/agents/:name/memory/:file` | Read an agent memory file |
+| PUT | `/agents/:name/memory/:file` | Write an agent memory file |
+| DELETE | `/agents/:name/memory/:file` | Delete an agent memory file |
+| POST | `/agents/:name/chat` | Send a chat message |
+| POST | `/agents/:name/task` | Create and start a task (`tokenBudget` supported) |
+| GET | `/tasks` | List tasks (filter by agent, status, priority) |
+| GET | `/tasks/:id` | Get task details (includes `eventCount`, structured `error`) |
+| GET | `/tasks/:id/events?since=&limit=` | Get task events (paginated) |
+| GET | `/tasks/:id/context` | Inspect the LLM context snapshot |
+| POST | `/tasks/:id/respond` | Respond to a waiting task |
+| POST | `/tasks/:id/cancel` | Cancel a task (cooperative cancel for processing tasks) |
+| GET | `/sessions` | List sessions |
+| GET | `/sessions/:id` | Get session details |
+| GET | `/sessions/:id/messages` | Get session messages |
+| GET | `/sessions/:id/context` | Inspect session message history |
+| POST | `/sessions/:id/reset` | Clear messages, re-inject system prompt |
+| DELETE | `/sessions/:id?hard=true` | Close session (`hard=true` = hard delete) |
+| GET | `/daemons` | List running daemons |
+| POST | `/agents/:name/daemon/start` | Start a daemon agent |
+| POST | `/agents/:name/daemon/stop` | Stop a daemon agent |
+| POST | `/agents/:name/daemon/trigger` | Manually trigger a daemon tick |
+| GET | `/settings` | Get current settings (api_keys redacted) |
+| PUT | `/settings` | Update settings with live reload |
+
+---
+
+## Detailed Reference
+
+- [System endpoints](01-system.md)
+- [Agents](02-agents.md) — includes agent-scoped sessions, tasks, skills
+- [Chat](03-chat.md)
+- [Tasks](04-tasks.md) — includes context, token budget, structured errors
+- [Sessions](05-sessions.md) — includes context, reset, hard delete
+- [Daemons](06-daemons.md)
+- [Memory](07-memory.md)
+- [Settings](08-settings.md)
+- [WebSocket](09-websocket.md)