@newsails/veil-cli 1.0.1

package/PLAN/02-tech-stack.md

@@ -0,0 +1,94 @@
+# 02 — Tech Stack
+
+## Language
+
+**Node.js + JSDoc** (no TypeScript). Plain JavaScript with JSDoc type annotations for IDE support and type checking.
+
+> **v2 Note:** TypeScript is strongly recommended for a future version. Most of the function-signature mismatches, missing exports, and field-name inconsistencies discovered during testing would be caught at compile time.
+
+## Dependencies (Minimal Set)
+
+| Concern | Package | Justification |
+|---------|---------|---------------|
+| **LLM Client** | native `fetch` (built-in) | Node 18+ built-in. No SDK version drift. Works with any OpenAI-compatible endpoint (OpenRouter, Anthropic, Ollama, LM Studio, etc.) without external dependencies. |
+| **REST Server** | `express` | Simplest, most maintained, vast middleware ecosystem |
+| **CORS** | `cors` | Required by express for cross-origin requests |
+| **Validation** | `ajv` + `ajv-formats` | JSON Schema validator, compiles schemas to fast native functions. `ajv-formats` required for `date-time` and other format validators. |
+| **Database** | `better-sqlite3` | Fastest SQLite for Node.js, synchronous (optimal for local) |
+| **Cron** | `node-cron` | Lightweight, Unix-native cron syntax |
+| **MCP Client** | TBD (existing lib) | Not custom-built, supports stdio + Streamable HTTP |
+| **CLI Parsing** | `util.parseArgs` | Built-in Node.js (>=18.3), zero external deps |
+
+**Rejected alternatives:**
+- `openai` SDK — SDK versioning caused `OpenAI is not a constructor` failures (v3 vs v4 API mismatch). Native `fetch` is simpler, portable, and requires no versioning decisions.
+- `nanoid` — was missing from package.json, caused runtime crash. Replaced by `crypto.randomBytes()` from Node's built-in `crypto` module (see `src/utils/id.js`).
+- `fastify` — more complex setup for marginal perf gain
+- `langchain` / `@vercel/ai` — framework lock-in
+- `sqlite3` (async) — slower than sync for local operations
+- `yargs` / `commander` — unnecessary weight when `util.parseArgs` exists
+- `chokidar` — not needed (no file watching for agent discovery)
+
+## LLM Interface
+
+Single interface for all providers using native `fetch`:
+```
+base_url + api_key + model_name
+```
+
+Works with: OpenRouter, Anthropic, OpenAI, Google, Ollama, LM Studio, or any OpenAI-compatible endpoint. No provider-specific code paths. No SDK version to manage.
+
+```javascript
+// src/llm/client.js — fetch-based, no SDK dependency
+async function callLLM({ baseUrl, apiKey, model, messages, tools }) {
+  const response = await fetch(`${baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({ model, messages, tools })
+  });
+  if (!response.ok) throw new Error(`LLM error: ${response.status}`);
+  return response.json();
+}
+```
+
+## ID Generation
+
+Use `crypto.randomBytes()` from Node's built-in `crypto` module. **Do not use `nanoid`** — it must be installed as an external dependency and was the cause of runtime crashes when omitted from `package.json`.
+
+```javascript
+// src/utils/id.js
+const crypto = require('crypto');
+function generateId(prefix) {
+  return `${prefix}${crypto.randomBytes(8).toString('hex')}`;
+}
+// Usage: generateId('sess_') → 'sess_a1b2c3d4e5f6g7h8'
+```
+
+## Node.js Version
+
+Minimum: **Node.js 18.3+** (for native `fetch`, `util.parseArgs`, `node:test`, and `AbortController`).
+
+**Enforced two ways:**
+
+1. `package.json` engines field:
+```json
+{ "engines": { "node": ">=18.3.0" } }
+```
+
+2. Runtime check at startup entry point:
+```javascript
+const [major] = process.version.slice(1).split('.').map(Number);
+if (major < 18) {
+  console.error(`VeilCLI requires Node.js 18+. Current: ${process.version}`);
+  process.exit(1);
+}
+```
+
+## Dependency Discipline
+
+- Use **exact versions** in `package.json` (no `^` or `~` for production deps)
+- Run `npm ci` in CI, not `npm install`
+- Audit `package.json` completeness before any commit (ensure all `require()`d packages are listed)
+- All built-in Node.js modules must be listed as comments in `package.json` (`// built-in: crypto, path, fs, util`) to make dependency inventory obvious

