@uxnan/shared 0.0.9-alpha.20260721 → 0.0.11-alpha.20260729

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/66_methods_%7C_8_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/68_methods_%7C_10_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 — **66 JSON-RPC methods** + **8 streaming
+> **Status:** implemented and stable — **68 JSON-RPC methods** + **10 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
@@ -49,7 +49,7 @@ flowchart TB
 
 | Area | Exports |
 |---|---|
-| JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32008`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
+| JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32009`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
 | Streaming | `StreamNotification` enum + param types (`TurnStartedParams`, `MessageDeltaParams`, `ThinkingDeltaParams`, `ContentBlockParams`, `TurnCompletedParams`, `TurnUsage`, `TurnErrorParams`, `TurnAbortedParams`, `ModelResolvedParams`) |
 | E2EE | handshake messages (`clientHello` / `serverHello` / `clientAuth` / `ready`), `buildHandshakeTranscript`, `SecureEnvelope`, `PairingPayload` v2 (`relay` optional + `hosts: string[]`) with `Base64(utf8(JSON))` QR encoding |
 | Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), bridge-owned profile metrics (complete-ledger export/import), approval, question (interactive multiple-choice) |

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

@@ -82,6 +82,31 @@ export interface IAgentAdapter {
     respondApproval?(threadId: string, approvalId: string, decision: ApprovalDecision): Promise<void>;
     /** Subscribe to streaming events. Returns an unsubscribe function. */
     onEvent(listener: (event: AgentStreamEvent) => void): () => void;
+    /**
+     * True when this adapter delivers `SendTurnOptions.attachments` to its CLI
+     * **itself** (a native image input), so the bridge must not materialize them
+     * to files nor append a path note to the prompt.
+     *
+     * Default (unset/false) is the CLI-agnostic path: the bridge writes each
+     * attachment into the agent's working directory and references it, which
+     * works for every agent whose file tools can open an image. An adapter opts
+     * in here when its protocol carries images natively AND its file tools
+     * cannot (Zero: ACP `promptCapabilities.image` accepts an inline image
+     * block, while its `read_file` is line-oriented text only).
+     */
+    handlesAttachments?(): boolean;
+    /**
+     * The directory this adapter runs a turn in when the turn carries no `cwd`
+     * of its own (its configured {@link AgentConfig.cwd}, else the daemon's
+     * process directory). Optional; adapters that cannot report one leave it
+     * unset.
+     *
+     * The bridge needs it to place per-turn files — image attachments in
+     * particular — **inside** the directory the CLI is actually sandboxed to:
+     * every supported agent refuses to open a path outside its workspace, so a
+     * file written anywhere else is unreachable no matter how it is referenced.
+     */
+    defaultCwd?(): string | undefined;
     /** List the models this agent's CLI reports as available (optional). */
     listModels?(): Promise<AgentModel[]>;
     /**

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

@@ -91,8 +91,8 @@ export interface AgentModelOption {
  * A selectable model an agent reports, returned by `agent/models`.
  *
  * `id` is the wire value passed back to the agent for routing — a stable alias
- * for Claude Code (`opus`/`sonnet`/`haiku`), a `provider/model` id for OpenCode,
- * or a concrete model id for Codex. `displayName`, `description`, `version` and
+ * for Claude Code (`fable`/`opus`/`sonnet`/`haiku`), a `provider/model` id for
+ * OpenCode, or a concrete model id for Codex. `displayName`, `description`, `version` and
  * `isDefault` are presentation hints; consumers must tolerate any of them being
  * absent (older bridges report bare id strings).
  */
@@ -105,7 +105,7 @@ export interface AgentModel {
     description?: string;
     /**
      * Concrete underlying version when `id` is an alias that resolves to a
-     * moving target — e.g. Claude Code's `opus` → `claude-opus-4-8`. Surfaced so
+     * moving target — e.g. Claude Code's `opus` → `claude-opus-5`. Surfaced so
      * the user can see which exact model an alias currently maps to.
      */
     version?: string;
@@ -125,11 +125,12 @@ export interface AgentModel {
      */
     contextWindow?: number;
     /**
-     * Marks a moving-target "latest" alias (Claude Code's `opus`/`sonnet`/`haiku`,
-     * each of which always routes to the newest version of that tier the account
-     * can use — see {@link version} for the resolved concrete id). Concrete/pinned
-     * models leave this absent. Presentation-only: lets a client offer to
-     * hide the aliases and show exact versions only, without hardcoding ids.
+     * Marks a moving-target "latest" alias (Claude Code's
+     * `fable`/`opus`/`sonnet`/`haiku`, each of which always routes to the newest
+     * version of that tier the account can use — see {@link version} for the
+     * resolved concrete id). Concrete/pinned models leave this absent.
+     * Presentation-only: lets a client offer to hide the aliases and show exact
+     * versions only, without hardcoding ids.
      */
     isLatestAlias?: boolean;
 }

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

@@ -1,7 +1,7 @@
 /**
  * JSON-RPC 2.0 error codes used across the Uxnan ecosystem.
  *
- * Standard codes (-32700..-32603) plus Uxnan-specific codes (-32000..-32008).
+ * Standard codes (-32700..-32603) plus Uxnan-specific codes (-32000..-32009).
  * Source: architecture/02b-contracts-and-requirements.md.
  */
 export declare const JsonRpcErrorCode: {
@@ -19,6 +19,12 @@ export declare const JsonRpcErrorCode: {
     readonly SessionExpired: -32006;
     readonly ConfirmationRequired: -32007;
     readonly ResourceNotFound: -32008;
+    /**
+     * A turn is already in flight on this thread and the caller asked NOT to
+     * queue behind it (`turn/send` with `queue: false`). Only ever raised on an
+     * explicit opt-out — the default is to queue.
+     */
+    readonly AgentBusy: -32009;
 };
 export type JsonRpcErrorCode = (typeof JsonRpcErrorCode)[keyof typeof JsonRpcErrorCode];
 /** Human-readable default messages for each error code. */

package/dist/src/jsonrpc/errors.js

@@ -1,7 +1,7 @@
 /**
  * JSON-RPC 2.0 error codes used across the Uxnan ecosystem.
  *
- * Standard codes (-32700..-32603) plus Uxnan-specific codes (-32000..-32008).
+ * Standard codes (-32700..-32603) plus Uxnan-specific codes (-32000..-32009).
  * Source: architecture/02b-contracts-and-requirements.md.
  */
 export const JsonRpcErrorCode = {
@@ -21,6 +21,12 @@ export const JsonRpcErrorCode = {
     SessionExpired: -32006,
     ConfirmationRequired: -32007,
     ResourceNotFound: -32008,
+    /**
+     * A turn is already in flight on this thread and the caller asked NOT to
+     * queue behind it (`turn/send` with `queue: false`). Only ever raised on an
+     * explicit opt-out — the default is to queue.
+     */
+    AgentBusy: -32009,
 };
 /** Human-readable default messages for each error code. */
 export const JSON_RPC_ERROR_MESSAGES = {
@@ -38,6 +44,7 @@ export const JSON_RPC_ERROR_MESSAGES = {
     [JsonRpcErrorCode.SessionExpired]: 'Session expired',
     [JsonRpcErrorCode.ConfirmationRequired]: 'Confirmation required',
     [JsonRpcErrorCode.ResourceNotFound]: 'Resource not found',
+    [JsonRpcErrorCode.AgentBusy]: 'Agent busy',
 };
 /**
  * Error carrying a JSON-RPC error code, so handlers can throw a typed error

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

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/jsonrpc/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/jsonrpc/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,wBAAwB;IACxB,UAAU,EAAE,CAAC,KAAK;IAClB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;IACtB,aAAa,EAAE,CAAC,KAAK;IACrB,aAAa,EAAE,CAAC,KAAK;IACrB,iBAAiB;IACjB,WAAW,EAAE,CAAC,KAAK;IACnB,sBAAsB,EAAE,CAAC,KAAK;IAC9B,eAAe,EAAE,CAAC,KAAK;IACvB,kBAAkB,EAAE,CAAC,KAAK;IAC1B,qBAAqB,EAAE,CAAC,KAAK;IAC7B,yBAAyB,EAAE,CAAC,KAAK;IACjC,cAAc,EAAE,CAAC,KAAK;IACtB,oBAAoB,EAAE,CAAC,KAAK;IAC5B,gBAAgB,EAAE,CAAC,KAAK;IACxB;;;;OAIG;IACH,SAAS,EAAE,CAAC,KAAK;CACT,CAAC;AAIX,2DAA2D;AAC3D,MAAM,CAAC,MAAM,uBAAuB,GAAqC;IACvE,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,aAAa;IAC5C,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,iBAAiB;IACpD,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,kBAAkB;IACrD,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,gBAAgB;IAClD,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,gBAAgB;IAClD,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,cAAc;IAC9C,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,EAAE,yBAAyB;IACpE,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE,mBAAmB;IACvD,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,EAAE,sBAAsB;IAC7D,CAAC,gBAAgB,CAAC,qBAAqB,CAAC,EAAE,yBAAyB;IACnE,CAAC,gBAAgB,CAAC,yBAAyB,CAAC,EAAE,6BAA6B;IAC3E,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,iBAAiB;IACpD,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,EAAE,uBAAuB;IAChE,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,EAAE,oBAAoB;IACzD,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,YAAY;CAC3C,CAAC;AASF;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,IAAI,CAAW;IAExB,YAAY,IAAY,EAAE,OAAgB,EAAE,IAAc;QACxD,MAAM,QAAQ,GAAG,OAAO,IAAI,uBAAuB,CAAC,IAAwB,CAAC,IAAI,cAAc,CAAC;QAChG,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAED,aAAa;QACX,MAAM,GAAG,GAAuB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3E,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,MAAc;QAClC,OAAO,IAAI,QAAQ,CAAC,gBAAgB,CAAC,cAAc,EAAE,qBAAqB,MAAM,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,MAAe,EAAE,IAAc;QAClD,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACxE,OAAO,IAAI,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;CACF"}

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

@@ -15,6 +15,9 @@ export const METHOD_NAMES = [
     'turn/read',
     'turn/send',
     'turn/cancel',
+    // Message queue
+    'queue/resume',
+    'queue/clear',
     // Git
     'git/status',
     'git/diff',

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

@@ -5,7 +5,7 @@
  * Source: architecture/02b-contracts-and-requirements.md and
  * uxnandesktop/architecture/02e-bridge-integration.md §4.4.
  */
-import type { AccessMode, Thread, ThreadList, Turn, TurnList } from '../models/thread.js';
+import type { AccessMode, QueuePausedReason, Thread, ThreadList, Turn, TurnList } from '../models/thread.js';
 import type { GitBranchList, GitBranchResult, GitCommitDetails, GitCommitResult, GitCommitShowParams, GitDiff, GitLogParams, GitLogResult, GitPrResult, GitPullResult, GitPushResult, GitRepoStatus, GitWorktreeResult } from '../models/git.js';
 import type { ApplyResult, BrowseResult, Checkpoint, CheckpointDiff, FileContent, ImageContent, PatchChange, TurnAttachment, WorkspaceExistsResult, WorkspaceListing, SearchFilesParams, WorkspaceSearchResult } from '../models/workspace.js';
 import type { AuthStatus, Project } from '../models/project.js';
@@ -91,6 +91,20 @@ export interface TurnSendParams {
      * required.
      */
     command?: AgentCommandInvocation;
+    /**
+     * What to do when a turn is ALREADY in flight on this thread (the CLIs' own
+     * "queue a follow-up while it works" behaviour):
+     * - `true` — queue it explicitly; it starts when the queue drains to it.
+     * - `false` — reject with `AgentBusy` instead of queueing (a client that
+     *   wants to handle the busy case itself).
+     * - absent — **queue it anyway**. Queueing is the safe default because the
+     *   bridge can only drive ONE turn per thread: half the agents run one-shot
+     *   per turn (`claude -p --resume`, gemini, pi, antigravity) and a second
+     *   concurrent turn would put two CLI processes on the same session.
+     *
+     * Ignored when no turn is in flight — the turn simply starts.
+     */
+    queue?: boolean;
 }
 export interface ThreadSetModelParams {
     threadId: string;
@@ -108,6 +122,22 @@ export interface ThreadSetAccessModeParams {
 }
 export interface TurnSendResult {
     turnId: string;
+    /**
+     * True when the turn was QUEUED behind an in-flight one instead of starting
+     * now. The `turnId` is real either way (the turn is stored, and `turn/cancel`
+     * takes it off the queue); it just has status `queued` until it runs.
+     */
+    queued?: boolean;
+    /** 1-based place in the queue when `queued` is true (1 = runs next). */
+    queuePosition?: number;
+}
+export interface QueueStateResult {
+    /** Queued turn ids in drain order. */
+    queuedTurnIds: string[];
+    /** True while draining is held after a stop/failure. */
+    paused: boolean;
+    /** Why it is held; absent when it is not paused. */
+    pausedReason?: QueuePausedReason;
 }
 export interface GitCommitParams {
     cwd: string;
@@ -342,6 +372,20 @@ export interface JsonRpcMethodRegistry {
         };
         result: void;
     };
+    /** Resumes draining after a stop/failure held the queue. */
+    'queue/resume': {
+        params: {
+            threadId: string;
+        };
+        result: QueueStateResult;
+    };
+    /** Drops every queued turn (each → `cancelled`) and clears the paused state. */
+    'queue/clear': {
+        params: {
+            threadId: string;
+        };
+        result: QueueStateResult;
+    };
     'git/status': {
         params: {
             cwd: string;

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

@@ -3,6 +3,7 @@
  *
  * Source: architecture/02b-contracts-and-requirements.md (streaming events).
  */
+import type { QueuePausedReason } from '../models/thread.js';
 export declare const StreamNotification: {
     readonly TurnStarted: "stream/turn/started";
     readonly MessageDelta: "stream/message/delta";
@@ -13,6 +14,10 @@ export declare const StreamNotification: {
     readonly TurnCompleted: "stream/turn/completed";
     readonly TurnError: "stream/turn/error";
     readonly TurnAborted: "stream/turn/aborted";
+    /** A queued turn was removed before it ever ran (status → `cancelled`). */
+    readonly TurnCancelled: "stream/turn/cancelled";
+    /** 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. */
     readonly ModelResolved: "stream/model/resolved";
 };
@@ -89,6 +94,32 @@ export interface TurnAbortedParams {
     threadId: string;
     turnId: string;
 }
+/**
+ * A queued turn was removed before it ever started (its status is now
+ * `cancelled`). The turn is NOT deleted — the user's message stays in the
+ * thread, marked as cancelled, so the history shows what was asked and dropped.
+ */
+export interface TurnCancelledParams {
+    threadId: string;
+    turnId: 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-
+ * reconnect) converges on the next one it receives instead of drifting.
+ *
+ * A client that sees an id it does not know about yet (another device queued
+ * it) resyncs the thread the same way it does for any unknown turn.
+ */
+export interface QueueUpdatedParams {
+    threadId: string;
+    /** Queued turn ids in drain order; empty when the queue just emptied. */
+    queuedTurnIds: string[];
+    /** True while draining is held after a stop/failure (see `TurnList.queuePaused`). */
+    paused: boolean;
+    /** Why it is held; absent when it is not paused. */
+    pausedReason?: QueuePausedReason;
+}
 export interface ModelResolvedParams {
     threadId: string;
     turnId: string;

package/dist/src/jsonrpc/notifications.js

@@ -1,8 +1,3 @@
-/**
- * Bridge → phone streaming notifications (JSON-RPC notifications, no `id`).
- *
- * Source: architecture/02b-contracts-and-requirements.md (streaming events).
- */
 export const StreamNotification = {
     TurnStarted: 'stream/turn/started',
     MessageDelta: 'stream/message/delta',
@@ -13,6 +8,10 @@ export const StreamNotification = {
     TurnCompleted: 'stream/turn/completed',
     TurnError: 'stream/turn/error',
     TurnAborted: 'stream/turn/aborted',
+    /** A queued turn was removed before it ever ran (status → `cancelled`). */
+    TurnCancelled: 'stream/turn/cancelled',
+    /** 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. */
     ModelResolved: 'stream/model/resolved',
 };

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

@@ -1 +1 @@
-{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../../src/jsonrpc/notifications.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,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,sFAAsF;IACtF,aAAa,EAAE,uBAAuB;CAC9B,CAAC"}
+{"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,+EAA+E;IAC/E,YAAY,EAAE,sBAAsB;IACpC,sFAAsF;IACtF,aAAa,EAAE,uBAAuB;CAC9B,CAAC"}

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

@@ -37,4 +37,27 @@ export interface BridgeStatus {
      * without querying npm itself. Absent/false when unknown or up to date.
      */
     updateAvailable?: boolean;
+    /**
+     * Optional capabilities this bridge supports, so a newer client offers a
+     * feature only where it actually works instead of inferring it from the
+     * version string. **Absent means "assume none"** — an older bridge simply
+     * omits the field and the client falls back to the pre-feature behaviour.
+     *
+     * This matters because guessing wrong is not a cosmetic degradation: a client
+     * that offers to queue a follow-up against a bridge that cannot queue makes it
+     * start a second CONCURRENT turn, which corrupts the agent session (two CLI
+     * processes on one `--resume`; OpenCode retires the running turn outright).
+     */
+    features?: BridgeFeatures;
+}
+/** Optional, additive bridge capabilities advertised on {@link BridgeStatus}. */
+export interface BridgeFeatures {
+    /**
+     * The bridge queues a `turn/send` that arrives while a turn is in flight
+     * (stored as a `queued` turn, drained on completion) instead of starting it
+     * concurrently, and implements `queue/resume` / `queue/clear`. Absent/false →
+     * the client must NOT offer to queue: sending during a live turn is unsafe on
+     * that bridge.
+     */
+    messageQueue?: boolean;
 }

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

@@ -5,8 +5,31 @@
  * and are kept in sync manually (see 02e-bridge-integration.md §4.2).
  */
 export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
-export type TurnStatus = 'pending' | 'streaming' | 'completed' | 'error' | 'aborted';
+/**
+ * Lifecycle of a turn.
+ * - `queued` — accepted while another turn was in flight; it holds its place in
+ *   the thread's queue and starts on its own once the queue drains to it. The
+ *   user message is already stored, the assistant one is still empty.
+ * - `pending` / `streaming` — the agent is producing it.
+ * - `completed` / `error` — it ran and ended.
+ * - `aborted` — it was RUNNING and the user stopped it mid-flight.
+ * - `cancelled` — it was QUEUED and removed before it ever started. Kept in the
+ *   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".
+ */
+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:
+ * - `turnAborted` — the user stopped the running turn.
+ * - `turnError` — the running turn failed.
+ *
+ * In both cases the remaining queued turns are kept, not discarded: the user
+ * stopped (or the agent broke) for a reason, and firing the follow-ups at it
+ * anyway is the one outcome nobody wants. Draining resumes on `queue/resume`.
+ */
+export type QueuePausedReason = 'turnAborted' | 'turnError';
 export interface Message {
     id: string;
     turnId: string;
@@ -101,4 +124,20 @@ export interface TurnList {
      * stopped tracking while backgrounded, instead of treating the turn as ended.
      */
     activeTurnId?: string;
+    /**
+     * The thread's queued turns (status `queued`), in the order they will run.
+     * Like {@link activeTurnId} this is LIVE bridge state the phone re-attaches to
+     * on resync — a client restores its "queued" bubbles from it without having to
+     * scan the returned page (the queue may sit outside a narrow `turn/list` page).
+     * Absent/empty when nothing is queued.
+     */
+    queuedTurnIds?: string[];
+    /**
+     * True when the queue is HELD: the previous turn was stopped by the user or
+     * failed, so the bridge stopped draining and is waiting for an explicit
+     * `queue/resume` (or `queue/clear`). Queued turns stay queued meanwhile.
+     */
+    queuePaused?: boolean;
+    /** Why the queue is held; absent when it is not paused. */
+    queuePausedReason?: QueuePausedReason;
 }

package/package.json

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