reflectt-node 0.1.8 → 0.1.12

package/public/design-tokens.css

@@ -0,0 +1,195 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Reflectt Design Tokens v0
+   ═══════════════════════════════════════════════════════════════════════
+   Single source of truth for all visual values across web, iOS, Android.
+   Platform implementations should map these to native equivalents:
+   - iOS: UIColor extensions + CGFloat constants
+   - Android: colors.xml + dimens.xml + attrs.xml
+   - Web: CSS custom properties (this file)
+
+   Usage: @import url('/design-tokens.css');
+   Or: <link rel="stylesheet" href="/design-tokens.css">
+   ═══════════════════════════════════════════════════════════════════════ */
+
+:root {
+  /* ── Brand Colors ─────────────────────────────────────────────────── */
+  --color-brand-primary: #7C3AED;       /* Purple 600 — main brand */
+  --color-brand-primary-light: #A78BFA; /* Purple 400 — hover/active */
+  --color-brand-primary-dark: #5B21B6;  /* Purple 800 — pressed */
+  --color-brand-accent: #8B5CF6;        /* Purple 500 — secondary accent */
+
+  /* ── Semantic Colors ──────────────────────────────────────────────── */
+  --color-success: #10B981;       /* Emerald 500 */
+  --color-success-bg: #D1FAE5;   /* Emerald 100 */
+  --color-warning: #F59E0B;       /* Amber 500 */
+  --color-warning-bg: #FEF3C7;   /* Amber 100 */
+  --color-error: #EF4444;         /* Red 500 */
+  --color-error-bg: #FEE2E2;     /* Red 100 */
+  --color-info: #3B82F6;          /* Blue 500 */
+  --color-info-bg: #DBEAFE;      /* Blue 100 */
+
+  /* ── Canvas State Colors ──────────────────────────────────────────── */
+  /* Maps to the 8-state machine from interface-os-v0-state-machine.html */
+  --color-state-floor: #1F2937;          /* Gray 800 — resting */
+  --color-state-listening: #7C3AED;      /* Purple 600 — active listening */
+  --color-state-thinking: #6366F1;       /* Indigo 500 — processing */
+  --color-state-rendering: #8B5CF6;      /* Purple 500 — outputting */
+  --color-state-ambient: #374151;        /* Gray 700 — passive monitoring */
+  --color-state-decision: #F59E0B;       /* Amber 500 — needs human input */
+  --color-state-urgent: #EF4444;         /* Red 500 — critical alert */
+  --color-state-handoff: #10B981;        /* Emerald 500 — transferring control */
+
+  /* ── Trust Indicator ──────────────────────────────────────────────── */
+  --color-trust-mic: #F87171;            /* Red 400 — visible without alarming */            /* Red — microphone active */
+  --color-trust-camera: #F87171;         /* Red — camera active */
+  --color-trust-mic-camera: #EF4444;  /* Red 500 — both sensors escalated */     /* Red 600 — both active */
+  --trust-indicator-size: 10px;
+  --trust-indicator-position-top: env(safe-area-inset-top, 8px);
+  --trust-indicator-position-left: 12px;
+  --trust-indicator-z-index: 9999;
+
+  /* ── Surface / Background ─────────────────────────────────────────── */
+  --color-bg-primary: #FFFFFF;
+  --color-bg-secondary: #F9FAFB;     /* Gray 50 */
+  --color-bg-tertiary: #F3F4F6;      /* Gray 100 */
+  --color-bg-elevated: #FFFFFF;
+  --color-bg-overlay: rgba(0, 0, 0, 0.5);
+  --color-bg-canvas: #0F0F0F;        /* Near-black for canvas surface */
+
+  /* ── Text ─────────────────────────────────────────────────────────── */
+  --color-text-primary: #111827;      /* Gray 900 */
+  --color-text-secondary: #6B7280;    /* Gray 500 */
+  --color-text-tertiary: #9CA3AF;     /* Gray 400 */
+  --color-text-inverse: #FFFFFF;
+  --color-text-link: #7C3AED;
+  --color-text-on-brand: #FFFFFF;
+
+  /* ── Borders ──────────────────────────────────────────────────────── */
+  --color-border-default: #E5E7EB;    /* Gray 200 */
+  --color-border-hover: #D1D5DB;      /* Gray 300 */
+  --color-border-focus: #7C3AED;
+  --color-border-error: #EF4444;
+
+  /* ── Typography ───────────────────────────────────────────────────── */
+  --font-family-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --font-family-mono: 'SF Mono', SFMono-Regular, ui-monospace, 'Cascadia Code', Menlo, monospace;
+
+  --font-size-xs: 0.75rem;     /* 12px */
+  --font-size-sm: 0.875rem;    /* 14px */
+  --font-size-base: 1rem;      /* 16px */
+  --font-size-lg: 1.125rem;    /* 18px */
+  --font-size-xl: 1.25rem;     /* 20px */
+  --font-size-2xl: 1.5rem;     /* 24px */
+  --font-size-3xl: 1.875rem;   /* 30px */
+
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+
+  /* ── Spacing ──────────────────────────────────────────────────────── */
+  --space-0: 0;
+  --space-1: 0.25rem;   /* 4px */
+  --space-2: 0.5rem;    /* 8px */
+  --space-3: 0.75rem;   /* 12px */
+  --space-4: 1rem;      /* 16px */
+  --space-5: 1.25rem;   /* 20px */
+  --space-6: 1.5rem;    /* 24px */
+  --space-8: 2rem;      /* 32px */
+  --space-10: 2.5rem;   /* 40px */
+  --space-12: 3rem;     /* 48px */
+  --space-16: 4rem;     /* 64px */
+
+  /* ── Border Radius ────────────────────────────────────────────────── */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-2xl: 24px;
+  --radius-full: 9999px;
+
+  /* ── Shadows ──────────────────────────────────────────────────────── */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+  --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+  --shadow-glow-brand: 0 0 20px rgba(124, 58, 237, 0.3);
+  --shadow-glow-urgent: 0 0 20px rgba(239, 68, 68, 0.4);
+
+  /* ── Transitions ──────────────────────────────────────────────────── */
+  --transition-fast: 150ms;
+  --transition-base: 250ms;
+  --transition-slow: 350ms;
+  --transition-canvas: 500ms;    /* Canvas state transitions */
+
+  --easing-smooth: cubic-bezier(0.4, 0, 0.2, 1);
+  --easing-ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --easing-ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --easing-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --easing-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+
+  /* ── Z-Index Scale ────────────────────────────────────────────────── */
+  --z-base: 0;
+  --z-dropdown: 100;
+  --z-sticky: 200;
+  --z-overlay: 300;
+  --z-modal: 400;
+  --z-popover: 500;
+  --z-toast: 600;
+  --z-override-bar: 800;      /* Persistent controls */
+  --z-trust-indicator: 9999;   /* Non-dismissable, always on top */
+
+  /* ── Interactive Elements ─────────────────────────────────────────── */
+  --tap-target-min: 44px;      /* WCAG minimum */
+  --tap-target-urgent: 52px;   /* Enlarged in urgent state */
+  --focus-ring: 0 0 0 3px rgba(124, 58, 237, 0.4);
+
+  /* ── Canvas / Orb ─────────────────────────────────────────────────── */
+  --orb-size-idle: 64px;
+  --orb-size-active: 64px;
+  --orb-size-transcript: 44px;   /* Shrinks when transcript appears */
+  --orb-glow-duration: 1.8s;
+  --orb-color: var(--color-brand-primary);
+
+  /* ── Override Bar ─────────────────────────────────────────────────── */
+  --override-bar-height: 52px;
+  --override-bar-bg: rgba(0, 0, 0, 0.85);
+  --override-bar-blur: 20px;
+
+  /* ── Presence Dot ─────────────────────────────────────────────────── */
+  --presence-dot-size: 8px;
+  --presence-dot-active: #10B981;    /* Online */
+  --presence-dot-idle: #F59E0B;      /* Away */
+  --presence-dot-offline: #6B7280;   /* Disconnected */
+}
+
+/* ── Dark Mode ──────────────────────────────────────────────────────── */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg-primary: #111827;
+    --color-bg-secondary: #1F2937;
+    --color-bg-tertiary: #374151;
+    --color-bg-elevated: #1F2937;
+    --color-bg-overlay: rgba(0, 0, 0, 0.7);
+
+    --color-text-primary: #F9FAFB;
+    --color-text-secondary: #9CA3AF;
+    --color-text-tertiary: #6B7280;
+
+    --color-border-default: #374151;
+    --color-border-hover: #4B5563;
+
+    --color-success-bg: rgba(16, 185, 129, 0.15);
+    --color-warning-bg: rgba(245, 158, 11, 0.15);
+    --color-error-bg: rgba(239, 68, 68, 0.15);
+    --color-info-bg: rgba(59, 130, 246, 0.15);
+
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+    --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.4);
+  }
+}

