@uxnan/shared 0.0.15-alpha.20260813 → 0.0.17-alpha.20260926

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

@@ -0,0 +1,88 @@
+/**
+ * Replica sync: how a client converges on the bridge's shared state without
+ * trusting that it saw every notification (architecture/02a §5.8.17).
+ *
+ * The bridge numbers every change to shared state — a thread, a project, the
+ * shared settings — with one global, persisted, strictly increasing **revision**
+ * (`rev`), and keeps a bounded list of deletions. A client remembers the last
+ * `rev` it applied and asks `sync/changes { since }`:
+ *
+ * - on every (re)connect and app resume;
+ * - whenever a notification carries a `rev` that is not `last + 1` (it missed
+ *   something in between).
+ *
+ * The answer is either the changes after `since` or, when the client cannot be
+ * served incrementally (`storeId` differs — a new state directory — or `since`
+ * predates the deletions the bridge still remembers), a full snapshot with
+ * `reset: true` that the client applies by replacing its replica.
+ */
+import type { Project } from './project.js';
+import type { Thread } from './thread.js';
+import type { TrustedDevice } from './session.js';
+/**
+ * Settings the bridge shares with every client, editable from any of them
+ * (`settings/set`) and from its own CLI (`uxnan-bridge config set`).
+ */
+export interface BridgeSettings {
+    /**
+     * The folder the bridge starts from, whatever directory `start` ran in: where
+     * exploring for a new project begins, and the boundary a phone may register
+     * projects under. Defaults to the user's home directory.
+     */
+    home: string;
+    /**
+     * What every client calls this PC. Defaults to the machine's own name; any
+     * client, or `uxnan-bridge config set name`, can change it.
+     */
+    name: string;
+}
+export interface SettingsSetParams {
+    /** New start folder: an absolute path to an existing directory. */
+    home?: string;
+    /** New name for this PC; empty goes back to the machine's own name. */
+    name?: string;
+    /**
+     * See `ActionAgeMs`: a change made offline and sent now, applied to each
+     * setting only if nobody changed that setting later.
+     */
+    ageMs?: number;
+}
+export interface SyncChangesParams {
+    /** The last revision this client applied; absent on a first sync. */
+    since?: number;
+    /** The `storeId` that revision belongs to; a different one forces a reset. */
+    storeId?: string;
+}
+/** What kind of client is connected. */
+export type ClientKind = 'phone' | 'desktop';
+/** One client connected to the bridge right now. */
+export interface ClientPresence {
+    /** Stable id: the phone's device id, or `local:<client>` for the desktop. */
+    id: string;
+    kind: ClientKind;
+    /** Human name (the phone's device name, the desktop's machine name). */
+    name: string;
+    /** When this connection opened (epoch ms). */
+    since: number;
+}
+export interface SyncChanges {
+    /** Identity of the bridge's state directory; changes only if it is recreated. */
+    storeId: string;
+    /** The revision this answer brings the client up to. */
+    rev: number;
+    /** True → a full snapshot: replace the replica instead of merging. */
+    reset: boolean;
+    settings: BridgeSettings;
+    /** Projects changed after `since` (all of them on a reset). */
+    projects: Project[];
+    /** Projects removed after `since` (empty on a reset). */
+    removedProjectIds: string[];
+    /** Threads changed after `since` (all of them on a reset). */
+    threads: Thread[];
+    /** Threads deleted after `since` (empty on a reset). */
+    removedThreadIds: string[];
+    /** Who is connected right now (live, not revisioned). */
+    clients: ClientPresence[];
+    /** Every paired phone, as it stands (small; always whole). */
+    devices: TrustedDevice[];
+}

package/dist/src/models/sync.js

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

package/dist/src/models/sync.js.map

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

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

