@uxnan/shared 0.0.17-alpha.20260926 → 0.0.18-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/72_methods_%7C_16_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/81_methods_%7C_21_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** + **22 streaming
+> **Status:** implemented and stable — **81 JSON-RPC methods** + **21 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

@@ -124,7 +124,8 @@ export interface IAgentAdapter {
      * `activeTurnId` is the bridge turn currently in flight on the thread, so the
      * adapter can address the right run (and refuse if it has already moved on).
      * `turnId` is the queued turn the text came from — it does NOT start a run of
-     * its own; it exists so the bridge can mark it `delivered`.
+     * its own: the bridge makes it the turn that carries the rest of this run,
+     * and keeps naming the run by `activeTurnId` in every call to the adapter.
      *
      * Returns **true only when the agent actually took the message**. Return
      * `false` (don't throw) for an ordinary "too late / not applicable" — the

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

@@ -56,7 +56,8 @@ export interface AgentCapabilities {
      * making it wait for the next one — what a CLI does when you type while it
      * works and it picks the message up at the next tool boundary. The bridge
      * hands such a turn straight to the adapter (`IAgentAdapter.steerTurn`)
-     * rather than holding it, and marks it `delivered` (see `TurnStatus`).
+     * rather than holding it; the turn that was answering ends there and the new
+     * one carries the rest of the agent's run (architecture/02a §5.8.13).
      *
      * Optional; absent/false means the agent has no input channel mid-turn (a
      * one-shot CLI, or a protocol that serializes prompts per session), and its

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

@@ -169,17 +169,6 @@ export interface TurnSendResult {
     queued?: boolean;
     /** 1-based place in the queue when `queued` is true (1 = runs next). */
     queuePosition?: number;
-    /**
-     * True when the agent took the message **into the turn already running**
-     * rather than making it wait (status `delivered`, see `TurnStatus`). It will
-     * never run as a turn of its own — the reply belongs to the turn it joined —
-     * so the client renders the user's message in place and stops offering to
-     * edit or cancel it. Mutually exclusive with {@link queued}.
-     *
-     * Only ever true when the agent advertises `AgentCapabilities.steering`; on
-     * every other agent a follow-up still comes back `queued`.
-     */
-    delivered?: boolean;
 }
 export interface QueueStateResult {
     /** Queued turn ids in drain order. */

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

@@ -27,11 +27,6 @@ export declare const StreamNotification: {
     readonly TurnAborted: "stream/turn/aborted";
     /** A queued turn was removed before it ever ran (status → `cancelled`). */
     readonly TurnCancelled: "stream/turn/cancelled";
-    /**
-     * A queued turn was handed to the agent **inside the turn already running**
-     * instead of waiting for it (status → `delivered`).
-     */
-    readonly TurnDelivered: "stream/turn/delivered";
     /** The thread's message queue changed (queued, drained, cancelled, paused). */
     readonly QueueUpdated: "stream/queue/updated";
     /** The agent resolved an alias (e.g. `opus`) to a concrete model id for this turn. */
@@ -149,22 +144,6 @@ export interface TurnCancelledParams {
     threadId: string;
     turnId: string;
 }
-/**
- * A queued turn reached the agent **without waiting**: it was folded into the
- * turn that was already running (its status is now `delivered`), the way a CLI
- * picks up what you typed while it worked. It will never run as a turn of its
- * own — the answer is part of `intoTurnId`.
- *
- * The client keeps the user's message where it is and stops offering to edit or
- * cancel it: the agent already has it.
- */
-export interface TurnDeliveredParams {
-    threadId: string;
-    /** The queued turn that was handed over. */
-    turnId: string;
-    /** The running turn it was folded into; its reply covers both messages. */
-    intoTurnId: string;
-}
 /**
  * The thread's message queue changed. Carries the WHOLE state rather than a
  * delta, so it is idempotent: a client that missed one (backgrounded, mid-

package/dist/src/jsonrpc/notifications.js

@@ -10,11 +10,6 @@ export const StreamNotification = {
     TurnAborted: 'stream/turn/aborted',
     /** A queued turn was removed before it ever ran (status → `cancelled`). */
     TurnCancelled: 'stream/turn/cancelled',
-    /**
-     * A queued turn was handed to the agent **inside the turn already running**
-     * instead of waiting for it (status → `delivered`).
-     */
-    TurnDelivered: 'stream/turn/delivered',
     /** The thread's message queue changed (queued, drained, cancelled, paused). */
     QueueUpdated: 'stream/queue/updated',
     /** The agent resolved an alias (e.g. `opus`) to a concrete model id for this turn. */

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;;;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"}
+{"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"}

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

@@ -86,7 +86,8 @@ export interface LocalControlMessageFrame {
 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. */
+    /** Stable name of the client (e.g. `desktop-3f9a1c2b7d4e`, `cli`); one live
+     *  connection per name. */
     client: string;
     /** Last notification `seq` the client applied (0 or absent on a fresh start). */
     resume?: number;
@@ -95,6 +96,17 @@ export interface LocalControlConnectParams {
 }
 /** Whether `id` is an acceptable local client name (lowercase, short, no separators). */
 export declare function isValidLocalClientId(id: string): boolean;
+/**
+ * The name Uxnan Desktop's client ids start with. Each desktop **profile** — the
+ * installed app, a development build, a disposable `UXNAN_DATA_DIR` — connects
+ * under its own `desktop-<profile>` id, because the channel keeps one live
+ * connection per name: two desktops sharing one would supersede each other in
+ * an endless reconnect loop and trade the same outbound log, presence and
+ * tools back and forth (architecture/02a §5.8.15).
+ */
+export declare const DESKTOP_LOCAL_CLIENT = "desktop";
+/** Whether a local client id is Uxnan Desktop's (`desktop` or `desktop-<profile>`). */
+export declare function isDesktopClientId(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.

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

@@ -36,6 +36,20 @@ const CLIENT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
 export function isValidLocalClientId(id) {
     return CLIENT_ID_PATTERN.test(id);
 }
+/**
+ * The name Uxnan Desktop's client ids start with. Each desktop **profile** — the
+ * installed app, a development build, a disposable `UXNAN_DATA_DIR` — connects
+ * under its own `desktop-<profile>` id, because the channel keeps one live
+ * connection per name: two desktops sharing one would supersede each other in
+ * an endless reconnect loop and trade the same outbound log, presence and
+ * tools back and forth (architecture/02a §5.8.15).
+ */
+export const DESKTOP_LOCAL_CLIENT = 'desktop';
+/** Whether a local client id is Uxnan Desktop's (`desktop` or `desktop-<profile>`). */
+export function isDesktopClientId(id) {
+    return (isValidLocalClientId(id) &&
+        (id === DESKTOP_LOCAL_CLIENT || id.startsWith(`${DESKTOP_LOCAL_CLIENT}-`)));
+}
 /**
  * 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.

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

@@ -1 +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"}
+{"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;AAsE9D,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;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,uFAAuF;AACvF,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,OAAO,CACL,oBAAoB,CAAC,EAAE,CAAC;QACxB,CAAC,EAAE,KAAK,oBAAoB,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,oBAAoB,GAAG,CAAC,CAAC,CAC3E,CAAC;AACJ,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/session.d.ts

@@ -133,8 +133,10 @@ export interface BridgeFeatures {
     messageQueue?: boolean;
     /**
      * The bridge can hand a queued turn to the agent **inside the turn already
-     * running**, for agents whose CLI has an input channel mid-turn — it marks
-     * that turn `delivered` and emits `stream/turn/delivered`. Absent/false → the
+     * running**, for agents whose CLI has an input channel mid-turn — the running
+     * turn completes and the handed-over one starts at once, carrying the rest of
+     * the agent's run (`stream/turn/completed` then `stream/turn/started`, as a
+     * queue that drained early). Absent/false → the
      * client must expect every follow-up to wait for the current turn to end, and
      * must not promise otherwise in its UI.
      *

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

@@ -17,14 +17,13 @@ export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
  *   thread (never deleted) so the user's message stays visible with a "cancelled"
  *   mark instead of silently vanishing; distinct from `aborted` precisely so a
  *   client can tell "never ran" from "interrupted".
- * - `delivered` — it was QUEUED and the agent took it **into the turn already
- *   running** (see `AgentCapabilities.steering`), so it will never run as a turn
- *   of its own: the answer is part of the turn it was folded into
- *   (`deliveredIntoTurnId`). Terminal and successful — distinct from `cancelled`
- *   precisely because the message DID reach the agent; the user's bubble stays,
- *   with no assistant reply hanging off it.
+ *
+ * A queued turn the agent takes **into the turn already running** (see
+ * `AgentCapabilities.steering`) goes straight to `streaming`: the running turn
+ * completes there and this one carries the rest of the agent's run, so what the
+ * agent says after taking the message is shown under it.
  */
-export type TurnStatus = 'queued' | 'pending' | 'streaming' | 'completed' | 'error' | 'aborted' | 'cancelled' | 'delivered';
+export type TurnStatus = 'queued' | 'pending' | 'streaming' | 'completed' | 'error' | 'aborted' | 'cancelled';
 export type ThreadStatus = 'active' | 'idle' | 'archived';
 /**
  * Why a thread's message queue is held instead of draining:
@@ -81,12 +80,6 @@ export interface Turn {
     messages: Message[];
     createdAt: number;
     completedAt?: number;
-    /**
-     * For a `delivered` turn: the id of the turn its message was folded into.
-     * The reply lives there, so a client renders this turn's user message in
-     * place and expects no assistant message of its own. Absent otherwise.
-     */
-    deliveredIntoTurnId?: string;
 }
 /**
  * Per-thread access (approval) mode: how much the agent may do before it must

package/package.json

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