@newsails/veil-cli 1.0.1

package/docs/guide/10-daemons.md

@@ -0,0 +1,226 @@
+# Daemon Agents
+
+Daemon agents run automatically on a cron schedule. Each scheduled "tick" creates an isolated session, the agent reads its heartbeat file for instructions, runs its task (including tool calls), and the session closes.
+
+---
+
+## Use Cases
+
+- **Monitoring** — check system metrics, alert on anomalies
+- **Maintenance** — clean up temp files, rotate logs, prune old data
+- **Reporting** — generate daily/weekly summaries and write them to memory
+- **Data sync** — fetch external data and store it for other agents
+- **Watchdogs** — check if other tasks are stuck and take action
+
+---
+
+## Configuration
+
+Add a `daemon` mode to the agent's `agent.json`:
+
+```json
+{
+  "name": "monitor",
+  "description": "System monitor daemon",
+  "model": "moonshotai/kimi-k2.5",
+  "modes": {
+    "daemon": {
+      "enabled": true,
+      "cron": "*/5 * * * *",
+      "maxIterations": 10,
+      "maxDurationSeconds": 60,
+      "conflictPolicy": "skip",
+      "heartbeatFile": ".veil/heartbeats/monitor.md",
+      "alertRouting": "ops-team",
+      "permissions": {
+        "allow": ["bash", "read_file", "write_file", "memory_write", "web_fetch"]
+      }
+    }
+  }
+}
+```
+
+### Daemon mode fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | — | Required. Must be `true`. |
+| `cron` | string | — | Cron expression. Required for auto-start on server boot. |
+| `maxIterations` | integer | settings default | Max LLM loop iterations per tick |
+| `maxDurationSeconds` | integer | settings default | Wall-clock time limit per tick |
+| `conflictPolicy` | string | `"skip"` | What to do if a tick fires while the previous one is still running |
+| `heartbeatFile` | string | `.veil/heartbeats/<name>.md` | Path to the instructions file read each tick |
+| `alertRouting` | string \| string[] | — | Agent(s) to notify on tick error |
+
+### Conflict policies
+
+| Policy | Behaviour |
+|--------|-----------|
+| `skip` | Ignore the new tick if one is already running (default) |
+| `queue` | Queue the tick; run it once the current one finishes |
+| `restart` | Cancel the running tick and start a fresh one |
+
+---
+
+## Cron Schedule Syntax
+
+VeilCLI uses standard 5-field cron expressions:
+
+```
+* * * * *
+│ │ │ │ └── day of week (0-7, 0=Sunday)
+│ │ │ └──── month (1-12)
+│ │ └────── day of month (1-31)
+│ └──────── hour (0-23)
+└────────── minute (0-59)
+```
+
+Common examples:
+
+| Expression | Meaning |
+|------------|---------|
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour (on the hour) |
+| `0 9 * * 1-5` | 9 AM, Monday–Friday |
+| `0 0 * * *` | Midnight every day |
+| `*/30 9-17 * * 1-5` | Every 30 min, 9 AM–5 PM, weekdays |
+| `0 0 1 * *` | First of every month, midnight |
+
+---
+
+## Heartbeat File
+
+The heartbeat file contains the instructions the daemon reads at the start of each tick. It is plain Markdown.
+
+Default location: `.veil/heartbeats/<agent-name>.md`
+
+If the file does not exist, the daemon uses the default instruction:
+```
+You are running a scheduled daemon tick. Check your heartbeat file and perform your scheduled duties.
+```
+
+Example heartbeat file (`.veil/heartbeats/monitor.md`):
+```markdown
+# System Monitor — Tick Instructions
+
+Each tick, perform these checks in order:
+
+1. Run `df -h /` to check disk usage
+2. Run `free -m` to check memory usage
+3. Run `uptime` to get load averages
+4. If disk usage > 90%, write a warning to global memory
+5. If load average > 4.0, write a warning to global memory
+6. Write a brief summary of all findings to global memory with today's date
+
+Keep your response concise. Only escalate to the ops-team agent if a threshold is exceeded.
+```
+
+Update the heartbeat file at any time to change what the daemon does — no server restart required.
+
+---
+
+## Auto-start on Server Boot
+
+Daemons with a `cron` field are **auto-started** when `veil start` runs. No manual intervention needed.
+
+```bash
+veil start
+# VeilCLI v0.1.0 started on port 5050
+# Auto-started daemon: monitor
+# Auto-started daemon: cleanup
+```
+
+---
+
+## Manual Control via API
+
+Start, stop, and trigger daemons without restarting the server:
+
+```bash
+# Start scheduling
+curl -X POST http://localhost:5050/agents/monitor/daemon/start
+
+# Stop scheduling
+curl -X POST http://localhost:5050/agents/monitor/daemon/stop
+
+# Trigger an immediate tick (async — returns right away)
+curl -X POST http://localhost:5050/agents/monitor/daemon/trigger
+
+# Check active daemons
+curl http://localhost:5050/daemons
+```
+
+See [Daemons API reference](../api/06-daemons.md).
+
+---
+
+## Daemon Session Lifecycle
+
+Each tick:
+1. A new session is created (`mode: "daemon"`)
+2. The heartbeat file is read
+3. The agent runs its loop (LLM + tool calls)
+4. The session is closed
+5. The result is available in the sessions list
+
+Daemon sessions are short-lived and auto-closed. Do not try to continue a daemon session via the chat endpoint.
+
+---
+
+## Complete Example: Daily Summary Daemon
+
+**`.veil/agents/summariser/agent.json`**:
+```json
+{
+  "name": "summariser",
+  "description": "Daily project activity summariser",
+  "model": "moonshotai/kimi-k2.5",
+  "modes": {
+    "daemon": {
+      "enabled": true,
+      "cron": "0 18 * * 1-5",
+      "maxIterations": 8,
+      "maxDurationSeconds": 90,
+      "conflictPolicy": "skip",
+      "permissions": {
+        "allow": ["read_file", "list_dir", "bash", "memory_read", "memory_write"]
+      }
+    }
+  }
+}
+```
+
+**`.veil/agents/summariser/AGENT.md`**:
+```markdown
+You are Summariser, an agent that runs at 6 PM on weekdays.
+
+Your job is to:
+1. Read today's task history from memory
+2. List any recently modified files in $PROJECT_ROOT
+3. Write a brief daily summary to global memory
+
+Keep summaries factual and concise (3-5 bullet points max).
+```
+
+**`.veil/heartbeats/summariser.md`**:
+```markdown
+# Daily Summary — 6 PM Run
+
+1. Run `git log --oneline --since="24 hours ago"` to see today's commits
+2. Check global memory for any notes added today
+3. Write a daily summary entry to global memory including:
+   - Number of commits
+   - Key changes (from commit messages)
+   - Any flagged issues from memory
+```
+
+**Start the server** — daemon auto-starts:
+```bash
+veil start
+# Auto-started daemon: summariser
+```
+
+**Or trigger manually**:
+```bash
+curl -X POST http://localhost:5050/agents/summariser/daemon/trigger
+```

