@uxnan/shared 0.0.15-alpha.20260813 → 0.0.17-alpha.20260926

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

@@ -1,9 +1,20 @@
 /**
- * Bridge → phone streaming notifications (JSON-RPC notifications, no `id`).
+ * Bridge → client streaming notifications (JSON-RPC notifications, no `id`).
+ *
+ * Every notification is broadcast to **every** connected client — each paired
+ * phone and the desktop on the local control channel — so any of them can
+ * drive a thread and all of them converge on the same state (architecture/02a
+ * §5.8.16). A client must therefore expect notifications about threads and
+ * turns it did not start itself.
  *
  * Source: architecture/02b-contracts-and-requirements.md (streaming events).
  */
-import type { QueuePausedReason, ThreadTitleSource } from '../models/thread.js';
+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 { AgentDescriptor } from '../agents/agent-capabilities.js';
 export declare const StreamNotification: {
     readonly TurnStarted: "stream/turn/started";
     readonly MessageDelta: "stream/message/delta";
@@ -25,8 +36,36 @@ export declare const StreamNotification: {
     readonly QueueUpdated: "stream/queue/updated";
     /** The agent resolved an alias (e.g. `opus`) to a concrete model id for this turn. */
     readonly ModelResolved: "stream/model/resolved";
-    /** A thread's title changed on the bridge (a generated title, or another device's rename). */
-    readonly ThreadRenamed: "stream/thread/renamed";
+    /**
+     * A thread was created or its stored metadata changed (title, model, access
+     * mode, archive state) — by any client or by the bridge itself (a generated
+     * title). Carries the whole {@link Thread}, so it is idempotent.
+     */
+    readonly ThreadUpdated: "stream/thread/updated";
+    /** A thread was deleted. */
+    readonly ThreadDeleted: "stream/thread/deleted";
+    /**
+     * A user turn was stored (started or queued), carrying the user's message —
+     * so a client sees a message another client sent, in order, before the
+     * agent's answer to it starts streaming.
+     */
+    readonly TurnCreated: "stream/turn/created";
+    /** A pending approval was answered (on any client) or timed out. */
+    readonly ApprovalResolved: "stream/approval/resolved";
+    /** A pending question was answered (on any client), skipped or timed out. */
+    readonly QuestionResolved: "stream/question/resolved";
+    /** A project was registered or its entry changed. */
+    readonly ProjectUpdated: "stream/project/updated";
+    /** A project was removed from the registry (its conversations stay). */
+    readonly ProjectRemoved: "stream/project/removed";
+    /** The shared settings changed (`settings/set`, or the bridge's CLI). */
+    readonly SettingsUpdated: "stream/settings/updated";
+    /** A client connected or disconnected. */
+    readonly PresenceUpdated: "stream/presence/updated";
+    /** A phone was paired, named, described or removed. */
+    readonly DevicesUpdated: "stream/devices/updated";
+    /** An agent became available or unavailable (installed, removed). */
+    readonly AgentsUpdated: "stream/agents/updated";
 };
 export type StreamNotification = (typeof StreamNotification)[keyof typeof StreamNotification];
 export interface TurnStartedParams {
@@ -150,17 +189,100 @@ export interface ModelResolvedParams {
     model: string;
 }
 /**
- * A thread's title changed **on the bridge**, so every client converges without
- * refetching the list. Emitted when a generated title replaces the provisional
- * one taken from the opening message, and when another device renames a thread.
+ * A thread was created or its stored metadata changed, on the bridge. Emitted
+ * by `thread/start`, `thread/fork`, `thread/rename`, `thread/setModel`,
+ * `thread/setAccessMode`, `thread/archive`, `thread/unarchive`, and when a
+ * generated title replaces the provisional one. The whole thread travels, so a
+ * client upserts it and converges without refetching the list — including on
+ * a thread another client just started.
  *
- * `titleSource` says how much to trust it: `user` is final, `agent` is the
- * generated name, `prompt` the weak fallback. A client MUST NOT let an `agent`
- * title overwrite a `user` one — the bridge already enforces that, and this
- * field is what lets a client reason about it too.
+ * `thread.titleSource` says how much to trust the title: `user` is final,
+ * `agent` is the generated name, `prompt` the weak fallback. The bridge never
+ * lets an `agent` title overwrite a `user` one; the field lets a client reason
+ * about it too.
  */
-export interface ThreadRenamedParams {
+export interface ThreadUpdatedParams {
+    thread: Thread;
+}
+/** A thread was deleted on the bridge (by any client). */
+export interface ThreadDeletedParams {
     threadId: string;
-    title: string;
-    titleSource: ThreadTitleSource;
+    /** Sync revision of the deletion (see `SyncChanges`). */
+    rev?: number;
+}
+/**
+ * A project was registered or changed. Like `stream/thread/updated`, the whole
+ * entry travels (idempotent upsert) and `project.rev` is its sync revision: a
+ * client that sees a revision that is not the one after its last runs
+ * `sync/changes`.
+ */
+export interface ProjectUpdatedParams {
+    project: Project;
+}
+/** A project left the registry. Its conversations are untouched. */
+export interface ProjectRemovedParams {
+    projectId: string;
+    rev: number;
+}
+export interface SettingsUpdatedParams {
+    settings: BridgeSettings;
+    rev: number;
+}
+/** The whole list of connected clients (idempotent; not revisioned). */
+export interface PresenceUpdatedParams {
+    clients: ClientPresence[];
+}
+/** Every paired phone, as it stands now (idempotent; not revisioned). */
+export interface DevicesUpdatedParams {
+    devices: TrustedDevice[];
+}
+/** The whole agent list, as `agent/list` would answer now. */
+export interface AgentsUpdatedParams {
+    agents: AgentDescriptor[];
+}
+/**
+ * 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
+ * message (and the assistant's still-empty placeholder), so every client can
+ * place the prompt in the timeline **before** the answer streams — including
+ * a prompt typed on another client.
+ *
+ * `clientTurnId` echoes `TurnSendParams.clientTurnId` from the client that sent
+ * it, so that client can match the notification to the optimistic bubble it
+ * already shows instead of drawing the message twice. It may arrive before the
+ * `turn/send` reply does.
+ */
+export interface TurnCreatedParams {
+    threadId: string;
+    turn: Turn;
+    clientTurnId?: string;
+}
+/**
+ * A pending approval is no longer pending. `decision` is what the agent got:
+ * the answer a client sent, or `reject` when it timed out (`timedOut: true`).
+ * Every client retires its card for `approvalId` — the one that answered and
+ * any other showing the same request.
+ */
+export interface ApprovalResolvedParams {
+    threadId: string;
+    approvalId: string;
+    decision: ApprovalDecision;
+    timedOut?: boolean;
+}
+/**
+ * A pending question is no longer pending: answered on some client, skipped
+ * (empty answers), or timed out (`timedOut: true`). Every client retires its
+ * card for `questionId`.
+ */
+export interface QuestionResolvedParams {
+    threadId: string;
+    questionId: string;
+    /** True when no option was chosen (skipped, or timed out). */
+    skipped: boolean;
+    /**
+     * The chosen option labels, one list per question in order — what the agent
+     * received — so a client that did not answer can still show the choice.
+     */
+    answers: string[][];
+    timedOut?: boolean;
 }

package/dist/src/jsonrpc/notifications.js

@@ -19,7 +19,35 @@ export const StreamNotification = {
     QueueUpdated: 'stream/queue/updated',
     /** The agent resolved an alias (e.g. `opus`) to a concrete model id for this turn. */
     ModelResolved: 'stream/model/resolved',
-    /** A thread's title changed on the bridge (a generated title, or another device's rename). */
-    ThreadRenamed: 'stream/thread/renamed',
+    /**
+     * A thread was created or its stored metadata changed (title, model, access
+     * mode, archive state) — by any client or by the bridge itself (a generated
+     * title). Carries the whole {@link Thread}, so it is idempotent.
+     */
+    ThreadUpdated: 'stream/thread/updated',
+    /** A thread was deleted. */
+    ThreadDeleted: 'stream/thread/deleted',
+    /**
+     * A user turn was stored (started or queued), carrying the user's message —
+     * so a client sees a message another client sent, in order, before the
+     * agent's answer to it starts streaming.
+     */
+    TurnCreated: 'stream/turn/created',
+    /** A pending approval was answered (on any client) or timed out. */
+    ApprovalResolved: 'stream/approval/resolved',
+    /** A pending question was answered (on any client), skipped or timed out. */
+    QuestionResolved: 'stream/question/resolved',
+    /** A project was registered or its entry changed. */
+    ProjectUpdated: 'stream/project/updated',
+    /** A project was removed from the registry (its conversations stay). */
+    ProjectRemoved: 'stream/project/removed',
+    /** The shared settings changed (`settings/set`, or the bridge's CLI). */
+    SettingsUpdated: 'stream/settings/updated',
+    /** A client connected or disconnected. */
+    PresenceUpdated: 'stream/presence/updated',
+    /** A phone was paired, named, described or removed. */
+    DevicesUpdated: 'stream/devices/updated',
+    /** An agent became available or unavailable (installed, removed). */
+    AgentsUpdated: 'stream/agents/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":"AAOA,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;;;OAGG;IACH,aAAa,EAAE,uBAAuB;IACtC,+EAA+E;IAC/E,YAAY,EAAE,sBAAsB;IACpC,sFAAsF;IACtF,aAAa,EAAE,uBAAuB;IACtC,8FAA8F;IAC9F,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;;;OAGG;IACH,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"}

package/dist/src/local-control/local-control.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Local control channel: how a client on the **same machine** as the bridge
+ * (Uxnan Desktop) talks to it without the E2EE pairing a phone needs.
+ *
+ * The bridge listens on loopback only, authorizes a connection with a token it
+ * writes to a file only the current user can read, and serves exactly the same
+ * JSON-RPC router the phones use. The client is registered as one more
+ * receiver of the bridge's `stream/*` notifications, with its own `seq`, so it
+ * sees every turn any client starts and is caught up after a reconnect the same
+ * way a phone is.
+ *
+ * The trust model is the one `POST /agent-hook/approval` already uses: a local
+ * route guarded by a token that only processes of the same user can read. The
+ * E2EE protocol is untouched — this is not a cryptographic variant, it is a
+ * loopback route.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.15 (local control channel).
+ */
+/** Wire protocol revision of the local control channel. */
+export declare const LOCAL_CONTROL_PROTOCOL = 1;
+/**
+ * File (under the bridge's state directory, `~/.uxnan/`) where a running bridge
+ * publishes how to reach its local control channel. Written with owner-only
+ * permissions when the listener starts, removed when it stops.
+ */
+export declare const LOCAL_CONTROL_FILE = "local-control.json";
+/** HTTP path of the WebSocket upgrade. */
+export declare const LOCAL_CONTROL_PATH = "/control";
+/**
+ * Largest single frame (either direction) the channel accepts. Generous because
+ * a `turn/send` may inline image attachments as base64.
+ */
+export declare const LOCAL_CONTROL_MAX_FRAME_BYTES: number;
+/** Contents of {@link LOCAL_CONTROL_FILE}. */
+export interface LocalControlDiscovery {
+    protocol: number;
+    /** Loopback port the listener is bound to (always `127.0.0.1`). */
+    port: number;
+    /**
+     * Bearer token for the WebSocket upgrade (`Authorization: Bearer <token>`).
+     * A fresh one is generated every time the listener starts, so a stale file
+     * from a previous run cannot authorize anything.
+     */
+    token: string;
+    /** Process id of the bridge serving it. */
+    pid: number;
+    /** Bridge package version. */
+    bridgeVersion: string;
+    /**
+     * Identifies this run of the bridge. A client that reconnects to a
+     * *different* instance must resync instead of expecting a replay.
+     */
+    instanceId: string;
+}
+/**
+ * First frame the bridge sends on a new connection, before any replay.
+ *
+ * `gap` is the important bit: when true the bridge could NOT replay everything
+ * the client missed (the retained window was exceeded, or the bridge restarted
+ * since the client's last `seq`), so the client must resync what it has open
+ * (`thread/list`, `turn/list`) instead of trusting its local state.
+ */
+export interface LocalControlHelloFrame {
+    type: 'hello';
+    protocol: number;
+    bridgeVersion: string;
+    instanceId: string;
+    /** The client id the connection was registered under. */
+    clientId: string;
+    /** How many retained notifications follow this frame as a replay. */
+    replayed: number;
+    /** True when some notifications the client missed are unrecoverable. */
+    gap: boolean;
+}
+/**
+ * Every other frame: a JSON-RPC response to a request the client sent, or a
+ * notification. Notifications carry the `seq` the client must persist and send
+ * back as `resume` on its next connection; responses carry none (a request
+ * pending across a disconnect is failed by the client, not replayed).
+ */
+export interface LocalControlMessageFrame {
+    type: 'message';
+    seq?: number;
+    message: unknown;
+}
+export type LocalControlFrame = LocalControlHelloFrame | LocalControlMessageFrame;
+/** Query parameters of the upgrade URL: `/control?client=<id>&resume=<seq>&instance=<id>`. */
+export interface LocalControlConnectParams {
+    /** Stable name of the client (e.g. `desktop`); one live connection per name. */
+    client: string;
+    /** Last notification `seq` the client applied (0 or absent on a fresh start). */
+    resume?: number;
+    /** `instanceId` of the bridge the client last talked to. */
+    instance?: string;
+}
+/** Whether `id` is an acceptable local client name (lowercase, short, no separators). */
+export declare function isValidLocalClientId(id: string): boolean;
+/**
+ * The receiver id a local client is registered under in the bridge's session
+ * registry. Prefixed so it can never collide with a paired phone's device id.
+ */
+export declare function localReceiverId(clientId: string): string;
+/**
+ * `desktop/attach` params — sent by Uxnan Desktop over the local control
+ * channel (and accepted **only** there) to give the agents the bridge runs the
+ * desktop's own tools: its MCP server (browser, terminals, other agents, the
+ * control catalog), the same server the desktop hands the agents it launches in
+ * its terminals (architecture/02a §5.8.15).
+ */
+export interface DesktopAttachParams {
+    /** The desktop's MCP endpoint — a loopback `http://127.0.0.1:<port>/mcp`. */
+    mcpUrl: string;
+    /** Bearer token for bridge-run agents, minted by the desktop per start. The
+     *  bridge hands it to an agent only through the environment, never argv or a
+     *  file, and forgets it when the desktop disconnects. */
+    token: string;
+}
+/** `desktop/attach` / `desktop/detach` result: whether tools are attached now. */
+export interface DesktopAttachResult {
+    attached: boolean;
+}
+/** The header a bridge-run agent's MCP requests carry: the conversation's
+ *  working directory, which scopes what the desktop lets it touch to the
+ *  project that folder belongs to. */
+export declare const DESKTOP_CWD_HEADER = "x-uxnan-cwd";
+/** The `x-uxnan-cwd` value for a folder: percent-encoded, so a path with
+ *  non-ASCII characters (`…/Año`) survives as an HTTP header; the desktop
+ *  decodes it. */
+export declare function encodeCwdHeader(cwd: string): string;
+/** The MCP server name bridge-run agents see the desktop's tools under — the
+ *  same one the desktop's terminal agents see, so every agent-facing guide
+ *  applies unchanged. */
+export declare const DESKTOP_MCP_SERVER_NAME = "uxnan-browser";
+/** Whether `url` is a loopback MCP endpoint the bridge will hand to an agent. */
+export declare function isLoopbackMcpUrl(url: string): boolean;
+/** Whether `token` has the shape of a desktop-minted token (base64url-ish). */
+export declare function isDesktopToken(token: string): boolean;

package/dist/src/local-control/local-control.js

@@ -0,0 +1,68 @@
+/**
+ * Local control channel: how a client on the **same machine** as the bridge
+ * (Uxnan Desktop) talks to it without the E2EE pairing a phone needs.
+ *
+ * The bridge listens on loopback only, authorizes a connection with a token it
+ * writes to a file only the current user can read, and serves exactly the same
+ * JSON-RPC router the phones use. The client is registered as one more
+ * receiver of the bridge's `stream/*` notifications, with its own `seq`, so it
+ * sees every turn any client starts and is caught up after a reconnect the same
+ * way a phone is.
+ *
+ * The trust model is the one `POST /agent-hook/approval` already uses: a local
+ * route guarded by a token that only processes of the same user can read. The
+ * E2EE protocol is untouched — this is not a cryptographic variant, it is a
+ * loopback route.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.15 (local control channel).
+ */
+/** Wire protocol revision of the local control channel. */
+export const LOCAL_CONTROL_PROTOCOL = 1;
+/**
+ * File (under the bridge's state directory, `~/.uxnan/`) where a running bridge
+ * publishes how to reach its local control channel. Written with owner-only
+ * permissions when the listener starts, removed when it stops.
+ */
+export const LOCAL_CONTROL_FILE = 'local-control.json';
+/** HTTP path of the WebSocket upgrade. */
+export const LOCAL_CONTROL_PATH = '/control';
+/**
+ * Largest single frame (either direction) the channel accepts. Generous because
+ * a `turn/send` may inline image attachments as base64.
+ */
+export const LOCAL_CONTROL_MAX_FRAME_BYTES = 32 * 1024 * 1024;
+const CLIENT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** Whether `id` is an acceptable local client name (lowercase, short, no separators). */
+export function isValidLocalClientId(id) {
+    return CLIENT_ID_PATTERN.test(id);
+}
+/**
+ * The receiver id a local client is registered under in the bridge's session
+ * registry. Prefixed so it can never collide with a paired phone's device id.
+ */
+export function localReceiverId(clientId) {
+    return `local:${clientId}`;
+}
+/** The header a bridge-run agent's MCP requests carry: the conversation's
+ *  working directory, which scopes what the desktop lets it touch to the
+ *  project that folder belongs to. */
+export const DESKTOP_CWD_HEADER = 'x-uxnan-cwd';
+/** The `x-uxnan-cwd` value for a folder: percent-encoded, so a path with
+ *  non-ASCII characters (`…/Año`) survives as an HTTP header; the desktop
+ *  decodes it. */
+export function encodeCwdHeader(cwd) {
+    return encodeURIComponent(cwd);
+}
+/** The MCP server name bridge-run agents see the desktop's tools under — the
+ *  same one the desktop's terminal agents see, so every agent-facing guide
+ *  applies unchanged. */
+export const DESKTOP_MCP_SERVER_NAME = 'uxnan-browser';
+/** Whether `url` is a loopback MCP endpoint the bridge will hand to an agent. */
+export function isLoopbackMcpUrl(url) {
+    return /^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):\d{1,5}\/mcp$/.test(url);
+}
+/** Whether `token` has the shape of a desktop-minted token (base64url-ish). */
+export function isDesktopToken(token) {
+    return /^[A-Za-z0-9_-]{16,512}$/.test(token);
+}
+//# sourceMappingURL=local-control.js.map

package/dist/src/local-control/local-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-control.js","sourceRoot":"","sources":["../../../src/local-control/local-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD,0CAA0C;AAC1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAqE9D,MAAM,iBAAiB,GAAG,2BAA2B,CAAC;AAEtD,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,SAAS,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAuBD;;sCAEsC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD;;kBAEkB;AAClB,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;yBAEyB;AACzB,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAEvD,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,0DAA0D,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC"}

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

@@ -1,15 +1,54 @@
 /**
  * Project models exchanged over JSON-RPC (project/* methods).
+ *
+ * The bridge keeps ONE persistent registry of projects (architecture/02a
+ * §5.8.17): the phone and Uxnan Desktop are mirrors of it, so a project added
+ * or removed on either appears or disappears on both. Removing a project never
+ * deletes its conversations.
  */
+/**
+ * How a project entered the registry — informational, never a permission:
+ * - `user` — added by hand on a client (`project/add`).
+ * - `desktop` — published by Uxnan Desktop from its own project list.
+ * - `thread` — registered because a conversation started in its folder.
+ * - `config` — listed in the bridge config's `workspaceRoots`.
+ */
+export type ProjectSource = 'user' | 'desktop' | 'thread' | 'config';
 export interface Project {
     id: string;
     name: string;
-    /** Absolute working directory on the PC (never sent verbatim to mobile if sensitive). */
+    /** Absolute, canonical (symlinks resolved) working directory on the PC. */
     cwd: string;
     /** Agent pinned for this project in bridge config (the thread's default agent). */
     agentId?: string;
     /** Model pinned for this project's agent in bridge config, when set. */
     model?: string;
+    /** How it entered the registry. Absent on a project that is not registered
+     *  (a `project/resolve` of a folder nobody added). */
+    source?: ProjectSource;
+    /** When it was registered (epoch ms). */
+    addedAt?: number;
+    /** When its entry last changed (epoch ms). */
+    updatedAt?: number;
+    /** Sync revision of its last change (see `SyncChanges`). */
+    rev?: number;
+}
+export interface ProjectAddParams {
+    /** Folder to register. A worktree registers the repository it belongs to. */
+    cwd: string;
+    /** Display name; defaults to the folder's name. */
+    name?: string;
+}
+export interface ProjectRemoveParams {
+    projectId: string;
+}
+export interface ProjectRemoveResult {
+    removed: boolean;
+}
+export interface ProjectRenameParams {
+    projectId: string;
+    /** New display name; an empty string restores the folder's name. */
+    name: string;
 }
 export interface AuthStatus {
     agentId: string;

package/dist/src/models/project.js

@@ -1,5 +1,10 @@
 /**
  * Project models exchanged over JSON-RPC (project/* methods).
+ *
+ * The bridge keeps ONE persistent registry of projects (architecture/02a
+ * §5.8.17): the phone and Uxnan Desktop are mirrors of it, so a project added
+ * or removed on either appears or disappears on both. Removing a project never
+ * deletes its conversations.
  */
 export {};
 //# sourceMappingURL=project.js.map

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

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

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

@@ -3,6 +3,7 @@
  *
  * Dart equivalents: `uxnanmobile/lib/domain/entities/{secure_session,trusted_device}.dart`.
  */
+import type { ClientPresence } from './sync.js';
 export type HandshakeMode = 'qr_bootstrap' | 'trusted_reconnect';
 export interface ConnectedPhone {
     deviceId: string;
@@ -12,11 +13,59 @@ export interface ConnectedPhone {
 }
 export interface TrustedDevice {
     deviceId: string;
+    /**
+     * The phone's name on every client: what the phone calls itself
+     * (`device/describe`) until someone names it (`device/rename`, on the phone
+     * or on the desktop) — then that name, the same everywhere.
+     */
     displayName: string;
     /** Phone Ed25519 identity public key (hex). */
     publicKey: string;
     pairedAt: number;
     lastSeen?: number;
+    /** Who chose `displayName`: the phone itself, or a person. */
+    nameSource?: 'device' | 'user';
+    /** Maker and model, as the phone reports them (e.g. `samsung SM-A556E`). */
+    model?: string;
+    /** `android` or `ios`. */
+    platform?: string;
+    /** The operating system's version. */
+    osVersion?: string;
+    /** The Uxnan app version the phone runs. */
+    appVersion?: string;
+}
+/**
+ * `device/describe`: a phone, right after connecting, says what it is and what
+ * it is called (architecture/02a §5.8.17). Only a phone may call it, and only
+ * about itself.
+ */
+export interface DeviceDescribeParams {
+    /** Its name: the one the user gave it, or its own default (the model). */
+    name: string;
+    /**
+     * How long ago the user chose [name] (`ActionAgeMs`); absent while the name
+     * is the phone's default. The bridge keeps the latest decision — this one,
+     * or a rename made on another client since.
+     */
+    nameAgeMs?: number;
+    model?: string;
+    platform?: string;
+    osVersion?: string;
+    appVersion?: string;
+}
+/** The phone's record as it stands, and how long ago its name was decided. */
+export interface DeviceDescription {
+    device: TrustedDevice;
+    /** Absent while the name is the phone's default (never decided by a person). */
+    nameAgeMs?: number;
+}
+/** `device/rename`: name a paired phone, from any client. */
+export interface DeviceRenameParams {
+    deviceId: string;
+    /** The new name; empty goes back to the phone's own name. */
+    name: string;
+    /** See `ActionAgeMs`: a rename made offline and sent now. */
+    ageMs?: number;
 }
 export interface BridgeStatus {
     version: string;
@@ -37,6 +86,13 @@ export interface BridgeStatus {
      * without querying npm itself. Absent/false when unknown or up to date.
      */
     updateAvailable?: boolean;
+    /**
+     * 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
+     * before anything that restarts the bridge (Uxnan Desktop's bridge update),
+     * so no one's running turn is cut.
+     */
+    activeTurns?: number;
     /**
      * Optional capabilities this bridge supports, so a newer client offers a
      * feature only where it actually works instead of inferring it from the
@@ -49,6 +105,21 @@ export interface BridgeStatus {
      * processes on one `--resume`; OpenCode retires the running turn outright).
      */
     features?: BridgeFeatures;
+    /** How this bridge was started and on which machine. Absent on an older bridge. */
+    host?: BridgeHost;
+    /** Who is connected right now. Absent on an older bridge. */
+    clients?: ClientPresence[];
+}
+/**
+ * What started the bridge: its own user service (`service` — the normal case,
+ * it outlives Uxnan Desktop), Uxnan Desktop directly (`desktop`), or a person
+ * in a terminal (`cli`).
+ */
+export type BridgeLaunchedBy = 'service' | 'desktop' | 'cli';
+export interface BridgeHost {
+    launchedBy: BridgeLaunchedBy;
+    /** The machine's name, as a phone shows it ("Linked with Uxnan Desktop on …"). */
+    machineName: string;
 }
 /** Optional, additive bridge capabilities advertised on {@link BridgeStatus}. */
 export interface BridgeFeatures {
@@ -85,4 +156,19 @@ export interface BridgeFeatures {
      * folder names for the same repository and branch.
      */
     managedWorktrees?: boolean;
+    /**
+     * The bridge is serving the loopback **local control channel**
+     * (`LOCAL_CONTROL_FILE`, architecture/02a §5.8.15) right now, so a client on
+     * the same machine can drive it without pairing. Unlike the other flags this
+     * one is live, not build-level: it is absent while the listener is off
+     * (`localControlEnabled: false`, or a short-lived CLI command).
+     */
+    localControl?: boolean;
+    /**
+     * The bridge serves replica sync (`sync/changes`), the persistent project
+     * registry (`project/add|remove|rename`, `stream/project/*`), shared settings
+     * (`settings/*`), presence (`stream/presence/updated`) and orders turns by
+     * `Turn.seq`. Absent/false → a client keeps its older `thread/list` flow.
+     */
+    sync?: boolean;
 }

package/dist/src/models/session.js

@@ -1,7 +1,2 @@
-/**
- * Session and trust models.
- *
- * Dart equivalents: `uxnanmobile/lib/domain/entities/{secure_session,trusted_device}.dart`.
- */
 export {};
 //# sourceMappingURL=session.js.map

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

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