@ottimis/jack-provider-sdk 0.2.0 → 0.3.0

package/dist/cjs/index.js

@@ -39,4 +39,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./backend"), exports);
 __exportStar(require("./spawner"), exports);
 __exportStar(require("./provider"), exports);
+__exportStar(require("./usage"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B;AAC1B,0CAAuB"}

package/dist/cjs/usage.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Usage / billing capability — provider-owned data flow.
+ *
+ * Each provider knows how to talk to its own billing surface (Claude
+ * cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
+ * Google Cloud quotas, …) and how to map its SDK's per-message token
+ * counts into a canonical shape. The host runs a generic poll loop and
+ * a generic chip — it never special-cases any provider.
+ *
+ * Two surfaces:
+ *
+ *   - `fetch()` for **account-level** snapshots. Pulled by a host poller
+ *     on `recommendedPollIntervalSec` cadence (clamped to host bounds).
+ *     What "account" means is provider-defined: Claude → org, Codex →
+ *     OpenAI project, Gemini → Cloud Billing project.
+ *
+ *   - `formatSessionMetrics()` for **per-session** translation. The
+ *     manager already calls `backend.getContextUsage()` after every
+ *     `assistant` message; that returns a loose `AgentContextUsage`
+ *     bag. This hook lets the provider lift it into canonical
+ *     {@link UsageMetric}[] without the host trying to interpret
+ *     provider-specific fields.
+ *
+ * Single source of truth: the provider. Host plumbs, never decodes.
+ *
+ * Optional everywhere — providers without billing visibility (Codex
+ * without admin keys, Gemini without OAuth) leave `fetch()` returning
+ * an empty `metrics: []`. The capability flag stays `true` if the
+ * provider can format per-session metrics, `false` if it has nothing
+ * to say at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=usage.js.map

package/dist/cjs/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/usage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/dist/index.d.ts

@@ -23,6 +23,7 @@
 export * from './backend';
 export * from './spawner';
 export * from './provider';
+export * from './usage';
 /**
  * Re-export of `NormalizedMessage` from chat-core so consumers don't need
  * to depend on it directly when their only entrypoint into the wire shape

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAE1B;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AAEvB;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -23,4 +23,5 @@
 export * from './backend';
 export * from './spawner';
 export * from './provider';
+export * from './usage';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA"}

package/dist/provider.d.ts

@@ -16,6 +16,7 @@
  * it free of provider-specific imports.
  */
 import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend';
+import type { UsageApi } from './usage';
 import type { ZodType } from 'zod';
 import type { ClientToolHandler, NormalizedMessage, NormalizedToolRef, ProviderUserContentPolicy, ToolShape } from '@ottimis/jack-chat-core';
 export type ProviderId = string;
@@ -249,6 +250,13 @@ export type CapabilityMatrix = {
      *     renderer hides it and only shows the post-fact audit log.
      */
     permissionGranularity: 'callback' | 'sandbox-only';
+    /**
+     * Provider exposes a usage / billing surface (account-level snapshot
+     * via `provider.usage.fetch()` and/or per-session metric translation
+     * via `formatSessionMetrics()`). When `false`, the chip hides the
+     * usage bars and no Connect affordance is offered.
+     */
+    usage: boolean;
 };
 /**
  * Re-exports of canonical wire-shape types from chat-core so consumers of
@@ -588,6 +596,14 @@ export type JackProvider = {
      * leave it undefined and the host returns empty snapshots.
      */
     persistedPermissions?: PersistedPermissionsApi;
+    /**
+     * Usage / billing capability — provider-owned data flow. See
+     * {@link UsageApi}. Optional; when undefined the chip degrades to
+     * showing nothing (and `capabilities.usage` MUST be `false`). The
+     * provider stays the single source of truth: host plumbs, never
+     * decodes.
+     */
+    usage?: UsageApi;
 };
 /**
  * Provider-neutral spec for an in-process MCP server the host wants to

package/dist/provider.d.ts.map

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

package/dist/usage.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Usage / billing capability — provider-owned data flow.
+ *
+ * Each provider knows how to talk to its own billing surface (Claude
+ * cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
+ * Google Cloud quotas, …) and how to map its SDK's per-message token
+ * counts into a canonical shape. The host runs a generic poll loop and
+ * a generic chip — it never special-cases any provider.
+ *
+ * Two surfaces:
+ *
+ *   - `fetch()` for **account-level** snapshots. Pulled by a host poller
+ *     on `recommendedPollIntervalSec` cadence (clamped to host bounds).
+ *     What "account" means is provider-defined: Claude → org, Codex →
+ *     OpenAI project, Gemini → Cloud Billing project.
+ *
+ *   - `formatSessionMetrics()` for **per-session** translation. The
+ *     manager already calls `backend.getContextUsage()` after every
+ *     `assistant` message; that returns a loose `AgentContextUsage`
+ *     bag. This hook lets the provider lift it into canonical
+ *     {@link UsageMetric}[] without the host trying to interpret
+ *     provider-specific fields.
+ *
+ * Single source of truth: the provider. Host plumbs, never decodes.
+ *
+ * Optional everywhere — providers without billing visibility (Codex
+ * without admin keys, Gemini without OAuth) leave `fetch()` returning
+ * an empty `metrics: []`. The capability flag stays `true` if the
+ * provider can format per-session metrics, `false` if it has nothing
+ * to say at all.
+ */
+import type { AgentContextUsage } from './backend';
+/**
+ * Canonical metric kinds. New kinds extend this union additively when a
+ * provider has a meaningfully different shape (e.g. a future
+ * `quarterly_burn` for enterprise billing). Adding a kind is a minor
+ * SDK bump; the renderer's dispatch table grows alongside.
+ */
+export type UsageMetric = TimeWindowMetric | TokenUtilizationMetric | MonthlySpendMetric;
+/**
+ * Rolling-window utilization. The classic Claude Pro/Max bucket
+ * (5-hour, 7-day) — utilization 0..1 with a hard reset boundary.
+ *
+ * Optional `used` / `limit` / `unit` carry raw counts when the
+ * provider exposes them (Gemini free-tier daily quota: 12 of 50
+ * requests). Claude's cookie API gives only `utilization`, so those
+ * stay undefined and the chip falls back to "X% of N-hour usage".
+ */
+export type TimeWindowMetric = {
+    kind: 'time_window';
+    /** Stable, provider-defined key. e.g. `'five_hour'`, `'seven_day_opus'`, `'daily'`. */
+    id: string;
+    /** Human-readable label for UI. Provider supplies (i18n is its concern). */
+    label: string;
+    /** Window utilization in [0, 1]. */
+    utilization: number;
+    /** Optional: raw count consumed in the window (when known). */
+    used?: number;
+    /** Optional: raw cap of the window (when known). */
+    limit?: number;
+    /** Optional: unit of `used`/`limit`. Default `'tokens'`. Chip uses for formatting. */
+    unit?: 'tokens' | 'requests' | (string & {});
+    /** ISO 8601 timestamp when the window resets. */
+    resetsAt: string;
+    /** Window length in seconds. Used for elapsed-progress UI. */
+    windowSeconds: number;
+};
+/**
+ * Count-based utilization without a time boundary. Used for context
+ * window pressure ("X tokens of Y max") and any cumulative provider
+ * metric that doesn't reset on a clock (lifetime / billing-period
+ * tokens, etc).
+ *
+ * `max` is optional — a provider tracking total token consumption
+ * without a hard cap (analytics, not gating) leaves it undefined and
+ * the chip shows just the count.
+ */
+export type TokenUtilizationMetric = {
+    kind: 'token_utilization';
+    /** Stable, provider-defined key. e.g. `'context'`, `'session_total'`. */
+    id: string;
+    /** Human-readable label for UI. */
+    label: string;
+    /** Tokens consumed. */
+    used: number;
+    /** Optional cap. Undefined = no cap, chip hides the ratio. */
+    max?: number;
+};
+/**
+ * Spend on a billing cycle (typically monthly). Only meaningful for
+ * providers using API-key auth — subscription users have rolling-window
+ * quotas, not $-spend.
+ *
+ * `budgetUsd` is optional: most users don't set a budget, so the chip
+ * shows raw spend without a denominator. When present, chip can render
+ * a budget bar.
+ */
+export type MonthlySpendMetric = {
+    kind: 'monthly_spend';
+    id: string;
+    /** Cycle label, e.g. "May 2026" or "Current cycle". */
+    label: string;
+    spentUsd: number;
+    budgetUsd?: number;
+    /** ISO 8601 — start of the billing cycle. */
+    cycleStart: string;
+    /** ISO 8601 — end of the billing cycle. */
+    cycleEnd: string;
+};
+/**
+ * One snapshot of provider-side usage data, as returned by
+ * {@link UsageApi.fetch}. `metrics` may be empty when the provider has
+ * no account-level data to report (Codex without billing key, etc.).
+ */
+export type UsageSnapshot = {
+    metrics: UsageMetric[];
+    /** ISO 8601 — when this snapshot was observed. */
+    observedAt: string;
+    /** Verbatim provider payload, kept for debug / future analytics.
+     *  Never consumed by host or chip directly. */
+    raw?: unknown;
+};
+/**
+ * Connection / authorization state of the provider's usage surface.
+ * Surface in the chip's pop-over so the user knows whether they're
+ * tracking real numbers or seeing a cached / disconnected snapshot.
+ */
+export type UsageStatus = {
+    connected: boolean;
+    /** Optional human-readable identity (org name, email, project id). */
+    identity?: string;
+    /**
+     * Provider-defined auth-mode hint. Lets the renderer adapt copy
+     * (e.g. "Connected as API user" vs "Pro subscription"). Stable
+     * provider-supplied strings; host doesn't interpret beyond
+     * passthrough.
+     */
+    authMode?: 'subscription' | 'api_key' | (string & {});
+    /** Last error message, when not connected. */
+    error?: string;
+};
+/**
+ * Result of {@link UsageApi.connect}. The `'choose'` branch covers
+ * multi-org / multi-project accounts where the user must pick one
+ * (Claude's multi-org case). Generalising to a generic option list
+ * means the chip's UI doesn't special-case any provider.
+ */
+export type UsageConnectResult = {
+    kind: 'ready';
+    identity: string;
+} | {
+    kind: 'choose';
+    options: UsageConnectOption[];
+} | {
+    kind: 'error';
+    error: string;
+} | {
+    kind: 'cancelled';
+};
+export type UsageConnectOption = {
+    id: string;
+    label: string;
+};
+/**
+ * Context handed to {@link UsageApi.connect}. Currently just a parent
+ * window for Electron-coupled flows (Claude opens a child BrowserWindow
+ * on `claude.ai/login`). Typed as `unknown` here so the SDK doesn't
+ * pull in `electron` as a peer dep — the host narrows to
+ * `BrowserWindow` at the call site.
+ */
+export type UsageConnectContext = {
+    /** Parent window for any modal flow the provider needs to open. */
+    parentWindow?: unknown;
+};
+/**
+ * Provider-owned usage capability. Optional on {@link JackProvider};
+ * absent = host hides the chip's "Connect" affordance and the
+ * capability flag is `false`.
+ */
+export type UsageApi = {
+    /** Current connection state — used for chip display + gating. */
+    status(): Promise<UsageStatus>;
+    /**
+     * Open the provider's connect flow. Whatever modality the provider
+     * needs (login window, API-key picker, OAuth redirect) lives here.
+     */
+    connect(ctx: UsageConnectContext): Promise<UsageConnectResult>;
+    /**
+     * When `connect()` returned `'choose'`, host calls this with the
+     * user's pick. Optional — providers that never choose omit it.
+     */
+    selectOption?(optionId: string): Promise<UsageConnectResult>;
+    /** Drop credentials and stop any provider-side polling. */
+    disconnect(): Promise<void>;
+    /**
+     * Fetch one fresh account-level snapshot. Empty `metrics: []` is
+     * fine when the provider has no billing surface yet — the capability
+     * stays `true` for the per-session bridge.
+     */
+    fetch(): Promise<UsageSnapshot>;
+    /**
+     * Recommended poll cadence (seconds). Host clamps to its bounds.
+     * Optional — host falls back to its own default if unset.
+     */
+    recommendedPollIntervalSec?: number;
+    /**
+     * Translate the loose {@link AgentContextUsage} the manager pulls from
+     * `backend.getContextUsage()` into canonical {@link UsageMetric}[].
+     *
+     * Pure function (no side effects) — provider knows its own SDK's
+     * shape and lifts it. Empty array OK when the raw bag has nothing
+     * useful (e.g. fresh session before any message lands).
+     *
+     * Optional. Providers without per-session token visibility omit it
+     * and the chip skips the per-session row.
+     */
+    formatSessionMetrics?(raw: AgentContextUsage): UsageMetric[];
+};
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

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

package/dist/usage.js

@@ -0,0 +1,33 @@
+/**
+ * Usage / billing capability — provider-owned data flow.
+ *
+ * Each provider knows how to talk to its own billing surface (Claude
+ * cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
+ * Google Cloud quotas, …) and how to map its SDK's per-message token
+ * counts into a canonical shape. The host runs a generic poll loop and
+ * a generic chip — it never special-cases any provider.
+ *
+ * Two surfaces:
+ *
+ *   - `fetch()` for **account-level** snapshots. Pulled by a host poller
+ *     on `recommendedPollIntervalSec` cadence (clamped to host bounds).
+ *     What "account" means is provider-defined: Claude → org, Codex →
+ *     OpenAI project, Gemini → Cloud Billing project.
+ *
+ *   - `formatSessionMetrics()` for **per-session** translation. The
+ *     manager already calls `backend.getContextUsage()` after every
+ *     `assistant` message; that returns a loose `AgentContextUsage`
+ *     bag. This hook lets the provider lift it into canonical
+ *     {@link UsageMetric}[] without the host trying to interpret
+ *     provider-specific fields.
+ *
+ * Single source of truth: the provider. Host plumbs, never decodes.
+ *
+ * Optional everywhere — providers without billing visibility (Codex
+ * without admin keys, Gemini without OAuth) leave `fetch()` returning
+ * an empty `metrics: []`. The capability flag stays `true` if the
+ * provider can format per-session metrics, `false` if it has nothing
+ * to say at all.
+ */
+export {};
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottimis/jack-provider-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -24,6 +24,7 @@
 export * from './backend'
 export * from './spawner'
 export * from './provider'
+export * from './usage'
 
 /**
  * Re-export of `NormalizedMessage` from chat-core so consumers don't need

package/src/provider.ts

@@ -17,6 +17,7 @@
  */
 
 import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend'
+import type { UsageApi } from './usage'
 import type { ZodType } from 'zod'
 import type {
   ClientToolHandler,
@@ -265,6 +266,13 @@ export type CapabilityMatrix = {
    *     renderer hides it and only shows the post-fact audit log.
    */
   permissionGranularity: 'callback' | 'sandbox-only'
+  /**
+   * Provider exposes a usage / billing surface (account-level snapshot
+   * via `provider.usage.fetch()` and/or per-session metric translation
+   * via `formatSessionMetrics()`). When `false`, the chip hides the
+   * usage bars and no Connect affordance is offered.
+   */
+  usage: boolean
 }
 
 /**
@@ -642,6 +650,14 @@ export type JackProvider = {
    * leave it undefined and the host returns empty snapshots.
    */
   persistedPermissions?: PersistedPermissionsApi
+  /**
+   * Usage / billing capability — provider-owned data flow. See
+   * {@link UsageApi}. Optional; when undefined the chip degrades to
+   * showing nothing (and `capabilities.usage` MUST be `false`). The
+   * provider stays the single source of truth: host plumbs, never
+   * decodes.
+   */
+  usage?: UsageApi
 }
 
 /**

package/src/usage.ts

@@ -0,0 +1,228 @@
+/**
+ * Usage / billing capability — provider-owned data flow.
+ *
+ * Each provider knows how to talk to its own billing surface (Claude
+ * cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
+ * Google Cloud quotas, …) and how to map its SDK's per-message token
+ * counts into a canonical shape. The host runs a generic poll loop and
+ * a generic chip — it never special-cases any provider.
+ *
+ * Two surfaces:
+ *
+ *   - `fetch()` for **account-level** snapshots. Pulled by a host poller
+ *     on `recommendedPollIntervalSec` cadence (clamped to host bounds).
+ *     What "account" means is provider-defined: Claude → org, Codex →
+ *     OpenAI project, Gemini → Cloud Billing project.
+ *
+ *   - `formatSessionMetrics()` for **per-session** translation. The
+ *     manager already calls `backend.getContextUsage()` after every
+ *     `assistant` message; that returns a loose `AgentContextUsage`
+ *     bag. This hook lets the provider lift it into canonical
+ *     {@link UsageMetric}[] without the host trying to interpret
+ *     provider-specific fields.
+ *
+ * Single source of truth: the provider. Host plumbs, never decodes.
+ *
+ * Optional everywhere — providers without billing visibility (Codex
+ * without admin keys, Gemini without OAuth) leave `fetch()` returning
+ * an empty `metrics: []`. The capability flag stays `true` if the
+ * provider can format per-session metrics, `false` if it has nothing
+ * to say at all.
+ */
+
+import type { AgentContextUsage } from './backend'
+
+/**
+ * Canonical metric kinds. New kinds extend this union additively when a
+ * provider has a meaningfully different shape (e.g. a future
+ * `quarterly_burn` for enterprise billing). Adding a kind is a minor
+ * SDK bump; the renderer's dispatch table grows alongside.
+ */
+export type UsageMetric = TimeWindowMetric | TokenUtilizationMetric | MonthlySpendMetric
+
+/**
+ * Rolling-window utilization. The classic Claude Pro/Max bucket
+ * (5-hour, 7-day) — utilization 0..1 with a hard reset boundary.
+ *
+ * Optional `used` / `limit` / `unit` carry raw counts when the
+ * provider exposes them (Gemini free-tier daily quota: 12 of 50
+ * requests). Claude's cookie API gives only `utilization`, so those
+ * stay undefined and the chip falls back to "X% of N-hour usage".
+ */
+export type TimeWindowMetric = {
+  kind: 'time_window'
+  /** Stable, provider-defined key. e.g. `'five_hour'`, `'seven_day_opus'`, `'daily'`. */
+  id: string
+  /** Human-readable label for UI. Provider supplies (i18n is its concern). */
+  label: string
+  /** Window utilization in [0, 1]. */
+  utilization: number
+  /** Optional: raw count consumed in the window (when known). */
+  used?: number
+  /** Optional: raw cap of the window (when known). */
+  limit?: number
+  /** Optional: unit of `used`/`limit`. Default `'tokens'`. Chip uses for formatting. */
+  unit?: 'tokens' | 'requests' | (string & {})
+  /** ISO 8601 timestamp when the window resets. */
+  resetsAt: string
+  /** Window length in seconds. Used for elapsed-progress UI. */
+  windowSeconds: number
+}
+
+/**
+ * Count-based utilization without a time boundary. Used for context
+ * window pressure ("X tokens of Y max") and any cumulative provider
+ * metric that doesn't reset on a clock (lifetime / billing-period
+ * tokens, etc).
+ *
+ * `max` is optional — a provider tracking total token consumption
+ * without a hard cap (analytics, not gating) leaves it undefined and
+ * the chip shows just the count.
+ */
+export type TokenUtilizationMetric = {
+  kind: 'token_utilization'
+  /** Stable, provider-defined key. e.g. `'context'`, `'session_total'`. */
+  id: string
+  /** Human-readable label for UI. */
+  label: string
+  /** Tokens consumed. */
+  used: number
+  /** Optional cap. Undefined = no cap, chip hides the ratio. */
+  max?: number
+}
+
+/**
+ * Spend on a billing cycle (typically monthly). Only meaningful for
+ * providers using API-key auth — subscription users have rolling-window
+ * quotas, not $-spend.
+ *
+ * `budgetUsd` is optional: most users don't set a budget, so the chip
+ * shows raw spend without a denominator. When present, chip can render
+ * a budget bar.
+ */
+export type MonthlySpendMetric = {
+  kind: 'monthly_spend'
+  id: string
+  /** Cycle label, e.g. "May 2026" or "Current cycle". */
+  label: string
+  spentUsd: number
+  budgetUsd?: number
+  /** ISO 8601 — start of the billing cycle. */
+  cycleStart: string
+  /** ISO 8601 — end of the billing cycle. */
+  cycleEnd: string
+}
+
+/**
+ * One snapshot of provider-side usage data, as returned by
+ * {@link UsageApi.fetch}. `metrics` may be empty when the provider has
+ * no account-level data to report (Codex without billing key, etc.).
+ */
+export type UsageSnapshot = {
+  metrics: UsageMetric[]
+  /** ISO 8601 — when this snapshot was observed. */
+  observedAt: string
+  /** Verbatim provider payload, kept for debug / future analytics.
+   *  Never consumed by host or chip directly. */
+  raw?: unknown
+}
+
+/**
+ * Connection / authorization state of the provider's usage surface.
+ * Surface in the chip's pop-over so the user knows whether they're
+ * tracking real numbers or seeing a cached / disconnected snapshot.
+ */
+export type UsageStatus = {
+  connected: boolean
+  /** Optional human-readable identity (org name, email, project id). */
+  identity?: string
+  /**
+   * Provider-defined auth-mode hint. Lets the renderer adapt copy
+   * (e.g. "Connected as API user" vs "Pro subscription"). Stable
+   * provider-supplied strings; host doesn't interpret beyond
+   * passthrough.
+   */
+  authMode?: 'subscription' | 'api_key' | (string & {})
+  /** Last error message, when not connected. */
+  error?: string
+}
+
+/**
+ * Result of {@link UsageApi.connect}. The `'choose'` branch covers
+ * multi-org / multi-project accounts where the user must pick one
+ * (Claude's multi-org case). Generalising to a generic option list
+ * means the chip's UI doesn't special-case any provider.
+ */
+export type UsageConnectResult =
+  | { kind: 'ready'; identity: string }
+  | { kind: 'choose'; options: UsageConnectOption[] }
+  | { kind: 'error'; error: string }
+  | { kind: 'cancelled' }
+
+export type UsageConnectOption = {
+  id: string
+  label: string
+}
+
+/**
+ * Context handed to {@link UsageApi.connect}. Currently just a parent
+ * window for Electron-coupled flows (Claude opens a child BrowserWindow
+ * on `claude.ai/login`). Typed as `unknown` here so the SDK doesn't
+ * pull in `electron` as a peer dep — the host narrows to
+ * `BrowserWindow` at the call site.
+ */
+export type UsageConnectContext = {
+  /** Parent window for any modal flow the provider needs to open. */
+  parentWindow?: unknown
+}
+
+/**
+ * Provider-owned usage capability. Optional on {@link JackProvider};
+ * absent = host hides the chip's "Connect" affordance and the
+ * capability flag is `false`.
+ */
+export type UsageApi = {
+  /** Current connection state — used for chip display + gating. */
+  status(): Promise<UsageStatus>
+
+  /**
+   * Open the provider's connect flow. Whatever modality the provider
+   * needs (login window, API-key picker, OAuth redirect) lives here.
+   */
+  connect(ctx: UsageConnectContext): Promise<UsageConnectResult>
+
+  /**
+   * When `connect()` returned `'choose'`, host calls this with the
+   * user's pick. Optional — providers that never choose omit it.
+   */
+  selectOption?(optionId: string): Promise<UsageConnectResult>
+
+  /** Drop credentials and stop any provider-side polling. */
+  disconnect(): Promise<void>
+
+  /**
+   * Fetch one fresh account-level snapshot. Empty `metrics: []` is
+   * fine when the provider has no billing surface yet — the capability
+   * stays `true` for the per-session bridge.
+   */
+  fetch(): Promise<UsageSnapshot>
+
+  /**
+   * Recommended poll cadence (seconds). Host clamps to its bounds.
+   * Optional — host falls back to its own default if unset.
+   */
+  recommendedPollIntervalSec?: number
+
+  /**
+   * Translate the loose {@link AgentContextUsage} the manager pulls from
+   * `backend.getContextUsage()` into canonical {@link UsageMetric}[].
+   *
+   * Pure function (no side effects) — provider knows its own SDK's
+   * shape and lifts it. Empty array OK when the raw bag has nothing
+   * useful (e.g. fresh session before any message lands).
+   *
+   * Optional. Providers without per-session token visibility omit it
+   * and the chip skips the per-session row.
+   */
+  formatSessionMetrics?(raw: AgentContextUsage): UsageMetric[]
+}