package/docs/guide/README.md

@@ -0,0 +1,53 @@
+# VeilCLI — Project Guide
+
+This guide covers everything you need to set up, configure, and operate VeilCLI.
+
+---
+
+## Contents
+
+| Doc | Topic |
+|-----|-------|
+| [01-quickstart.md](01-quickstart.md) | Install, create your first agent, run your first request |
+| [02-folder-structure.md](02-folder-structure.md) | The `.veil/` workspace layout explained |
+| [03-configuration.md](03-configuration.md) | `settings.json` + `auth.json` — every field |
+| [04-agents.md](04-agents.md) | `agent.json`, `AGENT.md`, and all 4 agent modes |
+| [05-cli.md](05-cli.md) | `veil` CLI commands reference |
+| [06-tools.md](06-tools.md) | All 24 built-in tools |
+| [07-permissions.md](07-permissions.md) | Tool permission system — allow/deny/ask |
+| [08-memory.md](08-memory.md) | Persistent memory and context compaction |
+| [09-multi-agent.md](09-multi-agent.md) | Multi-agent orchestration patterns |
+| [10-daemons.md](10-daemons.md) | Daemon / cron agents |
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────┐
+│             REST API (Express)           │
+│  /agents  /tasks  /sessions  /daemons   │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│              Core Runtime               │
+│  router.js → loop.js → tool registry   │
+│  prompt assembly → LLM client           │
+└──────────┬────────────────┬────────────┘
+           │                │
+┌──────────▼──────┐  ┌──────▼──────────┐
+│  SQLite (db)    │  │  File system     │
+│  sessions       │  │  .veil/agents/ │
+│  tasks          │  │  .veil/memory/ │
+│  messages       │  │  .veil/auth.json│
+│  events         │  │  settings.json   │
+│  todos          │  └─────────────────┘
+└─────────────────┘
+```
+
+**Key concepts:**
+- **Workspace** — any directory with a `.veil/` folder. One server instance per workspace.
+- **Agent** — a folder in `.veil/agents/<name>/` with `agent.json` + `AGENT.md`.
+- **Session** — a conversation thread. Created automatically per chat turn or task run.
+- **Task** — an async agent run. Returns a `taskId` immediately; poll for completion.
+- **Daemon** — an agent that runs on a cron schedule.