@agentic-kit/metering 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+# @agentic-kit/metering
+
+Metering for an agent run: the Constructive gateway as a model endpoint, the run's identity headers, and usage reporting — none of it tied to a particular harness.
+
+A run's model calls have to end up in `inference_log` under the same identity as every other platform inference call. *How* a harness is told which endpoint to call is vendor-specific; *what* that endpoint is, and who the run is, is not. This package owns the second part, so an adapter is left with a translation:
+
+```
+resolveMeteredGateway({ gatewayUrl, identity, models })
+        │
+        └─► MeteredGateway ──► the harness's own provider config
+```
+
+## Install
+
+```sh
+npm install @agentic-kit/metering
+```
+
+## The two lanes
+
+| lane | authority |
+| --- | --- |
+| model calls leave through the gateway (`resolveMeteredGateway`) | the gateway — the agent cannot under-report |
+| the host owns the provider keys and reports afterwards (`UsageReporter`) | self-reported; good for reconciliation, not for billing |
+
+Cloud runs use the first. A laptop run on the user's own key uses the second.
+
+## Gateway
+
+```ts
+import { resolveMeteredGateway } from '@agentic-kit/metering';
+
+const gateway = resolveMeteredGateway({
+  gatewayUrl: 'https://agentic.example.com', // the gateway root, NOT the /v1 path
+  identity: {
+    databaseId: process.env.CONSTRUCTIVE_DATABASE_ID!,
+    entityId: process.env.CONSTRUCTIVE_OWNER_ID,
+    actorId: runActorId,
+    runToken // run-scoped, never an account token
+  },
+  models: [{ id: 'anthropic/claude-sonnet-4', contextWindow: 200000, maxTokens: 8192, input: ['text', 'image'] }]
+});
+```
+
+- **Identity** travels as `X-Database-Id` / `X-Entity-Id` / `X-Actor-Id`, the headers `agentic-server` already reads, plus `Authorization: Bearer <runToken>` when one is given. Extra `headers` are merged but can never shadow identity.
+- **Headers are only as trustworthy as the network.** In-cluster, or behind an ingress that pins identity from the bearer, they are authoritative; a host outside that boundary must send `runToken` and let the ingress pin it.
+- **Misconfiguration fails at construction**, not at the first turn: a blank `databaseId`, a relative or non-http `gatewayUrl`, a `gatewayUrl` already ending in `/v1` (harnesses append their own, so the request would 404), or an empty model list.
+- **Cost fields default to zero.** The gateway is the pricing authority; zeros mean "not priced client-side", not free.
+
+## Usage reporting
+
+```ts
+import { httpUsageSink, toUsageReport, UsageReporter } from '@agentic-kit/metering';
+
+const reporter = new UsageReporter({
+  identity,
+  sink: httpUsageSink({ gatewayUrl: 'https://agentic.example.com', identity })
+});
+
+reporter.enqueue(toUsageReport(message, identity));
+await reporter.flush();
+```
+
+`toUsageReport` reads a harness-neutral assistant-message slice (`provider`, `model`, token counts, `stopReason`), so an adapter passes its own message through without a translation layer. Reports queue and are drained on `flush()`, which a run's shutdown path awaits.
+
+## Testing
+
+`pnpm test` — gateway and identity resolution are asserted directly and the reporter is driven against a fake sink, so no gateway or model credentials are needed.
+
+## Related
+
+- `@agentic-kit/harness` — the neutral harness contracts (adapter, run gate, approvals)
+- `@agentic-kit/run-log` — the append-only run log
+- `@agentic-kit/pi` — the pi adapter, which turns a `MeteredGateway` into pi's provider config
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/gateway.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The metered gateway as a resolved model endpoint.
+ *
+ * `agentic-server` speaks OpenAI's `/v1/chat/completions`, so routing a harness
+ * through it needs no custom streaming code — only an endpoint whose `baseUrl` is
+ * the gateway and whose headers carry the run's identity. Every harness worth
+ * adapting can already talk to an OpenAI-compatible endpoint, which is why this
+ * resolution is neutral and only the registration is vendor-specific: an adapter
+ * turns `MeteredGateway` into whatever its harness calls a provider.
+ */
+import { type MeteredIdentity } from './identity';
+/** The api the gateway exposes. */
+export declare const GATEWAY_API = "openai-completions";
+/** Default provider name; also the prefix a model picker shows. */
+export declare const DEFAULT_PROVIDER_NAME = "constructive-gateway";
+/** Per-token cost, for client-side display only. */
+export interface MeteredModelCost {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+export interface MeteredModelSpec {
+    /** Model id as the gateway routes it, e.g. `anthropic/claude-sonnet-4`. */
+    id: string;
+    name?: string;
+    contextWindow: number;
+    maxTokens: number;
+    reasoning?: boolean;
+    input?: ('text' | 'image')[];
+    /**
+     * Per-token cost for the host's own display. The gateway is the billing
+     * authority, so zeros here mean "not priced client-side", never "free".
+     */
+    cost?: MeteredModelCost;
+}
+export interface MeteredGatewayOptions {
+    /** Gateway root, e.g. `https://agentic.example.com` — not a `/v1` path. */
+    gatewayUrl: string;
+    identity: MeteredIdentity;
+    models: readonly MeteredModelSpec[];
+    /** Provider name to register under. Defaults to `constructive-gateway`. */
+    providerName?: string;
+    /** Display name in the host's UI. */
+    displayName?: string;
+    /** Extra headers, e.g. `X-LLM-Provider` to pin the upstream provider. */
+    headers?: Record<string, string>;
+    /**
+     * API key for the gateway itself. Identity travels in headers, so this is
+     * usually unnecessary; when the ingress wants a bearer, prefer
+     * `identity.runToken`.
+     */
+    apiKey?: string;
+}
+/** A gateway endpoint an adapter can register with its harness. */
+export interface MeteredGateway {
+    providerName: string;
+    displayName: string;
+    baseUrl: string;
+    api: typeof GATEWAY_API;
+    headers: Record<string, string>;
+    apiKey: string;
+    models: readonly MeteredModel[];
+}
+/** A model as the gateway serves it, with every default resolved. */
+export interface MeteredModel {
+    id: string;
+    name: string;
+    reasoning: boolean;
+    input: ('text' | 'image')[];
+    cost: MeteredModelCost;
+    contextWindow: number;
+    maxTokens: number;
+}
+/** Normalize the gateway root: absolute http(s), no trailing slash, no `/v1`. */
+export declare function normalizeGatewayUrl(gatewayUrl: string): string;
+export declare function resolveMeteredModel(spec: MeteredModelSpec): MeteredModel;
+/**
+ * Resolve the gateway endpoint for a run.
+ *
+ * Identity headers are computed once here rather than per request: a run's
+ * identity is fixed for its lifetime, and harnesses generally expose no
+ * per-request header hook a provider registration participates in.
+ */
+export declare function resolveMeteredGateway(options: MeteredGatewayOptions): MeteredGateway;

package/esm/gateway.js

@@ -0,0 +1,76 @@
+/**
+ * The metered gateway as a resolved model endpoint.
+ *
+ * `agentic-server` speaks OpenAI's `/v1/chat/completions`, so routing a harness
+ * through it needs no custom streaming code — only an endpoint whose `baseUrl` is
+ * the gateway and whose headers carry the run's identity. Every harness worth
+ * adapting can already talk to an OpenAI-compatible endpoint, which is why this
+ * resolution is neutral and only the registration is vendor-specific: an adapter
+ * turns `MeteredGateway` into whatever its harness calls a provider.
+ */
+import { buildIdentityHeaders } from './identity';
+/** The api the gateway exposes. */
+export const GATEWAY_API = 'openai-completions';
+/** Default provider name; also the prefix a model picker shows. */
+export const DEFAULT_PROVIDER_NAME = 'constructive-gateway';
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+/** Normalize the gateway root: absolute http(s), no trailing slash, no `/v1`. */
+export function normalizeGatewayUrl(gatewayUrl) {
+    const raw = gatewayUrl?.trim();
+    if (!raw)
+        throw new Error('metered model: gatewayUrl is required');
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`metered model: gatewayUrl must be an absolute URL, got ${raw}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`metered model: gatewayUrl must be http(s), got ${parsed.protocol}`);
+    }
+    const path = parsed.pathname.replace(/\/+$/, '');
+    // An OpenAI-compatible client appends `/v1/chat/completions`, so a baseUrl that
+    // already ends in `/v1` would request `/v1/v1/chat/completions` and 404 at the
+    // first model turn.
+    if (/\/v1$/.test(path))
+        throw new Error(`metered model: gatewayUrl must be the gateway root, not ${raw} (drop the /v1)`);
+    return `${parsed.origin}${path}`;
+}
+export function resolveMeteredModel(spec) {
+    if (!spec.id?.trim())
+        throw new Error('metered model: model id is required');
+    return {
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        reasoning: spec.reasoning ?? false,
+        input: spec.input ? [...spec.input] : ['text'],
+        cost: spec.cost ?? { ...ZERO_COST },
+        contextWindow: spec.contextWindow,
+        maxTokens: spec.maxTokens
+    };
+}
+/**
+ * Resolve the gateway endpoint for a run.
+ *
+ * Identity headers are computed once here rather than per request: a run's
+ * identity is fixed for its lifetime, and harnesses generally expose no
+ * per-request header hook a provider registration participates in.
+ */
+export function resolveMeteredGateway(options) {
+    if (options.models.length === 0)
+        throw new Error('metered model: at least one model is required');
+    const headers = { ...options.headers, ...buildIdentityHeaders(options.identity) };
+    return {
+        providerName: options.providerName ?? DEFAULT_PROVIDER_NAME,
+        displayName: options.displayName ?? 'Constructive (metered)',
+        baseUrl: normalizeGatewayUrl(options.gatewayUrl),
+        api: GATEWAY_API,
+        headers,
+        // Harnesses typically require an apiKey once models are declared; the gateway
+        // authenticates by identity headers, so a placeholder satisfies that
+        // validation without implying a real secret.
+        apiKey: options.apiKey ?? headers.Authorization?.replace(/^Bearer /, '') ?? 'unused',
+        models: options.models.map(resolveMeteredModel)
+    };
+}

package/esm/identity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Who a metered request belongs to.
+ *
+ * These are exactly the headers `agentic-server` reads (`X-Database-Id`,
+ * `X-Entity-Id`, `X-Actor-Id`) — the same identity lane the platform's own
+ * clients use — so a pi session lands in `inference_log` beside every other
+ * metered call rather than in a parallel accounting scheme.
+ *
+ * Headers are only trustworthy where the gateway is not reachable by the
+ * untrusted party: in-cluster, or behind an authenticated ingress that pins the
+ * identity from the bearer. Off-cluster hosts must send `runToken` and let the
+ * ingress do the pinning.
+ */
+export interface MeteredIdentity {
+    /** Tenant database the usage is billed to. Required by the gateway. */
+    databaseId: string;
+    /** Owning entity (organization/user) when the platform tracks one. */
+    entityId?: string;
+    /** The actor on whose behalf the run executes. */
+    actorId?: string;
+    /**
+     * Bearer token for the gateway's ingress — run-scoped, not an account token.
+     * Sent as `Authorization: Bearer <token>`.
+     */
+    runToken?: string;
+}
+export declare const DATABASE_ID_HEADER = "X-Database-Id";
+export declare const ENTITY_ID_HEADER = "X-Entity-Id";
+export declare const ACTOR_ID_HEADER = "X-Actor-Id";
+/**
+ * Build the identity headers for a metered request.
+ *
+ * Throws on a missing/blank `databaseId`: the gateway would reject the call with
+ * a 400 at the first model turn, which surfaces as an opaque agent failure much
+ * later than the misconfiguration.
+ */
+export declare function buildIdentityHeaders(identity: MeteredIdentity): Record<string, string>;

package/esm/identity.js

@@ -0,0 +1,39 @@
+/**
+ * Who a metered request belongs to.
+ *
+ * These are exactly the headers `agentic-server` reads (`X-Database-Id`,
+ * `X-Entity-Id`, `X-Actor-Id`) — the same identity lane the platform's own
+ * clients use — so a pi session lands in `inference_log` beside every other
+ * metered call rather than in a parallel accounting scheme.
+ *
+ * Headers are only trustworthy where the gateway is not reachable by the
+ * untrusted party: in-cluster, or behind an authenticated ingress that pins the
+ * identity from the bearer. Off-cluster hosts must send `runToken` and let the
+ * ingress do the pinning.
+ */
+export const DATABASE_ID_HEADER = 'X-Database-Id';
+export const ENTITY_ID_HEADER = 'X-Entity-Id';
+export const ACTOR_ID_HEADER = 'X-Actor-Id';
+/**
+ * Build the identity headers for a metered request.
+ *
+ * Throws on a missing/blank `databaseId`: the gateway would reject the call with
+ * a 400 at the first model turn, which surfaces as an opaque agent failure much
+ * later than the misconfiguration.
+ */
+export function buildIdentityHeaders(identity) {
+    const databaseId = identity.databaseId?.trim();
+    if (!databaseId)
+        throw new Error('metered model: identity.databaseId is required');
+    const headers = { [DATABASE_ID_HEADER]: databaseId };
+    const entityId = identity.entityId?.trim();
+    if (entityId)
+        headers[ENTITY_ID_HEADER] = entityId;
+    const actorId = identity.actorId?.trim();
+    if (actorId)
+        headers[ACTOR_ID_HEADER] = actorId;
+    const runToken = identity.runToken?.trim();
+    if (runToken)
+        headers.Authorization = `Bearer ${runToken}`;
+    return headers;
+}

package/esm/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@agentic-kit/metering` — harness-neutral metering for an agent run: the
+ * Constructive gateway as a resolved model endpoint, the run identity that
+ * travels with every call, and the `/v1/usage` report a self-reporting run
+ * delivers.
+ *
+ * No harness SDK is imported here. An adapter registers `MeteredGateway` with
+ * its own harness and feeds `toUsageReport()` from its own message events.
+ */
+export { DEFAULT_PROVIDER_NAME, GATEWAY_API, type MeteredGateway, type MeteredGatewayOptions, type MeteredModel, type MeteredModelCost, type MeteredModelSpec, normalizeGatewayUrl, resolveMeteredGateway, resolveMeteredModel } from './gateway';
+export { ACTOR_ID_HEADER, buildIdentityHeaders, DATABASE_ID_HEADER, ENTITY_ID_HEADER, type MeteredIdentity } from './identity';
+export { httpUsageSink, type HttpUsageSinkOptions, UsageReporter, type UsageReporterOptions, type UsageSink } from './reporter';
+export { type AssistantUsageMessage, isAssistantMessage, toUsageReport, type ToUsageReportOptions, type UsageReport } from './usage-report';

package/esm/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@agentic-kit/metering` — harness-neutral metering for an agent run: the
+ * Constructive gateway as a resolved model endpoint, the run identity that
+ * travels with every call, and the `/v1/usage` report a self-reporting run
+ * delivers.
+ *
+ * No harness SDK is imported here. An adapter registers `MeteredGateway` with
+ * its own harness and feeds `toUsageReport()` from its own message events.
+ */
+export { DEFAULT_PROVIDER_NAME, GATEWAY_API, normalizeGatewayUrl, resolveMeteredGateway, resolveMeteredModel } from './gateway';
+export { ACTOR_ID_HEADER, buildIdentityHeaders, DATABASE_ID_HEADER, ENTITY_ID_HEADER } from './identity';
+export { httpUsageSink, UsageReporter } from './reporter';
+export { isAssistantMessage, toUsageReport } from './usage-report';

package/esm/reporter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Delivery of usage reports: a serialized queue plus the default HTTP sink.
+ *
+ * Reports are queued rather than awaited inside the harness's event handler — a
+ * network round trip per assistant message would sit directly in the agent's turn
+ * latency. Failures are therefore not lost: the first one is kept and rethrown
+ * from `flush()`, so a host that flushes at shutdown still fails loudly.
+ */
+import { type MeteredIdentity } from './identity';
+import type { UsageReport } from './usage-report';
+export type UsageSink = (report: UsageReport) => Promise<void>;
+export interface HttpUsageSinkOptions {
+    /** Gateway root; `/v1/usage` is appended. */
+    gatewayUrl: string;
+    identity: MeteredIdentity;
+    /** Injectable for tests and for hosts with a custom agent/proxy. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare function httpUsageSink(options: HttpUsageSinkOptions): UsageSink;
+export interface UsageReporterOptions {
+    sink: UsageSink;
+    /** Called instead of retaining the error for `flush()` to rethrow. */
+    onError?: (error: unknown, report: UsageReport) => void;
+}
+export declare class UsageReporter {
+    private readonly sink;
+    private readonly onError;
+    private tail;
+    private failure;
+    private sent;
+    constructor(options: UsageReporterOptions);
+    /** Reports delivered successfully so far. */
+    get delivered(): number;
+    /** Queue a report. Never rejects; the failure surfaces from `flush()`. */
+    enqueue(report: UsageReport): void;
+    /** Wait for the queue to drain, then rethrow the first retained failure. */
+    flush(): Promise<void>;
+}

package/esm/reporter.js

@@ -0,0 +1,67 @@
+/**
+ * Delivery of usage reports: a serialized queue plus the default HTTP sink.
+ *
+ * Reports are queued rather than awaited inside the harness's event handler — a
+ * network round trip per assistant message would sit directly in the agent's turn
+ * latency. Failures are therefore not lost: the first one is kept and rethrown
+ * from `flush()`, so a host that flushes at shutdown still fails loudly.
+ */
+import { normalizeGatewayUrl } from './gateway';
+import { buildIdentityHeaders } from './identity';
+export function httpUsageSink(options) {
+    const url = `${normalizeGatewayUrl(options.gatewayUrl)}/v1/usage`;
+    const headers = { 'Content-Type': 'application/json', ...buildIdentityHeaders(options.identity) };
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (!doFetch)
+        throw new Error('usage report: no fetch implementation available; pass options.fetch');
+    return async (report) => {
+        const response = await doFetch(url, { method: 'POST', headers, body: JSON.stringify(report) });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`usage report: gateway rejected the report (${response.status}) ${body}`.trim());
+        }
+    };
+}
+export class UsageReporter {
+    sink;
+    onError;
+    tail = Promise.resolve();
+    failure;
+    sent = 0;
+    constructor(options) {
+        this.sink = options.sink;
+        this.onError = options.onError;
+    }
+    /** Reports delivered successfully so far. */
+    get delivered() {
+        return this.sent;
+    }
+    /** Queue a report. Never rejects; the failure surfaces from `flush()`. */
+    enqueue(report) {
+        this.tail = this.tail.then(async () => {
+            try {
+                await this.sink(report);
+                this.sent += 1;
+            }
+            catch (error) {
+                if (this.onError) {
+                    this.onError(error, report);
+                    return;
+                }
+                // Keep the first failure: it is the one with the original cause, and a
+                // later cascade usually says less about what broke.
+                if (this.failure === undefined)
+                    this.failure = error;
+            }
+        });
+    }
+    /** Wait for the queue to drain, then rethrow the first retained failure. */
+    async flush() {
+        await this.tail;
+        const failure = this.failure;
+        if (failure !== undefined) {
+            this.failure = undefined;
+            throw failure;
+        }
+    }
+}

package/esm/usage-report.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turn an assistant message's usage into a `POST /v1/usage` body.
+ *
+ * A harness reports richer usage than the gateway's own proxy path sees — cache
+ * reads, cache writes, and its own cost breakdown — so the whole `usage` object is
+ * sent as `raw_usage` while the four scalar columns carry what billing
+ * aggregates.
+ */
+/**
+ * The slice of an assistant message this module reads. An adapter maps its
+ * harness's message onto it; the field names are the ones every provider SDK
+ * already uses.
+ */
+export interface AssistantUsageMessage {
+    role: string;
+    provider?: string;
+    model?: string;
+    responseModel?: string;
+    responseId?: string;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        totalTokens?: number;
+        cost?: Record<string, number>;
+    };
+}
+/** The gateway's `/v1/usage` payload (snake_case, as the endpoint reads it). */
+export interface UsageReport {
+    model: string;
+    provider: string;
+    service: 'chat';
+    operation: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    latency_ms: number;
+    status: 'ok' | 'error';
+    error_type?: string;
+    raw_usage?: unknown;
+}
+export interface ToUsageReportOptions {
+    /** Free-form label for the row; defaults to `agent/chat`. */
+    operation?: string;
+    /** Turn latency, when the host measured it. */
+    latencyMs?: number;
+}
+export declare function isAssistantMessage(message: unknown): message is AssistantUsageMessage;
+/**
+ * `undefined` when the message carries no usage at all (aborted before the
+ * provider answered), which is a row worth nothing rather than a row of zeros.
+ */
+export declare function toUsageReport(message: AssistantUsageMessage, options?: ToUsageReportOptions): UsageReport | undefined;

package/esm/usage-report.js

@@ -0,0 +1,48 @@
+/**
+ * Turn an assistant message's usage into a `POST /v1/usage` body.
+ *
+ * A harness reports richer usage than the gateway's own proxy path sees — cache
+ * reads, cache writes, and its own cost breakdown — so the whole `usage` object is
+ * sent as `raw_usage` while the four scalar columns carry what billing
+ * aggregates.
+ */
+export function isAssistantMessage(message) {
+    return typeof message === 'object' && message !== null && message.role === 'assistant';
+}
+/**
+ * `undefined` when the message carries no usage at all (aborted before the
+ * provider answered), which is a row worth nothing rather than a row of zeros.
+ */
+export function toUsageReport(message, options = {}) {
+    const usage = message.usage;
+    if (!usage)
+        return undefined;
+    const input = num(usage.input);
+    const cacheRead = num(usage.cacheRead);
+    const cacheWrite = num(usage.cacheWrite);
+    const output = num(usage.output);
+    // Every prompt token the provider processed, cached or not: `input` alone
+    // excludes cache hits, which would under-report a long agent session
+    // dramatically. The split survives in `raw_usage`.
+    const inputTokens = input + cacheRead + cacheWrite;
+    const totalTokens = usage.totalTokens === undefined ? inputTokens + output : num(usage.totalTokens);
+    const failed = message.stopReason === 'error';
+    const report = {
+        model: message.responseModel ?? message.model ?? 'unknown',
+        provider: message.provider ?? 'unknown',
+        service: 'chat',
+        operation: options.operation ?? 'agent/chat',
+        input_tokens: inputTokens,
+        output_tokens: output,
+        total_tokens: totalTokens,
+        latency_ms: options.latencyMs === undefined ? 0 : Math.max(0, Math.round(options.latencyMs)),
+        status: failed ? 'error' : 'ok',
+        raw_usage: usage
+    };
+    if (failed)
+        report.error_type = message.errorMessage ?? 'error';
+    return report;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}

package/gateway.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The metered gateway as a resolved model endpoint.
+ *
+ * `agentic-server` speaks OpenAI's `/v1/chat/completions`, so routing a harness
+ * through it needs no custom streaming code — only an endpoint whose `baseUrl` is
+ * the gateway and whose headers carry the run's identity. Every harness worth
+ * adapting can already talk to an OpenAI-compatible endpoint, which is why this
+ * resolution is neutral and only the registration is vendor-specific: an adapter
+ * turns `MeteredGateway` into whatever its harness calls a provider.
+ */
+import { type MeteredIdentity } from './identity';
+/** The api the gateway exposes. */
+export declare const GATEWAY_API = "openai-completions";
+/** Default provider name; also the prefix a model picker shows. */
+export declare const DEFAULT_PROVIDER_NAME = "constructive-gateway";
+/** Per-token cost, for client-side display only. */
+export interface MeteredModelCost {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+export interface MeteredModelSpec {
+    /** Model id as the gateway routes it, e.g. `anthropic/claude-sonnet-4`. */
+    id: string;
+    name?: string;
+    contextWindow: number;
+    maxTokens: number;
+    reasoning?: boolean;
+    input?: ('text' | 'image')[];
+    /**
+     * Per-token cost for the host's own display. The gateway is the billing
+     * authority, so zeros here mean "not priced client-side", never "free".
+     */
+    cost?: MeteredModelCost;
+}
+export interface MeteredGatewayOptions {
+    /** Gateway root, e.g. `https://agentic.example.com` — not a `/v1` path. */
+    gatewayUrl: string;
+    identity: MeteredIdentity;
+    models: readonly MeteredModelSpec[];
+    /** Provider name to register under. Defaults to `constructive-gateway`. */
+    providerName?: string;
+    /** Display name in the host's UI. */
+    displayName?: string;
+    /** Extra headers, e.g. `X-LLM-Provider` to pin the upstream provider. */
+    headers?: Record<string, string>;
+    /**
+     * API key for the gateway itself. Identity travels in headers, so this is
+     * usually unnecessary; when the ingress wants a bearer, prefer
+     * `identity.runToken`.
+     */
+    apiKey?: string;
+}
+/** A gateway endpoint an adapter can register with its harness. */
+export interface MeteredGateway {
+    providerName: string;
+    displayName: string;
+    baseUrl: string;
+    api: typeof GATEWAY_API;
+    headers: Record<string, string>;
+    apiKey: string;
+    models: readonly MeteredModel[];
+}
+/** A model as the gateway serves it, with every default resolved. */
+export interface MeteredModel {
+    id: string;
+    name: string;
+    reasoning: boolean;
+    input: ('text' | 'image')[];
+    cost: MeteredModelCost;
+    contextWindow: number;
+    maxTokens: number;
+}
+/** Normalize the gateway root: absolute http(s), no trailing slash, no `/v1`. */
+export declare function normalizeGatewayUrl(gatewayUrl: string): string;
+export declare function resolveMeteredModel(spec: MeteredModelSpec): MeteredModel;
+/**
+ * Resolve the gateway endpoint for a run.
+ *
+ * Identity headers are computed once here rather than per request: a run's
+ * identity is fixed for its lifetime, and harnesses generally expose no
+ * per-request header hook a provider registration participates in.
+ */
+export declare function resolveMeteredGateway(options: MeteredGatewayOptions): MeteredGateway;

package/gateway.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * The metered gateway as a resolved model endpoint.
+ *
+ * `agentic-server` speaks OpenAI's `/v1/chat/completions`, so routing a harness
+ * through it needs no custom streaming code — only an endpoint whose `baseUrl` is
+ * the gateway and whose headers carry the run's identity. Every harness worth
+ * adapting can already talk to an OpenAI-compatible endpoint, which is why this
+ * resolution is neutral and only the registration is vendor-specific: an adapter
+ * turns `MeteredGateway` into whatever its harness calls a provider.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROVIDER_NAME = exports.GATEWAY_API = void 0;
+exports.normalizeGatewayUrl = normalizeGatewayUrl;
+exports.resolveMeteredModel = resolveMeteredModel;
+exports.resolveMeteredGateway = resolveMeteredGateway;
+const identity_1 = require("./identity");
+/** The api the gateway exposes. */
+exports.GATEWAY_API = 'openai-completions';
+/** Default provider name; also the prefix a model picker shows. */
+exports.DEFAULT_PROVIDER_NAME = 'constructive-gateway';
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+/** Normalize the gateway root: absolute http(s), no trailing slash, no `/v1`. */
+function normalizeGatewayUrl(gatewayUrl) {
+    const raw = gatewayUrl?.trim();
+    if (!raw)
+        throw new Error('metered model: gatewayUrl is required');
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`metered model: gatewayUrl must be an absolute URL, got ${raw}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`metered model: gatewayUrl must be http(s), got ${parsed.protocol}`);
+    }
+    const path = parsed.pathname.replace(/\/+$/, '');
+    // An OpenAI-compatible client appends `/v1/chat/completions`, so a baseUrl that
+    // already ends in `/v1` would request `/v1/v1/chat/completions` and 404 at the
+    // first model turn.
+    if (/\/v1$/.test(path))
+        throw new Error(`metered model: gatewayUrl must be the gateway root, not ${raw} (drop the /v1)`);
+    return `${parsed.origin}${path}`;
+}
+function resolveMeteredModel(spec) {
+    if (!spec.id?.trim())
+        throw new Error('metered model: model id is required');
+    return {
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        reasoning: spec.reasoning ?? false,
+        input: spec.input ? [...spec.input] : ['text'],
+        cost: spec.cost ?? { ...ZERO_COST },
+        contextWindow: spec.contextWindow,
+        maxTokens: spec.maxTokens
+    };
+}
+/**
+ * Resolve the gateway endpoint for a run.
+ *
+ * Identity headers are computed once here rather than per request: a run's
+ * identity is fixed for its lifetime, and harnesses generally expose no
+ * per-request header hook a provider registration participates in.
+ */
+function resolveMeteredGateway(options) {
+    if (options.models.length === 0)
+        throw new Error('metered model: at least one model is required');
+    const headers = { ...options.headers, ...(0, identity_1.buildIdentityHeaders)(options.identity) };
+    return {
+        providerName: options.providerName ?? exports.DEFAULT_PROVIDER_NAME,
+        displayName: options.displayName ?? 'Constructive (metered)',
+        baseUrl: normalizeGatewayUrl(options.gatewayUrl),
+        api: exports.GATEWAY_API,
+        headers,
+        // Harnesses typically require an apiKey once models are declared; the gateway
+        // authenticates by identity headers, so a placeholder satisfies that
+        // validation without implying a real secret.
+        apiKey: options.apiKey ?? headers.Authorization?.replace(/^Bearer /, '') ?? 'unused',
+        models: options.models.map(resolveMeteredModel)
+    };
+}

package/identity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Who a metered request belongs to.
+ *
+ * These are exactly the headers `agentic-server` reads (`X-Database-Id`,
+ * `X-Entity-Id`, `X-Actor-Id`) — the same identity lane the platform's own
+ * clients use — so a pi session lands in `inference_log` beside every other
+ * metered call rather than in a parallel accounting scheme.
+ *
+ * Headers are only trustworthy where the gateway is not reachable by the
+ * untrusted party: in-cluster, or behind an authenticated ingress that pins the
+ * identity from the bearer. Off-cluster hosts must send `runToken` and let the
+ * ingress do the pinning.
+ */
+export interface MeteredIdentity {
+    /** Tenant database the usage is billed to. Required by the gateway. */
+    databaseId: string;
+    /** Owning entity (organization/user) when the platform tracks one. */
+    entityId?: string;
+    /** The actor on whose behalf the run executes. */
+    actorId?: string;
+    /**
+     * Bearer token for the gateway's ingress — run-scoped, not an account token.
+     * Sent as `Authorization: Bearer <token>`.
+     */
+    runToken?: string;
+}
+export declare const DATABASE_ID_HEADER = "X-Database-Id";
+export declare const ENTITY_ID_HEADER = "X-Entity-Id";
+export declare const ACTOR_ID_HEADER = "X-Actor-Id";
+/**
+ * Build the identity headers for a metered request.
+ *
+ * Throws on a missing/blank `databaseId`: the gateway would reject the call with
+ * a 400 at the first model turn, which surfaces as an opaque agent failure much
+ * later than the misconfiguration.
+ */
+export declare function buildIdentityHeaders(identity: MeteredIdentity): Record<string, string>;

package/identity.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Who a metered request belongs to.
+ *
+ * These are exactly the headers `agentic-server` reads (`X-Database-Id`,
+ * `X-Entity-Id`, `X-Actor-Id`) — the same identity lane the platform's own
+ * clients use — so a pi session lands in `inference_log` beside every other
+ * metered call rather than in a parallel accounting scheme.
+ *
+ * Headers are only trustworthy where the gateway is not reachable by the
+ * untrusted party: in-cluster, or behind an authenticated ingress that pins the
+ * identity from the bearer. Off-cluster hosts must send `runToken` and let the
+ * ingress do the pinning.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTOR_ID_HEADER = exports.ENTITY_ID_HEADER = exports.DATABASE_ID_HEADER = void 0;
+exports.buildIdentityHeaders = buildIdentityHeaders;
+exports.DATABASE_ID_HEADER = 'X-Database-Id';
+exports.ENTITY_ID_HEADER = 'X-Entity-Id';
+exports.ACTOR_ID_HEADER = 'X-Actor-Id';
+/**
+ * Build the identity headers for a metered request.
+ *
+ * Throws on a missing/blank `databaseId`: the gateway would reject the call with
+ * a 400 at the first model turn, which surfaces as an opaque agent failure much
+ * later than the misconfiguration.
+ */
+function buildIdentityHeaders(identity) {
+    const databaseId = identity.databaseId?.trim();
+    if (!databaseId)
+        throw new Error('metered model: identity.databaseId is required');
+    const headers = { [exports.DATABASE_ID_HEADER]: databaseId };
+    const entityId = identity.entityId?.trim();
+    if (entityId)
+        headers[exports.ENTITY_ID_HEADER] = entityId;
+    const actorId = identity.actorId?.trim();
+    if (actorId)
+        headers[exports.ACTOR_ID_HEADER] = actorId;
+    const runToken = identity.runToken?.trim();
+    if (runToken)
+        headers.Authorization = `Bearer ${runToken}`;
+    return headers;
+}

package/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@agentic-kit/metering` — harness-neutral metering for an agent run: the
+ * Constructive gateway as a resolved model endpoint, the run identity that
+ * travels with every call, and the `/v1/usage` report a self-reporting run
+ * delivers.
+ *
+ * No harness SDK is imported here. An adapter registers `MeteredGateway` with
+ * its own harness and feeds `toUsageReport()` from its own message events.
+ */
+export { DEFAULT_PROVIDER_NAME, GATEWAY_API, type MeteredGateway, type MeteredGatewayOptions, type MeteredModel, type MeteredModelCost, type MeteredModelSpec, normalizeGatewayUrl, resolveMeteredGateway, resolveMeteredModel } from './gateway';
+export { ACTOR_ID_HEADER, buildIdentityHeaders, DATABASE_ID_HEADER, ENTITY_ID_HEADER, type MeteredIdentity } from './identity';
+export { httpUsageSink, type HttpUsageSinkOptions, UsageReporter, type UsageReporterOptions, type UsageSink } from './reporter';
+export { type AssistantUsageMessage, isAssistantMessage, toUsageReport, type ToUsageReportOptions, type UsageReport } from './usage-report';

package/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * `@agentic-kit/metering` — harness-neutral metering for an agent run: the
+ * Constructive gateway as a resolved model endpoint, the run identity that
+ * travels with every call, and the `/v1/usage` report a self-reporting run
+ * delivers.
+ *
+ * No harness SDK is imported here. An adapter registers `MeteredGateway` with
+ * its own harness and feeds `toUsageReport()` from its own message events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toUsageReport = exports.isAssistantMessage = exports.UsageReporter = exports.httpUsageSink = exports.ENTITY_ID_HEADER = exports.DATABASE_ID_HEADER = exports.buildIdentityHeaders = exports.ACTOR_ID_HEADER = exports.resolveMeteredModel = exports.resolveMeteredGateway = exports.normalizeGatewayUrl = exports.GATEWAY_API = exports.DEFAULT_PROVIDER_NAME = void 0;
+var gateway_1 = require("./gateway");
+Object.defineProperty(exports, "DEFAULT_PROVIDER_NAME", { enumerable: true, get: function () { return gateway_1.DEFAULT_PROVIDER_NAME; } });
+Object.defineProperty(exports, "GATEWAY_API", { enumerable: true, get: function () { return gateway_1.GATEWAY_API; } });
+Object.defineProperty(exports, "normalizeGatewayUrl", { enumerable: true, get: function () { return gateway_1.normalizeGatewayUrl; } });
+Object.defineProperty(exports, "resolveMeteredGateway", { enumerable: true, get: function () { return gateway_1.resolveMeteredGateway; } });
+Object.defineProperty(exports, "resolveMeteredModel", { enumerable: true, get: function () { return gateway_1.resolveMeteredModel; } });
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "ACTOR_ID_HEADER", { enumerable: true, get: function () { return identity_1.ACTOR_ID_HEADER; } });
+Object.defineProperty(exports, "buildIdentityHeaders", { enumerable: true, get: function () { return identity_1.buildIdentityHeaders; } });
+Object.defineProperty(exports, "DATABASE_ID_HEADER", { enumerable: true, get: function () { return identity_1.DATABASE_ID_HEADER; } });
+Object.defineProperty(exports, "ENTITY_ID_HEADER", { enumerable: true, get: function () { return identity_1.ENTITY_ID_HEADER; } });
+var reporter_1 = require("./reporter");
+Object.defineProperty(exports, "httpUsageSink", { enumerable: true, get: function () { return reporter_1.httpUsageSink; } });
+Object.defineProperty(exports, "UsageReporter", { enumerable: true, get: function () { return reporter_1.UsageReporter; } });
+var usage_report_1 = require("./usage-report");
+Object.defineProperty(exports, "isAssistantMessage", { enumerable: true, get: function () { return usage_report_1.isAssistantMessage; } });
+Object.defineProperty(exports, "toUsageReport", { enumerable: true, get: function () { return usage_report_1.toUsageReport; } });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@agentic-kit/metering",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "harness-neutral metering for an agent run — the Constructive gateway as a model endpoint, run identity headers, and usage reporting",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "agentic-kit",
+    "metering",
+    "usage",
+    "gateway",
+    "constructive"
+  ],
+  "gitHead": "44a670631c98f7174db0e4c25dc30a3c81fd4437"
+}