package/public/docs.md

@@ -111,7 +111,7 @@ Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the
 | GET | `/health/watchdog` | Richer keepalive with cold_start flag, task/chat stats, boot_info, and remediation hints. For monitoring dashboards. See `docs/KEEPALIVE.md`. |
 | GET | `/health` | System health — task counts, chat stats, inbox stats. Includes `cold_start` flag (true if uptime < 60s). Query: `include_test=1` to include test-harness tasks in stats (excluded by default). |
 | GET | `/team/health` | Team config linter status for `~/.reflectt/TEAM.md`, `TEAM-ROLES.yaml`, `TEAM-STANDARDS.md` (issues, role coverage, last check timestamp) |
-| GET | `/health/team` | Team health metrics with compliance + `staleDoing` snapshot. Per-agent rows include `activeTaskTitle` and `activeTaskPrLink` when an agent has a doing task with PR evidence. Flagged agents also include `actionable_reason` (last comment age, last transition, last mention age, suggested action). |
+| GET | `/health/team` | Host-local team health metrics with compliance + `staleDoing` snapshot. Response now includes `scope` metadata (`kind: "host-local"`, `hostName`, `label`, `message`, `orgHealthUrl`) so operators can see which host they are inspecting and, when cloud is configured, follow the org-health pointer for cross-host truth. Per-agent rows include `activeTaskTitle` and `activeTaskPrLink` when an agent has a doing task with PR evidence. Flagged agents also include `actionable_reason` (last comment age, last transition, last mention age, suggested action). |
 | GET | `/health/agents` | Per-agent health summary (`last_seen`, `active_task`, `heartbeat_age_ms`, `last_shipped_at`, `stale_reason`, state) |
 | GET | `/health/compliance` | Compliance check results |
 | GET | `/compliance/violations` | State-read-before-assertion compliance violations. Query: `agent`, `severity`, `limit` (max 1000), `since` (epoch ms). Returns `{ violations, count, summary, query }`. |
