@uptimizr/agent-core 1.0.1 → 1.1.0

package/AGENTS.md

@@ -9,7 +9,9 @@ The **framework-agnostic, browser-safe core** shared by every Uptimizr analytics
 the agent tool surface **once** (ADR 0050 §1) so `@uptimizr/mcp`, the dashboard assistant, and the
 demo assistant never drift apart. It owns:
 
-- the **read-only tool catalog** (`readTools`) — one entry per documented collector query endpoint;
+- the **read-only tool catalog** (`readTools`) — one entry per documented collector query endpoint,
+  **generated** from the `@uptimizr/metrics` semantic metric registry (ADR 0051 §1), so coverage of the
+  collector's read surface cannot drift;
 - a headless **LLM provider-adapter interface** (`LlmProvider`) — messages + tool schemas in, tool
   calls or final text out;
 - the headless **tool-calling loop** (`runAgent`) — LLM ↔ tools ↔ collector.
@@ -17,22 +19,60 @@ demo assistant never drift apart. It owns:
 The core ships **no model and no key**. It only ever reads a consumer's **own** collector via the
 `CollectorClient` (`GET`-only, `x-api-key`).
 
+## Tool catalog (read-only)
+
+<!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this list -->
+
+`list_sessions`, `session_meta`, `scene_representation`, `list_scenes`, `timeseries`,
+`event_counts`, `pointer_heatmap`, `mesh_uv_heatmap`, `world_heatmap`, `world_heatmap_stats`,
+`gaze_heatmap`, `gaze_heatmap_stats`, `camera_heatmap`, `view_coverage_histogram`,
+`position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
+`click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
+`mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
+`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
+`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
+`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
+`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
+`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
+`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
+`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
+`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+
+<!-- generated:registry-tool-names:end -->
+
+Each name is a metric in the collector's semantic metric registry (ADR 0051) and maps one-to-one to
+a documented query endpoint. Most accept `since`/`until` (epoch ms) plus endpoint-specific filters.
+
 ## Rules for agents
 
 - **Read-only and privacy-preserving.** Never add ingestion, mutation, or raw per-session event
   tools. The surface is aggregate-only; no data leaves the consumer's infrastructure (ADR 0003 /
-  ADR 0017). A new tool = a new entry in `readTools` mapping to a documented query endpoint — no
-  aggregation/business logic (that lives in the collector, ADR 0005).
-- **Browser-safe.** No Node dependencies, no `types: ["node"]`; only `zod` at runtime. Anything that
-  needs `process.env`, stdio, or the filesystem belongs in a consumer package (e.g. `@uptimizr/mcp`),
-  not here.
+  ADR 0017). A new tool = a new **metric registry entry** in `@uptimizr/metrics` for a documented query
+  endpoint — never a hand-written catalog entry here — and no aggregation/business logic (that lives
+  in the collector, ADR 0005).
+- **Browser-safe.** No Node dependencies, no `types: ["node"]`. At runtime this package uses `zod`
+  plus the pure, data-only `@uptimizr/metrics` package — **never** `@uptimizr/db`, which owns the
+  DuckDB store and its ~37 MB native binding. `src/__tests__/browserSafety.test.ts` bundles the
+  package for the browser and fails if that changes, and `src/__tests__/dependencies.test.ts` fails
+  if `@uptimizr/db` (or anything else with a native/optional binary dependency) reappears in the
+  manifest. Anything that needs `process.env`, stdio, or the filesystem belongs in a consumer
+  package (e.g. `@uptimizr/mcp`), not here.
 - Tool definitions are pure (`buildRequest`) and must stay unit-testable without a live collector.
+- The 20 tool names (and argument schemas) that shipped before the registry are a public contract:
+  `src/__tests__/shippedToolCompat.test.ts` pins them against a frozen fixture. Widening a tool with
+  a new **optional** argument is fine; renaming one or making an argument required is not.
 - Keep provider adapters thin and out of this package: implement `LlmProvider` in the consumer.
 
 ## Programmatic API
 
-`readTools`, `createCollectorClient(config)`, `toToolSchemas(tools?)`, `runAgent(options)`, plus the
-`LlmProvider` / `AgentMessage` / `AgentToolCall` / `ProviderResponse` types.
+`readTools`, `coreReadTools`, `selectReadTools(kind)`, `filterReadTools(names)`,
+`registryToTools(metrics?)`, `createCollectorClient(config)`, `toToolSchemas(tools?)`,
+`runAgent(options)`, plus the `LlmProvider` / `AgentMessage` / `AgentToolCall` /
+`ProviderResponse` types.
+
+The catalog is ~69 tools. A small local model cannot hold every schema in its function-calling
+prompt — hand a run `coreReadTools` or `filterReadTools([...])` rather than the full catalog.
 
 ## More
 

package/README.md

@@ -61,23 +61,71 @@ console.log(result.content); // the model's final answer
 
 ## Tool catalog (read-only)
 
-`list_sessions`, `pointer_heatmap`, `world_heatmap`, `camera_heatmap`, `click_rays`, `flow_links`,
-`top_meshes`, `perf_summary`, `list_scenes`, `timeseries`, `event_counts`, `session_meta`,
-`scene_representation`, `funnel`, `aggregate_paths`, `rendering_technology`, `xr_rotation`,
-`xr_sources`, `xr_abandonment`, `xr_locomotion`. Most accept `since`/`until` (epoch ms) plus
-endpoint-specific filters (`scene`, `session`, `source`, `bins`, `cellSize`, `limit`, `cameraMode`,
-`rapidTurn`, `steps`). Each maps one-to-one to a documented
-collector query endpoint (see the [integration guide](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md)).
+<!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this table -->
+
+`list_sessions`, `session_meta`, `scene_representation`, `list_scenes`, `timeseries`,
+`event_counts`, `pointer_heatmap`, `mesh_uv_heatmap`, `world_heatmap`, `world_heatmap_stats`,
+`gaze_heatmap`, `gaze_heatmap_stats`, `camera_heatmap`, `view_coverage_histogram`,
+`position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
+`click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
+`mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
+`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
+`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
+`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
+`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
+`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
+`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
+`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
+`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+
+<!-- generated:registry-tool-names:end -->
+
+`readTools` is **generated** from the semantic metric registry in `@uptimizr/metrics`
+([ADR 0051](https://github.com/RaananW/Uptimizr/blob/main/docs/adr/0051-ai-first-analytics-layer.md) §1):
+one tool per metric the collector serves on a read endpoint — **69** today, covering sessions and
+scenes, pointer/world/gaze/camera heatmaps, mesh attention and blind spots, dead and rage clicks,
+navigation and desire lines, performance (FPS distribution, jank, compile stalls, per-device and
+per-scene), errors and stability, XR/AR comfort and placement, and conversion (funnel, scene
+retention, load→bounce, variant leaderboard). The full table is in the
+[MCP guide](https://uptimizr.com/docs/guides/mcp/), and each tool maps one-to-one to a documented
+collector query endpoint (see the
+[integration guide](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md)).
+
+Each tool carries:
+
+- a **name** that is the registry metric id (the 20 names shipped before the registry are
+  unchanged, and so are their argument schemas — a frozen-fixture test pins that);
+- a **description** composed from the metric's description, how to read the result, and its
+  caveats (sample-size limits, which capture channel must be on);
+- an **input schema** built from the endpoint's filters — most accept `since`/`until` (epoch ms)
+  plus `scene`, `session`, `source`, `bins`, `cellSize`, `limit`, `cameraMode`, `region`, …;
+- an **output schema** (`{ rows: Row[] }`) derived from the metric's row schema, which
+  `@uptimizr/mcp` registers as the MCP `outputSchema`.
+
+The registry lives in `@uptimizr/metrics`, a dependency-free package (`zod` +
+`@uptimizr/schema`), so installing this one never downloads a database driver: `@uptimizr/db` and
+its ~37 MB native DuckDB binding are **not** a dependency. Two tests keep that true — a bundle test
+asserts no `node:` built-in or DuckDB driver can reach a browser build, and a manifest test fails
+if any package with a native or optional binary dependency reappears.
 
 ## API
 
-| Export                         | Purpose                                                           |
-| ------------------------------ | ----------------------------------------------------------------- |
-| `readTools`                    | The read-only tool catalog (one entry per query endpoint).        |
-| `createCollectorClient(cfg)`   | Thin `GET`-only collector client (`fetch`-based, injectable).     |
-| `toToolSchemas(tools?)`        | Convert catalog tools to JSON-Schema tool descriptors for an LLM. |
-| `runAgent(options)`            | The headless tool-calling loop.                                   |
-| `LlmProvider` / `AgentMessage` | The provider-adapter interface and message types.                 |
+| Export                         | Purpose                                                              |
+| ------------------------------ | -------------------------------------------------------------------- |
+| `readTools`                    | The read-only tool catalog (one entry per query endpoint).           |
+| `coreReadTools`                | Focused subset for small local models (a filtered view, not a copy). |
+| `selectReadTools(kind)`        | Pick `"core"` or `"full"`.                                           |
+| `filterReadTools(names)`       | Narrow the catalog to specific tool names, in catalog order.         |
+| `registryToTools(metrics?)`    | Generate the catalog from metric-registry definitions.               |
+| `createCollectorClient(cfg)`   | Thin `GET`-only collector client (`fetch`-based, injectable).        |
+| `toToolSchemas(tools?)`        | Convert catalog tools to JSON-Schema tool descriptors for an LLM.    |
+| `runAgent(options)`            | The headless tool-calling loop.                                      |
+| `LlmProvider` / `AgentMessage` | The provider-adapter interface and message types.                    |
+
+A 69-tool catalog is more than a small local model can hold in its function-calling prompt — use
+`coreReadTools` (what the `@uptimizr/react` assistant sends the WebLLM backend) or
+`filterReadTools([...])` to hand a run a deliberate subset.
 
 The loop stops when the provider returns a final answer or after `maxSteps` turns
 (`DEFAULT_MAX_STEPS`, default 8). Unknown tools and invalid arguments are surfaced back to the model

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createCollectorClient, CollectorError, type CollectorClient, type CollectorClientConfig, type QueryParams, } from "./client.js";
-export { readTools, coreReadTools, selectReadTools, CORE_READ_TOOL_NAMES, type ReadTool, type ReadToolRequest, type ReadToolSetKind, } from "./tools.js";
+export { readTools, coreReadTools, selectReadTools, filterReadTools, CORE_READ_TOOL_NAMES, type ReadTool, type ReadToolRequest, type ReadToolSetKind, } from "./tools.js";
+export { registryToTools, metricToTool, describeMetric } from "./registryTools.js";
 export type { AgentMessage, AgentToolCall, AgentToolSchema, LlmProvider, ProviderRequest, ProviderResponse, } from "./provider.js";
 export { runAgent, toToolSchemas, truncateToolResult, DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_RESULT_CHARS, type AgentStreamEvent, type RunAgentOptions, type RunAgentResult, } from "./loop.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnF,YAAY,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createCollectorClient, CollectorError, } from "./client.js";
-export { readTools, coreReadTools, selectReadTools, CORE_READ_TOOL_NAMES, } from "./tools.js";
+export { readTools, coreReadTools, selectReadTools, filterReadTools, CORE_READ_TOOL_NAMES, } from "./tools.js";
+export { registryToTools, metricToTool, describeMetric } from "./registryTools.js";
 export { runAgent, toToolSchemas, truncateToolResult, DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_RESULT_CHARS, } from "./loop.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GAIf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,oBAAoB,GAIrB,MAAM,YAAY,CAAC;AASpB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,GAI9B,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GAIf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,GAIrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASnF,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,GAI9B,MAAM,WAAW,CAAC"}

package/dist/registryTools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * **Generated tool catalog** (ADR 0051 §1, design sketch §A.2).
+ *
+ * `registryToTools()` turns the semantic metric registry in `@uptimizr/metrics`
+ * into the read-only {@link ReadTool} catalog this package exports. One registry
+ * entry with an `endpoint` becomes exactly one tool, so agent coverage of the
+ * collector's read surface is mechanical rather than hand-maintained: adding an
+ * aggregation + a registry entry adds the tool, and there is no second list to
+ * forget.
+ *
+ * What each part of a tool is derived from:
+ *
+ * | Tool field     | Registry source                                            |
+ * | -------------- | ---------------------------------------------------------- |
+ * | `name`         | `id` (the 20 shipped tool names are registry ids verbatim)  |
+ * | `title`        | `title`                                                     |
+ * | `description`  | `description` + `interpretation` + `caveats`                |
+ * | `inputSchema`  | `filters` + `endpoint.pathParams`, via {@link FILTER_FIELDS} |
+ * | `buildRequest` | `endpoint.path` (with `:param` substitution) + `filters`    |
+ * | `outputSchema` | `row`, wrapped as `{ rows: Row[] }`                         |
+ *
+ * **Browser safety (ADR 0050).** This module imports `@uptimizr/metrics` — the
+ * registry's own dependency-free package, whose only runtime dependencies are
+ * `zod` and `@uptimizr/schema`. This package does not depend on `@uptimizr/db`
+ * at all: that package owns the DuckDB store and pulls in a ~37 MB native
+ * binding a browser can never use. `src/__tests__/browserSafety.test.ts` bundles
+ * this package for the browser and fails if any `node:` built-in or the DuckDB
+ * driver reaches the bundle, and `src/__tests__/dependencies.test.ts` fails if
+ * `@uptimizr/db` ever reappears in the manifest.
+ */
+import { type MetricDefinition } from "@uptimizr/metrics";
+import type { ReadTool } from "./tools.js";
+/**
+ * Compose the agent-facing tool description: what the metric measures, how to
+ * read the result, and the caveats that decide how far to trust it. All three
+ * come from the registry, so the prose an agent sees and the prose the docs and
+ * the capabilities resource show are the same text.
+ */
+export declare function describeMetric(metric: MetricDefinition): string;
+/**
+ * Build the {@link ReadTool} for one registry metric. Returns `undefined` for a
+ * metric with no collector endpoint (the two daily rollups), which therefore
+ * cannot be called by an agent.
+ */
+export declare function metricToTool(metric: MetricDefinition): ReadTool | undefined;
+/**
+ * Generate the read-only tool catalog from the metric registry: one tool per
+ * registry entry that has a collector endpoint, in registry declaration order.
+ *
+ * Pure — it reads definitions only and never touches a collector — so the whole
+ * catalog is unit-testable without a live server.
+ */
+export declare function registryToTools(metrics?: readonly MetricDefinition[]): readonly ReadTool[];
+//# sourceMappingURL=registryTools.d.ts.map

package/dist/registryTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registryTools.d.ts","sourceRoot":"","sources":["../src/registryTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErF,OAAO,KAAK,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC;AAkT5D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAO/D;AAYD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CA6D3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,SAAS,gBAAgB,EAAiB,GAClD,SAAS,QAAQ,EAAE,CAOrB"}

package/dist/registryTools.js

@@ -0,0 +1,409 @@
+/**
+ * **Generated tool catalog** (ADR 0051 §1, design sketch §A.2).
+ *
+ * `registryToTools()` turns the semantic metric registry in `@uptimizr/metrics`
+ * into the read-only {@link ReadTool} catalog this package exports. One registry
+ * entry with an `endpoint` becomes exactly one tool, so agent coverage of the
+ * collector's read surface is mechanical rather than hand-maintained: adding an
+ * aggregation + a registry entry adds the tool, and there is no second list to
+ * forget.
+ *
+ * What each part of a tool is derived from:
+ *
+ * | Tool field     | Registry source                                            |
+ * | -------------- | ---------------------------------------------------------- |
+ * | `name`         | `id` (the 20 shipped tool names are registry ids verbatim)  |
+ * | `title`        | `title`                                                     |
+ * | `description`  | `description` + `interpretation` + `caveats`                |
+ * | `inputSchema`  | `filters` + `endpoint.pathParams`, via {@link FILTER_FIELDS} |
+ * | `buildRequest` | `endpoint.path` (with `:param` substitution) + `filters`    |
+ * | `outputSchema` | `row`, wrapped as `{ rows: Row[] }`                         |
+ *
+ * **Browser safety (ADR 0050).** This module imports `@uptimizr/metrics` — the
+ * registry's own dependency-free package, whose only runtime dependencies are
+ * `zod` and `@uptimizr/schema`. This package does not depend on `@uptimizr/db`
+ * at all: that package owns the DuckDB store and pulls in a ~37 MB native
+ * binding a browser can never use. `src/__tests__/browserSafety.test.ts` bundles
+ * this package for the browser and fails if any `node:` built-in or the DuckDB
+ * driver reaches the bundle, and `src/__tests__/dependencies.test.ts` fails if
+ * `@uptimizr/db` ever reappears in the manifest.
+ */
+import { z } from "zod";
+import { allMetrics } from "@uptimizr/metrics";
+// ---------------------------------------------------------------------------
+// Shared parameter definitions
+// ---------------------------------------------------------------------------
+//
+// One Zod field per registry `FilterId`, defined **once** and reused by every
+// tool that accepts that filter — the "a param means the same thing everywhere"
+// rule the capabilities resource already assumes.
+//
+// The fields for the parameters the hand-written catalog shipped (`since`,
+// `until`, `bins`, `limit`, `scene`, `session`, `cellSize`, `interval`, `type`,
+// `source`, `cameraMode`, `rapidTurn`, `steps`) are carried over **verbatim**,
+// so the 20 shipped tools' JSON Schemas are byte-identical after the migration
+// (`src/__tests__/shippedToolCompat.test.ts` pins that against a frozen
+// fixture). Bounds on the new fields mirror the collector's own Zod querystring
+// in `oss/apps/collector-server/src/routes/query.ts`.
+const since = z.number().int().optional().describe("Start of the time range, epoch milliseconds.");
+const until = z.number().int().optional().describe("End of the time range, epoch milliseconds.");
+const bins = z.number().int().positive().max(500).optional().describe("Grid resolution per axis.");
+const limit = z.number().int().positive().max(1000).optional().describe("Maximum rows to return.");
+const scene = z.string().optional().describe("Restrict to one developer-assigned scene id.");
+const session = z.string().optional().describe("Scope the aggregate to a single session id.");
+const cellSize = z.number().positive().max(1000).optional().describe("Voxel size in world units.");
+const interval = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Time-series bucket width, seconds.");
+const eventType = z
+    .string()
+    .optional()
+    .describe("Restrict to a single event type, e.g. pointer_click.");
+const source = z
+    .enum(["mouse", "touch", "stylus", "pen", "xr-controller", "hand", "gaze", "transient", "other"])
+    .optional()
+    .describe("Restrict a pointer/world heatmap to one input source.");
+const cameraMode = z
+    .enum(["viewer", "first-person"])
+    .optional()
+    .describe("Camera navigation mode to scope to: 'viewer' (orbit) or 'first-person' (walkable).");
+const rapidTurn = z
+    .number()
+    .nonnegative()
+    .max(Math.PI)
+    .optional()
+    .describe("Rapid-turn threshold in radians (0..π); view turns above this flag motion-sickness risk.");
+const steps = z
+    .string()
+    .min(1)
+    .describe("Funnel steps as a JSON-encoded array of ordered step predicates (ADR 0038). Required. " +
+    'Each step is `{ "type": <event_type>, ... }`; e.g. ' +
+    '`[{"type":"scene_change","to":"lobby"},{"type":"mesh_interaction","mesh":"buy"}]`.');
+/**
+ * The Zod field each {@link FilterId} contributes to a tool's input schema.
+ *
+ * Every entry is **optional** except the two the collector declares required
+ * (see {@link REQUIRED_FILTERS}); `filterField()` re-derives requiredness per
+ * metric so one shared definition serves both cases.
+ */
+const FILTER_FIELDS = {
+    since,
+    until,
+    scene,
+    session,
+    source,
+    mesh: z.string().min(1).max(256).optional().describe("Restrict to one mesh/object name."),
+    region: z
+        .string()
+        .optional()
+        .describe("World-space drill-down box as `minX,minY,minZ,maxX,maxY,maxZ` (ADR 0040 §4). " +
+        "Omit for the whole scene."),
+    cameraMode,
+    bins,
+    limit,
+    cellSize,
+    interval,
+    type: eventType,
+    bucket: z.number().int().positive().max(240).optional().describe("Histogram bin width in FPS."),
+    bucketMs: z
+        .number()
+        .int()
+        .positive()
+        .max(60_000)
+        .optional()
+        .describe("Histogram bin width in milliseconds."),
+    bucketSize: z
+        .number()
+        .positive()
+        .max(1000)
+        .optional()
+        .describe("Histogram bin width in world units."),
+    minRepeats: z
+        .number()
+        .int()
+        .min(2)
+        .max(100)
+        .optional()
+        .describe("Minimum clicks in a window before it counts as a rage cluster."),
+    windowMs: z
+        .number()
+        .int()
+        .positive()
+        .max(86_400_000)
+        .optional()
+        .describe("How long before a session's end a perf dip still counts as correlated."),
+    fpsThreshold: z
+        .number()
+        .positive()
+        .max(240)
+        .optional()
+        .describe("A frame-perf sample below this FPS counts as a dip."),
+    stallMs: z
+        .number()
+        .nonnegative()
+        .max(60_000)
+        .optional()
+        .describe("A shader-compile stall at least this long (ms) counts as a dip."),
+    moveThreshold: z
+        .number()
+        .nonnegative()
+        .max(1000)
+        .optional()
+        .describe("Inter-sample distance (world units) above which a segment counts as active travel."),
+    rapidTurn,
+    centerX: z.number().optional().describe("X of the reference point distances are measured from."),
+    centerY: z.number().optional().describe("Y of the reference point distances are measured from."),
+    centerZ: z.number().optional().describe("Z of the reference point distances are measured from."),
+    severity: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Graphics-diagnostic severity (info / warning / error / fatal). " +
+        "Setting it excludes JS runtime errors."),
+    category: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Graphics-diagnostic category (context-loss / validation / shader-compile / …). " +
+        "Setting it excludes JS runtime errors."),
+    errorKind: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Runtime-error kind (error / unhandledrejection). Setting it excludes engine diagnostics."),
+    groupByOrigin: z
+        .boolean()
+        .optional()
+        .describe("Add the click-time standpoint voxel as a grouping dimension."),
+    originVoxel: z
+        .string()
+        .regex(/^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$/)
+        .optional()
+        .describe("Restrict to clicks whose standpoint falls in this `vx,vy,vz` voxel."),
+    steps: steps.optional(),
+    bands: z
+        .string()
+        .max(256)
+        .optional()
+        .describe("Ascending, comma-separated load-time band boundaries in ms. " +
+        "Omit for the default `1000,3000,5000`."),
+    variant: z
+        .string()
+        .min(1)
+        .max(2048)
+        .optional()
+        .describe("JSON funnel-step predicate selecting the variant events. " +
+        "Omit to treat every custom event as a variant."),
+    conversion: z
+        .string()
+        .min(1)
+        .max(2048)
+        .optional()
+        .describe("JSON funnel-step predicate for the success event. Omit to report views only."),
+    // The shared result envelope (ADR 0051 §2). Declared literally rather than
+    // imported from `@uptimizr/db/summary`, which would put a database driver back
+    // on this package's dependency graph. `full` stays the default here: switching
+    // the generated tools to `table` is a separate, documented change (#299).
+    format: z
+        .enum(["full", "table", "summary"])
+        .optional()
+        .describe("Result envelope. `full` (default) returns the bare rows; `table` wraps them with a " +
+        "`meta` block; `summary` returns a bounded digest — top rows, a trend or merged " +
+        "spatial clusters — with shares, caveats and a plain-language reading. Prefer " +
+        "`summary` for a large result such as a heatmap or a long leaderboard."),
+};
+/**
+ * Filters the collector declares **required** in its querystring schema, by
+ * metric id. The registry records requiredness in prose (a `caveats` line) but
+ * not as data, so the two exceptions are listed here; everything else is
+ * optional. Path parameters are always required and are handled separately.
+ *
+ * Keep this in step with `oss/apps/collector-server/src/routes/query.ts`
+ * (`funnelQueryParams.steps`, `meshUvHeatmapQueryParams.mesh`). Promoting it
+ * into the registry itself is tracked as a follow-up.
+ */
+const REQUIRED_FILTERS = {
+    funnel: ["steps"],
+    mesh_uv_heatmap: ["mesh"],
+};
+/**
+ * The **required** variant of each filter named in {@link REQUIRED_FILTERS} —
+ * the same field without the trailing `.optional()`. Declared rather than
+ * unwrapped so the shipped `steps` schema stays byte-identical.
+ */
+const REQUIRED_FILTER_FIELDS = {
+    steps,
+    mesh: z.string().min(1).max(256).describe("The mesh/object name to bin. Required."),
+};
+/**
+ * Argument name for a filter that travels in the **path** rather than the
+ * querystring. The registry names such a parameter by the filter it binds
+ * (`session`, `scene`); the shipped tools call them `sessionId` / `sceneId` and
+ * those names are part of the public MCP contract, so they are preserved.
+ */
+const PATH_PARAM_ARG_NAMES = {
+    session: "sessionId",
+    scene: "sceneId",
+};
+/** The Zod field a path parameter contributes — always a required, non-empty id. */
+const PATH_PARAM_FIELDS = {
+    session: z.string().min(1).describe("The session id to describe."),
+    scene: z.string().min(1).describe("The scene id to fetch."),
+};
+// ---------------------------------------------------------------------------
+// Generation
+// ---------------------------------------------------------------------------
+/** The field a metric contributes for one filter: required where the route says so. */
+function filterField(metric, filter) {
+    if (REQUIRED_FILTERS[metric.id]?.includes(filter)) {
+        const required = REQUIRED_FILTER_FIELDS[filter];
+        if (!required)
+            throw new Error(`no required field defined for filter '${filter}'`);
+        return required;
+    }
+    return FILTER_FIELDS[filter];
+}
+/**
+ * The row schema a tool advertises, built from the registry's `row`.
+ *
+ * Two deliberate relaxations, both driven by what the collector really returns:
+ *
+ * - **Every column is nullable.** An aggregate over a range with no matching
+ *   samples projects SQL `NULL` for its measures (`resource_summary`,
+ *   `perf_churn`, … over an empty window). The registry's row schema describes
+ *   the populated shape; a consumer that validates the advertised JSON Schema
+ *   strictly — the MCP SDK's client does, with Ajv — would otherwise reject a
+ *   perfectly ordinary "no data yet" answer. The column set and its types stay
+ *   exactly as the registry declares them.
+ * - **Unknown columns are kept.** A few routes add a field of their own on top
+ *   of the aggregation (the `*_stats` endpoints echo the resolved `cellSize`),
+ *   and dropping it silently would be worse than passing it through.
+ *
+ * The schema still *coerces*: `@uptimizr/db` declares numeric columns with
+ * `z.coerce.number()` because ClickHouse renders 64-bit integers as strings over
+ * HTTP, so parsing a result with this schema normalises those strings to JSON
+ * numbers (ADR 0051 §2). `@uptimizr/mcp` parses with it before sending
+ * `structuredContent`, which is what makes the advertised schema true on every
+ * store engine.
+ */
+function outputRowSchema(metric) {
+    const shape = {};
+    for (const [column, field] of Object.entries(metric.row.shape)) {
+        shape[column] = field.nullable();
+    }
+    return z.looseObject(shape);
+}
+/** `[":id"]` → the ordered `:param` placeholders of a Fastify path. */
+function pathPlaceholders(path) {
+    return path
+        .split("/")
+        .filter((segment) => segment.startsWith(":"))
+        .map((segment) => segment.slice(1));
+}
+/**
+ * Compose the agent-facing tool description: what the metric measures, how to
+ * read the result, and the caveats that decide how far to trust it. All three
+ * come from the registry, so the prose an agent sees and the prose the docs and
+ * the capabilities resource show are the same text.
+ */
+export function describeMetric(metric) {
+    const caveats = metric.caveats.map((caveat) => `- ${caveat}`).join("\n");
+    return (`${metric.description}\n\n` +
+        `How to read it: ${metric.interpretation}\n\n` +
+        `Caveats:\n${caveats}`);
+}
+/** The value a validated argument contributes to the collector querystring. */
+function toQueryValue(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "number" || typeof value === "string")
+        return value;
+    // `groupByOrigin` is a boolean in the tool schema and `"true"`/`"false"` on
+    // the wire (the collector's querystring enum).
+    if (typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
+/**
+ * Build the {@link ReadTool} for one registry metric. Returns `undefined` for a
+ * metric with no collector endpoint (the two daily rollups), which therefore
+ * cannot be called by an agent.
+ */
+export function metricToTool(metric) {
+    const endpoint = metric.endpoint;
+    if (!endpoint)
+        return undefined;
+    const pathParams = endpoint.pathParams ?? [];
+    const placeholders = pathPlaceholders(endpoint.path);
+    if (placeholders.length !== pathParams.length) {
+        throw new Error(`metric ${metric.id}: endpoint path has ${placeholders.length} path parameter(s) but ` +
+            `${pathParams.length} are declared`);
+    }
+    // `:param` placeholder (positional) → the tool argument that fills it.
+    const pathArgs = placeholders.map((placeholder, index) => {
+        const filter = pathParams[index];
+        const argName = PATH_PARAM_ARG_NAMES[filter];
+        const field = PATH_PARAM_FIELDS[filter];
+        if (!argName || !field) {
+            throw new Error(`metric ${metric.id}: no tool argument defined for path filter '${filter}'`);
+        }
+        return { placeholder, argName, field };
+    });
+    const inputSchema = {};
+    for (const { argName, field } of pathArgs)
+        inputSchema[argName] = field;
+    for (const filter of metric.filters)
+        inputSchema[filter] = filterField(metric, filter);
+    // Every row of the collector's response, in one bounded envelope. A single
+    // object result (a session descriptor, a one-row summary) is reported as a
+    // one-element `rows` array so the envelope is the same for every tool.
+    const outputSchema = {
+        rows: z
+            .array(outputRowSchema(metric))
+            .describe(`Result rows (one row per ${metric.grain}). A column is null when it has no data.`),
+    };
+    // The collector client strips a leading slash; keep paths root-relative so a
+    // tool's `path` reads the same as it always has (`api/v1/...`).
+    const template = endpoint.path.replace(/^\//, "");
+    return {
+        name: metric.id,
+        title: metric.title,
+        description: describeMetric(metric),
+        inputSchema,
+        outputSchema,
+        buildRequest: (args) => {
+            let path = template;
+            for (const { placeholder, argName } of pathArgs) {
+                const raw = args[argName];
+                path = path.replace(`:${placeholder}`, encodeURIComponent(typeof raw === "string" ? raw : ""));
+            }
+            const params = {};
+            for (const filter of metric.filters)
+                params[filter] = toQueryValue(args[filter]);
+            return { path, params };
+        },
+    };
+}
+/**
+ * Generate the read-only tool catalog from the metric registry: one tool per
+ * registry entry that has a collector endpoint, in registry declaration order.
+ *
+ * Pure — it reads definitions only and never touches a collector — so the whole
+ * catalog is unit-testable without a live server.
+ */
+export function registryToTools(metrics = allMetrics()) {
+    const tools = [];
+    for (const metric of metrics) {
+        const tool = metricToTool(metric);
+        if (tool)
+            tools.push(tool);
+    }
+    return tools;
+}
+//# sourceMappingURL=registryTools.js.map

package/dist/registryTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registryTools.js","sourceRoot":"","sources":["../src/registryTools.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import type { z } from "zod";
 import type { QueryParams } from "./client.js";
 /** A resolved read request: the collector path and its query parameters. */
 export interface ReadToolRequest {
@@ -16,22 +16,46 @@ export interface ReadTool {
     title: string;
     description: string;
     inputSchema: z.ZodRawShape;
+    /**
+     * Zod raw shape describing what the tool **returns**, derived from the metric
+     * registry's `row` schema (ADR 0051 §1). It is always the single-key envelope
+     * `{ rows: Row[] }`: a single-object result (a session descriptor, a one-row
+     * summary) is reported as a one-element array so every tool has the same
+     * shape. Consumers that speak MCP register it as the tool's `outputSchema`
+     * and return matching `structuredContent`; consumers that do not can ignore
+     * it. Optional so a hand-built tool stays valid.
+     */
+    outputSchema?: z.ZodRawShape;
     buildRequest: (args: Record<string, unknown>) => ReadToolRequest;
 }
 /**
- * The catalog of read-only tools. Each wraps one documented collector query
- * endpoint (docs/integration.md §Query). There are intentionally **no**
- * ingestion, mutation, or raw per-session event tools — the surface is
- * aggregate, read-only, and privacy-preserving (ADR 0003 / ADR 0017).
+ * The catalog of read-only tools — one per metric in the `@uptimizr/db`
+ * **semantic metric registry** that the collector serves on an endpoint
+ * (ADR 0051 §1, design sketch §A.2). It is **generated**, not hand-written: a
+ * new aggregation reaches agents by getting a registry entry, and there is no
+ * second list to keep in step. See `registryTools.ts` for how each field is
+ * derived.
+ *
+ * Every tool wraps one documented collector query endpoint (docs/integration.md
+ * §Query). There are intentionally **no** ingestion, mutation, or raw
+ * per-session event tools — the surface is aggregate, read-only, and
+ * privacy-preserving (ADR 0003 / ADR 0017); the registry's two builder-less
+ * resource entries (`session_meta`, `scene_representation`) are coarse
+ * descriptors, never an event stream.
+ *
+ * The 20 tool names the hand-written catalog shipped are registry ids verbatim
+ * and their argument schemas are unchanged — `__tests__/shippedToolCompat.test.ts`
+ * pins that against a frozen fixture, so an MCP client written against the old
+ * catalog keeps working.
  */
 export declare const readTools: readonly ReadTool[];
 /**
  * Names of the **core** read tools — a small, single-step-friendly subset of
  * {@link readTools} for small local models (ADR 0050). A 4-bit 7–8B model folds
- * every tool schema into its function-calling system prompt, so sending all 20
- * overwhelms it and degrades selection even for simple questions. This subset
- * covers the most common single-metric questions (recent sessions, active
- * scenes, top meshes, FPS, event counts, event volume over time, and one
+ * every tool schema into its function-calling system prompt, so sending the
+ * whole catalog overwhelms it and degrades selection even for simple questions.
+ * This subset covers the most common single-metric questions (recent sessions,
+ * active scenes, top meshes, FPS, event counts, event volume over time, and one
  * view-direction heatmap).
  *
  * Plain string membership only — used to FILTER {@link readTools} below, never to
@@ -51,4 +75,15 @@ export type ReadToolSetKind = "core" | "full";
  * catalog. Both are views of the same single tool definitions.
  */
 export declare function selectReadTools(kind: ReadToolSetKind): readonly ReadTool[];
+/**
+ * Narrow the catalog to a caller-supplied set of tool names, preserving catalog
+ * order and identity. Unknown names are ignored, so a host app that pins a tool
+ * list cannot break when the registry renames or retires a metric — check the
+ * result's length if that matters to you.
+ *
+ * Use it when a model's context budget or a product decision calls for a
+ * deliberate subset (see {@link coreReadTools} for the built-in small-model one)
+ * rather than the full ~69-tool surface.
+ */
+export declare function filterReadTools(names: readonly string[]): readonly ReadTool[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,CAAC;CAClE;AAqDD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAwRxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAQjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,QAAQ,EAE5C,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,QAAQ,EAAE,CAE1E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC;IAC7B,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,CAAC;CAClE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAAsB,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAQjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,QAAQ,EAE5C,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,QAAQ,EAAE,CAE1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,QAAQ,EAAE,CAG7E"}

package/dist/tools.js

@@ -1,336 +1,32 @@
-import { z } from "zod";
-const num = (v) => (typeof v === "number" ? v : undefined);
-const str = (v) => (typeof v === "string" ? v : undefined);
-// Shared, reusable input fields (all optional unless a tool needs otherwise).
-const since = z.number().int().optional().describe("Start of the time range, epoch milliseconds.");
-const until = z.number().int().optional().describe("End of the time range, epoch milliseconds.");
-const bins = z.number().int().positive().max(500).optional().describe("Grid resolution per axis.");
-const limit = z.number().int().positive().max(1000).optional().describe("Maximum rows to return.");
-const scene = z.string().optional().describe("Restrict to one developer-assigned scene id.");
-const session = z.string().optional().describe("Scope the aggregate to a single session id.");
-const cellSize = z.number().positive().max(1000).optional().describe("Voxel size in world units.");
-const interval = z
-    .number()
-    .int()
-    .positive()
-    .optional()
-    .describe("Time-series bucket width, seconds.");
-const eventType = z
-    .string()
-    .optional()
-    .describe("Restrict to a single event type, e.g. pointer_click.");
-const source = z
-    .enum(["mouse", "touch", "stylus", "pen", "xr-controller", "hand", "gaze", "transient", "other"])
-    .optional()
-    .describe("Restrict a pointer/world heatmap to one input source.");
-const cameraMode = z
-    .enum(["viewer", "first-person"])
-    .optional()
-    .describe("Camera navigation mode to scope to: 'viewer' (orbit) or 'first-person' (walkable).");
-const rapidTurn = z
-    .number()
-    .nonnegative()
-    .max(Math.PI)
-    .optional()
-    .describe("Rapid-turn threshold in radians (0..π); view turns above this flag motion-sickness risk.");
-const steps = z
-    .string()
-    .min(1)
-    .describe("Funnel steps as a JSON-encoded array of ordered step predicates (ADR 0038). Required. " +
-    'Each step is `{ "type": <event_type>, ... }`; e.g. ' +
-    '`[{"type":"scene_change","to":"lobby"},{"type":"mesh_interaction","mesh":"buy"}]`.');
-/** Build the common `{ since, until }` range params from validated args. */
-function range(args) {
-    return { since: num(args.since), until: num(args.until) };
-}
+import { registryToTools } from "./registryTools.js";
 /**
- * The catalog of read-only tools. Each wraps one documented collector query
- * endpoint (docs/integration.md §Query). There are intentionally **no**
- * ingestion, mutation, or raw per-session event tools — the surface is
- * aggregate, read-only, and privacy-preserving (ADR 0003 / ADR 0017).
+ * The catalog of read-only tools — one per metric in the `@uptimizr/db`
+ * **semantic metric registry** that the collector serves on an endpoint
+ * (ADR 0051 §1, design sketch §A.2). It is **generated**, not hand-written: a
+ * new aggregation reaches agents by getting a registry entry, and there is no
+ * second list to keep in step. See `registryTools.ts` for how each field is
+ * derived.
+ *
+ * Every tool wraps one documented collector query endpoint (docs/integration.md
+ * §Query). There are intentionally **no** ingestion, mutation, or raw
+ * per-session event tools — the surface is aggregate, read-only, and
+ * privacy-preserving (ADR 0003 / ADR 0017); the registry's two builder-less
+ * resource entries (`session_meta`, `scene_representation`) are coarse
+ * descriptors, never an event stream.
+ *
+ * The 20 tool names the hand-written catalog shipped are registry ids verbatim
+ * and their argument schemas are unchanged — `__tests__/shippedToolCompat.test.ts`
+ * pins that against a frozen fixture, so an MCP client written against the old
+ * catalog keeps working.
  */
-export const readTools = [
-    {
-        name: "list_sessions",
-        title: "List recent sessions",
-        description: "Recent sessions with id, visitor, event count, and start/end times.",
-        inputSchema: { since, until, limit },
-        buildRequest: (args) => ({
-            path: "api/v1/sessions",
-            params: { ...range(args), limit: num(args.limit) },
-        }),
-    },
-    {
-        name: "pointer_heatmap",
-        title: "2D pointer heatmap",
-        description: "Binned 2D pointer-position heatmap (screen-normalized).",
-        inputSchema: { since, until, bins, scene, source, session },
-        buildRequest: (args) => ({
-            path: "api/v1/heatmaps/pointer",
-            params: {
-                ...range(args),
-                bins: num(args.bins),
-                scene: str(args.scene),
-                source: str(args.source),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "world_heatmap",
-        title: "3D world-space pointer heatmap",
-        description: "Voxelized world-space pointer heatmap.",
-        inputSchema: { since, until, cellSize, limit, scene, source },
-        buildRequest: (args) => ({
-            path: "api/v1/heatmaps/world",
-            params: {
-                ...range(args),
-                cellSize: num(args.cellSize),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                source: str(args.source),
-            },
-        }),
-    },
-    {
-        name: "camera_heatmap",
-        title: "View-direction heatmap",
-        description: "Camera view-direction distribution as spherical bins.",
-        inputSchema: { since, until, bins, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/heatmaps/camera",
-            params: {
-                ...range(args),
-                bins: num(args.bins),
-                scene: str(args.scene),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "click_rays",
-        title: "View-gated click rays",
-        description: "Clicks ASOF-joined to their nearest camera sample, per voxel and clicked mesh.",
-        inputSchema: { since, until, cellSize, limit, scene, source, session },
-        buildRequest: (args) => ({
-            path: "api/v1/heatmaps/click-rays",
-            params: {
-                ...range(args),
-                cellSize: num(args.cellSize),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                source: str(args.source),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "flow_links",
-        title: "Gaze→mesh flow links",
-        description: "Aggregate links from camera-direction bins to clicked meshes.",
-        inputSchema: { since, until, bins, limit, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/heatmaps/flow",
-            params: {
-                ...range(args),
-                bins: num(args.bins),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "top_meshes",
-        title: "Most-interacted meshes",
-        description: "Meshes ranked by interaction count.",
-        inputSchema: { since, until, limit, session },
-        buildRequest: (args) => ({
-            path: "api/v1/meshes/top",
-            params: { ...range(args), limit: num(args.limit), session: str(args.session) },
-        }),
-    },
-    {
-        name: "perf_summary",
-        title: "Rendering performance summary",
-        description: "Sample count and avg/min/p50 FPS over the range.",
-        inputSchema: { since, until, session },
-        buildRequest: (args) => ({
-            path: "api/v1/perf",
-            params: { ...range(args), session: str(args.session) },
-        }),
-    },
-    {
-        name: "list_scenes",
-        title: "List active scenes",
-        description: "Distinct developer-assigned scenes with activity.",
-        inputSchema: { since, until, limit },
-        buildRequest: (args) => ({
-            path: "api/v1/scenes",
-            params: { ...range(args), limit: num(args.limit) },
-        }),
-    },
-    {
-        name: "timeseries",
-        title: "Event-volume time series",
-        description: "Event-volume buckets over time, with average FPS per bucket.",
-        inputSchema: { since, until, interval, scene, type: eventType },
-        buildRequest: (args) => ({
-            path: "api/v1/timeseries",
-            params: {
-                ...range(args),
-                interval: num(args.interval),
-                scene: str(args.scene),
-                type: str(args.type),
-            },
-        }),
-    },
-    {
-        name: "event_counts",
-        title: "Per-event-type counts",
-        description: "Counts per event type over the range (scene-health panel).",
-        inputSchema: { since, until, scene },
-        buildRequest: (args) => ({
-            path: "api/v1/event-counts",
-            params: { ...range(args), scene: str(args.scene) },
-        }),
-    },
-    {
-        name: "session_meta",
-        title: "Session descriptor",
-        description: "Coarse descriptor for one session (device/scene/user). No raw event stream.",
-        inputSchema: { sessionId: z.string().min(1).describe("The session id to describe.") },
-        buildRequest: (args) => ({
-            path: `api/v1/sessions/${encodeURIComponent(str(args.sessionId) ?? "")}/meta`,
-            params: {},
-        }),
-    },
-    {
-        name: "scene_representation",
-        title: "Scene representation",
-        description: "Registered proxy geometry (bounds/meshes) for one scene, if any.",
-        inputSchema: { sceneId: z.string().min(1).describe("The scene id to fetch.") },
-        buildRequest: (args) => ({
-            path: `api/v1/scenes/${encodeURIComponent(str(args.sceneId) ?? "")}/representation`,
-            params: {},
-        }),
-    },
-    {
-        name: "funnel",
-        title: "Conversion funnel",
-        description: "Ordered, per-session conversion funnel (ADR 0038): how many sessions reach each " +
-            "caller-supplied step. Steps are a JSON array (see the `steps` argument).",
-        inputSchema: { since, until, scene, cameraMode, steps },
-        buildRequest: (args) => ({
-            path: "api/v1/funnel",
-            params: {
-                ...range(args),
-                scene: str(args.scene),
-                cameraMode: str(args.cameraMode),
-                steps: str(args.steps),
-            },
-        }),
-    },
-    {
-        name: "aggregate_paths",
-        title: "Aggregate desire-line paths",
-        description: "Crowd-level movement routes (ADR 0037): every session's camera path binned onto the " +
-            "ground grid and returned as ordered, session-keyed points for an overlaid route map.",
-        inputSchema: { since, until, cellSize, limit, scene, cameraMode },
-        buildRequest: (args) => ({
-            path: "api/v1/paths",
-            params: {
-                ...range(args),
-                cellSize: num(args.cellSize),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                cameraMode: str(args.cameraMode),
-            },
-        }),
-    },
-    {
-        name: "rendering_technology",
-        title: "Rendering-technology breakdown",
-        description: "Rendering-technology mix from session_start.graphics (ADR 0046): session count per " +
-            "(api, backend, api_version, shading_language) — WebGPU vs WebGL2 and shading language.",
-        inputSchema: { since, until, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/rendering-technology",
-            params: { ...range(args), scene: str(args.scene), session: str(args.session) },
-        }),
-    },
-    {
-        name: "xr_rotation",
-        title: "XR head-rotation rate",
-        description: "XR head/view rotation rate (ADR 0048), a motion-sickness proxy: per-session rapid-turn " +
-            "counts over the camera pose stream.",
-        inputSchema: { since, until, rapidTurn, limit, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/xr/rotation",
-            params: {
-                ...range(args),
-                rapidTurn: num(args.rapidTurn),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "xr_sources",
-        title: "XR input-source usage",
-        description: "XR input-source split (ADR 0048): hand vs. controller vs. gaze usage.",
-        inputSchema: { since, until, limit, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/xr/sources",
-            params: {
-                ...range(args),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "xr_abandonment",
-        title: "XR session abandonment",
-        description: "XR session abandonment (ADR 0048): per XR session, its time bounds and event/interaction " +
-            "counts; a short span signals headset drop-off.",
-        inputSchema: { since, until, limit, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/xr/abandonment",
-            params: {
-                ...range(args),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                session: str(args.session),
-            },
-        }),
-    },
-    {
-        name: "xr_locomotion",
-        title: "XR locomotion & comfort",
-        description: "XR locomotion & comfort (ADR 0048): per XR session, its locomotion-style mix " +
-            "(fly / navigate / teleport + duration) and wall-clock span — a discomfort proxy.",
-        inputSchema: { since, until, limit, scene, session },
-        buildRequest: (args) => ({
-            path: "api/v1/xr/locomotion",
-            params: {
-                ...range(args),
-                limit: num(args.limit),
-                scene: str(args.scene),
-                session: str(args.session),
-            },
-        }),
-    },
-];
+export const readTools = registryToTools();
 /**
  * Names of the **core** read tools — a small, single-step-friendly subset of
  * {@link readTools} for small local models (ADR 0050). A 4-bit 7–8B model folds
- * every tool schema into its function-calling system prompt, so sending all 20
- * overwhelms it and degrades selection even for simple questions. This subset
- * covers the most common single-metric questions (recent sessions, active
- * scenes, top meshes, FPS, event counts, event volume over time, and one
+ * every tool schema into its function-calling system prompt, so sending the
+ * whole catalog overwhelms it and degrades selection even for simple questions.
+ * This subset covers the most common single-metric questions (recent sessions,
+ * active scenes, top meshes, FPS, event counts, event volume over time, and one
  * view-direction heatmap).
  *
  * Plain string membership only — used to FILTER {@link readTools} below, never to
@@ -358,4 +54,18 @@ export const coreReadTools = readTools.filter((tool) => CORE_READ_TOOL_NAMES.inc
 export function selectReadTools(kind) {
     return kind === "core" ? coreReadTools : readTools;
 }
+/**
+ * Narrow the catalog to a caller-supplied set of tool names, preserving catalog
+ * order and identity. Unknown names are ignored, so a host app that pins a tool
+ * list cannot break when the registry renames or retires a metric — check the
+ * result's length if that matters to you.
+ *
+ * Use it when a model's context budget or a product decision calls for a
+ * deliberate subset (see {@link coreReadTools} for the built-in small-model one)
+ * rather than the full ~69-tool surface.
+ */
+export function filterReadTools(names) {
+    const wanted = new Set(names);
+    return readTools.filter((tool) => wanted.has(tool.name));
+}
 //# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAgCrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAwB,eAAe,EAAE,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,eAAe;IACf,aAAa;IACb,YAAY;IACZ,cAAc;IACd,cAAc;IACd,YAAY;IACZ,gBAAgB;CACjB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAwB,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAC1E,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CACzC,CAAC;AAKF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAqB;IACnD,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,KAAwB;IACtD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/llms.txt

@@ -11,9 +11,36 @@
 - [Integration & API reference](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md): the underlying query endpoints.
 - [Architecture Decision Records](https://github.com/RaananW/Uptimizr/tree/main/docs/adr): in-browser assistant (0050), privacy model (0003), thin backends (0005), consumer-facing agents (0017).
 
+## Tools (read-only)
+
+<!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this list -->
+
+`list_sessions`, `session_meta`, `scene_representation`, `list_scenes`, `timeseries`,
+`event_counts`, `pointer_heatmap`, `mesh_uv_heatmap`, `world_heatmap`, `world_heatmap_stats`,
+`gaze_heatmap`, `gaze_heatmap_stats`, `camera_heatmap`, `view_coverage_histogram`,
+`position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
+`click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
+`mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
+`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
+`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
+`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
+`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
+`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
+`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
+`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
+`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+
+<!-- generated:registry-tool-names:end -->
+
 ## Key exports
 
-- `readTools` — the read-only tool catalog (one entry per query endpoint).
+- `readTools` — the read-only tool catalog (one entry per query endpoint), generated from the
+  `@uptimizr/metrics` metric registry: 69 tools, each with an input schema, an output schema and the
+  metric's interpretation notes and caveats in its description (ADR 0051).
+- `coreReadTools` / `selectReadTools(kind)` / `filterReadTools(names)` — narrowed views of the
+  catalog for models that cannot carry every tool schema.
+- `registryToTools(metrics?)` — generate the catalog from metric-registry definitions.
 - `createCollectorClient(config)` — the thin GET-only collector client.
 - `runAgent(options)` — the headless tool-calling loop (LLM ↔ tools ↔ collector).
 - `toToolSchemas(tools?)` — convert catalog tools to JSON-Schema tool descriptors for an LLM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/agent-core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Framework-agnostic, browser-safe core for Uptimizr analytics agents — the single read-only tool catalog over the collector query API, a headless LLM provider-adapter interface, and the tool-calling loop.",
   "keywords": [
     "uptimizr",
@@ -58,7 +58,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "zod": "^4.5.4"
+    "zod": "^4.5.4",
+    "@uptimizr/metrics": "0.1.0"
   },
   "peerDependencies": {
     "@mlc-ai/web-llm": "^0.2.0"
@@ -70,6 +71,7 @@
   },
   "devDependencies": {
     "@mlc-ai/web-llm": "^0.2.84",
+    "esbuild": "^0.28.2",
     "vitest": "^4.1.11"
   },
   "engines": {