package/reporter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Delivery of usage reports: a serialized queue plus the default HTTP sink.
+ *
+ * Reports are queued rather than awaited inside the harness's event handler — a
+ * network round trip per assistant message would sit directly in the agent's turn
+ * latency. Failures are therefore not lost: the first one is kept and rethrown
+ * from `flush()`, so a host that flushes at shutdown still fails loudly.
+ */
+import { type MeteredIdentity } from './identity';
+import type { UsageReport } from './usage-report';
+export type UsageSink = (report: UsageReport) => Promise<void>;
+export interface HttpUsageSinkOptions {
+    /** Gateway root; `/v1/usage` is appended. */
+    gatewayUrl: string;
+    identity: MeteredIdentity;
+    /** Injectable for tests and for hosts with a custom agent/proxy. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare function httpUsageSink(options: HttpUsageSinkOptions): UsageSink;
+export interface UsageReporterOptions {
+    sink: UsageSink;
+    /** Called instead of retaining the error for `flush()` to rethrow. */
+    onError?: (error: unknown, report: UsageReport) => void;
+}
+export declare class UsageReporter {
+    private readonly sink;
+    private readonly onError;
+    private tail;
+    private failure;
+    private sent;
+    constructor(options: UsageReporterOptions);
+    /** Reports delivered successfully so far. */
+    get delivered(): number;
+    /** Queue a report. Never rejects; the failure surfaces from `flush()`. */
+    enqueue(report: UsageReport): void;
+    /** Wait for the queue to drain, then rethrow the first retained failure. */
+    flush(): Promise<void>;
+}

