@uxnan/shared 0.0.20-alpha.20260926 → 0.0.22-alpha.20260927

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 — **83 JSON-RPC methods** + **22 streaming
+> **Status:** implemented and stable — **87 JSON-RPC methods** + **22 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

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", "queue/resume", "queue/clear", "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/worktrees", "git/log", "git/commitShow", "workspace/readFile", "workspace/readImage", "workspace/list", "workspace/searchFiles", "workspace/resolveFileLink", "workspace/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "project/add", "project/remove", "project/rename", "sync/changes", "settings/get", "settings/set", "device/describe", "device/rename", "agent/list", "agent/models", "agent/commands", "agent/usageStats", "agent/doctor", "metrics/get", "metrics/export", "metrics/import", "auth/status", "auth/login", "auth/logout", "notifications/register", "notifications/update", "notifications/unregister", "bridge/status", "bridge/generatePairingQr", "bridge/connectedPhones", "bridge/disconnectPhone", "bridge/trustedDevices", "bridge/removeTrustedDevice", "bridge/update", "bridge/checkForUpdate", "desktop/attach", "desktop/detach"];
+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", "turn/attachment", "queue/resume", "queue/clear", "queue/sendNow", "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/worktrees", "git/log", "git/commitShow", "workspace/readFile", "workspace/readImage", "workspace/list", "workspace/searchFiles", "workspace/resolveFileLink", "workspace/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "project/add", "project/remove", "project/rename", "sync/changes", "settings/get", "settings/set", "device/describe", "device/rename", "agent/list", "agent/models", "agent/commands", "agent/usageStats", "usage/redeemReset", "usage/summary", "agent/doctor", "metrics/get", "metrics/export", "metrics/import", "auth/status", "auth/login", "auth/logout", "notifications/register", "notifications/update", "notifications/unregister", "bridge/status", "bridge/generatePairingQr", "bridge/connectedPhones", "bridge/disconnectPhone", "bridge/trustedDevices", "bridge/removeTrustedDevice", "bridge/update", "bridge/checkForUpdate", "desktop/attach", "desktop/detach"];
 export declare function isKnownMethod(method: string): method is JsonRpcMethodName;

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

