@uptimizr/agent-core 1.1.1 → 1.2.0

package/dist/context.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Rendering the collector's **project context document** for a system prompt
+ * (ADR 0051 §5, design sketch §E.1).
+ *
+ * `GET /api/v1/context` answers, in one read, everything an agent would
+ * otherwise guess about the project in front of it: the scene ids and their
+ * named regions, the custom events the application emits and the props they
+ * carry, which capture channels are off (and so which metrics will be
+ * legitimately empty), whether raw session retention is enabled, and how fresh
+ * the data is.
+ *
+ * The document is JSON and bounded, but it is still several kilobytes — too much
+ * to paste into the system prompt of a 1–3 B local model, which has to carry ~69
+ * tool schemas in the same budget. {@link renderContextForPrompt} turns it into a
+ * compact, ordered block of prose-and-lists: a few hundred tokens that put the
+ * *names* an agent needs in front of it, and say plainly which questions the data
+ * cannot answer. Anything a model would only need after it has already decided
+ * what to ask (per-channel volumes, the full metric list, the window bounds) is
+ * left out — it can read the resource itself.
+ *
+ * Pure and dependency-free: a plain function from a structural view of the
+ * document to a string. It is deliberately **tolerant** of a partial or
+ * unfamiliar document — an older collector, a newer field, a proxy that trimmed
+ * something — because degrading to a shorter block is always better than an
+ * assistant that will not start.
+ */
+/** Hard cap on the rendered block, in characters (~1.5 k tokens). */
+export declare const CONTEXT_PROMPT_MAX_CHARS = 6000;
+/** Structural view of the parts of the context document the rendering uses. */
+export interface PromptContextDocument {
+    project?: {
+        id?: string;
+        store?: string;
+        collectorVersion?: string;
+    } | null;
+    dataQuality?: {
+        lastEventAt?: number | null;
+        sessions24h?: number;
+        events24h?: number;
+        retention?: {
+            rawSessions?: boolean;
+        } | null;
+    } | null;
+    scenes?: readonly {
+        id?: string;
+        label?: string | null;
+        regions?: readonly {
+            id?: string;
+            label?: string;
+        }[];
+        proxy?: boolean;
+    }[];
+    vocabulary?: {
+        customEvents?: readonly {
+            name?: string;
+            count28d?: number;
+            props?: Record<string, string>;
+        }[];
+        meshes?: {
+            count?: number;
+            top?: readonly string[];
+        } | null;
+        inputActions?: readonly string[];
+    } | null;
+    definitions?: {
+        glossary?: readonly {
+            term?: string;
+            meaning?: string;
+        }[];
+    } | null;
+    annotations?: {
+        recent?: readonly {
+            text?: string;
+            at?: number;
+        }[];
+    } | null;
+    metrics?: {
+        disabledByCapture?: readonly string[];
+    } | null;
+}
+/**
+ * Render a project context document as a compact system-prompt block.
+ *
+ * Returns `""` when there is nothing useful to say, so a caller can append the
+ * result unconditionally. The output is truncated to
+ * {@link CONTEXT_PROMPT_MAX_CHARS} on a line boundary, with a marker, so a
+ * pathological project can never crowd out the tool schemas.
+ *
+ * @param context The document from `GET /api/v1/context` (any subset of it).
+ * @param nowMs Current time, for the "last event" phrasing. Defaults to `Date.now()`.
+ */
+export declare function renderContextForPrompt(context: PromptContextDocument | null | undefined, nowMs?: number): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E,WAAW,CAAC,EAAE;QACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;KAC9C,GAAG,IAAI,CAAC;IACT,MAAM,CAAC,EAAE,SAAS;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,OAAO,CAAC,EAAE,SAAS;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACrD,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,EAAE,CAAC;IACJ,UAAU,CAAC,EAAE;QACX,YAAY,CAAC,EAAE,SAAS;YACtB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SAChC,EAAE,CAAC;QACJ,MAAM,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,GAAG,IAAI,CAAC;QAC5D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,GAAG,IAAI,CAAC;IACT,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,SAAS;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACnF,WAAW,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,SAAS;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E,OAAO,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5D;AA4CD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EACjD,KAAK,GAAE,MAAmB,GACzB,MAAM,CAsFR"}

