@uxnan/shared 0.0.4-alpha.20260703 → 0.0.6-alpha.20260716

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 — **61 JSON-RPC methods** + **8 streaming
+> **Status:** implemented and stable — **66 JSON-RPC methods** + **8 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
@@ -52,7 +52,7 @@ flowchart TB
 | JSON-RPC | envelope types + constructors (`makeRequest`, `makeNotification`, `makeResponse`, `makeErrorResponse`), error codes (`JsonRpcErrorCode` + Uxnan-specific `-32000..-32008`), `RpcError`, typed method registry (`JsonRpcMethodRegistry` + `METHOD_NAMES`), `isKnownMethod` |
 | Streaming | `StreamNotification` enum + param types (`TurnStartedParams`, `MessageDeltaParams`, `ThinkingDeltaParams`, `ContentBlockParams`, `TurnCompletedParams`, `TurnUsage`, `TurnErrorParams`, `TurnAbortedParams`, `ModelResolvedParams`) |
 | 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), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), approval |
+| Models | thread / turn / message (with `MessageContent` polymorphic blocks), git, workspace (incl. `browseDirs` + `exists`), project, auth, session/trust (`BridgeStatus` incl. `latestVersion?`/`updateAvailable?`), 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`), `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

@@ -3,7 +3,7 @@
  *
  * Source: architecture/02a-system-architecture.md §5.8.2 (adapters/base-adapter).
  */
-import type { AgentCapabilities, AgentId, AgentModel } from './agent-capabilities.js';
+import type { AgentCapabilities, AgentCommand, AgentCommandInvocation, AgentId, AgentModel } from './agent-capabilities.js';
 import type { AgentConfig } from './agent-config.js';
 import type { TurnAttachment } from '../models/workspace.js';
 import type { ApprovalDecision } from '../models/approval.js';
@@ -52,6 +52,15 @@ export interface SendTurnOptions {
      * configured default posture (no behaviour change).
      */
     accessMode?: AccessMode;
+    /**
+     * Invoke an advertised agent command (from `agent/commands`) instead of
+     * free-form {@link text}. The {@link AgentManager} resolves it before the
+     * adapter runs — expanding a custom prompt-template via {@link
+     * IAgentAdapter.expandCommand}, or composing the CLI's native `/name args`
+     * form — and sets {@link text} to the result, so most adapters need no
+     * per-command handling. Absent for an ordinary text turn.
+     */
+    command?: AgentCommandInvocation;
 }
 export interface IAgentAdapter {
     readonly agentId: AgentId;
@@ -75,4 +84,23 @@ export interface IAgentAdapter {
     onEvent(listener: (event: AgentStreamEvent) => void): () => void;
     /** List the models this agent's CLI reports as available (optional). */
     listModels?(): Promise<AgentModel[]>;
+    /**
+     * List the special ("slash") commands this agent exposes — control commands
+     * 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
+     * ones. Discovery only; invocation flows through {@link sendTurn} with {@link
+     * SendTurnOptions.command}.
+     */
+    listCommands?(cwd?: string): Promise<AgentCommand[]>;
+    /**
+     * 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
+     * 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.
+     */
+    expandCommand?(name: string, args?: string, cwd?: string): Promise<string>;
 }

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

@@ -3,7 +3,11 @@
  *
  * Source: architecture/02a-system-architecture.md §5.8.2 (adapters).
  */
-export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli' | 'pi-agent' | 'aider'
+export type AgentId = 'codex' | 'opencode' | 'claude-code' | 'gemini-cli' | 'pi-agent'
+/** Zero — open-source Go coding agent, driven over the Agent Client Protocol. */
+ | 'zero'
+/** Grok — xAI's coding CLI, driven over the Agent Client Protocol (`grok agent stdio`). */
+ | 'grok'
 /** Built-in reference/dev agent that echoes the prompt (no external CLI). */
  | 'echo';
 export interface AgentCapabilities {
@@ -24,6 +28,21 @@ export interface AgentCapabilities {
      * OpenCode) and the meter stays hidden.
      */
     reportsContextUsage?: boolean;
+    /**
+     * Agent runs in autonomous ("YOLO") mode by default — it acts and edits
+     * without per-action approval prompts because its headless CLI exposes no
+     * pre-tool approval channel. The phone surfaces this so the user knows Pi
+     * (and any such agent) will not ask before running tools. Optional; absent/
+     * false means the agent either gates tools or is pending approval wiring.
+     */
+    autonomous?: boolean;
+    /**
+     * Agent exposes special ("slash") commands the phone can discover via
+     * `agent/commands` and invoke through `turn/send` `command`. Optional for
+     * back-compat; absent/false means the agent advertises none (the phone shows
+     * only its client-side `/` palette). See {@link AgentCommand}.
+     */
+    commands?: boolean;
 }
 /**
  * A registered agent the phone can pick for a thread, returned by `agent/list`.
@@ -112,3 +131,52 @@ export interface AgentModel {
      */
     isLatestAlias?: boolean;
 }