@@ -15,9 +15,11 @@ export const METHOD_NAMES = [
     'turn/read',
     'turn/send',
     'turn/cancel',
+    'turn/attachment',
     // Message queue
     'queue/resume',
     'queue/clear',
+    'queue/sendNow',
     // Git
     'git/status',
     'git/diff',
@@ -69,6 +71,8 @@ export const METHOD_NAMES = [
     'agent/models',
     'agent/commands',
     'agent/usageStats',
+    'usage/redeemReset',
+    'usage/summary',
     'agent/doctor',
     // Metrics (bridge-owned, survivable profile stats + tamper-proof backup)
     'metrics/get',

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,gBAAgB;IAChB,cAAc;IACd,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,eAAe;IACf,SAAS;IACT,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,2BAA2B;IAC3B,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,mCAAmC;IACnC,cAAc;IACd,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,cAAc;IACd,yEAAyE;IACzE,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,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;IAC5B,eAAe;IACf,uBAAuB;IACvB,mEAAmE;IACnE,gBAAgB;IAChB,gBAAgB;CACR,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,iBAAiB;IACjB,gBAAgB;IAChB,cAAc;IACd,aAAa;IACb,eAAe;IACf,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,eAAe;IACf,SAAS;IACT,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,2BAA2B;IAC3B,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,mCAAmC;IACnC,cAAc;IACd,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,eAAe;IACf,cAAc;IACd,yEAAyE;IACzE,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,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;IAC5B,eAAe;IACf,uBAAuB;IACvB,mEAAmE;IACnE,gBAAgB;IAChB,gBAAgB;CACR,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

@@ -15,7 +15,7 @@ import type { QuestionResponse } from '../models/question.js';
 import type { BridgeStatus, BridgeUpdate, ConnectedPhone, DeviceDescribeParams, DeviceDescription, DeviceRenameParams, TrustedDevice } from '../models/session.js';
 import type { PairingPayload } from '../e2ee/pairing-payload.js';
 import type { AgentCommand, AgentCommandInvocation, AgentDescriptor, AgentDiagnosis, AgentId, AgentModel } from '../agents/agent-capabilities.js';
-import type { UsageStatsParams, UsageStatsResult } from '../models/usage.js';
+import type { ProviderUsage, UsageRedeemResetParams, UsageStatsParams, UsageStatsResult, UsageSummary, UsageSummaryParams } from '../models/usage.js';
 import type { MetricsExportParams, MetricsExportResult, MetricsImportParams, MetricsImportResult, MetricsSnapshot } from '../models/metrics.js';
 import type { PushPlatform } from '../notifications/push-payload.js';
 import type { DesktopAttachParams, DesktopAttachResult } from '../local-control/local-control.js';
@@ -47,6 +47,17 @@ export interface TurnListParams {
      */
     fromEnd?: boolean;
 }
+/** `turn/attachment`: one image a user message carries (`Message.attachments`). */
+export interface TurnAttachmentParams {
+    threadId: string;
+    attachmentId: string;
+}
+/** The image's bytes, as they were sent. */
+export interface TurnAttachmentData {
+    mimeType: string;
+    /** Base64 payload (no `data:` URI prefix). */
+    base64Data: string;
+}
 export interface TurnSendParams {
     threadId: string;
     /**
@@ -421,6 +432,11 @@ export interface JsonRpcMethodRegistry {
         };
         result: void;
     };
+    /** The bytes of an image a user message carries (`Message.attachments`). */
+    'turn/attachment': {
+        params: TurnAttachmentParams;
+        result: TurnAttachmentData;
+    };
     /** Resumes draining after a stop/failure held the queue. */
     'queue/resume': {
         params: {
@@ -435,6 +451,19 @@ export interface JsonRpcMethodRegistry {
         };
         result: QueueStateResult;
     };
+    /**
+     * Sends one queued message now: into the running turn when its agent takes
+     * input mid-turn (`capabilities.steering`), else — nothing running — as the
+     * next turn at once, through a pause. Refused while a turn runs whose agent
+     * cannot take it, or the agent waits on the person's answer.
+     */
+    'queue/sendNow': {
+        params: {
+            threadId: string;
+            turnId: string;
+        };
+        result: QueueStateResult;
+    };
     'git/status': {
         params: {
             cwd: string;
@@ -645,6 +674,16 @@ export interface JsonRpcMethodRegistry {
         params: UsageStatsParams;
         result: UsageStatsResult;
     };
+    /** Redeem a rate-limit reset (Codex); answers the provider's fresh usage. */
+    'usage/redeemReset': {
+        params: UsageRedeemResetParams;
+        result: ProviderUsage;
+    };
+    /** Tokens and cost the agent CLIs on this PC spent, by day, agent and model. */
+    'usage/summary': {
+        params: UsageSummaryParams;
+        result: UsageSummary;
+    };
     'agent/doctor': {
         params: void;
         result: {

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

@@ -7,7 +7,7 @@
  * were derived on the phone from local storage and so were lost on an app
  * uninstall (the app has no cloud login). To make them durable, the **bridge**
  * becomes the source of truth: it persists a complete activity ledger
- * (conversations, turns/messages, reported tokens, sessions and Git actions)
+ * (conversations, turns/messages, sessions and Git actions)
  * and serves it over `metrics/get`. Deleting mutable conversation history does
  * not subtract activity. The phone renders one snapshot per PC and sums PCs.
  *
@@ -16,8 +16,10 @@
  * keychain), so users cannot fabricate or edit their stats; `metrics/import`
  * feeds one back and merges its events by id (idempotent).
  *
- * Provider usage/credits are deliberately NOT part of this — those are read live
- * via `agent/usageStats` and never persisted.
+ * What the agents spent (tokens, cost) and provider limits are deliberately NOT
+ * part of this: `usage/summary` reads spend from each CLI's own history (every
+ * session, not only the bridge's) and `agent/usageStats` asks for limits live.
+ * The development `echo` agent is never counted.
  *
  * Source: architecture/02a-system-architecture.md §5.8.11 and
  * 02b-contracts-and-requirements.md.
@@ -39,19 +41,12 @@ export interface MetricsAgentDay {
     conversations: number;
     /** Messages exchanged that day in this agent's threads. */
     messages: number;
-    /**
-     * Tokens processed that day — the sum of each turn's reported usage (input
-     * incl. the re-sent context + output). **Throughput, not billed cost**: caching
-     * and input/output pricing differ (use `agent/usageStats` for money). 0 for
-     * agents that don't report usage (e.g. Zero).
-     */
-    tokens: number;
 }
 /** One calendar day's activity split per agent. */
 export interface MetricsDayBreakdown {
     /** UTC-midnight epoch ms of the calendar date (same encoding as `activity`). */
     day: number;
-    /** Per-agent activity that day (agents with any conversation/message/token). */
+    /** Per-agent activity that day (agents with any conversation or message). */
     byAgent: MetricsAgentDay[];
 }
 /**
@@ -112,7 +107,7 @@ export interface MetricsSnapshot {
     /** Per-day activity buckets for the contribution heatmap. */
     activity: MetricsActivityDay[];
     /**
-     * Per-day activity split per agent (conversations, messages, tokens), for the
+     * Per-day activity split per agent (conversations, messages), for the
      * unified agent-activity view: the per-agent bars show all-time totals, or a
      * single day's totals when a heatmap cell is selected. See
      * {@link MetricsAgentDay}.

package/dist/src/models/metrics.js

@@ -7,7 +7,7 @@
  * were derived on the phone from local storage and so were lost on an app
  * uninstall (the app has no cloud login). To make them durable, the **bridge**
  * becomes the source of truth: it persists a complete activity ledger
- * (conversations, turns/messages, reported tokens, sessions and Git actions)
+ * (conversations, turns/messages, sessions and Git actions)
  * and serves it over `metrics/get`. Deleting mutable conversation history does
  * not subtract activity. The phone renders one snapshot per PC and sums PCs.
  *
@@ -16,8 +16,10 @@
  * keychain), so users cannot fabricate or edit their stats; `metrics/import`
  * feeds one back and merges its events by id (idempotent).
  *
- * Provider usage/credits are deliberately NOT part of this — those are read live
- * via `agent/usageStats` and never persisted.
+ * What the agents spent (tokens, cost) and provider limits are deliberately NOT
+ * part of this: `usage/summary` reads spend from each CLI's own history (every
+ * session, not only the bridge's) and `agent/usageStats` asks for limits live.
+ * The development `echo` agent is never counted.
  *
  * Source: architecture/02a-system-architecture.md §5.8.11 and
  * 02b-contracts-and-requirements.md.

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

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

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

@@ -64,8 +64,30 @@ export interface Message {
         tokens: number;
         contextWindow?: number;
     };
+    /**
+     * The images and files the user attached to this message, kept by the bridge
+     * with the turn (user messages only). They are named here, not inlined — a page of
+     * history stays small — and each client fetches the bytes it shows with
+     * `turn/attachment`.
+     */
+    attachments?: MessageAttachment[];
     createdAt: number;
 }
+/** An image or a file attached to a user message, as `turn/list` names it. */
+export interface MessageAttachment {
+    /** Opaque id, unique in its thread; the key for `turn/attachment`. */
+    id: string;
+    /** MIME type, e.g. `image/png`. */
+    mimeType: string;
+    /** Size of the stored image or file in bytes. */
+    bytes: number;
+    /** A file's name, as it was sent (absent for an image). */
+    name?: string;
+    /** Pixel width, when the sender knew it. */
+    width?: number;
+    /** Pixel height, when the sender knew it. */
+    height?: number;
+}
 /**
  * One exchange: at most one user message (absent when the agent spoke on its
  * own) and ONE assistant message, whose `segments` carry its prose and steps

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

@@ -1,21 +1,17 @@
 /**
- * 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.
+ * AI-provider usage: plan limits (quota windows, plan, account, credit) and
+ * spend (tokens and cost by day, agent and model).
  *
- * 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 token the CLI itself stored is read — from its file, or
- * from the OS credential store where that is where the CLI keeps it (Claude
- * Code on macOS), and then only after the user has granted the OS-level
- * permission once (see `accessRequired`). Never browser cookies, never
- * user-pasted API keys, never a refresh token.
+ * The bridge is the one reader; every client — the phone, Uxnan Desktop's
+ * Providers panel — asks it (`agent/usageStats`, `usage/summary`,
+ * `usage/redeemReset`). Claude Code and Codex are asked themselves: each CLI
+ * answers for the account it is signed in to, so no credential is read and no
+ * OS permission is needed. Copilot and Grok have no such surface: only the
+ * token each CLI stored is read (`gh auth token`, `~/.grok/auth.json`) and sent
+ * to the provider's own usage API. Spend comes from the transcripts every
+ * agent CLI keeps on disk. Never browser cookies, never a pasted key, never a
+ * refresh token. The Dart equivalents live in uxnanmobile and are kept in sync
+ * manually.
  */
 /** A coding CLI whose usage we read from its own stored token. */
 export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'grok';
@@ -25,18 +21,13 @@ export type UsageStatus =
 'ok'
 /** CLI is present but not signed in (no usable token). */
  | 'authRequired'
-/** The CLI's token exists in the OS credential store, but the OS has not yet
- *  authorized the reader to open it. The user grants that once from the
- *  desktop's Providers panel (the OS shows its own dialog); the reader never
- *  prompts on its own. A phone shows "grant access on the PC". */
- | 'accessRequired'
 /** 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';
+/** How the data was obtained: asked of the CLI itself (`cli`, Claude Code and
+ *  Codex), or its stored token sent to the provider's usage API (`token`). */
+export type UsageSource = 'cli' | 'token';
 /**
  * The kind of billing relationship, so the UI can label an account beyond its
  * plan name (e.g. distinguish a flat subscription from usage/credit billing).
@@ -94,6 +85,8 @@ export interface CreditBalance {
  */
 /** One redeemable reset — for the per-credit detail (which one, when it expires). */
 export interface ResetCreditEntry {
+    /** The provider's id for this reset, to redeem exactly it (`usage/redeemReset`). */
+    id?: string;
     /** Short label the provider gives the reset (e.g. "Full reset"). */
     title?: string;
     /** When this reset lapses (epoch ms). */
@@ -129,8 +122,7 @@ export interface ProviderUsage {
     resetCredits?: ResetCredits;
     /** When this snapshot was produced (epoch ms). */
     updatedAt: number;
-    /** Error/hint message for `error` / `authRequired` / `accessRequired` /
-     *  `notInstalled` states. */
+    /** Error/hint message for `error` / `authRequired` / `notInstalled` states. */
     message?: string;
 }
 /**
@@ -144,3 +136,77 @@ export interface UsageStatsParams {
 export interface UsageStatsResult {
     usage: ProviderUsage[];
 }
+/**
+ * `usage/redeemReset` request: redeem one of a provider's rate-limit resets
+ * (Codex today) — [creditId] from `ResetCredits.entries`, or the
+ * soonest-expiring one when absent. [idempotencyKey] names the attempt, so a
+ * retry after a lost answer never redeems twice.
+ */
+export interface UsageRedeemResetParams {
+    provider: UsageProvider;
+    idempotencyKey: string;
+    creditId?: string;
+}
+/**
+ * `usage/summary` request: the last [days] calendar days of this PC (today
+ * included), 1–366.
+ */
+export interface UsageSummaryParams {
+    days: number;
+}
+/** Tokens and cost of a set of model responses. */
+export interface UsageSpend {
+    /** Input not read from the cache. */
+    inputTokens: number;
+    /** Input read from the cache. */
+    cachedInputTokens: number;
+    /** Input written to the cache. */
+    cacheWriteTokens: number;
+    /** Output, reasoning included. */
+    outputTokens: number;
+    /** The reasoning part of `outputTokens`, where the CLI records it. */
+    reasoningTokens: number;
+    /** US dollars: what the provider billed where the CLI records it, else the
+     *  estimate at API prices (`estimatedCostUsd` of it). */
+    costUsd: number;
+    /** The part of `costUsd` estimated at API prices (on a subscription, what
+     *  the same work would cost pay-as-you-go). */
+    estimatedCostUsd: number;
+    /** Tokens of responses whose model has no known price — not in `costUsd`. */
+    unpricedTokens: number;
+    /** Model responses counted. */
+    responses: number;
+}
+/** One agent + model's spend on one day. */
+export interface UsageBucket extends UsageSpend {
+    /** Wire agent id (`claude-code`, `codex`, `pi-agent`, `grok`, `opencode`). */
+    agentId: string;
+    /** The model id as the CLI recorded it (`provider/model` where it routes). */
+    model: string;
+}
+/** One calendar day of this PC. */
+export interface UsageDay {
+    /** `YYYY-MM-DD`, the PC's local date. */
+    day: string;
+    buckets: UsageBucket[];
+}
+/** What was found for one agent. */
+export interface UsageAgentSource {
+    agentId: string;
+    /** Sessions with spend in the period. */
+    sessions: number;
+    /** `ok`: read (possibly nothing in the period); `unreadable`: its store
+     *  exists but could not be read (see `message`). Agents with no store on
+     *  this PC are not listed. */
+    status: 'ok' | 'unreadable';
+    message?: string;
+}
+/**
+ * `usage/summary` result: every model response the agent CLIs on this PC
+ * recorded in the period — the bridge's turns and a person's own terminal
+ * sessions alike — by day, agent and model. Only days with spend are listed.
+ */
+export interface UsageSummary {
+    days: UsageDay[];
+    agents: UsageAgentSource[];
+}

package/dist/src/models/usage.js

@@ -1,21 +1,17 @@
 /**
- * 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.
+ * AI-provider usage: plan limits (quota windows, plan, account, credit) and
+ * spend (tokens and cost by day, agent and model).
  *
- * 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 token the CLI itself stored is read — from its file, or
- * from the OS credential store where that is where the CLI keeps it (Claude
- * Code on macOS), and then only after the user has granted the OS-level
- * permission once (see `accessRequired`). Never browser cookies, never
- * user-pasted API keys, never a refresh token.
+ * The bridge is the one reader; every client — the phone, Uxnan Desktop's
+ * Providers panel — asks it (`agent/usageStats`, `usage/summary`,
+ * `usage/redeemReset`). Claude Code and Codex are asked themselves: each CLI
+ * answers for the account it is signed in to, so no credential is read and no
+ * OS permission is needed. Copilot and Grok have no such surface: only the
+ * token each CLI stored is read (`gh auth token`, `~/.grok/auth.json`) and sent
+ * to the provider's own usage API. Spend comes from the transcripts every
+ * agent CLI keeps on disk. Never browser cookies, never a pasted key, never a
+ * refresh token. The Dart equivalents live in uxnanmobile and are kept in sync
+ * manually.
  */
 export {};
 //# sourceMappingURL=usage.js.map

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

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

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

@@ -26,14 +26,21 @@ export interface WorkspaceFileTarget {
     path: string;
 }
 /**
- * An image (or other media) attached to a user turn (`turn/send { attachments }`).
- * Tolerant by design — the phone sends inline base64 with the original
+ * An image or a file attached to a user turn (`turn/send { attachments }`).
+ * Tolerant by design — clients send inline base64 with the original
  * `mimeType`; `path`/`width`/`height` are best-effort metadata. At least one of
  * `base64Data`/`path` must be present for the bridge to deliver it to the agent.
+ * The bridge writes each one into the agent's folder for the turn and names
+ * it in the prompt, so every agent opens it with its own tools; a file keeps
+ * its `name` there. At most {@link MAX_ATTACHMENT_BYTES} each.
  */
+/** The largest attachment `turn/send` takes, decoded: 20 MB. */
+export declare const MAX_ATTACHMENT_BYTES: number;
 export interface TurnAttachment {
-    /** Wire discriminator (always `image` today). */
-    type?: 'image';
+    /** An image (the default), or any other file. */
+    type?: 'image' | 'file';
+    /** A file's name (no directories), kept when the agent receives it. */
+    name?: string;
     /** MIME type, e.g. `image/png`. */
     mimeType: string;
     /** Inline base64 payload (no `data:` URI prefix). */

package/dist/src/models/workspace.js

@@ -3,5 +3,15 @@
  *
  * Source: architecture/02a-system-architecture.md §5.8.7.
  */
-export {};
+/**
+ * An image or a file attached to a user turn (`turn/send { attachments }`).
+ * Tolerant by design — clients send inline base64 with the original
+ * `mimeType`; `path`/`width`/`height` are best-effort metadata. At least one of
+ * `base64Data`/`path` must be present for the bridge to deliver it to the agent.
+ * The bridge writes each one into the agent's folder for the turn and names
+ * it in the prompt, so every agent opens it with its own tools; a file keeps
+ * its `name` there. At most {@link MAX_ATTACHMENT_BYTES} each.
+ */
+/** The largest attachment `turn/send` takes, decoded: 20 MB. */
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
 //# sourceMappingURL=workspace.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/models/workspace.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/models/workspace.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2BH;;;;;;;;GAQG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/package.json

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