@uxnan/shared 0.0.5-alpha.20260711 → 0.0.6-alpha.20260716

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 — **62 JSON-RPC methods** + **8 streaming
+> **Status:** implemented and stable — **66 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

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

@@ -3,7 +3,7 @@
  *
  * Source: architecture/02a-system-architecture.md §5.8.2 (adapters/base-adapter).
  */
-import type { AgentCapabilities, AgentId, AgentModel } from './agent-capabilities.js';
+import type { AgentCapabilities, AgentCommand, AgentCommandInvocation, AgentId, AgentModel } from './agent-capabilities.js';
 import type { AgentConfig } from './agent-config.js';
 import type { TurnAttachment } from '../models/workspace.js';
 import type { ApprovalDecision } from '../models/approval.js';
@@ -52,6 +52,15 @@ export interface SendTurnOptions {
      * configured default posture (no behaviour change).
      */
     accessMode?: AccessMode;
+    /**
+     * Invoke an advertised agent command (from `agent/commands`) instead of
+     * free-form {@link text}. The {@link AgentManager} resolves it before the
+     * adapter runs — expanding a custom prompt-template via {@link
+     * IAgentAdapter.expandCommand}, or composing the CLI's native `/name args`
+     * form — and sets {@link text} to the result, so most adapters need no
+     * per-command handling. Absent for an ordinary text turn.
+     */
+    command?: AgentCommandInvocation;
 }
 export interface IAgentAdapter {
     readonly agentId: AgentId;
@@ -75,4 +84,23 @@ export interface IAgentAdapter {
     onEvent(listener: (event: AgentStreamEvent) => void): () => void;
     /** List the models this agent's CLI reports as available (optional). */
     listModels?(): Promise<AgentModel[]>;
+    /**
+     * List the special ("slash") commands this agent exposes — control commands
+     * reachable headless plus user-defined prompt-template commands scanned from
+     * disk (optional; adapters with none simply don't implement it). `cwd` is the
+     * thread/project directory so project-scoped custom commands (`<cwd>/.claude/
+     * commands`, `<cwd>/.gemini/commands`, …) are discovered alongside user-level
+     * ones. Discovery only; invocation flows through {@link sendTurn} with {@link
+     * SendTurnOptions.command}.
+     */
+    listCommands?(cwd?: string): Promise<AgentCommand[]>;
+    /**
+     * Resolve a custom prompt-template command to the final prompt text (reads the
+     * template file from `cwd`/user config, substitutes arguments). Implemented
+     * only by adapters whose commands are prompt templates the bridge expands
+     * itself (Codex/Gemini/OpenCode); adapters whose commands run natively (Claude
+     * Code, ACP agents) leave it unset and receive the composed `/name args` form
+     * as {@link SendTurnOptions.text}. Throw if `name` is not a known custom command.
+     */
+    expandCommand?(name: string, args?: string, cwd?: string): Promise<string>;
 }

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

@@ -36,6 +36,13 @@ export interface AgentCapabilities {
      * false means the agent either gates tools or is pending approval wiring.
      */
     autonomous?: boolean;
+    /**
+     * Agent exposes special ("slash") commands the phone can discover via
+     * `agent/commands` and invoke through `turn/send` `command`. Optional for
+     * back-compat; absent/false means the agent advertises none (the phone shows
+     * only its client-side `/` palette). See {@link AgentCommand}.
+     */
+    commands?: boolean;
 }
 /**
  * A registered agent the phone can pick for a thread, returned by `agent/list`.
@@ -124,3 +131,52 @@ export interface AgentModel {
      */
     isLatestAlias?: boolean;
 }
