@uxnan/shared 0.0.18-alpha.20260926 → 0.0.19-alpha.20260926

package/README.md

@@ -3,7 +3,7 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-ESM-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
 ![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
 ![JSON Schema](https://img.shields.io/badge/validation-Ajv-000000?style=for-the-badge&logo=json&logoColor=white)
-![Contracts](https://img.shields.io/badge/81_methods_%7C_21_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/82_methods_%7C_22_notifications-blue?style=for-the-badge)
 
 Shared JSON-RPC and E2EE contracts for the [Uxnan](../README.md) ecosystem — the
 single source of truth every component agrees on. Consumed as a local workspace
@@ -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 — **81 JSON-RPC methods** + **21 streaming
+> **Status:** implemented and stable — **82 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", "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", "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", "desktop/attach", "desktop/detach"];
 export declare function isKnownMethod(method: string): method is JsonRpcMethodName;

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

@@ -89,6 +89,7 @@ export const METHOD_NAMES = [
     'bridge/disconnectPhone',
     'bridge/trustedDevices',
     'bridge/removeTrustedDevice',
+    'bridge/update',
     // Desktop tools for bridge-run agents (local control channel only)
     'desktop/attach',
     'desktop/detach',

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,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,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,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

@@ -12,7 +12,7 @@ import type { AuthStatus, Project, ProjectAddParams, ProjectRemoveParams, Projec
 import type { BridgeSettings, SettingsSetParams, SyncChanges, SyncChangesParams } from '../models/sync.js';
 import type { ApprovalResponse } from '../models/approval.js';
 import type { QuestionResponse } from '../models/question.js';
-import type { BridgeStatus, ConnectedPhone, DeviceDescribeParams, DeviceDescription, DeviceRenameParams, TrustedDevice } from '../models/session.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';
@@ -719,6 +719,10 @@ export interface JsonRpcMethodRegistry {
         };
         result: void;
     };
+    'bridge/update': {
+        params: void;
+        result: BridgeUpdate;
+    };
     'desktop/attach': {
         params: DesktopAttachParams;
         result: DesktopAttachResult;

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

@@ -13,7 +13,7 @@ import type { ApprovalDecision } from '../models/approval.js';
 import type { QueuePausedReason, Thread, Turn } from '../models/thread.js';
 import type { Project } from '../models/project.js';
 import type { BridgeSettings, ClientPresence } from '../models/sync.js';
-import type { TrustedDevice } from '../models/session.js';
+import type { BridgeUpdate, TrustedDevice } from '../models/session.js';
 import type { AgentDescriptor } from '../agents/agent-capabilities.js';
 export declare const StreamNotification: {
     readonly TurnStarted: "stream/turn/started";
@@ -61,6 +61,12 @@ export declare const StreamNotification: {
     readonly DevicesUpdated: "stream/devices/updated";
     /** An agent became available or unavailable (installed, removed). */
     readonly AgentsUpdated: "stream/agents/updated";
+    /**
+     * The bridge's own update changed: a newer version was published, or an
+     * update started or failed. The whole state, as `bridge/status` → `update`
+     * would answer now (idempotent).
+     */
+    readonly BridgeUpdated: "stream/bridge/updated";
 };
 export type StreamNotification = (typeof StreamNotification)[keyof typeof StreamNotification];
 export interface TurnStartedParams {
@@ -219,6 +225,10 @@ export interface DevicesUpdatedParams {
 export interface AgentsUpdatedParams {
     agents: AgentDescriptor[];
 }
+/** The bridge's update, as `bridge/status` → `update` would answer now. */
+export interface BridgeUpdatedParams {
+    update: BridgeUpdate;
+}
 /**
  * A user turn was stored: it started right away (`status` `pending`) or it was
  * queued behind the running one (`queued`). `turn.messages` holds the user's

package/dist/src/jsonrpc/notifications.js

@@ -44,5 +44,11 @@ export const StreamNotification = {
     DevicesUpdated: 'stream/devices/updated',
     /** An agent became available or unavailable (installed, removed). */
     AgentsUpdated: 'stream/agents/updated',
+    /**
+     * The bridge's own update changed: a newer version was published, or an
+     * update started or failed. The whole state, as `bridge/status` → `update`
+     * would answer now (idempotent).
+     */
+    BridgeUpdated: 'stream/bridge/updated',
 };
 //# sourceMappingURL=notifications.js.map

package/dist/src/jsonrpc/notifications.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../../src/jsonrpc/notifications.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,qBAAqB;IAClC,YAAY,EAAE,sBAAsB;IACpC,kFAAkF;IAClF,aAAa,EAAE,uBAAuB;IACtC,mFAAmF;IACnF,YAAY,EAAE,sBAAsB;IACpC,aAAa,EAAE,uBAAuB;IACtC,SAAS,EAAE,mBAAmB;IAC9B,WAAW,EAAE,qBAAqB;IAClC,2EAA2E;IAC3E,aAAa,EAAE,uBAAuB;IACtC,+EAA+E;IAC/E,YAAY,EAAE,sBAAsB;IACpC,sFAAsF;IACtF,aAAa,EAAE,uBAAuB;IACtC;;;;OAIG;IACH,aAAa,EAAE,uBAAuB;IACtC,4BAA4B;IAC5B,aAAa,EAAE,uBAAuB;IACtC;;;;OAIG;IACH,WAAW,EAAE,qBAAqB;IAClC,oEAAoE;IACpE,gBAAgB,EAAE,0BAA0B;IAC5C,6EAA6E;IAC7E,gBAAgB,EAAE,0BAA0B;IAC5C,qDAAqD;IACrD,cAAc,EAAE,wBAAwB;IACxC,wEAAwE;IACxE,cAAc,EAAE,wBAAwB;IACxC,yEAAyE;IACzE,eAAe,EAAE,yBAAyB;IAC1C,0CAA0C;IAC1C,eAAe,EAAE,yBAAyB;IAC1C,uDAAuD;IACvD,cAAc,EAAE,wBAAwB;IACxC,qEAAqE;IACrE,aAAa,EAAE,uBAAuB;CAC9B,CAAC"}
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../../src/jsonrpc/notifications.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,qBAAqB;IAClC,YAAY,EAAE,sBAAsB;IACpC,kFAAkF;IAClF,aAAa,EAAE,uBAAuB;IACtC,mFAAmF;IACnF,YAAY,EAAE,sBAAsB;IACpC,aAAa,EAAE,uBAAuB;IACtC,SAAS,EAAE,mBAAmB;IAC9B,WAAW,EAAE,qBAAqB;IAClC,2EAA2E;IAC3E,aAAa,EAAE,uBAAuB;IACtC,+EAA+E;IAC/E,YAAY,EAAE,sBAAsB;IACpC,sFAAsF;IACtF,aAAa,EAAE,uBAAuB;IACtC;;;;OAIG;IACH,aAAa,EAAE,uBAAuB;IACtC,4BAA4B;IAC5B,aAAa,EAAE,uBAAuB;IACtC;;;;OAIG;IACH,WAAW,EAAE,qBAAqB;IAClC,oEAAoE;IACpE,gBAAgB,EAAE,0BAA0B;IAC5C,6EAA6E;IAC7E,gBAAgB,EAAE,0BAA0B;IAC5C,qDAAqD;IACrD,cAAc,EAAE,wBAAwB;IACxC,wEAAwE;IACxE,cAAc,EAAE,wBAAwB;IACxC,yEAAyE;IACzE,eAAe,EAAE,yBAAyB;IAC1C,0CAA0C;IAC1C,eAAe,EAAE,yBAAyB;IAC1C,uDAAuD;IACvD,cAAc,EAAE,wBAAwB;IACxC,qEAAqE;IACrE,aAAa,EAAE,uBAAuB;IACtC;;;;OAIG;IACH,aAAa,EAAE,uBAAuB;CAC9B,CAAC"}

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

@@ -75,17 +75,17 @@ export interface BridgeStatus {
     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.
+     * The bridge's own update: the newest published version it knows of, whether
+     * it can install that version and restart itself, and how an update under way
+     * is going ({@link BridgeUpdate}). Every client reads it here and follows
+     * `stream/bridge/updated`; none of them asks npm itself.
+     *
+     * **Absent means the bridge predates updating itself**, and is therefore older
+     * than the client reading this: a client offers the update it can do on its
+     * own (Uxnan Desktop installs the published bridge) or says to update the
+     * bridge on the PC (the phone).
      */
-    updateAvailable?: boolean;
+    update?: BridgeUpdate;
     /**
      * Threads with a turn in flight right now, whichever client started it.
      * Absent on an older bridge. A client uses it to wait for a quiet moment
@@ -110,6 +110,58 @@ export interface BridgeStatus {
     /** Who is connected right now. Absent on an older bridge. */
     clients?: ClientPresence[];
 }
+/**
+ * Where an update of the bridge stands. `updating` spans the whole handover —
+ * the bridge stops, installs the published version and its service starts the
+ * new one — so a client sees the connection drop and come back on the new
+ * {@link BridgeUpdate.version}; the outcome of a failed install is reported by
+ * the bridge that comes back.
+ */
+export type BridgeUpdatePhase = 'idle' | 'updating' | 'failed';
+/**
+ * Why an update did not happen:
+ * - `busy`: a turn is running on some client — the bridge never restarts
+ *   under one; try again when it ends.
+ * - `unsupported`: this bridge cannot replace itself (see
+ *   {@link BridgeUpdate.canApply}).
+ * - `permission`: npm could not write its global folder; {@link
+ *   BridgeUpdateFailure.command} is the command to run by hand.
+ * - `install`: npm failed for another reason (offline, registry, disk).
+ */
+export type BridgeUpdateFailureReason = 'busy' | 'unsupported' | 'permission' | 'install';
+export interface BridgeUpdateFailure {
+    reason: BridgeUpdateFailureReason;
+    /** What went wrong, for a person (npm's last lines for `install`). */
+    message: string;
+    /** The command that does the update by hand, when that is the way out. */
+    command?: string;
+}
+/**
+ * The bridge's own update, owned by the bridge: it checks the npm registry
+ * itself (hourly while it runs), installs the published version and restarts on
+ * it (`bridge/update`), and tells every client with `stream/bridge/updated`.
+ */
+export interface BridgeUpdate {
+    /** The version running now. */
+    version: string;
+    /** The newest version published under npm's `latest` dist-tag, once known. */
+    latestVersion?: string;
+    /** {@link latestVersion} is strictly newer than {@link version}. */
+    available: boolean;
+    /**
+     * This bridge can install the published version and restart on it by
+     * itself: it runs as the user's service from a global npm install, with npm
+     * beside it. False for a bridge started in a terminal or run from a source
+     * checkout — {@link unsupportedReason} says which.
+     */
+    canApply: boolean;
+    unsupportedReason?: string;
+    phase: BridgeUpdatePhase;
+    /** The version being installed while {@link phase} is `updating`. */
+    targetVersion?: string;
+    /** Why the last attempt failed, while {@link phase} is `failed`. */
+    failure?: BridgeUpdateFailure;
+}
 /**
  * What started the bridge: its own user service (`service` — the normal case,
  * it outlives Uxnan Desktop), Uxnan Desktop directly (`desktop`), or a person

package/package.json

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