uxnan-bridge 0.0.1-alpha.20260627

package/README.md

@@ -0,0 +1,180 @@
+# uxnan-bridge
+
+![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-ESM-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
+![JSON RPC](https://img.shields.io/badge/JSON--RPC_2.0-60_methods-000000?style=for-the-badge&logo=json&logoColor=white)
+![E2EE](https://img.shields.io/badge/E2EE-AES--256--GCM-0a0a0a?style=for-the-badge&logo=letsencrypt&logoColor=white)
+![Platforms](https://img.shields.io/badge/Windows_%7C_macOS_%7C_Linux-lightgrey?style=for-the-badge)
+
+The local control-plane daemon that connects the [Uxnan](../README.md) mobile app
+to your PC over an end-to-end-encrypted channel. It is the **heart of the
+product**: it holds the secure connection to your phone, runs Git and reads your
+workspace on request, and drives the AI coding agents on your behalf, routing
+JSON-RPC methods to per-domain handlers.
+
+The product is **bridge-first**. The mobile app pairs with the bridge and tries
+its direct LAN / Tailscale addresses first; the [relay](../relay/README.md) is an
+optional, self-hosted off-LAN fallback. Background push notifications are sent
+**by the bridge itself** (FCM HTTP v1) over any transport, so the phone keeps
+receiving them whether it reached the bridge directly or through a relay.
+
+> **Status:** alpha-functional on the primary path (LAN/Tailscale-direct,
+> bridge-direct push), with **five real agents wired**. The detailed breakdown of
+> what is built and what remains lives in [`FOR-DEV.md`](FOR-DEV.md); the release
+> history is in [`CHANGELOG.md`](CHANGELOG.md).
+
+## Why the bridge matters
+
+The bridge is small on purpose, but it is where the design decisions that make
+Uxnan distinct actually live:
+
+- **One bridge, many projects.** You start the bridge **once**, from a single
+  location of your choosing, and it gives the phone access to **all** the projects
+  underneath it — Git repositories or plain folders alike. There is no need to
+  launch a separate process per project: the phone browses the configured roots
+  (`workspace/browseDirs`, constrained by the `browseRoots` setting) and roots a
+  new conversation anywhere it is allowed to look.
+- **Provider-agnostic, with no keys to hand over.** For each agent the bridge
+  spawns that agent's **official local CLI** and talks to it over stdio. It never
+  uses a provider HTTP API, API key, or language SDK. Each CLI runs under the
+  account or subscription you already authenticated on the machine, and the bridge
+  only orchestrates it.
+- **Effortless discovery.** A freshly started bridge advertises itself on the
+  local network over mDNS (`_uxnan._tcp.local`), so the phone can find it without
+  typing an address. Pairing is by QR (which carries the bridge's direct
+  `host:port` list) or by a short manual code (`GET /pair/resolve?code=`) when a
+  camera is not convenient.
+- **The transports it brings up.** On start, the bridge runs a direct LAN
+  `http + ws` server (which also serves Tailscale addresses transparently) and,
+  optionally, maintains a relay pairing session for off-LAN reach. The phone
+  chooses the best available path; you do not have to.
+- **End-to-end encryption is not optional.** Every byte to and from the phone is
+  sealed with the documented E2EE protocol (X25519 + HKDF + Ed25519 +
+  AES-256-GCM). Responses are sanitized before they leave the machine — for
+  example, `auth/status` reports sign-in per agent and **never** returns a token.
+
+<details>
+<summary><b>Diagram — one bridge serving many projects over several transports</b></summary>
+
+```mermaid
+flowchart LR
+  phone["📱 uxnanmobile"]
+
+  subgraph disc["Discovery & pairing"]
+    mdns["mDNS · _uxnan._tcp.local"]
+    qr["QR (direct hosts)"]
+    code["Manual code · /pair/resolve"]
+  end
+
+  subgraph pc["💻 your PC"]
+    bridge["uxnan-bridge<br/>(single instance)"]
+    subgraph roots["browseRoots"]
+      p1["project-a (git)"]
+      p2["project-b (git)"]
+      p3["scripts/ (plain folder)"]
+    end
+    clis["Official local CLIs<br/>opencode · claude · codex · pi · gemini"]
+  end
+
+  phone -- "E2EE" --> disc
+  disc --> bridge
+  phone -- "LAN / Tailscale (direct)" --> bridge
+  phone -- "relay (optional, off-LAN)" --> bridge
+  bridge --> p1
+  bridge --> p2
+  bridge --> p3
+  bridge --> clis
+```
+
+</details>
+
+## How the bridge drives agents
+
+This is the mechanism behind "provider-agnostic": the bridge spawns each agent's
+official local CLI — `opencode`, `claude`, `codex`, `pi`, `gemini` — as a child
+process and drives it over stdio, exactly as you would in a terminal. Prompts are
+passed as `argv` elements with `shell:false` (no shell injection), in the thread's
+working directory. The bridge parses each CLI's native stream and re-emits it as
+structured events — `stream/content/block` (command / diff / tool) plus
+`stream/thinking/delta` (reasoning) — so the phone renders the same shape no
+matter which agent is running.
+
+See [`FOR-HUMAN.md`](FOR-HUMAN.md) for the per-agent install / login
+prerequisites, and [`docs/agents.md`](docs/agents.md) for the details.
+
+## Install
+
+```bash
+npm install -g uxnan-bridge   # (planned — published as a global package)
+```
+
+## CLI
+
+```bash
+uxnan-bridge start            # start the daemon: LAN server + (optional) relay pairing session
+uxnan-bridge status           # print current status as JSON
+uxnan-bridge qr               # print the pairing QR in the terminal (with the manual code)
+uxnan-bridge code             # print just the current pairing code
+uxnan-bridge stop             # stop the running daemon (via the lock file)
+uxnan-bridge install-service  # autostart at logon (Task Scheduler / LaunchAgent / systemd --user)
+uxnan-bridge uninstall-service
+```
+
+Logs are written to `~/.uxnan/logs/bridge-YYYY-MM-DD.log` (daily rotation, with a
+secret-redaction pass) and to stderr. Autostart at login is configured by the
+platform scripts under `scripts/`.
+
+The Ed25519 identity is stored in the OS keychain (Windows Credential Manager /
+macOS Keychain / Linux Secret Service) via `@napi-rs/keyring`. With no keychain
+available, the bridge still runs with an in-memory identity (not persisted across
+restarts).
+
+## Docs
+
+Task-focused guides live in [`docs/`](docs/):
+[installation & autostart](docs/installation.md) ·
+[configuration](docs/configuration.md) ·
+[connectivity (LAN / Tailscale / relay)](docs/connectivity.md) ·
+[how agents are driven](docs/agents.md) ·
+[testing](docs/testing.md) ·
+[packaging & deploy](docs/deploy.md) ·
+[push notifications](docs/push-notifications.md).
+
+## Architecture
+
+- **Contracts.** Consumes [`@uxnan/shared`](../shared/README.md) for JSON-RPC and
+  E2EE types and runtime validators. The bridge exposes **60 JSON-RPC methods +
+  8 streaming notifications** (see `shared/src/jsonrpc/`); the mobile app keeps
+  manually-synced Dart equivalents of the same shapes.
+- **State.** Non-secret JSON under `~/.uxnan/` (atomic writes) —
+  `daemon-config.json`, `pairing-session.json`, `threads.json`,
+  `trusted-phones.json`, `push-state.json`, `agent-cache/`, `logs/`. The Ed25519
+  identity is a secret kept in a `SecretStore`, never written in plaintext.
+- **Routing.** `HandlerRouter.dispatchRaw()` validates the envelope and routes to
+  registered handlers; errors map to JSON-RPC error codes (`-32000..-32008` +
+  standard).
+- **Agents.** An `IAgentAdapter` per agent (OpenCode / Claude Code / Codex / pi /
+  Gemini CLI); `AgentManager` orchestrates streaming and broadcasts `stream/*`
+  notifications to connected phones.
+- **Push.** `PushService` (persisted by relay `sessionId`) delivers FCM HTTP v1
+  directly via `createBridgePushSender` (lazy `firebase-admin`), with the relay
+  `/push/notify` as a fallback.
+
+The cross-component specification is `architecture/02a-system-architecture.md`
+§5.8 and
+[`uxnandesktop/architecture/02e-bridge-integration.md`](../uxnandesktop/architecture/02e-bridge-integration.md).
+
+## Develop
+
+```bash
+# from the repo root (npm workspaces):
+npm run build      # build @uxnan/shared then uxnan-bridge
+npm test           # build + run all node:test suites
+npm run typecheck  # tsc --noEmit across packages
+npm run format     # prettier --write
+```
+
+Requires Node ≥ 18. ESM-only. The test runner uses `--test-concurrency=1` on
+Windows (see [`CHANGELOG.md`](CHANGELOG.md) for why). What is implemented versus
+still pending — including the recipe for wiring the next agent — is tracked in
+[`FOR-DEV.md`](FOR-DEV.md).

package/dist/src/account-status.d.ts

@@ -0,0 +1,13 @@
+import type { AgentId, AuthStatus } from '@uxnan/shared';
+export interface AccountStatusDeps {
+    /** Whether the agent's binary resolved (from the AgentManager). */
+    isAvailable(agentId: AgentId): boolean;
+    /** Injectable home dir (defaults to the OS home) — for tests. */
+    homeDir?: string;
+    /** Injectable existence check (defaults to fs `access`) — for tests. */
+    fileExists?: (path: string) => Promise<boolean>;
+    /** Injectable platform (defaults to `process.platform`) — for tests. */
+    platform?: NodeJS.Platform | string;
+}
+/** Build the sanitized {@link AuthStatus} for one agent. */
+export declare function getAuthStatus(agentId: AgentId, deps: AccountStatusDeps): Promise<AuthStatus>;

package/dist/src/account-status.js

@@ -0,0 +1,78 @@
+/**
+ * Sanitized account/auth status per agent (architecture/02a §5.8.9).
+ *
+ * Reports whether an agent's CLI looks logged in on this PC WITHOUT ever reading
+ * or exposing tokens/keys: detection is by **existence only** of each agent's
+ * well-known auth file (never its contents), and the response carries only the
+ * agent id, booleans, the public provider name, the transport mode and the OS
+ * platform. There is intentionally no `displayName` — deriving it would mean
+ * reading an account/credentials file, which may hold secrets.
+ *
+ * Heuristic, not authoritative: an installed-but-logged-out CLI whose auth file
+ * is absent reports `requiresLogin: true`; an agent we have no auth-file mapping
+ * for falls back to its binary availability. FOR-DEV: for an authoritative
+ * answer, run the agent CLI's own auth/whoami command (out of MVP scope — it is
+ * slower and per-CLI).
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+/** Public provider name surfaced per agent (never a secret). */
+const PROVIDER_BY_AGENT = {
+    codex: 'openai',
+    'claude-code': 'anthropic',
+    opencode: 'opencode',
+};
+/**
+ * Auth-presence files per agent, relative to the user's home. EXISTENCE is the
+ * only signal read — contents (which hold the token) are never opened. Multiple
+ * candidates cover platform/version differences; the first that exists wins.
+ */
+const AUTH_FILES = {
+    codex: ['.codex/auth.json'],
+    'claude-code': ['.claude/.credentials.json', '.claude.json'],
+    opencode: ['.local/share/opencode/auth.json', '.config/opencode/auth.json'],
+    // pi stores per-provider credentials (OAuth/API keys) in one auth file; its
+    // existence means at least one provider is logged in. pi is multi-provider, so
+    // no single public provider name is surfaced.
+    'pi-agent': ['.pi/agent/auth.json'],
+};
+async function defaultExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Build the sanitized {@link AuthStatus} for one agent. */
+export async function getAuthStatus(agentId, deps) {
+    const available = deps.isAvailable(agentId);
+    const provider = PROVIDER_BY_AGENT[agentId];
+    const authFiles = AUTH_FILES[agentId] ?? [];
+    let authenticated = false;
+    if (available && authFiles.length > 0) {
+        const home = deps.homeDir ?? homedir();
+        const exists = deps.fileExists ?? defaultExists;
+        for (const relative of authFiles) {
+            if (await exists(join(home, relative))) {
+                authenticated = true;
+                break;
+            }
+        }
+    }
+    // No binary → must be set up on the PC. Binary present with an auth-file
+    // mapping → trust the existence check. Binary present without a mapping →
+    // assume usable (we can't cheaply tell, and blocking would be wrong).
+    const requiresLogin = available ? (authFiles.length > 0 ? !authenticated : false) : true;
+    return {
+        agentId,
+        requiresLogin,
+        loginInProgress: false,
+        ...(provider !== undefined && authenticated ? { authenticatedProvider: provider } : {}),
+        transportMode: 'local',
+        platform: deps.platform ?? process.platform,
+    };
+}
+//# sourceMappingURL=account-status.js.map

package/dist/src/account-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-status.js","sourceRoot":"","sources":["../../src/account-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,gEAAgE;AAChE,MAAM,iBAAiB,GAAqC;IAC1D,KAAK,EAAE,QAAQ;IACf,aAAa,EAAE,WAAW;IAC1B,QAAQ,EAAE,UAAU;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,GAAuC;IACrD,KAAK,EAAE,CAAC,kBAAkB,CAAC;IAC3B,aAAa,EAAE,CAAC,2BAA2B,EAAE,cAAc,CAAC;IAC5D,QAAQ,EAAE,CAAC,iCAAiC,EAAE,4BAA4B,CAAC;IAC3E,4EAA4E;IAC5E,+EAA+E;IAC/E,8CAA8C;IAC9C,UAAU,EAAE,CAAC,qBAAqB,CAAC;CACpC,CAAC;AAaF,KAAK,UAAU,aAAa,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAgB,EAChB,IAAuB;IAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAE5C,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC;QAChD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;gBACvC,aAAa,GAAG,IAAI,CAAC;gBACrB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzF,OAAO;QACL,OAAO;QACP,aAAa;QACb,eAAe,EAAE,KAAK;QACtB,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,aAAa,EAAE,OAAO;QACtB,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ;KAC5C,CAAC;AACJ,CAAC"}

package/dist/src/adapters/base-adapter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base class for agent CLI adapters: event fan-out plus the {@link IAgentAdapter}
+ * surface. Concrete adapters implement the lifecycle and turn methods.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (adapters/base-adapter).
+ */
+import type { AgentCapabilities, AgentConfig, AgentId, AgentStreamEvent, IAgentAdapter, SendTurnOptions } from '@uxnan/shared';
+export declare abstract class BaseAgentAdapter implements IAgentAdapter {
+    #private;
+    abstract readonly agentId: AgentId;
+    abstract readonly capabilities: AgentCapabilities;
+    onEvent(listener: (event: AgentStreamEvent) => void): () => void;
+    protected emit(event: AgentStreamEvent): void;
+    abstract start(config: AgentConfig): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract sendTurn(options: SendTurnOptions): Promise<void>;
+    abstract cancelTurn(threadId: string, turnId: string): Promise<void>;
+}

package/dist/src/adapters/base-adapter.js

@@ -0,0 +1,15 @@
+export class BaseAgentAdapter {
+    #listeners = new Set();
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.#listeners) {
+            listener(event);
+        }
+    }
+}
+//# sourceMappingURL=base-adapter.js.map

package/dist/src/adapters/base-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.js","sourceRoot":"","sources":["../../../src/adapters/base-adapter.ts"],"names":[],"mappings":"AAeA,MAAM,OAAgB,gBAAgB;IAI3B,UAAU,GAAG,IAAI,GAAG,EAAqC,CAAC;IAEnE,OAAO,CAAC,QAA2C;QACjD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC;IAES,IAAI,CAAC,KAAuB;QACpC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CAMF"}

package/dist/src/adapters/claude-adapter.d.ts

@@ -0,0 +1,102 @@
+import type { AgentCapabilities, AgentConfig, AgentId, AgentModel, SendTurnOptions } from '@uxnan/shared';
+import { BaseAgentAdapter } from './base-adapter.js';
+import { type ClaudeToolResult, type ClaudeToolUse } from './claude-tools.js';
+import { type SpawnFn } from './spawn.js';
+/**
+ * Headless permission posture passed to the CLI:
+ *  - `default`           → no flag (tools needing approval are auto-denied headless);
+ *  - `acceptEdits`       → `--permission-mode acceptEdits` (file edits auto-apply);
+ *  - `bypassPermissions` → `--dangerously-skip-permissions` (all tools run).
+ */
+export type ClaudePermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions';
+/** An explicit, concrete model to add to the picker beyond the stable aliases. */
+export interface ClaudeModelSpec {
+    /** Exact model id passed to `--model` (e.g. `claude-opus-4-8`). */
+    id: string;
+    /** Human-facing label (defaults to `id`). */
+    displayName?: string;
+    /** Optional one-line description. */
+    description?: string;
+}
+export interface ClaudeCodeAdapterOptions {
+    /** Executable to spawn (resolved path; see resolve-claude.ts). */
+    binaryPath?: string;
+    /** Args prepended before the adapter args (e.g. `[cli.js]` when running via node). */
+    prependArgs?: string[];
+    /** Default model (`alias` or full id) when the thread/turn doesn't pick one. */
+    defaultModel?: string;
+    /**
+     * Concrete, versioned models to surface in the picker **in addition** to the
+     * stable `opus`/`sonnet`/`haiku` aliases — declared in daemon config
+     * (`agents.claude-code.models`). Lets users pick an exact/older version while
+     * the aliases keep tracking "latest". Deduplicated against the aliases by id.
+     */
+    pinnedModels?: ClaudeModelSpec[];
+    /** Headless permission posture (default `acceptEdits`). */
+    permissionMode?: ClaudePermissionMode;
+    /**
+     * Opt-in interactive approvals: inject a `PreToolUse` hook (via `--settings`)
+     * so every tool round-trips to the bridge for the user's approval. Requires
+     * {@link approvalHook} to be set and resolvable (the bridge's local endpoint).
+     */
+    interactiveApprovals?: boolean;
+    /**
+     * The local approval-hook endpoint + token + the path to the shipped hook
+     * script. `url()` is lazy because the LAN port is known only after the server
+     * starts; it returns `undefined` until then (the turn runs without the hook).
+     */
+    approvalHook?: {
+        token: string;
+        scriptPath: string;
+        url: () => string | undefined;
+    };
+    /** Injected spawn function for the one-shot path (tests). */
+    spawnFn?: SpawnFn;
+}
+/** A normalized Claude Code event extracted from one stream-json line. */
+export interface ClaudeEvent {
+    kind: 'init' | 'delta' | 'thinking' | 'assistant_text' | 'tool_result' | 'result' | 'other';
+    sessionId?: string;
+    text?: string;
+    /** Only set for `init`: the concrete model id the run resolved the alias to. */
+    model?: string;
+    /** Only set for `result`: whether the turn ended in error. */
+    isError?: boolean;
+    /** Only set for `result`: the raw `usage` object (token counts), if present. */
+    usage?: unknown;
+    /** Only set for `assistant_text`: any tool invocations in the message. */
+    toolUses?: ClaudeToolUse[];
+    /** Only set for `tool_result`: results the agent fed back from its tools. */
+    toolResults?: ClaudeToolResult[];
+}
+/**
+ * Context-window size (tokens) for a Claude model id or alias, so the phone can
+ * show context usage as a percentage. Fable/Opus/Sonnet are 1M, Haiku is 200K
+ * (matches the current model catalog); unknown ids return undefined.
+ */
+export declare function claudeContextWindow(model: string | undefined): number | undefined;
+/** Sum the context-occupying token counts from a Claude `result.usage` object. */
+export declare function claudeUsageTokens(usage: unknown): number | undefined;
+/** Parse one `claude … --output-format stream-json` line, or null if it isn't JSON. */
+export declare function parseClaudeLine(line: string): ClaudeEvent | null;
+export declare class ClaudeCodeAdapter extends BaseAgentAdapter {
+    #private;
+    readonly agentId: AgentId;
+    readonly capabilities: AgentCapabilities;
+    /** Native Claude session id for a thread (on-disk history-fallback locator). */
+    nativeSessionId(threadId: string): string | undefined;
+    constructor(options?: ClaudeCodeAdapterOptions);
+    get defaultModel(): string | undefined;
+    start(config: AgentConfig): Promise<void>;
+    stop(): Promise<void>;
+    sendTurn(options: SendTurnOptions): Promise<void>;
+    cancelTurn(threadId: string, turnId: string): Promise<void>;
+    /**
+     * Claude Code has no model-list command. Expose the stable `--model` aliases
+     * (each tracks the latest model of its tier the account can use — the concrete
+     * version is reported per-run via the `model_resolved` event), followed by any
+     * concrete versions pinned in config. Pinned ids that collide with an alias
+     * are dropped so the alias (the "latest" entry) wins.
+     */
+    listModels(): Promise<AgentModel[]>;
+}