@uxnan/shared 0.0.6-alpha.20260716 → 0.0.8-alpha.20260720

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/60_methods_%7C_8_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/66_methods_%7C_8_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
@@ -90,8 +90,9 @@ and [`src/jsonrpc/notifications.ts`](src/jsonrpc/notifications.ts)
 §1.2 / §1.4. Per `AGENTS.md` → *Spec drift control*, any change here MUST be
 reflected in the spec in the same change set.
 
-## Publish (planned)
+## Published
 
-`@uxnan/shared` is published to npm **first**; `uxnan-bridge` and `uxnan-relay`
-then pin `"@uxnan/shared": "^0.x"` instead of the `"*"` workspace spec they
-use today. See `bridge/FOR-DEV.md` → *Packaging*.
+`@uxnan/shared` is published to npm; `uxnan-bridge` and `uxnan-relay`
+then pin `"@uxnan/shared": "^0.x"` — the release workflow replaces the
+`"*"` workspace spec with the exact published version at build time.
+See `bridge/FOR-DEV.md` → *Packaging*.

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

@@ -3,7 +3,9 @@
  *
  * Source: architecture/02a-system-architecture.md §5.8.2 (adapters).
  */
-export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli' | 'pi-agent'
+export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli'
+/** Antigravity — Google's `agy` CLI, the successor to the deprecated Gemini CLI. */
+ | 'antigravity-cli' | 'pi-agent'
 /** Zero — open-source Go coding agent, driven over the Agent Client Protocol. */
  | 'zero'
 /** Grok — xAI's coding CLI, driven over the Agent Client Protocol (`grok agent stdio`). */

package/dist/src/constants.d.ts

@@ -6,8 +6,29 @@
  *
  * Source: architecture/02a-system-architecture.md §5.9.1.
  */
-/** Secure transport protocol version negotiated in the handshake. */
-export declare const SECURE_PROTOCOL_VERSION = 1;
+/**
+ * Secure transport protocol version negotiated in the handshake. Both sides
+ * reject a mismatch during `clientHello`/`serverHello`, so an incompatible pair
+ * fails fast and legibly instead of completing the handshake and then dropping
+ * every encrypted frame.
+ *
+ * **Bump this whenever the encrypted-frame format changes** (envelope shape,
+ * AAD layout, key derivation) — not just when the handshake JSON changes. The
+ * handshake is the only place the two sides can still talk, so it is the only
+ * place a version gap can be reported.
+ *
+ * - `1` — initial: AES-256-GCM over the envelope's ciphertext only.
+ * - `2` — `sessionId`/`seq`/direction bound as GCM AAD (`buildEnvelopeAad`).
+ */
+export declare const SECURE_PROTOCOL_VERSION = 2;
+/**
+ * AAD direction bytes for {@link SECURE_PROTOCOL_VERSION} ≥ 2. The session key
+ * is shared by both directions, so the direction is bound into the AAD to stop
+ * a frame being reflected back at its own sender as apparently-inbound traffic.
+ * Mirrored in the mobile `ProtocolConstants`.
+ */
+export declare const ENVELOPE_DIRECTION_PHONE_TO_BRIDGE = 1;
+export declare const ENVELOPE_DIRECTION_BRIDGE_TO_PHONE = 2;
 /** Version stamped into the pairing QR payload. */
 export declare const PAIRING_QR_VERSION = 2;
 /** HKDF `info` tag used when deriving the session key. */

package/dist/src/constants.js

@@ -6,8 +6,29 @@
  *
  * Source: architecture/02a-system-architecture.md §5.9.1.
  */
-/** Secure transport protocol version negotiated in the handshake. */
-export const SECURE_PROTOCOL_VERSION = 1;
+/**
+ * Secure transport protocol version negotiated in the handshake. Both sides
+ * reject a mismatch during `clientHello`/`serverHello`, so an incompatible pair
+ * fails fast and legibly instead of completing the handshake and then dropping
+ * every encrypted frame.
+ *
+ * **Bump this whenever the encrypted-frame format changes** (envelope shape,
+ * AAD layout, key derivation) — not just when the handshake JSON changes. The
+ * handshake is the only place the two sides can still talk, so it is the only
+ * place a version gap can be reported.
+ *
+ * - `1` — initial: AES-256-GCM over the envelope's ciphertext only.
+ * - `2` — `sessionId`/`seq`/direction bound as GCM AAD (`buildEnvelopeAad`).
+ */
+export const SECURE_PROTOCOL_VERSION = 2;
+/**
+ * AAD direction bytes for {@link SECURE_PROTOCOL_VERSION} ≥ 2. The session key
+ * is shared by both directions, so the direction is bound into the AAD to stop
+ * a frame being reflected back at its own sender as apparently-inbound traffic.
+ * Mirrored in the mobile `ProtocolConstants`.
+ */
+export const ENVELOPE_DIRECTION_PHONE_TO_BRIDGE = 0x01;
+export const ENVELOPE_DIRECTION_BRIDGE_TO_PHONE = 0x02;
 /** Version stamped into the pairing QR payload. */
 export const PAIRING_QR_VERSION = 2;
 /** HKDF `info` tag used when deriving the session key. */

package/dist/src/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,mDAAmD;AACnD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C,mEAAmE;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C,gEAAgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD,uEAAuE;AACvE,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEpD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AAExD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,wCAAwC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC;AACvD,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC;AAEvD,mDAAmD;AACnD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C,mEAAmE;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C,gEAAgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD,uEAAuE;AACvE,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEpD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AAExD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,wCAAwC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC"}

package/dist/src/e2ee/envelope.d.ts

@@ -5,8 +5,24 @@
  */
 export interface SecureEnvelope {
     kind: 'encryptedEnvelope';
+    /**
+     * Session this envelope belongs to. Travels in the clear (the receiver needs
+     * it before it can look up a key) and is therefore bound as GCM AAD — see
+     * {@link seq}.
+     */
     sessionId: string;
-    /** Monotonic sequence number (replay protection). */
+    /**
+     * Monotonic sequence number (replay protection). Like `sessionId` it is
+     * visible on the wire, so from `SECURE_PROTOCOL_VERSION` 2 both are bound —
+     * together with a direction byte — as the AES-GCM **AAD**:
+     *
+     *   AAD = utf8(sessionId) || 0x00 || u64_be(seq) || 0x00 || direction
+     *
+     * so tampering with either field fails the tag instead of silently passing an
+     * unauthenticated `seq <= lastApplied` check. Both implementations must build
+     * this byte-for-byte identically (`buildEnvelopeAad` on each side); see
+     * architecture/02a §5.9.1.
+     */
     seq: number;
     /** Per-message random nonce (hex, 12 bytes). */
     nonce: string;

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

@@ -45,6 +45,18 @@ export interface ContentBlockParams {
     turnId: string;
     messageId: string;
     content: unknown;
+    /**
+     * `true` when the block arrived from a **parallel/background** activity (e.g.
+     * a Claude Code subagent's tool run) while the assistant's main text was
+     * still streaming. The client must then insert the block BEFORE the
+     * currently-open text run instead of appending it after — appending would
+     * sever the run and render the sentence split mid-word by an activity card.
+     * Absent/false for the sequential case (the block lands at a real text-run
+     * boundary and is appended in arrival order). Mirrors how the bridge itself
+     * orders the block inside the persisted `Message.segments`, so the live view
+     * and a later `turn/list` re-sync render the identical interleave.
+     */
+    beforeText?: boolean;
 }
 /**
  * Token usage for a completed turn, as reported by the agent's CLI.

package/package.json

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