@kontourai/console-telemetry 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import type { PricingRegistry } from "./types";
+export interface TelemetryClientOptions {
+    /** Console base URL, e.g. https://console.example.com */
+    baseUrl: string;
+    /** Optional bearer token / tenant headers. */
+    headers?: Record<string, string>;
+}
+export declare class ConsoleTelemetryClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(options: TelemetryClientOptions);
+    /** POST one or more telemetry records to the console intake. */
+    postTelemetry(records: unknown[]): Promise<Response>;
+    /** Fetch the live pricing registry served by the console. */
+    getPricing(): Promise<PricingRegistry>;
+}

package/dist/client.js

@@ -0,0 +1,31 @@
+"use strict";
+// client.ts — typed clients for the console telemetry/pricing intake URLs.
+//
+// The console is the distribution hub; this is the typed surface for its URLs,
+// shared by producers (post events / fetch pricing) and tooling.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleTelemetryClient = void 0;
+class ConsoleTelemetryClient {
+    baseUrl;
+    headers;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.headers = { "content-type": "application/json", ...(options.headers || {}) };
+    }
+    /** POST one or more telemetry records to the console intake. */
+    async postTelemetry(records) {
+        return fetch(`${this.baseUrl}/api/telemetry/records`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(records.length === 1 ? records[0] : records)
+        });
+    }
+    /** Fetch the live pricing registry served by the console. */
+    async getPricing() {
+        const res = await fetch(`${this.baseUrl}/api/telemetry/pricing`, { headers: this.headers });
+        if (!res.ok)
+            throw new Error(`pricing fetch failed: ${res.status}`);
+        return (await res.json());
+    }
+}
+exports.ConsoleTelemetryClient = ConsoleTelemetryClient;

package/dist/default-registry.d.ts

@@ -0,0 +1,2 @@
+import type { PricingRegistry } from "./types";
+export declare const DEFAULT_REGISTRY: PricingRegistry;

package/dist/default-registry.js

