@uxnan/shared 0.0.12-alpha.20260803 → 0.0.13-alpha.20260804

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/69_methods_%7C_10_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/69_methods_%7C_12_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 — **69 JSON-RPC methods** + **10 streaming
+> **Status:** implemented and stable — **69 JSON-RPC methods** + **12 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

@@ -62,6 +62,15 @@ export interface SendTurnOptions {
      */
     command?: AgentCommandInvocation;
 }
+/** Input for {@link IAgentAdapter.generateTitle}. */
+export interface GenerateTitleOptions {
+    /** The user's opening message. */
+    userText: string;
+    /** The agent's reply to it, when there is one (trimmed by the caller). */
+    assistantText?: string;
+    /** Working directory to run the one-shot in (the thread's own). */
+    cwd?: string;
+}
 export interface IAgentAdapter {
     readonly agentId: AgentId;
     readonly capabilities: AgentCapabilities;
@@ -73,6 +82,46 @@ export interface IAgentAdapter {
     sendTurn(options: SendTurnOptions): Promise<void>;
     /** Cancel an in-flight turn. */
     cancelTurn(threadId: string, turnId: string): Promise<void>;
+    /**
+     * Name a conversation from its opening exchange — a handful of words, no
+     * punctuation, in the language the user wrote in.
+     *
+     * **This is a side errand, not a turn.** Implementations run a fresh one-shot
+     * with **no session id**, so nothing lands in the thread's history, no
+     * streaming event is emitted, and the agent's own context is untouched. It is
+     * also expected to use the agent's *cheapest* model rather than the one the
+     * conversation runs on: naming is a trivial task and should never spend the
+     * expensive model's quota.
+     *
+     * Optional — an adapter that cannot do it cheaply simply omits it, and the
+     * thread keeps the provisional title derived from the opening message.
+     *
+     * Returns the bare title, or `undefined` when the agent produced nothing
+     * usable. **Never throws for an ordinary failure** (no credit, CLI missing,
+     * a timeout): titling is cosmetic and must not disturb a working thread.
+     */
+    generateTitle?(options: GenerateTitleOptions): Promise<string | undefined>;
+    /**
+     * Hand a follow-up to the agent **inside the turn already running** — what a
+     * CLI does when you type while it works and it picks the message up at the
+     * next tool boundary. Implemented only by adapters whose CLI has an input
+     * channel mid-turn; those advertise `AgentCapabilities.steering`.
+     *
+     * `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`.
+     *
+     * Returns **true only when the agent actually took the message**. Return
+     * `false` (don't throw) for an ordinary "too late / not applicable" — the
+     * turn ended between the check and the call, the protocol rejected the
+     * hand-off. The bridge then leaves the turn queued and it runs normally next,
+     * so a refusal costs the user nothing but a wait. Throwing is for a broken
+     * transport, and is handled the same way.
+     */
+    steerTurn?(options: SendTurnOptions & {
+        activeTurnId: string;
+    }): Promise<boolean>;
     /**
      * Reply to a pending approval the agent emitted (as an `approval` content
      * block) for {@link threadId}. Optional: adapters that never request approval

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

@@ -53,6 +53,19 @@ export interface AgentCapabilities {
      * only its client-side `/` palette). See {@link AgentCommand}.
      */
     commands?: boolean;
+    /**
+     * Agent can take a follow-up **into the turn already running** instead of
+     * 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`).
+     *
+     * 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
+     * follow-ups keep waiting for the current turn to end. The phone reads this
+     * to tell the user which of the two is about to happen.
+     */
+    steering?: boolean;
 }
 /**
  * A registered agent the phone can pick for a thread, returned by `agent/list`.

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

@@ -114,6 +114,16 @@ export interface ThreadRenameParams {
     threadId: string;
     /** New, non-empty title for the thread. */
     title: string;
+    /**
+     * Who is naming it. **Absent means the user did** — the safe default, since
+     * `thread/rename` is the hand-rename call and a name the user chose is final.
+     *
+     * A client that auto-names a new thread from its opening message MUST send
+     * `'prompt'`; otherwise its throwaway title is recorded as the user's choice
+     * and the real generated title is refused later. `'agent'` is not accepted
+     * here — the bridge writes those itself when it generates one.
+     */
+    source?: 'prompt' | 'user';
 }
 export interface ThreadSetAccessModeParams {
     threadId: string;
@@ -130,6 +140,17 @@ 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

@@ -3,7 +3,7 @@
  *
  * Source: architecture/02b-contracts-and-requirements.md (streaming events).
  */
-import type { QueuePausedReason } from '../models/thread.js';
+import type { QueuePausedReason, ThreadTitleSource } from '../models/thread.js';
 export declare const StreamNotification: {
     readonly TurnStarted: "stream/turn/started";
     readonly MessageDelta: "stream/message/delta";
@@ -16,10 +16,17 @@ 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. */
     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";
 };
 export type StreamNotification = (typeof StreamNotification)[keyof typeof StreamNotification];
 export interface TurnStartedParams {
@@ -103,6 +110,22 @@ 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-
@@ -126,3 +149,18 @@ export interface ModelResolvedParams {
     /** Concrete model id the agent resolved for this turn (e.g. `claude-opus-4-8`). */
     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.
+ *
+ * `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.
+ */
+export interface ThreadRenamedParams {
+    threadId: string;
+    title: string;
+    titleSource: ThreadTitleSource;
+}

package/dist/src/jsonrpc/notifications.js

@@ -10,9 +10,16 @@ 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. */
     ModelResolved: 'stream/model/resolved',
+    /** A thread's title changed on the bridge (a generated title, or another device's rename). */
+    ThreadRenamed: 'stream/thread/renamed',
 };
 //# 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,+EAA+E;IAC/E,YAAY,EAAE,sBAAsB;IACpC,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;;;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"}

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

@@ -60,4 +60,16 @@ export interface BridgeFeatures {
      * that bridge.
      */
     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
+     * client must expect every follow-up to wait for the current turn to end, and
+     * must not promise otherwise in its UI.
+     *
+     * Distinct from {@link messageQueue}, which this builds on: the queue is where
+     * a follow-up lands, and per-agent `AgentCapabilities.steering` decides
+     * whether it waits there or goes straight through.
+     */
+    midTurnDelivery?: boolean;
 }

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

@@ -17,8 +17,14 @@ 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.
  */
-export type TurnStatus = 'queued' | 'pending' | 'streaming' | 'completed' | 'error' | 'aborted' | 'cancelled';
+export type TurnStatus = 'queued' | 'pending' | 'streaming' | 'completed' | 'error' | 'aborted' | 'cancelled' | 'delivered';
 export type ThreadStatus = 'active' | 'idle' | 'archived';
 /**
  * Why a thread's message queue is held instead of draining:
@@ -68,6 +74,12 @@ 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
@@ -100,7 +112,23 @@ export interface Thread {
     agentSessionId?: string;
     /** Per-thread access (approval) mode; see {@link AccessMode}. */
     accessMode?: AccessMode;
+    /**
+     * Where {@link title} came from, so a better title can replace a weaker one
+     * without ever overwriting a name the **user** chose.
+     *
+     * - `prompt` — provisional, derived from the opening message. Instant, and
+     *   the weakest: two conversations that start with the same phrase collide.
+     * - `agent` — written by a model that read the first exchange. Replaces
+     *   `prompt`, never `user`.
+     * - `user` — renamed by hand (`thread/rename`). Final; nothing overwrites it.
+     *
+     * Absent on threads stored before this existed; treat that as `prompt`, which
+     * is what they are.
+     */
+    titleSource?: ThreadTitleSource;
 }
+/** Where a thread's title came from. See {@link Thread.titleSource}. */
+export type ThreadTitleSource = 'prompt' | 'agent' | 'user';
 export interface ThreadList {
     threads: Thread[];
 }

package/package.json

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