@uptimizr/agent-core 1.1.0 → 1.2.0

package/dist/skills.js

@@ -0,0 +1,144 @@
+/**
+ * **Packaged agent skills** — the canned investigations a client can run against
+ * a project's analytics (ADR 0050 §7, ADR 0051 §6–§7, design sketch §G.4).
+ *
+ * A skill is a named methodology: a short title, the tools its method relies on,
+ * the capabilities an API key needs to follow it, the arguments it accepts, and
+ * a `render` that turns those arguments into the single user turn that steers an
+ * agent. No data is fetched here and no model is called — a skill is text plus
+ * metadata, so the same definition serves every consumer:
+ *
+ * - `@uptimizr/mcp` registers each one as an MCP **prompt template**
+ *   (`prompts/list` → `prompts/get`) and lists them on `uptimizr://skills`.
+ * - `uptimizr agent report --skill <name>` in the collector CLI seeds its
+ *   headless `runAgent` transcript with the rendered text (ADR 0051 §6, design
+ *   sketch §F.4).
+ * - `@uptimizr/agent-eval` asks the bank the very questions a real client sends.
+ * - The in-browser assistant offers them as starter prompts.
+ *
+ * ### Where the text lives
+ *
+ * Not here. Each skill is an **Agent Skills file** —
+ * `oss/packages/agent-core/skills/<name>/SKILL.md` — with YAML frontmatter
+ * (`name`, `title`, `description`, `tools`, `capabilities`, `args`) and a
+ * Markdown body holding the methodology. Those files are the source of truth:
+ * they ship in the `@uptimizr/agent-core` and `@uptimizr/mcp` tarballs, and a
+ * user can lift one straight into their own agent.
+ *
+ * They cannot be read at runtime, because this package is browser-safe and must
+ * not touch `node:fs`. So `scripts/gen-agent-skills.mjs` compiles them into
+ * {@link GENERATED_AGENT_SKILLS} (`skills.generated.ts`) and this module turns
+ * that data into {@link AgentSkill} values. Reword a SKILL.md, run
+ * `pnpm gen:skills`, and every consumer's wording changes with it, with nothing
+ * to keep in step. `pnpm gen:skills:check` is the CI gate that fails on a
+ * hand-edited generated file.
+ *
+ * ### Body placeholders
+ *
+ * A body is a template with a deliberately tiny vocabulary — enough to scope a
+ * methodology, not a second templating language:
+ *
+ * - `{{scene}}` — the scene id, or the empty string.
+ * - `{{scope}}` — `scene "lobby"`, or `the project (all scenes)`.
+ * - `{{range}}` — the window, in words, defaulting to the argument's `default`.
+ * - `{{#name}}…{{/name}}` / `{{^name}}…{{/name}}` — a section kept only when the
+ *   argument is, or is not, present. Sections may span lines.
+ */
+import { GENERATED_AGENT_SKILLS, } from "./skills.generated.js";
+/** `{{#name}}…{{/name}}` and `{{^name}}…{{/name}}`, possibly spanning lines. */
+const SECTION = /\{\{([#^])([a-z][a-z0-9_]*)\}\}([\s\S]*?)\{\{\/\2\}\}/g;
+/** `{{name}}`. */
+const VARIABLE = /\{\{([a-z][a-z0-9_]*)\}\}/g;
+/** `scene "lobby"` when a scene was given, otherwise the whole project. */
+function scopeFor(scene) {
+    return scene ? `scene "${scene}"` : "the project (all scenes)";
+}
+/**
+ * Substitute a skill's arguments into its body.
+ *
+ * Sections are resolved before variables so a `{{scene}}` inside a dropped
+ * `{{#scene}}` block never renders, and the trailing whitespace a dropped
+ * section can leave behind is stripped per line — otherwise a scene-less render
+ * would carry invisible spaces the authored file never had.
+ */
+function renderBody(body, values) {
+    const resolved = body
+        .replace(SECTION, (_match, kind, name, inner) => (kind === "#") === Boolean(values[name]) ? inner : "")
+        .replace(VARIABLE, (_match, name) => values[name] ?? "");
+    return resolved.replace(/[ \t]+$/gm, "");
+}
+/** Turn one compiled SKILL.md into the renderable skill consumers use. */
+function toAgentSkill(source) {
+    return {
+        id: source.id,
+        name: source.name,
+        title: source.title,
+        description: source.description,
+        tools: source.tools,
+        capabilities: source.capabilities,
+        args: source.args,
+        render(args = {}) {
+            const values = {};
+            for (const arg of source.args) {
+                values[arg.name] = args[arg.name]?.trim() || arg.default || "";
+            }
+            // `scope` is derived rather than declared: a skill that takes a scene
+            // always wants to open with "scene X" or "the whole project", and spelling
+            // that out in five frontmatter blocks would invite five phrasings of it.
+            values.scope = scopeFor(values.scene);
+            return renderBody(source.body, values);
+        },
+    };
+}
+/**
+ * The packaged skills, in catalog order. The text of each is the contract: it is
+ * what an MCP client shows its user and what the report CLI sends as the user
+ * turn, so changing a SKILL.md changes every consumer at once (which is the
+ * point).
+ */
+export const AGENT_SKILLS = GENERATED_AGENT_SKILLS.map(toAgentSkill);
+/** The packaged skill names, in catalog order. */
+export const AGENT_SKILL_NAMES = AGENT_SKILLS.map((skill) => skill.name);
+/**
+ * Names that used to identify a skill and still resolve to one.
+ *
+ * `xr_comfort_review` shipped as an MCP prompt and a `--skill` value before the
+ * methodology was packaged and widened into `xr_comfort_audit` (#316). An MCP
+ * client's saved prompt reference and an operator's cron line both name a skill
+ * by string, so the old name keeps working rather than failing on the next
+ * scheduled run.
+ */
+const SKILL_ALIASES = {
+    xr_comfort_review: "xr_comfort_audit",
+};
+/**
+ * Resolve a skill by name, or `undefined` when nothing answers to it.
+ *
+ * The one lookup every consumer goes through, and deliberately forgiving about
+ * spelling: a skill's directory is kebab-case (`xr-comfort-audit`) and its id is
+ * snake_case (`xr_comfort_audit`), so both resolve, as do the historical names
+ * in {@link SKILL_ALIASES}.
+ */
+export function getAgentSkill(name) {
+    const normalized = name.trim().toLowerCase().replace(/-/g, "_");
+    const resolved = SKILL_ALIASES[normalized] ?? normalized;
+    return AGENT_SKILLS.find((skill) => skill.name === resolved);
+}
+/**
+ * Render one skill's user turn, throwing on an unknown name (a typo should fail
+ * loudly rather than silently produce an empty prompt) or on a missing required
+ * argument.
+ */
+export function renderAgentSkill(name, args = {}) {
+    const skill = getAgentSkill(name);
+    if (!skill) {
+        throw new Error(`Unknown skill "${name}". Known skills: ${AGENT_SKILL_NAMES.join(", ")}.`);
+    }
+    for (const arg of skill.args) {
+        if (arg.required && !args[arg.name]) {
+            throw new Error(`Skill "${name}" requires the "${arg.name}" argument.`);
+        }
+    }
+    return skill.render(args);
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

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

package/dist/tools.d.ts

@@ -17,15 +17,33 @@ export interface ReadTool {
     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.
+     * Zod schema describing what the tool **returns**, derived from the metric
+     * registry's `row` schema (ADR 0051 §1) and the `format` result envelope
+     * (ADR 0051 §2).
+     *
+     * It is a single **object** schema, because that is what an MCP
+     * `outputSchema` must be. For a metric that honours `format` it is
+     * `structuredEnvelopeSchema(row)`: the merged, every-key-optional object form
+     * of the three envelopes — `{ rows }` for `full`, `{ meta, rows }` for
+     * `table`, the `kind`-tagged digest for `summary` — so a client validating
+     * `structuredContent` accepts whichever one the collector returns (#350). The
+     * two resource metrics, which declare no `format`, keep the single-key
+     * `{ rows: Row[] }` envelope: a single-object result (a session descriptor) 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`;
+     * consumers that do not can ignore it. Optional so a hand-built tool stays
+     * valid.
      */
-    outputSchema?: z.ZodRawShape;
+    outputSchema?: z.ZodType;
+    /**
+     * Turn the collector's response into the object {@link outputSchema}
+     * describes. Omitted by every generated per-metric tool, whose result is
+     * always a list of rows and is therefore wrapped as `{ rows }` by the
+     * consumer. The `query` tool sets it because its shape is chosen by the
+     * request's `format`, so only the tool knows how its answer is keyed.
+     */
+    structuredContent?: (data: unknown) => Record<string, unknown>;
     buildRequest: (args: Record<string, unknown>) => ReadToolRequest;
 }
 /**
@@ -43,12 +61,41 @@ export interface ReadTool {
  * resource entries (`session_meta`, `scene_representation`) are coarse
  * descriptors, never an event stream.
  *
+ * This is the **`query`** surface: every metric whose endpoint needs nothing
+ * more than the ordinary read capability. Metrics that require more are not
+ * silently mixed in — see {@link rawTools}.
+ *
  * 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.
+ *
+ * One tool is **not** per-metric: `query` (ADR 0051 §3), appended last. Its
+ * input is the query DSL, so it can run any metric with any filter that metric
+ * declares — what the per-metric tools are for discovery, `query` is for
+ * anything that needs a filter the canned tool does not expose. See
+ * `queryTool.ts`.
  */
 export declare const readTools: readonly ReadTool[];
+/**
+ * The **`query:raw`** tools: generated from exactly the registry metrics whose
+ * endpoint declares that capability (ADR 0051 §7, design sketch §G.2). Today
+ * that is `session_narrative`, the compacted account of one session.
+ *
+ * Kept as a separate catalog rather than folded into {@link readTools} because
+ * the capability is not a property of the *agent*, it is a property of the **key
+ * the agent was handed**. A host registers these tools only after confirming the
+ * key holds `query:raw` — `@uptimizr/mcp`'s `createMcpServer(client, {
+ * capabilities })` does exactly that, and `GET /api/v1/whoami` is where the
+ * capability set comes from. Registering them unconditionally would advertise a
+ * tool that answers 403, which is worse for a model than not having it: it burns
+ * a turn and invites a retry.
+ *
+ * The collector refuses these endpoints unless it *also* has
+ * `ENABLE_RAW_SESSION_RETENTION` enabled, so holding the capability is necessary
+ * but never sufficient (ADR 0003).
+ */
+export declare const rawTools: 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

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/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;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/D,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,CAAC;CAClE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAQxC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,QAAQ,EAEvC,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;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,QAAQ,EAAE,CAG7E"}

package/dist/tools.js

@@ -1,4 +1,7 @@
+import { allMetrics, metricCapability } from "@uptimizr/metrics";
 import { registryToTools } from "./registryTools.js";
+import { queryTool } from "./queryTool.js";
+import { NON_REGISTRY_READ_TOOLS } from "./nonRegistryTools.js";
 /**
  * The catalog of read-only tools — one per metric in the `@uptimizr/db`
  * **semantic metric registry** that the collector serves on an endpoint
@@ -14,12 +17,49 @@ import { registryToTools } from "./registryTools.js";
  * resource entries (`session_meta`, `scene_representation`) are coarse
  * descriptors, never an event stream.
  *
+ * This is the **`query`** surface: every metric whose endpoint needs nothing
+ * more than the ordinary read capability. Metrics that require more are not
+ * silently mixed in — see {@link rawTools}.
+ *
  * 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.
+ *
+ * One tool is **not** per-metric: `query` (ADR 0051 §3), appended last. Its
+ * input is the query DSL, so it can run any metric with any filter that metric
+ * declares — what the per-metric tools are for discovery, `query` is for
+ * anything that needs a filter the canned tool does not expose. See
+ * `queryTool.ts`.
+ */
+export const readTools = [
+    ...registryToTools(allMetrics().filter((metric) => metricCapability(metric) === "query")),
+    // The one deliberate exception to "generated, not hand-written": collector
+    // reads that are configuration rather than measurements and so have no
+    // registry entry to generate from (#311). See `nonRegistryTools.ts` for why
+    // inventing a registry entry for them would be worse.
+    ...NON_REGISTRY_READ_TOOLS,
+    queryTool,
+];
+/**
+ * The **`query:raw`** tools: generated from exactly the registry metrics whose
+ * endpoint declares that capability (ADR 0051 §7, design sketch §G.2). Today
+ * that is `session_narrative`, the compacted account of one session.
+ *
+ * Kept as a separate catalog rather than folded into {@link readTools} because
+ * the capability is not a property of the *agent*, it is a property of the **key
+ * the agent was handed**. A host registers these tools only after confirming the
+ * key holds `query:raw` — `@uptimizr/mcp`'s `createMcpServer(client, {
+ * capabilities })` does exactly that, and `GET /api/v1/whoami` is where the
+ * capability set comes from. Registering them unconditionally would advertise a
+ * tool that answers 403, which is worse for a model than not having it: it burns
+ * a turn and invites a retry.
+ *
+ * The collector refuses these endpoints unless it *also* has
+ * `ENABLE_RAW_SESSION_RETENTION` enabled, so holding the capability is necessary
+ * but never sufficient (ADR 0003).
  */
-export const readTools = registryToTools();
+export const rawTools = registryToTools(allMetrics().filter((metric) => metricCapability(metric) === "query:raw"));
 /**
  * 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

package/dist/tools.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAkDhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,SAAS,GAAwB;IAC5C,GAAG,eAAe,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC;IACzF,2EAA2E;IAC3E,uEAAuE;IACvE,4EAA4E;IAC5E,sDAAsD;IACtD,GAAG,uBAAuB;IAC1B,SAAS;CACV,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAwB,eAAe,CAC1D,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC,CAC1E,CAAC;AAEF;;;;;;;;;;;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/dist/writeTools.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import type { CollectorClient } from "./client.js";
+/**
+ * The **metadata write tools** (#310, ADR 0051 §5; #315, §7): `annotate`,
+ * `define_term`, `save_analysis`, `pin_panel` and `unpin_panel`, plus the four
+ * reads that make them usable (`list_annotations`, `list_glossary`,
+ * `list_analyses`, `list_panels`).
+ *
+ * They are a deliberately separate export from `readTools`, not an addition to
+ * it, for one reason: ADR 0017's read-only stance must stay **inspectable**. A
+ * reader who wants to know whether an integration can change anything looks at
+ * which of the two catalogs it registers, and `readTools` remains exactly what
+ * its name says.
+ *
+ * What they can and cannot touch:
+ *
+ * - They write **metadata only** — notes, definitions, saved questions. No tool
+ *   here can write, alter or delete an analytics event; events stay read-only
+ *   (ADR 0051 §9) and no ingestion path exists in this package at all.
+ * - Every one of them needs an API key holding the `annotate` capability. The
+ *   collector enforces that (`403` without it); the MCP server checks it once at
+ *   start-up so an agent is never offered a tool its key cannot use.
+ * - Every call is recorded in the project's agent audit log, and the stored row
+ *   records that an agent — not a person — wrote it.
+ *
+ * Each definition is pure data plus an `execute` that calls one collector
+ * endpoint, so they are unit-testable without a live collector, exactly like the
+ * generated read tools.
+ */
+/** One metadata write (or metadata read) exposed as an agent tool. */
+export interface WriteTool {
+    name: string;
+    title: string;
+    description: string;
+    /** Zod raw shape the MCP runtime validates arguments against. */
+    inputSchema: z.ZodRawShape;
+    /** Whether this tool changes stored state (all three writers do; the lists do not). */
+    mutates: boolean;
+    /** Call the collector with validated arguments and return its JSON. */
+    execute: (client: CollectorClient, args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Thrown when a write tool is handed a client with no write transport — a
+ * read-only `CollectorClient` built by hand, for instance. A clear error beats
+ * `client.post is not a function`.
+ */
+export declare class WriteNotSupportedError extends Error {
+    constructor(method: string);
+}
+export declare const annotateTool: WriteTool;
+export declare const defineTermTool: WriteTool;
+export declare const saveAnalysisTool: WriteTool;
+export declare const listAnnotationsTool: WriteTool;
+export declare const listGlossaryTool: WriteTool;
+export declare const listAnalysesTool: WriteTool;
+export declare const pinPanelTool: WriteTool;
+export declare const listPanelsTool: WriteTool;
+export declare const unpinPanelTool: WriteTool;
+/**
+ * The metadata tool catalog. Registered **only** when the calling key holds the
+ * `annotate` capability — including the read tools, which are listed here
+ * rather than in `readTools` so the whole metadata surface appears and
+ * disappears as one coherent feature.
+ */
+export declare const writeTools: readonly WriteTool[];
+/** The tools that actually change stored state. */
+export declare const mutatingWriteTools: readonly WriteTool[];
+//# sourceMappingURL=writeTools.d.ts.map

package/dist/writeTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeTools.d.ts","sourceRoot":"","sources":["../src/writeTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvF;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,MAAM,EAAE,MAAM;CAM3B;AAuBD,eAAO,MAAM,YAAY,EAAE,SA2C1B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAsB5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SA4B9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,SAqBjC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAS9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAS9B,CAAC;AAWF,eAAO,MAAM,YAAY,EAAE,SA6D1B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAY5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAe5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAU1C,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,EAAE,SAAS,SAAS,EAA8C,CAAC"}

package/dist/writeTools.js

@@ -0,0 +1,256 @@
+import { z } from "zod";
+import { LIMITS } from "@uptimizr/schema";
+/**
+ * Thrown when a write tool is handed a client with no write transport — a
+ * read-only `CollectorClient` built by hand, for instance. A clear error beats
+ * `client.post is not a function`.
+ */
+export class WriteNotSupportedError extends Error {
+    constructor(method) {
+        super(`This collector client is read-only: it has no \`${method}\` method, so metadata write tools cannot be used with it.`);
+        this.name = "WriteNotSupportedError";
+    }
+}
+function requirePost(client) {
+    if (!client.post)
+        throw new WriteNotSupportedError("post");
+    return client.post.bind(client);
+}
+function requirePut(client) {
+    if (!client.put)
+        throw new WriteNotSupportedError("put");
+    return client.put.bind(client);
+}
+/** Drop `undefined` entries so an optional argument is simply absent on the wire. */
+function compact(body) {
+    return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined));
+}
+const targetKind = z
+    .enum(["project", "scene", "mesh", "region", "metric", "window"])
+    .describe("What the note is about. `scene`/`mesh`/`region`/`metric` need a `targetId`; `window` needs `since`.");
+export const annotateTool = {
+    name: "annotate",
+    title: "Annotate something",
+    description: "Leave a note on the project, a scene, a mesh, a region, a metric, or a period of time — what changed, what you concluded, what a future reader should know before trusting a number. Notes are shown on dashboard time axes and read back by agents. Use it when you have found something worth remembering, not for scratch state.",
+    inputSchema: {
+        targetKind,
+        targetId: z
+            .string()
+            .min(1)
+            .max(LIMITS.maxAnnotationTargetIdLength)
+            .optional()
+            .describe("The scene id, mesh name, region id or metric id the note is about."),
+        since: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Start of the period the note applies to, epoch milliseconds."),
+        until: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("End of the period the note applies to, epoch milliseconds."),
+        text: z
+            .string()
+            .min(1)
+            .max(LIMITS.maxAnnotationTextLength)
+            .describe("The note itself, in plain words."),
+    },
+    mutates: true,
+    execute: async (client, args) => requirePost(client)("/api/v1/annotations", compact({
+        targetKind: args.targetKind,
+        targetId: args.targetId,
+        since: args.since,
+        until: args.until,
+        text: args.text,
+    })),
+};
+export const defineTermTool = {
+    name: "define_term",
+    title: "Define a term",
+    description: "Record what a name means in this project — a mesh name, a scene id, a custom event, an in-house abbreviation. Writing it down once saves every later reader (and every later agent) from guessing. Defining a term again replaces its meaning.",
+    inputSchema: {
+        term: z
+            .string()
+            .min(1)
+            .max(LIMITS.maxGlossaryTermLength)
+            .describe("The name being defined, exactly as it appears in the data."),
+        meaning: z
+            .string()
+            .min(1)
+            .max(LIMITS.maxGlossaryMeaningLength)
+            .describe("What it means in this project."),
+    },
+    mutates: true,
+    execute: async (client, args) => requirePut(client)(`/api/v1/glossary/${encodeURIComponent(String(args.term))}`, {
+        meaning: args.meaning,
+    }),
+};
+export const saveAnalysisTool = {
+    name: "save_analysis",
+    title: "Save an analysis",
+    description: "Store a question worth re-asking together with what you concluded from it: a title someone will recognise in a list, the query that produced the answer, and the finding in words. Use it at the end of an investigation, not for every intermediate query.",
+    inputSchema: {
+        title: z
+            .string()
+            .min(1)
+            .max(LIMITS.maxSavedAnalysisTitleLength)
+            .describe("Short human title, e.g. 'Lobby FPS after the lighting change'."),
+        query: z
+            .record(z.string(), z.unknown())
+            .describe("The question as a JSON object — the endpoint and filters you used. Stored as-is; the collector does not interpret it."),
+        conclusion: z
+            .string()
+            .max(LIMITS.maxSavedAnalysisConclusionLength)
+            .optional()
+            .describe("What the numbers showed, and how far to trust it."),
+    },
+    mutates: true,
+    execute: async (client, args) => requirePost(client)("/api/v1/analyses", compact({ title: args.title, query: args.query, conclusion: args.conclusion })),
+};
+export const listAnnotationsTool = {
+    name: "list_annotations",
+    title: "Read the project's annotations",
+    description: "The notes people and agents have already left, newest first. Read them before answering a question about a change or a spike — someone may already have explained it. `since`/`until` select notes whose period overlaps the window.",
+    inputSchema: {
+        targetKind: targetKind.optional(),
+        targetId: z.string().min(1).max(LIMITS.maxAnnotationTargetIdLength).optional(),
+        since: z.number().int().nonnegative().optional(),
+        until: z.number().int().nonnegative().optional(),
+        limit: z.number().int().positive().max(500).optional(),
+    },
+    mutates: false,
+    execute: async (client, args) => client.get("/api/v1/annotations", {
+        targetKind: args.targetKind,
+        targetId: args.targetId,
+        since: args.since,
+        until: args.until,
+        limit: args.limit,
+    }),
+};
+export const listGlossaryTool = {
+    name: "list_glossary",
+    title: "Read the project's glossary",
+    description: "What this project's names mean. Read it before interpreting mesh names, scene ids or custom events — the team's vocabulary is rarely self-explanatory.",
+    inputSchema: { limit: z.number().int().positive().max(500).optional() },
+    mutates: false,
+    execute: async (client, args) => client.get("/api/v1/glossary", { limit: args.limit }),
+};
+export const listAnalysesTool = {
+    name: "list_analyses",
+    title: "Read the project's saved analyses",
+    description: "Questions this project has asked before and what was concluded, newest first. Check here before re-deriving an answer from scratch.",
+    inputSchema: { limit: z.number().int().positive().max(500).optional() },
+    mutates: false,
+    execute: async (client, args) => client.get("/api/v1/analyses", { limit: args.limit }),
+};
+// --- Declarative panel specs (#315, ADR 0051 §7 / sketch §G.3) -------------
+//
+// The most durable thing an agent can leave behind: not a note *about* an
+// answer, but the question itself, on the dashboard, re-asked every time
+// somebody opens it. And still metadata — the spec is a closed document (a
+// metric id, a chart name, some column names) that the dashboard renders with
+// panels it already ships. No module is loaded and nothing is evaluated, so
+// pinning a panel does not widen the dashboard's trust boundary (ADR 0041).
+export const pinPanelTool = {
+    name: "pin_panel",
+    title: "Pin an answer to the dashboard as a panel",
+    description: "Keep a question on the project's dashboard, where it will be re-asked and redrawn every " +
+        "time somebody opens it. Pass the same `query` document you ran with the `query` tool, but " +
+        'with `range` set to "inherit" so the panel follows the dashboard\'s own time filter instead ' +
+        "of freezing the window you happened to ask in. Pick a `chart` the metric's grain can " +
+        "actually support — `line`/`area` need a time-bucketed metric, `heatmap2d` a binned one, " +
+        "`world3d` a voxelised one, `stat` a single-record one, `bar` a ranking, `table` anything — " +
+        "or the collector refuses the spec and names the charts that would have worked. Put your " +
+        "one-line reading in `note`: it becomes the panel's subtitle, and it is the part a person " +
+        "reads a week later. Use this when an answer is worth watching, not for a one-off lookup.",
+    inputSchema: {
+        title: z
+            .string()
+            .min(1)
+            .max(LIMITS.maxPanelSpecTitleLength)
+            .describe("What the panel is called in the grid, e.g. 'Meshes people actually touch'."),
+        query: z
+            .record(z.string(), z.unknown())
+            .describe('A `queryV1` document — the same shape the `query` tool takes — with `range` set to "inherit", or to an explicit `{since, until}` to pin one period.'),
+        chart: z
+            .enum(["stat", "table", "bar", "line", "area", "heatmap2d", "world3d"])
+            .describe("How to draw the result. Must suit the metric's grain."),
+        encoding: z
+            .object({
+            x: z.string().max(LIMITS.maxPanelEncodingColumnLength).optional(),
+            y: z.string().max(LIMITS.maxPanelEncodingColumnLength).optional(),
+            series: z.string().max(LIMITS.maxPanelEncodingColumnLength).optional(),
+        })
+            .optional()
+            .describe("Which result column feeds which channel. Omit to use the metric's own label/axis and measure columns."),
+        span: z
+            .union([z.literal(1), z.literal(2)])
+            .optional()
+            .describe("Grid width: 1 (half) or 2 (full). Defaults to 1."),
+        note: z
+            .string()
+            .max(LIMITS.maxPanelSpecNoteLength)
+            .optional()
+            .describe("Your one-line reading of the result. Shown as the panel's subtitle."),
+    },
+    mutates: true,
+    execute: async (client, args) => requirePost(client)("/api/v1/panels", compact({
+        v: 1,
+        title: args.title,
+        query: args.query,
+        chart: args.chart,
+        encoding: args.encoding,
+        span: args.span,
+        note: args.note,
+    })),
+};
+export const listPanelsTool = {
+    name: "list_panels",
+    title: "Read the project's pinned panels",
+    description: "The panels already pinned to this project's dashboard, oldest first — what somebody decided " +
+        "was worth watching. Read it before pinning, so you extend the dashboard instead of " +
+        "duplicating a panel that is already there, and to learn which questions this team treats as " +
+        "important. Each row carries the spec's `id`, which is what `unpin_panel` takes.",
+    inputSchema: { limit: z.number().int().positive().max(500).optional() },
+    mutates: false,
+    execute: async (client, args) => client.get("/api/v1/panels", { limit: args.limit }),
+};
+export const unpinPanelTool = {
+    name: "unpin_panel",
+    title: "Remove a pinned panel",
+    description: "Remove one panel from the project's dashboard by its `id` (from `list_panels`). This " +
+        "removes it for **everyone** on the project rather than just the current viewer, so unpin a " +
+        "panel that has stopped being useful — never one you have not read first.",
+    inputSchema: {
+        id: z.string().min(1).max(128).describe("The panel spec's id, as `list_panels` reports it."),
+    },
+    mutates: true,
+    execute: async (client, args) => {
+        if (!client.delete)
+            throw new WriteNotSupportedError("delete");
+        return client.delete(`/api/v1/panels/${encodeURIComponent(String(args.id))}`);
+    },
+};
+/**
+ * The metadata tool catalog. Registered **only** when the calling key holds the
+ * `annotate` capability — including the read tools, which are listed here
+ * rather than in `readTools` so the whole metadata surface appears and
+ * disappears as one coherent feature.
+ */
+export const writeTools = [
+    annotateTool,
+    defineTermTool,
+    saveAnalysisTool,
+    pinPanelTool,
+    unpinPanelTool,
+    listAnnotationsTool,
+    listGlossaryTool,
+    listAnalysesTool,
+    listPanelsTool,
+];
+/** The tools that actually change stored state. */
+export const mutatingWriteTools = writeTools.filter((tool) => tool.mutates);
+//# sourceMappingURL=writeTools.js.map