package/dist/context.js

@@ -0,0 +1,137 @@
+/**
+ * Rendering the collector's **project context document** for a system prompt
+ * (ADR 0051 §5, design sketch §E.1).
+ *
+ * `GET /api/v1/context` answers, in one read, everything an agent would
+ * otherwise guess about the project in front of it: the scene ids and their
+ * named regions, the custom events the application emits and the props they
+ * carry, which capture channels are off (and so which metrics will be
+ * legitimately empty), whether raw session retention is enabled, and how fresh
+ * the data is.
+ *
+ * The document is JSON and bounded, but it is still several kilobytes — too much
+ * to paste into the system prompt of a 1–3 B local model, which has to carry ~69
+ * tool schemas in the same budget. {@link renderContextForPrompt} turns it into a
+ * compact, ordered block of prose-and-lists: a few hundred tokens that put the
+ * *names* an agent needs in front of it, and say plainly which questions the data
+ * cannot answer. Anything a model would only need after it has already decided
+ * what to ask (per-channel volumes, the full metric list, the window bounds) is
+ * left out — it can read the resource itself.
+ *
+ * Pure and dependency-free: a plain function from a structural view of the
+ * document to a string. It is deliberately **tolerant** of a partial or
+ * unfamiliar document — an older collector, a newer field, a proxy that trimmed
+ * something — because degrading to a shorter block is always better than an
+ * assistant that will not start.
+ */
+/** Hard cap on the rendered block, in characters (~1.5 k tokens). */
+export const CONTEXT_PROMPT_MAX_CHARS = 6000;
+/** Join a list for prose, capping it and saying how many were left out. */
+function capped(values, max) {
+    if (values.length <= max)
+        return values.join(", ");
+    return `${values.slice(0, max).join(", ")} (+${values.length - max} more)`;
+}
+/** `name(sku: string, qty: number)` — a custom event and what it carries. */
+function renderCustomEvent(event) {
+    const props = Object.entries(event.props ?? {})
+        .slice(0, 8)
+        .map(([key, type]) => `${key}: ${type}`)
+        .join(", ");
+    const count = typeof event.count28d === "number" ? ` ×${event.count28d}` : "";
+    return `${event.name ?? "?"}${count}${props ? ` {${props}}` : ""}`;
+}
+/** `lobby "Main Lobby" [regions: counter, door]` — one scene line. */
+function renderScene(scene) {
+    const label = scene.label ? ` "${scene.label}"` : "";
+    const regions = (scene.regions ?? []).map((region) => region.id).filter(Boolean);
+    const regionPart = regions.length > 0 ? ` [regions: ${capped(regions, 8)}]` : "";
+    return `- ${scene.id ?? "?"}${label}${regionPart}`;
+}
+/** How long ago, in whole units, for the freshness line. */
+function ago(lastEventAt, nowMs) {
+    const minutes = Math.max(0, Math.round((nowMs - lastEventAt) / 60_000));
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `${hours} h ago`;
+    return `${Math.round(hours / 24)} days ago`;
+}
+/**
+ * Render a project context document as a compact system-prompt block.
+ *
+ * Returns `""` when there is nothing useful to say, so a caller can append the
+ * result unconditionally. The output is truncated to
+ * {@link CONTEXT_PROMPT_MAX_CHARS} on a line boundary, with a marker, so a
+ * pathological project can never crowd out the tool schemas.
+ *
+ * @param context The document from `GET /api/v1/context` (any subset of it).
+ * @param nowMs Current time, for the "last event" phrasing. Defaults to `Date.now()`.
+ */
+export function renderContextForPrompt(context, nowMs = Date.now()) {
+    if (context == null || typeof context !== "object")
+        return "";
+    const lines = [];
+    const scenes = (context.scenes ?? []).filter((scene) => typeof scene.id === "string");
+    if (scenes.length > 0) {
+        lines.push("Scenes (use these exact ids for the `scene` filter; region ids for `region`):");
+        for (const scene of scenes.slice(0, 20))
+            lines.push(renderScene(scene));
+        if (scenes.length > 20)
+            lines.push(`- (+${scenes.length - 20} more scenes)`);
+    }
+    const customEvents = (context.vocabulary?.customEvents ?? []).filter((event) => typeof event.name === "string");
+    if (customEvents.length > 0) {
+        lines.push("", "Custom events this app emits (name ×count {props}) — use these exact names:", ...customEvents.slice(0, 15).map((event) => `- ${renderCustomEvent(event)}`));
+        if (customEvents.length > 15)
+            lines.push(`- (+${customEvents.length - 15} more)`);
+    }
+    const meshes = context.vocabulary?.meshes?.top ?? [];
+    if (meshes.length > 0)
+        lines.push("", `Most-interacted meshes: ${capped([...meshes], 10)}.`);
+    const actions = context.vocabulary?.inputActions ?? [];
+    if (actions.length > 0)
+        lines.push(`Bound input actions: ${capped([...actions], 12)}.`);
+    const glossary = (context.definitions?.glossary ?? []).filter((entry) => entry.term);
+    if (glossary.length > 0) {
+        lines.push("", "Project glossary:", ...glossary.slice(0, 12).map((entry) => `- ${entry.term}: ${entry.meaning ?? ""}`));
+    }
+    const annotations = (context.annotations?.recent ?? []).filter((entry) => entry.text);
+    if (annotations.length > 0) {
+        lines.push("", "Recent annotations (project notes, newest first):", ...annotations.slice(0, 5).map((entry) => `- ${entry.text ?? ""}`));
+    }
+    const disabled = context.metrics?.disabledByCapture ?? [];
+    if (disabled.length > 0) {
+        lines.push("", `No data is captured for these metrics, so they WILL return empty — say the channel is off ` +
+            `rather than reporting a zero: ${capped([...disabled], 20)}.`);
+    }
+    const quality = context.dataQuality;
+    if (quality != null) {
+        const parts = [];
+        if (typeof quality.lastEventAt === "number") {
+            parts.push(`last event ${ago(quality.lastEventAt, nowMs)}`);
+        }
+        else if (quality.lastEventAt === null) {
+            parts.push("no events recorded yet");
+        }
+        if (typeof quality.sessions24h === "number") {
+            parts.push(`${quality.sessions24h} sessions in the last 24 h`);
+        }
+        if (parts.length > 0)
+            lines.push("", `Data: ${parts.join(", ")}.`);
+        if (quality.retention?.rawSessions === false) {
+            lines.push("Raw per-session retention is OFF: session timelines and replay are unavailable by design.");
+        }
+    }
+    if (lines.length === 0)
+        return "";
+    const header = "Project context (read from this collector; prefer these real names over any you infer):";
+    const body = [header, "", ...lines].join("\n").trimEnd();
+    if (body.length <= CONTEXT_PROMPT_MAX_CHARS)
+        return body;
+    const truncated = body.slice(0, CONTEXT_PROMPT_MAX_CHARS);
+    const lastBreak = truncated.lastIndexOf("\n");
+    return `${truncated.slice(0, lastBreak > 0 ? lastBreak : CONTEXT_PROMPT_MAX_CHARS)}\n… (context truncated)`;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 export { createCollectorClient, CollectorError, type CollectorClient, type CollectorClientConfig, type QueryParams, } from "./client.js";
-export { readTools, coreReadTools, selectReadTools, filterReadTools, CORE_READ_TOOL_NAMES, type ReadTool, type ReadToolRequest, type ReadToolSetKind, } from "./tools.js";
-export { registryToTools, metricToTool, describeMetric } from "./registryTools.js";
-export type { AgentMessage, AgentToolCall, AgentToolSchema, LlmProvider, ProviderRequest, ProviderResponse, } from "./provider.js";
+export { readTools, rawTools, coreReadTools, selectReadTools, filterReadTools, CORE_READ_TOOL_NAMES, type ReadTool, type ReadToolRequest, type ReadToolSetKind, } from "./tools.js";
+export { registryToTools, metricToTool, describeMetric, DEFAULT_TOOL_FORMAT, } from "./registryTools.js";
+export { QUERY_TOOL_NAME, queryTool } from "./queryTool.js";
+export { writeTools, mutatingWriteTools, annotateTool, defineTermTool, saveAnalysisTool, pinPanelTool, unpinPanelTool, listAnnotationsTool, listGlossaryTool, listAnalysesTool, listPanelsTool, WriteNotSupportedError, type WriteTool, } from "./writeTools.js";
+export { renderContextForPrompt, CONTEXT_PROMPT_MAX_CHARS } from "./context.js";
+export type { PromptContextDocument } from "./context.js";
+export { NON_REGISTRY_READ_TOOLS } from "./nonRegistryTools.js";
+export type { AgentMessage, AgentToolCall, AgentToolSchema, LlmProvider, ProviderRequest, ProviderResponse, ProviderUsage, } from "./provider.js";
+export { ANALYTICS_AGENT_GUIDELINES, renderCurrentTimeLine } from "./prompt.js";
+export { AGENT_SKILLS, AGENT_SKILL_NAMES, getAgentSkill, renderAgentSkill, type AgentSkill, type AgentSkillArg, } from "./skills.js";
 export { runAgent, toToolSchemas, truncateToolResult, DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_RESULT_CHARS, type AgentStreamEvent, type RunAgentOptions, type RunAgentResult, } from "./loop.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnF,YAAY,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG5D,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAG1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIhF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,5 +1,23 @@
 export { createCollectorClient, CollectorError, } from "./client.js";
-export { readTools, coreReadTools, selectReadTools, filterReadTools, CORE_READ_TOOL_NAMES, } from "./tools.js";
-export { registryToTools, metricToTool, describeMetric } from "./registryTools.js";
+export { readTools, rawTools, coreReadTools, selectReadTools, filterReadTools, CORE_READ_TOOL_NAMES, } from "./tools.js";
+export { registryToTools, metricToTool, describeMetric, DEFAULT_TOOL_FORMAT, } from "./registryTools.js";
+export { QUERY_TOOL_NAME, queryTool } from "./queryTool.js";
+// Metadata write tools (#310, #315) — a separate export from `readTools` on
+// purpose, so ADR 0017's read-only stance stays inspectable at a glance.
+export { writeTools, mutatingWriteTools, annotateTool, defineTermTool, saveAnalysisTool, pinPanelTool, unpinPanelTool, listAnnotationsTool, listGlossaryTool, listAnalysesTool, listPanelsTool, WriteNotSupportedError, } from "./writeTools.js";
+// --- Project context (ADR 0051 §5, design sketch §E.1) ---
+// The compact system-prompt rendering of the collector context document.
+export { renderContextForPrompt, CONTEXT_PROMPT_MAX_CHARS } from "./context.js";
+// Collector reads that are configuration rather than measurements, and so have
+// no registry entry to generate a tool from (#311, ADR 0051 §6).
+export { NON_REGISTRY_READ_TOOLS } from "./nonRegistryTools.js";
+// --- Shared system-prompt fragments (ADR 0050 §4, ADR 0051 §6) ---
+// What every analytics agent says about the data, shared by the browser
+// assistant and the headless report CLI.
+export { ANALYTICS_AGENT_GUIDELINES, renderCurrentTimeLine } from "./prompt.js";
+// --- Agent skills (ADR 0050 §7, ADR 0051 §6) ---
+// The curated investigation methodologies shared by the MCP prompt templates and
+// the headless `uptimizr agent report` CLI.
+export { AGENT_SKILLS, AGENT_SKILL_NAMES, getAgentSkill, renderAgentSkill, } from "./skills.js";
 export { runAgent, toToolSchemas, truncateToolResult, DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_RESULT_CHARS, } from "./loop.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GAIf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,GAIrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASnF,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,GAI9B,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GAIf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,GAIrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC5D,4EAA4E;AAC5E,yEAAyE;AACzE,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,GAEvB,MAAM,iBAAiB,CAAC;AACzB,4DAA4D;AAC5D,yEAAyE;AACzE,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEhF,+EAA+E;AAC/E,iEAAiE;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAUhE,oEAAoE;AACpE,wEAAwE;AACxE,yCAAyC;AACzC,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAChF,kDAAkD;AAClD,iFAAiF;AACjF,4CAA4C;AAC5C,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GAGjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,GAI9B,MAAM,WAAW,CAAC"}