+/**
+ * A special ("slash") command an agent exposes, returned by `agent/commands`.
+ *
+ * Two kinds are unified under this one shape:
+ * - **control** commands the CLI understands in its headless/programmatic mode
+ *   (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
+ *   expands itself before running a normal turn.
+ *
+ * The phone is a generic renderer: it lists the advertised commands in its `/`
+ * palette and, when one is picked, echoes it back on `turn/send` under
+ * {@link AgentCommandInvocation} — the bridge resolves it to the final prompt
+ * text (expanded template) or the CLI's native `/name args` form. Consumers MUST
+ * tolerate absent optional fields so a newer bridge advertising a richer command
+ * never breaks an older app.
+ */
+export interface AgentCommand {
+    /** Command name WITHOUT the leading slash (e.g. `compact`, `refactor`). */
+    name: string;
+    /** One-line description for the palette, when the source provides one. */
+    description?: string;
+    /** Hint for the arguments the command accepts (e.g. `<file> <priority>`). */
+    argumentHint?: string;
+    /**
+     * Where the command comes from: `acp` (advertised by an ACP agent),
+     * `builtin` (a CLI control command reachable headless), or `custom` (a
+     * user-defined prompt-template file the bridge expands).
+     */
+    source: 'acp' | 'builtin' | 'custom';
+    /**
+     * Whether the command actually runs in the agent's headless/programmatic mode.
+     * Absent/true means yes; `false` marks a command that only works in the CLI's
+     * interactive TUI, which the phone should hide. The bridge only advertises
+     * commands it can run, so this is a belt-and-suspenders gate.
+     */
+    headlessSupported?: boolean;
+}
+/**
+ * A picked {@link AgentCommand} carried on `turn/send` under `command`, instead
+ * of free-form `text`. The bridge resolves `{ name, args }` to the final prompt.
+ */
+export interface AgentCommandInvocation {
+    /** The command's {@link AgentCommand.name} (no leading slash). */
+    name: string;
+    /** Raw argument string the user appended after the command, if any. */
+    args?: string;
+}

package/dist/src/index.d.ts

@@ -22,5 +22,8 @@ export * from './models/workspace.js';
 export * from './models/project.js';
 export * from './models/session.js';
 export * from './models/approval.js';
+export * from './models/question.js';
+export * from './models/usage.js';
+export * from './models/metrics.js';
 export * from './validators/validate.js';
 export * from './validators/json-schema/schemas.js';

package/dist/src/index.js

@@ -28,6 +28,9 @@ export * from './models/workspace.js';
 export * from './models/project.js';
 export * from './models/session.js';
 export * from './models/approval.js';
+export * from './models/question.js';
+export * from './models/usage.js';
+export * from './models/metrics.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;AAE1C,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,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAErC,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;AAE1C,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,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AAEpC,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,qCAAqC,CAAC"}

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", "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/browseDirs", "workspace/checkpoint", "workspace/diffCheckpoint", "workspace/applyCheckpoint", "workspace/applyPatch", "workspace/exists", "project/list", "project/resolve", "agent/list", "agent/models", "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", "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/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

