@uptimizr/collector-server 2.1.0 → 2.2.0

package/AGENTS.md

@@ -40,6 +40,7 @@ mint one with `uptimizr new-key <projectId> --capabilities query` instead.
 | `uptimizr migrate`             | Apply store migrations.                                              |
 | `uptimizr regions set <scene>` | Replace a scene's named regions from `--file <regions.json>`.        |
 | `uptimizr regions get <scene>` | Print a scene's named regions as JSON.                               |
+| `uptimizr agent report`        | Run a read-only agent once and write a Markdown report (see below).  |
 | `uptimizr help`                | Usage.                                                               |
 
 `new-key` flags: `--capabilities <list>` (comma-separated; default `query`), `--label <name>`,
@@ -60,17 +61,54 @@ project you mint is the one the running collector resolves.
 Installed as a dependency, the package exposes the `uptimizr` CLI plus the legacy
 `uptimizr-collector` bin (equivalent to `uptimizr serve`).
 
+### `uptimizr agent report` — headless scheduled reports (ADR 0051 §6)
+
+Runs the headless `runAgent` loop from `@uptimizr/agent-core` **once**, in this process,
+over the generated read-only tool catalog against the collector's query API, and writes
+Markdown to a file, stdout or a signed webhook. The collector gains no in-process LLM loop;
+scheduling is the operator's cron / systemd timer / GitHub Action.
+
+| Flag                 | Meaning                                                                                                                                                                     |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--skill <name>`     | Required. A packaged skill: `attention_hotspots` (needs `--scene`), `conversion_investigation`, `performance_regression_triage`, `weekly_scene_health`, `xr_comfort_audit`. |
+| `--list-skills`      | Print the skills with their descriptions and the metrics each one reads.                                                                                                    |
+| `--scene <id>`       | Scope the report to one scene.                                                                                                                                              |
+| `--window <NdNhNw>`  | Window back from now (`24h`, `7d` default, `2w`), or `--since` / `--until` in epoch ms.                                                                                     |
+| `--out <file or ->`  | Markdown destination (default `-`, stdout).                                                                                                                                 |
+| `--json <file or ->` | Structured report: tool calls with arguments, durations and outcomes, plus token usage when reported.                                                                       |
+| `--webhook <url>`    | `POST {markdown, report}` to an `http(s)` URL.                                                                                                                              |
+| `--max-steps <n>`    | Cap on provider turns (default `8`).                                                                                                                                        |
+| `--dry-run`          | Print the prompt and tool list; call no provider.                                                                                                                           |
+
+Environment — read from the environment only and never persisted:
+`UPTIMIZR_COLLECTOR_URL`, `UPTIMIZR_API_KEY` (a `query` key is enough; the command only ever
+reads), `UPTIMIZR_AGENT_PROVIDER` (`anthropic` default | `openai` | `scripted`),
+`UPTIMIZR_AGENT_MODEL`, `UPTIMIZR_AGENT_API_KEY` (falls back to `ANTHROPIC_API_KEY` /
+`OPENAI_API_KEY`), `UPTIMIZR_AGENT_ENDPOINT`, `UPTIMIZR_WEBHOOK_SECRET`. The provider key
+never reaches a log, a report or an error message.
+
+The system prompt is the shared analytics guidelines plus the rendered `GET /api/v1/context`
+document, so a run uses the project's real scene ids and custom-event names; a collector
+without that endpoint degrades silently. Webhook bodies carry
+`X-Uptimizr-Signature: sha256=<hex HMAC-SHA-256 of the raw body>` and `X-Uptimizr-Delivery`.
+Exit codes: `0` ok · `1` usage/config · `2` provider or delivery failure · `3` report
+produced but incomplete (a tool call failed, or no answer).
+
+`UPTIMIZR_AGENT_PROVIDER=scripted` is a documented, model-free provider: it calls exactly the
+tools the skill names and prints what the collector returned. It is for proving wiring in CI —
+it produces data, not analysis.
+
 ## API keys and capabilities (ADR 0051 §7)
 
 A key carries a **set of capabilities**, not a single role. `new-key` defaults to `query`;
 `init` / `new-project` mint their single key with `query`, `query:raw` and `annotate`.
 
-| Capability  | Unlocks                                                                                                   |
-| ----------- | --------------------------------------------------------------------------------------------------------- |
-| `query`     | The aggregate analytics API, the scene registry, the live token exchange, and `GET /api/v1/audit`.        |
-| `query:raw` | Raw per-session streams: `GET /api/v1/sessions/:id/events` and `GET /api/v1/live/sessions/:id`.           |
-| `annotate`  | The project **metadata** write path (annotations, glossary, saved analyses, panel specs). Never events.   |
-| `ingest`    | Reserved for server-side write paths. Public ingestion is keyless, so issued keys are normally read keys. |
+| Capability  | Unlocks                                                                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`     | The aggregate analytics API, the scene registry, the live token exchange, and `GET /api/v1/audit`.                                                |
+| `query:raw` | Raw per-session data: `GET /api/v1/sessions/:id/events`, `GET /api/v1/live/sessions/:id`, and the compacted `GET /api/v1/sessions/:id/narrative`. |
+| `annotate`  | The project **metadata** write path (annotations, glossary, saved analyses, panel specs). Never events.                                           |
+| `ingest`    | Reserved for server-side write paths. Public ingestion is keyless, so issued keys are normally read keys.                                         |
 
 The raw endpoints are gated **twice**: the collector must run with `ENABLE_RAW_SESSION_RETENTION`
 **and** the key must hold `query:raw` — otherwise `403`. Retention alone is not enough.