package/dist/nonRegistryTools.d.ts

@@ -0,0 +1,34 @@
+import type { ReadTool } from "./tools.js";
+/**
+ * **Read tools that are not registry metrics** (ADR 0051 §1).
+ *
+ * The catalog in `tools.ts` is generated from `@uptimizr/metrics`, and that is
+ * the rule: a new aggregation reaches agents by getting a registry entry, never
+ * by being added to a hand-written list. This module is the narrow, deliberate
+ * exception — collector surfaces that an agent needs but that are **not
+ * metrics** and so have no registry entry to generate from.
+ *
+ * There is exactly one today: `list_subscriptions` (#311, ADR 0051 §6). A
+ * subscription is project *configuration*, not a measurement; it has no rows, no
+ * unit, no comparable column, and no window. Inventing a registry entry for it
+ * would put a non-metric into the catalog that every other consumer (OpenAPI,
+ * the docs tables, the insight primitives' "comparable metrics" lists) treats as
+ * a measurement.
+ *
+ * Anything that *is* a measurement belongs in the registry instead. If this file
+ * grows past a handful of entries, that is the signal that the boundary has
+ * moved and the registry should absorb them.
+ *
+ * ## Writing subscriptions
+ *
+ * `create_subscription` / `delete_subscription` are deliberately absent. They
+ * are mutations, and the MCP server has no write path at all on this branch (see
+ * `@uptimizr/mcp`'s `server.ts`: `CollectorClient` exposes only `get`). They land
+ * with the `annotate`-gated write-tool surface introduced by the metadata write
+ * path (#310); until then an agent creates a subscription over plain HTTP with
+ * an `annotate` key, or an operator does it with
+ * `uptimizr subscriptions add --file`.
+ */
+/** One `ReadTool` per non-metric collector read an agent should have. */
+export declare const NON_REGISTRY_READ_TOOLS: readonly ReadTool[];
+//# sourceMappingURL=nonRegistryTools.d.ts.map