@@ -70,6 +70,13 @@ export interface Message {
 export interface Turn {
     id: string;
     threadId: string;
+    /**
+     * The turn's position in its thread (1-based, assigned by the bridge when the
+     * turn is stored, never reused). Clients order a conversation by it — never by
+     * the order notifications happened to arrive — so a turn a client missed and
+     * fetched later still lands in its place. Absent on an older bridge.
+     */
+    seq?: number;
     status: TurnStatus;
     messages: Message[];
     createdAt: number;
@@ -112,6 +119,14 @@ export interface Thread {
     agentSessionId?: string;
     /** Per-thread access (approval) mode; see {@link AccessMode}. */
     accessMode?: AccessMode;
+    /**
+     * Live, never persisted: the turn running on this thread right now, set by
+     * the bridge on `thread/list` and `thread/read` responses (the same value as
+     * `TurnList.activeTurnId`). Lets a client that just connected show which
+     * conversations are working without reading each one's turns. Absent when
+     * nothing runs.
+     */
+    activeTurnId?: string;
     /**
      * Where {@link title} came from, so a better title can replace a weaker one
      * without ever overwriting a name the **user** chose.
@@ -126,6 +141,16 @@ export interface Thread {
      * is what they are.
      */
     titleSource?: ThreadTitleSource;
+    /** Which client started the conversation, when known. */
+    origin?: ThreadOrigin;
+    /** Sync revision of the thread's last change (see `SyncChanges`). */
+    rev?: number;
+}
+/** Where a conversation was started. */
+export interface ThreadOrigin {
+    kind: 'phone' | 'desktop';
+    /** The device's or machine's name. */
+    name: string;
 }
 /** Where a thread's title came from. See {@link Thread.titleSource}. */
 export type ThreadTitleSource = 'prompt' | 'agent' | 'user';

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

@@ -0,0 +1,68 @@
+/**
+ * What a tool call did, in one vocabulary shared by every agent. Each agent
+ * names its tools its own way (`Read`, `read_file`, `view_file`, an ACP
+ * `kind`, a Codex item type…); the bridge classifies them once, so a client
+ * says "Read notes.txt" for all of them instead of learning every CLI.
+ *
+ *  - `read`: read a file or an image
+ *  - `search`: search file contents or names (grep, glob, find)
+ *  - `list`: list a folder
+ *  - `fetch`: fetch a URL
+ *  - `web_search`: search the web
+ *  - `mcp`: a tool of an MCP server
+ *  - `other`: anything else — clients show the tool's name
+ */
+export type ToolKind = 'read' | 'search' | 'list' | 'fetch' | 'web_search' | 'mcp' | 'other';
+/** Every {@link ToolKind}, for validators and exhaustive checks. */
+export declare const TOOL_KINDS: readonly ToolKind[];
+/**
+ * A step shown while it runs. Any structured block may carry a `blockId`, the
+ * id of the step it stands for: a later block of the **same turn** with the
+ * same `blockId` replaces it in place — in the bridge's store and in every
+ * client's live view — so a step appears as it starts (`status: 'running'`,
+ * or `state.status: 'running'` for a subagent) and settles into its result
+ * where it stood. Once the turn ends a step is never running: the bridge
+ * settles any the agent left open, and a client treats a running step of a
+ * turn that is no longer live as settled.
+ */
+export interface LiveBlock {
+    blockId?: string;
+}
+/**
+ * A tool call that is not a shell command, an edit, a plan or a subagent,
+ * as a `stream/content/block` (persisted with the assistant message).
+ */
+export interface ToolContentBlock extends LiveBlock {
+    type: 'tool';
+    /** The agent's own name for the tool (`Read`, `grep`, `server/tool`…). */
+    toolName: string;
+    toolId: string;
+    input: Record<string, unknown>;
+    output?: string;
+    isError: boolean;
+    /** `running` while the call is in flight (see {@link LiveBlock}); absent once it finished. */
+    status?: 'running';
+    /** What the call did, classified by the bridge. */
+    kind: ToolKind;
+    /**
+     * What it acted on, ready to show: a path (relative to the project when it
+     * is inside it), a search pattern, a URL, a query. Absent when there is none.
+     */
+    target?: string;
+}
+/**
+ * A subagent the agent delegated to (Claude's `Agent`, OpenCode's `task`,
+ * Codex's collaboration tools, Antigravity's subagents): running, then
+ * finished with its report.
+ */
+export interface SubagentContentBlock extends LiveBlock {
+    type: 'subagent';
+    state: {
+        id: string;
+        /** What the subagent was asked to do, in a few words. */
+        name: string;
+        status: 'running' | 'completed' | 'error';
+        /** Its final report, truncated for the wire. */
+        output?: string;
+    };
+}

package/dist/src/models/tool.js

@@ -0,0 +1,11 @@
+/** Every {@link ToolKind}, for validators and exhaustive checks. */
+export const TOOL_KINDS = [
+    'read',
+    'search',
+    'list',
+    'fetch',
+    'web_search',
+    'mcp',
+    'other',
+];
+//# sourceMappingURL=tool.js.map

package/dist/src/models/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../src/models/tool.ts"],"names":[],"mappings":"AAgBA,oEAAoE;AACpE,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C,MAAM;IACN,QAAQ;IACR,MAAM;IACN,OAAO;IACP,YAAY;IACZ,KAAK;IACL,OAAO;CACR,CAAC"}

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

@@ -11,8 +11,11 @@
  * over `agent/usageStats`. The Dart equivalents live in uxnanmobile and are kept
  * in sync manually (see 02e-bridge-integration.md §4.2).
  *
- * Posture: only the CLI's own stored token is read — never browser cookies or
- * user-pasted API keys.
+ * Posture: only the token the CLI itself stored is read — from its file, or
+ * from the OS credential store where that is where the CLI keeps it (Claude
+ * Code on macOS), and then only after the user has granted the OS-level
+ * permission once (see `accessRequired`). Never browser cookies, never
+ * user-pasted API keys, never a refresh token.
  */
 /** A coding CLI whose usage we read from its own stored token. */
 export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'grok';
@@ -22,6 +25,11 @@ export type UsageStatus =
 'ok'
 /** CLI is present but not signed in (no usable token). */
  | 'authRequired'
+/** The CLI's token exists in the OS credential store, but the OS has not yet
+ *  authorized the reader to open it. The user grants that once from the
+ *  desktop's Providers panel (the OS shows its own dialog); the reader never
+ *  prompts on its own. A phone shows "grant access on the PC". */
+ | 'accessRequired'
 /** CLI / its config directory is not present on this machine. */
  | 'notInstalled'
 /** Read/network/parse failure — see {@link ProviderUsage.message}. */
@@ -121,7 +129,8 @@ export interface ProviderUsage {
     resetCredits?: ResetCredits;
     /** When this snapshot was produced (epoch ms). */
     updatedAt: number;
-    /** Error/hint message for `error` / `authRequired` / `notInstalled` states. */
+    /** Error/hint message for `error` / `authRequired` / `accessRequired` /
+     *  `notInstalled` states. */
     message?: string;
 }
 /**

package/dist/src/models/usage.js

@@ -11,8 +11,11 @@
  * over `agent/usageStats`. The Dart equivalents live in uxnanmobile and are kept
  * in sync manually (see 02e-bridge-integration.md §4.2).
  *
- * Posture: only the CLI's own stored token is read — never browser cookies or
- * user-pasted API keys.
+ * Posture: only the token the CLI itself stored is read — from its file, or
+ * from the OS credential store where that is where the CLI keeps it (Claude
+ * Code on macOS), and then only after the user has granted the OS-level
+ * permission once (see `accessRequired`). Never browser cookies, never
+ * user-pasted API keys, never a refresh token.
  */
 export {};
 //# sourceMappingURL=usage.js.map

package/dist/src/models/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/models/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/models/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxnan/shared",
-  "version": "0.0.15-alpha.20260813",
+  "version": "0.0.17-alpha.20260926",
   "description": "Shared JSON-RPC and E2EE contracts for the Uxnan ecosystem (bridge, relay, mobile).",
   "license": "MPL-2.0",
   "author": "Luis Donaldo Gamas Vazquez",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist/src"
+    "dist/src",
+    "agent-locations.json"
   ],
   "engines": {
     "node": ">=18"