reflectt-node 0.1.7 → 0.1.11

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`. |
@@ -216,7 +228,10 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 | POST | `/tasks/batch-create` | Batch create up to 20 tasks. Body: `{ "tasks": [...], "createdBy": "agent", "deduplicate": true, "dryRun": false }`. Each task follows the same schema as `POST /tasks`. Returns per-task results (created/duplicate/error) with summary counts. Deduplication checks exact title match + fuzzy word overlap (Jaccard >0.6) against active tasks. |
 | GET | `/tasks/heartbeat-status` | All doing tasks with stale comment activity (>30m). Returns `{ threshold, doingTaskCount, staleCount, staleTasks[] }`. Use for monitoring status heartbeat discipline compliance. |
 | GET | `/tasks/board-health` | Board-level health metrics for backlog replenishment. Returns per-agent breakdown (doing, validating, todo, active counts), `needsWork`/`lowWatermark` flags, and `replenishNeeded` trigger (fires when 2+ agents idle or <3 backlog tasks). Query: `include_test=1` to include test-harness tasks. |
+| GET | `/agents` | Agent list — alias for /agents/roles. Returns all agents with roles, WIP status, affinity tags. |
 | GET | `/agents/roles` | Agent role registry with live WIP status. Returns all agents with `name`, `displayName`, `role`, `affinityTags`, `protectedDomains`, `wipCap`, `wipCount`, `overCap`. |
+| POST | `/agents` | Add agent to team. Body: `{ name, role, description?, affinityTags?, wipCap? }`. Hot-reloads TEAM-ROLES.yaml. |
+| DELETE | `/agents/:name` | Remove agent from team. Hot-reloads TEAM-ROLES.yaml. |
 | POST | `/config/identity` | Set an agent's display name. Body: `{ "agent": "agent-1", "displayName": "Juniper" }`. Persists to TEAM-ROLES.yaml, hot-reloads. Dashboard and mentions use display name. |
 | PUT | `/config/team-roles` | Write TEAM-ROLES.yaml. Body: `{ "yaml": "agents:\n  - name: link\n    role: engineer..." }`. Hot-reloads on save. Used by bootstrap agent to configure team from user intent. |
 | GET | `/resolve/mention/:mention` | Resolve a mention string (name, displayName, or alias) to canonical agent ID. Returns `{ agent, displayName, role }`. |
@@ -551,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. |
@@ -863,6 +879,7 @@ Set via `reflectionNudge` in policy config:
 | 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 | `/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). |
 
 ### Model Pricing (built-in estimates, per 1M tokens)
 | Model | Input | Output |
@@ -1034,6 +1051,20 @@ Export → import preserves: summary, description, organizer, attendees, locatio
 | GET | `/calendar/events/:id/export.ics` | Export single event as .ics file. |
 | POST | `/calendar/import` | Import events from .ics content. Body: `{ ics: string, organizer?: string }` or raw .ics string. Returns created/updated events. UID-based dedup on re-import. |
 
+## Schedule Feed
+
+Shared time-awareness for the team. Canonical records for deploy windows, focus blocks, and scheduled task work — so agents can coordinate timing without chat.
+
+**MVP scope (v1):** One-off windows only. No iCal/RRULE, no reminders, no recurring rules. For per-agent availability and recurring blocks use `/calendar/blocks`. For notifications use the Calendar Reminder Engine.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/schedule/feed` | Upcoming entries in chronological order. Query: `kinds` (comma-separated: `deploy_window,focus_block,scheduled_task`), `owner`, `after` (epoch ms, default: now), `before` (epoch ms), `limit` (default: 50, max: 200). |
+| POST | `/schedule/entries` | Create a schedule entry. Body: `{ kind, title, start, end, owner, task_id?, status?, meta? }`. `kind` must be `deploy_window`, `focus_block`, or `scheduled_task`. `start`/`end` are epoch ms. Default status: `open` / `active` / `pending`. |
+| GET | `/schedule/entries/:id` | Get a single entry by ID. |
+| PATCH | `/schedule/entries/:id` | Update an entry. Body: `{ title?, start?, end?, status?, meta? }`. |
+| DELETE | `/schedule/entries/:id` | Delete an entry. Returns 204. |
+
 ## Remote Node Management
 
 Auth-gated endpoints for managing a reflectt-node instance remotely. Provide `REFLECTT_MANAGE_TOKEN` env var; authenticate via `x-manage-token` header or `Authorization: Bearer <token>`. Loopback (localhost) access is always allowed.
@@ -1046,6 +1077,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