@@ -182,6 +182,8 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 |--------|------|-------------|
 | GET | `/tasks` | List tasks. Query: `status`, `assignee`, `agent`, `priority`, `limit`, `offset`, `q` (text search), `updatedSince`, `include_test=1|true` (include test-harness tasks; default excluded). Returns `{ tasks, total, offset, limit, hasMore }`. |
 | GET | `/tasks/:id` | Get task by ID. Also accepts unambiguous ID prefixes. Ambiguous prefix returns `400` with full-ID suggestions. |
+| GET | `/tasks/:id/handoff` | Get handoff state for a task (reviewed_by, decision, next_owner). |
+| PUT | `/tasks/:id/handoff` | Set handoff state. Body: `{ reviewed_by (required), decision: "approved"\|"rejected"\|"needs_changes"\|"escalated" (required), next_owner? }`. Also settable via PATCH /tasks/:id metadata.handoff_state. |
 | GET | `/tasks/:id/artifacts` | Resolve all artifact references from task metadata. Returns accessibility status (file existence, URL validation), heartbeat status (last comment age, staleness). Heartbeat threshold: 30m for doing tasks. Query: `include=preview` (first 2000 chars) or `include=content` (full file, up to 400KB). Falls back to shared workspace (`~/.openclaw/workspace-shared`) when file is not in repo root. |
 | GET | `/tasks/:id/history` | Status changelog for task lifecycle transitions. Returns `history[]` entries shaped as `{ status, changedBy, changedAt, metadata }` for each status transition. |
 | GET | `/tasks/:id/comments` | List task discussion comments. Query: `includeSuppressed=true|1` to include suppressed (audit) comments. Returns `{ comments, count, includeSuppressed }` where each comment is `{ id, taskId, author, content, timestamp, category?, suppressed, suppressedReason?, suppressedRule? }`. |
@@ -197,7 +199,7 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 | DELETE | `/tasks/:id` | Delete task |
 | GET | `/tasks/next` | Pull-based assignment. Query: `agent`, `compact`, `claim=1` (auto-transitions todo→doing on pull) |
 | GET | `/tasks/active` | Get active (doing) task for agent. Query: `agent`, `compact`. Returns null if no doing tasks. |