package/reporter.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Delivery of usage reports: a serialized queue plus the default HTTP sink.
+ *
+ * Reports are queued rather than awaited inside the harness's event handler — a
+ * network round trip per assistant message would sit directly in the agent's turn
+ * latency. Failures are therefore not lost: the first one is kept and rethrown
+ * from `flush()`, so a host that flushes at shutdown still fails loudly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageReporter = void 0;
+exports.httpUsageSink = httpUsageSink;
+const gateway_1 = require("./gateway");
+const identity_1 = require("./identity");
+function httpUsageSink(options) {
+    const url = `${(0, gateway_1.normalizeGatewayUrl)(options.gatewayUrl)}/v1/usage`;
+    const headers = { 'Content-Type': 'application/json', ...(0, identity_1.buildIdentityHeaders)(options.identity) };
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (!doFetch)
+        throw new Error('usage report: no fetch implementation available; pass options.fetch');
+    return async (report) => {
+        const response = await doFetch(url, { method: 'POST', headers, body: JSON.stringify(report) });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`usage report: gateway rejected the report (${response.status}) ${body}`.trim());
+        }
+    };
+}
+class UsageReporter {
+    sink;
+    onError;
+    tail = Promise.resolve();
+    failure;
+    sent = 0;
+    constructor(options) {
+        this.sink = options.sink;
+        this.onError = options.onError;
+    }
+    /** Reports delivered successfully so far. */
+    get delivered() {
+        return this.sent;
+    }
+    /** Queue a report. Never rejects; the failure surfaces from `flush()`. */
+    enqueue(report) {
+        this.tail = this.tail.then(async () => {
+            try {
+                await this.sink(report);
+                this.sent += 1;
+            }
+            catch (error) {
+                if (this.onError) {
+                    this.onError(error, report);
+                    return;
+                }
+                // Keep the first failure: it is the one with the original cause, and a
+                // later cascade usually says less about what broke.
+                if (this.failure === undefined)
+                    this.failure = error;
+            }
+        });
+    }
+    /** Wait for the queue to drain, then rethrow the first retained failure. */
+    async flush() {
+        await this.tail;
+        const failure = this.failure;
+        if (failure !== undefined) {
+            this.failure = undefined;
+            throw failure;
+        }
+    }
+}
+exports.UsageReporter = UsageReporter;

