@newsails/veil-cli 1.0.1

package/PLAN/08-api-cli.md

@@ -0,0 +1,153 @@
+# 08 — API & CLI
+
+## REST API
+
+**Base URL:** `http://localhost:5050` (configurable)
+**Auth:** Optional `X-Veil-Secret` header
+**Format:** JSON request/response. No streaming. No WebSocket. Chat requests block until the agent responds (HTTP long-poll). Clients should set appropriate timeouts.
+**Pagination:** Cursor-based for list endpoints (`?cursor=<id>&limit=20`)
+**Errors:** Standard format: `{ "error": { "code": "ERROR_CODE", "message": "..." } }`
+
+> **CWD in routes:** Routes never call `process.cwd()`. The project working directory is passed from the CLI at startup and stored in `src/utils/context.js`. Routes call `context.getCwd()` to get the correct project directory. This prevents routes from silently scanning the wrong folder when the server is started from a different directory.
+
+### Endpoints
+
+#### Agents
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/agents` | List all discovered agents |
+| GET | `/agents/:name` | Get agent details (config, modes, skills, tools) |
+
+#### Chat Mode
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/agents/:name/chat` | Send message (creates session or resumes) |
+
+**Request:**
+```json
+{
+  "message": "Hello, agent!",
+  "sessionId": "sess_abc123",
+  "files": [{ "path": "./src/auth.js" }]
+}
+```
+**Response:**
+```json
+{
+  "sessionId": "sess_abc123",
+  "message": { "role": "assistant", "content": "..." },
+  "tokenUsage": { "input": 1500, "output": 300, "cache": 0 }
+}
+```
+
+#### Task Mode
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/agents/:name/task` | Create a new task |
+| GET | `/tasks` | List tasks (filter: agent, status, priority, tags) |
+| GET | `/tasks/:id` | Get task details |
+| GET | `/tasks/:id/events` | Get task progress events |
+| POST | `/tasks/:id/respond` | Respond to a waiting task |
+| POST | `/tasks/:id/cancel` | Cancel a task |
+
+**Create task request:**
+```json
+{
+  "input": "Research the best auth libraries for Node.js",
+  "priority": "high",
+  "tags": ["research", "auth"],
+  "files": [{ "path": "./requirements.md" }],
+  "maxIterations": 30,
+  "maxDurationSeconds": 600
+}
+```
+**Create task response:**
+```json
+{
+  "taskId": "task_xyz789",
+  "status": "pending"
+}
+```
+
+#### Daemon Mode
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/daemons` | List active daemons (status, next tick, last result). State is in-memory, rebuilt from agent.json on restart. |
+| POST | `/agents/:name/daemon/trigger` | Trigger a daemon tick manually |
+| POST | `/agents/:name/daemon/start` | Start a daemon |
+| POST | `/agents/:name/daemon/stop` | Stop a daemon |
+
+#### Sessions
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/sessions` | List sessions (filter: agent, mode, status) |
+| GET | `/sessions/:id` | Get session details |
+| GET | `/sessions/:id/messages` | Get messages (paginated) |
+| DELETE | `/sessions/:id` | Close/delete session |
+
+#### System
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| GET | `/status` | System status (uptime, agents, sessions, tasks, daemons) |
+| POST | `/shutdown` | Graceful shutdown |
+
+### Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `AGENT_NOT_FOUND` | 404 | Agent doesn't exist |
+| `MODE_NOT_SUPPORTED` | 400 | Agent doesn't support requested mode |
+| `TASK_NOT_FOUND` | 404 | Task doesn't exist |
+| `SESSION_NOT_FOUND` | 404 | Session doesn't exist |
+| `SESSION_CLOSED` | 400 | Session is closed |
+| `TASK_NOT_WAITING` | 400 | Task is not in waiting status |
+| `PERMISSION_DENIED` | 403 | Invalid or missing secret |
+| `VALIDATION_ERROR` | 400 | Invalid request body |
+| `INTERNAL_ERROR` | 500 | Unexpected error |
+
+---
+
+## CLI
+
+### Server Mode
+```
+veil start [--port <n>] [--folder <path>] [--secret <s>] [--ably]
+```
+- Loads all agent definitions, auto-starts daemons, exposes REST API
+- Writes PID file to `.veil/runtime.pid`
+- Sets `context.setCwd(cwd)` at startup — used by all routes and agents internally
+
+> **Settings location:** Project settings must be in `.veil/settings.json`, NOT `./settings.json` at the project root. The root-level `settings.json` is never read. This is a common mistake when setting up a new project.
+
+### One-Shot Mode
+```
+veil run --agent <name> --input "..." [--input-file <path>] [--output-file <path>] [--timeout <s>]
+```
+- Creates a task, runs to completion, exits
+- Progress to stdout: `VEIL_PROGRESS={"type":"tool.end","name":"grep","duration":120}`
+- Exit 0 on success (result JSON to stdout), exit 1 on failure (error JSON to stderr)
+- Multiple one-shot instances can run in parallel (shared SQLite via WAL)
+
+### Management Commands
+```
+veil stop                          # Graceful shutdown
+veil status                        # Show running server info
+veil agents list                   # List all discovered agents
+veil agents inspect <name>         # Show agent details
+veil agents create                 # Interactive agent creation wizard
+```
+
+### Import
+```
+veil import --type=claude-code|openclaw|raw --source <path>
+```
+- Transforms source format to VeilCLI format
+- Interactive: asks follow-up questions to configure agent modes
+- Extensible adapter system
+
+### Login
+```
+veil login --key <token> [--global]
+```
+- Default: stores in project `.veil/auth.json`. With `--global`: stores in `~/.veil/auth.json`.

package/PLAN/09-permissions.md

@@ -0,0 +1,108 @@
+# 09 — Permissions & Hooks
+
+## Permission System
+
+Adopted from Claude Code. Evaluated in order: **deny → ask → allow**.
+
+### Permission Format
+```
+tool_name(pattern)
+
+Examples:
+  bash(npm run *)          ← bash commands starting with "npm run"
+  read_file(**)            ← read any file recursively
+  write_file(./src/**)     ← write anywhere in src/
+  edit_file(./src/**)      ← edit anywhere in src/
+  web_fetch(https://api.*) ← fetch from api.* domains
+```
+
+**Tool names are snake_case** — must match exactly. All built-in tools use snake_case (`bash`, `read_file`, `write_file`, `web_fetch`, etc.).
+
+### MCP Tool Permissions
+
+MCP tools use the format `mcp:<server>.<tool>`:
+```
+  mcp:filesystem.read_file(**)     ← MCP filesystem server's read_file
+  mcp:database.query(SELECT *)     ← MCP database server's query tool
+  mcp:*.*(**)                       ← all MCP tools (wildcard)
+```
+
+### Defaults
+- **Always denied:** `read_file(./.veil/auth.json)`, `read_file(~/.veil/auth.json)`
+- **Interactive mode (chat):** default `ask` — agent requests permission, user approves
+- **Non-interactive mode (task, daemon, subagent, one-shot):** default `deny` — must be explicitly allowed
+
+### Configuration Layers
+
+Permissions resolved in order (last wins):
+```
+1. Built-in defaults (auth.json always denied)
+2. ~/.veil/settings.json → permissions
+3. ./.veil/settings.json → permissions
+4. ./.veil/settings.local.json → permissions
+5. agent.json → modes.<mode>.permissions   ← per-agent, per-mode overrides
+```
+
+### Interaction with `disallowedTools`
+
+The permission system and `disallowedTools` in agent.json are complementary:
+- **`disallowedTools`** — removes the tool entirely from the agent's toolset (LLM never sees it)
+- **Permissions** — controls whether a visible tool can actually execute (deny/ask/allow)
+
+Resolution order: `disallowedTools` checked first (tool removed) → then permissions checked (tool allowed/denied).
+
+Per-agent, per-mode permissions in agent.json support `allow` and `deny` only. The `ask` level is only available in settings.json because it requires interactive user approval, which is a global behavior — not agent-specific.
+
+Example:
+```json
+{
+  "modes": {
+    "task": {
+      "permissions": {
+        "allow": ["bash(npm run *)", "read_file(**)", "write_file(./src/**)"],
+        "deny": ["bash(rm *)"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Hooks
+
+Two hooks only: **PreToolUse** and **PostToolUse**. Shell commands defined in settings.json.
+
+### Configuration
+```json
+{
+  "hooks": {
+    "PreToolUse": "node .veil/hooks/pre-tool.js",
+    "PostToolUse": "node .veil/hooks/post-tool.js"
+  }
+}
+```
+
+### Environment Variables
+Hooks receive context via environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `VEIL_TOOL_NAME` | Tool being called (e.g., `bash`, `write_file`) |
+| `VEIL_TOOL_INPUT` | JSON-encoded tool input |
+| `VEIL_TOOL_OUTPUT` | JSON-encoded tool output (PostToolUse only) |
+| `VEIL_AGENT_NAME` | Agent calling the tool |
+| `VEIL_SESSION_ID` | Current session ID |
+| `VEIL_TASK_ID` | Current task ID (if in task mode) |
+| `VEIL_MODE` | Current mode: chat/task/daemon/subagent |
+| `VEIL_AGENT_FOLDER` | Absolute path to agent's folder |
+
+### Behavior
+- **PreToolUse:** Exit 0 → allow tool execution. Exit 1 → block (tool returns error to LLM).
+- **PostToolUse:** Exit 0 → continue. Exit 1 → log warning (tool already executed).
+- **Timeout:** 10s default. Hook killed on timeout, tool proceeds.
+
+### Use Cases
+- `PreToolUse` where `VEIL_TOOL_NAME=bash` → validate bash commands before execution
+- `PostToolUse` where `VEIL_TOOL_NAME=write_file` → trigger lint/format after file write
+- `PreToolUse` → log all tool calls to external audit system

package/PLAN/10-ably.md

@@ -0,0 +1,105 @@
+# 10 — Ably Remote Access
+
+## Overview
+
+When enabled, VeilCLI subscribes to an Ably channel and relays REST API calls over it. This allows remote consumers (web app, mobile app, Veil.com dashboard) to interact with a local VeilCLI instance without port forwarding.
+
+```
+[Remote Client] → [Veil.com] → [Ably Channel] → [VeilCLI (local)]
+                                                          ↓
+                                                    REST API handler
+                                                          ↓
+                                                    [Ably Channel] → [Veil.com] → [Remote Client]
+```
+
+## Channel Architecture
+
+**One channel per VeilCLI instance** (not per agent or session).
+
+- Channel name: `veil:instance:<instanceId>`
+- `instanceId` assigned by Veil.com on registration
+- Namespace `veil:` allows applying Ably channel rules globally
+
+**Message name routing** on the single channel:
+- `api:request` — remote client → VeilCLI
+- `api:response` — VeilCLI → remote client
+- `task:progress` — VeilCLI pushes task progress events
+- `system:ping` / `system:pong` — health checks
+
+## Message Format (RPC over Pub/Sub)
+
+Request/response via **correlation IDs** (`requestId`).
+
+**Request:**
+```json
+{
+  "requestId": "req_a1b2c3d4",
+  "method": "POST",
+  "path": "/agents/researcher/task",
+  "headers": { "X-Veil-Secret": "mysecret" },
+  "body": { "input": "Research topic X" },
+  "timestamp": 1740793200000,
+  "timeout": 30000
+}
+```
+
+**Response:**
+```json
+{
+  "requestId": "req_a1b2c3d4",
+  "status": 200,
+  "body": { "taskId": "task_xyz789", "status": "pending" },
+  "timestamp": 1740793201500,
+  "duration": 1500
+}
+```
+
+## Authentication Flow
+
+1. VeilCLI starts with `ably.enabled: true`
+2. Creates Ably Realtime client with `authCallback`
+3. `authCallback` calls Veil.com: `POST /api/v1/ably/token` with `veil_token`
+4. Veil.com validates token, issues scoped Ably TokenRequest (1h TTL)
+5. Ably SDK handles automatic token refresh before expiry
+6. VeilCLI enters presence on its channel to signal "online"
+
+**Remote clients never connect to Ably directly.** Veil.com relays on their behalf.
+
+## Reliability
+
+| Offline Duration | Ably State | Behavior |
+|-----------------|------------|----------|
+| 0–2 min | `disconnected` | Auto-reconnect. Missed messages replayed. |
+| >2 min | `suspended` | Messages during gap are lost. Re-enter presence on reconnect. |
+| Extended | `failed` | Auth token expired. Log error, await manual reconnect. |
+
+**Stale request handling:** Requests with `timestamp` older than `timeout` are skipped — remote client already timed out.
+
+## Limits
+
+- **Message size:** 64 KiB. Responses >60 KiB truncated with `{ "truncated": true, "fetchUrl": "/messages/msg_xyz/full" }`.
+- **Rate:** 50 msg/s per channel (sufficient for VeilCLI's use case).
+- **Latency overhead:** ~100-300ms round-trip. Negligible vs LLM call time.
+
+## Security
+
+Even though VeilCLI trusts Veil.com:
+- Validate incoming message schema (required fields, method whitelist)
+- Local `X-Veil-Secret` still required in relayed requests
+- Track recent `requestId`s to reject duplicates
+- Permission system still applies to all tool calls via Ably
+- Optional: AES-256-CBC per-channel encryption for high-security deployments
+
+## Settings
+
+```json
+{
+  "ably": {
+    "enabled": false,
+    "instanceId": "",
+    "tokenEndpoint": "https://veil.com/api/v1/ably/token",
+    "requestTimeout": 30000,
+    "maxRequestAge": 60000
+  }
+}
+```