@uxnan/shared 0.0.13-alpha.20260804 → 0.0.15-alpha.20260813

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_12_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/70_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** + **12 streaming
+> **Status:** implemented and stable — **70 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

@@ -163,7 +163,7 @@ export interface IAgentAdapter {
      * reachable headless plus user-defined prompt-template commands scanned from
      * disk (optional; adapters with none simply don't implement it). `cwd` is the
      * thread/project directory so project-scoped custom commands (`<cwd>/.claude/
-     * commands`, `<cwd>/.gemini/commands`, …) are discovered alongside user-level
+     * commands`, `<cwd>/.opencode/command`, …) are discovered alongside user-level
      * ones. Discovery only; invocation flows through {@link sendTurn} with {@link
      * SendTurnOptions.command}.
      */
@@ -172,7 +172,7 @@ export interface IAgentAdapter {
      * Resolve a custom prompt-template command to the final prompt text (reads the
      * template file from `cwd`/user config, substitutes arguments). Implemented
      * only by adapters whose commands are prompt templates the bridge expands
-     * itself (Codex/Gemini/OpenCode); adapters whose commands run natively (Claude
+     * itself (Codex/OpenCode); adapters whose commands run natively (Claude
      * Code, ACP agents) leave it unset and receive the composed `/name args` form
      * as {@link SendTurnOptions.text}. Throw if `name` is not a known custom command.
      */

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

@@ -4,9 +4,7 @@
  * Source: architecture/02a-system-architecture.md §5.8.2 (adapters).
  */
 export type AgentId = 'codex' | 'opencode' | 'claude-code'
-/** @deprecated The standalone Gemini CLI is retired; use `antigravity-cli`. */
- | 'gemini-cli'
-/** Antigravity — Google's `agy` CLI, the successor to the deprecated Gemini CLI. */
+/** Antigravity — Google's supported `agy` CLI. */
  | 'antigravity-cli' | 'pi-agent'
 /** Zero — open-source Go coding agent, driven over the Agent Client Protocol. */
  | 'zero'
@@ -168,7 +166,7 @@ export interface AgentModel {
  *   (Claude Code's `/compact` sent as the prompt with `--resume`; the commands
  *   ACP agents advertise via `available_commands_update`), and
  * - **custom** user-defined prompt-template commands (`.claude/commands`,
- *   `~/.codex/prompts`, `.gemini/commands`, `.opencode/command`) that the bridge
+ *   `~/.codex/prompts`, `.opencode/command`) that the bridge
  *   expands itself before running a normal turn.
  *
  * The phone is a generic renderer: it lists the advertised commands in its `/`

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", "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/resolveFileLink", "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/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", "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

@@ -37,6 +37,7 @@ export const METHOD_NAMES = [
     'git/revert',
     'git/deleteBranch',
     'git/removeWorktree',
+    'git/worktrees',
     'git/log',
     'git/commitShow',
     // Workspace

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,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,2BAA2B;IAC3B,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,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,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

@@ -6,7 +6,7 @@
  * uxnandesktop/architecture/02e-bridge-integration.md §4.4.
  */
 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 { 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';
 import type { AuthStatus, Project } from '../models/project.js';
 import type { ApprovalResponse } from '../models/approval.js';
@@ -99,7 +99,7 @@ export interface TurnSendParams {
      *   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
+     *   per turn (`claude -p --resume`, 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.
@@ -223,7 +223,23 @@ export interface GitBranchParams {
 export interface GitWorktreeParams {
     cwd: string;
     branch: string;
-    path: string;
+    /**
+     * Absolute directory for the new worktree. **Optional**: omit it (with
+     * {@link managed}) and the bridge resolves the location itself, from its
+     * `worktrees` config — by default the managed root
+     * `<home>/uxnan/worktrees/<repo>/<branch>`, the same layout the desktop uses,
+     * so both apps group one repository's checkouts in one place.
+     *
+     * A bridge that does not advertise `features.managedWorktrees` still
+     * **requires** this, so a client that wants to work against an older bridge
+     * has to keep deriving a path as its fallback.
+     */
+    path?: string;
+    /**
+     * Let the bridge own the location (the default when {@link path} is absent).
+     * A managed worktree is recorded in the bridge's registry, so the ones uxnan
+     * created can be told from the ones that were already there.
+     */
     managed?: boolean;
 }
 export interface GitRevertParams {
@@ -284,7 +300,7 @@ export interface AgentCommandsParams {
     agentId: AgentId;
     /**
      * Thread/project directory, so project-scoped custom commands (e.g.
-     * `<cwd>/.claude/commands`, `<cwd>/.gemini/commands`) are discovered alongside
+     * `<cwd>/.claude/commands`, `<cwd>/.opencode/command`) are discovered alongside
      * the user-level ones. Omitted → only user-level commands are returned.
      */
     cwd?: string;
@@ -485,6 +501,13 @@ export interface JsonRpcMethodRegistry {
         params: GitRemoveWorktreeParams;
         result: void;
     };
+    /** Which directories are worktrees of the repository at `cwd`. */
+    'git/worktrees': {
+        params: {
+            cwd: string;
+        };
+        result: GitWorktreeList;
+    };
     'git/log': {
         params: GitLogParams;
         result: GitLogResult;

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

@@ -53,6 +53,30 @@ export interface GitWorktreeResult {
     path: string;
     branch: string;
 }
+/**
+ * One entry of `git worktree list --porcelain`.
+ *
+ * A worktree can live anywhere: beside its repository (`../repo-feature`),
+ * grouped under the folder uxnan manages (`~/uxnan/worktrees/<repo>/<branch>`),
+ * or wherever the user put it. None of those spellings is a child of the main
+ * worktree, and the grouped one shares a prefix with worktrees of OTHER
+ * repositories — which is precisely why a client cannot infer the hierarchy
+ * from paths and has to be told.
+ */
+export interface GitWorktreeEntry {
+    /** Absolute path of the worktree. */
+    path: string;
+    /** Checked-out branch; absent when the worktree is in a detached HEAD. */
+    branch?: string;
+    /** Whether this is the repository's main worktree. */
+    isMain: boolean;
+    /** Whether `git worktree lock` has been applied to it. */
+    isLocked?: boolean;
+}
+export interface GitWorktreeList {
+    /** The main worktree first, then the linked ones in git's own order. */
+    worktrees: GitWorktreeEntry[];
+}
 export interface GitBranchList {
     /** The currently checked-out branch (`HEAD` when detached). */
     current: string;

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

@@ -72,4 +72,17 @@ export interface BridgeFeatures {
      * whether it waits there or goes straight through.
      */
     midTurnDelivery?: boolean;
+    /**
+     * The bridge resolves where a worktree goes on its own, so `git/createWorktree`
+     * accepts `managed: true` **without** a `path` and places it under the managed
+     * root (`<home>/uxnan/worktrees/<repo>/<branch>` by default) — the same layout
+     * the desktop uses, so one repository's checkouts stay grouped no matter which
+     * app created them.
+     *
+     * Absent/false → the bridge still **requires** `path`, and a client must keep
+     * deriving one itself. That fallback is worth keeping aligned with the
+     * desktop's spelling: the two derivations had already drifted into different
+     * folder names for the same repository and branch.
+     */
+    managedWorktrees?: boolean;
 }

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

@@ -15,9 +15,7 @@
  * user-pasted API keys.
  */
 /** A coding CLI whose usage we read from its own stored token. */
-export type UsageProvider = 'codex' | 'claude' | 'copilot'
-/** @deprecated Legacy read-only usage source for retired Gemini CLI installs. */
- | 'gemini' | 'grok';
+export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'grok';
 /** Outcome of reading one provider's usage. */
 export type UsageStatus = 
 /** Fresh quota/credit data was read. */

package/package.json

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