@uxnan/shared 0.0.3-alpha.20260702 → 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,8 +52,9 @@ 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, 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 |
 
 ## Usage

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

@@ -14,6 +14,7 @@ export * from './e2ee/pairing-payload.js';
 export * from './agents/agent-capabilities.js';
 export * from './agents/agent-config.js';
 export * from './agents/agent-adapter.js';
+export * from './version/compare.js';
 export * from './notifications/push-payload.js';
 export * from './models/thread.js';
 export * from './models/git.js';
@@ -21,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

@@ -17,6 +17,8 @@ export * from './e2ee/pairing-payload.js';
 export * from './agents/agent-capabilities.js';
 export * from './agents/agent-config.js';
 export * from './agents/agent-adapter.js';
+// Version
+export * from './version/compare.js';
 // Notifications
 export * from './notifications/push-payload.js';
 // Models
@@ -26,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,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/session.d.ts

@@ -25,4 +25,16 @@ export interface BridgeStatus {
     activeSessions: number;
     platform: NodeJS.Platform | string;
     uptimeMs: number;
+    /**
+     * Latest bridge version published to npm (dist-tag `alpha`), as discovered by
+     * the bridge's own background update check. Absent when the check hasn't run
+     * yet or couldn't reach the registry (offline) — never blocks status.
+     */
+    latestVersion?: string;
+    /**
+     * True when {@link latestVersion} is strictly newer than {@link version}
+     * (SemVer precedence). Lets the phone show a "bridge update available" hint
+     * without querying npm itself. Absent/false when unknown or up to date.
+     */
+    updateAvailable?: boolean;
 }

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/dist/src/version/compare.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Semantic-version comparison shared across the ecosystem.
+ *
+ * Uxnan versions follow SemVer with a date-stamped prerelease, e.g.
+ * `0.0.3-alpha.20260702` (and, on mobile, an optional `+<build>` metadata
+ * suffix). This implements SemVer 2.0.0 precedence (§11) closely enough for
+ * those formats — enough for the bridge to decide "is the published version
+ * newer than mine?" without pulling in a `semver` dependency.
+ *
+ * Build metadata (`+...`) is ignored for precedence, per the spec.
+ */
+/**
+ * Compare two SemVer strings. Returns `-1` if `a < b`, `1` if `a > b`, `0` if
+ * they are precedence-equal. Unparseable inputs sort as *lower* than any
+ * parseable version (and equal to each other), so a garbage/absent version
+ * never masquerades as "newer".
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * True when `candidate` is a strictly newer version than `current`. Used to
+ * decide whether to announce an available update. A candidate that is absent or
+ * unparseable is never treated as newer.
+ */
+export declare function isNewerVersion(candidate: string | undefined | null, current: string): boolean;

package/dist/src/version/compare.js

@@ -0,0 +1,116 @@
+/**
+ * Semantic-version comparison shared across the ecosystem.
+ *
+ * Uxnan versions follow SemVer with a date-stamped prerelease, e.g.
+ * `0.0.3-alpha.20260702` (and, on mobile, an optional `+<build>` metadata
+ * suffix). This implements SemVer 2.0.0 precedence (§11) closely enough for
+ * those formats — enough for the bridge to decide "is the published version
+ * newer than mine?" without pulling in a `semver` dependency.
+ *
+ * Build metadata (`+...`) is ignored for precedence, per the spec.
+ */
+/** Parse `MAJOR.MINOR.PATCH[-prerelease][+build]`, or `null` if unparseable. */
+function parseVersion(version) {
+    const trimmed = version.trim();
+    if (!trimmed)
+        return null;
+    // Strip build metadata (everything from the first `+`), which never affects
+    // precedence.
+    const noBuild = trimmed.split('+', 1)[0];
+    const dashIndex = noBuild.indexOf('-');
+    const core = dashIndex === -1 ? noBuild : noBuild.slice(0, dashIndex);
+    const prereleaseRaw = dashIndex === -1 ? '' : noBuild.slice(dashIndex + 1);
+    const coreParts = core.split('.');
+    if (coreParts.length !== 3)
+        return null;
+    const major = Number(coreParts[0]);
+    const minor = Number(coreParts[1]);
+    const patch = Number(coreParts[2]);
+    if (!Number.isInteger(major) ||
+        !Number.isInteger(minor) ||
+        !Number.isInteger(patch) ||
+        major < 0 ||
+        minor < 0 ||
+        patch < 0) {
+        return null;
+    }
+    const prerelease = prereleaseRaw.length > 0 ? prereleaseRaw.split('.') : [];
+    return { major, minor, patch, prerelease };
+}
+/** Numeric identifiers are all-digits (SemVer §9). */
+function isNumericIdentifier(id) {
+    return id.length > 0 && /^[0-9]+$/.test(id);
+}
+/** Compare two prerelease identifier lists per SemVer §11. */
+function comparePrerelease(a, b) {
+    // A release with no prerelease outranks one that has a prerelease.
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1; // `a` is stable, `b` is prerelease → a > b
+    if (b.length === 0)
+        return -1;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const idA = a[i];
+        const idB = b[i];
+        if (idA === idB)
+            continue;
+        const numA = isNumericIdentifier(idA);
+        const numB = isNumericIdentifier(idB);
+        if (numA && numB) {
+            const diff = Number(idA) - Number(idB);
+            if (diff !== 0)
+                return diff < 0 ? -1 : 1;
+        }
+        else if (numA) {
+            return -1; // numeric identifiers have lower precedence than alphanumeric
+        }
+        else if (numB) {
+            return 1;
+        }
+        else {
+            return idA < idB ? -1 : 1; // lexical ASCII order
+        }
+    }
+    // All shared identifiers equal → the longer set has higher precedence.
+    if (a.length === b.length)
+        return 0;
+    return a.length < b.length ? -1 : 1;
+}
+/**
+ * Compare two SemVer strings. Returns `-1` if `a < b`, `1` if `a > b`, `0` if
+ * they are precedence-equal. Unparseable inputs sort as *lower* than any
+ * parseable version (and equal to each other), so a garbage/absent version
+ * never masquerades as "newer".
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa && !pb)
+        return 0;
+    if (!pa)
+        return -1;
+    if (!pb)
+        return 1;
+    if (pa.major !== pb.major)
+        return pa.major < pb.major ? -1 : 1;
+    if (pa.minor !== pb.minor)
+        return pa.minor < pb.minor ? -1 : 1;
+    if (pa.patch !== pb.patch)
+        return pa.patch < pb.patch ? -1 : 1;
+    return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+/**
+ * True when `candidate` is a strictly newer version than `current`. Used to
+ * decide whether to announce an available update. A candidate that is absent or
+ * unparseable is never treated as newer.
+ */
+export function isNewerVersion(candidate, current) {
+    if (!candidate)
+        return false;
+    if (parseVersion(candidate) === null)
+        return false;
+    return compareVersions(candidate, current) > 0;
+}
+//# sourceMappingURL=compare.js.map

package/dist/src/version/compare.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxnan/shared",
-  "version": "0.0.3-alpha.20260702",
+  "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",