@uxnan/shared 0.0.4-alpha.20260703 → 0.0.5-alpha.20260711

package/README.md

@@ -13,7 +13,7 @@ equivalents (see
 [`architecture/02b-contracts-and-requirements.md`](../architecture/02b-contracts-and-requirements.md)
 §1 for the canonical contract list).
 
-> **Status:** implemented and stable — **61 JSON-RPC methods** + **8 streaming
+> **Status:** implemented and stable — **62 JSON-RPC methods** + **8 streaming
 > notifications**, kept lock-step at build time with the `METHOD_NAMES` array and
 > the `StreamNotification` enum (a compile-time assertion in
 > `src/jsonrpc/method-registry.ts` fails the build on any drift). Changes are
@@ -52,7 +52,7 @@ flowchart TB
 | JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32008`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
 | Streaming | `StreamNotification` enum + param types (`TurnStartedParams`, `MessageDeltaParams`, `ThinkingDeltaParams`, `ContentBlockParams`, `TurnCompletedParams`, `TurnUsage`, `TurnErrorParams`, `TurnAbortedParams`, `ModelResolvedParams`) |
 | E2EE | handshake messages (`clientHello` / `serverHello` / `clientAuth` / `ready`), `buildHandshakeTranscript`, `SecureEnvelope`, `PairingPayload` v2 (`relay` optional + `hosts: string[]`) with `Base64(utf8(JSON))` QR encoding |
-| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), approval |
+| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), approval, question (interactive multiple-choice) |
 | Agents | `IAgentAdapter` (with `respondApproval`, `listModels`, `nativeSessionId`, `SendTurnOptions { threadId, turnId, text, service?, effort?, options?, attachments?, cwd?, accessMode? }`), `AgentModel` (incl. `version?`, `isDefault?`, `options?`, `contextWindow?`, `isLatestAlias?`), `AgentCapabilities` (incl. `images`, `approvals`, `reportsContextUsage`), `AgentConfig` (cwd, agentId, model, plus optional `binaryPath`/`extraArgs`) |
 | Version | `compareVersions` / `isNewerVersion` — dependency-free SemVer precedence (used by the bridge's npm update check) |
 | Validation | Ajv validators for requests, responses, envelopes, pairing payload, push payloads |

package/dist/src/agents/agent-capabilities.d.ts

@@ -3,7 +3,11 @@
  *
  * Source: architecture/02a-system-architecture.md §5.8.2 (adapters).
  */
-export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli' | 'pi-agent' | 'aider'
+export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli' | 'pi-agent'
+/** Zero — open-source Go coding agent, driven over the Agent Client Protocol. */
+ | 'zero'
+/** Grok — xAI's coding CLI, driven over the Agent Client Protocol (`grok agent stdio`). */
+ | 'grok'
 /** Built-in reference/dev agent that echoes the prompt (no external CLI). */
  | 'echo';
 export interface AgentCapabilities {
@@ -24,6 +28,14 @@ export interface AgentCapabilities {
      * OpenCode) and the meter stays hidden.
      */
     reportsContextUsage?: boolean;
+    /**
+     * Agent runs in autonomous ("YOLO") mode by default — it acts and edits
+     * without per-action approval prompts because its headless CLI exposes no
+     * pre-tool approval channel. The phone surfaces this so the user knows Pi
+     * (and any such agent) will not ask before running tools. Optional; absent/
+     * false means the agent either gates tools or is pending approval wiring.
+     */
+    autonomous?: boolean;
 }
 /**
  * A registered agent the phone can pick for a thread, returned by `agent/list`.

package/dist/src/index.d.ts

@@ -22,5 +22,7 @@ export * from './models/workspace.js';
 export * from './models/project.js';
 export * from './models/session.js';
 export * from './models/approval.js';
+export * from './models/question.js';
+export * from './models/usage.js';
 export * from './validators/validate.js';
 export * from './validators/json-schema/schemas.js';

package/dist/src/index.js

@@ -28,6 +28,8 @@ export * from './models/workspace.js';
 export * from './models/project.js';
 export * from './models/session.js';
 export * from './models/approval.js';
+export * from './models/question.js';
+export * from './models/usage.js';
 // Validators
 export * from './validators/validate.js';
 export * from './validators/json-schema/schemas.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,OAAO;AACP,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAE1C,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAE1C,UAAU;AACV,cAAc,sBAAsB,CAAC;AAErC,gBAAgB;AAChB,cAAc,iCAAiC,CAAC;AAEhD,SAAS;AACT,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAErC,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,OAAO;AACP,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAE1C,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAE1C,UAAU;AACV,cAAc,sBAAsB,CAAC;AAErC,gBAAgB;AAChB,cAAc,iCAAiC,CAAC;AAEhD,SAAS;AACT,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAElC,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}

package/dist/src/jsonrpc/method-registry.d.ts

@@ -3,5 +3,5 @@
  * compile-time {@link JsonRpcMethodRegistry} via the assertion below.
  */
 import type { JsonRpcMethodName } from './methods.js';
-export declare const METHOD_NAMES: readonly ["thread/list", "thread/read", "thread/start", "thread/resume", "thread/fork", "thread/setModel", "thread/rename", "thread/setAccessMode", "thread/archive", "thread/unarchive", "thread/delete", "turn/list", "turn/read", "turn/send", "turn/cancel", "git/status", "git/diff", "git/commit", "git/push", "git/pull", "git/checkout", "git/createBranch", "git/createWorktree", "git/stage", "git/unstage", "git/discard", "git/createPr", "git/undoCommit", "git/branches", "git/switchBranch", "git/revert", "git/deleteBranch", "git/removeWorktree", "git/log", "git/commitShow", "workspace/readFile", "workspace/readImage", "workspace/list", "workspace/searchFiles", "workspace/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "agent/list", "agent/models", "auth/status", "auth/login", "auth/logout", "notifications/register", "notifications/update", "notifications/unregister", "bridge/status", "bridge/generatePairingQr", "bridge/connectedPhones", "bridge/disconnectPhone", "bridge/trustedDevices", "bridge/removeTrustedDevice"];
+export declare const METHOD_NAMES: readonly ["thread/list", "thread/read", "thread/start", "thread/resume", "thread/fork", "thread/setModel", "thread/rename", "thread/setAccessMode", "thread/archive", "thread/unarchive", "thread/delete", "turn/list", "turn/read", "turn/send", "turn/cancel", "git/status", "git/diff", "git/commit", "git/push", "git/pull", "git/checkout", "git/createBranch", "git/createWorktree", "git/stage", "git/unstage", "git/discard", "git/createPr", "git/undoCommit", "git/branches", "git/switchBranch", "git/revert", "git/deleteBranch", "git/removeWorktree", "git/log", "git/commitShow", "workspace/readFile", "workspace/readImage", "workspace/list", "workspace/searchFiles", "workspace/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "agent/list", "agent/models", "agent/usageStats", "auth/status", "auth/login", "auth/logout", "notifications/register", "notifications/update", "notifications/unregister", "bridge/status", "bridge/generatePairingQr", "bridge/connectedPhones", "bridge/disconnectPhone", "bridge/trustedDevices", "bridge/removeTrustedDevice"];
 export declare function isKnownMethod(method: string): method is JsonRpcMethodName;

package/dist/src/jsonrpc/method-registry.js

@@ -53,6 +53,7 @@ export const METHOD_NAMES = [
     // Agents
     'agent/list',
     'agent/models',
+    'agent/usageStats',
     // Auth
     'auth/status',
     'auth/login',

package/dist/src/jsonrpc/method-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"method-registry.js","sourceRoot":"","sources":["../../../src/jsonrpc/method-registry.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,kBAAkB;IAClB,aAAa;IACb,aAAa;IACb,cAAc;IACd,eAAe;IACf,aAAa;IACb,iBAAiB;IACjB,eAAe;IACf,sBAAsB;IACtB,gBAAgB;IAChB,kBAAkB;IAClB,eAAe;IACf,WAAW;IACX,WAAW;IACX,WAAW;IACX,aAAa;IACb,MAAM;IACN,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,UAAU;IACV,UAAU;IACV,cAAc;IACd,kBAAkB;IAClB,oBAAoB;IACpB,WAAW;IACX,aAAa;IACb,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,cAAc;IACd,kBAAkB;IAClB,YAAY;IACZ,kBAAkB;IAClB,oBAAoB;IACpB,SAAS;IACT,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,SAAS;IACT,YAAY;IACZ,cAAc;IACd,OAAO;IACP,aAAa;IACb,YAAY;IACZ,aAAa;IACb,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,0BAA0B;IAC1B,iBAAiB;IACjB,eAAe;IACf,0BAA0B;IAC1B,wBAAwB;IACxB,wBAAwB;IACxB,uBAAuB;IACvB,4BAA4B;CACpB,CAAC;AAQX,MAAM,sBAAsB,GAAqB,IAAI,CAAC;AACtD,MAAM,sBAAsB,GAAqB,IAAI,CAAC;AACtD,KAAK,sBAAsB,CAAC;AAC5B,KAAK,sBAAsB,CAAC;AAE5B,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;AAEnE,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"method-registry.js","sourceRoot":"","sources":["../../../src/jsonrpc/method-registry.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,kBAAkB;IAClB,aAAa;IACb,aAAa;IACb,cAAc;IACd,eAAe;IACf,aAAa;IACb,iBAAiB;IACjB,eAAe;IACf,sBAAsB;IACtB,gBAAgB;IAChB,kBAAkB;IAClB,eAAe;IACf,WAAW;IACX,WAAW;IACX,WAAW;IACX,aAAa;IACb,MAAM;IACN,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,UAAU;IACV,UAAU;IACV,cAAc;IACd,kBAAkB;IAClB,oBAAoB;IACpB,WAAW;IACX,aAAa;IACb,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,cAAc;IACd,kBAAkB;IAClB,YAAY;IACZ,kBAAkB;IAClB,oBAAoB;IACpB,SAAS;IACT,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,SAAS;IACT,YAAY;IACZ,cAAc;IACd,kBAAkB;IAClB,OAAO;IACP,aAAa;IACb,YAAY;IACZ,aAAa;IACb,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,0BAA0B;IAC1B,iBAAiB;IACjB,eAAe;IACf,0BAA0B;IAC1B,wBAAwB;IACxB,wBAAwB;IACxB,uBAAuB;IACvB,4BAA4B;CACpB,CAAC;AAQX,MAAM,sBAAsB,GAAqB,IAAI,CAAC;AACtD,MAAM,sBAAsB,GAAqB,IAAI,CAAC;AACtD,KAAK,sBAAsB,CAAC;AAC5B,KAAK,sBAAsB,CAAC;AAE5B,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;AAEnE,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/src/jsonrpc/methods.d.ts

@@ -10,9 +10,11 @@ import type { GitBranchList, GitBranchResult, GitCommitDetails, GitCommitResult,
 import type { ApplyResult, BrowseResult, Checkpoint, CheckpointDiff, FileContent, ImageContent, PatchChange, TurnAttachment, WorkspaceExistsResult, WorkspaceListing, SearchFilesParams, WorkspaceSearchResult } from '../models/workspace.js';
 import type { AuthStatus, Project } from '../models/project.js';
 import type { ApprovalResponse } from '../models/approval.js';
+import type { QuestionResponse } from '../models/question.js';
 import type { BridgeStatus, ConnectedPhone, TrustedDevice } from '../models/session.js';
 import type { PairingPayload } from '../e2ee/pairing-payload.js';
 import type { AgentDescriptor, AgentId, AgentModel } from '../agents/agent-capabilities.js';
+import type { UsageStatsParams, UsageStatsResult } from '../models/usage.js';
 import type { PushPlatform } from '../notifications/push-payload.js';
 export interface ListThreadsParams {
     projectId?: string;
@@ -74,6 +76,12 @@ export interface TurnSendParams {
      * is not required.
      */
     approvalResponse?: ApprovalResponse;
+    /**
+     * Reply to a pending question the agent asked (no new turn is created). The
+     * bridge routes the chosen answers to the agent adapter. When present, `text`
+     * is not required.
+     */
+    questionResponse?: QuestionResponse;
 }
 export interface ThreadSetModelParams {
     threadId: string;
@@ -468,6 +476,10 @@ export interface JsonRpcMethodRegistry {
         params: AgentModelsParams;
         result: AgentModelsResult;
     };
+    'agent/usageStats': {
+        params: UsageStatsParams;
+        result: UsageStatsResult;
+    };
     'auth/status': {
         params: {
             agentId: AgentId;

package/dist/src/models/question.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Interactive question contracts.
+ *
+ * An agent that needs the user to CHOOSE among options (not just approve/reject
+ * an action) emits a `question` content block (on `stream/content/block`); the
+ * phone renders an interactive picker and replies via `turn/send { questionResponse }`.
+ * The bridge routes the chosen answers back to the agent adapter. This mirrors
+ * the {@link ApprovalResponse} flow but carries multiple-choice answers instead
+ * of a binary decision.
+ *
+ * Source: architecture/02a-system-architecture.md §6.2.
+ */
+/** One selectable option of a {@link QuestionItem}. */
+export interface QuestionOption {
+    /** Display text the user picks (also the value echoed back as the answer). */
+    label: string;
+    /** Optional one-line explanation of what choosing this option means. */
+    description?: string;
+}
+/** A single question with its options. */
+export interface QuestionItem {
+    /** The full question text. */
+    question: string;
+    /** Optional short label/category for the question. */
+    header?: string;
+    /** The choices the user may pick from. */
+    options: QuestionOption[];
+    /** Whether more than one option may be selected (defaults to single-select). */
+    multiple?: boolean;
+}
+/**
+ * Payload of a `question` content block. The phone decodes this into its
+ * interactive question card. `questionId` is the bridge handle the user echoes
+ * back in {@link QuestionResponse.questionId}.
+ */
+export interface QuestionRequestBlock {
+    type: 'question';
+    /** Bridge id the phone echoes back in `questionResponse.questionId`. */
+    questionId: string;
+    /** The questions to ask (usually one; an agent may batch a few). */
+    questions: QuestionItem[];
+}
+/**
+ * The user's reply to a pending question, carried on `turn/send`. `answers` is
+ * one entry per question (in order), each an array of the chosen option
+ * `label`s (one for single-select, several for a `multiple` question, empty when
+ * the user skipped that question).
+ */
+export interface QuestionResponse {
+    /** The id from the question request the user is answering. */
+    questionId: string;
+    /** Chosen option labels, per question, in question order. */
+    answers: string[][];
+}

package/dist/src/models/question.js

@@ -0,0 +1,14 @@
+/**
+ * Interactive question contracts.
+ *
+ * An agent that needs the user to CHOOSE among options (not just approve/reject
+ * an action) emits a `question` content block (on `stream/content/block`); the
+ * phone renders an interactive picker and replies via `turn/send { questionResponse }`.
+ * The bridge routes the chosen answers back to the agent adapter. This mirrors
+ * the {@link ApprovalResponse} flow but carries multiple-choice answers instead
+ * of a binary decision.
+ *
+ * Source: architecture/02a-system-architecture.md §6.2.
+ */
+export {};
+//# sourceMappingURL=question.js.map

package/dist/src/models/question.js.map

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

package/dist/src/models/usage.d.ts

@@ -0,0 +1,92 @@
+/**
+ * AI-provider usage statistics: quota/rate windows, plan/account, credit
+ * balance and local token tallies read from a coding CLI's on-disk state — its
+ * stored OAuth token (→ the provider's official usage API) and/or its local
+ * session logs.
+ *
+ * Surfaced in the desktop's Settings → Providers section and, over the bridge,
+ * on the phone. The access path is per-runtime by design (02a §5.8.10): the
+ * desktop reads these files natively in Rust; the bridge reads them in TS so a
+ * paired phone — which cannot see the PC's disk directly — gets the same data
+ * over `agent/usageStats`. The Dart equivalents live in uxnanmobile and are kept
+ * in sync manually (see 02e-bridge-integration.md §4.2).
+ *
+ * Posture: only the CLI's own stored token is read — never browser cookies or
+ * user-pasted API keys.
+ */
+/** A coding CLI whose usage we read from its own stored token. */
+export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'gemini';
+/** Outcome of reading one provider's usage. */
+export type UsageStatus = 
+/** Fresh quota/credit data was read. */
+'ok'
+/** CLI is present but not signed in (no usable token). */
+ | 'authRequired'
+/** CLI / its config directory is not present on this machine. */
+ | 'notInstalled'
+/** Read/network/parse failure — see {@link ProviderUsage.message}. */
+ | 'error';
+/** How the data was obtained, for the UI's provenance label. Every wired
+ *  provider reads its quota from the CLI's own signed-in token. */
+export type UsageSource = 'token';
+/**
+ * A single quota/rate window, expressed as a used-percentage with an optional
+ * reset time — the atomic unit a provider reports (e.g. a 5-hour session, a
+ * weekly cap, or a model-specific window).
+ */
+export interface UsageWindow {
+    /** Stable id (e.g. `session5h`, `weekly`, `opusWeekly`) — used by the
+     *  status-bar picker to remember which windows to surface. */
+    id: string;
+    /** Human label (English; the UI localizes known ids, else shows this). */
+    label: string;
+    /** Consumed fraction of this window, clamped to 0–100. */
+    usedPercent: number;
+    /** Window length in minutes (300 = 5h, 10080 = 7d, 1440 = 24h), when known. */
+    windowMinutes?: number;
+    /** When the window resets (epoch ms), when the provider reports it. */
+    resetsAt?: number;
+}
+/** A monetary / credit balance, kept separate from the percentage windows. */
+export interface CreditBalance {
+    /** Amount consumed this period, in `currency`. */
+    used: number;
+    /** Spend/credit cap, when the provider exposes one. */
+    limit?: number;
+    /** ISO-4217 code (`USD`, `EUR`, …) or `credits` for non-currency units. */
+    currency: string;
+    /** Period label (English; e.g. `Monthly`, `Credits`). */
+    period: string;
+    /** When the balance resets (epoch ms), when known. */
+    resetsAt?: number;
+}
+/** One provider's usage snapshot. */
+export interface ProviderUsage {
+    provider: UsageProvider;
+    status: UsageStatus;
+    /** How `windows`/`credit` were obtained (absent for states with no data). */
+    source?: UsageSource;
+    account?: {
+        email?: string;
+        organization?: string;
+        plan?: string;
+    };
+    /** Quota/rate windows (percentage-based). Empty when none apply. */
+    windows: UsageWindow[];
+    credit?: CreditBalance;
+    /** When this snapshot was produced (epoch ms). */
+    updatedAt: number;
+    /** Error/hint message for `error` / `authRequired` / `notInstalled` states. */
+    message?: string;
+}
+/**
+ * `agent/usageStats` request: read usage for exactly these providers — only the
+ * ones the user activated. The reader never polls providers not listed here, so
+ * inactive providers cost nothing.
+ */
+export interface UsageStatsParams {
+    providers: UsageProvider[];
+}
+export interface UsageStatsResult {
+    usage: ProviderUsage[];
+}

package/dist/src/models/usage.js

@@ -0,0 +1,18 @@
+/**
+ * AI-provider usage statistics: quota/rate windows, plan/account, credit
+ * balance and local token tallies read from a coding CLI's on-disk state — its
+ * stored OAuth token (→ the provider's official usage API) and/or its local
+ * session logs.
+ *
+ * Surfaced in the desktop's Settings → Providers section and, over the bridge,
+ * on the phone. The access path is per-runtime by design (02a §5.8.10): the
+ * desktop reads these files natively in Rust; the bridge reads them in TS so a
+ * paired phone — which cannot see the PC's disk directly — gets the same data
+ * over `agent/usageStats`. The Dart equivalents live in uxnanmobile and are kept
+ * in sync manually (see 02e-bridge-integration.md §4.2).
+ *
+ * Posture: only the CLI's own stored token is read — never browser cookies or
+ * user-pasted API keys.
+ */
+export {};
+//# sourceMappingURL=usage.js.map

package/dist/src/models/usage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxnan/shared",
-  "version": "0.0.4-alpha.20260703",
+  "version": "0.0.5-alpha.20260711",
   "description": "Shared JSON-RPC and E2EE contracts for the Uxnan ecosystem (bridge, relay, mobile).",
   "license": "MPL-2.0",
   "author": "Luis Donaldo Gamas Vazquez",