@newsails/veil-cli 1.0.1

package/docs/api/04-tasks.md

@@ -0,0 +1,470 @@
+# Tasks
+
+Tasks are **asynchronous** agent runs. Unlike chat, a task is created immediately (202) and runs in the background. Poll for status or stream events to track progress.
+
+---
+
+## Task Lifecycle
+
+```
+pending → processing → finished
+                     → failed
+                     → canceled
+                     → waiting   (agent used task_respond tool, awaiting reply)
+```
+
+---
+
+## POST /agents/:name/task
+
+Create a new task for an agent. Returns immediately with the task ID.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `name` | Agent name |
+
+**Request body**
+
+```json
+{
+  "input": "Read package.json and tell me the dependencies",
+  "priority": "normal",
+  "tags": ["audit", "deps"],
+  "maxIterations": 15,
+  "maxDurationSeconds": 60
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `input` | string | ✓ | Task instruction |
+| `priority` | string | | `"high"`, `"normal"` (default), or `"low"` |
+| `tags` | string[] | | Arbitrary labels for filtering |
+| `maxIterations` | integer | | Override max agent loop iterations for this task |
+| `maxDurationSeconds` | integer | | Override max wall-clock seconds for this task |
+| `tokenBudget` | integer | | Max total tokens (input + output) before failing with `BUDGET_EXCEEDED` |
+
+**Response — 202 Accepted**
+
+```json
+{
+  "taskId": "task_c0ab38d8377cdd47",
+  "status": "pending"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 VALIDATION_ERROR` | `input` is missing or not a string |
+| `400 MODE_NOT_SUPPORTED` | Agent does not have `task.enabled: true` |
+| `404 AGENT_NOT_FOUND` | No agent with that name |
+
+---
+
+## GET /tasks
+
+List tasks for the current workspace with optional filters.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentName` | string | Filter by agent |
+| `status` | string | Filter by status: `pending`, `processing`, `finished`, `failed`, `canceled`, `waiting` |
+| `priority` | string | Filter by priority: `high`, `normal`, `low` |
+| `limit` | integer | Max results (default: 20) |
+| `cursor` | string | Pagination cursor (last task ID from previous page) |
+
+**Response**
+
+```json
+{
+  "tasks": [
+    {
+      "id": "task_c0ab38d8377cdd47",
+      "agent_name": "assistant",
+      "status": "finished",
+      "priority": "normal",
+      "input": "Read package.json and tell me the dependencies",
+      "output": "The project depends on: ajv@8.17.1, express@4.21.2...",
+      "error": null,
+      "iterations": 3,
+      "token_input": 2140,
+      "token_output": 310,
+      "tags": ["audit"],
+      "created_at": "2025-03-02T10:00:00.000Z",
+      "started_at": "2025-03-02T10:00:01.000Z",
+      "finished_at": "2025-03-02T10:00:09.000Z"
+    }
+  ]
+}
+```
+
+---
+
+## GET /tasks/:id
+
+Get full details for a single task.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Task ID |
+
+**Response**
+
+```json
+{
+  "task": {
+    "id": "task_c0ab38d8377cdd47",
+    "agent_name": "assistant",
+    "session_id": "sess_ff1122334455",
+    "status": "finished",
+    "priority": "normal",
+    "input": "...",
+    "output": "...",
+    "error": null,
+    "iterations": 3,
+    "token_input": 2140,
+    "token_output": 310,
+    "tags": [],
+    "parent_task_id": null,
+    "created_at": "2025-03-02T10:00:00.000Z",
+    "started_at": "2025-03-02T10:00:01.000Z",
+    "finished_at": "2025-03-02T10:00:09.000Z"
+  }
+}
+```
+
+**Task object fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique task ID |
+| `agent_name` | string | Agent that ran (or will run) the task |
+| `session_id` | string \| null | Session created for this task run |
+| `status` | string | Current lifecycle status |
+| `priority` | string | `high` / `normal` / `low` |
+| `input` | string | Original input text |
+| `output` | string \| null | Final agent text output (set on `finished`) |
+| `error` | object \| null | Structured error object with `code`, `message`, `iteration`, etc. (set on `failed`) |
+| `eventCount` | integer | Number of events recorded for this task |
+| `iterations` | integer | Number of LLM loop iterations used |
+| `token_input` | integer | Total input tokens |
+| `token_output` | integer | Total output tokens |
+| `tags` | string[] | Tags supplied at creation |
+| `parent_task_id` | string \| null | Set when spawned by `agent_spawn` |
+| `created_at` | ISO string | When task was created |
+| `started_at` | ISO string \| null | When processing began |
+| `finished_at` | ISO string \| null | When task reached terminal state |
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 TASK_NOT_FOUND` | No task with that ID |
+
+---
+
+## GET /tasks/:id/events
+
+Returns the list of progress events emitted during task execution. Use this for real-time tool tracing.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `since` | integer | Return only events with ID greater than this value (default: 0) |
+| `limit` | integer | Max events to return (default: 500) |
+
+**Response**
+
+```json
+{
+  "taskId": "task_c0ab38d8377cdd47",
+  "events": [
+    {
+      "id": 1,
+      "type": "status.change",
+      "data": { "from": "pending", "to": "processing" },
+      "created_at": "2025-03-02T10:00:01.000Z"
+    },
+    {
+      "id": 2,
+      "type": "tool.start",
+      "data": {
+        "toolName": "read_file",
+        "toolInput": { "path": "package.json" }
+      },
+      "created_at": "2025-03-02T10:00:02.000Z"
+    },
+    {
+      "id": 3,
+      "type": "tool.end",
+      "data": {
+        "toolName": "read_file",
+        "durationMs": 12,
+        "success": true,
+        "outputPreview": "{\n  \"name\": \"veilcli\",\n  \"version\": \"0.1.0\""
+      },
+      "created_at": "2025-03-02T10:00:02.000Z"
+    }
+  ]
+}
+```
+
+**Event types**
+
+| Type | Data fields | Description |
+|------|-------------|-------------|
+| `status.change` | `from`, `to`, `reason?` | Task status transition |
+| `tool.start` | `toolName`, `toolInput` | Tool call began |
+| `tool.end` | `toolName`, `durationMs`, `success`, `outputPreview` | Tool call completed |
+
+---
+
+## DELETE /tasks/:id
+
+Hard-delete a task and all its associated data (events, context snapshot, subscriptions).
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Task ID |
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `force` | boolean | Set to `true` to cancel and delete an active task. Without this, deleting an active task returns `409`. |
+
+**Response**
+```json
+{
+  "deleted": true,
+  "taskId": "task_c0ab38d8377cdd47"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `409 TASK_ACTIVE` | Task is in `pending`, `processing`, or `waiting` status. Use `?force=true` to override. |
+| `404 TASK_NOT_FOUND` | No task with that ID |
+
+**Examples**
+```bash
+# Delete a finished task
+curl -X DELETE http://localhost:5050/tasks/task_c0ab38d8377cdd47
+
+# Force-delete a running task (cancels first, then deletes)
+curl -X DELETE "http://localhost:5050/tasks/task_c0ab38d8377cdd47?force=true"
+```
+
+---
+
+## GET /tasks/:id/stream
+
+Real-time SSE (Server-Sent Events) stream for a single task. Replays all historical events from the database, then streams live events until the task reaches a terminal state.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `id` | Task ID |
+
+**Response** — `text/event-stream`
+
+The stream sends two SSE event types:
+
+**`event: status`** — sent once after history replay, shows current task state:
+```
+event: status
+data: {"taskId":"task_c0ab38d8377cdd47","status":"processing","output":null,"error":null}
+```
+
+**`event: task`** — one per event (both historical and live):
+```
+event: task
+data: {"id":1,"type":"status.change","data":{"from":"pending","to":"processing"},"created_at":"..."}
+
+event: task
+data: {"type":"task.event","event":{"type":"tool.start","toolName":"read_file","toolInput":{"path":"package.json"}},"timestamp":1234567890}
+```
+
+The stream auto-closes when the task reaches a terminal state (`finished`, `failed`, `canceled`). A keepalive comment is sent every 15 seconds to prevent proxy timeouts:
+```
+: keepalive
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 TASK_NOT_FOUND` | No task with that ID |
+
+**JavaScript example**
+```js
+const source = new EventSource('http://localhost:5050/tasks/task_c0ab38d8377cdd47/stream');
+
+source.addEventListener('status', (e) => {
+  const { status, output } = JSON.parse(e.data);
+  console.log('Current status:', status);
+});
+
+source.addEventListener('task', (e) => {
+  const ev = JSON.parse(e.data);
+  if (ev.type === 'tool.start' || ev.event?.type === 'tool.start') {
+    const toolName = ev.data?.toolName || ev.event?.toolName;
+    console.log('Tool call:', toolName);
+  }
+  if (ev.type === 'task.status' && ['finished','failed','canceled'].includes(ev.event?.status)) {
+    source.close();
+  }
+});
+
+source.onerror = () => source.close();
+```
+
+---
+
+## POST /tasks/:id/respond
+
+Unblock a task that is in `waiting` status. Used when an agent called `task_respond` internally or when the orchestrator needs to feed back data.
+
+**Request body**
+
+```json
+{
+  "message": "The answer is 42"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `message` | string | ✓ | Message to inject into the agent's context |
+
+**Response**
+
+```json
+{
+  "taskId": "task_c0ab38d8377cdd47",
+  "status": "processing"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 TASK_NOT_WAITING` | Task is not in `waiting` status |
+| `400 VALIDATION_ERROR` | `message` is missing |
+| `404 TASK_NOT_FOUND` | No task with that ID |
+
+---
+
+## POST /tasks/:id/cancel
+
+Cancel a task. Works for tasks in any non-terminal status. Tasks in `processing` status are cooperatively canceled — the running loop checks the cancel signal between iterations and tool calls, stopping within one cycle.
+
+**Request body** — none
+
+**Response**
+
+```json
+{
+  "taskId": "task_c0ab38d8377cdd47",
+  "status": "canceled"
+}
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 TASK_ALREADY_TERMINAL` | Task is already in `finished`, `failed`, or `canceled` status |
+| `404 TASK_NOT_FOUND` | No task with that ID |
+
+---
+
+## GET /tasks/:id/context
+
+Returns the LLM context snapshot from the most recent iteration. Useful for debugging agent behavior.
+
+**Response**
+
+```json
+{
+  "taskId": "task_c0ab38d8377cdd47",
+  "context": {
+    "messages": [
+      { "role": "system", "content": "You are..." },
+      { "role": "user", "content": "Read package.json..." },
+      { "role": "assistant", "content": null, "tool_calls": [...] }
+    ],
+    "tools": ["read_file", "bash", "list_dir"],
+    "iteration": 3,
+    "timestamp": "2025-03-02T10:00:05.000Z"
+  }
+}
+```
+
+If the task has not yet made an LLM call, `context` will be `null`.
+
+---
+
+## Polling Pattern
+
+Since tasks are asynchronous, poll `GET /tasks/:id` until status is terminal:
+
+```js
+async function pollTask(baseUrl, taskId, timeoutMs = 120000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 1500));
+    const res = await fetch(`${baseUrl}/tasks/${taskId}`);
+    const { task } = await res.json();
+    if (['finished', 'failed', 'canceled', 'waiting'].includes(task.status)) {
+      return task;
+    }
+  }
+  throw new Error('Task timed out');
+}
+
+// Usage
+const { taskId } = await fetch('http://localhost:5050/agents/assistant/task', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ input: 'Summarise README.md' }),
+}).then(r => r.json());
+
+const task = await pollTask('http://localhost:5050', taskId);
+console.log(task.output);
+```
+
+---
+
+## Live Tool Event Streaming
+
+While polling, also fetch events to see what tools the agent is using in real time:
+
+```js
+let seenIds = new Set();
+
+async function checkEvents(baseUrl, taskId) {
+  const { events } = await fetch(`${baseUrl}/tasks/${taskId}/events`).then(r => r.json());
+  for (const ev of events) {
+    if (seenIds.has(ev.id)) continue;
+    seenIds.add(ev.id);
+    if (ev.type === 'tool.start') console.log(`🔧 ${ev.data.toolName}`);
+    if (ev.type === 'tool.end')   console.log(`   ✓ ${ev.data.durationMs}ms`);
+  }
+}
+```