@uptimizr/agent-core 1.1.0 → 1.2.0

package/dist/providers/anthropic.js

@@ -6,6 +6,20 @@
  * `tool_use` content blocks, and tool results are `tool_result` blocks carried
  * in a following user turn.
  */
+/**
+ * Normalise Anthropic's `usage` into {@link ProviderUsage}, or `undefined` when
+ * the response carried none — so a caller can tell "not reported" from zero.
+ */
+export function toProviderUsage(usage) {
+    const input = usage?.input_tokens;
+    const output = usage?.output_tokens;
+    if (typeof input !== "number" && typeof output !== "number")
+        return undefined;
+    return {
+        ...(typeof input === "number" ? { inputTokens: input } : {}),
+        ...(typeof output === "number" ? { outputTokens: output } : {}),
+    };
+}
 /**
  * Build the Anthropic request pieces (system prompt, messages, tools) from the
  * agent conversation and tool schemas.
@@ -73,10 +87,16 @@ export function parseAnthropicCompletion(completion) {
         .filter((b) => b.type === "text")
         .map((b) => b.text)
         .join("");
+    const usage = toProviderUsage(completion.usage);
     if (toolCalls.length > 0) {
-        return { kind: "tool_calls", toolCalls, ...(text ? { content: text } : {}) };
+        return {
+            kind: "tool_calls",
+            toolCalls,
+            ...(text ? { content: text } : {}),
+            ...(usage ? { usage } : {}),
+        };
     }
-    return { kind: "final", content: text };
+    return { kind: "final", content: text, ...(usage ? { usage } : {}) };
 }
 /** Parse a tool block's accumulated JSON input; malformed/empty → `{}`. */
 function parseToolInput(raw) {
@@ -93,9 +113,20 @@ function parseToolInput(raw) {
 /** Create a fresh {@link AnthropicStreamAssembler}. Pure: no I/O, no regex. */
 export function createAnthropicStreamAssembler() {
     const blocks = new Map();
+    // Anthropic splits the accounting across the stream: `message_start` reports
+    // the prompt tokens and `message_delta` the generated ones as they accrue.
+    const usage = {};
     return {
         push(event) {
             const index = typeof event.index === "number" ? event.index : 0;
+            const reported = event.message?.usage ?? event.usage;
+            if (reported) {
+                if (typeof reported.input_tokens === "number")
+                    usage.input_tokens = reported.input_tokens;
+                if (typeof reported.output_tokens === "number") {
+                    usage.output_tokens = reported.output_tokens;
+                }
+            }
             if (event.type === "content_block_start" && event.content_block) {
                 const start = event.content_block;
                 if (start.type === "text") {
@@ -149,7 +180,8 @@ export function createAnthropicStreamAssembler() {
                     });
                 }
             }
-            return { content };
+            const reported = usage.input_tokens != null || usage.output_tokens != null;
+            return { content, ...(reported ? { usage } : {}) };
         },
     };
 }

package/dist/providers/anthropic.js.map

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

package/dist/providers/openai.d.ts

@@ -5,7 +5,7 @@
  * OpenAI-compatible `chat.completions.create`. No I/O, no dependencies: just
  * shape mapping, so both adapters agree on tool-calling semantics.
  */
-import type { AgentMessage, AgentToolSchema, ProviderResponse } from "../provider.js";
+import type { AgentMessage, AgentToolSchema, ProviderResponse, ProviderUsage } from "../provider.js";
 /** OpenAI chat message (request side). */
 export interface OpenAiMessage {
     role: "system" | "user" | "assistant" | "tool";
@@ -32,6 +32,11 @@ export interface OpenAiTool {
         parameters: Record<string, unknown>;
     };
 }
+/** OpenAI's token accounting, as the chat-completions API spells it. */
+export interface OpenAiUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+}
 /** The subset of an OpenAI chat-completion response this module reads. */
 export interface OpenAiCompletion {
     choices?: Array<{
@@ -40,7 +45,13 @@ export interface OpenAiCompletion {
             tool_calls?: OpenAiToolCall[] | null;
         };
     }>;
+    usage?: OpenAiUsage;
 }