-| GET | `/heartbeat/:agent` | Single compact heartbeat payload (~200 tokens). Returns active task, next task, slim inbox, queue counts, and suggested action. Replaces 3 separate API calls. |
+| GET | `/heartbeat/:agent` | Single compact heartbeat payload (~200 tokens). Returns active task, next task, slim inbox, queue counts, suggested action, boot context (recent memories top 5, active agent_run). Replaces 3+ separate API calls. |
 | GET | `/bootstrap/heartbeat/:agent` | Generate optimal HEARTBEAT.md content for agent. References best endpoints. Includes version stamp and content hash for change detection. |
 | POST | `/bootstrap/team` | Returns TEAM-ROLES.yaml schema, constraints, well-formed examples, and save endpoint. The calling agent composes the team itself. Body: `{ useCase?, maxAgents? }`. Returns `{ schema, constraints, examples[], saveEndpoint, nextSteps[] }`. |
 | GET | `/manage/status` | Remote management: unified status (version + health + uptime). Auth: `x-manage-token` header or `Authorization: Bearer`. |
@@ -205,6 +207,16 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 | GET | `/manage/logs` | Remote management: bounded log tail. Query: `level`, `since`, `limit`, `format=text`. Auth required. |
 | POST | `/manage/restart` | Remote management: graceful restart (Docker/systemd/CLI). Auth required. |
 | GET | `/manage/disk` | Remote management: data directory sizes. Auth required. |
+| GET | `/browser/config` | Browser capability configuration (max sessions, rate limits, viewport). |
+| POST | `/browser/sessions` | Create a new isolated browser session. Body: `{ agent, url?, headless?, viewport? }`. Returns session object. |
+| GET | `/browser/sessions` | List all browser sessions (active and recent). |
+| GET | `/browser/sessions/:id` | Get browser session by ID. |
+| DELETE | `/browser/sessions/:id` | Close and cleanup a browser session. |
+| POST | `/browser/sessions/:id/act` | Execute a natural language browser action. Body: `{ instruction }`. |
+| POST | `/browser/sessions/:id/extract` | Extract structured data from current page. Body: `{ instruction, schema? }`. |
+| POST | `/browser/sessions/:id/observe` | Discover available actions on current page. Body: `{ instruction }`. |
+| POST | `/browser/sessions/:id/navigate` | Navigate to a URL. Body: `{ url }`. |
+| GET | `/browser/sessions/:id/screenshot` | Take a screenshot of the current page. Returns `{ base64, mimeType }`. |
 | GET | `/capabilities` | Agent-facing endpoint discovery. Lists all endpoints grouped by purpose, compact support flags, and usage recommendations. |
 | GET | `/version` | Current version + latest available from GitHub releases. Includes `update_available` boolean. Caches GitHub check for 15 minutes. |
 | GET | `/me/:agent` | Agent "My Now" cockpit payload: assigned tasks, pending reviews, blockers, failing-check signals, since-last-seen changelog, and next action. Supports `compact`. |
@@ -554,6 +566,7 @@ Multi-host management: remote hosts register via heartbeat and are tracked by st
 | POST | `/board-health/rollback/:actionId` | Rollback an automated action within the rollback window. Body: `{ by? }`. |
 | PATCH | `/board-health/config` | Update worker config at runtime. Fields: enabled, intervalMs, staleDoingThresholdMin, suggestCloseThresholdMin, rollbackWindowMs, digestIntervalMs, digestChannel, quietHoursStart, quietHoursEnd, dryRun, maxActionsPerTick. |
 | POST | `/board-health/prune` | Prune old audit log entries. Query: `?maxAgeDays=7`. |
+| POST | `/board-health/quiet-window` | Reset the quiet window — suppresses ready-queue alerts for `restartQuietWindowMs` (default 5 min). Call after gateway restart/reconnect. |
 | GET | `/feed/:agent` | Since-last-seen change feed. Query: `?since=timestamp&limit=100&kinds=task_status_changed,mention&includeGlobal=true`. Returns unified timeline of task changes, comments, mentions, PRs, deploys relevant to agent. |
 | GET | `/policy` | Get unified policy config (quiet hours, idle nudge, cadence watchdog, board health, escalation thresholds). |
 | PATCH | `/policy` | Update policy config at runtime (deep-merged, persisted to ~/.reflectt/policy.json). Propagates to running workers. |
