@newsails/veil-cli 1.0.1

package/docs/api/05-sessions.md

@@ -0,0 +1,444 @@
+# Sessions
+
+A session is created automatically for every chat or task run. It holds the full conversation history (system prompt, user messages, assistant replies, tool calls, tool results).
+
+---
+
+## POST /sessions
+
+Create a new session without sending a message. Useful when you want to pre-create a session and pass it as `sessionId` to the chat endpoint, or to attach a stream listener before the first message.
+
+A system prompt is automatically injected as the first message.
+
+**Request body**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `agentName` | string | ✓ | Agent to create the session for |
+| `mode` | string | | `chat` (default), `task`, `daemon`, or `subagent` |
+| `model` | string | | Override model for this session. Defaults to the agent's configured model. |
+| `model_thinking` | object\|null | | Extended thinking config for this session, e.g. `{"type":"enabled","budget_tokens":5000}`. Defaults to agent's `thinking` config if set. Pass `null` to disable. |
+
+**Request example**
+```json
+{
+  "agentName": "assistant",
+  "mode": "chat"
+}
+```
+
+**Response** `201 Created`
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "session": {
+    "id": "sess_4f3a1b9c2d8e7f01",
+    "agent_name": "assistant",
+    "mode": "chat",
+    "status": "active",
+    "model": "anthropic/claude-sonnet-4-5",
+    "created_at": "2025-03-02T10:00:00.000Z",
+    "updated_at": "2025-03-02T10:00:00.000Z"
+  }
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 AGENT_NOT_FOUND` | No agent with that name |
+| `400 VALIDATION_ERROR` | `agentName` missing or `mode` is invalid |
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"agentName": "assistant", "mode": "chat"}'
+```
+
+---
+
+## GET /sessions
+
+List sessions for the current workspace.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentName` | string | Filter by agent name |
+| `status` | string | `active` or `closed` |
+| `limit` | integer | Max results (default: 20) |
+| `cursor` | string | Pagination cursor (last session ID from previous page) |
+
+**Response**
+
+```json
+{
+  "sessions": [
+    {
+      "id": "sess_4f3a1b9c2d8e7f01",
+      "agent_name": "assistant",
+      "mode": "chat",
+      "status": "active",
+      "model": "moonshotai/kimi-k2.5",
+      "message_count": 6,
+      "instance_folder": "/home/user/workspace",
+      "created_at": "2025-03-02T10:00:00.000Z",
+      "updated_at": "2025-03-02T10:05:00.000Z"
+    }
+  ]
+}
+```
+
+**Session object fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique session ID |
+| `agent_name` | string | Agent this session belongs to |
+| `mode` | string | `chat`, `task`, `daemon`, or `subagent` |
+| `status` | string | `active` or `closed` |
+| `model` | string | LLM model used |
+| `title` | string\|null | Optional session title |
+| `message_count` | integer | Total messages in this session |
+| `total_input_tokens` | integer | Accumulated prompt tokens for the session (includes deleted messages and resets) |
+| `total_output_tokens` | integer | Accumulated completion tokens for the session |
+| `total_cache_tokens` | integer | Accumulated cached prompt tokens for the session |
+| `context_size` | integer | Prompt + completion tokens of the **last** LLM turn (current context window usage) |
+| `context_size_limit` | integer\|null | Model context limit in tokens (if known) |
+| `cost` | number | Accumulated cost in USD for the session |
+| `model_thinking` | object\|null | Extended thinking config active for this session (JSON-encoded in DB, returned as object) |
+| `instance_folder` | string | Workspace that owns this session |
+| `created_at` | ISO string | When session was created |
+| `updated_at` | ISO string | Last activity timestamp |
+
+---
+
+## GET /sessions/:id
+
+Get details for a single session.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Session ID |
+
+**Response**
+
+```json
+{
+  "session": {
+    "id": "sess_4f3a1b9c2d8e7f01",
+    "agent_name": "assistant",
+    "mode": "chat",
+    "status": "active",
+    "model": "moonshotai/kimi-k2.5",
+    "message_count": 6,
+    "instance_folder": "/home/user/workspace",
+    "created_at": "2025-03-02T10:00:00.000Z",
+    "updated_at": "2025-03-02T10:05:00.000Z"
+  }
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 SESSION_NOT_FOUND` | No session with that ID |
+
+---
+
+## GET /sessions/:id/messages
+
+Retrieve the message history for a session.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Session ID |
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `limit` | integer | Max messages to return (default: 100) |
+| `offset` | integer | Skip first N messages (default: 0) |
+
+**Response**
+
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "messages": [
+    {
+      "id": 1,
+      "session_id": "sess_4f3a1b9c2d8e7f01",
+      "role": "system",
+      "content": "You are Assistant, a helpful agent...",
+      "tool_calls": null,
+      "tool_call_id": null,
+      "created_at": "2025-03-02T10:00:00.000Z"
+    },
+    {
+      "id": 2,
+      "role": "user",
+      "content": "What files are in the current directory?",
+      "tool_calls": null,
+      "tool_call_id": null,
+      "created_at": "2025-03-02T10:00:01.000Z"
+    },
+    {
+      "id": 3,
+      "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"
+    },
+    {
+      "id": 4,
+      "role": "tool",
+      "content": "README.md (1.2KB)\npackage.json (544B)\n...",
+      "tool_calls": null,
+      "tool_call_id": "call_abc",
+      "created_at": "2025-03-02T10:00:03.000Z"
+    },
+    {
+      "id": 5,
+      "role": "assistant",
+      "content": "Here are the files in the current directory:\n- README.md\n- package.json",
+      "tool_calls": null,
+      "tool_call_id": null,
+      "created_at": "2025-03-02T10:00:04.000Z"
+    }
+  ]
+}
+```
+
+**Message object fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Auto-incremented message ID |
+| `session_id` | string | Parent session |
+| `role` | string | `system`, `user`, `assistant`, or `tool` |
+| `content` | string\|null | Text content (null for tool-call-only assistant messages) |
+| `tool_calls` | array\|null | OpenAI tool call objects (parsed from JSON) — present on `assistant` messages that call tools |
+| `tool_call_id` | string\|null | Links a `tool` result back to the originating tool call |
+| `model_key` | string\|null | Model used for this message (only set on `assistant` messages) |
+| `input_tokens` | integer\|null | Prompt tokens for this LLM call (assistant messages only) |
+| `output_tokens` | integer\|null | Completion tokens for this LLM call (assistant messages only) |
+| `cache_tokens` | integer\|null | Cached prompt tokens for this LLM call (assistant messages only) |
+| `cost` | number\|null | Cost in USD for this LLM call — from API response, null if not reported |
+| `created_at` | ISO string | When the message was created |
+
+**Message roles**
+
+| Role | Description |
+|------|-------------|
+| `system` | System prompt (first message, set once per session) |
+| `user` | User input message |
+| `assistant` | Agent reply — may have `tool_calls` instead of `content` when using tools |
+| `tool` | Tool execution result — `tool_call_id` links it to the assistant's tool call |
+
+**Note on `tool_calls`**: The field is a JSON string (not a nested object) containing an array of OpenAI function-call objects. Parse it with `JSON.parse()`.
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 SESSION_NOT_FOUND` | No session with that ID |
+
+---
+
+## GET /sessions/:id/stream
+
+Real-time SSE (Server-Sent Events) stream for a session. Streams all runtime events scoped to this session — tool calls, LLM responses, iteration starts, daemon ticks, and more.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Session ID |
+
+**Response** — `text/event-stream`
+
+The stream opens with a `session` event showing the current session state, then forwards all matching eventBus events in real time.
+
+**`event: session`** — sent immediately on connection:
+```
+event: session
+data: {"sessionId":"sess_...","status":"active","agentName":"assistant","mode":"chat"}
+```
+
+**Live events** — one SSE event per bus event, named by event type:
+```
+event: chat.tool
+data: {"sessionId":"sess_...","agentName":"assistant","event":{"type":"tool.start","toolName":"read_file","toolInput":{"path":"package.json"}},"timestamp":1234567890}
+
+event: chat.response
+data: {"sessionId":"sess_...","agentName":"assistant","event":{"content":"Here are the files...","toolCount":2},"timestamp":1234567890}
+
+event: chat.event
+data: {"sessionId":"sess_...","agentName":"assistant","event":{"type":"iteration.start","iteration":1},"timestamp":1234567890}
+```
+
+**Event types by session mode**
+
+| Type | Mode | Description |
+|------|------|-------------|
+| `chat.event` | chat | Iteration start, LLM errors |
+| `chat.tool` | chat | Tool call start/end |
+| `chat.response` | chat | Final agent reply |
+| `task.event` | task | Tool calls, iteration progress |
+| `task.status` | task | Task status changes (via associated taskId) |
+| `daemon.tick` | daemon | Daemon tick start/done/error |
+
+A keepalive comment is sent every 15 seconds:
+```
+: keepalive
+```
+
+The stream stays open until the client disconnects. There is no automatic close.
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 SESSION_NOT_FOUND` | No session with that ID |
+
+**JavaScript example**
+```js
+// Pre-create a session, then open the stream before sending the first message
+const { sessionId } = await fetch('http://localhost:5050/sessions', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ agentName: 'assistant' }),
+}).then(r => r.json());
+
+const source = new EventSource(`http://localhost:5050/sessions/${sessionId}/stream`);
+
+source.addEventListener('chat.tool', (e) => {
+  const { event } = JSON.parse(e.data);
+  if (event.type === 'tool.start') console.log('Tool:', event.toolName);
+  if (event.type === 'tool.end') console.log('Done in', event.durationMs, 'ms');
+});
+
+source.addEventListener('chat.response', (e) => {
+  const { event } = JSON.parse(e.data);
+  console.log('Reply:', event.content);
+});
+
+// Now send a chat message using the pre-created sessionId
+await fetch(`http://localhost:5050/agents/assistant/chat`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ message: 'List files in the current dir', sessionId }),
+});
+```
+
+---
+
+## GET /sessions/:id/context
+
+Returns the full message history for debugging. Unlike `/messages`, this endpoint formats messages for quick context inspection.
+
+**Response**
+
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "agentName": "assistant",
+  "mode": "chat",
+  "messageCount": 5,
+  "messages": [
+    { "id": 1, "role": "system", "content": "You are...", "created_at": "..." },
+    { "id": 2, "role": "user", "content": "What files...", "created_at": "..." },
+    { "id": 3, "role": "assistant", "content": null, "tool_calls": [...], "created_at": "..." }
+  ]
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 SESSION_NOT_FOUND` | No session with that ID |
+
+---
+
+## POST /sessions/:id/reset
+
+Clear all messages from a session but keep the session alive. A fresh system prompt is re-injected so the agent starts with a clean slate.
+
+**Response**
+
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "status": "reset",
+  "messageCount": 1
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 SESSION_CLOSED` | Cannot reset a closed session |
+| `404 SESSION_NOT_FOUND` | No session with that ID |
+
+---
+
+## DELETE /sessions/:id
+
+Close or delete a session.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `hard` | string | Set to `"true"` to permanently delete the session and all messages. Default: soft close only. |
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Session ID |
+
+**Response (soft close — default)**
+
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "status": "closed"
+}
+```
+
+**Response (hard delete — `?hard=true`)**
+
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "status": "deleted"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 SESSION_NOT_FOUND` | No session with that ID |
+
+---
+
+## Notes
+
+- Sessions are scoped to the workspace (`instance_folder`). You cannot access sessions from a different server instance using the same ID.
+- Task sessions (`mode: "task"`) are created and managed automatically — do not close them manually.
+- Chat sessions (`mode: "chat"`) stay `active` until explicitly closed or the server restarts (active sessions are left open; they can be resumed).

package/docs/api/06-daemons.md

@@ -0,0 +1,142 @@
+# Daemons
+
+Daemon agents run on a cron schedule. They wake up, execute their task (reading a heartbeat file for instructions), and go back to sleep. Daemons with a `schedule` in their `agent.json` are auto-started when the server boots.
+
+See [Daemon Agents guide](../guide/10-daemons.md) for configuration details.
+
+---
+
+## GET /daemons
+
+List all currently active daemon schedulers.
+
+**Response**
+
+```json
+{
+  "daemons": [
+    {
+      "agentName": "monitor",
+      "schedule": "*/5 * * * *",
+      "status": "active",
+      "lastTick": "2025-03-02T10:05:00.000Z",
+      "nextTick": "2025-03-02T10:10:00.000Z"
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agentName` | string | Agent identifier |
+| `schedule` | string | Cron expression |
+| `status` | string | `active` |
+| `lastTick` | ISO string \| null | When the last tick ran |
+| `nextTick` | ISO string \| null | When the next tick is scheduled |
+
+---
+
+## POST /agents/:name/daemon/start
+
+Start scheduling a daemon agent. The agent must have `modes.daemon.enabled: true` in its `agent.json`.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Request body** — none
+
+**Response**
+
+```json
+{
+  "agentName": "monitor",
+  "status": "started"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 MODE_NOT_SUPPORTED` | Agent does not have daemon mode enabled |
+| `404 AGENT_NOT_FOUND` | No agent with that name |
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/agents/monitor/daemon/start
+```
+
+---
+
+## POST /agents/:name/daemon/stop
+
+Stop a running daemon scheduler. The agent will not run again until started.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Request body** — none
+
+**Response**
+
+```json
+{
+  "agentName": "monitor",
+  "status": "stopped"
+}
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/agents/monitor/daemon/stop
+```
+
+---
+
+## POST /agents/:name/daemon/trigger
+
+Manually trigger a single daemon tick immediately, regardless of the cron schedule. The tick runs asynchronously — the endpoint returns immediately.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Request body** — none
+
+**Response**
+
+```json
+{
+  "agentName": "monitor",
+  "status": "triggered"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 MODE_NOT_SUPPORTED` | Agent does not have daemon mode enabled |
+| `404 AGENT_NOT_FOUND` | No agent with that name |
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/agents/monitor/daemon/trigger
+```
+
+---
+
+## Notes
+
+- **Auto-start**: Daemons with a `schedule` field in `agent.json` start automatically when `veil start` runs.
+- **Conflict policy**: If a tick fires while the previous one is still running, behavior depends on `conflictPolicy` in `agent.json`: `skip` (default), `queue`, or `restart`.
+- **Heartbeat files**: By default the daemon reads `.veil/heartbeats/<agentName>.md` as its instruction. Customize with `heartbeatFile` in `agent.json`.
+- Daemon sessions are created per tick and auto-closed when the tick completes.