package/dist/nonRegistryTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonRegistryTools.d.ts","sourceRoot":"","sources":["../src/nonRegistryTools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,EAAE,SAAS,QAAQ,EAuCtD,CAAC"}

package/dist/nonRegistryTools.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/**
+ * **Read tools that are not registry metrics** (ADR 0051 §1).
+ *
+ * The catalog in `tools.ts` is generated from `@uptimizr/metrics`, and that is
+ * the rule: a new aggregation reaches agents by getting a registry entry, never
+ * by being added to a hand-written list. This module is the narrow, deliberate
+ * exception — collector surfaces that an agent needs but that are **not
+ * metrics** and so have no registry entry to generate from.
+ *
+ * There is exactly one today: `list_subscriptions` (#311, ADR 0051 §6). A
+ * subscription is project *configuration*, not a measurement; it has no rows, no
+ * unit, no comparable column, and no window. Inventing a registry entry for it
+ * would put a non-metric into the catalog that every other consumer (OpenAPI,
+ * the docs tables, the insight primitives' "comparable metrics" lists) treats as
+ * a measurement.
+ *
+ * Anything that *is* a measurement belongs in the registry instead. If this file
+ * grows past a handful of entries, that is the signal that the boundary has
+ * moved and the registry should absorb them.
+ *
+ * ## Writing subscriptions
+ *
+ * `create_subscription` / `delete_subscription` are deliberately absent. They
+ * are mutations, and the MCP server has no write path at all on this branch (see
+ * `@uptimizr/mcp`'s `server.ts`: `CollectorClient` exposes only `get`). They land
+ * with the `annotate`-gated write-tool surface introduced by the metadata write
+ * path (#310); until then an agent creates a subscription over plain HTTP with
+ * an `annotate` key, or an operator does it with
+ * `uptimizr subscriptions add --file`.
+ */
+/** One `ReadTool` per non-metric collector read an agent should have. */
+export const NON_REGISTRY_READ_TOOLS = [
+    {
+        name: "list_subscriptions",
+        title: "List conditional subscriptions",
+        description: "The project's standing conditional subscriptions (ADR 0051 §6): what the collector is " +
+            "watching for, how often it checks, where a firing is delivered, and how each one last " +
+            "went (`lastFiredAt`, `failures`, `lastError`). Configuration, not a measurement — it " +
+            "takes no time range. Any webhook secret is masked and never returned. Needs only the " +
+            "`query` capability; creating or deleting one needs `annotate` and is not available as a " +
+            "tool.\n\nCaveats: this is what the project is configured to watch for, not a measurement " +
+            "of anything. A subscription that has never fired may mean the condition never occurred, " +
+            "or that it is disabled, or that its `minSample` gate was never cleared — check `enabled` " +
+            "and the subscription's own firing log (`GET /api/v1/subscriptions/:id/events`) before " +
+            "concluding anything about the underlying metric.",
+        inputSchema: {},
+        outputSchema: z.object({
+            rows: z
+                .array(z.object({
+                id: z.string(),
+                name: z.string(),
+                metric: z.string().describe("Registry metric id the subscription watches."),
+                predicate: z
+                    .record(z.string(), z.unknown())
+                    .describe("Closed union discriminated on `kind`."),
+                enabled: z.boolean(),
+                lastFiredAt: z
+                    .string()
+                    .nullable()
+                    .describe("ISO timestamp of the last firing, or null if it never fired."),
+                failures: z.number().describe("Consecutive delivery failures since the last success."),
+                lastError: z.string().nullable(),
+            }))
+                .describe("One row per subscription, oldest first."),
+        }),
+        buildRequest: () => ({ path: "api/v1/subscriptions", params: {} }),
+    },
+];
+//# sourceMappingURL=nonRegistryTools.js.map

