@uxnan/shared 0.0.1-alpha.20260627

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

@@ -0,0 +1,526 @@
+/**
+ * Typed registry of all JSON-RPC methods the mobile app can invoke and the
+ * bridge must implement.
+ *
+ * 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 { 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 } from '../models/workspace.js';
+import type { AuthStatus, Project } from '../models/project.js';
+import type { ApprovalResponse } from '../models/approval.js';
+import type { BridgeStatus, ConnectedPhone, TrustedDevice } from '../models/session.js';
+import type { PairingPayload } from '../e2ee/pairing-payload.js';
+import type { AgentDescriptor, AgentId, AgentModel } from '../agents/agent-capabilities.js';
+import type { PushPlatform } from '../notifications/push-payload.js';
+export interface ListThreadsParams {
+    projectId?: string;
+}
+export interface StartThreadParams {
+    projectId: string;
+    title?: string;
+    /** Agent to drive the thread (defaults to the bridge's configured default). */
+    agentId?: AgentId;
+    /** Model the agent should use (e.g. `provider/model`). */
+    model?: string;
+    /** Working directory override; defaults to the project's cwd. */
+    cwd?: string;
+}
+export interface ForkParams {
+    threadId: string;
+    newBranch?: string;
+}
+export interface TurnListParams {
+    threadId: string;
+    cursor?: string;
+    limit?: number;
+    /**
+     * When true, return the newest `limit` turns (the last page) regardless of
+     * `cursor`. Lets a client open a long thread at its most recent messages and
+     * page backward from there using `total`.
+     */
+    fromEnd?: boolean;
+}
+export interface TurnSendParams {
+    threadId: string;
+    /**
+     * User prompt text. Optional when `attachments` (an image-only message) is
+     * present; otherwise required and non-empty. The bridge rejects a turn with
+     * neither text nor attachments.
+     */
+    text?: string;
+    service?: string;
+    /**
+     * Legacy flat reasoning-effort field. Still honored; new clients should send
+     * the value under `options` (keyed by the advertised knob, e.g. `reasoning`).
+     */
+    effort?: string;
+    /**
+     * Chosen per-model run-option values, keyed by `AgentModelOption.key` (the
+     * knobs advertised on the thread's model via `agent/models`). The bridge maps
+     * each into the agent CLI's real flag; unknown keys are ignored.
+     */
+    options?: Record<string, string | boolean>;
+    /**
+     * Inline image attachments for this turn. The bridge materializes each to a
+     * temp file and references it in the prompt so any file/vision-capable agent
+     * CLI can open it. An image-only message (empty `text`) is allowed.
+     */
+    attachments?: TurnAttachment[];
+    /**
+     * Reply to a pending approval the agent requested (no new turn is created).
+     * The bridge routes the decision to the agent adapter. When present, `text`
+     * is not required.
+     */
+    approvalResponse?: ApprovalResponse;
+}
+export interface ThreadSetModelParams {
+    threadId: string;
+    model: string;
+}
+export interface ThreadRenameParams {
+    threadId: string;
+    /** New, non-empty title for the thread. */
+    title: string;
+}
+export interface ThreadSetAccessModeParams {
+    threadId: string;
+    /** The per-thread access (approval) mode to persist. */
+    mode: AccessMode;
+}
+export interface TurnSendResult {
+    turnId: string;
+}
+export interface GitCommitParams {
+    cwd: string;
+    message: string;
+    /**
+     * Repository-relative paths to stage before committing. When omitted or
+     * empty the whole working tree is staged (`git add -A`), preserving the
+     * previous behaviour. Any co-author trailer is already part of `message`.
+     */
+    paths?: string[];
+}
+export interface GitPathsParams {
+    cwd: string;
+    /** Repository-relative paths to act on. */
+    paths: string[];
+}
+export interface GitDiffParams {
+    cwd: string;
+    /** When set, returns the diff for this single file (handles untracked). */
+    path?: string;
+}
+export interface GitPrParams {
+    cwd: string;
+    title: string;
+    body?: string;
+    /** Base branch for the PR (defaults to the host's default branch). */
+    base?: string;
+    /**
+     * Head branch the PR is opened from (defaults to the current branch). The
+     * bridge pushes it to the remote before opening the PR.
+     */
+    head?: string;
+}
+export interface GitPushParams {
+    cwd: string;
+    remote: string;
+    branch: string;
+}
+export interface GitPullParams {
+    cwd: string;
+    remote?: string;
+    branch?: string;
+}
+export interface GitCheckoutParams {
+    cwd: string;
+    branch: string;
+}
+export interface GitSwitchBranchParams {
+    cwd: string;
+    /** The branch to switch to. */
+    target: string;
+    /**
+     * When true the working-tree changes follow you to the target; when false
+     * they stay on the current branch (stashed, restored on return).
+     */
+    carryChanges: boolean;
+}
+export interface GitBranchParams {
+    cwd: string;
+    name: string;
+}
+export interface GitWorktreeParams {
+    cwd: string;
+    branch: string;
+    path: string;
+    managed?: boolean;
+}
+export interface GitRevertParams {
+    cwd: string;
+    /** Commit-ish to revert (e.g. `HEAD`, a sha). Creates a new revert commit. */
+    commit: string;
+}
+export interface GitDeleteBranchParams {
+    cwd: string;
+    branch: string;
+    /**
+     * When false, git refuses to delete a branch not fully merged (`-d`); true
+     * forces it (`-D`). The phone should retry with `force: true` only after an
+     * explicit user confirmation.
+     */
+    force: boolean;
+}
+export interface GitRemoveWorktreeParams {
+    cwd: string;
+    /** The worktree's path to remove. */
+    path: string;
+    /**
+     * When false, git refuses to remove a worktree with uncommitted/untracked
+     * changes; true forces it. Confirm with the user before forcing.
+     */
+    force: boolean;
+}
+export interface WorkspaceExistsParams {
+    /** Absolute directory to probe (a thread's `cwd`). */
+    cwd: string;
+}
+export interface BrowseDirsParams {
+    /** Which configured root to browse (defaults to the first when omitted). */
+    rootId?: string;
+    /** Path relative to the root (`''` or omitted = the root itself). */
+    path?: string;
+}
+export interface CheckpointParams {
+    cwd: string;
+    threadId?: string;
+    label?: string;
+}
+export interface PatchParams {
+    cwd: string;
+    changes: PatchChange[];
+}
+export interface AgentListResult {
+    agents: AgentDescriptor[];
+}
+export interface AgentModelsParams {
+    agentId: AgentId;
+}
+export interface AgentModelsResult {
+    /** Models the agent can use, with presentation metadata, as reported by its CLI. */
+    models: AgentModel[];
+}
+/** What the phone wants to be notified about (background push). */
+export interface NotificationPreferences {
+    /** Push when an agent turn completes. */
+    turnCompleted: boolean;
+    /** Push when an agent turn errors. */
+    turnError: boolean;
+}
+export interface RegisterNotificationsParams {
+    /** FCM (Android) or APNs (iOS) device token. */
+    pushToken: string;
+    platform: PushPlatform;
+    preferences?: NotificationPreferences;
+}
+export interface RegisterNotificationsResult {
+    /** Whether the bridge accepted (and forwarded to the relay) the token. */
+    registered: boolean;
+}
+export interface UpdateNotificationsParams {
+    preferences: NotificationPreferences;
+}
+/**
+ * Maps each method name to its `params` and `result` types. Use with
+ * {@link JsonRpcMethodName} for end-to-end type-safety on both peers.
+ */
+export interface JsonRpcMethodRegistry {
+    'thread/list': {
+        params: ListThreadsParams;
+        result: ThreadList;
+    };
+    'thread/read': {
+        params: {
+            threadId: string;
+        };
+        result: Thread;
+    };
+    'thread/start': {
+        params: StartThreadParams;
+        result: Thread;
+    };
+    'thread/resume': {
+        params: {
+            threadId: string;
+        };
+        result: void;
+    };
+    'thread/fork': {
+        params: ForkParams;
+        result: Thread;
+    };
+    'thread/setModel': {
+        params: ThreadSetModelParams;
+        result: void;
+    };
+    'thread/rename': {
+        params: ThreadRenameParams;
+        result: Thread;
+    };
+    'thread/setAccessMode': {
+        params: ThreadSetAccessModeParams;
+        result: Thread;
+    };
+    'thread/archive': {
+        params: {
+            threadId: string;
+        };
+        result: Thread;
+    };
+    'thread/unarchive': {
+        params: {
+            threadId: string;
+        };
+        result: Thread;
+    };
+    'thread/delete': {
+        params: {
+            threadId: string;
+        };
+        result: void;
+    };
+    'turn/list': {
+        params: TurnListParams;
+        result: TurnList;
+    };
+    'turn/read': {
+        params: {
+            turnId: string;
+        };
+        result: Turn;
+    };
+    'turn/send': {
+        params: TurnSendParams;
+        result: TurnSendResult;
+    };
+    'turn/cancel': {
+        params: {
+            threadId: string;
+            turnId: string;
+        };
+        result: void;
+    };
+    'git/status': {
+        params: {
+            cwd: string;
+        };
+        result: GitRepoStatus;
+    };
+    'git/diff': {
+        params: GitDiffParams;
+        result: GitDiff;
+    };
+    'git/commit': {
+        params: GitCommitParams;
+        result: GitCommitResult;
+    };
+    'git/push': {
+        params: GitPushParams;
+        result: GitPushResult;
+    };
+    'git/pull': {
+        params: GitPullParams;
+        result: GitPullResult;
+    };
+    'git/checkout': {
+        params: GitCheckoutParams;
+        result: void;
+    };
+    'git/createBranch': {
+        params: GitBranchParams;
+        result: GitBranchResult;
+    };
+    'git/createWorktree': {
+        params: GitWorktreeParams;
+        result: GitWorktreeResult;
+    };
+    'git/stage': {
+        params: GitPathsParams;
+        result: void;
+    };
+    'git/unstage': {
+        params: GitPathsParams;
+        result: void;
+    };
+    'git/discard': {
+        params: GitPathsParams;
+        result: void;
+    };
+    'git/createPr': {
+        params: GitPrParams;
+        result: GitPrResult;
+    };
+    'git/undoCommit': {
+        params: {
+            cwd: string;
+        };
+        result: void;
+    };
+    'git/branches': {
+        params: {
+            cwd: string;
+        };
+        result: GitBranchList;
+    };
+    'git/switchBranch': {
+        params: GitSwitchBranchParams;
+        result: void;
+    };
+    'git/revert': {
+        params: GitRevertParams;
+        result: void;
+    };
+    'git/deleteBranch': {
+        params: GitDeleteBranchParams;
+        result: void;
+    };
+    'git/removeWorktree': {
+        params: GitRemoveWorktreeParams;
+        result: void;
+    };
+    'git/log': {
+        params: GitLogParams;
+        result: GitLogResult;
+    };
+    'git/commitShow': {
+        params: GitCommitShowParams;
+        result: GitCommitDetails;
+    };
+    'workspace/readFile': {
+        params: {
+            cwd: string;
+            path: string;
+        };
+        result: FileContent;
+    };
+    'workspace/readImage': {
+        params: {
+            cwd: string;
+            path: string;
+        };
+        result: ImageContent;
+    };
+    'workspace/list': {
+        params: {
+            cwd: string;
+        };
+        result: WorkspaceListing;
+    };
+    'workspace/browseDirs': {
+        params: BrowseDirsParams;
+        result: BrowseResult;
+    };
+    'workspace/checkpoint': {
+        params: CheckpointParams;
+        result: Checkpoint;
+    };
+    'workspace/diffCheckpoint': {
+        params: {
+            id: string;
+        };
+        result: CheckpointDiff;
+    };
+    'workspace/applyCheckpoint': {
+        params: {
+            id: string;
+        };
+        result: void;
+    };
+    'workspace/applyPatch': {
+        params: PatchParams;
+        result: ApplyResult;
+    };
+    'workspace/exists': {
+        params: WorkspaceExistsParams;
+        result: WorkspaceExistsResult;
+    };
+    'project/list': {
+        params: void;
+        result: Project[];
+    };
+    'project/resolve': {
+        params: {
+            cwd: string;
+        };
+        result: Project;
+    };
+    'agent/list': {
+        params: void;
+        result: AgentListResult;
+    };
+    'agent/models': {
+        params: AgentModelsParams;
+        result: AgentModelsResult;
+    };
+    'auth/status': {
+        params: {
+            agentId: AgentId;
+        };
+        result: AuthStatus;
+    };
+    'auth/login': {
+        params: {
+            provider: string;
+        };
+        result: void;
+    };
+    'auth/logout': {
+        params: void;
+        result: void;
+    };
+    'notifications/register': {
+        params: RegisterNotificationsParams;
+        result: RegisterNotificationsResult;
+    };
+    'notifications/update': {
+        params: UpdateNotificationsParams;
+        result: void;
+    };
+    'notifications/unregister': {
+        params: void;
+        result: void;
+    };
+    'bridge/status': {
+        params: void;
+        result: BridgeStatus;
+    };
+    'bridge/generatePairingQr': {
+        params: void;
+        result: PairingPayload;
+    };
+    'bridge/connectedPhones': {
+        params: void;
+        result: ConnectedPhone[];
+    };
+    'bridge/disconnectPhone': {
+        params: {
+            deviceId: string;
+        };
+        result: void;
+    };
+    'bridge/trustedDevices': {
+        params: void;
+        result: TrustedDevice[];
+    };
+    'bridge/removeTrustedDevice': {
+        params: {
+            deviceId: string;
+        };
+        result: void;
+    };
+}
+export type JsonRpcMethodName = keyof JsonRpcMethodRegistry;
+export type MethodParams<M extends JsonRpcMethodName> = JsonRpcMethodRegistry[M]['params'];
+export type MethodResult<M extends JsonRpcMethodName> = JsonRpcMethodRegistry[M]['result'];

