@newsails/veil-cli 1.0.1

package/docs/api/02-agents.md

@@ -0,0 +1,374 @@
+# Agents
+
+---
+
+## POST /agents
+
+Create a new agent at the project or global level.
+
+**Request body**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✓ | Agent identifier — letters, numbers, hyphens, underscores only |
+| `level` | string | | `"project"` (default) or `"global"` |
+| `config` | object | ✓ | Agent configuration (must satisfy the agent schema — `model` required) |
+| `agentMd` | string | | Content for `AGENT.md` (system prompt / instructions) |
+
+**Request example**
+```json
+{
+  "name": "researcher",
+  "level": "project",
+  "config": {
+    "model": "anthropic/claude-sonnet-4-5",
+    "description": "Deep research agent",
+    "modes": {
+      "task": { "enabled": true, "tools": ["bash", "read_file", "write_file"] }
+    }
+  },
+  "agentMd": "You are a research assistant. Be thorough and cite sources."
+}
+```
+
+**Response** `201 Created`
+```json
+{
+  "agent": {
+    "name": "researcher",
+    "level": "project",
+    "folder": "/home/user/workspace/.veil/agents/researcher"
+  }
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `409 AGENT_EXISTS` | An agent with that name already exists at any level (project, global, or bundled) |
+| `400 INVALID_NAME` | Name contains invalid characters |
+| `400 INVALID_CONFIG` | Config fails schema validation (error details included) |
+| `400 VALIDATION_ERROR` | Missing required body fields or invalid `level` |
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/agents \
+  -H "Content-Type: application/json" \
+  -d '{"name":"researcher","config":{"model":"anthropic/claude-sonnet-4-5"}}'
+```
+
+---
+
+## GET /agents
+
+Returns all agents discovered in the workspace's `.veil/agents/` directory (and the global cache if configured).
+
+**Query parameters** — none
+
+**Response**
+```json
+{
+  "agents": [
+    {
+      "name": "hello",
+      "description": "A simple conversational agent",
+      "model": "moonshotai/kimi-k2.5",
+      "modes": ["chat", "task"],
+      "source": "project"
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Agent identifier (folder name) |
+| `description` | string | From `agent.json` |
+| `model` | string | LLM model identifier |
+| `modes` | string[] | Enabled modes: `"chat"`, `"task"`, `"daemon"`, `"subagent"` |
+| `source` | string | `"project"` or `"global"` or `"bundled"` |
+
+**Example**
+```bash
+curl http://localhost:5050/agents
+```
+
+---
+
+## GET /agents/:name
+
+Returns the full configuration for a single agent.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name (must match a folder in `.veil/agents/`) |
+
+**Response**
+```json
+{
+  "agent": {
+    "name": "assistant",
+    "description": "General-purpose agent with file and shell access",
+    "model": "moonshotai/kimi-k2.5",
+    "temperature": 0.7,
+    "reasoning": "medium",
+    "modes": {
+      "chat": { "enabled": true },
+      "task": {
+        "enabled": true,
+        "maxIterations": 20,
+        "maxDurationSeconds": 120,
+        "tools": ["read_file", "list_dir", "bash", "write_file"],
+        "permissions": {
+          "deny": ["bash(rm *)", "bash(sudo *)", "write_file(/etc/*)"]
+        }
+      }
+    },
+    "skillDiscovery": false,
+    "memory": { "enabled": false },
+    "agentFolder": "/home/user/workspace/.veil/agents/assistant",
+    "source": "project",
+    "agentMd": "You are a general-purpose assistant with file and shell access."
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Agent identifier |
+| `description` | string | Human-readable description |
+| `model` | string | LLM model string |
+| `temperature` | number | 0–2, sampling temperature |
+| `reasoning` | string | Reasoning level: "minimal", "low", "medium", "high" |
+| `modes` | object | Full mode configs (see [Agent Configuration](../guide/04-agents.md)) |
+| `skillDiscovery` | boolean | Whether the agent auto-discovers skills |
+| `memory` | object | `{ enabled, maxLines }` |
+| `agentFolder` | string | Absolute path to the agent's folder |
+| `source` | string | Where the agent was loaded from: `"project"`, `"global"`, or `"bundled"` |
+| `agentMd` | string | Full content of the agent's `AGENT.md` system prompt file |
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 AGENT_NOT_FOUND` | No agent with that name exists |
+
+**Example**
+```bash
+curl http://localhost:5050/agents/assistant
+```
+
+---
+
+## POST /agents/:name/reload
+
+Hot-reload an agent's configuration from disk. Since `loadAgent` always reads from disk, this endpoint simply forces a fresh load and returns the current config. Useful for confirming that config file edits have taken effect, or for programmatically verifying the agent is valid after an update.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Response**
+```json
+{
+  "reloaded": true,
+  "agent": {
+    "name": "assistant",
+    "model": "anthropic/claude-sonnet-4-5",
+    "description": "General-purpose assistant",
+    "modes": { "chat": { "enabled": true } }
+  }
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 AGENT_NOT_FOUND` | No agent with that name exists |
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/agents/assistant/reload
+```
+
+---
+
+## PUT /agents/:name
+
+Update an existing agent's configuration and/or `AGENT.md`. Only project-level and global agents can be updated — bundled agents are read-only.
+
+At least one of `config` or `agentMd` must be provided. Config fields are **shallow-merged** with the current `agent.json` (top-level keys are replaced).
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Request body**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `config` | object | | Partial or full agent config — merged over current `agent.json` |
+| `agentMd` | string | | New content for `AGENT.md` — fully replaces existing content |
+
+**Request example** — update model and add a tool
+```json
+{
+  "config": {
+    "model": "anthropic/claude-opus-4-5",
+    "modes": {
+      "chat": { "enabled": true, "tools": ["read_file", "bash"] }
+    }
+  }
+}
+```
+
+**Response**
+```json
+{
+  "agent": {
+    "name": "researcher",
+    "level": "project",
+    "folder": "/home/user/workspace/.veil/agents/researcher"
+  }
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 AGENT_NOT_FOUND` | No agent with that name exists |
+| `403 AGENT_READ_ONLY` | Agent is bundled and cannot be modified |
+| `400 INVALID_CONFIG` | Merged config fails schema validation |
+| `400 VALIDATION_ERROR` | Neither `config` nor `agentMd` provided |
+
+**Example**
+```bash
+curl -X PUT http://localhost:5050/agents/researcher \
+  -H "Content-Type: application/json" \
+  -d '{"config":{"model":"anthropic/claude-opus-4-5"}}'
+```
+
+---
+
+## DELETE /agents/:name
+
+Delete an agent folder and all its contents (config, AGENT.md, skills, etc.). Only project-level and global agents can be deleted — bundled agents are read-only.
+
+> **Warning:** This is irreversible. The agent folder is permanently removed from disk.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Response**
+```json
+{
+  "deleted": true,
+  "agent": {
+    "name": "researcher",
+    "level": "project",
+    "folder": "/home/user/workspace/.veil/agents/researcher"
+  }
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 AGENT_NOT_FOUND` | No agent with that name exists |
+| `403 AGENT_READ_ONLY` | Agent is bundled and cannot be deleted |
+
+**Example**
+```bash
+curl -X DELETE http://localhost:5050/agents/researcher
+```
+
+---
+
+## GET /agents/:name/sessions
+
+List sessions for a specific agent. This is a convenience alias for `GET /sessions?agentName=:name`.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `status` | string | Filter by `active` or `closed` |
+| `limit` | integer | Max results (default: 20) |
+| `cursor` | string | Pagination cursor |
+
+**Response**
+```json
+{
+  "agentName": "assistant",
+  "sessions": [
+    { "id": "sess_...", "mode": "chat", "status": "active", ... }
+  ]
+}
+```
+
+---
+
+## GET /agents/:name/tasks
+
+List tasks for a specific agent. This is a convenience alias for `GET /tasks?agentName=:name`.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `status` | string | Filter by status |
+| `priority` | string | Filter by priority |
+| `limit` | integer | Max results (default: 20) |
+| `cursor` | string | Pagination cursor |
+
+**Response**
+```json
+{
+  "agentName": "assistant",
+  "tasks": [
+    { "id": "task_...", "status": "finished", ... }
+  ]
+}
+```
+
+---
+
+## GET /agents/:name/skills
+
+List skills configured for an agent and their load status.
+
+**Response**
+```json
+{
+  "agentName": "assistant",
+  "skills": [
+    { "name": "web-search", "loaded": true, "source": "project", "path": "/.../.veil/skills/web-search.md" },
+    { "name": "missing-skill", "loaded": false, "error": "File not found" }
+  ],
+  "customTools": [
+    { "name": "my_tool", "source": "project" }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `skills[].name` | string | Skill name from agent config |
+| `skills[].loaded` | boolean | Whether the skill file was found |
+| `skills[].source` | string | `"agent"` or `"project"` |
+| `skills[].path` | string | Absolute path (if loaded) |
+| `skills[].error` | string | Error message (if not loaded) |
+| `customTools` | array | Custom tools discovered for this agent |

package/docs/api/03-chat.md

@@ -0,0 +1,269 @@
+# Chat
+
+The chat endpoint enables multi-turn conversations with an agent. Each call is synchronous — it blocks until the agent finishes its response (including any tool calls).
+
+---
+
+## POST /agents/:name/chat
+
+Send a message to an agent and receive a reply.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Request body**
+
+```json
+{
+  "message": "What files are in the current directory?",
+  "sessionId": "sess_abc123"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `message` | string | ✓ | User message content |
+| `sessionId` | string | | Existing session ID to continue a conversation. Omit to start a new session. |
+| `sse` | boolean | | `true` to enable SSE streaming — the response is `text/event-stream` instead of JSON. |
+
+**Response**
+
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "message": {
+    "role": "assistant",
+    "content": "Here are the files in the current directory:\n- README.md\n- package.json\n..."
+  },
+  "tokenUsage": {
+    "input": 1240,
+    "output": 183,
+    "cache": 0,
+    "cost": 0.0021
+  },
+  "toolCalls": [
+    { "name": "list_dir", "durationMs": 12, "success": true },
+    { "name": "read_file", "durationMs": 8, "success": true }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId` | string | Session ID (pass this back for multi-turn) |
+| `message.role` | string | Always `"assistant"` |
+| `message.content` | string | Agent reply text (last iteration's response) |
+| `tokenUsage.input` | integer | Total input tokens for this turn |
+| `tokenUsage.output` | integer | Total output tokens for this turn |
+| `tokenUsage.cache` | integer | Cached tokens (if provider supports it) |
+| `tokenUsage.cost` | number | Estimated cost in USD |
+| `toolCalls` | array | Summary of tools called: `{ name, durationMs, success }` |
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 VALIDATION_ERROR` | `message` is missing or not a string |
+| `400 MODE_NOT_SUPPORTED` | Agent does not have `chat.enabled: true` |
+| `400 SESSION_CLOSED` | The provided `sessionId` belongs to a closed session |
+| `404 AGENT_NOT_FOUND` | No agent with that name |
+
+---
+
+## SSE Streaming Mode
+
+Set `"sse": true` in the request body to receive a real-time `text/event-stream` response. The connection stays open across all LLM iterations (including tool call rounds) and closes only when the full turn is complete.
+
+**Design principle:** Events are split into two categories — _inference_ events carry transient streaming data not needed for state; _message_ events carry the exact schema returned by `GET /sessions/:id/messages` so clients can update their local state directly without any conversion.
+
+**Event types**
+
+| Event | Category | Description |
+|-------|----------|-------------|
+| `inference.chunk` | Inference | One streaming token fragment from the current LLM call |
+| `inference.tool` | Inference | Tool name detected in stream before arguments are complete — lets UI show a loading indicator early |
+| `message` | State | An assistant or tool message, identical to the session messages API schema |
+| `done` | State | Turn complete — includes the updated session record and turn-level stats |
+| `error` | — | Emitted instead of `done` if the run fails |
+
+---
+
+**`inference.chunk`**
+```json
+{ "content": "Here are the" }
+```
+
+**`inference.tool`** — fires once per tool call as soon as the tool name appears in the stream (before arguments are complete)
+```json
+{ "name": "sleep" }
+```
+
+---
+
+**`message`** — session-API-compatible message object, augmented with inference metadata for assistant turns
+
+*Assistant turn (text only):*
+```json
+{
+  "id": 5,
+  "session_id": "sess_4f3a1b9c2d8e7f01",
+  "role": "assistant",
+  "content": "Here are the files:\n- README.md",
+  "tool_calls": null,
+  "tool_call_id": null,
+  "created_at": "2025-03-02T10:00:04.000Z",
+  "finishReason": "stop",
+  "iteration": 1,
+  "tokenUsage": { "input": 1240, "output": 38, "cache": 0, "cost": 0.0003 }
+}
+```
+
+*Assistant turn (with tool calls):*
+```json
+{
+  "id": 3,
+  "session_id": "sess_4f3a1b9c2d8e7f01",
+  "role": "assistant",
+  "content": null,
+  "tool_calls": [{ "id": "call_abc", "type": "function", "function": { "name": "list_dir", "arguments": "{\"dir\": \".\"}" } }],
+  "tool_call_id": null,
+  "created_at": "2025-03-02T10:00:02.000Z",
+  "finishReason": "tool_calls",
+  "iteration": 1,
+  "tokenUsage": { "input": 980, "output": 22, "cache": 0, "cost": 0.0002 }
+}
+```
+
+*Tool result:*
+```json
+{
+  "id": 4,
+  "session_id": "sess_4f3a1b9c2d8e7f01",
+  "role": "tool",
+  "content": "README.md (1.2KB)\npackage.json (544B)",
+  "tool_calls": null,
+  "tool_call_id": "call_abc",
+  "created_at": "2025-03-02T10:00:03.000Z"
+}
+```
+
+`finishReason` on assistant turns: `"stop"` = no tools followed | `"tool_calls"` = continued with tool use | `"length"` = token limit hit
+
+---
+
+**`done`**
+```json
+{
+  "session": {
+    "id": "sess_4f3a1b9c2d8e7f01",
+    "agent_name": "assistant",
+    "mode": "chat",
+    "status": "active",
+    "model": "claude-3-5-sonnet",
+    "total_input_tokens": 6842,
+    "total_output_tokens": 124,
+    "cost": 0.0089,
+    "message_count": 5,
+    "created_at": "2025-03-02T10:00:00.000Z",
+    "updated_at": "2025-03-02T10:00:05.000Z"
+  },
+  "agentName": "assistant",
+  "model": "claude-3-5-sonnet",
+  "iterations": 3,
+  "durationMs": 4210,
+  "tokenUsage": { "input": 6842, "output": 124, "cache": 0, "cost": 0.0089 },
+  "toolCalls": [
+    { "name": "sleep", "durationMs": 1003, "success": true }
+  ]
+}
+```
+
+**`error`**
+```json
+{ "error": "LLM API error 429: rate limit", "code": "INTERNAL_ERROR" }
+```
+
+---
+
+**Behavior notes**
+- `inference.chunk` fires for every LLM iteration across the full turn — all chunks are streamed in order.
+- `inference.tool` fires during streaming as soon as the tool name is known, before arguments finish — use this for tool loading indicators.
+- Each `message` event (role `assistant` or `tool`) matches what `GET /sessions/:id/messages` returns, so clients can append them directly to local state without schema conversion.
+- `done.session` is a snapshot of the session record after the turn — clients can use it to update session state without a separate `GET /sessions/:id` call.
+- The response `Content-Type` is `text/event-stream`; use `EventSource` or an SSE client library.
+
+**JavaScript example**
+```js
+const response = await fetch('http://localhost:5050/agents/assistant/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ message: 'List files', sse: true }),
+});
+
+const messages = [];
+const reader = response.body.getReader();
+const decoder = new TextDecoder();
+let buffer = '';
+let pendingEvent = null;
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  buffer += decoder.decode(value, { stream: true });
+  const lines = buffer.split('\n');
+  buffer = lines.pop();
+  for (const line of lines) {
+    if (line.startsWith('event: ')) { pendingEvent = line.slice(7).trim(); continue; }
+    if (line.startsWith('data: ') && pendingEvent) {
+      const data = JSON.parse(line.slice(6));
+      if (pendingEvent === 'inference.chunk') process.stdout.write(data.content);
+      if (pendingEvent === 'inference.tool')  console.log(`[tool] ${data.name}…`);
+      if (pendingEvent === 'message')         messages.push(data);  // directly usable
+      if (pendingEvent === 'done')            console.log('session:', data.session);
+      pendingEvent = null;
+    }
+  }
+}
+```
+
+**curl example**
+```bash
+curl -X POST http://localhost:5050/agents/assistant/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "List files", "sse": true}' \
+  --no-buffer
+```
+
+---
+
+## Multi-turn Conversation Example
+
+Start a new conversation, then continue it:
+
+```bash
+# Turn 1 — new session
+curl -X POST http://localhost:5050/agents/assistant/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "My name is Alice."}'
+
+# Response includes sessionId, e.g. "sess_4f3a1b9c2d8e7f01"
+
+# Turn 2 — continue the same session
+curl -X POST http://localhost:5050/agents/assistant/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What is my name?", "sessionId": "sess_4f3a1b9c2d8e7f01"}'
+
+# Agent remembers: "Your name is Alice."
+```
+
+---
+
+## Notes
+
+- The agent's full message history (including tool call messages) is persisted in SQLite and replayed on each turn.
+- If the agent uses tools (e.g. `read_file`, `bash`), those calls happen **before** the reply is returned — the response always contains the final text response.
+- To inspect which tools were called during a chat turn, fetch the session messages after the call: `GET /sessions/:id/messages`.
+- Sessions are scoped to a workspace (`instanceFolder`). A `sessionId` from one server instance will not be found by another.