+/**
+ * A special ("slash") command an agent exposes, returned by `agent/commands`.
+ *
+ * Two kinds are unified under this one shape:
+ * - **control** commands the CLI understands in its headless/programmatic mode
+ *   (Claude Code's `/compact` sent as the prompt with `--resume`; the commands
+ *   ACP agents advertise via `available_commands_update`), and
+ * - **custom** user-defined prompt-template commands (`.claude/commands`,
+ *   `~/.codex/prompts`, `.gemini/commands`, `.opencode/command`) that the bridge
+ *   expands itself before running a normal turn.
+ *
+ * The phone is a generic renderer: it lists the advertised commands in its `/`
+ * palette and, when one is picked, echoes it back on `turn/send` under
+ * {@link AgentCommandInvocation} — the bridge resolves it to the final prompt
+ * text (expanded template) or the CLI's native `/name args` form. Consumers MUST
+ * tolerate absent optional fields so a newer bridge advertising a richer command
+ * never breaks an older app.
+ */
+export interface AgentCommand {
+    /** Command name WITHOUT the leading slash (e.g. `compact`, `refactor`). */
+    name: string;
+    /** One-line description for the palette, when the source provides one. */
+    description?: string;
+    /** Hint for the arguments the command accepts (e.g. `<file> <priority>`). */
+    argumentHint?: string;
+    /**
+     * Where the command comes from: `acp` (advertised by an ACP agent),
+     * `builtin` (a CLI control command reachable headless), or `custom` (a
+     * user-defined prompt-template file the bridge expands).
+     */
+    source: 'acp' | 'builtin' | 'custom';
+    /**
+     * Whether the command actually runs in the agent's headless/programmatic mode.
+     * Absent/true means yes; `false` marks a command that only works in the CLI's
+     * interactive TUI, which the phone should hide. The bridge only advertises
+     * commands it can run, so this is a belt-and-suspenders gate.
+     */
+    headlessSupported?: boolean;
+}
+/**
+ * A picked {@link AgentCommand} carried on `turn/send` under `command`, instead
+ * of free-form `text`. The bridge resolves `{ name, args }` to the final prompt.
+ */
+export interface AgentCommandInvocation {
+    /** The command's {@link AgentCommand.name} (no leading slash). */
+    name: string;
+    /** Raw argument string the user appended after the command, if any. */
+    args?: string;
+}

package/dist/src/index.d.ts

@@ -24,5 +24,6 @@ export * from './models/session.js';
 export * from './models/approval.js';
 export * from './models/question.js';
 export * from './models/usage.js';
+export * from './models/metrics.js';
 export * from './validators/validate.js';
 export * from './validators/json-schema/schemas.js';

package/dist/src/index.js

@@ -30,6 +30,7 @@ export * from './models/session.js';
 export * from './models/approval.js';
 export * from './models/question.js';
 export * from './models/usage.js';
+export * from './models/metrics.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;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAElC,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;AAClC,cAAc,qBAAqB,CAAC;AAEpC,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", "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 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/commands", "agent/usageStats", "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"];
 export declare function isKnownMethod(method: string): method is JsonRpcMethodName;

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