package/dist/nonRegistryTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonRegistryTools.js","sourceRoot":"","sources":["../src/nonRegistryTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,uBAAuB,GAAwB;IAC1D;QACE,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,gCAAgC;QACvC,WAAW,EACT,wFAAwF;YACxF,wFAAwF;YACxF,uFAAuF;YACvF,uFAAuF;YACvF,0FAA0F;YAC1F,2FAA2F;YAC3F,0FAA0F;YAC1F,2FAA2F;YAC3F,wFAAwF;YACxF,kDAAkD;QACpD,WAAW,EAAE,EAAE;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;YACrB,IAAI,EAAE,CAAC;iBACJ,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;gBACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;gBACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;gBAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;gBAC3E,SAAS,EAAE,CAAC;qBACT,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;qBAC/B,QAAQ,CAAC,uCAAuC,CAAC;gBACpD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;gBACpB,WAAW,EAAE,CAAC;qBACX,MAAM,EAAE;qBACR,QAAQ,EAAE;qBACV,QAAQ,CAAC,8DAA8D,CAAC;gBAC3E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;gBACtF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;aACjC,CAAC,CACH;iBACA,QAAQ,CAAC,yCAAyC,CAAC;SACvD,CAAC;QACF,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;KACnE;CACF,CAAC"}