package/usage-report.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turn an assistant message's usage into a `POST /v1/usage` body.
+ *
+ * A harness reports richer usage than the gateway's own proxy path sees — cache
+ * reads, cache writes, and its own cost breakdown — so the whole `usage` object is
+ * sent as `raw_usage` while the four scalar columns carry what billing
+ * aggregates.
+ */
+/**
+ * The slice of an assistant message this module reads. An adapter maps its
+ * harness's message onto it; the field names are the ones every provider SDK
+ * already uses.
+ */
+export interface AssistantUsageMessage {
+    role: string;
+    provider?: string;
+    model?: string;
+    responseModel?: string;
+    responseId?: string;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        totalTokens?: number;
+        cost?: Record<string, number>;
+    };
+}
+/** The gateway's `/v1/usage` payload (snake_case, as the endpoint reads it). */
+export interface UsageReport {
+    model: string;
+    provider: string;
+    service: 'chat';
+    operation: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    latency_ms: number;
+    status: 'ok' | 'error';
+    error_type?: string;
+    raw_usage?: unknown;
+}
+export interface ToUsageReportOptions {
+    /** Free-form label for the row; defaults to `agent/chat`. */
+    operation?: string;
+    /** Turn latency, when the host measured it. */
+    latencyMs?: number;
+}
+export declare function isAssistantMessage(message: unknown): message is AssistantUsageMessage;
+/**
+ * `undefined` when the message carries no usage at all (aborted before the
+ * provider answered), which is a row worth nothing rather than a row of zeros.
+ */
+export declare function toUsageReport(message: AssistantUsageMessage, options?: ToUsageReportOptions): UsageReport | undefined;