@@ -100,8 +138,49 @@ Ingestion keeps its separate `COLLECTOR_INGEST_RATE_LIMIT_*` budget.
 - The read API: sessions, heatmaps (`pointer`, `camera`, `position`, `world`, `gaze`, `mesh-uv`,
   `click-rays`, `flow`, `perf`, `errors`), mesh/interaction insights, performance and diagnostics,
   scene/path/funnel analytics, scene representations and regions, and the live SSE endpoints.
+- **`POST /api/v1/query`** (and `GET /api/v1/query?q=<url-encoded JSON>`) — **the query DSL**
+  (ADR 0051 §3): one endpoint that runs any registry metric. See below.
 - `GET /health` — liveness probe, unauthenticated.
 
+### The query DSL: `POST /api/v1/query` (ADR 0051 §3)
+
+One endpoint for every metric. Name the `metric`, bound it with a `range`, narrow it with the
+filters that metric declares, cap it, pick the envelope:
+
+```jsonc
+{
+  "v": 1,
+  "metric": "mesh_sources",
+  "range": { "since": 1757000000000, "until": 1757600000000 },
+  "filters": { "scene": "lobby", "cameraMode": "first-person" },
+  "limit": 20,
+  "format": "summary",
+}
+```
+
+`GET /api/v1/query?q=<url-encoded JSON>` takes the same document (8 KiB cap) for GET-only clients.
+Both are reads: same `query` capability, same audit trail, same aggregations.
+
+- The grammar is **closed** — no SQL, no expression language, typed filters, bounded output,
+  unknown keys rejected. `range` is required; `format` defaults to `table` here, not `full`.
+- A metric, dimension or filter outside the registry's vocabulary is a `400` listing **every**
+  objection, each with a stable `code`, the offending `path` and (for a closed list) `accepted`.
+  Read `accepted` instead of guessing again.
+- `dimensions` may be any subset a metric declares **when** its measure is a portable count —
+  event counts, mesh and interaction tallies, input actions, camera gestures. A spatial heatmap or a
+  percentile is computed at one fixed grain and refuses anything else, naming the grain it supports.
+- **`compare`** — another `{ range }` or `{ segment }`; the result comes back joined on the
+  dimension key as `{ current, previous, delta, deltaPct }`, with a significance test where the
+  measure is a count and both windows clear the metric's minimum. Never subtract two results by hand.
+- **`explain: true`** — the compiled plan instead of the rows: the tier, the SQL with its parameters
+  left unbound, `params` by name and type (never value), `rowsScanned`, and `warnings` (a capture
+  channel that produced nothing, a sample below the metric's minimum, a truncated result).
+- **`drillQuery`** — every row of a `summary` carries the whole query narrowed to that row, ready to
+  send straight back.
+- `order` takes a measure column, and only where the result is a ranked list.
+- `filters.event` (an ADR 0038 step predicate, applied as a **cohort** of sessions) and
+  `filters.device` (`os` / `browser` on `session_start`) exist only on the generic tier.
+
 ### Result envelopes: `format=full | table | summary` (ADR 0051 §2)
 
 Every aggregate endpoint accepts `format`. It **filters nothing** — it picks the result envelope:
@@ -114,6 +193,23 @@ Every aggregate endpoint accepts `format`. It **filters nothing** — it picks t
   the registry's `maxSummaryRows`. **This is what makes a 500-bin heatmap affordable for an LLM** —
   prefer it over `full` when feeding a model.
 
+### Session narrative: `GET /api/v1/sessions/:id/narrative` (`query:raw`)
+
+The one per-session read worth an agent's time. It compacts the raw stream into an ordered account
+of what the session did — scene changes, per-mesh dwell above `minDwellMs`, interactions, frame
+dips below `fpsThreshold`, errors, capability changes, XR entry/exit, the end reason — with
+timestamps **relative to the session's first event** and a closing `summary` entry of totals.
+Bounded by `maxEntries` (default 200, hard cap 1000).
+
+`format` here is `full` | `table` | **`text`**. Prefer `text`: one line per entry, about a third of
+the tokens of the JSON, which is what makes a whole session affordable in a context window. There
+is no `summary` envelope — a narrative is already one.
+
+Gated **twice**, like the raw stream: `ENABLE_RAW_SESSION_RETENTION` **and** `query:raw`, either
+missing is `403`; an unknown session is `404`. It is a projection, never the stream: no
+`visitorId`, no URL or page metadata, no positions or rays, no `device` detail beyond the engine,
+and custom-event property **keys** only — never their values.
+
 ### Filters
 
 Common query params: `since`, `until` (epoch ms), `bins`, `limit`, `scene`, `session`,
@@ -129,6 +225,25 @@ set is carried **inside the signed token**, so `GET /api/v1/live/sessions/:id` c
 `query:raw` even though `EventSource` cannot send headers. `GET /api/v1/live/presence` and
 `/live/stream` use the same `?token=...`.
 
+### Hosted MCP (`/mcp`, ADR 0051 §7)
+
+`COLLECTOR_MCP_HTTP=1` (off by default) makes the collector serve the **Model Context Protocol**
+over MCP's Streamable HTTP transport: `POST /mcp` for JSON-RPC, `GET /mcp` for the server→client
+SSE stream, `DELETE /mcp` to end a session. It is the same server `@uptimizr/mcp` runs over stdio —
+same tools, resources and prompts, built by the same factory — so a remote agent needs only a URL
+and a key, with nothing installed locally.
+
+- Every request is authenticated with `x-api-key` **or** `Authorization: Bearer <key>` (a bearer
+  alias accepted on this route only) and needs `query`: `401` without a key, `403` without the
+  capability, `403` if a session id is presented by a different key than opened it.
+- Tool calls are dispatched to the collector's own query routes **in process**, so they run the
+  same validation, scoping and result envelope as the equivalent `curl`, and cost the caller's
+  ordinary per-key rate-limit budget once.
+- Bounded by `COLLECTOR_MCP_MAX_SESSIONS` (default `50`, one too many → `503`) and
+  `COLLECTOR_MCP_SESSION_TTL_MS` (default 30 minutes idle). Audited with `surface: "mcp-http"`.
+- Behind a reverse proxy, disable response buffering for `/mcp` (it answers with SSE) and pin a
+  session to one instance if you run several.
+
 ## Storage (`COLLECTOR_STORE`)
 
 | Value                  | Store                                                                                                                                                                                                                 |
@@ -142,6 +257,59 @@ set is carried **inside the signed token**, so `GET /api/v1/live/sessions/:id` c
 All four return **identical analytics** (the cross-engine parity suite). Aggregations are computed
 at **query time** in v1 — no materialized views.
 
+## Conditional subscriptions (ADR 0051 §6)
+
+Standing predicates over a registry metric, delivered over SSE and signed webhooks.
+
+- `GET /api/v1/subscriptions` · `GET /api/v1/subscriptions/:id` ·
+  `GET /api/v1/subscriptions/:id/events` — need `query`.
+- `POST /api/v1/subscriptions` · `PATCH /api/v1/subscriptions/:id` (`{ enabled }` only) ·
+  `DELETE /api/v1/subscriptions/:id` · `POST /api/v1/subscriptions/:id/test[?deliver=true]` —
+  need **`annotate`**: creating one is how a caller asks the collector to make an outbound
+  request on its behalf.
+- `GET /api/v1/subscriptions/stream?token=…` — SSE, live-token auth (ADR 0032 §7), optional
+  `&id=` filter, shares `LIVE_MAX_CONNECTIONS`.
+
+Predicates: `threshold` (on the metric's registry headline column only), `anomaly`, `movers`,
+`new_value`, `presence`. `evaluate.every` ≥ 1m, `evaluate.window` ≥ 1h. 100 per project, last
+100 firings each.
+
+**A webhook secret is write-only** — accepted on create, never returned; reads carry a mask.
+**Webhook egress is off until `COLLECTOR_WEBHOOK_ALLOWED_HOSTS` names the hosts**, because a
+subscription URL arrives over HTTP and is therefore request-controlled input to an outbound
+request. Bodies are signed `X-Uptimizr-Signature: sha256=<hex>` over the raw bytes; verify before
+parsing, in constant time.
+
+`POST …/test` is a dry run by default and answers with _why_ it did or did not fire.
+
+## Pinned panels (ADR 0051 §7)
+
+Declarative panels an agent leaves on the project's dashboard. A spec is a title, a query, a chart
+name, an optional encoding, a span and a one-line note — **data**, which the dashboard draws with
+panel components `@uptimizr/react` already ships. No module is loaded and nothing is evaluated, so
+ADR 0041's remote-panel trust decision is not widened.
+
+- `GET /api/v1/panels` (`limit`) — the project's pinned panels, **oldest first**: these are grid
+  positions, not a feed. Needs `query`.
+- `POST /api/v1/panels` → `201` · `PUT /api/v1/panels/:id` · `DELETE /api/v1/panels/:id` → `204` —
+  need **`annotate`**, and are audited like every other metadata write. `PUT` is a full replacement
+  (half a spec is not a panel); the row keeps its id, its place in the grid and its original
+  authorship. An unknown id — or one belonging to another project, which is deliberately
+  indistinguishable — is `404`.
+- **Validated twice**, for two different questions: `panelSpecV1Schema` (`@uptimizr/schema`) for the
+  shape, then `validatePanelSpec` (`@uptimizr/metrics`) for the vocabulary — does the metric exist
+  and accept these filters, does the chart suit its grain, do the encoding columns exist in its
+  result. A failure is `400 { error, issues }`, the same body `POST /api/v1/query` answers with, so
+  a client fixes the spec from the response instead of guessing. The second check runs at **pin**
+  time because a pinned panel is read weeks later: a line chart with no axis to walk along does not
+  fail, it draws something a reader takes for a trend.
+- `409` when the project already holds `LIMITS.maxProjectPanelSpecs` (50) panels.
+- `query.range` may be the literal `"inherit"`, which the dashboard resolves against its filter bar
+  on every load, or an explicit `{ since, until }` to pin one period.
+- OpenAPI operation ids `list_panels`, `pin_panel`, `update_panel` and `unpin_panel`, under a
+  `panels` tag. `CollectorStore` gains `createPanelSpec` / `listPanelSpecs` / `updatePanelSpec` /
+  `deletePanelSpec`, implemented by all five stores.
+
 ## Other configuration
 
 - Server / browser access: `COLLECTOR_HOST` (`0.0.0.0`), `COLLECTOR_PORT` (`4318`),
@@ -151,9 +319,14 @@ at **query time** in v1 — no materialized views.
   `LIVE_MAX_CONNECTIONS`, `LIVE_PRESENCE_INTERVAL_MS`.
 - Rate limits: `COLLECTOR_RATE_LIMIT_MAX`, `COLLECTOR_RATE_LIMIT_WINDOW_MS`,
   `COLLECTOR_INGEST_RATE_LIMIT_MAX`, `COLLECTOR_INGEST_RATE_LIMIT_WINDOW_MS`.
+- Subscriptions: `COLLECTOR_SUBSCRIPTIONS` (default on; `0` keeps the API and runs no timers),
+  `COLLECTOR_SUBSCRIPTIONS_MAX_CONCURRENT` (default `4`),
+  **`COLLECTOR_WEBHOOK_ALLOWED_HOSTS`** (empty = no webhook egress at all).
 - Agent audit: **`AUDIT_RETENTION_DAYS`** (default `30`; `0` = keep forever),
   `AUDIT_DASHBOARD_REQUESTS` (default off — requests carrying `x-uptimizr-client: dashboard` are
   skipped as a volume filter, **not** a security boundary).
+- Hosted MCP: `COLLECTOR_MCP_HTTP` (off by default), `COLLECTOR_MCP_MAX_SESSIONS` (`50`),
+  `COLLECTOR_MCP_SESSION_TTL_MS` (`1800000`).
 - All-in-one dashboard: `COLLECTOR_DASHBOARD_DIR` (point it at a static dashboard export and one
   process serves ingestion, queries and the UI), `COLLECTOR_CSP` (`strict` or `off`).
 

package/README.md

@@ -75,6 +75,52 @@ so it needs no API key. Over HTTP the same thing is
 an `annotate`-capable key, and from a client build `registerRegions` in
 `@uptimizr/sdk-core`.
 
+### Scheduled reports: `uptimizr agent report`
+
+Run a read-only analytics agent **once** and write a Markdown report — a weekly
+scene-health digest with nobody in the chair. It is an ordinary CLI process that
+reads this collector's query API with an ordinary key, so the collector itself
+gains no LLM loop and scheduling stays yours (cron, a systemd timer, a GitHub
+Action).
+
+```bash
+# The narrow key a report should hold
+npx -p @uptimizr/collector-server uptimizr new-key <projectId> \
+  --capabilities query --label "weekly-report"
+
+export UPTIMIZR_COLLECTOR_URL=https://collect.example.com
+export UPTIMIZR_API_KEY=utk_…            # the query-only key above
+export UPTIMIZR_AGENT_API_KEY=sk-ant-…   # your own provider key
+
+npx -p @uptimizr/collector-server uptimizr agent report \
+  --skill weekly_scene_health --scene lobby --window 7d \
+  --out report.md --json report.json --webhook https://hooks.example.com/uptimizr
+```
+
+- `--list-skills` prints the investigations this release ships
+  (`attention_hotspots`, `conversion_investigation`,
+  `performance_regression_triage`, `weekly_scene_health`, `xr_comfort_audit`) and
+  the metrics each one reads — the same packaged methodologies `@uptimizr/mcp`
+  offers as prompts.
+- `--dry-run` prints the exact prompt and tool list and calls no provider;
+  `UPTIMIZR_AGENT_PROVIDER=scripted` runs the whole path with no model, no key
+  and no egress (useful in CI — it produces data, not analysis).
+- Provider configuration is read from the environment only and never persisted:
+  `UPTIMIZR_AGENT_PROVIDER` (`anthropic` | `openai` | `scripted`),
+  `UPTIMIZR_AGENT_MODEL`, `UPTIMIZR_AGENT_API_KEY`, `UPTIMIZR_AGENT_ENDPOINT`.
+  The key is never logged, echoed or written into a report.
+- Webhook deliveries are signed with
+  `X-Uptimizr-Signature: sha256=<hex HMAC-SHA-256 of the raw body>` keyed with
+  `UPTIMIZR_WEBHOOK_SECRET`, plus a unique `X-Uptimizr-Delivery` id.
+- Exit codes: `0` success · `1` usage/configuration · `2` provider or delivery
+  failure · `3` report produced but incomplete (a tool call failed, or no answer).
+
+Every report ends with a **Method** section listing each tool call and its
+arguments, so an unattended, model-written document stays auditable. See
+`uptimizr agent report --help`, or the
+[deploy guide](https://uptimizr.com/docs/deploy/collector/#scheduled-agent-reports)
+for a copy-pasteable weekly GitHub Actions workflow.
+
 ### All-in-one: serve the dashboard too
 
 The collector can also serve a pre-built static dashboard from its own origin, so
@@ -207,6 +253,26 @@ what makes a 500-bin heatmap affordable for an LLM. See
 
 - `GET /health` — liveness probe.
 
+### Hosted MCP (`/mcp`, opt-in)
+
+Start the collector with `COLLECTOR_MCP_HTTP=1` and it also speaks the **Model Context Protocol**
+over Streamable HTTP, so a remote AI client connects with a URL and an API key instead of running
+`npx @uptimizr/mcp` locally (ADR 0051 §7). It is off by default — without the variable the route is
+not registered.
+
+| Method   | Path   | Purpose                                                                |
+| -------- | ------ | ---------------------------------------------------------------------- |
+| `POST`   | `/mcp` | JSON-RPC. Without `Mcp-Session-Id`, only `initialize` opens a session. |
+| `GET`    | `/mcp` | The server→client SSE stream for an existing session.                  |
+| `DELETE` | `/mcp` | End a session and release its slot.                                    |
+
+Every request is authenticated with `x-api-key` or `Authorization: Bearer <key>` and needs `query`;
+a session may only be driven by the key that opened it. Tools, resources and prompts are exactly
+`@uptimizr/mcp`'s. Sessions are capped by `COLLECTOR_MCP_MAX_SESSIONS` (default `50`, one too many
+→ `503`) and expire after `COLLECTOR_MCP_SESSION_TTL_MS` idle (default 30 minutes); tool calls are
+audited with `surface: "mcp-http"`. Behind a reverse proxy, turn response buffering **off** for
+`/mcp`. See the [MCP guide](https://uptimizr.com/docs/guides/mcp/#hosted-transport-streamable-http).
+
 ## Security
 
 `@fastify/helmet`, `@fastify/cors` (restricted to `COLLECTOR_CORS_ORIGINS`), and
@@ -223,6 +289,7 @@ if `VISITOR_HASH_SECRET` is missing.
 | Live SSE routes (`/api/v1/live/*` `GET`s) | `?token=...`       | Browser `EventSource` cannot attach custom headers, so live streams use short-lived bearer tokens.                                                      |
 | `GET /health`                             | None               | Liveness probe.                                                                                                                                         |
 | `GET /api/v1/openapi.json`                | None               | API documentation, not data — a client needs it before it has a key. Rate-limited like every other route.                                               |
+| `/mcp` (when `COLLECTOR_MCP_HTTP=1`)      | `x-api-key`        | Hosted MCP. `Authorization: Bearer <key>` is accepted as an alias on this route only; the session id is never a credential on its own.                  |
 
 ### API keys and capabilities
 
@@ -306,6 +373,8 @@ Environment-driven (see [`.env.example`](../../../.env.example)):
 - Rate limits: `COLLECTOR_RATE_LIMIT_MAX`, `COLLECTOR_RATE_LIMIT_WINDOW_MS`,
   `COLLECTOR_INGEST_RATE_LIMIT_MAX`, `COLLECTOR_INGEST_RATE_LIMIT_WINDOW_MS`
   (a key's own budget overrides the first pair).
+- Hosted MCP: `COLLECTOR_MCP_HTTP` (off by default), `COLLECTOR_MCP_MAX_SESSIONS`
+  (default `50`), `COLLECTOR_MCP_SESSION_TTL_MS` (default `1800000`).
 - Agent audit: `AUDIT_RETENTION_DAYS` (default `30`, `0` = keep forever),
   `AUDIT_DASHBOARD_REQUESTS` (default off).
 - All-in-one dashboard: `COLLECTOR_DASHBOARD_DIR` (optional; see

package/dist/__tests__/support/registryRequests.d.ts

@@ -34,7 +34,8 @@ export declare const TEST_PROXY: {
 export declare const PATH_PARAM_VALUES: Readonly<Record<string, string>>;
 /**
  * Query parameters an endpoint needs beyond the shared range. Only the genuinely
- * required ones: `mesh` for the per-mesh UV heatmap and `steps` for the funnel.
+ * required ones: `mesh` for the per-mesh UV heatmap, `steps` for the funnel and
+ * `metric` for the baseline.
  */
 export declare const REQUIRED_QUERY: Readonly<Record<string, Record<string, string>>>;
 /** The two resource reads, which legitimately 404 when nothing is registered. */

package/dist/__tests__/support/registryRequests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registryRequests.d.ts","sourceRoot":"","sources":["../../../src/__tests__/support/registryRequests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,eAqBzB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,UAAU;;;;YAIW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;cAM5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;CAMrF,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAK3E,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAG/C,CAAC;AAEH;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC3C,MAAM,CAYR"}
+{"version":3,"file":"registryRequests.d.ts","sourceRoot":"","sources":["../../../src/__tests__/support/registryRequests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,eA6BzB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,UAAU;;;;YAIW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;cAM5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;CAMrF,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY3E,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAG/C,CAAC;AAEH;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC3C,MAAM,CAYR"}

package/dist/__tests__/support/registryRequests.js

@@ -33,6 +33,14 @@ export const TEST_CONFIG = {
     cspMode: "strict",
     auditRetentionDays: 30,
     auditDashboardRequests: false,
+    mcpHttpEnabled: false,
+    mcpMaxSessions: 50,
+    mcpSessionTtlMs: 1_800_000,
+    // The sweeps build an app per case; leaving the scheduler off keeps them free
+    // of timers they never assert on. Webhook egress stays disallowed by default.
+    subscriptions: false,
+    subscriptionsMaxConcurrent: 4,
+    webhookAllowedHosts: [],
 };
 /** Fixture scene proxy, so the `scene_representation` resource has a hit. */
 export const TEST_PROXY = {
@@ -60,13 +68,21 @@ export const PATH_PARAM_VALUES = {
 };
 /**
  * Query parameters an endpoint needs beyond the shared range. Only the genuinely
- * required ones: `mesh` for the per-mesh UV heatmap and `steps` for the funnel.
+ * required ones: `mesh` for the per-mesh UV heatmap, `steps` for the funnel and
+ * `metric` for the baseline.
  */
 export const REQUIRED_QUERY = {
     "/api/v1/heatmaps/mesh-uv": { mesh: "box" },
     "/api/v1/funnel": {
         steps: JSON.stringify([{ type: "session_start" }, { type: "pointer_click" }]),
     },
+    // A baseline is a baseline *of* something: the metric is the subject rather
+    // than a filter, so it is the one insight parameter with no default.
+    "/api/v1/insights/baseline": { metric: "list_sessions" },
+    // --- anomalies (#306) --- same subject-is-the-parameter rule.
+    "/api/v1/insights/anomalies": { metric: "list_sessions" },
+    // --- significance / scene health (#307) ---
+    "/api/v1/insights/significance": { metric: "list_sessions" },
 };
 /** The two resource reads, which legitimately 404 when nothing is registered. */
 export const RESOURCE_METRICS = new Set([

package/dist/__tests__/support/registryRequests.js.map

@@ -1 +1 @@
-{"version":3,"file":"registryRequests.js","sourceRoot":"","sources":["../../../src/__tests__/support/registryRequests.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registryRequests.js","sourceRoot":"","sources":["../../../src/__tests__/support/registryRequests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,CAAC;IACP,WAAW,EAAE,EAAE;IACf,iBAAiB,EAAE,aAAa;IAChC,yBAAyB,EAAE,KAAK;IAChC,YAAY,EAAE,MAAM;IACpB,eAAe,EAAE,kBAAkB;IACnC,0BAA0B,EAAE,IAAI;IAChC,cAAc,EAAE,OAAO;IACvB,kBAAkB,EAAE,GAAG;IACvB,sBAAsB,EAAE,KAAK;IAC7B,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,MAAM;IACzB,kBAAkB,EAAE,IAAI;IACxB,uBAAuB,EAAE,MAAM;IAC/B,UAAU,EAAE,KAAK;IACjB,SAAS,EAAE,SAAS;IACpB,OAAO,EAAE,QAAQ;IACjB,kBAAkB,EAAE,EAAE;IACtB,sBAAsB,EAAE,KAAK;IAC7B,cAAc,EAAE,KAAK;IACrB,cAAc,EAAE,EAAE;IAClB,eAAe,EAAE,SAAS;IAC1B,8EAA8E;IAC9E,8EAA8E;IAC9E,aAAa,EAAE,KAAK;IACpB,0BAA0B,EAAE,CAAC;IAC7B,mBAAmB,EAAE,EAAE;CACxB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,CAAU;IACnB,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,MAAe;IACrB,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAqD;IAChF,MAAM,EAAE,GAAY;IACpB,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE;QACN;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAqD;SACjF;KACF;IACD,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,QAAQ;IACrB,UAAU,EAAE,iBAAiB;CAC9B,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAqC;IACjE,YAAY,EAAE,IAAI;IAClB,KAAK,EAAE,IAAI;IACX,UAAU,EAAE,OAAO;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAqD;IAC9E,0BAA0B,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;IAC3C,gBAAgB,EAAE;QAChB,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;KAC9E;IACD,4EAA4E;IAC5E,qEAAqE;IACrE,2BAA2B,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE;IACxD,+DAA+D;IAC/D,4BAA4B,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE;IACzD,6CAA6C;IAC7C,+BAA+B,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE;CAC7D,CAAC;AAEF,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IAC3D,cAAc;IACd,sBAAsB;CACvB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,MAAwB,EACxB,QAA0C,EAAE;IAE5C,IAAI,IAAI,GAAG,MAAM,CAAC,QAAS,CAAC,IAAI,CAAC;IACjC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC/D,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,KAAK,EAAE,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC;QACjC,KAAK,EAAE,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC;QACjC,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,QAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChD,GAAG,KAAK;KACT,CAAC,CAAC;IACH,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AACxC,CAAC"}

package/dist/__tests__/support/subscriptionFixtures.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared constants for the subscription route suite (#311).
+ *
+ * Re-exported through this module rather than imported directly in the test so
+ * the numbers and the mask come from the single definitions in
+ * `@uptimizr/schema` and `@uptimizr/db` — a test that hard-codes `100` or
+ * `"••••••••"` stops testing the bound the moment the bound moves.
+ *
+ * Not a test file — the filename has no `.test.` segment, so Vitest does not
+ * collect it.
+ */
+export declare const LIMITS: {
+    readonly maxBatchEvents: 1000;
+    readonly maxProjectIdLength: 128;
+    readonly maxSessionIdLength: 128;
+    readonly maxSdkVersionLength: 64;
+    readonly maxUrlLength: 2048;
+    readonly maxTitleLength: 512;
+    readonly maxReferrerLength: 2048;
+    readonly maxLanguageLength: 35;
+    readonly maxMeshNameLength: 256;
+    readonly maxAssetNameLength: 1024;
+    readonly maxCustomNameLength: 128;
+    readonly maxCustomPropValueLength: 1024;
+    readonly maxCustomPropEntries: 64;
+    readonly maxUserIdLength: 128;
+    readonly maxUserTraitValueLength: 1024;
+    readonly maxUserTraitEntries: 64;
+    readonly maxSceneDescriptionLength: 256;
+    readonly maxCameraNameLength: 128;
+    readonly maxSceneProxyMeshNameLength: 256;
+    readonly maxSceneProxyMeshPathLength: 512;
+    readonly maxSceneProxyMeshes: 10000;
+    readonly maxSceneRegionLabelLength: 120;
+    readonly maxSceneRegionDescriptionLength: 500;
+    readonly maxSceneRegions: 200;
+    readonly maxSubscriptionNameLength: 120;
+    readonly maxSubscriptionDeliveries: 4;
+    readonly maxSubscriptionsPerProject: 100;
+    readonly maxSubscriptionEvents: 100;
+    readonly maxNodeIdLength: 128;
+    readonly maxBoneIdLength: 128;
+    readonly maxChildPathLength: 512;
+    readonly maxGraphicsDiagnosticMessageLength: 1024;
+    readonly maxGraphicsDiagnosticCodeLength: 64;
+    readonly maxAnnotationTextLength: 2000;
+    readonly maxAnnotationTargetIdLength: 256;
+    readonly maxProjectAnnotations: 500;
+    readonly maxGlossaryTermLength: 64;
+    readonly maxGlossaryMeaningLength: 500;
+    readonly maxProjectGlossaryEntries: 200;
+    readonly maxSavedAnalysisTitleLength: 120;
+    readonly maxSavedAnalysisConclusionLength: 4000;
+    readonly maxSavedAnalysisQueryLength: 8000;
+    readonly maxProjectSavedAnalyses: 200;
+    readonly maxPanelSpecTitleLength: 120;
+    readonly maxPanelSpecNoteLength: 500;
+    readonly maxPanelEncodingColumnLength: 64;
+    readonly maxProjectPanelSpecs: 50;
+};
+/** What every read path shows in place of a stored webhook secret. */
+export declare const MASKED_SECRET_PLACEHOLDER = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+//# sourceMappingURL=subscriptionFixtures.d.ts.map

package/dist/__tests__/support/subscriptionFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionFixtures.d.ts","sourceRoot":"","sources":["../../../src/__tests__/support/subscriptionFixtures.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAgB,CAAC;AAEpC,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,qDAAgB,CAAC"}

package/dist/__tests__/support/subscriptionFixtures.js

@@ -0,0 +1,17 @@
+import { LIMITS as SCHEMA_LIMITS } from "@uptimizr/schema";
+import { MASKED_SECRET } from "@uptimizr/db";
+/**
+ * Shared constants for the subscription route suite (#311).
+ *
+ * Re-exported through this module rather than imported directly in the test so
+ * the numbers and the mask come from the single definitions in
+ * `@uptimizr/schema` and `@uptimizr/db` — a test that hard-codes `100` or
+ * `"••••••••"` stops testing the bound the moment the bound moves.
+ *
+ * Not a test file — the filename has no `.test.` segment, so Vitest does not
+ * collect it.
+ */
+export const LIMITS = SCHEMA_LIMITS;
+/** What every read path shows in place of a stored webhook secret. */
+export const MASKED_SECRET_PLACEHOLDER = MASKED_SECRET;
+//# sourceMappingURL=subscriptionFixtures.js.map

package/dist/__tests__/support/subscriptionFixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionFixtures.js","sourceRoot":"","sources":["../../../src/__tests__/support/subscriptionFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,aAAa,CAAC;AAEpC,sEAAsE;AACtE,MAAM,CAAC,MAAM,yBAAyB,GAAG,aAAa,CAAC"}