+/**
+ * Normalise OpenAI's `usage` into {@link ProviderUsage}, or `undefined` when the
+ * response carried none — so a caller can tell "not reported" from zero.
+ */
+export declare function toProviderUsage(usage: OpenAiUsage | undefined): ProviderUsage | undefined;
 /** Map the agent conversation to OpenAI request messages. */
 export declare function toOpenAiMessages(messages: readonly AgentMessage[]): OpenAiMessage[];
 /** Map the read-only tool schemas to OpenAI `tools`. */
@@ -57,6 +68,8 @@ export declare function parseOpenAiCompletion(completion: OpenAiCompletion): Pro
  * ones append to `function.arguments`. WebLLM's streamed tool calls omit `id`.
  */
 export interface OpenAiStreamChunk {
+    /** Present on the trailing chunk when the endpoint reports streamed usage. */
+    usage?: OpenAiUsage;
     choices?: Array<{
         delta?: {
             content?: string | null;

package/dist/providers/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACtF;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,OAAO,CAAC,EAAE;YACR,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,UAAU,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;SACtC,CAAC;KACH,CAAC,CAAC;CACJ;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,aAAa,EAAE,CAsBnF;AAUD,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,UAAU,EAAE,CAK7E;AAaD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CAkBpF;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,KAAK,CAAC,EAAE;YACN,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,UAAU,CAAC,EAAE,KAAK,CAAC;gBACjB,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,EAAE,CAAC,EAAE,MAAM,CAAC;gBACZ,IAAI,CAAC,EAAE,UAAU,CAAC;gBAClB,QAAQ,CAAC,EAAE;oBAAE,IAAI,CAAC,EAAE,MAAM,CAAC;oBAAC,SAAS,CAAC,EAAE,MAAM,CAAA;iBAAE,CAAC;aAClD,CAAC,GAAG,IAAI,CAAC;SACX,CAAC;QACF,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACvC,MAAM,IAAI,gBAAgB,CAAC;CAC5B;AAED,4EAA4E;AAC5E,wBAAgB,2BAA2B,IAAI,qBAAqB,CA6CnE"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,gBAAgB,EAChB,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACtF;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,OAAO,CAAC,EAAE;YACR,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,UAAU,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;SACtC,CAAC;KACH,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAQzF;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,aAAa,EAAE,CAsBnF;AAUD,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,UAAU,EAAE,CAK7E;AAaD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CAoBpF;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,KAAK,CAAC,EAAE;YACN,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,UAAU,CAAC,EAAE,KAAK,CAAC;gBACjB,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,EAAE,CAAC,EAAE,MAAM,CAAC;gBACZ,IAAI,CAAC,EAAE,UAAU,CAAC;gBAClB,QAAQ,CAAC,EAAE;oBAAE,IAAI,CAAC,EAAE,MAAM,CAAC;oBAAC,SAAS,CAAC,EAAE,MAAM,CAAA;iBAAE,CAAC;aAClD,CAAC,GAAG,IAAI,CAAC;SACX,CAAC;QACF,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACvC,MAAM,IAAI,gBAAgB,CAAC;CAC5B;AAED,4EAA4E;AAC5E,wBAAgB,2BAA2B,IAAI,qBAAqB,CAkDnE"}

package/dist/providers/openai.js

@@ -5,6 +5,20 @@
  * OpenAI-compatible `chat.completions.create`. No I/O, no dependencies: just
  * shape mapping, so both adapters agree on tool-calling semantics.
  */
+/**
+ * Normalise OpenAI's `usage` into {@link ProviderUsage}, or `undefined` when the
+ * response carried none — so a caller can tell "not reported" from zero.
+ */
+export function toProviderUsage(usage) {
+    const input = usage?.prompt_tokens;
+    const output = usage?.completion_tokens;
+    if (typeof input !== "number" && typeof output !== "number")
+        return undefined;
+    return {
+        ...(typeof input === "number" ? { inputTokens: input } : {}),
+        ...(typeof output === "number" ? { outputTokens: output } : {}),
+    };
+}
 /** Map the agent conversation to OpenAI request messages. */
 export function toOpenAiMessages(messages) {
     return messages.map((message) => {
@@ -63,6 +77,7 @@ export function parseOpenAiCompletion(completion) {
     const message = completion.choices?.[0]?.message;
     const toolCalls = message?.tool_calls ?? [];
     const content = message?.content ?? "";
+    const usage = toProviderUsage(completion.usage);
     if (toolCalls.length > 0) {
         return {
             kind: "tool_calls",
@@ -72,17 +87,23 @@ export function parseOpenAiCompletion(completion) {
                 arguments: parseArguments(call.function.arguments),
             })),
             ...(content ? { content } : {}),
+            ...(usage ? { usage } : {}),
         };
     }
-    return { kind: "final", content };
+    return { kind: "final", content, ...(usage ? { usage } : {}) };
 }
 /** Create a fresh {@link OpenAiStreamAssembler}. Pure: no I/O, no regex. */
 export function createOpenAiStreamAssembler() {
     let content = "";
     // Keyed by `index` so gapped or out-of-order indices still assemble.
     const calls = new Map();
+    // An endpoint that reports streamed usage puts it on a trailing chunk with no
+    // delta, so it is read before the early return below.
+    let usage;
     return {
         push(chunk) {
+            if (chunk.usage)
+                usage = chunk.usage;
             const delta = chunk.choices?.[0]?.delta;
             if (!delta)
                 return "";
@@ -122,6 +143,7 @@ export function createOpenAiStreamAssembler() {
                         },
                     },
                 ],
+                ...(usage ? { usage } : {}),
             };
         },
     };

package/dist/providers/openai.js.map

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

package/dist/queryTool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * **The `query` tool** (ADR 0051 §3, design sketch §C.3).
+ *
+ * One tool whose input *is* the query DSL. Where the generated catalog gives a
+ * model seventy tools and asks it to guess which one carries which flag, this
+ * gives it one tool and a vocabulary it can read: pick a `metric`, bound it with
+ * a `range`, narrow it with that metric's filters, cap it, and choose the result
+ * envelope.
+ *
+ * The canned per-metric tools stay — they are excellent for discovery, and a
+ * small model does better with a narrow, obvious tool than with a schema it has
+ * to compose. `query` is what the prompts and skills recommend once a question
+ * needs a filter the canned tool does not expose.
+ *
+ * ## Why it is a `GET`
+ *
+ * The collector serves the DSL on both `POST /api/v1/query` and
+ * `GET /api/v1/query?q=<url-encoded JSON>`. This tool uses the GET form, so
+ * {@link import("./client.js").CollectorClient} stays what it has always been —
+ * a read-only client that performs `GET` and nothing else. That is not a
+ * cosmetic preference: the client's inability to send anything but a `GET` is
+ * one of the reasons an Uptimizr agent is structurally incapable of writing
+ * (ADR 0003 / ADR 0017), and adding a `post()` for one tool would spend that
+ * guarantee to save a URL-encode. The collector's 8 KiB cap on `q` is well above
+ * any real query — the largest is a twenty-step funnel.
+ */
+import type { ReadTool } from "./tools.js";
+/** The tool name, also the `operationId` of the endpoint it calls. */
+export declare const QUERY_TOOL_NAME = "query";
+/**
+ * The single `query` tool. Its `inputSchema` is the DSL itself, so the model
+ * sees the same grammar the collector validates and the docs describe — there is
+ * no second, paraphrased tool schema to drift.
+ */
+export declare const queryTool: ReadTool;
+//# sourceMappingURL=queryTool.d.ts.map

package/dist/queryTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryTool.d.ts","sourceRoot":"","sources":["../src/queryTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC;AAE5D,sEAAsE;AACtE,eAAO,MAAM,eAAe,UAAU,CAAC;AAmFvC;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,QAWvB,CAAC"}

package/dist/queryTool.js

@@ -0,0 +1,123 @@
+/**
+ * **The `query` tool** (ADR 0051 §3, design sketch §C.3).
+ *
+ * One tool whose input *is* the query DSL. Where the generated catalog gives a
+ * model seventy tools and asks it to guess which one carries which flag, this
+ * gives it one tool and a vocabulary it can read: pick a `metric`, bound it with
+ * a `range`, narrow it with that metric's filters, cap it, and choose the result
+ * envelope.
+ *
+ * The canned per-metric tools stay — they are excellent for discovery, and a
+ * small model does better with a narrow, obvious tool than with a schema it has
+ * to compose. `query` is what the prompts and skills recommend once a question
+ * needs a filter the canned tool does not expose.
+ *
+ * ## Why it is a `GET`
+ *
+ * The collector serves the DSL on both `POST /api/v1/query` and
+ * `GET /api/v1/query?q=<url-encoded JSON>`. This tool uses the GET form, so
+ * {@link import("./client.js").CollectorClient} stays what it has always been —
+ * a read-only client that performs `GET` and nothing else. That is not a
+ * cosmetic preference: the client's inability to send anything but a `GET` is
+ * one of the reasons an Uptimizr agent is structurally incapable of writing
+ * (ADR 0003 / ADR 0017), and adding a `post()` for one tool would spend that
+ * guarantee to save a URL-encode. The collector's 8 KiB cap on `q` is well above
+ * any real query — the largest is a twenty-step funnel.
+ */
+import { z } from "zod";
+import { queryV1Schema } from "@uptimizr/schema";
+import { allMetrics } from "@uptimizr/metrics";
+/** The tool name, also the `operationId` of the endpoint it calls. */
+export const QUERY_TOOL_NAME = "query";
+/** The collector path the tool reads, root-relative like every other tool's. */
+const QUERY_PATH = "api/v1/query";
+/**
+ * The agent-facing description.
+ *
+ * It says six things a model needs and cannot infer from a JSON Schema: where
+ * the metric vocabulary comes from (so it looks an id up rather than inventing
+ * one), that `range` is not optional, how to read the default envelope, that
+ * `compare` will do the arithmetic it would otherwise do in prose, that
+ * `explain` exists at all, and that a summary row already carries the query to
+ * drill into it. The last three are the ones a model never discovers on its own:
+ * it will subtract two results by hand, report a zero it cannot account for, and
+ * rebuild a filter it was handed — every time — unless the tool says otherwise.
+ */
+function describeQueryTool() {
+    const known = new Set(allMetrics().map((metric) => metric.id));
+    const examples = ["top_meshes", "perf_summary", "mesh_sources", "timeseries"]
+        .filter((id) => known.has(id))
+        .map((id) => `\`${id}\``)
+        .join(", ");
+    return ("Run any Uptimizr metric in one validated request: choose the `metric`, bound it with a " +
+        "`range` (required, epoch milliseconds), narrow it with the filters that metric declares, " +
+        "cap it with `limit`, and choose the result envelope with `format`.\n\n" +
+        "Metric ids come from the registry — read the `uptimizr://capabilities` resource (or the " +
+        "collector's `GET /api/v1/openapi.json`) for the full list, which also names each metric's " +
+        `filters, its row columns and their units. Examples: ${examples}.\n\n` +
+        'How to read it: the default `format: "table"` returns `{ meta, rows }`, where `meta` ' +
+        "carries the window, the filters that were applied, the sample size behind the answer and " +
+        "whether the result was truncated — read it before quoting a number. `summary` returns a " +
+        "bounded digest (top rows, a trend, or merged spatial clusters) with shares and a " +
+        "plain-language reading; prefer it for a heatmap or a long leaderboard. `full` returns the " +
+        "bare rows.\n\n" +
+        "What changed: set `compare` to another `{ range }` or `{ segment }` and the result comes " +
+        "back already joined on the dimension key — `{ current, previous, delta, deltaPct }` per " +
+        "row, with a significance test where the measure is a count and both windows are big " +
+        "enough. Never run two queries and subtract them yourself.\n\n" +
+        "Can you trust it: set `explain: true` and the response is the plan instead of the rows — " +
+        "which compiler would run, the SQL with its parameters left unbound, how much data the " +
+        "window holds, and every reason the answer might mislead (a capture channel that is " +
+        "switched off, a sample below the metric's own minimum, a result cut off by `limit`). Worth " +
+        "one call before reporting a zero.\n\n" +
+        "Narrowing down: every row of a `summary` carries `drillQuery` — the whole query, narrowed " +
+        "to that row, ready to send straight back. Use it rather than rebuilding the query.\n\n" +
+        "Caveats:\n" +
+        "- Naming a metric, dimension or filter that does not exist is an error that names what the " +
+        "metric does accept — read it rather than guessing again.\n" +
+        "- `dimensions` may be any subset a metric declares **when** its measure is a portable count " +
+        "(event counts, mesh and interaction tallies, input actions, camera gestures). A spatial " +
+        "heatmap or a percentile is computed at one fixed grain and refuses anything else by name.\n" +
+        "- `order` takes a measure column, not a label, and only where the result is a ranked list.");
+}
+/**
+ * The `{ result }` envelope the tool advertises.
+ *
+ * The per-metric tools always return `{ rows }`, because their result is always
+ * a list of one metric's rows. This tool's shape is chosen by `format`, and the
+ * three envelopes are defined once in `@uptimizr/metrics` — but they are
+ * parameterised by the answering metric's row schema, which this tool only
+ * learns at call time. Restating two
+ * hundred lines of envelope schema here to dodge that dependency would create
+ * exactly the second definition ADR 0051 §1 exists to prevent, and an MCP client
+ * validating against a stale copy would reject a perfectly good answer.
+ *
+ * So the advertised schema is one described key, and the **response describes
+ * itself**: a `table` carries `meta.metric`, `meta.sampleSize` and
+ * `meta.truncated`; a `summary` carries `kind`, `metric`, `measure`, `reading`
+ * and `caveats`.
+ */
+const outputSchema = z.object({
+    result: z
+        .unknown()
+        .describe("The result, shaped by `format`: `table` → `{ meta, rows }` (the default), `summary` → a " +
+        "bounded digest with `kind`, `reading` and `caveats`, `full` → the bare rows."),
+});
+/**
+ * The single `query` tool. Its `inputSchema` is the DSL itself, so the model
+ * sees the same grammar the collector validates and the docs describe — there is
+ * no second, paraphrased tool schema to drift.
+ */
+export const queryTool = {
+    name: QUERY_TOOL_NAME,
+    title: "Run an analytics query",
+    description: describeQueryTool(),
+    inputSchema: queryV1Schema.shape,
+    outputSchema,
+    buildRequest: (args) => ({
+        path: QUERY_PATH,
+        params: { q: JSON.stringify(args) },
+    }),
+    structuredContent: (data) => ({ result: data }),
+};
+//# sourceMappingURL=queryTool.js.map

package/dist/queryTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryTool.js","sourceRoot":"","sources":["../src/queryTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,gFAAgF;AAChF,MAAM,UAAU,GAAG,cAAc,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,SAAS,iBAAiB;IACxB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAY,CAAC,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,CAAC,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,CAAC;SAC1E,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;SAC7B,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC;SACxB,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,CACL,yFAAyF;QACzF,2FAA2F;QAC3F,wEAAwE;QACxE,0FAA0F;QAC1F,4FAA4F;QAC5F,uDAAuD,QAAQ,OAAO;QACtE,uFAAuF;QACvF,2FAA2F;QAC3F,0FAA0F;QAC1F,mFAAmF;QACnF,4FAA4F;QAC5F,gBAAgB;QAChB,2FAA2F;QAC3F,0FAA0F;QAC1F,sFAAsF;QACtF,+DAA+D;QAC/D,2FAA2F;QAC3F,wFAAwF;QACxF,qFAAqF;QACrF,6FAA6F;QAC7F,uCAAuC;QACvC,4FAA4F;QAC5F,wFAAwF;QACxF,YAAY;QACZ,6FAA6F;QAC7F,4DAA4D;QAC5D,8FAA8F;QAC9F,0FAA0F;QAC1F,6FAA6F;QAC7F,4FAA4F,CAC7F,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC;SACN,OAAO,EAAE;SACT,QAAQ,CACP,0FAA0F;QACxF,8EAA8E,CACjF;CACJ,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAa;IACjC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EAAE,iBAAiB,EAAE;IAChC,WAAW,EAAE,aAAa,CAAC,KAAK;IAChC,YAAY;IACZ,YAAY,EAAE,CAAC,IAA6B,EAAmB,EAAE,CAAC,CAAC;QACjE,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;KACpC,CAAC;IACF,iBAAiB,EAAE,CAAC,IAAa,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CACzD,CAAC"}

package/dist/registryTools.d.ts

@@ -17,7 +17,7 @@
  * | `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[] }`                         |
+ * | `outputSchema` | `row`, in the `format` result envelope (ADR 0051 §2)        |
  *
  * **Browser safety (ADR 0050).** This module imports `@uptimizr/metrics` — the
  * registry's own dependency-free package, whose only runtime dependencies are
@@ -30,6 +30,21 @@
  */
 import { type MetricDefinition } from "@uptimizr/metrics";
 import type { ReadTool } from "./tools.js";
+/**
+ * The result envelope a generated tool asks the collector for when the caller
+ * names none (#336).
+ *
+ * `table` — the rows *plus* the `meta` block that says which metric answered,
+ * over what range, with which filters, how many rows came back and whether the
+ * row cap truncated them. An agent that omits `format` therefore gets the
+ * context it needs to judge the answer instead of a bare, unlabelled array; a
+ * caller that wants the old shape asks for `full` explicitly.
+ *
+ * The default lives **here, in the tool**, and travels as an explicit
+ * `format=table` on the wire. The collector's own default is still `full`, so
+ * the dashboard — which never sends the parameter — cannot be affected.
+ */
+export declare const DEFAULT_TOOL_FORMAT: "table";
 /**
  * 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
@@ -47,6 +62,13 @@ export declare function metricToTool(metric: MetricDefinition): ReadTool | undef
  * Generate the read-only tool catalog from the metric registry: one tool per
  * registry entry that has a collector endpoint, in registry declaration order.
  *
+ * **Capability-blind by design.** It generates a tool for every endpoint,
+ * whatever `endpoint.capability` says, because generation and *exposure* are
+ * separate decisions: `tools.ts` partitions the result into the `query` catalog
+ * (`readTools`) and the `query:raw` one (`rawTools`), and the host decides which
+ * of those a given API key may see (ADR 0051 §7). Pass a filtered metric list to
+ * generate only part of the catalog.
+ *
  * Pure — it reads definitions only and never touches a collector — so the whole
  * catalog is unit-testable without a live server.
  */

package/dist/registryTools.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"registryTools.d.ts","sourceRoot":"","sources":["../src/registryTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,EAOL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC;AAkB5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAG,OAAgB,CAAC;AAqapD;;;;;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,CA8E3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,SAAS,gBAAgB,EAAiB,GAClD,SAAS,QAAQ,EAAE,CAOrB"}