@@ -865,6 +878,10 @@ Set via `reflectionNudge` in policy config:
 | GET | `/usage/caps` | List active spend caps with current utilization status. |
 | POST | `/usage/caps` | Create spend cap. Body: `{ scope: "global"\|"agent"\|"team", scope_id?, period: "daily"\|"weekly"\|"monthly", limit_usd, action: "warn"\|"throttle"\|"block" }`. |
 | DELETE | `/usage/caps/:id` | Delete a spend cap. |
+| GET | `/agents/:agentId/spend` | Get current spend totals for a specific agent. Returns `{ agentId, totalCost, inputTokens, outputTokens, periodStart }`. |
+| POST | `/agents/:agentId/enforce-cost` | Trigger cost enforcement check for agent. Evaluates active caps and applies configured action (warn/throttle/block). Body: `{}`. |
+| POST | `/usage/record` | Record a single usage event. Body: `{ agentId, inputTokens, outputTokens, cost?, model?, taskId? }`. |
+| POST | `/usage/purge` | Purge old usage records. Body: `{ maxAgeDays? }` (default 90). |
 | GET | `/usage/routing-suggestions` | Smart routing savings suggestions (which low-stakes categories could use cheaper models). Query: `since`. |
 | GET | `/costs` | Cost dashboard — aggregated spend for COO/PM monitoring. Query: `days` (1–90, default 7). Returns: `daily_by_model` (spend per model per day), `daily_totals` (per-day rolled-up for threshold alerting), `avg_cost_by_lane` (avg cost per closed task by `qa_bundle.lane`, 30-day floor), `avg_cost_by_agent` (avg cost per closed task per agent + `top_model`, 30-day floor), `top_tasks_by_cost` (top 20 most expensive tasks in window), `summary` (total tokens + cost), `lane_agent_window_days` (actual window used for lane/agent averages). |
 