package/dist/prompt.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The system-prompt fragments every Uptimizr analytics agent shares.
+ *
+ * Two clients now prime a model to read this collector's analytics: the
+ * in-browser assistant (`@uptimizr/react`) and the headless
+ * `uptimizr agent report` CLI (`@uptimizr/collector-server`, ADR 0051 §6). What
+ * they say about the *data* must not diverge — that the figures come from tools
+ * and are never invented, that everything is aggregate and privacy-preserving
+ * (ADR 0003 / 0017), that timestamps are epoch milliseconds, that a tool error
+ * is explained rather than papered over. Only the opening role sentence and the
+ * output format legitimately differ between them, so only those live in the
+ * clients.
+ *
+ * Pure strings and one pure function — no I/O, no regex over prompt text.
+ */
+/**
+ * The shared behavioural guidelines, verbatim, as a `Guidelines:`-headed block.
+ * A client prepends its own one-paragraph role statement and may append its own
+ * output-format instructions.
+ */
+export declare const ANALYTICS_AGENT_GUIDELINES: string;
+/**
+ * The single line that gives the model a clock.
+ *
+ * The guidelines tell it to convert relative ranges, but a model has no inherent
+ * clock — without a "now" reference it drops the range or invents timestamps and
+ * answers over all time. Callers stamp it at send time so a long-lived session
+ * keeps resolving "today" against the real current day.
+ *
+ * @param nowMs The current time in epoch milliseconds (e.g. `Date.now()`).
+ */
+export declare function renderCurrentTimeLine(nowMs: number): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAU3B,CAAC;AAEb;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3D"}

