@uxnan/shared 0.0.22-alpha.20260927 → 0.0.23-alpha.20260927

package/README.md

@@ -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 — **87 JSON-RPC methods** + **22 streaming
+> **Status:** implemented and stable — **93 JSON-RPC methods** + **24 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,14 +49,15 @@ flowchart TB
 
 | Area | Exports |
 |---|---|
-| JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32009`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
+| JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32010`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
 | Streaming | `StreamNotification` enum + param types (`TurnStartedParams`, `MessageDeltaParams`, `ThinkingDeltaParams`, `ContentBlockParams`, `TurnCompletedParams`, `TurnUsage`, `TurnErrorParams`, `TurnAbortedParams`, `ModelResolvedParams`, and the multi-client set: `ThreadUpdatedParams`, `ThreadDeletedParams`, `TurnCreatedParams`, `ApprovalResolvedParams`, `QuestionResolvedParams`) |
 | Local control | the loopback channel Uxnan Desktop uses on the bridge's machine: `LOCAL_CONTROL_FILE` / `LOCAL_CONTROL_PATH`, `LocalControlDiscovery`, the `LocalControlFrame` union (`hello` + `message`), `isValidLocalClientId`, `localReceiverId` (architecture/02a §5.8.15) |
 | Replica sync | `sync/changes` (`SyncChanges`: revisioned threads, projects, settings, deletions, presence), `BridgeSettings { home }`, `ClientPresence`, `Project` registry fields, `Turn.seq`, `Thread.origin` (`src/models/sync.ts`, architecture/02a §5.8.17) |
 | Agent locations | `agent-locations.json` (package root) + `locateAgent` / `agentLocation`: where every agent CLI installs — the one table the bridge and Uxnan Desktop resolve from |
 | 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), durable `CompactionContentBlock` and `AssistantResponseBoundaryBlock`, 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) |