package/dist/src/jsonrpc/methods.js

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

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

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

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

@@ -0,0 +1,85 @@
+/**
+ * Bridge → phone streaming notifications (JSON-RPC notifications, no `id`).
+ *
+ * Source: architecture/02b-contracts-and-requirements.md (streaming events).
+ */
+export declare const StreamNotification: {
+    readonly TurnStarted: "stream/turn/started";
+    readonly MessageDelta: "stream/message/delta";
+    /** A chunk of the agent's reasoning / "thinking" for this turn (`data.delta`). */
+    readonly ThinkingDelta: "stream/thinking/delta";
+    /** A structured content block (command/diff/tool) the agent produced this turn. */
+    readonly ContentBlock: "stream/content/block";
+    readonly TurnCompleted: "stream/turn/completed";
+    readonly TurnError: "stream/turn/error";
+    readonly TurnAborted: "stream/turn/aborted";
+    /** The agent resolved an alias (e.g. `opus`) to a concrete model id for this turn. */
+    readonly ModelResolved: "stream/model/resolved";
+};
+export type StreamNotification = (typeof StreamNotification)[keyof typeof StreamNotification];
+export interface TurnStartedParams {
+    threadId: string;
+    turnId: string;
+}
+export interface MessageDeltaParams {
+    threadId: string;
+    turnId: string;
+    messageId: string;
+    delta: string;
+}
+/** A chunk of the agent's reasoning ("thinking") for a turn. */
+export interface ThinkingDeltaParams {
+    threadId: string;
+    turnId: string;
+    messageId: string;
+    delta: string;
+}
+/**
+ * A structured content block (a serialized MessageContent: `command_execution`,
+ * `diff`, `tool`, …) the agent produced during a turn. The phone decodes
+ * `content` straight into a MessageContent and folds it into the streaming
+ * message (Work log / Changed files).
+ */
+export interface ContentBlockParams {
+    threadId: string;
+    turnId: string;
+    messageId: string;
+    content: unknown;
+}
+/**
+ * Token usage for a completed turn, as reported by the agent's CLI.
+ * `tokens` is the context the conversation now occupies (≈ the latest turn's
+ * input + the output it produced). `contextWindow` is the model's limit when
+ * known (Claude tiers); omitted when the CLI doesn't expose it (Codex), in
+ * which case the phone shows the raw token count instead of a percentage.
+ */
+export interface TurnUsage {
+    tokens: number;
+    contextWindow?: number;
+}
+export interface TurnCompletedParams {
+    threadId: string;
+    turnId: string;
+    messageId: string;
+    text: string;
+    /** Token usage for this turn, when the agent reported it. */
+    usage?: TurnUsage;
+}
+export interface TurnErrorParams {
+    threadId: string;
+    turnId: string;
+    error: {
+        code: number;
+        message: string;
+    };
+}
+export interface TurnAbortedParams {
+    threadId: string;
+    turnId: string;
+}
+export interface ModelResolvedParams {
+    threadId: string;
+    turnId: string;
+    /** Concrete model id the agent resolved for this turn (e.g. `claude-opus-4-8`). */
+    model: string;
+}