package/dist/prompt.js

@@ -0,0 +1,49 @@
+/**
+ * The system-prompt fragments every Uptimizr analytics agent shares.
+ *
+ * Two clients now prime a model to read this collector's analytics: the
+ * in-browser assistant (`@uptimizr/react`) and the headless
+ * `uptimizr agent report` CLI (`@uptimizr/collector-server`, ADR 0051 §6). What
+ * they say about the *data* must not diverge — that the figures come from tools
+ * and are never invented, that everything is aggregate and privacy-preserving
+ * (ADR 0003 / 0017), that timestamps are epoch milliseconds, that a tool error
+ * is explained rather than papered over. Only the opening role sentence and the
+ * output format legitimately differ between them, so only those live in the
+ * clients.
+ *
+ * Pure strings and one pure function — no I/O, no regex over prompt text.
+ */
+/**
+ * The shared behavioural guidelines, verbatim, as a `Guidelines:`-headed block.
+ * A client prepends its own one-paragraph role statement and may append its own
+ * output-format instructions.
+ */
+export const ANALYTICS_AGENT_GUIDELINES = [
+    "Guidelines:",
+    "- Use the provided tools to fetch data before answering; never invent numbers.",
+    "- All data is aggregate and privacy-preserving — there are no raw per-session events,",
+    "  no PII, and no way to ingest or modify data. Do not claim otherwise.",
+    "- Timestamps are epoch milliseconds. When the user gives a relative range",
+    '  ("this week", "last 24h"), convert it to `since`/`until` before calling a tool.',
+    "- Prefer a short, direct answer with the key figures. Call out caveats (small sample",
+    "  sizes, missing scenes) when relevant.",
+    "- If a tool returns an error, explain what went wrong and, if useful, try a corrected call.",
+].join("\n");
+/**
+ * The single line that gives the model a clock.
+ *
+ * The guidelines tell it to convert relative ranges, but a model has no inherent
+ * clock — without a "now" reference it drops the range or invents timestamps and
+ * answers over all time. Callers stamp it at send time so a long-lived session
+ * keeps resolving "today" against the real current day.
+ *
+ * @param nowMs The current time in epoch milliseconds (e.g. `Date.now()`).
+ */
+export function renderCurrentTimeLine(nowMs) {
+    const iso = new Date(nowMs).toISOString();
+    return (`Current time: ${iso} (epoch milliseconds: ${nowMs}). ` +
+        "Resolve any relative time range in the question against this — " +
+        '"today" is the current calendar day, "this week" the last 7 days, ' +
+        '"last 24h" the preceding 24 hours — into concrete `since`/`until` epoch-ms arguments.');
+}
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,aAAa;IACb,gFAAgF;IAChF,uFAAuF;IACvF,wEAAwE;IACxE,2EAA2E;IAC3E,mFAAmF;IACnF,sFAAsF;IACtF,yCAAyC;IACzC,6FAA6F;CAC9F,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,OAAO,CACL,iBAAiB,GAAG,yBAAyB,KAAK,KAAK;QACvD,iEAAiE;QACjE,oEAAoE;QACpE,uFAAuF,CACxF,CAAC;AACJ,CAAC"}

package/dist/provider.d.ts