package/PLAN/03-agents.md

@@ -0,0 +1,232 @@
+# 03 — Agent Architecture
+
+## Core Concept
+
+An **agent** is an autonomous AI entity defined by files. **How it's invoked** (chat, task, daemon, subagent) is a **mode**, not a type. The same agent can support multiple modes with different tools, skills, and permissions per mode.
+
+> **Required location:** Agents MUST be placed in `.veil/agents/<agentName>/`. A directory named `agents/` at the project root is NOT scanned. This is not configurable. Claude Code projects must be imported via `veil import` first.
+
+## Agent Definition (Two Files)
+
+Agent folders are **static and read-only** — safe to download from a registry, version in git, or share between projects. All mutable state (memory, heartbeats) lives elsewhere in `.veil/`.
+
+```
+.veil/agents/<agentName>/
+├── AGENT.md        ← Instructions / system prompt (read-only)
+├── agent.json      ← Configuration (modes, model, tools, permissions)
+├── SOUL.md         ← Optional persona and behavioral identity
+├── skills/         ← Agent-specific skills
+│   └── <skillName>/
+│       ├── SKILL.md
+│       └── scripts/    ← Scripts referenced by the skill
+└── tools/          ← Agent-level custom tools (scoped to this agent only)
+    └── <toolName>/
+        ├── tool.json
+        └── index.js
+```
+
+### AGENT.md
+Plain markdown. The agent's instructions, rules, and personality. Always loaded into the system prompt. No configuration here — that goes in `agent.json`.
+
+### agent.json
+All configuration. Defines which modes the agent supports and how each mode behaves.
+
+> **Validated at load time.** Every `agent.json` is validated against the JSON schema using ajv when the runtime loads an agent. Invalid files cause a startup error with a clear message — the agent will not be available until fixed. This catches field type errors early rather than causing silent failures during LLM calls.
+
+```json
+{
+  "name": "researcher",
+  "description": "Deep research agent that investigates topics",
+  "model": "anthropic/claude-3.5-sonnet",
+  "temperature": 0.7,
+  "reasoning": "medium",
+  "memory": { "enabled": true, "maxLines": 200 },
+  "skillDiscovery": true,
+  "modes": {
+    "chat": {
+      "enabled": true,
+      "model": "anthropic/claude-3.5-sonnet",
+      "temperature": 0.7,
+      "tools": [],
+      "disallowedTools": [],
+      "skills": [],
+      "autoLoadSkills": [],
+      "mcpServers": [],
+      "allowedAgents": [],
+      "disallowedAgents": [],
+      "permissions": {}
+    },
+    "task": {
+      "enabled": true,
+      "model": "anthropic/claude-3.5-sonnet",
+      "temperature": 0.5,
+      "reasoning": "medium",
+      "tools": [],
+      "disallowedTools": ["bash"],
+      "skills": [],
+      "autoLoadSkills": [],
+      "mcpServers": [],
+      "allowedAgents": [],
+      "disallowedAgents": ["deploy-prod"],
+      "maxIterations": 50,
+      "maxDurationSeconds": 300,
+      "permissions": {}
+    },
+    "subagent": {
+      "enabled": true,
+      "model": "anthropic/claude-3-haiku",
+      "temperature": 0.3,
+      "reasoning": "medium",
+      "tools": ["web_search", "read_file", "grep"],
+      "disallowedTools": [],
+      "skills": ["summarize"],
+      "autoLoadSkills": [],
+      "mcpServers": [],
+      "allowedAgents": [],
+      "disallowedAgents": [],
+      "maxIterations": 20,
+      "maxDurationSeconds": 120,
+      "permissions": {}
+    },
+    "daemon": {
+      "enabled": false,
+      "model": "anthropic/claude-3-haiku",
+      "temperature": 0,
+      "reasoning": "medium",
+      "cron": "*/5 * * * *",
+      "triggers": ["task.completed", "task.failed"],
+      "conflictPolicy": "skip",
+      "alertRouting": ["log", "webhook:https://slack.com/webhook/xxx"],
+      "heartbeatFile": "",
+      "tools": [],
+      "disallowedTools": [],
+      "skills": [],
+      "autoLoadSkills": [],
+      "mcpServers": [],
+      "allowedAgents": [],
+      "disallowedAgents": [],
+      "permissions": {}
+    }
+  }
+}
+```
+
+**Critical field type rules (these caused real failures during testing):**
+- **`model`** — must be a **string** e.g. `"anthropic/claude-3.5-sonnet"`. NOT an object like `{ "role": "main" }`. Using an object here causes every agent to fail schema validation.
+- **`modes.chat` / `modes.task` / etc.** — must be an **object** with at minimum `{ "enabled": boolean }`. NOT a bare boolean like `true` or `false`. Using a bare boolean here causes every agent to fail schema validation.
+
+**Field rules:**
+- **`tools`** — non-empty = whitelist (only these tools). Empty = all available.
+- **`disallowedTools`** — non-empty = blacklist (all tools EXCEPT these). Empty = no exclusions.
+- `tools` and `disallowedTools` are mutually exclusive — setting both non-empty is a validation error. Both empty = all tools allowed (not an error).
+- Same whitelist/blacklist logic for `allowedAgents`/`disallowedAgents`. `skills` and `mcpServers` are whitelist-only (empty = all).
+- **`skillDiscovery`** — when `false`, no skill names/descriptions listed in system prompt. Agent is skill-blind unless given via `autoLoadSkills`. Default: `true`.
+- **`memory.enabled`** — enables persistent memory for this agent. Default: `true`.
+- **`memory.maxLines`** — MEMORY.md line cap before auto-export. Default: 200 (from settings.json). Per-agent override.
+- **`mcpServers`** — whitelist of MCP server names. Empty = all configured servers available.
+- **`allowedAgents`/`disallowedAgents`** — controls which agents this agent can spawn/message. Available in all modes. Empty = all agents.
+- **`heartbeatFile`** — path to heartbeat checklist for daemon mode. Default: `.veil/heartbeats/<agentName>.md`.
+- `autoLoadSkills` = skills whose full content is always in the system prompt (not on-demand)
+- `permissions` = per-mode overrides (empty = inherit from settings.json)
+- `model` at root = default for all modes. Per-mode `model` overrides the root value.
+- `temperature` at root = default for all modes. Per-mode `temperature` overrides the root value.
+- `reasoning` at root = default for all modes. Per-mode `reasoning` overrides the root value.
+- **`alertRouting`** — array of routing targets: `"log"`, `"webhook:<url>"`, `"agent:<name>"`, `"ably:<channel>"`. Single string also accepted.
+
+## `$AGENT_FOLDER` Variable
+
+The runtime exposes `$AGENT_FOLDER` as a template variable in AGENT.md, SKILL.md, and heartbeat files. Resolved at load time to the **absolute path** of the agent's folder.
+
+This lets agents and skills reference co-located scripts:
+```markdown
+Use the script at $AGENT_FOLDER/skills/scrape/scripts/url_to_markdown.js to convert URLs to markdown.
+```
+
+Resolved example: `$AGENT_FOLDER` → `/home/user/project/.veil/agents/scraper`
+
+Also available as the `VEIL_AGENT_FOLDER` environment variable in:
+- Custom tool execution
+- Skill scripts (referenced in SKILL.md)
+- PreToolUse / PostToolUse hooks
+
+**Not available in:** MCP tool execution (MCP servers are external processes with their own environment).
+
+## Example Agents
+
+The source tree ships an `examples/` directory with reference agents that:
+- Are guaranteed to pass the JSON schema validator
+- Have correct field types (string model, object modes)
+- Are used directly in smoke tests and documentation
+
+Minimal reference: `examples/agents/hello/` — a simple chat-only agent. Always check this when unsure about the correct format before writing a new `agent.json` from scratch.
+
+## Invocation Modes
+
+### Chat Mode
+- **Trigger:** API call `POST /agents/:name/chat`
+- **Behavior:** Synchronous request/response. Stateful via sessions. User sends message, agent responds.
+- **Session:** Created on first message, resumed via session_id.
+- **Completion:** Never "completes" — session stays open until closed.
+
+### Task Mode
+- **Trigger:** API call `POST /agents/:name/task` or CLI `veil run --agent <name>`
+- **Behavior:** Asynchronous. Agent runs autonomously to completion.
+- **Status flow:** `pending` → `processing` → `waiting` → `finished` / `failed` / `canceled`
+- **Completion:** Agent decides it's done (no more tool calls) or hits limits.
+- **Waiting:** Agent can pause and wait for human input via `task_respond`.
+
+### Daemon Mode
+- **Trigger:** Cron schedule or **system-wide** event trigger (task.completed, task.failed, agent.error)
+- **System-wide events:** These fire when ANY task in the system completes/fails — not a specific one. The daemon gets woken up to handle it. This is different from `task_subscribe` (which an already-running agent uses to watch a specific task it created).
+- **Behavior:** Each tick: reads heartbeat file (from `.veil/heartbeats/<agentName>.md` or custom path), decides action, outputs result.
+- **Output contract:** Must output `HEARTBEAT_OK` or `HEARTBEAT_ALERT: <message>`
+- **Alert routing:** Configured in agent.json — log, webhook URL, another agent, Ably channel.
+- **Conflict policy:** What to do when tick fires mid-execution:
+  - `skip` — discard this tick, no-op
+  - `queue` — add to FIFO queue (max 10 pending ticks, oldest dropped if exceeded)
+  - `restart` — cancel running tick immediately, start new one
+- **Auto-start:** All agents with `daemon.enabled: true` start on `veil start`.
+
+### Sub-Agent Mode
+- **Trigger:** Another agent calls `agent_spawn(agent: "<name>")` (sync or async)
+- **Behavior:** Uses `modes.subagent` config for tools/skills/permissions. (`task_create` always uses `modes.task`, not subagent.)
+- **Sync vs Async:** `agent_spawn(wait: true)` blocks until sub-agent completes (default). `agent_spawn(wait: false)` returns a `taskId` immediately — sub-agent runs in background, result retrievable via `task_status`.
+- **Purpose:** An agent may need different behavior when called as a sub-agent vs running independently. For example, a "researcher" agent might have full web_search + bash in chat mode, but only web_search + read_file when spawned as a sub-agent.
+- **Parallel fan-out:** An orchestrator can `agent_spawn(wait: false)` × N to run multiple sub-agents in parallel. Caller is auto-subscribed — notifications arrive as each completes. Results retrieved via `task_status`.
+- **Fallback:** If `modes.subagent` is not defined or not enabled, the runtime falls back to `modes.chat` config. If `modes.chat` is also not enabled, the spawn fails with an error. Fallback emits a warning log.
+
+## Sub-Agents
+
+Any agent can be a sub-agent. The `subagent` mode gives fine-grained control over behavior when called by other agents.
+
+- **`agent_spawn`** — Sync (`wait: true`, default) or async (`wait: false`). Creates an isolated context window using `modes.subagent`. Sync returns condensed result directly. Async returns `taskId` for later retrieval.
+- **`task_create`** — Always asynchronous. Creates a task in the queue using `modes.task`. Parent can continue or wait.
+
+Built-in agent patterns (all just regular agents with specific tool configs):
+- **Explore** — read-only tools (read_file, grep, glob, list_dir, web_search)
+- **Plan** — read-only + todo_write, no execution tools
+- **Execute** — full tool access
+
+## Built-in Hidden Agents
+
+Shipped with the runtime, not visible to users:
+- **compact** — Context compaction (uses `compact` model)
+- **title** — Session title generation (uses `title` model)
+- **summary** — Session summary generation (uses `title` model)
+
+## Agent Discovery
+
+Agent resolution order (when an agent is needed by name):
+
+```
+1. ./.veil/agents/<name>/     ← project-local (user owns, never auto-updated)
+2. ~/.veil/agents/<name>/     ← global (auto-updated if version hash differs)
+3. Veil.com registry          ← remote (if connected, cached locally)
+4. NOT FOUND → error
+```
+
+**Startup scan:** On `veil start`, the runtime scans agent folders to auto-start daemons (`daemon.enabled: true`) and populate the `GET /agents` list. No file watcher — agents added after startup are discovered on next invocation or restart.
+
+Global instructions: `.veil/AGENT.md` only. No fallback to project root. Claude Code projects must be converted via `veil import`.
+
+> **Common mistake:** Placing agents in `./agents/` (visible project root directory) instead of `./.veil/agents/`. The runtime only scans `.veil/agents/` and `~/.veil/agents/`. Agents in the wrong location will silently not appear in `GET /agents`.