package/usage-report.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Turn an assistant message's usage into a `POST /v1/usage` body.
+ *
+ * A harness reports richer usage than the gateway's own proxy path sees — cache
+ * reads, cache writes, and its own cost breakdown — so the whole `usage` object is
+ * sent as `raw_usage` while the four scalar columns carry what billing
+ * aggregates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAssistantMessage = isAssistantMessage;
+exports.toUsageReport = toUsageReport;
+function isAssistantMessage(message) {
+    return typeof message === 'object' && message !== null && message.role === 'assistant';
+}
+/**
+ * `undefined` when the message carries no usage at all (aborted before the
+ * provider answered), which is a row worth nothing rather than a row of zeros.
+ */
+function toUsageReport(message, options = {}) {
+    const usage = message.usage;
+    if (!usage)
+        return undefined;
+    const input = num(usage.input);
+    const cacheRead = num(usage.cacheRead);
+    const cacheWrite = num(usage.cacheWrite);
+    const output = num(usage.output);
+    // Every prompt token the provider processed, cached or not: `input` alone
+    // excludes cache hits, which would under-report a long agent session
+    // dramatically. The split survives in `raw_usage`.
+    const inputTokens = input + cacheRead + cacheWrite;
+    const totalTokens = usage.totalTokens === undefined ? inputTokens + output : num(usage.totalTokens);
+    const failed = message.stopReason === 'error';
+    const report = {
+        model: message.responseModel ?? message.model ?? 'unknown',
+        provider: message.provider ?? 'unknown',
+        service: 'chat',
+        operation: options.operation ?? 'agent/chat',
+        input_tokens: inputTokens,
+        output_tokens: output,
+        total_tokens: totalTokens,
+        latency_ms: options.latencyMs === undefined ? 0 : Math.max(0, Math.round(options.latencyMs)),
+        status: failed ? 'error' : 'ok',
+        raw_usage: usage
+    };
+    if (failed)
+        report.error_type = message.errorMessage ?? 'error';
+    return report;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}