@@ -44,14 +44,32 @@ export interface AgentToolSchema {
     description: string;
     parameters: Record<string, unknown>;
 }
+/**
+ * Token accounting for one provider turn, when the provider reports it.
+ *
+ * Every field is optional: a provider may report neither, one or both, and a
+ * local backend reports nothing at all. Consumers therefore treat a missing
+ * number as "not reported" and never as zero — the distinction matters in the
+ * cost line of a scheduled report.
+ */
+export interface ProviderUsage {
+    /** Prompt tokens billed for this turn. */
+    inputTokens?: number;
+    /** Generated tokens billed for this turn. */
+    outputTokens?: number;
+}
 /** The two possible outcomes of a provider turn. */
 export type ProviderResponse = {
     kind: "tool_calls";
     toolCalls: AgentToolCall[];
     content?: string;
+    /** Token accounting for this turn, when the provider reported any. */
+    usage?: ProviderUsage;
 } | {
     kind: "final";
     content: string;
+    /** Token accounting for this turn, when the provider reported any. */
+    usage?: ProviderUsage;
 };
 /** A single provider completion request. */
 export interface ProviderRequest {

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kDAAkD;AAClD,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,aAAa,EAAE,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,aAAa,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wDAAwD;IACxD,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kDAAkD;AAClD,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,aAAa,EAAE,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GACxB;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,CAAC;AAEN,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wDAAwD;IACxD,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/D"}

package/dist/providers/anthropic.d.ts

@@ -6,7 +6,7 @@
  * `tool_use` content blocks, and tool results are `tool_result` blocks carried
  * in a following user turn.
  */
-import type { AgentMessage, AgentToolSchema, ProviderResponse } from "../provider.js";
+import type { AgentMessage, AgentToolSchema, ProviderResponse, ProviderUsage } from "../provider.js";
 /** An Anthropic content block (the subset used here). */
 export type AnthropicContentBlock = {
     type: "text";
@@ -39,10 +39,21 @@ export interface AnthropicRequestBody {
     /** Omitted when no tools are advertised (e.g. a forced plain-text turn). */
     tools?: AnthropicTool[];
 }
+/** Anthropic's token accounting, as the Messages API spells it. */
+export interface AnthropicUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+}
 /** The subset of an Anthropic Messages response this module reads. */
 export interface AnthropicCompletion {
     content?: AnthropicContentBlock[];
+    usage?: AnthropicUsage;
 }
+/**
+ * Normalise Anthropic'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: AnthropicUsage | undefined): ProviderUsage | undefined;
 /**
  * Build the Anthropic request pieces (system prompt, messages, tools) from the
  * agent conversation and tool schemas.
@@ -74,6 +85,12 @@ export interface AnthropicStreamEvent {
         text?: string;
         partial_json?: string;
     };
+    /** `message_start` reports the prompt tokens on the message it opens. */
+    message?: {
+        usage?: AnthropicUsage;
+    };
+    /** `message_delta` reports the generated tokens as they accrue. */
+    usage?: AnthropicUsage;
 }
 /**
  * Accumulates {@link AnthropicStreamEvent}s into a complete

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

@@ -1 +1 @@
-{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/providers/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,yDAAyD;AACzD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,oBAAoB,CA6CtB;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,mBAAmB,GAAG,gBAAgB,CAc1F;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAAC;IAC1C,MAAM,IAAI,mBAAmB,CAAC;CAC/B;AAaD,+EAA+E;AAC/E,wBAAgB,8BAA8B,IAAI,wBAAwB,CA+DzE"}
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/providers/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,gBAAgB,EAChB,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB,yDAAyD;AACzD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAQ5F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,oBAAoB,CA6CtB;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,mBAAmB,GAAG,gBAAgB,CAqB1F;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,yEAAyE;IACzE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,cAAc,CAAA;KAAE,CAAC;IACrC,mEAAmE;IACnE,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAAC;IAC1C,MAAM,IAAI,mBAAmB,CAAC;CAC/B;AAaD,+EAA+E;AAC/E,wBAAgB,8BAA8B,IAAI,wBAAwB,CA0EzE"}