@oh-my-pi/pi-ai 17.1.1 → 17.1.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [17.1.2] - 2026-07-24
+
+### Added
+
+- Added `GET /v1/usage/history` to the auth broker (recorded usage-limit snapshots with `sinceMs`/`provider` filters) and `AuthBrokerClient.fetchUsageHistory` — in broker deployments the broker host performs every upstream usage fetch, so its durable history is the only complete utilization record
+- Added per-client burn tracking to the auth broker: clients batch observed request usage per (provider, model) and flush it to `POST /v1/usage/observed` every 10 seconds (install id as client key, hostname as display name); the broker persists 5-minute buckets in `client_usage`/`clients` and serves aggregates from `GET /v1/usage/clients`. Brokers without the endpoint disable reporting for the process lifetime
+
+### Changed
+
+- Renamed the Z.AI feature quota row to `ZAI Zread Quota` (tier/id slug `zread`), replacing the 74-char `ZAI Web Search / Reader / Zread Quota (web-search-reader-zread)` title that wrapped `omp usage` rows
+
+### Fixed
+
+- Fixed every Claude (`anthropic-messages`) model on the `opencode-zen` provider failing with `401 Missing API key`: the gateway requires `x-api-key`, so `opencode-zen` now uses X-Api-Key auth like `opencode-go`/`umans` instead of bearer-only, and no longer sends the `context_management` field its Anthropic proxy rejects on thinking requests ([#6510](https://github.com/can1357/oh-my-pi/issues/6510)).
+- Fixed Anthropic native server-tool blocks being dropped from persisted assistant turns, preserving signed web-search continuations in their original response order ([#6495](https://github.com/can1357/oh-my-pi/issues/6495))
+
 ## [17.1.1] - 2026-07-24
 
 ### Added

package/dist/types/auth-broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredential } from "../auth-storage.js";
-import type { CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse, UsageStaleResponse } from "./types.js";
+import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
     url: string;
@@ -60,6 +60,17 @@ export declare class AuthBrokerClient {
         signal?: AbortSignal;
     }): AsyncGenerator<SnapshotStreamEvent>;
     fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
+    /** Recorded usage-limit snapshots from the broker host, oldest first. */
+    fetchUsageHistory(query?: {
+        sinceMs?: number;
+        provider?: string;
+    }, signal?: AbortSignal): Promise<UsageHistoryResponse>;
+    /** Report this client's batched observed request usage for per-install burn tracking. */
+    reportClientUsage(report: ClientUsageReportRequest, signal?: AbortSignal): Promise<ClientUsageReportResponse>;
+    /** Per-client token burn aggregates recorded by the broker host. */
+    fetchClientUsageSummary(query?: {
+        sinceMs?: number;
+    }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse>;
     notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
     refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;

package/dist/types/auth-broker/remote-store.d.ts

@@ -1,7 +1,7 @@
 import { type AuthCredential, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential, type StoredCredentialBlock } from "../auth-storage.js";
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { Provider } from "../types.js";
-import type { UsageReport } from "../usage.js";
+import type { ObservedUsageEntry, UsageReport } from "../usage.js";
 import { type AuthBrokerClient } from "./client.js";
 import type { SnapshotResponse } from "./types.js";
 /**
@@ -33,6 +33,8 @@ export interface RemoteAuthCredentialStoreOptions {
      * routing policy, not broker authorization.
      */
     accountPool?: AuthBrokerAccountPool;
+    /** Flush cadence for batched observed-usage reports. Default 10s. */
+    observedUsageFlushMs?: number;
 }
 export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     #private;
@@ -120,5 +122,12 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      */
     getUsageReport(provider: Provider, credential: OAuthCredential, signal?: AbortSignal): Promise<UsageReport | null>;
     ingestUsageReport(provider: Provider, credential: OAuthCredential, report: UsageReport): boolean;
+    /**
+     * Fold locally observed request usage into the pending report and schedule
+     * a flush. One `POST /v1/usage/observed` at most per flush interval; on
+     * failure the batch is retained and retried with the next flush. A 404
+     * (pre-endpoint broker) disables reporting for the life of this store.
+     */
+    recordObservedUsage(entries: ObservedUsageEntry[]): void;
     close(): void;
 }

package/dist/types/auth-broker/types.d.ts

@@ -6,7 +6,7 @@
  * credential expires or a 401 surfaces on a supposedly-fresh credential.
  */
 import type { AuthCredential, AuthCredentialSnapshot, AuthCredentialSnapshotEntry, StoredCredentialBlock } from "../auth-storage.js";
-import type { UsageReport } from "../usage.js";
+import type { ClientUsageClientSummary, ClientUsageReport, UsageHistoryEntry, UsageReport } from "../usage.js";
 /** GET /v1/healthz response body. */
 export interface HealthzResponse {
     ok: boolean;
@@ -34,6 +34,26 @@ export interface UsageResponse {
     generatedAt: number;
     reports: UsageReport[];
 }
+/**
+ * GET /v1/usage/history response body. Entries come from the broker host's
+ * durable `usage_history` — the broker performs every upstream usage fetch in
+ * broker deployments, so this is the only complete utilization record.
+ */
+export interface UsageHistoryResponse {
+    generatedAt: number;
+    entries: UsageHistoryEntry[];
+}
+/** POST /v1/usage/observed request body — one client's batched observed usage. */
+export type ClientUsageReportRequest = ClientUsageReport;
+/** POST /v1/usage/observed response body. */
+export interface ClientUsageReportResponse {
+    ok: boolean;
+}
+/** GET /v1/usage/clients response body — per-client token burn aggregates. */
+export interface ClientUsageSummaryResponse {
+    generatedAt: number;
+    clients: ClientUsageClientSummary[];
+}
 /** POST /v1/credential/:id/refresh response body. */
 export interface CredentialRefreshResponse {
     entry: AuthCredentialSnapshotEntry;

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -418,6 +418,61 @@ export declare const usageResponseSchema: import("arktype/internal/variants/obje
         raw?: unknown;
     }[];
 }, {}>;
+/** Broker `/v1/usage/history` response — recorded usage-limit snapshots, oldest first. */
+export declare const usageHistoryResponseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    generatedAt: number;
+    entries: {
+        recordedAt: number;
+        provider: string;
+        accountKey: string;
+        email?: string | undefined;
+        accountId?: string | undefined;
+        limitId: string;
+        label: string;
+        windowLabel?: string | undefined;
+        usedFraction?: number | undefined;
+        status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+        resetsAt?: number | undefined;
+    }[];
+}, {}>;
+/** Broker `POST /v1/usage/observed` request — one client's batched observed usage. */
+export declare const clientUsageReportRequestSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    installId: string;
+    hostname?: string | undefined;
+    entries: {
+        at: number;
+        provider: string;
+        model: string;
+        requests: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        costUsd: number;
+    }[];
+}, {}>;
+export declare const clientUsageReportResponseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    ok: boolean;
+}, {}>;
+/** Broker `GET /v1/usage/clients` response — per-client token burn aggregates. */
+export declare const clientUsageSummaryResponseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    generatedAt: number;
+    clients: {
+        installId: string;
+        hostname?: string | undefined;
+        firstSeen: number;
+        lastSeen: number;
+        providers: {
+            provider: string;
+            requests: number;
+            inputTokens: number;
+            outputTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+            costUsd: number;
+        }[];
+    }[];
+}, {}>;
 export declare const credentialRefreshResponseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     entry: {
         id: number;

package/dist/types/auth-storage.d.ts

@@ -11,7 +11,7 @@ import { Database } from "bun:sqlite";
 import type { ApiKeyResolver } from "./auth-retry.js";
 import type { OAuthAuthInfo, OAuthController, OAuthCredentials, OAuthProviderId } from "./registry/oauth/types.js";
 import type { Provider } from "./types.js";
-import type { CredentialRankingStrategy, UsageCostHistoryEntry, UsageCostHistoryQuery, UsageHistoryEntry, UsageHistoryQuery, UsageLogger, UsageProvider, UsageReport } from "./usage.js";
+import type { ClientUsageReport, ClientUsageSummary, CredentialRankingStrategy, ObservedUsageEntry, UsageCostHistoryEntry, UsageCostHistoryQuery, UsageHistoryEntry, UsageHistoryQuery, UsageLogger, UsageProvider, UsageReport } from "./usage.js";
 import { type CodexResetConsumeCode, type CodexResetCredit } from "./usage/openai-codex-reset.js";
 export type ApiKeyCredential = {
     type: "api_key";
@@ -281,6 +281,16 @@ export interface AuthCredentialStore {
     listUsageCosts?(query?: UsageCostHistoryQuery): UsageCostHistoryEntry[];
     /** Read recorded usage-limit snapshots, oldest first. */
     listUsageHistory?(query?: UsageHistoryQuery): UsageHistoryEntry[];
+    /**
+     * Client hook: forward locally observed request usage. Remote broker stores
+     * batch these to the broker so it can attribute token burn per install;
+     * local stores omit it and observation is skipped.
+     */
+    recordObservedUsage?(entries: ObservedUsageEntry[]): void;
+    /** Broker host: persist one client's observed-usage report. */
+    recordClientUsage?(report: ClientUsageReport): void;
+    /** Broker host: aggregate recorded per-client usage since a timestamp. */
+    getClientUsageSummary?(sinceMs: number): ClientUsageSummary;
     /**
      * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
      * it before the per-provider local refresh path. `RemoteAuthCredentialStore`
@@ -836,6 +846,28 @@ export declare class AuthStorage {
         recordedAt?: number;
         baseUrl?: string;
     }): boolean;
+    /**
+     * Forward one completed request's usage to the store's observer hook.
+     * Broker-backed stores batch these into per-install reports so the broker
+     * can track actual token burn per client; local stores have no hook and
+     * the call is a no-op.
+     */
+    recordObservedUsage(entry: {
+        provider: Provider;
+        model: string;
+        usage: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+        };
+        costUsd?: number;
+        at?: number;
+    }): void;
+    /** Broker host: persist one client's observed-usage report (per-install token burn). */
+    recordClientUsage(report: ClientUsageReport): boolean;
+    /** Broker host: aggregate recorded per-client usage since `sinceMs`. */
+    getClientUsageSummary(sinceMs: number): ClientUsageSummary;
     ingestUsageHeaders(provider: Provider, headers: Record<string, string>, options?: {
         sessionId?: string;
         baseUrl?: string;
@@ -1200,6 +1232,8 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     listUsageHistory(query?: UsageHistoryQuery): UsageHistoryEntry[];
     recordUsageCosts(entries: UsageCostHistoryEntry[]): void;
     listUsageCosts(query?: UsageCostHistoryQuery): UsageCostHistoryEntry[];
+    recordClientUsage(report: ClientUsageReport): void;
+    getClientUsageSummary(sinceMs: number): ClientUsageSummary;
     /**
      * Save OAuth credentials for a provider.
      * Preserves unrelated identities and replaces only the matching credential.

package/dist/types/providers/anthropic-wire.d.ts

@@ -57,6 +57,33 @@ export type ToolResultBlockParam = {
     is_error?: boolean;
     cache_control?: CacheControlEphemeral | null;
 };
+/** Anthropic-executed server tool call replayed inside an assistant turn. */
+export type ServerToolUseBlockParam = {
+    type: "server_tool_use";
+    id: string;
+    name: string;
+    input?: Record<string, unknown> | null;
+    [key: string]: unknown;
+};
+/** Web-search server-tool call whose matching result is replayable by omp. */
+export type WebSearchServerToolUseBlockParam = ServerToolUseBlockParam & {
+    name: "web_search";
+};
+/** Native web-search result replayed inside an assistant turn. */
+export type WebSearchToolResultBlockParam = {
+    type: "web_search_tool_result";
+    tool_use_id: string;
+    content: unknown;
+    [key: string]: unknown;
+};
+/** True for the complete native web-search history variants omp can replay. */
+export declare function isAnthropicWebSearchHistoryBlock(block: {
+    type: string;
+    name?: unknown;
+    id?: unknown;
+    tool_use_id?: unknown;
+    content?: unknown;
+}): block is WebSearchServerToolUseBlockParam | WebSearchToolResultBlockParam;
 export type ThinkingBlockParam = {
     type: "thinking";
     thinking: string;
@@ -81,7 +108,7 @@ export type FallbackBlockParam = {
         model: string;
     };
 };
-export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
+export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
 /**
  * A single conversation turn.
  *
@@ -257,7 +284,7 @@ export type ResponseContentBlock = {
     id: string;
     name: string;
     input?: Record<string, unknown> | null;
-} | {
+} | ServerToolUseBlockParam | WebSearchToolResultBlockParam | {
     type: "fallback";
     from: {
         model: string;

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

@@ -1,6 +1,6 @@
 import type { FetchImpl, Message, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types.js";
 import { type AnthropicFetchOptions, type AnthropicMessagesClientLike } from "./anthropic-client.js";
-import type { FallbackParam, MessageParam, TextBlockParam } from "./anthropic-wire.js";
+import { type FallbackParam, type MessageParam, type TextBlockParam } from "./anthropic-wire.js";
 export type AnthropicHeaderOptions = {
     apiKey: string;
     baseUrl?: string;

package/dist/types/types.d.ts

@@ -476,6 +476,25 @@ export interface AnthropicFallbackContent {
         model: string;
     };
 }
+/**
+ * Verbatim Anthropic web-search call/result retained for same-provider
+ * history replay. Other providers discard it in `transformMessages`.
+ */
+export interface AnthropicServerToolContent {
+    type: "anthropicServerTool";
+    block: {
+        type: "server_tool_use";
+        id: string;
+        name: "web_search";
+        input?: Record<string, unknown> | null;
+        [key: string]: unknown;
+    } | {
+        type: "web_search_tool_result";
+        tool_use_id: string;
+        content: unknown;
+        [key: string]: unknown;
+    };
+}
 export interface ImageContent {
     type: "image";
     data: string;
@@ -631,7 +650,7 @@ export interface ContextSnapshot {
 }
 export interface AssistantMessage {
     role: "assistant";
-    content: (TextContent | ThinkingContent | RedactedThinkingContent | AnthropicFallbackContent | ImageContent | ToolCall)[];
+    content: (TextContent | ThinkingContent | RedactedThinkingContent | AnthropicFallbackContent | AnthropicServerToolContent | ImageContent | ToolCall)[];
     api: Api;
     provider: Provider;
     model: string;

package/dist/types/usage.d.ts

@@ -156,6 +156,56 @@ export interface UsageCostHistoryQuery {
     /** Inclusive lower bound on {@link UsageCostHistoryEntry.recordedAt} (epoch ms). */
     sinceMs?: number;
 }
+/**
+ * Aggregated request usage a client observed for one (provider, model) pair.
+ * Clients fold every completed request into per-pair buckets and flush them to
+ * the auth broker on a short cadence, so the broker can attribute token burn
+ * to the install that produced it.
+ */
+export interface ObservedUsageEntry {
+    /** Epoch ms of the newest request folded into this bucket. */
+    at: number;
+    provider: Provider;
+    model: string;
+    /** Completed requests folded into this bucket. */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Estimated USD cost of the folded requests (0 when unknown). */
+    costUsd: number;
+}
+/** One client's observed-usage report, keyed by its stable install id. */
+export interface ClientUsageReport {
+    /** Stable per-machine install id — the client primary key. */
+    installId: string;
+    /** Human-readable machine name for display surfaces. */
+    hostname?: string;
+    entries: ObservedUsageEntry[];
+}
+/** Per-provider aggregate of one client's recorded usage. */
+export interface ClientProviderUsage {
+    provider: string;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costUsd: number;
+}
+/** One known client with its usage aggregates over the queried window. */
+export interface ClientUsageClientSummary {
+    installId: string;
+    hostname?: string;
+    firstSeen: number;
+    lastSeen: number;
+    providers: ClientProviderUsage[];
+}
+/** Aggregated per-client usage recorded by the broker host. */
+export interface ClientUsageSummary {
+    clients: ClientUsageClientSummary[];
+}
 export declare const usageUnitSchema: import("arktype/internal/variants/string.ts").StringType<"bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd", {}>;
 export declare const usageStatusSchema: import("arktype/internal/variants/string.ts").StringType<"exhausted" | "ok" | "unknown" | "warning", {}>;
 export declare const usageWindowSchema: import("arktype/internal/variants/object.ts").ObjectType<{

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.1.1",
+	"version": "17.1.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.1.1",
-		"@oh-my-pi/pi-utils": "17.1.1",
-		"@oh-my-pi/pi-wire": "17.1.1",
+		"@oh-my-pi/pi-catalog": "17.1.2",
+		"@oh-my-pi/pi-utils": "17.1.2",
+		"@oh-my-pi/pi-wire": "17.1.2",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},

package/src/auth-broker/client.ts

@@ -9,6 +9,9 @@ import { readSseEvents } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import type { AuthCredential } from "../auth-storage";
 import type {
+	ClientUsageReportRequest,
+	ClientUsageReportResponse,
+	ClientUsageSummaryResponse,
 	CredentialBlockRequest,
 	CredentialBlockResponse,
 	CredentialBlocksDeleteResponse,
@@ -20,10 +23,13 @@ import type {
 	HealthzResponse,
 	SnapshotResponse,
 	SnapshotStreamEvent,
+	UsageHistoryResponse,
 	UsageResponse,
 	UsageStaleResponse,
 } from "./types";
 import {
+	clientUsageReportResponseSchema,
+	clientUsageSummaryResponseSchema,
 	credentialBlockResponseSchema,
 	credentialBlocksDeleteResponseSchema,
 	credentialDisableResponseSchema,
@@ -32,6 +38,7 @@ import {
 	healthzResponseSchema,
 	snapshotResponseSchema,
 	snapshotStreamEventSchema,
+	usageHistoryResponseSchema,
 	usageResponseSchema,
 	usageStaleResponseSchema,
 } from "./wire-schemas";
@@ -244,6 +251,38 @@ export class AuthBrokerClient {
 		return this.#request<UsageResponse>("GET", "/v1/usage", { schema: usageResponseSchema, signal });
 	}
 
+	/** Recorded usage-limit snapshots from the broker host, oldest first. */
+	fetchUsageHistory(
+		query?: { sinceMs?: number; provider?: string },
+		signal?: AbortSignal,
+	): Promise<UsageHistoryResponse> {
+		const params = new URLSearchParams();
+		if (query?.sinceMs !== undefined) params.set("sinceMs", String(query.sinceMs));
+		if (query?.provider) params.set("provider", query.provider);
+		const path = `/v1/usage/history${params.size > 0 ? `?${params.toString()}` : ""}`;
+		return this.#request<UsageHistoryResponse>("GET", path, { schema: usageHistoryResponseSchema, signal });
+	}
+
+	/** Report this client's batched observed request usage for per-install burn tracking. */
+	reportClientUsage(report: ClientUsageReportRequest, signal?: AbortSignal): Promise<ClientUsageReportResponse> {
+		return this.#request<ClientUsageReportResponse>("POST", "/v1/usage/observed", {
+			body: report,
+			schema: clientUsageReportResponseSchema,
+			signal,
+		});
+	}
+
+	/** Per-client token burn aggregates recorded by the broker host. */
+	fetchClientUsageSummary(query?: { sinceMs?: number }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse> {
+		const params = new URLSearchParams();
+		if (query?.sinceMs !== undefined) params.set("sinceMs", String(query.sinceMs));
+		const path = `/v1/usage/clients${params.size > 0 ? `?${params.toString()}` : ""}`;
+		return this.#request<ClientUsageSummaryResponse>("GET", path, {
+			schema: clientUsageSummaryResponseSchema,
+			signal,
+		});
+	}
+
 	notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse> {
 		return this.#request<UsageStaleResponse>("POST", "/v1/usage/stale", {
 			schema: usageStaleResponseSchema,

package/src/auth-broker/remote-store.ts

@@ -7,8 +7,9 @@
  * usage reports cache TTL is 5 minutes per credential, so durability across
  * runs isn't required.
  */
+import * as os from "node:os";
 import { scheduler } from "node:timers/promises";
-import { logger } from "@oh-my-pi/pi-utils";
+import { getInstallId, logger } from "@oh-my-pi/pi-utils";
 import {
 	type AuthCredential,
 	type AuthCredentialSnapshotEntry,
@@ -21,8 +22,8 @@ import {
 import * as AIError from "../error";
 import type { OAuthCredentials } from "../registry/oauth/types";
 import type { Provider } from "../types";
-import type { UsageReport } from "../usage";
-import { type AuthBrokerClient, AuthBrokerStreamUnsupportedError } from "./client";
+import type { ObservedUsageEntry, UsageReport } from "../usage";
+import { type AuthBrokerClient, AuthBrokerError, AuthBrokerStreamUnsupportedError } from "./client";
 import type {
 	CredentialBlockSnapshot,
 	RefresherSchedule,
@@ -232,6 +233,8 @@ export interface RemoteAuthCredentialStoreOptions {
 	 * routing policy, not broker authorization.
 	 */
 	accountPool?: AuthBrokerAccountPool;
+	/** Flush cadence for batched observed-usage reports. Default 10s. */
+	observedUsageFlushMs?: number;
 }
 
 export class RemoteAuthCredentialStore implements AuthCredentialStore {
@@ -259,10 +262,17 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	#streamingActive = false;
 	/** Latched once the broker has answered 404 — never try the stream again. */
 	#streamingUnsupported = false;
+	/** Pending observed usage keyed by `provider\u0000model`, merged until flush. */
+	#observedUsage = new Map<string, ObservedUsageEntry>();
+	#observedUsageTimer: Timer | undefined;
+	readonly #observedUsageFlushMs: number;
+	/** Latched once the broker answered 404 — old broker, never report again. */
+	#observedUsageUnsupported = false;
 
 	constructor(opts: RemoteAuthCredentialStoreOptions) {
 		this.#client = opts.client;
 		this.#streamSnapshots = opts.streamSnapshots ?? true;
+		this.#observedUsageFlushMs = opts.observedUsageFlushMs ?? 10_000;
 		this.#accountPool = opts.accountPool
 			? new Map([...opts.accountPool].map(([provider, identities]) => [provider, new Set(identities)]))
 			: undefined;
@@ -1049,10 +1059,73 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		return inflight;
 	}
 
+	/**
+	 * Fold locally observed request usage into the pending report and schedule
+	 * a flush. One `POST /v1/usage/observed` at most per flush interval; on
+	 * failure the batch is retained and retried with the next flush. A 404
+	 * (pre-endpoint broker) disables reporting for the life of this store.
+	 */
+	recordObservedUsage(entries: ObservedUsageEntry[]): void {
+		if (this.#closed || this.#observedUsageUnsupported) return;
+		for (const entry of entries) {
+			const key = `${entry.provider}\u0000${entry.model}`;
+			const pending = this.#observedUsage.get(key);
+			if (pending) {
+				pending.at = Math.max(pending.at, entry.at);
+				pending.requests += entry.requests;
+				pending.inputTokens += entry.inputTokens;
+				pending.outputTokens += entry.outputTokens;
+				pending.cacheReadTokens += entry.cacheReadTokens;
+				pending.cacheWriteTokens += entry.cacheWriteTokens;
+				pending.costUsd += entry.costUsd;
+			} else {
+				this.#observedUsage.set(key, { ...entry });
+			}
+		}
+		if (this.#observedUsage.size > 0 && this.#observedUsageTimer === undefined) {
+			this.#observedUsageTimer = setTimeout(() => {
+				this.#observedUsageTimer = undefined;
+				void this.#flushObservedUsage();
+			}, this.#observedUsageFlushMs);
+			this.#observedUsageTimer.unref?.();
+		}
+	}
+
+	async #flushObservedUsage(): Promise<void> {
+		if (this.#observedUsage.size === 0 || this.#observedUsageUnsupported) return;
+		const batch = [...this.#observedUsage.values()];
+		this.#observedUsage.clear();
+		try {
+			await this.#client.reportClientUsage({
+				installId: getInstallId(),
+				hostname: os.hostname(),
+				entries: batch,
+			});
+		} catch (error) {
+			const status = error instanceof AuthBrokerError ? error.status : undefined;
+			if (status === 404 || status === 501) {
+				// Broker predates the endpoint (or store can't persist) — stop trying.
+				this.#observedUsageUnsupported = true;
+				logger.debug("auth-broker does not accept observed usage; reporting disabled", { status });
+				return;
+			}
+			logger.debug("auth-broker observed usage flush failed; retrying next flush", { error: String(error) });
+			// Merge the failed batch back under the (possibly refilled) buffer so
+			// nothing is lost; bounded because entries are keyed per (provider, model).
+			if (!this.#closed) this.recordObservedUsage(batch);
+		}
+	}
+
 	close(): void {
 		if (this.#closed) return;
 		this.#closed = true;
 		this.#backgroundAbort.abort();
+		if (this.#observedUsageTimer !== undefined) {
+			clearTimeout(this.#observedUsageTimer);
+			this.#observedUsageTimer = undefined;
+		}
+		// Best-effort final flush; failures are dropped (the process is exiting).
+		if (this.#observedUsage.size > 0) void this.#flushObservedUsage();
 		this.#cache.clear();
 		this.#usageOverlays.clear();
 	}