@@ -1064,6 +1081,118 @@ Auth-gated endpoints for managing a reflectt-node instance remotely. Provide `RE
 | POST | `/manage/restart` | Graceful restart. Works with Docker, systemd, and reflectt CLI (PID file). Returns 501 if unsupported. |
 | GET | `/manage/disk` | Data directory sizes for capacity monitoring |
 
+### Agent Runs & Events
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/agents/:agentId/runs` | Create a new agent run. Body: `{ objective, teamId?, taskId?, parentRunId? }` |
+| GET | `/agents/:agentId/runs` | List runs. Query: `?status=&teamId=&limit=` |
+| GET | `/agents/:agentId/runs/current` | Get active (non-terminal) run. Query: `?teamId=` |
+| PATCH | `/agents/:agentId/runs/:runId` | Update run. Body: `{ status?, contextSnapshot?, artifacts? }` |
+| POST | `/agents/:agentId/events` | Append an event (immutable). Body: `{ eventType, runId?, payload? }` |
+| GET | `/agents/:agentId/events` | List events. Query: `?runId=&type=&since=&limit=` |
+| GET | `/approvals/pending` | List pending approvals (review_requested events needing action). Query: `?agentId=&limit=` |
+| POST | `/approvals/:eventId/decide` | Submit approval decision. Body: `{ decision: "approve"|"reject", reviewer (required), comment? }`. Auto-unblocks run on approve. |
+| GET | `/agents/:agentId/runs/:runId/stream` | SSE stream for a specific run. Sends snapshot (run + recent events), then real-time events as they occur. Heartbeat every 15s. |
+| GET | `/agents/:agentId/stream` | SSE stream for all events for an agent. Sends snapshot (active run + recent events), then real-time events. Heartbeat every 15s. |
+| GET | `/workflows` | List available workflow templates. |
+| GET | `/workflows/:id` | Get template details (name, description, steps). |
+| POST | `/workflows/:id/run` | Execute a workflow. Body: `{ agentId?, teamId?, objective?, taskId?, reviewer?, prUrl?, title?, urgency?, nextOwner?, summary? }`. Returns step-by-step results with timing. Currently available: `pr-review` (6 steps: create → work → review → approve → handoff → complete). |
+| POST | `/canvas/input` | Human→agent control seam for Presence Layer. Body: `{ action: "decision"\|"interrupt"\|"pause"\|"resume"\|"mute"\|"unmute", actor (required), targetRunId?, decisionId?, choice?: "approve"\|"deny"\|"defer", comment? }`. Emits canvas_input SSE event. |
+| GET | `/canvas/input/schema` | Discovery: lists valid actions and field descriptions for canvas input. |
+| POST | `/canvas/state` | Agent emits Presence Layer state transition. Body: `{ state: "floor"\|"listening"\|"thinking"\|"rendering"\|"ambient"\|"decision"\|"urgent"\|"handoff", sensors: null\|"mic"\|"camera"\|"mic+camera", agentId (required), payload?: { text?, media?, decision?: { question, decisionId, expiresAt?, autoAction? }, agents?: [{ name, state, task? }], summary?: { headline, items?, cost?, duration? } } }`. Emits canvas_render SSE event. |
+| GET | `/canvas/state` | Current Presence Layer state for agents. Params: `agentId?` (single agent) or all agents. |
+| GET | `/canvas/states` | Discovery: valid states, sensors, and payload schema. |
+| GET | `/agents/:agentId/config` | Get agent config (model preference, cost caps, settings). |
+| PUT | `/agents/:agentId/config` | Upsert agent config. Body: `{ model?, fallbackModel?, costCapDaily?, costCapMonthly?, maxTokensPerCall?, teamId?, settings? }`. |
+| DELETE | `/agents/:agentId/config` | Remove agent config. |
+| GET | `/agent-configs` | List all agent configs. Params: `teamId?`. |
+| GET | `/agents/:agentId/cost-check` | Runtime cost enforcement check. Params: `dailySpend?`, `monthlySpend?`. Returns: allowed, action (allow\|warn\|downgrade\|deny), remaining budgets, model/fallback. |
+| POST | `/events/routing/validate` | Validate routing semantics for an event payload. Body: `{ eventType, payload }`. Returns: valid, errors[], warnings[]. Actionable events (review_requested, approval_requested, escalation, handoff) require: action_required, urgency (low\|normal\|high\|critical), owner. |
+| GET | `/agents/:name/identity` | Host-native agent identity resolution. Resolves by name, alias, or display name without requiring OpenClaw gateway. Returns: agentId, displayName, role, aliases, capabilities, model, costCap. Merges YAML roles + agent_config table. |
+| POST | `/agents/:agentId/messages/send` | Send message to another agent. Body: `{ to (required), content (required), channel?, metadata? }`. Emits message_posted SSE event. |
+| GET | `/agents/:agentId/messages` | Inbox — list messages for an agent. Params: `channel?`, `unread?` (true), `since?`, `limit?`. Returns messages + unreadCount. |
+| GET | `/agents/:agentId/messages/sent` | Sent messages. Params: `limit?`. |
+| POST | `/agents/:agentId/messages/read` | Mark messages as read. Body: `{ messageIds?: string[] }` (omit for mark all). |
+| GET | `/messages/channel/:channel` | List messages in a channel. Params: `since?`, `limit?`. |
+| GET | `/runs/retention/stats` | Preview retention: total runs, terminal runs, how many would be archived. Params: `maxAgeDays?`, `maxCompletedRuns?`. |
+| POST | `/runs/retention/apply` | Apply retention policy. Body: `{ maxAgeDays? (default 30), maxCompletedRuns? (default 100), deleteArchived? (default false), agentId?, dryRun? }`. Returns: archived, deleted, eventsDeleted counts. |
+| POST | `/agents/:agentId/artifacts` | Upload artifact. Body: `{ name (required), content (required), encoding? ("base64"), mimeType?, runId?, taskId?, metadata? }`. Stores file on disk + metadata in DB. |
+| GET | `/agents/:agentId/artifacts` | List artifacts for agent. Params: `runId?`, `taskId?`, `limit?`. Returns artifacts + usage. |
+| GET | `/artifacts/:artifactId` | Get artifact metadata. |
+| GET | `/artifacts/:artifactId/content` | Download artifact content (returns file with correct MIME type). |
+| DELETE | `/artifacts/:artifactId` | Delete artifact (removes file + DB row). |
+| GET | `/agents/:agentId/storage` | Get storage usage (totalBytes, count). |
+| POST | `/webhooks/ingest` | Store inbound webhook payload. Body: `{ source (required), eventType (required), body (required), agentId? }`. Captures request headers automatically. |
+| GET | `/webhooks/payloads` | List stored payloads. Params: `source?`, `agentId?`, `unprocessed?` (true), `since?`, `limit?`. Returns payloads + unprocessedCount. |
+| GET | `/webhooks/payloads/:payloadId` | Get single payload with full body + headers. |
+| POST | `/webhooks/payloads/:payloadId/process` | Mark payload as processed. |
+| POST | `/webhooks/purge` | Delete old processed payloads. Body: `{ maxAgeDays? }` (default 30). |
+| POST | `/agents/:agent/waiting` | Set agent to waiting state (blocked on human). Body: `{ reason (required), waitingFor?, taskId?, expiresAt? }`. Shows in heartbeat response. |
+| DELETE | `/agents/:agent/waiting` | Clear waiting state — agent is unblocked. |
+| GET | `/approval-queue` | Unified approval queue — everything needing human decision. Params: `agentId?`, `category?` (review\|agent_action), `includeExpired?` (true), `limit?`. Returns: items[], count, hasExpired. Each item: id, category, title, description, urgency, owner, expiresAt, autoAction, isExpired. |
+| POST | `/approval-queue/:approvalId/decide` | Resolve an approval. Body: `{ decision: "approve"\|"reject"\|"defer", actor (required), comment? }`. Emits canvas_input SSE event. |
+| POST | `/email/send` | Send email via cloud relay. Body: `{ from, to, subject, html/text (required), replyTo?, cc?, bcc?, agentId?, teamId? }`. Requires cloud connection. |
+| POST | `/sms/send` | Send SMS via cloud relay. Body: `{ to, body (required), from?, agentId?, teamId? }`. Requires cloud connection. |
+
+**Run statuses**: `idle`, `working`, `blocked`, `waiting_review`, `completed`, `failed`, `cancelled`
+
+**Event types**: `run_created`, `task_attached`, `tool_invoked`, `artifact_produced`, `review_requested`, `review_approved`, `review_rejected`, `blocked`, `handed_off`, `completed`, `failed`
+
+### Agent Memories
+
+Persistent key-value store with tags, namespaces, and expiration. Survives node restarts.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| PUT | `/agents/:agentId/memories` | Set (upsert) a memory. Body: `{ key, content, namespace?, tags?, expiresAt? }` |
+| GET | `/agents/:agentId/memories/:key` | Get a memory by key. Query: `?namespace=` |
+| GET | `/agents/:agentId/memories` | List memories. Query: `?namespace=&tag=&search=&limit=` |
+| DELETE | `/agents/:agentId/memories/:key` | Delete a memory by key. Query: `?namespace=` |
+| GET | `/agents/:agentId/memories/count` | Count memories. Query: `?namespace=` |
+| POST | `/agents/memories/purge` | Purge all expired memories (housekeeping) |
+
+Events are **append-only** — no updates, no deletes.
+
+### Browser Capability
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/browser/config` | Browser capability config (limits, viewport, idle timeout) |
+| POST | `/browser/sessions` | Create isolated browser session. Body: `{ agent, url?, headless?, viewport? }` |
+| GET | `/browser/sessions` | List all sessions |
+| GET | `/browser/sessions/:id` | Get session details |
+| DELETE | `/browser/sessions/:id` | Close session |
+| POST | `/browser/sessions/:id/act` | Natural language action. Body: `{ instruction }` |
+| POST | `/browser/sessions/:id/extract` | Extract data. Body: `{ instruction, schema? }` |
+| POST | `/browser/sessions/:id/observe` | Discover actions. Body: `{ instruction }` |
+| POST | `/browser/sessions/:id/navigate` | Go to URL. Body: `{ url }` |
+| GET | `/browser/sessions/:id/screenshot` | Screenshot as base64 PNG |
+
+**Example: Create session and act**
+
+```bash
+# Create a session
+SESSION=$(curl -s -X POST http://127.0.0.1:4445/browser/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"agent":"link","url":"https://example.com"}' | jq -r .id)
+
+# Act on the page
+curl -s -X POST "http://127.0.0.1:4445/browser/sessions/$SESSION/act" \
+  -H 'Content-Type: application/json' \
+  -d '{"instruction":"click the More Information link"}'
+
+# Extract data
+curl -s -X POST "http://127.0.0.1:4445/browser/sessions/$SESSION/extract" \
+  -H 'Content-Type: application/json' \
+  -d '{"instruction":"extract the main heading text"}'
+
+# Close when done
+curl -s -X DELETE "http://127.0.0.1:4445/browser/sessions/$SESSION"
+```
+
+Sessions auto-close after 5 minutes of inactivity. Max 3 concurrent sessions, 10 per agent per hour.
+
 ### Example: Check Remote Node Status
 
 ```bash