@@ -53,6 +53,12 @@ export const METHOD_NAMES = [
     // Agents
     'agent/list',
     'agent/models',
+    'agent/commands',
+    'agent/usageStats',
+    // Metrics (bridge-owned, survivable profile stats + tamper-proof backup)
+    'metrics/get',
+    'metrics/export',
+    'metrics/import',
     // Auth
     'auth/status',
     'auth/login',

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,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,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,sBAAsB;IACtB,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,iBAAiB;IACjB,SAAS;IACT,YAAY;IACZ,cAAc;IACd,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,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,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

@@ -10,9 +10,12 @@ import type { GitBranchList, GitBranchResult, GitCommitDetails, GitCommitResult,
 import type { ApplyResult, BrowseResult, Checkpoint, CheckpointDiff, FileContent, ImageContent, PatchChange, TurnAttachment, WorkspaceExistsResult, WorkspaceListing, SearchFilesParams, WorkspaceSearchResult } from '../models/workspace.js';
 import type { AuthStatus, Project } from '../models/project.js';
 import type { ApprovalResponse } from '../models/approval.js';
+import type { QuestionResponse } from '../models/question.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 { AgentCommand, AgentCommandInvocation, AgentDescriptor, AgentId, AgentModel } from '../agents/agent-capabilities.js';
+import type { UsageStatsParams, UsageStatsResult } from '../models/usage.js';
+import type { MetricsExportParams, MetricsExportResult, MetricsImportParams, MetricsImportResult, MetricsSnapshot } from '../models/metrics.js';
 import type { PushPlatform } from '../notifications/push-payload.js';
 export interface ListThreadsParams {
     projectId?: string;
@@ -74,6 +77,20 @@ export interface TurnSendParams {
      * is not required.
      */
     approvalResponse?: ApprovalResponse;
+    /**
+     * Reply to a pending question the agent asked (no new turn is created). The
+     * bridge routes the chosen answers to the agent adapter. When present, `text`
+     * is not required.
+     */
+    questionResponse?: QuestionResponse;
+    /**
+     * Invoke an advertised agent command (from `agent/commands`) instead of
+     * free-form `text`. The bridge resolves `{ name, args }` to the final prompt —
+     * expanding a custom prompt-template file, or composing the CLI's native
+     * `/name args` form — then runs a normal turn. When present, `text` is not
+     * required.
+     */
+    command?: AgentCommandInvocation;
 }
 export interface ThreadSetModelParams {
     threadId: string;
@@ -212,6 +229,19 @@ export interface AgentModelsResult {
     /** Models the agent can use, with presentation metadata, as reported by its CLI. */
     models: AgentModel[];
 }
+export interface AgentCommandsParams {
+    agentId: AgentId;
+    /**
+     * Thread/project directory, so project-scoped custom commands (e.g.
+     * `<cwd>/.claude/commands`, `<cwd>/.gemini/commands`) are discovered alongside
+     * the user-level ones. Omitted → only user-level commands are returned.
+     */
+    cwd?: string;
+}
+export interface AgentCommandsResult {
+    /** Special ("slash") commands the agent exposes, discovered from its CLI/disk. */
+    commands: AgentCommand[];
+}
 /** What the phone wants to be notified about (background push). */
 export interface NotificationPreferences {
     /** Push when an agent turn completes. */
@@ -468,6 +498,26 @@ export interface JsonRpcMethodRegistry {
         params: AgentModelsParams;
         result: AgentModelsResult;
     };
+    'agent/commands': {
+        params: AgentCommandsParams;
+        result: AgentCommandsResult;
+    };
+    'agent/usageStats': {
+        params: UsageStatsParams;
+        result: UsageStatsResult;
+    };
+    'metrics/get': {
+        params: void;
+        result: MetricsSnapshot;
+    };
+    'metrics/export': {
+        params: MetricsExportParams;
+        result: MetricsExportResult;
+    };
+    'metrics/import': {
+        params: MetricsImportParams;
+        result: MetricsImportResult;
+    };
     'auth/status': {
         params: {
             agentId: AgentId;

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

@@ -0,0 +1,162 @@
+/**
+ * Profile metrics — a bridge-owned, survivable tally of a PC's activity, plus a
+ * tamper-proof export/import backup.
+ *
+ * The mobile profile screen shows aggregated metrics (conversations, messages,
+ * agents/models used, connection time, git actions, an activity heatmap). Those
+ * were derived on the phone from local storage and so were lost on an app
+ * uninstall (the app has no cloud login). To make them durable, the **bridge**
+ * becomes the source of truth: it computes them from its own authoritative data
+ * (the conversation store) plus persisted session + git-action event logs it
+ * observes itself, and serves them over `metrics/get`. The phone renders one
+ * snapshot per PC and sums across PCs.
+ *
+ * A `metrics/export` produces an opaque, tamper-proof file only the SAME bridge
+ * can later verify + decrypt (AES-256-GCM under a secret held in the PC's OS
+ * keychain), so users cannot fabricate or edit their stats; `metrics/import`
+ * feeds one back and merges its events by id (idempotent).
+ *
+ * Provider usage/credits are deliberately NOT part of this — those are read live
+ * via `agent/usageStats` and never persisted.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.11 and
+ * 02b-contracts-and-requirements.md.
+ */
+/** Transport a phone→PC connection session used. */
+export type MetricsTransport = 'relay' | 'direct';
+/** Per-agent conversation tally (most-used first). */
+export interface MetricsAgentUsage {
+    /** Agent wire id (e.g. `claude-code`, `codex`). */
+    agentId: string;
+    /** Conversations started with this agent on this PC. */
+    conversations: number;
+}
+/** One agent's activity on a given day (drives the per-agent bars). */
+export interface MetricsAgentDay {
+    /** Agent wire id (e.g. `claude-code`, `codex`). */
+    agentId: string;
+    /** Conversations (threads) this agent started that day. */
+    conversations: number;
+    /** Messages exchanged that day in this agent's threads. */
+    messages: number;
+    /**
+     * Tokens processed that day — the sum of each turn's reported usage (input
+     * incl. the re-sent context + output). **Throughput, not billed cost**: caching
+     * and input/output pricing differ (use `agent/usageStats` for money). 0 for
+     * agents that don't report usage (e.g. Zero).
+     */
+    tokens: number;
+}
+/** One calendar day's activity split per agent. */
+export interface MetricsDayBreakdown {
+    /** UTC-midnight epoch ms of the calendar date (same encoding as `activity`). */
+    day: number;
+    /** Per-agent activity that day (agents with any conversation/message/token). */
+    byAgent: MetricsAgentDay[];
+}
+/**
+ * One local calendar-day activity bucket. Counts are split by category so a
+ * client can render any metric filter (combined / conversations / messages /
+ * work) with no extra round-trip. Days with no activity are omitted.
+ */
+export interface MetricsActivityDay {
+    /**
+     * The calendar date this bucket covers, as **UTC-midnight epoch ms** of the
+     * bridge host's local date. Encoding the local date at UTC midnight (not the
+     * local-midnight instant) makes the key timezone-stable, so a phone in any
+     * timezone maps it to the correct heatmap cell.
+     */
+    day: number;
+    /** Conversations started that day. */
+    conversations: number;
+    /** Messages exchanged that day. */
+    messages: number;
+    /** Git/work actions performed that day. */
+    work: number;
+}
+/**
+ * Aggregated metrics for ONE PC (the bridge that returns it), built from the
+ * bridge's own authoritative data: the conversation store (threads/turns) plus
+ * its persisted session + git-action event logs. The phone renders this per PC
+ * and sums across PCs for the all-PCs profile. Every field is a count the phone
+ * cannot inflate — the bridge observes it. Source of `metrics/get`.
+ */
+export interface MetricsSnapshot {
+    /** Schema version, for forward-compatible parsing. */
+    version: number;
+    /** The bridge PC's `macDeviceId` this snapshot belongs to. */
+    deviceId: string;
+    /** Total conversations (threads) started on this PC. */
+    conversations: number;
+    /** Distinct agents used. */
+    agentsUsed: number;
+    /** Distinct models used. */
+    modelsUsed: number;
+    /** Total messages exchanged (both roles). */
+    messages: number;
+    /** Total git actions performed (mutating operations). */
+    gitActions: number;
+    /** Connection sessions recorded. */
+    sessions: number;
+    /** Cumulative connected time across all sessions, ms. */
+    totalConnectedMs: number;
+    /** The single longest connection session, ms. */
+    longestSessionMs: number;
+    /** Sessions that ran over the relay. */
+    relaySessions: number;
+    /** Sessions that ran over a direct LAN/Tailscale host. */
+    directSessions: number;
+    /** Per-agent conversation tallies, most-used first. */
+    byAgent: MetricsAgentUsage[];
+    /** Earliest conversation creation (epoch ms); absent when there are none. */
+    memberSince?: number;
+    /** Per-day activity buckets for the contribution heatmap. */
+    activity: MetricsActivityDay[];
+    /**
+     * Per-day activity split per agent (conversations, messages, tokens), for the
+     * unified agent-activity view: the per-agent bars show all-time totals, or a
+     * single day's totals when a heatmap cell is selected. See
+     * {@link MetricsAgentDay}.
+     */
+    byAgentDay: MetricsDayBreakdown[];
+    /** When the bridge produced this snapshot (epoch ms). */
+    updatedAt: number;
+}
+/**
+ * `metrics/export` request. The bridge seals its metrics event log into an
+ * opaque, tamper-proof blob that only THIS same bridge can later verify +
+ * decrypt (AES-256-GCM under a secret held in the OS keychain). An optional user
+ * [passphrase] adds a second confidentiality layer (scrypt-derived), so a leaked
+ * file also needs the phrase; it must be supplied again at import.
+ */
+export interface MetricsExportParams {
+    /** Optional extra passphrase lock; required again at import when set. */
+    passphrase?: string;
+}
+export interface MetricsExportResult {
+    /** The sealed blob to write to a file (a JSON string, opaque to the phone). */
+    blob: string;
+    /** Suggested filename (e.g. `uxnan-metrics-<host>-<date>.uxmetrics`). */
+    filename: string;
+    /** Whether the blob carries an extra passphrase lock (import will need it). */
+    passphraseProtected: boolean;
+}
+/**
+ * `metrics/import` request. The phone sends back a previously exported [blob].
+ * The bridge verifies it was sealed by THIS PC — a foreign or edited file is
+ * rejected — decrypts it (using [passphrase] when the file was passphrase-locked)
+ * and merges its events by id (idempotent: re-importing the same file changes
+ * nothing). Returns the refreshed snapshot.
+ */
+export interface MetricsImportParams {
+    /** The sealed blob produced by a prior `metrics/export` on this PC. */
+    blob: string;
+    /** The passphrase, when the file was exported with one. */
+    passphrase?: string;
+}
+export interface MetricsImportResult {
+    /** How many new session + git-action events were merged in. */
+    imported: number;
+    /** The refreshed snapshot after the merge. */
+    snapshot: MetricsSnapshot;
+}

package/dist/src/models/metrics.js

@@ -0,0 +1,26 @@
+/**
+ * Profile metrics — a bridge-owned, survivable tally of a PC's activity, plus a
+ * tamper-proof export/import backup.
+ *
+ * The mobile profile screen shows aggregated metrics (conversations, messages,
+ * agents/models used, connection time, git actions, an activity heatmap). Those
+ * were derived on the phone from local storage and so were lost on an app
+ * uninstall (the app has no cloud login). To make them durable, the **bridge**
+ * becomes the source of truth: it computes them from its own authoritative data
+ * (the conversation store) plus persisted session + git-action event logs it
+ * observes itself, and serves them over `metrics/get`. The phone renders one
+ * snapshot per PC and sums across PCs.
+ *
+ * A `metrics/export` produces an opaque, tamper-proof file only the SAME bridge
+ * can later verify + decrypt (AES-256-GCM under a secret held in the PC's OS
+ * keychain), so users cannot fabricate or edit their stats; `metrics/import`
+ * feeds one back and merges its events by id (idempotent).
+ *
+ * Provider usage/credits are deliberately NOT part of this — those are read live
+ * via `agent/usageStats` and never persisted.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.11 and
+ * 02b-contracts-and-requirements.md.
+ */
+export {};
+//# sourceMappingURL=metrics.js.map

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * Interactive question contracts.
+ *
+ * An agent that needs the user to CHOOSE among options (not just approve/reject
+ * an action) emits a `question` content block (on `stream/content/block`); the
+ * phone renders an interactive picker and replies via `turn/send { questionResponse }`.
+ * The bridge routes the chosen answers back to the agent adapter. This mirrors
+ * the {@link ApprovalResponse} flow but carries multiple-choice answers instead
+ * of a binary decision.
+ *
+ * Source: architecture/02a-system-architecture.md §6.2.
+ */
+/** One selectable option of a {@link QuestionItem}. */
+export interface QuestionOption {
+    /** Display text the user picks (also the value echoed back as the answer). */
+    label: string;
+    /** Optional one-line explanation of what choosing this option means. */
+    description?: string;
+}
+/** A single question with its options. */
+export interface QuestionItem {
+    /** The full question text. */
+    question: string;
+    /** Optional short label/category for the question. */
+    header?: string;
+    /** The choices the user may pick from. */
+    options: QuestionOption[];
+    /** Whether more than one option may be selected (defaults to single-select). */
+    multiple?: boolean;
+}
+/**
+ * Payload of a `question` content block. The phone decodes this into its
+ * interactive question card. `questionId` is the bridge handle the user echoes
+ * back in {@link QuestionResponse.questionId}.
+ */
+export interface QuestionRequestBlock {
+    type: 'question';
+    /** Bridge id the phone echoes back in `questionResponse.questionId`. */
+    questionId: string;
+    /** The questions to ask (usually one; an agent may batch a few). */
+    questions: QuestionItem[];
+}
+/**
+ * The user's reply to a pending question, carried on `turn/send`. `answers` is
+ * one entry per question (in order), each an array of the chosen option
+ * `label`s (one for single-select, several for a `multiple` question, empty when
+ * the user skipped that question).
+ */
+export interface QuestionResponse {
+    /** The id from the question request the user is answering. */
+    questionId: string;
+    /** Chosen option labels, per question, in question order. */
+    answers: string[][];
+}

package/dist/src/models/question.js

@@ -0,0 +1,14 @@
+/**
+ * Interactive question contracts.
+ *
+ * An agent that needs the user to CHOOSE among options (not just approve/reject
+ * an action) emits a `question` content block (on `stream/content/block`); the
+ * phone renders an interactive picker and replies via `turn/send { questionResponse }`.
+ * The bridge routes the chosen answers back to the agent adapter. This mirrors
+ * the {@link ApprovalResponse} flow but carries multiple-choice answers instead
+ * of a binary decision.
+ *
+ * Source: architecture/02a-system-architecture.md §6.2.
+ */
+export {};
+//# sourceMappingURL=question.js.map

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

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

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

@@ -0,0 +1,137 @@
+/**
+ * AI-provider usage statistics: quota/rate windows, plan/account, credit
+ * balance and local token tallies read from a coding CLI's on-disk state — its
+ * stored OAuth token (→ the provider's official usage API) and/or its local
+ * session logs.
+ *
+ * Surfaced in the desktop's Settings → Providers section and, over the bridge,
+ * on the phone. The access path is per-runtime by design (02a §5.8.10): the
+ * desktop reads these files natively in Rust; the bridge reads them in TS so a
+ * paired phone — which cannot see the PC's disk directly — gets the same data
+ * 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.
+ */
+/** A coding CLI whose usage we read from its own stored token. */
+export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'gemini' | 'grok';
+/** Outcome of reading one provider's usage. */
+export type UsageStatus = 
+/** Fresh quota/credit data was read. */
+'ok'
+/** CLI is present but not signed in (no usable token). */
+ | 'authRequired'
+/** CLI / its config directory is not present on this machine. */
+ | 'notInstalled'
+/** Read/network/parse failure — see {@link ProviderUsage.message}. */
+ | 'error';
+/** How the data was obtained, for the UI's provenance label. Every wired
+ *  provider reads its quota from the CLI's own signed-in token. */
+export type UsageSource = 'token';
+/**
+ * The kind of billing relationship, so the UI can label an account beyond its
+ * plan name (e.g. distinguish a flat subscription from usage/credit billing).
+ * Derived per provider from its plan / billing signals.
+ */
+export type AccountType = 
+/** A flat paid subscription (Pro / Max / Plus / Pro+ …). */
+'subscription'
+/** Usage-billed: credits, on-demand, or pay-as-you-go on top of / instead of a plan. */
+ | 'payAsYouGo'
+/** Free tier. */
+ | 'free'
+/** A team / organization seat. */
+ | 'team'
+/** An enterprise plan. */
+ | 'enterprise';
+/**
+ * A single quota/rate window, expressed as a used-percentage with an optional
+ * reset time — the atomic unit a provider reports (e.g. a 5-hour session, a
+ * weekly cap, or a model-specific window).
+ */
+export interface UsageWindow {
+    /** Stable id (e.g. `session5h`, `weekly`, `opusWeekly`) — used by the
+     *  status-bar picker to remember which windows to surface. */
+    id: string;
+    /** Human label (English; the UI localizes known ids, else shows this). */
+    label: string;
+    /** Consumed fraction of this window, clamped to 0–100. */
+    usedPercent: number;
+    /** Window length in minutes (300 = 5h, 10080 = 7d, 1440 = 24h), when known. */
+    windowMinutes?: number;
+    /** When the window resets (epoch ms), when the provider reports it. */
+    resetsAt?: number;
+}
+/** A monetary / credit balance, kept separate from the percentage windows. */
+export interface CreditBalance {
+    /** Amount consumed this period, in `currency`. */
+    used: number;
+    /** Spend/credit cap, when the provider exposes one. */
+    limit?: number;
+    /** ISO-4217 code (`USD`, `EUR`, …) or `credits` for non-currency units. */
+    currency: string;
+    /** Period label (English; e.g. `Monthly`, `Credits`). */
+    period: string;
+    /** When the balance resets (epoch ms), when known. */
+    resetsAt?: number;
+    /** Amount still available this period, in `currency`, when the provider
+     *  reports a remaining balance directly (e.g. Grok on-demand / prepaid). */
+    available?: number;
+}
+/**
+ * "Reset credits" a provider grants to roll a hit rate-limit back early — Codex's
+ * rate-limit reset-credit system. Distinct from `credit` (money): these are
+ * redeemable reset tokens, not a balance.
+ */
+/** One redeemable reset — for the per-credit detail (which one, when it expires). */
+export interface ResetCreditEntry {
+    /** Short label the provider gives the reset (e.g. "Full reset"). */
+    title?: string;
+    /** When this reset lapses (epoch ms). */
+    expiresAt?: number;
+}
+export interface ResetCredits {
+    /** How many resets can be redeemed right now. */
+    available: number;
+    /** Total resets ever granted to this account, when reported. */
+    totalEarned?: number;
+    /** When the soonest still-available reset lapses (epoch ms), when known. */
+    nextExpiresAt?: number;
+    /** The individual available resets, soonest-expiring first, when the provider
+     *  details them. */
+    entries?: ResetCreditEntry[];
+}
+/** One provider's usage snapshot. */
+export interface ProviderUsage {
+    provider: UsageProvider;
+    status: UsageStatus;
+    /** How `windows`/`credit` were obtained (absent for states with no data). */
+    source?: UsageSource;
+    account?: {
+        email?: string;
+        organization?: string;
+        plan?: string;
+        accountType?: AccountType;
+    };
+    /** Quota/rate windows (percentage-based). Empty when none apply. */
+    windows: UsageWindow[];
+    credit?: CreditBalance;
+    /** Redeemable rate-limit resets (Codex), when the provider grants them. */
+    resetCredits?: ResetCredits;
+    /** When this snapshot was produced (epoch ms). */
+    updatedAt: number;
+    /** Error/hint message for `error` / `authRequired` / `notInstalled` states. */
+    message?: string;
+}
+/**
+ * `agent/usageStats` request: read usage for exactly these providers — only the
+ * ones the user activated. The reader never polls providers not listed here, so
+ * inactive providers cost nothing.
+ */
+export interface UsageStatsParams {
+    providers: UsageProvider[];
+}
+export interface UsageStatsResult {
+    usage: ProviderUsage[];
+}

package/dist/src/models/usage.js

@@ -0,0 +1,18 @@
+/**
+ * AI-provider usage statistics: quota/rate windows, plan/account, credit
+ * balance and local token tallies read from a coding CLI's on-disk state — its
+ * stored OAuth token (→ the provider's official usage API) and/or its local
+ * session logs.
+ *
+ * Surfaced in the desktop's Settings → Providers section and, over the bridge,
+ * on the phone. The access path is per-runtime by design (02a §5.8.10): the
+ * desktop reads these files natively in Rust; the bridge reads them in TS so a
+ * paired phone — which cannot see the PC's disk directly — gets the same data
+ * 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.
+ */
+export {};
+//# sourceMappingURL=usage.js.map

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

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

package/package.json

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