-| Agents | `IAgentAdapter` (with `respondApproval`, `listModels`, `nativeSessionId`, `SendTurnOptions { threadId, turnId, text, service?, effort?, options?, attachments?, cwd?, accessMode? }`), `AgentModel` (incl. `version?`, `isDefault?`, `options?`, `contextWindow?`, `isLatestAlias?`), `AgentCapabilities` (incl. `images`, `approvals`, `reportsContextUsage`, `reportsCompaction`), `AgentDescriptor.deprecated`, `AgentConfig` (cwd, agentId, model, plus optional `binaryPath`/`extraArgs`) |
+| Agent sessions | `agent/sessions` · `holds` · `hold` · `release` · `requestHandoff` · `handoffAnswer` (`AgentSessionSummary`, `AgentSessionHold`, hand-off outcomes), `stream/agent/held` / `handoffRequested`, `SessionHeld` (`-32010`), `ONE_SHOT_PROMPT_OPENERS` / `isOneShotPrompt` (`src/models/agent-session.ts`, `src/agents/one-shot.ts`, architecture/02a §5.8.19) |
+| Agents | `IAgentAdapter` (with `respondApproval`, `listModels`, `nativeSessionId`, `adoptNativeSession`, `listNativeSessions` → `NativeSessionInfo`, `SendTurnOptions { threadId, turnId, text, service?, effort?, options?, attachments?, cwd?, accessMode? }`), `AgentModel` (incl. `version?`, `isDefault?`, `options?`, `contextWindow?`, `isLatestAlias?`), `AgentCapabilities` (incl. `images`, `approvals`, `reportsContextUsage`, `reportsCompaction`), `AgentDescriptor.deprecated`, `AgentConfig` (cwd, agentId, model, plus optional `binaryPath`/`extraArgs`) |
 | Version | `compareVersions` / `isNewerVersion` — dependency-free SemVer precedence (used by the bridge's npm update check) |
 | Validation | Ajv validators for requests, responses, envelopes, pairing payload, push payloads |
 

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

@@ -85,6 +85,26 @@ export interface GenerateTitleOptions {
     /** Working directory to run the one-shot in (the thread's own). */
     cwd?: string;
 }
+/**
+ * One of the agent's own sessions in a folder, as its CLI keeps it — the raw
+ * material of `agent/sessions` (the bridge turns the time into an age and
+ * links the conversation that continues it).
+ */
+export interface NativeSessionInfo {
+    sessionId: string;
+    cwd: string;
+    /** The CLI's own title for it, else the first thing the person asked. */
+    title?: string;
+    /** When it last changed, on this PC's clock (epoch ms). */
+    updatedAt: number;
+    /**
+     * Started by a person in the agent's own interface (its terminal UI or
+     * app), rather than run headless by a program — the bridge's own runs, or
+     * one-shots like naming a conversation. A headless session is listed only
+     * when a conversation continues it.
+     */
+    interactive: boolean;
+}
 export interface IAgentAdapter {
     readonly agentId: AgentId;
     readonly capabilities: AgentCapabilities;
@@ -96,6 +116,33 @@ export interface IAgentAdapter {
     sendTurn(options: SendTurnOptions): Promise<void>;
     /** Cancel an in-flight turn. */
     cancelTurn(threadId: string, turnId: string): Promise<void>;
+    /**
+     * The agent's own session id for a conversation — the id its CLI resumes
+     * (`claude --resume`, Codex `thread/resume`, ACP `session/load`, …) and the
+     * one its transcript on disk is named after. `undefined` until the agent
+     * has one for the thread.
+     */
+    nativeSessionId(threadId: string): string | undefined;
+    /**
+     * Continue a conversation in a native session this process did not open:
+     * the id the bridge stored before it restarted, or a session started
+     * elsewhere (a terminal) that the conversation now takes over. The next
+     * turn resumes it instead of opening a new one, so the agent keeps the
+     * context the user can see.
+     *
+     * Never replaces a session the adapter already holds for the thread, and
+     * never takes back an id the CLI already refused to resume for it: that
+     * conversation continues in the fresh session that replaced it.
+     */
+    adoptNativeSession(threadId: string, sessionId: string): void;
+    /**
+     * The agent's sessions in a folder, most recent first, read the way this
+     * CLI exposes them (its app-server, its server, ACP `session/list`, or its
+     * own session store — head and tail only, never whole transcripts).
+     * Optional: an agent whose CLI cannot list its sessions (Antigravity) omits
+     * it, and its sessions are continued only from the terminal they run in.
+     */
+    listNativeSessions?(cwd: string): Promise<NativeSessionInfo[]>;
     /**
      * Name a conversation from its opening exchange — a handful of words, no
      * punctuation, in the language the user wrote in.

package/dist/src/agents/one-shot.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Uxnan's own one-shot prompts: the short headless runs it makes through an
+ * agent's CLI to name a conversation or write a commit message or a pull
+ * request body. They are errands, not conversations — but a CLI that cannot
+ * run without keeping a session (OpenCode, Grok, Zero, Antigravity; Claude
+ * Code, Codex and pi run them without one) keeps them in its history like any
+ * other session. The session catalog (`agent/sessions`) leaves them out by
+ * how they open.
+ *
+ * Every producer's test checks its prompt opens with one of these, so a
+ * reworded prompt cannot leak back into the list: the bridge's
+ * (`agents/thread-title.ts`) and the desktop's (`convtitle.rs`, `aicommit.rs`).
+ */
+export declare const ONE_SHOT_PROMPT_OPENERS: readonly ["Name this conversation in 3 to 6 words", "Below is an excerpt of a terminal session with a coding agent.", "Write a git commit message for the following staged changes.", "Write a GitHub pull request description in Markdown"];
+/** Whether a session's first prompt is one of Uxnan's own one-shots. */
+export declare function isOneShotPrompt(prompt: string): boolean;

package/dist/src/agents/one-shot.js

@@ -0,0 +1,29 @@
+/**
+ * Uxnan's own one-shot prompts: the short headless runs it makes through an
+ * agent's CLI to name a conversation or write a commit message or a pull
+ * request body. They are errands, not conversations — but a CLI that cannot
+ * run without keeping a session (OpenCode, Grok, Zero, Antigravity; Claude
+ * Code, Codex and pi run them without one) keeps them in its history like any
+ * other session. The session catalog (`agent/sessions`) leaves them out by
+ * how they open.
+ *
+ * Every producer's test checks its prompt opens with one of these, so a
+ * reworded prompt cannot leak back into the list: the bridge's
+ * (`agents/thread-title.ts`) and the desktop's (`convtitle.rs`, `aicommit.rs`).
+ */
+export const ONE_SHOT_PROMPT_OPENERS = [
+    // Naming a chat (the bridge).
+    'Name this conversation in 3 to 6 words',
+    // Naming a terminal session (the desktop).
+    'Below is an excerpt of a terminal session with a coding agent.',
+    // A commit message (the desktop).
+    'Write a git commit message for the following staged changes.',
+    // A pull request body (the desktop).
+    'Write a GitHub pull request description in Markdown',
+];
+/** Whether a session's first prompt is one of Uxnan's own one-shots. */
+export function isOneShotPrompt(prompt) {
+    const text = prompt.trimStart();
+    return ONE_SHOT_PROMPT_OPENERS.some((opener) => text.startsWith(opener));
+}
+//# sourceMappingURL=one-shot.js.map

package/dist/src/agents/one-shot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"one-shot.js","sourceRoot":"","sources":["../../../src/agents/one-shot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,8BAA8B;IAC9B,wCAAwC;IACxC,2CAA2C;IAC3C,gEAAgE;IAChE,kCAAkC;IAClC,8DAA8D;IAC9D,qCAAqC;IACrC,qDAAqD;CAC7C,CAAC;AAEX,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAChC,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAC3E,CAAC"}

package/dist/src/index.d.ts

@@ -15,6 +15,7 @@ export * from './agents/agent-capabilities.js';
 export * from './agents/agent-config.js';
 export * from './agents/agent-adapter.js';
 export * from './agents/agent-locations.js';
+export * from './agents/one-shot.js';
 export * from './local-control/local-control.js';
 export * from './version/compare.js';
 export * from './notifications/push-payload.js';
@@ -31,5 +32,6 @@ export * from './models/assistant-response.js';
 export * from './models/tool.js';
 export * from './models/usage.js';
 export * from './models/metrics.js';
+export * from './models/agent-session.js';
 export * from './validators/validate.js';
 export * from './validators/json-schema/schemas.js';

package/dist/src/index.js

@@ -18,6 +18,7 @@ export * from './agents/agent-capabilities.js';
 export * from './agents/agent-config.js';
 export * from './agents/agent-adapter.js';
 export * from './agents/agent-locations.js';
+export * from './agents/one-shot.js';
 // Local control channel (desktop ↔ bridge on the same machine)
 export * from './local-control/local-control.js';
 // Version
@@ -38,6 +39,7 @@ export * from './models/assistant-response.js';
 export * from './models/tool.js';
 export * from './models/usage.js';
 export * from './models/metrics.js';
+export * from './models/agent-session.js';
 // Validators
 export * from './validators/validate.js';
 export * from './validators/json-schema/schemas.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,OAAO;AACP,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAE1C,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAE5C,+DAA+D;AAC/D,cAAc,kCAAkC,CAAC;AAEjD,UAAU;AACV,cAAc,sBAAsB,CAAC;AAErC,gBAAgB;AAChB,cAAc,iCAAiC,CAAC;AAEhD,SAAS;AACT,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AAEpC,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,OAAO;AACP,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAE1C,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AAErC,+DAA+D;AAC/D,cAAc,kCAAkC,CAAC;AAEjD,UAAU;AACV,cAAc,sBAAsB,CAAC;AAErC,gBAAgB;AAChB,cAAc,iCAAiC,CAAC;AAEhD,SAAS;AACT,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAE1C,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}

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

@@ -25,6 +25,12 @@ export declare const JsonRpcErrorCode: {
      * explicit opt-out — the default is to queue.
      */
     readonly AgentBusy: -32009;
+    /**
+     * The conversation's agent session is open in a desktop terminal
+     * (`agent/hold`): the bridge runs no turn in it until the terminal
+     * lets it go. `data` carries the {@link AgentSessionHold}.
+     */
+    readonly SessionHeld: -32010;
 };
 export type JsonRpcErrorCode = (typeof JsonRpcErrorCode)[keyof typeof JsonRpcErrorCode];
 /** Human-readable default messages for each error code. */

package/dist/src/jsonrpc/errors.js

@@ -27,6 +27,12 @@ export const JsonRpcErrorCode = {
      * explicit opt-out — the default is to queue.
      */
     AgentBusy: -32009,
+    /**
+     * The conversation's agent session is open in a desktop terminal
+     * (`agent/hold`): the bridge runs no turn in it until the terminal
+     * lets it go. `data` carries the {@link AgentSessionHold}.
+     */
+    SessionHeld: -32010,
 };
 /** Human-readable default messages for each error code. */
 export const JSON_RPC_ERROR_MESSAGES = {
@@ -45,6 +51,7 @@ export const JSON_RPC_ERROR_MESSAGES = {
     [JsonRpcErrorCode.ConfirmationRequired]: 'Confirmation required',
     [JsonRpcErrorCode.ResourceNotFound]: 'Resource not found',
     [JsonRpcErrorCode.AgentBusy]: 'Agent busy',
+    [JsonRpcErrorCode.SessionHeld]: 'Session open in a terminal',
 };
 /**
  * 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":"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"}

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", "turn/attachment", "queue/resume", "queue/clear", "queue/sendNow", "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/worktrees", "git/log", "git/commitShow", "workspace/readFile", "workspace/readImage", "workspace/list", "workspace/searchFiles", "workspace/resolveFileLink", "workspace/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "project/add", "project/remove", "project/rename", "sync/changes", "settings/get", "settings/set", "device/describe", "device/rename", "agent/list", "agent/models", "agent/commands", "agent/usageStats", "usage/redeemReset", "usage/summary", "agent/doctor", "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", "bridge/update", "bridge/checkForUpdate", "desktop/attach", "desktop/detach"];
+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", "turn/attachment", "queue/resume", "queue/clear", "queue/sendNow", "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/worktrees", "git/log", "git/commitShow", "workspace/readFile", "workspace/readImage", "workspace/list", "workspace/searchFiles", "workspace/resolveFileLink", "workspace/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "project/add", "project/remove", "project/rename", "sync/changes", "settings/get", "settings/set", "device/describe", "device/rename", "agent/list", "agent/models", "agent/commands", "agent/usageStats", "usage/redeemReset", "usage/summary", "agent/sessions", "agent/holds", "agent/hold", "agent/release", "agent/requestHandoff", "agent/handoffAnswer", "agent/doctor", "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", "bridge/update", "bridge/checkForUpdate", "desktop/attach", "desktop/detach"];
 export declare function isKnownMethod(method: string): method is JsonRpcMethodName;

package/dist/src/jsonrpc/method-registry.js

@@ -73,6 +73,13 @@ export const METHOD_NAMES = [
     'agent/usageStats',
     'usage/redeemReset',
     'usage/summary',
+    // Agent sessions
+    'agent/sessions',
+    'agent/holds',
+    'agent/hold',
+    'agent/release',
+    'agent/requestHandoff',
+    'agent/handoffAnswer',
     'agent/doctor',
     // Metrics (bridge-owned, survivable profile stats + tamper-proof backup)
     'metrics/get',

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,iBAAiB;IACjB,gBAAgB;IAChB,cAAc;IACd,aAAa;IACb,eAAe;IACf,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,eAAe;IACf,SAAS;IACT,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,2BAA2B;IAC3B,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,mCAAmC;IACnC,cAAc;IACd,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,eAAe;IACf,cAAc;IACd,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;IAC5B,eAAe;IACf,uBAAuB;IACvB,mEAAmE;IACnE,gBAAgB;IAChB,gBAAgB;CACR,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,iBAAiB;IACjB,gBAAgB;IAChB,cAAc;IACd,aAAa;IACb,eAAe;IACf,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,eAAe;IACf,SAAS;IACT,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,2BAA2B;IAC3B,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,mCAAmC;IACnC,cAAc;IACd,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,eAAe;IACf,sBAAsB;IACtB,qBAAqB;IACrB,cAAc;IACd,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;IAC5B,eAAe;IACf,uBAAuB;IACvB,mEAAmE;IACnE,gBAAgB;IAChB,gBAAgB;CACR,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,6 +5,7 @@
  * Source: architecture/02b-contracts-and-requirements.md and
  * uxnandesktop/architecture/02e-bridge-integration.md §4.4.
  */
+import type { AgentSessionHandoffAnswerParams, AgentSessionHandoffResult, AgentSessionHold, AgentSessionHoldParams, AgentSessionHoldsResult, AgentSessionKey, AgentSessionListParams, AgentSessionListResult } from '../models/agent-session.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, GitWorktreeList, GitWorktreeResult } from '../models/git.js';
 import type { ApplyResult, BrowseResult, Checkpoint, CheckpointDiff, FileContent, ImageContent, PatchChange, TurnAttachment, WorkspaceFileTarget, WorkspaceExistsResult, WorkspaceListing, SearchFilesParams, WorkspaceSearchResult } from '../models/workspace.js';
@@ -31,6 +32,13 @@ export interface StartThreadParams {
     model?: string;
     /** Working directory override; defaults to the project's cwd. */
     cwd?: string;
+    /**
+     * Continue this existing session of the agent (`agent/sessions`) instead
+     * of opening a new one: its turns become the conversation's history and the
+     * first turn resumes it. Requires `agentId`. When a conversation already
+     * continues the session, that conversation is returned instead of a second one.
+     */
+    agentSessionId?: string;
 }
 export interface ForkParams {
     threadId: string;
@@ -684,6 +692,30 @@ export interface JsonRpcMethodRegistry {
         params: UsageSummaryParams;
         result: UsageSummary;
     };
+    'agent/sessions': {
+        params: AgentSessionListParams;
+        result: AgentSessionListResult;
+    };
+    'agent/holds': {
+        params: void;
+        result: AgentSessionHoldsResult;
+    };
+    'agent/hold': {
+        params: AgentSessionHoldParams;
+        result: AgentSessionHold;
+    };
+    'agent/release': {
+        params: AgentSessionKey;
+        result: void;
+    };
+    'agent/requestHandoff': {
+        params: AgentSessionKey;
+        result: AgentSessionHandoffResult;
+    };
+    'agent/handoffAnswer': {
+        params: AgentSessionHandoffAnswerParams;
+        result: void;
+    };
     'agent/doctor': {
         params: void;
         result: {

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

@@ -67,6 +67,16 @@ export declare const StreamNotification: {
      * would answer now (idempotent).
      */
     readonly BridgeUpdated: "stream/bridge/updated";
+    /**
+     * A session's hold changed: a desktop terminal took it, its agent started or
+     * stopped working, or the terminal let it go (`hold` absent).
+     */
+    readonly AgentSessionHeld: "stream/agent/held";
+    /**
+     * Someone asked the holding desktop to let a session go (sent to that
+     * desktop only); it answers with `agent/handoffAnswer`.
+     */
+    readonly AgentSessionHandoffRequested: "stream/agent/handoffRequested";
 };
 export type StreamNotification = (typeof StreamNotification)[keyof typeof StreamNotification];
 export interface TurnStartedParams {

package/dist/src/jsonrpc/notifications.js

@@ -50,5 +50,15 @@ export const StreamNotification = {
      * would answer now (idempotent).
      */
     BridgeUpdated: 'stream/bridge/updated',
+    /**
+     * A session's hold changed: a desktop terminal took it, its agent started or
+     * stopped working, or the terminal let it go (`hold` absent).
+     */
+    AgentSessionHeld: 'stream/agent/held',
+    /**
+     * Someone asked the holding desktop to let a session go (sent to that
+     * desktop only); it answers with `agent/handoffAnswer`.
+     */
+    AgentSessionHandoffRequested: 'stream/agent/handoffRequested',
 };
 //# 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":"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;IACtC;;;;OAIG;IACH,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;IACtC;;;;OAIG;IACH,aAAa,EAAE,uBAAuB;IACtC;;;OAGG;IACH,gBAAgB,EAAE,mBAAmB;IACrC;;;OAGG;IACH,4BAA4B,EAAE,+BAA+B;CACrD,CAAC"}

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

@@ -0,0 +1,120 @@
+/**
+ * Agent sessions: the conversations an agent CLI keeps on the PC, whoever
+ * started them — a terminal, the bridge, the agent's own app — and whether one
+ * is open in a terminal right now (architecture/02a §5.8.19).
+ *
+ * The bridge owns both: it lists each agent's sessions through that agent's
+ * own surface (`agent/sessions`), and it knows which ones a desktop
+ * terminal holds (`agent/hold`), so every client — phone, desktop — can
+ * pick a session up, and none of them ever writes into a session a terminal is
+ * running.
+ *
+ * Across devices every time is an age (`…AgoMs`), never a timestamp.
+ */
+import type { AgentId } from '../agents/agent-capabilities.js';
+/** One of an agent's sessions in a folder, as `agent/sessions` returns it. */
+export interface AgentSessionSummary {
+    agentId: AgentId;
+    /** The agent's own session id — the one its CLI resumes. */
+    sessionId: string;
+    /** The folder the session runs in. */
+    cwd: string;
+    /**
+     * The session's name: the CLI's own title when it keeps one, else the
+     * first thing the person asked, trimmed. Absent when neither is known.
+     */
+    title?: string;
+    /** How long ago the session last changed. */
+    updatedAgoMs: number;
+    /** The conversation that continues this session, when one does. */
+    threadId?: string;
+    /** Where the session is open right now, when a terminal holds it. */
+    hold?: AgentSessionHold;
+}
+/** Who holds a session: a terminal of Uxnan Desktop, on the named PC. */
+export interface AgentSessionHolder {
+    kind: 'terminal';
+    /** The PC's name, as the bridge's shared settings call it. */
+    name: string;
+}
+/**
+ * A session open in a desktop terminal. While it is held, the bridge runs no
+ * turn in it: a CLI's session has one writer, and the terminal is it.
+ */
+export interface AgentSessionHold {
+    agentId: AgentId;
+    sessionId: string;
+    cwd?: string;
+    holder: AgentSessionHolder;
+    /** How long ago the terminal took it. */
+    heldAgoMs: number;
+    /** Whether the agent is working right now; a hand-off waits until it is not. */
+    busy: boolean;
+    /** The conversation that continues this session, when one does. */
+    threadId?: string;
+}
+/** Which session: an agent and its session id. */
+export interface AgentSessionKey {
+    agentId: AgentId;
+    sessionId: string;
+}
+export interface AgentSessionListParams {
+    /** The folder whose sessions to list. */
+    cwd: string;
+    /** Only this agent's sessions; every agent's when absent. */
+    agentId?: AgentId;
+}
+export interface AgentSessionListResult {
+    /** Most recently changed first. */
+    sessions: AgentSessionSummary[];
+    /**
+     * Agents installed here whose CLI cannot list its sessions (Antigravity):
+     * one of their sessions can still be continued from the terminal it runs in.
+     */
+    unlisted: AgentId[];
+}
+/**
+ * `agent/hold` — Uxnan Desktop says one of its terminals has this
+ * session open (or that its agent started or stopped working). Idempotent:
+ * the latest call wins. Accepted only over the local control channel, and
+ * dropped when that connection closes (the terminals close with the app).
+ */
+export interface AgentSessionHoldParams extends AgentSessionKey {
+    cwd?: string;
+    busy?: boolean;
+}
+export interface AgentSessionHoldsResult {
+    holds: AgentSessionHold[];
+}
+/**
+ * How asking a terminal to let go of a session ended:
+ * - `released`: the agent was closed in its terminal; the session is free.
+ * - `busy`: the agent is working; ask again when it is done.
+ * - `declined`: the person at the PC kept it.
+ * - `unreachable`: the desktop did not answer in time.
+ * - `notHeld`: no terminal holds it; it is free already.
+ */
+export type AgentSessionHandoffOutcome = 'released' | 'busy' | 'declined' | 'unreachable' | 'notHeld';
+export interface AgentSessionHandoffResult {
+    outcome: AgentSessionHandoffOutcome;
+}
+/** `stream/agent/handoffRequested` — sent only to the holding desktop. */
+export interface AgentSessionHandoffRequestedParams extends AgentSessionKey {
+    /** Answer with `agent/handoffAnswer` quoting this id. */
+    requestId: string;
+    /** Who asks: the client's name (a phone's, or the PC's). */
+    from: string;
+}
+/** `agent/handoffAnswer` — the holding desktop's answer. */
+export interface AgentSessionHandoffAnswerParams {
+    requestId: string;
+    outcome: Extract<AgentSessionHandoffOutcome, 'released' | 'busy' | 'declined'>;
+}
+/**
+ * `stream/agent/held` — a session's hold changed: taken, busy or idle,
+ * or let go (`hold` absent). Every client follows it; one that missed some
+ * asks `agent/holds`.
+ */
+export interface AgentSessionHeldParams extends AgentSessionKey {
+    hold?: AgentSessionHold;
+}

package/dist/src/models/agent-session.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-session.js.map

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

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

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

@@ -225,4 +225,12 @@ export interface BridgeFeatures {
      * `Turn.seq`. Absent/false → a client keeps its older `thread/list` flow.
      */
     sync?: boolean;
+    /**
+     * The bridge lists every agent's sessions in a folder (`agent/sessions`),
+     * starts a conversation that continues one (`thread/start` with
+     * `agentSessionId`) and knows which ones a desktop terminal holds
+     * (`agent/holds`, `agent/hold`, …, `stream/agent/held`). Absent/false → a client
+     * offers none of it.
+     */
+    agentSessions?: boolean;
 }

package/package.json

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