@@ -53,7 +53,12 @@ export const METHOD_NAMES = [
     // Agents
     'agent/list',
     'agent/models',
+    'agent/commands',
     'agent/usageStats',
+    // Metrics (bridge-owned, survivable profile stats + tamper-proof backup)
+    'metrics/get',
+    'metrics/export',
+    'metrics/import',
     // 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,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"}
+{"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,gBAAgB;IAChB,kBAAkB;IAClB,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;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

@@ -13,8 +13,9 @@ 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 { AgentCommand, AgentCommandInvocation, AgentDescriptor, AgentId, AgentModel } from '../agents/agent-capabilities.js';
 import type { UsageStatsParams, UsageStatsResult } from '../models/usage.js';
+import type { MetricsExportParams, MetricsExportResult, MetricsImportParams, MetricsImportResult, MetricsSnapshot } from '../models/metrics.js';
 import type { PushPlatform } from '../notifications/push-payload.js';
 export interface ListThreadsParams {
     projectId?: string;
@@ -82,6 +83,14 @@ export interface TurnSendParams {
      * is not required.
      */
     questionResponse?: QuestionResponse;
+    /**
+     * Invoke an advertised agent command (from `agent/commands`) instead of
+     * free-form `text`. The bridge resolves `{ name, args }` to the final prompt —
+     * expanding a custom prompt-template file, or composing the CLI's native
+     * `/name args` form — then runs a normal turn. When present, `text` is not
+     * required.
+     */
+    command?: AgentCommandInvocation;
 }
 export interface ThreadSetModelParams {
     threadId: string;
@@ -220,6 +229,19 @@ export interface AgentModelsResult {
     /** Models the agent can use, with presentation metadata, as reported by its CLI. */
     models: AgentModel[];
 }
+export interface AgentCommandsParams {
+    agentId: AgentId;
+    /**
+     * Thread/project directory, so project-scoped custom commands (e.g.
+     * `<cwd>/.claude/commands`, `<cwd>/.gemini/commands`) are discovered alongside
+     * the user-level ones. Omitted → only user-level commands are returned.
+     */
+    cwd?: string;
+}
+export interface AgentCommandsResult {
+    /** Special ("slash") commands the agent exposes, discovered from its CLI/disk. */
+    commands: AgentCommand[];
+}
 /** What the phone wants to be notified about (background push). */
 export interface NotificationPreferences {
     /** Push when an agent turn completes. */
@@ -476,10 +498,26 @@ export interface JsonRpcMethodRegistry {
         params: AgentModelsParams;
         result: AgentModelsResult;
     };
+    'agent/commands': {
+        params: AgentCommandsParams;
+        result: AgentCommandsResult;
+    };
     'agent/usageStats': {
         params: UsageStatsParams;
         result: UsageStatsResult;
     };
+    'metrics/get': {
+        params: void;
+        result: MetricsSnapshot;
+    };
+    'metrics/export': {
+        params: MetricsExportParams;
+        result: MetricsExportResult;
+    };
+    'metrics/import': {
+        params: MetricsImportParams;
+        result: MetricsImportResult;
+    };
     'auth/status': {
         params: {
             agentId: AgentId;

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

@@ -0,0 +1,162 @@
+/**
+ * Profile metrics — a bridge-owned, survivable tally of a PC's activity, plus a
+ * tamper-proof export/import backup.
+ *
+ * The mobile profile screen shows aggregated metrics (conversations, messages,
+ * agents/models used, connection time, git actions, an activity heatmap). Those
+ * 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 computes them from its own authoritative data
+ * (the conversation store) plus persisted session + git-action event logs it
+ * observes itself, and serves them over `metrics/get`. The phone renders one
+ * snapshot per PC and sums across PCs.
+ *
+ * A `metrics/export` produces an opaque, tamper-proof file only the SAME bridge
+ * can later verify + decrypt (AES-256-GCM under a secret held in the PC's OS
+ * 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.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.11 and
+ * 02b-contracts-and-requirements.md.
+ */
+/** Transport a phone→PC connection session used. */
+export type MetricsTransport = 'relay' | 'direct';
+/** Per-agent conversation tally (most-used first). */
+export interface MetricsAgentUsage {
+    /** Agent wire id (e.g. `claude-code`, `codex`). */
+    agentId: string;
+    /** Conversations started with this agent on this PC. */
+    conversations: number;
+}
+/** One agent's activity on a given day (drives the per-agent bars). */
+export interface MetricsAgentDay {
+    /** Agent wire id (e.g. `claude-code`, `codex`). */
+    agentId: string;
+    /** Conversations (threads) this agent started that day. */
+    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). */
+    byAgent: MetricsAgentDay[];
+}
+/**
+ * One local calendar-day activity bucket. Counts are split by category so a
+ * client can render any metric filter (combined / conversations / messages /
+ * work) with no extra round-trip. Days with no activity are omitted.
+ */
+export interface MetricsActivityDay {
+    /**
+     * The calendar date this bucket covers, as **UTC-midnight epoch ms** of the
+     * bridge host's local date. Encoding the local date at UTC midnight (not the
+     * local-midnight instant) makes the key timezone-stable, so a phone in any
+     * timezone maps it to the correct heatmap cell.
+     */
+    day: number;
+    /** Conversations started that day. */
+    conversations: number;
+    /** Messages exchanged that day. */
+    messages: number;
+    /** Git/work actions performed that day. */
+    work: number;
+}
+/**
+ * Aggregated metrics for ONE PC (the bridge that returns it), built from the
+ * bridge's own authoritative data: the conversation store (threads/turns) plus
+ * its persisted session + git-action event logs. The phone renders this per PC
+ * and sums across PCs for the all-PCs profile. Every field is a count the phone
+ * cannot inflate — the bridge observes it. Source of `metrics/get`.
+ */
+export interface MetricsSnapshot {
+    /** Schema version, for forward-compatible parsing. */
+    version: number;
+    /** The bridge PC's `macDeviceId` this snapshot belongs to. */
+    deviceId: string;
+    /** Total conversations (threads) started on this PC. */
+    conversations: number;
+    /** Distinct agents used. */
+    agentsUsed: number;
+    /** Distinct models used. */
+    modelsUsed: number;
+    /** Total messages exchanged (both roles). */
+    messages: number;
+    /** Total git actions performed (mutating operations). */
+    gitActions: number;
+    /** Connection sessions recorded. */
+    sessions: number;
+    /** Cumulative connected time across all sessions, ms. */
+    totalConnectedMs: number;
+    /** The single longest connection session, ms. */
+    longestSessionMs: number;
+    /** Sessions that ran over the relay. */
+    relaySessions: number;
+    /** Sessions that ran over a direct LAN/Tailscale host. */
+    directSessions: number;
+    /** Per-agent conversation tallies, most-used first. */
+    byAgent: MetricsAgentUsage[];
+    /** Earliest conversation creation (epoch ms); absent when there are none. */
+    memberSince?: number;
+    /** Per-day activity buckets for the contribution heatmap. */
+    activity: MetricsActivityDay[];
+    /**
+     * Per-day activity split per agent (conversations, messages, tokens), 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}.
+     */
+    byAgentDay: MetricsDayBreakdown[];
+    /** When the bridge produced this snapshot (epoch ms). */
+    updatedAt: number;
+}
+/**
+ * `metrics/export` request. The bridge seals its metrics event log into an
+ * opaque, tamper-proof blob that only THIS same bridge can later verify +
+ * decrypt (AES-256-GCM under a secret held in the OS keychain). An optional user
+ * [passphrase] adds a second confidentiality layer (scrypt-derived), so a leaked
+ * file also needs the phrase; it must be supplied again at import.
+ */
+export interface MetricsExportParams {
+    /** Optional extra passphrase lock; required again at import when set. */
+    passphrase?: string;
+}
+export interface MetricsExportResult {
+    /** The sealed blob to write to a file (a JSON string, opaque to the phone). */
+    blob: string;
+    /** Suggested filename (e.g. `uxnan-metrics-<host>-<date>.uxmetrics`). */
+    filename: string;
+    /** Whether the blob carries an extra passphrase lock (import will need it). */
+    passphraseProtected: boolean;
+}
+/**
+ * `metrics/import` request. The phone sends back a previously exported [blob].
+ * The bridge verifies it was sealed by THIS PC — a foreign or edited file is
+ * rejected — decrypts it (using [passphrase] when the file was passphrase-locked)
+ * and merges its events by id (idempotent: re-importing the same file changes
+ * nothing). Returns the refreshed snapshot.
+ */
+export interface MetricsImportParams {
+    /** The sealed blob produced by a prior `metrics/export` on this PC. */
+    blob: string;
+    /** The passphrase, when the file was exported with one. */
+    passphrase?: string;
+}
+export interface MetricsImportResult {
+    /** How many new session + git-action events were merged in. */
+    imported: number;
+    /** The refreshed snapshot after the merge. */
+    snapshot: MetricsSnapshot;
+}

package/dist/src/models/metrics.js

@@ -0,0 +1,26 @@
+/**
+ * Profile metrics — a bridge-owned, survivable tally of a PC's activity, plus a
+ * tamper-proof export/import backup.
+ *
+ * The mobile profile screen shows aggregated metrics (conversations, messages,
+ * agents/models used, connection time, git actions, an activity heatmap). Those
+ * 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 computes them from its own authoritative data
+ * (the conversation store) plus persisted session + git-action event logs it
+ * observes itself, and serves them over `metrics/get`. The phone renders one
+ * snapshot per PC and sums across PCs.
+ *
+ * A `metrics/export` produces an opaque, tamper-proof file only the SAME bridge
+ * can later verify + decrypt (AES-256-GCM under a secret held in the PC's OS
+ * 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.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.11 and
+ * 02b-contracts-and-requirements.md.
+ */
+export {};
+//# sourceMappingURL=metrics.js.map

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

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

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

@@ -15,7 +15,7 @@
  * user-pasted API keys.
  */
 /** A coding CLI whose usage we read from its own stored token. */
-export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'gemini';
+export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'gemini' | 'grok';
 /** Outcome of reading one provider's usage. */
 export type UsageStatus = 
 /** Fresh quota/credit data was read. */
@@ -29,6 +29,22 @@ export type UsageStatus =
 /** 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';
+/**
+ * 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).
+ * Derived per provider from its plan / billing signals.
+ */
+export type AccountType = 
+/** A flat paid subscription (Pro / Max / Plus / Pro+ …). */
+'subscription'
+/** Usage-billed: credits, on-demand, or pay-as-you-go on top of / instead of a plan. */
+ | 'payAsYouGo'
+/** Free tier. */
+ | 'free'
+/** A team / organization seat. */
+ | 'team'
+/** An enterprise plan. */
+ | 'enterprise';
 /**
  * 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
@@ -59,6 +75,32 @@ export interface CreditBalance {
     period: string;
     /** When the balance resets (epoch ms), when known. */
     resetsAt?: number;
+    /** Amount still available this period, in `currency`, when the provider
+     *  reports a remaining balance directly (e.g. Grok on-demand / prepaid). */
+    available?: number;
+}
+/**
+ * "Reset credits" a provider grants to roll a hit rate-limit back early — Codex's
+ * rate-limit reset-credit system. Distinct from `credit` (money): these are
+ * redeemable reset tokens, not a balance.
+ */
+/** One redeemable reset — for the per-credit detail (which one, when it expires). */
+export interface ResetCreditEntry {
+    /** Short label the provider gives the reset (e.g. "Full reset"). */
+    title?: string;
+    /** When this reset lapses (epoch ms). */
+    expiresAt?: number;
+}
+export interface ResetCredits {
+    /** How many resets can be redeemed right now. */
+    available: number;
+    /** Total resets ever granted to this account, when reported. */
+    totalEarned?: number;
+    /** When the soonest still-available reset lapses (epoch ms), when known. */
+    nextExpiresAt?: number;
+    /** The individual available resets, soonest-expiring first, when the provider
+     *  details them. */
+    entries?: ResetCreditEntry[];
 }
 /** One provider's usage snapshot. */
 export interface ProviderUsage {
@@ -70,10 +112,13 @@ export interface ProviderUsage {
         email?: string;
         organization?: string;
         plan?: string;
+        accountType?: AccountType;
     };
     /** Quota/rate windows (percentage-based). Empty when none apply. */
     windows: UsageWindow[];
     credit?: CreditBalance;
+    /** Redeemable rate-limit resets (Codex), when the provider grants them. */
+    resetCredits?: ResetCredits;
     /** When this snapshot was produced (epoch ms). */
     updatedAt: number;
     /** Error/hint message for `error` / `authRequired` / `notInstalled` states. */

package/package.json

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