@uptimizr/agent-core 1.0.1 → 1.1.1

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,86 @@ 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.
+
+## Result formats (`format`)
+
+Every **aggregate** tool in the catalog declares a `format` argument — `full | table | summary`.
+It picks the envelope the rows arrive in and filters nothing (ADR 0051 §2). The collector's
+`preSerialization` hook does the shaping, so the tool definitions stay pure `buildRequest` functions.
+
+| `format`  | Returns                                                                                                                                                                                         | Use it when                                                        |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `summary` | A bounded digest — `ranked` top rows, a `series` trend, merged spatial `clusters` or a single `record` — with shares, a sample size, the metric's `caveats` and a templated `reading` sentence. | **The default choice when a model will read the result.**          |
+| `table`   | `{ meta, rows }`: the rows plus metric, range, applied filters, sample size, row count, a truncation flag and the registry's limits.                                                            | You need every row _and_ the context to judge how far to trust it. |
+| `full`    | The bare rows, unchanged.                                                                                                                                                                       | You are post-processing the rows yourself. Today's default.        |
+
+- `summary` is capped at the metric's `limits.maxSummaryRows`, which is what makes a heatmap, voxel
+  cloud or long leaderboard safe to hand a model at all. This matters most for the **local** backend:
+  a 4-bit 7–8B model's whole context can be filled by one `full` heatmap.
+- `reading` and `caveats` are templated from the registry's column semantics by pure code — no model
+  — so identical rows always produce identical words. Quote them rather than re-deriving them.
+- Shares appear only where the measure can honestly be summed; an FPS or ratio metric reports
+  `total: null` and no shares. Cluster coordinates are grid indices — multiply by the effective
+  `cellSize` for world space.
+- `session_meta` and `scene_representation` are single stored records, not aggregations, and declare
+  no `format`.
+- `full` remains the generated catalog's default so that existing consumers (the dashboard) are
+  unaffected. Pass `format: "summary"` explicitly from an agent path; the default flip is a separate,
+  documented change.
+
 ## 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"}