@@ -0,0 +1,36 @@
+"use strict";
+// default-registry.ts — bundled offline fallback pricing registry.
+//
+// This is the compiled-in snapshot used when no live registry is configured
+// (TELEMETRY_PRICING_FILE / TELEMETRY_PRICING_URL). Keep in sync with the
+// authored source: flow-agents/scripts/telemetry/pricing.json. The live source
+// (file or URL) overrides this at runtime, so this only matters air-gapped.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REGISTRY = void 0;
+exports.DEFAULT_REGISTRY = {
+    schema_version: "2.0",
+    current_version: "2026-06-28",
+    source: "Anthropic public list pricing; cache multipliers per prompt-caching docs",
+    versions: {
+        "2026-06-28": {
+            effective_date: "2026-06-28",
+            currency: "USD",
+            unit: "per_1m_tokens",
+            cache_multipliers: { write_5m: 1.25, write_1h: 2.0, read: 0.1 },
+            models: {
+                "claude-fable-5": { input: 10.0, output: 50.0 },
+                "claude-mythos-5": { input: 10.0, output: 50.0 },
+                "claude-opus-4-8": { input: 5.0, output: 25.0 },
+                "claude-opus-4-7": { input: 5.0, output: 25.0 },
+                "claude-opus-4-6": { input: 5.0, output: 25.0 },
+                "claude-opus-4-5": { input: 5.0, output: 25.0 },
+                "claude-opus-4-1": { input: 15.0, output: 75.0 },
+                "claude-sonnet-4-6": { input: 3.0, output: 15.0 },
+                "claude-sonnet-4-5": { input: 3.0, output: 15.0 },
+                "claude-haiku-4-5": { input: 1.0, output: 5.0 }
+            },
+            default: { input: 5.0, output: 25.0 },
+            zero_cost_models: ["<synthetic>", "synthetic", "unknown", ""]
+        }
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { TokenCounts, TelemetryUsageTotals, TelemetryUsageBreakdown, CanonicalUsage, ModelRate, PricingCacheMultipliers, PricingVersionBlock, PricingRegistry } from "./types";
+export { DEFAULT_REGISTRY } from "./default-registry";
+export { refreshPricingFromUrl, setRegistry, getRegistry, currentPricingVersion, listPricingVersions, costForModel } from "./pricing";
+export { GEN_AI_SYSTEM, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_OPERATION_NAME, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, KONTOUR_CACHE_READ_TOKENS, KONTOUR_CACHE_CREATION_TOKENS, KONTOUR_COST_USD, KONTOUR_PRICING_VERSION, toOtelGenAIAttributes, fromOtelGenAIAttributes } from "./otel";
+export type { OtelAttributes } from "./otel";
+export { ConsoleTelemetryClient } from "./client";
+export type { TelemetryClientOptions } from "./client";

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleTelemetryClient = exports.fromOtelGenAIAttributes = exports.toOtelGenAIAttributes = exports.KONTOUR_PRICING_VERSION = exports.KONTOUR_COST_USD = exports.KONTOUR_CACHE_CREATION_TOKENS = exports.KONTOUR_CACHE_READ_TOKENS = exports.GEN_AI_USAGE_OUTPUT_TOKENS = exports.GEN_AI_USAGE_INPUT_TOKENS = exports.GEN_AI_OPERATION_NAME = exports.GEN_AI_RESPONSE_MODEL = exports.GEN_AI_REQUEST_MODEL = exports.GEN_AI_SYSTEM = exports.costForModel = exports.listPricingVersions = exports.currentPricingVersion = exports.getRegistry = exports.setRegistry = exports.refreshPricingFromUrl = exports.DEFAULT_REGISTRY = void 0;
+var default_registry_1 = require("./default-registry");
+Object.defineProperty(exports, "DEFAULT_REGISTRY", { enumerable: true, get: function () { return default_registry_1.DEFAULT_REGISTRY; } });
+var pricing_1 = require("./pricing");
+Object.defineProperty(exports, "refreshPricingFromUrl", { enumerable: true, get: function () { return pricing_1.refreshPricingFromUrl; } });
+Object.defineProperty(exports, "setRegistry", { enumerable: true, get: function () { return pricing_1.setRegistry; } });
+Object.defineProperty(exports, "getRegistry", { enumerable: true, get: function () { return pricing_1.getRegistry; } });
+Object.defineProperty(exports, "currentPricingVersion", { enumerable: true, get: function () { return pricing_1.currentPricingVersion; } });
+Object.defineProperty(exports, "listPricingVersions", { enumerable: true, get: function () { return pricing_1.listPricingVersions; } });
+Object.defineProperty(exports, "costForModel", { enumerable: true, get: function () { return pricing_1.costForModel; } });
+var otel_1 = require("./otel");
+Object.defineProperty(exports, "GEN_AI_SYSTEM", { enumerable: true, get: function () { return otel_1.GEN_AI_SYSTEM; } });
+Object.defineProperty(exports, "GEN_AI_REQUEST_MODEL", { enumerable: true, get: function () { return otel_1.GEN_AI_REQUEST_MODEL; } });
+Object.defineProperty(exports, "GEN_AI_RESPONSE_MODEL", { enumerable: true, get: function () { return otel_1.GEN_AI_RESPONSE_MODEL; } });
+Object.defineProperty(exports, "GEN_AI_OPERATION_NAME", { enumerable: true, get: function () { return otel_1.GEN_AI_OPERATION_NAME; } });
+Object.defineProperty(exports, "GEN_AI_USAGE_INPUT_TOKENS", { enumerable: true, get: function () { return otel_1.GEN_AI_USAGE_INPUT_TOKENS; } });
+Object.defineProperty(exports, "GEN_AI_USAGE_OUTPUT_TOKENS", { enumerable: true, get: function () { return otel_1.GEN_AI_USAGE_OUTPUT_TOKENS; } });
+Object.defineProperty(exports, "KONTOUR_CACHE_READ_TOKENS", { enumerable: true, get: function () { return otel_1.KONTOUR_CACHE_READ_TOKENS; } });
+Object.defineProperty(exports, "KONTOUR_CACHE_CREATION_TOKENS", { enumerable: true, get: function () { return otel_1.KONTOUR_CACHE_CREATION_TOKENS; } });
+Object.defineProperty(exports, "KONTOUR_COST_USD", { enumerable: true, get: function () { return otel_1.KONTOUR_COST_USD; } });
+Object.defineProperty(exports, "KONTOUR_PRICING_VERSION", { enumerable: true, get: function () { return otel_1.KONTOUR_PRICING_VERSION; } });
+Object.defineProperty(exports, "toOtelGenAIAttributes", { enumerable: true, get: function () { return otel_1.toOtelGenAIAttributes; } });
+Object.defineProperty(exports, "fromOtelGenAIAttributes", { enumerable: true, get: function () { return otel_1.fromOtelGenAIAttributes; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "ConsoleTelemetryClient", { enumerable: true, get: function () { return client_1.ConsoleTelemetryClient; } });

package/dist/otel.d.ts

@@ -0,0 +1,19 @@
+import type { CanonicalUsage } from "./types";
+export declare const GEN_AI_SYSTEM = "gen_ai.system";
+export declare const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+export declare const GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+export declare const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+export declare const GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+export declare const GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+export declare const KONTOUR_CACHE_READ_TOKENS = "gen_ai.usage.cache_read_input_tokens";
+export declare const KONTOUR_CACHE_CREATION_TOKENS = "gen_ai.usage.cache_creation_input_tokens";
+export declare const KONTOUR_COST_USD = "kontour.gen_ai.usage.cost_usd";
+export declare const KONTOUR_PRICING_VERSION = "kontour.gen_ai.pricing_version";
+export type OtelAttributes = Record<string, string | number | boolean>;
+/**
+ * Map a canonical usage block to OTel GenAI attributes. `system` is the runtime
+ * (e.g. "claude-code", "strands"). Cache tokens + cost ride as extension keys.
+ */
+export declare function toOtelGenAIAttributes(usage: CanonicalUsage, system?: string): OtelAttributes;
+/** Inverse: read a canonical usage block from OTel GenAI attributes (ingest interop). */
+export declare function fromOtelGenAIAttributes(attrs: OtelAttributes): CanonicalUsage;

package/dist/otel.js

@@ -0,0 +1,66 @@
+"use strict";
+// otel.ts — OpenTelemetry GenAI semantic-conventions mapping.
+//
+// Speak the standard at the boundary, keep the richer canonical model inside.
+// Core GenAI attributes (gen_ai.system, gen_ai.request.model,
+// gen_ai.usage.input_tokens/output_tokens) are stable; the broader GenAI
+// semconv is still experimental (Development status) as of 2026, so we map
+// conservatively. Cache tokens + cost are NOT in the standard — emitted as
+// clearly-namespaced extension attributes.
+// Ref: https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KONTOUR_PRICING_VERSION = exports.KONTOUR_COST_USD = exports.KONTOUR_CACHE_CREATION_TOKENS = exports.KONTOUR_CACHE_READ_TOKENS = exports.GEN_AI_USAGE_OUTPUT_TOKENS = exports.GEN_AI_USAGE_INPUT_TOKENS = exports.GEN_AI_OPERATION_NAME = exports.GEN_AI_RESPONSE_MODEL = exports.GEN_AI_REQUEST_MODEL = exports.GEN_AI_SYSTEM = void 0;
+exports.toOtelGenAIAttributes = toOtelGenAIAttributes;
+exports.fromOtelGenAIAttributes = fromOtelGenAIAttributes;
+// Stable / core GenAI attributes
+exports.GEN_AI_SYSTEM = "gen_ai.system";
+exports.GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+exports.GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+exports.GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+exports.GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+exports.GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+// Extension attributes (NOT in the GenAI semconv — Anthropic cache + cost).
+exports.KONTOUR_CACHE_READ_TOKENS = "gen_ai.usage.cache_read_input_tokens";
+exports.KONTOUR_CACHE_CREATION_TOKENS = "gen_ai.usage.cache_creation_input_tokens";
+exports.KONTOUR_COST_USD = "kontour.gen_ai.usage.cost_usd";
+exports.KONTOUR_PRICING_VERSION = "kontour.gen_ai.pricing_version";
+function n(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+/**
+ * Map a canonical usage block to OTel GenAI attributes. `system` is the runtime
+ * (e.g. "claude-code", "strands"). Cache tokens + cost ride as extension keys.
+ */
+function toOtelGenAIAttributes(usage, system) {
+    const attrs = {};
+    if (system)
+        attrs[exports.GEN_AI_SYSTEM] = system;
+    if (usage.model) {
+        attrs[exports.GEN_AI_REQUEST_MODEL] = usage.model;
+        attrs[exports.GEN_AI_RESPONSE_MODEL] = usage.model;
+    }
+    attrs[exports.GEN_AI_OPERATION_NAME] = "chat";
+    attrs[exports.GEN_AI_USAGE_INPUT_TOKENS] = n(usage.inputTokens);
+    attrs[exports.GEN_AI_USAGE_OUTPUT_TOKENS] = n(usage.outputTokens);
+    attrs[exports.KONTOUR_CACHE_READ_TOKENS] = n(usage.cacheReadInputTokens);
+    attrs[exports.KONTOUR_CACHE_CREATION_TOKENS] = n(usage.cacheCreationInputTokens);
+    if (typeof usage.estimatedCostUsd === "number")
+        attrs[exports.KONTOUR_COST_USD] = usage.estimatedCostUsd;
+    if (usage.pricingVersion)
+        attrs[exports.KONTOUR_PRICING_VERSION] = usage.pricingVersion;
+    return attrs;
+}
+/** Inverse: read a canonical usage block from OTel GenAI attributes (ingest interop). */
+function fromOtelGenAIAttributes(attrs) {
+    const num = (k) => (typeof attrs[k] === "number" ? attrs[k] : 0);
+    const str = (k) => (typeof attrs[k] === "string" ? attrs[k] : undefined);
+    return {
+        model: str(exports.GEN_AI_RESPONSE_MODEL) || str(exports.GEN_AI_REQUEST_MODEL),
+        inputTokens: num(exports.GEN_AI_USAGE_INPUT_TOKENS),
+        outputTokens: num(exports.GEN_AI_USAGE_OUTPUT_TOKENS),
+        cacheReadInputTokens: num(exports.KONTOUR_CACHE_READ_TOKENS),
+        cacheCreationInputTokens: num(exports.KONTOUR_CACHE_CREATION_TOKENS),
+        estimatedCostUsd: typeof attrs[exports.KONTOUR_COST_USD] === "number" ? attrs[exports.KONTOUR_COST_USD] : undefined,
+        pricingVersion: str(exports.KONTOUR_PRICING_VERSION)
+    };
+}

package/dist/pricing.d.ts

@@ -0,0 +1,13 @@
+import type { PricingRegistry, TokenCounts } from "./types";
+/** Replace the in-memory registry from a remote URL (single live source). */
+export declare function refreshPricingFromUrl(url?: string | undefined): Promise<boolean>;
+/** Replace the in-memory registry directly (e.g. console syncing from flow-agents). */
+export declare function setRegistry(registry: PricingRegistry): boolean;
+export declare function getRegistry(): PricingRegistry;
+export declare function currentPricingVersion(): string;
+export declare function listPricingVersions(): string[];
+/**
+ * Estimated USD cost for one model's token counts, priced against the given
+ * registry version (defaults to current). Cache writes assume the 5m TTL tier.
+ */
+export declare function costForModel(model: string | undefined, tokens: TokenCounts, version?: string): number;

package/dist/pricing.js

@@ -0,0 +1,103 @@
+"use strict";
+// pricing.ts — versioned pricing registry loader + cost recompute.
+//
+// Single source of truth for cost math. Resolution (init, synchronous):
+//   1. local file  TELEMETRY_PRICING_FILE / FLOW_AGENTS_PRICING_FILE
+//   2. bundled     DEFAULT_REGISTRY
+// Remote (TELEMETRY_PRICING_URL) is applied via async refreshPricingFromUrl()
+// — call it at server boot / on an interval. Tokens are the source of truth;
+// cost is derived here against an explicit version (defaults to current), so a
+// session priced at emit can be reproduced or recomputed against any version.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshPricingFromUrl = refreshPricingFromUrl;
+exports.setRegistry = setRegistry;
+exports.getRegistry = getRegistry;
+exports.currentPricingVersion = currentPricingVersion;
+exports.listPricingVersions = listPricingVersions;
+exports.costForModel = costForModel;
+const fs = require("node:fs");
+const default_registry_1 = require("./default-registry");
+function isRegistry(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        typeof value.current_version === "string" &&
+        value.versions &&
+        typeof value.versions === "object");
+}
+function loadRegistrySync() {
+    const envPath = process.env.TELEMETRY_PRICING_FILE || process.env.FLOW_AGENTS_PRICING_FILE;
+    if (envPath) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(envPath, "utf8"));
+            if (isRegistry(parsed))
+                return parsed;
+        }
+        catch {
+            // fall through to bundled
+        }
+    }
+    return default_registry_1.DEFAULT_REGISTRY;
+}
+let REGISTRY = loadRegistrySync();
+/** Replace the in-memory registry from a remote URL (single live source). */
+async function refreshPricingFromUrl(url = process.env.TELEMETRY_PRICING_URL || process.env.FLOW_AGENTS_PRICING_URL) {
+    if (!url)
+        return false;
+    try {
+        const res = await fetch(url);
+        if (!res.ok)
+            return false;
+        const parsed = await res.json();
+        if (isRegistry(parsed)) {
+            REGISTRY = parsed;
+            return true;
+        }
+    }
+    catch {
+        // keep current registry on any failure
+    }
+    return false;
+}
+/** Replace the in-memory registry directly (e.g. console syncing from flow-agents). */
+function setRegistry(registry) {
+    if (!isRegistry(registry))
+        return false;
+    REGISTRY = registry;
+    return true;
+}
+function getRegistry() {
+    return REGISTRY;
+}
+function currentPricingVersion() {
+    return REGISTRY.current_version;
+}
+function listPricingVersions() {
+    return Object.keys(REGISTRY.versions || {});
+}
+function versionBlock(version) {
+    const versions = REGISTRY.versions || {};
+    return (versions[version || REGISTRY.current_version] ||
+        versions[REGISTRY.current_version] ||
+        default_registry_1.DEFAULT_REGISTRY.versions[default_registry_1.DEFAULT_REGISTRY.current_version]);
+}
+function round6(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+/**
+ * Estimated USD cost for one model's token counts, priced against the given
+ * registry version (defaults to current). Cache writes assume the 5m TTL tier.
+ */
+function costForModel(model, tokens, version) {
+    const block = versionBlock(version);
+    const key = (model || "").trim();
+    if (block.zero_cost_models.includes(key))
+        return 0;
+    const rate = block.models[key] || block.default;
+    const cm = block.cache_multipliers;
+    const cost = (tokens.inputTokens * rate.input +
+        tokens.outputTokens * rate.output +
+        tokens.cacheCreationInputTokens * rate.input * cm.write_5m +
+        tokens.cacheReadInputTokens * rate.input * cm.read) /
+        1_000_000;
+    return round6(cost);
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export interface TokenCounts {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+}
+export interface TelemetryUsageTotals extends TokenCounts {
+    totalTokens: number;
+    estimatedCostUsd: number;
+}
+export interface TelemetryUsageBreakdown extends TelemetryUsageTotals {
+    key: string;
+    label: string;
+}
+/** The `usage` block carried by a `session.usage` telemetry event. */
+export interface CanonicalUsage {
+    model?: string;
+    durationS?: number | null;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+    estimatedCostUsd?: number;
+    pricingVersion?: string;
+    byModel?: Array<TokenCounts & {
+        model: string;
+        estimatedCostUsd?: number;
+    }>;
+}
+export interface ModelRate {
+    input: number;
+    output: number;
+}
+export interface PricingCacheMultipliers {
+    write_5m: number;
+    write_1h: number;
+    read: number;
+}
+export interface PricingVersionBlock {
+    effective_date?: string;
+    currency?: string;
+    unit?: string;
+    cache_multipliers: PricingCacheMultipliers;
+    models: Record<string, ModelRate>;
+    default: ModelRate;
+    zero_cost_models: string[];
+}
+export interface PricingRegistry {
+    schema_version?: string;
+    current_version: string;
+    source?: string;
+    versions: Record<string, PricingVersionBlock>;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+// types.ts — canonical telemetry + pricing contract shapes.
+//
+// One definition consumed by the console server (ingest/aggregation) and by
+// producers (flow-agents runtimes/sinks). Pricing has no industry standard, so
+// this is the controlled shape; telemetry maps to OpenTelemetry GenAI semconv
+// at the boundary (see otel.ts).
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kontourai/console-telemetry",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "description": "Canonical Kontour Console telemetry contract: event + pricing shapes, versioned pricing registry, OpenTelemetry GenAI mapping, and intake/pricing clients.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kontourai/console.git",
+    "directory": "console-telemetry"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}