package/PLAN/04-runtime.md

@@ -0,0 +1,171 @@
+# 04 — Agent Runtime
+
+## Agentic Loop
+
+The core execution model. Runs identically for all modes — the mode only determines how the loop is started and how results are returned.
+
+```
+Load agent definition (AGENT.md + agent.json)
+    ↓
+Compile system prompt (7-layer assembly)
+    ↓
+Send to LLM (via native fetch — OpenAI-compatible API)
+    ↓
+LLM responds with text and/or tool_calls
+    ↓
+┌─ If tool_calls: ──────────────────────────────┐
+│   For each tool call:                          │
+│     1. Drain message queue (inject pending)    │
+│     2. Check permissions (deny/ask/allow)      │
+│     3. Run PreToolUse hook                     │
+│     4. Validate args against JSON Schema (ajv) │
+│     5. Execute tool                            │
+│     6. Run PostToolUse hook                    │
+│     7. Append tool result to messages          │
+│   Loop back to "Send to LLM"                  │
+└────────────────────────────────────────────┘
+┌─ If no tool_calls: ───────────────────────────┐
+│   Chat mode: return response to user           │
+│   Task mode: check if agent is done or stuck   │
+│   Daemon mode: parse HEARTBEAT_OK/ALERT        │
+│   Drain followup queue (inject followup msgs)  │
+└────────────────────────────────────────────┘
+    ↓
+Check limits:
+  - max_iterations reached? → fail
+  - max_duration reached? → fail
+  - context > 85% threshold? → extract memories → trigger compaction → continue
+```
+
+**Implementation pattern:** Async generators (`async function*`). Each iteration yields a state event, allowing consumers (API, CLI) to observe progress without coupling.
+
+**Function interface discipline:** All core functions use **object-destructuring parameters**, not positional arguments. This prevents signature mismatch bugs (a real source of failures found in testing) and makes call sites self-documenting:
+```javascript
+// Correct — named params, order-independent:
+async function runChat({ agent, message, sessionId, settings, cwd }) { ... }
+
+// Wrong — positional, fragile:
+async function runChat(agent, message, options) { ... }
+```
+All public functions in `src/core/`, `src/api/`, and `src/cli/` follow this convention. JSDoc `@param` annotations are required on all exported functions.
+
+## Model Delegation (v1)
+
+Three model roles. Each can have a different `base_url` + `api_key` + `model`.
+
+```json
+{
+  "models": {
+    "main": { "model": "anthropic/claude-3.5-sonnet" },
+    "compact": { "model": "anthropic/claude-3-haiku" },
+    "title": { "model": "anthropic/claude-3-haiku" }
+  }
+}
+```
+
+| Role | Used For | Typical Model |
+|------|----------|---------------|
+| `main` | Reasoning, planning, tool decisions, file edits (str_replace) | Claude 3.5 Sonnet, GPT-4o |
+| `compact` | Context compaction / summarization | Claude Haiku, GPT-4o-mini |
+| `title` | Session title, session summary | Cheapest available |
+
+If only `main` is configured, all roles fall back to `main`.
+
+**LLM calls use native `fetch` directly** — no OpenAI SDK. See `02-tech-stack.md` and `src/llm/client.js`. The `callLLM()` function validates its inputs before calling the API:
+```javascript
+async function callLLM({ baseUrl, apiKey, model, messages, tools = [] }) {
+  if (!Array.isArray(tools)) throw new Error('tools must be an array');
+  if (!Array.isArray(messages) || messages.length === 0) throw new Error('messages must be a non-empty array');
+  // ... fetch call
+}
+```
+Failing fast on bad inputs prevents silent failures where tool calls never reach the LLM.
+
+**Apply layer deferred to future version.** For v1, `edit_file` uses search-and-replace via the main model (like Claude Code).
+
+## Context Engineering
+
+### Auto-Compaction
+- Triggered when context window usage exceeds **85%** (configurable)
+- Hidden `compact` agent summarizes conversation history (runs using the `compact` model role from settings.json)
+- Preserves: key decisions, unresolved issues, file paths, active TODOs, error patterns
+- Result replaces old messages with a single compacted summary message
+- TODOs from `todo_write` are always included in compacted context
+
+### Pre-Compaction Memory Extraction
+Before compaction runs, the runtime asks the main model:
+> "What key facts, decisions, or learnings from this conversation should be remembered long-term?"
+
+- Model returns structured memories → runtime writes them to agent's MEMORY.md via `memory_write`
+- Model can return `NO_MEMORY` to skip
+- Only runs if `memory.enabled: true` in agent.json (default: on)
+- This ensures important context survives compaction even if the agent didn't explicitly `memory_write`
+
+### Context Trimming (applied every iteration, in order)
+
+**Execution order:**
+1. **Observation masking** (first) — Tool outputs beyond 10 turns old are replaced with `[output hidden]` placeholders. Agent's reasoning text is preserved. Configurable via `settings.json` → `compaction.observationMaskingTurns` (default: 10).
+2. **Tool result clearing** (second) — For messages in turns 1–10 (within masking window), large raw outputs (file reads, bash outputs) are truncated to ~500 chars + `"... [truncated]"`. This keeps recent tool outputs readable but bounded. Messages already masked in step 1 are skipped (already replaced with placeholder).
+3. **Compaction** (third, conditional) — If context still exceeds 85% threshold after steps 1-2, full compaction triggers (see above).
+
+**Why this order:** Masking is the cheapest operation (placeholder replacement). Clearing is slightly more work (truncation). Compaction is expensive (LLM call). Running them in this order minimizes cost while progressively reducing context.
+
+### Token Tracking
+Per session/task:
+- Input tokens, output tokens, cache tokens
+- Estimated cost (based on model pricing config)
+- Iteration count, tool call count
+- Stored in SQLite, queryable via API
+
+## System Prompt Architecture (7 Layers)
+
+Assembled at session start. Layers 1-2 are static (optimize for prompt caching). Layers 3-7 are dynamic.
+
+| Layer | Content | Type |
+|-------|---------|------|
+| 1. Base Core | Identity, version, mandate | Static, cached |
+| 2. Safety & Rules | Permission rules, instruction hierarchy | Static, cached |
+| 3. Environment | OS, shell, cwd, git status, MCP servers | Dynamic per session |
+| 4. Agent Instructions | AGENT.md + SOUL.md + Memory files | User-defined |
+| 5. Tools & Capabilities | Tool names + descriptions (progressive disclosure) | Conditional |
+| 6. Task Heuristics | "Read before edit", "no over-engineering", mode-specific tips | Conditional |
+| 7. Session Context | Compacted history, active TODOs, task brief | Dynamic |
+
+**Token budget:** ~6,400-8,400 tokens target. Hard cap: 12,000 tokens.
+
+### System Reminders (Mid-Conversation Injections)
+
+| Reminder | Trigger | Purpose |
+|----------|---------|---------|
+| Anti-drift | Every N iterations | Refocus on original task |
+| Stall recovery | 3+ iterations with no progress | Suggest different approach |
+| Safe-edit | Before write/edit tool | Remind to read first |
+| Plan adherence | When TODO exists | Check progress against plan |
+| Compaction warning | At 75% context | Prepare for imminent compaction |
+
+### Instruction Priority Hierarchy
+
+Baked into Layer 2 (Safety & Rules):
+```
+Safety rules (Layer 2) > User's current message > AGENT.md > SOUL.md > MEMORY.md > System defaults
+```
+
+## Progress Events
+
+The runtime emits progress events during execution. These are:
+- **Written to SQLite** (queryable via `GET /tasks/:id/events`)
+- **Written to stdout** in one-shot mode (`VEIL_PROGRESS={...}`)
+- **Pushed via Ably** for remote consumers
+
+**Automatic events** (emitted by runtime, `type: "iteration"`):
+- `iteration.start` — new loop iteration
+- `tool.start` — tool execution beginning
+- `tool.end` — tool execution complete (with duration)
+- `compaction.start` / `compaction.end`
+- `status.change` — task status transition
+
+**Agent-driven events** (via `log_write` tool, `type: "custom"`):
+- Custom progress messages, research updates, milestones
+- Format is free-form — agents decide what's useful to report
+
+All events include a `type` field (`"iteration"` or `"custom"`) so API consumers can filter/distinguish runtime progress from agent-specific progress.