package/dist/src/jsonrpc/notifications.js

@@ -0,0 +1,19 @@
+/**
+ * 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',
+    /** A chunk of the agent's reasoning / "thinking" for this turn (`data.delta`). */
+    ThinkingDelta: 'stream/thinking/delta',
+    /** A structured content block (command/diff/tool) the agent produced this turn. */
+    ContentBlock: 'stream/content/block',
+    TurnCompleted: 'stream/turn/completed',
+    TurnError: 'stream/turn/error',
+    TurnAborted: 'stream/turn/aborted',
+    /** The agent resolved an alias (e.g. `opus`) to a concrete model id for this turn. */
+    ModelResolved: 'stream/model/resolved',
+};
+//# sourceMappingURL=notifications.js.map

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

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

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

@@ -0,0 +1,37 @@
+/**
+ * Interactive approval contracts.
+ *
+ * An agent that needs the user to authorize an action emits an `approval`
+ * content block (on `stream/content/block`); the phone renders an interactive
+ * card and replies via `turn/send { approvalResponse }`. The bridge routes the
+ * decision back to the agent adapter.
+ *
+ * Source: architecture/02a-system-architecture.md §6.2.
+ */
+/** Risk level the agent assigns to an action awaiting approval. */
+export type ApprovalRisk = 'low' | 'medium' | 'high' | 'unknown';
+/** The user's decision for a pending approval. */
+export type ApprovalDecision = 'approve' | 'reject' | 'approveSession';
+/** The user's reply to a pending approval, carried on `turn/send`. */
+export interface ApprovalResponse {
+    /** The id from the approval request the user is answering. */
+    approvalId: string;
+    /** Allow once, deny, or allow for the rest of the session. */
+    decision: ApprovalDecision;
+}
+/**
+ * Payload of an `approval` content block. The phone decodes this straight into
+ * its interactive approval card (it is also tolerant of a nested
+ * `{ type:'approval', request:{...} }` form).
+ */
+export interface ApprovalRequestBlock {
+    type: 'approval';
+    /** Bridge id the phone echoes back in `approvalResponse.approvalId`. */
+    approvalId: string;
+    /** Human description of what the agent wants to do. */
+    action: string;
+    /** Risk level (defaults to `unknown` on the phone if omitted). */
+    risk?: ApprovalRisk;
+    /** Optional extra detail (e.g. the command or affected paths). */
+    detail?: string;
+}

package/dist/src/models/approval.js

@@ -0,0 +1,12 @@
+/**
+ * Interactive approval contracts.
+ *
+ * An agent that needs the user to authorize an action emits an `approval`
+ * content block (on `stream/content/block`); the phone renders an interactive
+ * card and replies via `turn/send { approvalResponse }`. The bridge routes the
+ * decision back to the agent adapter.
+ *
+ * Source: architecture/02a-system-architecture.md §6.2.
+ */
+export {};
+//# sourceMappingURL=approval.js.map

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

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