@uptimizr/agent-core 1.0.1 → 1.1.1

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,57 @@
 - [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 -->
+
+## Result formats (`format`)
+
+Every aggregate tool declares a `format` argument — the envelope its rows arrive in, not a filter
+(ADR 0051 §2).
+
+- `summary` — **prefer this whenever a model reads the result.** 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. Capped at the metric's
+  `limits.maxSummaryRows`, so a 500-bin heatmap costs the same as a 5-bin one — which is what keeps
+  one heatmap from filling a small local model's whole context.
+- `table` — `{ meta, rows }`: every row plus the metric, range, applied filters, sample size, row
+  count, a truncation flag and the registry limits.
+- `full` — the bare rows. Today's default, so existing consumers such as the dashboard are
+  unaffected; pass `format` explicitly from an agent path.
+
+`reading` and `caveats` are templated by pure code, never a model, so identical rows always produce
+identical words. 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 stored records,
+not aggregations, and declare no `format`.
+
 ## 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.1",
   "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": {