@uptimizr/agent-core 1.0.1 → 1.1.1

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"}