@ai-matrx/desktop-protocol 0.6.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.10.0
+
+Protocol 1.2 adds the `apps` capability (SPEC §6): the desktop apps a person uses (Claude, Codex,
+Cursor, VS Code, Antigravity), their profiles (one account each, opened side by side) and usage.
+
+- Ops `apps.list`, `apps.profiles.list`, `apps.profiles.save`, `apps.profiles.remove`, `apps.open`
+  (`src/schema/apps.ts`). A profile is a row of `users.desktop_app_profile`; folders found on disk
+  that no row names yet are listed with `id: null`. Each app reports `open`, `profiles` and `usage`
+  as supported, partial or unsupported on the device's OS, with a one-line reason.
+- `AppProfileLocator`: a profile folder relative to the app's data root; never absolute, no segment
+  starting with a dot.
+
+Consumer action: none for existing ops.
+
+## 0.9.0
+
+Protocol 1.2: the `models` capability (local transcription) and the contract for supervised Python
+services (SPEC §3.10).
+
+- Ops `models.status`, `models.install`, `models.transcribe` and the event `models.progress`
+  (`src/schema/models.ts`). Install and transcribe report progress to the requesting client;
+  transcribe streams each recognised segment as it lands.
+- `SERVICES` (registry.ts) and the service envelope (`src/schema/service.ts`): the length-framed
+  JSON a core speaks to a Python service over its local socket — `hello` with a per-launch token and
+  `CONTRACT_SHA256`, `request`/`response`/`error`/`progress`/`cancel`, `ping`/`pong`, `shutdown`.
+  A forwarded Router op uses the same schemas as its service op.
+- `CONTRACT_SHA256` (`src/contract.ts`, generated): the schema file's hash. The generated Python
+  module carries the same value, plus `SERVICES`, `SERVICE_PROGRESS` and a typed handler
+  `Protocol` per service (`MlServiceHandlers`), so `pyright --strict` fails a service that drifts.
+- Error reasons `runtime_not_installed`, `model_not_installed`, `unsupported_media`,
+  `download_failed`, `service_starting`, `service_restarted`, `service_failed`, listed in
+  `REASONS_SINCE`; `forPeer` drops a reason an older peer does not know.
+- The tarball ships `generated/desktop-protocol.schema.json` and `scripts/gen_pydantic.py`, so a
+  consumer that runs Python (matrx-desktop's services) generates its Pydantic twin with the one
+  generator, from the exact schema it installed.
+
+Consumer action: none for existing ops. Python consumers regenerate from the installed package
+(`gen_pydantic.py --schema node_modules/@ai-matrx/desktop-protocol/generated/desktop-protocol.schema.json`).
+
+## 0.8.0
+
+- Local tool proof records (SPEC §10): `ToolLevel`, `ToolOutcome`, `ToolPlatform`, `ToolTransport`,
+  `ToolName`, `ToolLevelResult`, `ToolResultsFile` (`src/schema/tools.ts`), generated into the
+  Pydantic twin, so the desktop's vitest harnesses and aidream's live pytest write one shape.
+- `TOOL_CATALOG`, `TOOL_GROUPS`, `LEGACY_ACTIONS`, `LEGACY_DISPATCHERS` (`src/tools/catalog.ts`):
+  every tool a platform agent calls on a computer, the ops it reaches, its group, and what became of
+  each of matrx-local's 139 handlers.
+- `buildToolStatus(files)` and `renderToolStatusMarkdown(status)` (`src/tools/status.ts`): the
+  generated tool × level × platform table. Level 2 reads `pass` only with localhost, the relay and
+  the relay from another network; a tool is working only when all three levels pass.
+
+Consumer action: cite tool status only from `buildToolStatus`; never hand-write a status.
+
+## 0.7.0
+
+- `CLOSE_RULES` / `closeRule(code)` / `isTerminalClose(code)` (`src/close-policy.ts`): the one table
+  of what a dialer does after each close — `reconnect_now`, `reconnect`, `reauth` (one retry with a
+  fresh token; a second refusal before any welcome is terminal, outcome `signed_out`), or `stop`
+  with an `outcome` (`not_owned` 4003, `removed` 4004, `replaced` 4009, `revoked` 4010,
+  `upgrade_required` 4426). A CloseCode without a rule fails to compile; unknown codes reconnect.
+- The client reads that table (its private terminal list is gone) and reports
+  `DesktopClientState.outcome` when it stops; 4001/4008 no longer redial forever.
+
+Consumer action: never keep a local list of terminal close codes; branch on `closeRule(code)` and
+show `state.outcome`.
+
 ## 0.6.0
 
 - `RelayDeviceStatusEvent.since_ms` is `null` for a device that has never connected (protocol 1.1;

package/README.md

@@ -88,6 +88,19 @@ params = validate_wire(FsListParams, raw_json)  # same verdict as zod, always
 `validate_wire` is the one Python entry point: strict (no `"2"` → 2) and JavaScript-faithful
 (`2.0` is the integer 2). `OPS` maps every op to its params/result models, kind and errors.
 
+## Python services (matrx-desktop)
+
+The desktop's supervised Python services generate their models from the installed package with
+the same generator, so the core and the service can never drift:
+
+```bash
+python3 node_modules/@ai-matrx/desktop-protocol/scripts/gen_pydantic.py \
+  --schema node_modules/@ai-matrx/desktop-protocol/generated/desktop-protocol.schema.json --out <module>.py
+```
+
+The module carries `SERVICES`, a typed handler `Protocol` per service (`MlServiceHandlers`) and
+`CONTRACT_SHA256`, which must equal the core's (`import { CONTRACT_SHA256 }`) in the service hello.
+
 ## Changing the protocol
 
 Edit `src/schema/*.ts`, then `pnpm generate` and commit all three files. Rules (enforced by

package/dist/client.cjs

@@ -124,7 +124,7 @@ var import_zod2 = require("zod");
 // src/schema/primitives.ts
 var import_zod = require("zod");
 var PROTOCOL_MAJOR = 1;
-var PROTOCOL_MINOR = 1;
+var PROTOCOL_MINOR = 2;
 var PROTOCOL_VERSION = `${PROTOCOL_MAJOR}.${PROTOCOL_MINOR}`;
 var ProtocolVersion = import_zod.z.string().regex(/^[1-9][0-9]{0,2}\.[0-9]{1,3}$/);
 var RequestId = import_zod.z.string().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/);
@@ -182,7 +182,22 @@ var ErrorReason = import_zod2.z.enum([
   "resource_expired",
   "control_taken",
   // another client of the same user took control
-  "window_exhausted"
+  "window_exhausted",
+  // 1.2 (REASONS_SINCE): the `models` capability and its supervised Python service
+  "runtime_not_installed",
+  // NOT_FOUND: install the inference runtime first (models.install)
+  "model_not_installed",
+  // NOT_FOUND: that model's weights are not on the device
+  "unsupported_media",
+  // INVALID_PARAMS: the file is not audio or video the decoder reads
+  "download_failed",
+  // install could not fetch a package or model file
+  "service_starting",
+  // RESOURCE_BUSY (retryable): the service is starting or restarting
+  "service_restarted",
+  // RESOURCE_GONE: the service died while this request ran
+  "service_failed"
+  // INTERNAL: the service could not be started (see models.status)
 ]);
 var FsPatchEditFailure = import_zod2.z.strictObject({ edit_index: nonNegInt, reason: import_zod2.z.string().max(300) });
 var ProtocolErrorBody = import_zod2.z.strictObject({
@@ -311,6 +326,29 @@ var CloseCode = {
 };
 var CloseCodeValue = import_zod3.z.literal([1e3, 1001, 1006, 1012, 1013, 4001, 4003, 4004, 4008, 4009, 4010, 4400, 4426]);
 
+// src/close-policy.ts
+var CLOSE_RULES = {
+  [CloseCode.NORMAL]: { action: "reconnect", error: ["DEVICE_OFFLINE", "Connection closed"] },
+  [CloseCode.GOING_AWAY]: { action: "reconnect_now", error: ["DEVICE_OFFLINE", "Connection lost"] },
+  [CloseCode.ABNORMAL]: { action: "reconnect_now", error: ["DEVICE_OFFLINE", "Connection lost"] },
+  [CloseCode.DEVICE_RECONNECTED]: { action: "reconnect_now", error: ["DEVICE_OFFLINE", "Device reconnected"] },
+  [CloseCode.TRY_AGAIN_LATER]: { action: "reconnect", error: ["DEVICE_OFFLINE", "Relay busy; retrying"] },
+  [CloseCode.AUTH_INVALID]: { action: "reauth", outcome: "signed_out", error: ["AUTH_INVALID", "Sign-in was not accepted"] },
+  [CloseCode.AUTH_FORBIDDEN]: { action: "stop", outcome: "not_owned", error: ["AUTH_FORBIDDEN", "Not this device's owner"] },
+  [CloseCode.DEVICE_NOT_FOUND]: { action: "stop", outcome: "removed", error: ["NOT_FOUND", "Device not found"] },
+  [CloseCode.AUTH_EXPIRED]: { action: "reauth", outcome: "signed_out", error: ["AUTH_EXPIRED", "Sign-in expired"] },
+  [CloseCode.REPLACED]: { action: "stop", outcome: "replaced", error: ["CONFLICT", "Replaced by a newer connection"] },
+  [CloseCode.DEVICE_REVOKED]: { action: "stop", outcome: "revoked", error: ["AUTH_DEVICE_REVOKED", "This device was revoked"] },
+  // A malformed message, or a connection the relay lost track of: a fresh socket starts clean.
+  [CloseCode.PROTOCOL_ERROR]: { action: "reconnect", error: ["PROTOCOL_ERROR", "Connection reset by the relay"] },
+  [CloseCode.UPGRADE_REQUIRED]: { action: "stop", outcome: "upgrade_required", error: ["PROTOCOL_VERSION_UNSUPPORTED", "Protocol upgrade required"] }
+};
+var UNKNOWN = { action: "reconnect", error: ["DEVICE_OFFLINE", "Connection lost"] };
+function closeRule(code) {
+  if (code === null || code === void 0) return CLOSE_RULES[CloseCode.ABNORMAL];
+  return CLOSE_RULES[code] ?? UNKNOWN;
+}
+
 // src/schema/frame.ts
 var import_zod4 = require("zod");
 var FrameHeader = import_zod4.z.strictObject({
@@ -642,34 +680,115 @@ var SessionListParams = import_zod8.z.strictObject({});
 var SessionListResult = import_zod8.z.strictObject({ resources: import_zod8.z.array(ResourceInfo) });
 var SessionControlChangedEvent = import_zod8.z.strictObject({ controller_client_id: import_zod8.z.string().max(64).nullable(), your_mode: import_zod8.z.enum(["control", "read_only"]) });
 
-// src/schema/relay.ts
+// src/schema/models.ts
 var import_zod9 = require("zod");
-var RelayDeviceStatusEvent = import_zod9.z.strictObject({
-  online: import_zod9.z.boolean(),
+var TranscriptionModelId = import_zod9.z.enum(["tiny", "base", "small", "large-v3-turbo"]);
+var MlRuntimeState = import_zod9.z.enum(["not_installed", "installing", "installed", "failed"]);
+var MlInstallPhase = import_zod9.z.enum(["packages", "model", "verifying"]);
+var MlInstallProgress = import_zod9.z.strictObject({
+  phase: MlInstallPhase,
+  /** What is being fetched now: a package or a model file name. */
+  item: import_zod9.z.string().max(200),
+  bytes_done: nonNegInt,
+  /** Null while the total is not known yet. */
+  bytes_total: nonNegInt.nullable()
+});
+var TranscriptionModelInfo = import_zod9.z.strictObject({
+  id: TranscriptionModelId,
+  /** Download size of the weights. */
+  size_bytes: nonNegInt,
+  multilingual: import_zod9.z.boolean(),
+  installed: import_zod9.z.boolean()
+});
+var TranscriptSegment = import_zod9.z.strictObject({
+  start_s: import_zod9.z.number().min(0),
+  end_s: import_zod9.z.number().min(0),
+  text: import_zod9.z.string().max(4e3)
+});
+var MlStatusParams = import_zod9.z.strictObject({});
+var MlStatusResult = import_zod9.z.strictObject({
+  runtime: MlRuntimeState,
+  /** Non-null while runtime or model files are being installed. */
+  install: MlInstallProgress.nullable(),
+  /** The last install failure, one human line; null when the last install succeeded or none ran. */
+  error: import_zod9.z.string().max(300).nullable(),
+  /** Where inference runs once the runtime is installed: `cuda` only when a usable GPU is present. */
+  accelerator: import_zod9.z.enum(["cpu", "cuda"]),
+  models: import_zod9.z.array(TranscriptionModelInfo).max(16),
+  default_model: TranscriptionModelId
+});
+var ModelsInstallParams = import_zod9.z.strictObject({ model: TranscriptionModelId.optional() });
+var ModelsInstallResult = import_zod9.z.strictObject({ model: TranscriptionModelId, elapsed_ms: nonNegInt });
+var ModelsTranscribeParams = import_zod9.z.strictObject({
+  path: AbsPath,
+  model: TranscriptionModelId.optional(),
+  language: import_zod9.z.string().regex(/^[a-z]{2,3}$/).optional(),
+  task: import_zod9.z.enum(["transcribe", "translate"]).default("transcribe")
+});
+var ModelsTranscribeResult = import_zod9.z.strictObject({
+  text: import_zod9.z.string().max(4e5),
+  language: import_zod9.z.string().max(8),
+  language_probability: import_zod9.z.number().min(0).max(1),
+  duration_s: import_zod9.z.number().min(0),
+  model: TranscriptionModelId,
+  segments: import_zod9.z.array(TranscriptSegment).max(2e4),
+  elapsed_ms: nonNegInt
+});
+var MlProgress = import_zod9.z.strictObject({
+  kind: import_zod9.z.enum(["install", "transcribe"]),
+  /** 0–1 when known (transcribe: audio covered so far; install: bytes so far). */
+  fraction: import_zod9.z.number().min(0).max(1).nullable(),
+  install: MlInstallProgress.nullable(),
+  /** The segment just transcribed (transcribe only): text appears as it is recognised. */
+  segment: TranscriptSegment.nullable()
+});
+var MlServiceState = import_zod9.z.enum(["starting", "ready", "restarting", "failed", "stopped"]);
+var MlServiceStatus = import_zod9.z.strictObject({
+  state: MlServiceState,
+  pid: nonNegInt.nullable(),
+  /** Restarts since the app started (crashes, missed health checks). */
+  restarts: nonNegInt,
+  /** The bundled interpreter's version once the service has answered, e.g. "3.13.15". */
+  python: import_zod9.z.string().max(32).nullable(),
+  /** Why the service is restarting or failed, one human line. */
+  error: import_zod9.z.string().max(300).nullable()
+});
+var ModelsStatusParams = import_zod9.z.strictObject({});
+var ModelsStatusResult = import_zod9.z.strictObject({
+  service: MlServiceStatus,
+  /** Null until the service has answered (starting, restarting, failed). */
+  transcription: MlStatusResult.nullable()
+});
+var ModelsProgressEvent = import_zod9.z.strictObject({ request_id: RequestId, progress: MlProgress });
+
+// src/schema/relay.ts
+var import_zod10 = require("zod");
+var RelayDeviceStatusEvent = import_zod10.z.strictObject({
+  online: import_zod10.z.boolean(),
   /**
    * When the device last went online/offline; null = it has never connected (since 1.1 —
    * NULL_SINCE: a 1.0 reader is sent 0, its old meaning).
    */
   since_ms: epochMs.nullable(),
-  app_version: import_zod9.z.string().max(32).nullable(),
+  app_version: import_zod10.z.string().max(32).nullable(),
   protocol_version: ProtocolVersion.nullable()
 });
-var RelayAuthExpiringEvent = import_zod9.z.strictObject({ expires_at_ms: epochMs });
-var RelayCallRequest = import_zod9.z.strictObject({
-  cap: import_zod9.z.string().min(1).max(32),
-  op: import_zod9.z.string().min(1).max(64),
-  params: import_zod9.z.unknown(),
-  timeout_ms: import_zod9.z.int().min(100).max(37e5).default(7e4)
+var RelayAuthExpiringEvent = import_zod10.z.strictObject({ expires_at_ms: epochMs });
+var RelayCallRequest = import_zod10.z.strictObject({
+  cap: import_zod10.z.string().min(1).max(32),
+  op: import_zod10.z.string().min(1).max(64),
+  params: import_zod10.z.unknown(),
+  timeout_ms: import_zod10.z.int().min(100).max(37e5).default(7e4)
 });
-var RelayCallResponse = import_zod9.z.discriminatedUnion("ok", [
-  import_zod9.z.strictObject({
-    ok: import_zod9.z.literal(true),
-    result: import_zod9.z.unknown(),
+var RelayCallResponse = import_zod10.z.discriminatedUnion("ok", [
+  import_zod10.z.strictObject({
+    ok: import_zod10.z.literal(true),
+    result: import_zod10.z.unknown(),
     /** Since 1.1: the version the device negotiated for this call (its welcome). */
     protocol_version: ProtocolVersion.optional()
   }),
-  import_zod9.z.strictObject({
-    ok: import_zod9.z.literal(false),
+  import_zod10.z.strictObject({
+    ok: import_zod10.z.literal(false),
     error: ProtocolErrorBody,
     /** Since 1.1, as above (absent when the device never answered hello). */
     protocol_version: ProtocolVersion.optional()
@@ -677,19 +796,111 @@ var RelayCallResponse = import_zod9.z.discriminatedUnion("ok", [
 ]);
 var RELAY_CALL_HELLO_ID = "hello";
 var RELAY_CALL_REQUEST_ID = "call";
-var RelayCallHello = import_zod9.z.strictObject({
-  type: import_zod9.z.literal("hello"),
-  id: import_zod9.z.literal(RELAY_CALL_HELLO_ID),
+var RelayCallHello = import_zod10.z.strictObject({
+  type: import_zod10.z.literal("hello"),
+  id: import_zod10.z.literal(RELAY_CALL_HELLO_ID),
   protocolVersion: ProtocolVersion,
-  clientType: import_zod9.z.literal("server"),
-  clientVersion: import_zod9.z.string().min(1).max(32)
+  clientType: import_zod10.z.literal("server"),
+  clientVersion: import_zod10.z.string().min(1).max(32)
+});
+var RelayCallEnvelope = import_zod10.z.strictObject({
+  id: import_zod10.z.literal(RELAY_CALL_REQUEST_ID),
+  type: import_zod10.z.literal("request"),
+  cap: import_zod10.z.string().min(1).max(32),
+  op: import_zod10.z.string().min(1).max(64),
+  params: import_zod10.z.unknown()
+});
+
+// src/schema/apps.ts
+var import_zod11 = require("zod");
+var AppKey = import_zod11.z.string().regex(/^[a-z][a-z0-9_-]{0,39}$/);
+var AppProfileId = import_zod11.z.string().regex(/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/);
+var AppProfileLocator = import_zod11.z.string().min(1).max(512).regex(/^[A-Za-z0-9 _()+@,-][A-Za-z0-9 ._()+@,-]{0,127}(\/[A-Za-z0-9 _()+@,-][A-Za-z0-9 ._()+@,-]{0,127}){0,7}$/);
+var AppSupport = import_zod11.z.enum(["supported", "partial", "unsupported"]);
+var AppFeatureStatus = import_zod11.z.strictObject({
+  status: AppSupport,
+  /** One line, set whenever status is not "supported". */
+  reason: import_zod11.z.string().max(140).nullable()
+});
+var AppInfo = import_zod11.z.strictObject({
+  app_key: AppKey,
+  name: import_zod11.z.string().max(64),
+  installed: import_zod11.z.boolean(),
+  /** The app's own version string, or null when it is not installed or does not say. */
+  version: import_zod11.z.string().max(64).nullable(),
+  /** The install found (an .app bundle, an .exe, a binary), or null. */
+  location: AbsPath.nullable(),
+  /** Open the app at all on this OS. */
+  open: AppFeatureStatus,
+  /** Separate profiles (one account each) on this OS. */
+  profiles: AppFeatureStatus,
+  /** Plan usage read from the app's own files on this OS. */
+  usage: AppFeatureStatus
+});
+var AppUsageReading = import_zod11.z.strictObject({
+  window: import_zod11.z.enum(["five_hour", "weekly", "extra"]),
+  /** 0–100 for five_hour and weekly; extra-usage spend as a percent of its cap (may pass 100). */
+  percent: import_zod11.z.number().min(0).max(1e4),
+  /** When the app recorded it. */
+  sampled_at_ms: epochMs,
+  /** True when the window has rolled over since the sample, so the figure has reset. */
+  reset_since: import_zod11.z.boolean()
+});
+var AppProfile = import_zod11.z.strictObject({
+  /** The row's id; null for a folder found on disk that no row names yet. */
+  id: AppProfileId.nullable(),
+  app_key: AppKey,
+  display_name: import_zod11.z.string().min(1).max(120),
+  /** The account the person means to be signed in here; null when not stated (never guessed). */
+  account_identity: import_zod11.z.string().min(3).max(320).nullable(),
+  profile_locator: AppProfileLocator.nullable(),
+  /** The device the row is tied to; null when the row names none. */
+  device_id: DeviceId.nullable(),
+  /** The folder this profile resolves to on this device; null for a row tied to another device. */
+  folder: AbsPath.nullable(),
+  /** The folder exists on this device. */
+  on_disk: import_zod11.z.boolean(),
+  /** An instance with this profile is running; null when it could not be determined. */
+  running: import_zod11.z.boolean().nullable(),
+  /** Usage the app recorded for this profile; null when the app exposes none here. */
+  usage: import_zod11.z.array(AppUsageReading).nullable(),
+  last_opened_ms: epochMs.nullable()
 });
-var RelayCallEnvelope = import_zod9.z.strictObject({
-  id: import_zod9.z.literal(RELAY_CALL_REQUEST_ID),
-  type: import_zod9.z.literal("request"),
-  cap: import_zod9.z.string().min(1).max(32),
-  op: import_zod9.z.string().min(1).max(64),
-  params: import_zod9.z.unknown()
+var AppsListParams = import_zod11.z.strictObject({});
+var AppsListResult = import_zod11.z.strictObject({ apps: import_zod11.z.array(AppInfo) });
+var AppsProfilesListParams = import_zod11.z.strictObject({
+  /** Only this app's profiles; every app's when absent. */
+  app_key: AppKey.optional()
+});
+var AppsProfilesListResult = import_zod11.z.strictObject({
+  profiles: import_zod11.z.array(AppProfile),
+  /**
+   * Whether the saved rows could be read: false while signed out or offline, when only folders
+   * found on disk are listed.
+   */
+  registry: import_zod11.z.enum(["ok", "signed_out", "unavailable"])
+});
+var AppsProfilesSaveParams = import_zod11.z.strictObject({
+  id: AppProfileId.optional(),
+  app_key: AppKey,
+  display_name: import_zod11.z.string().min(1).max(120),
+  account_identity: import_zod11.z.string().min(3).max(320).nullable(),
+  /** On create: the folder to use (one found on disk), or null for the app's default profile. Ignored on update. */
+  profile_locator: AppProfileLocator.nullable(),
+  /** On create with profile_locator null: make a new folder named after display_name instead. */
+  new_folder: import_zod11.z.boolean().default(false)
+});
+var AppsProfilesSaveResult = AppProfile;
+var AppsProfilesRemoveParams = import_zod11.z.strictObject({ id: AppProfileId });
+var AppsProfilesRemoveResult = import_zod11.z.strictObject({ removed: import_zod11.z.boolean() });
+var AppsOpenParams = import_zod11.z.strictObject({
+  app_key: AppKey,
+  profile_id: AppProfileId.optional()
+});
+var AppsOpenResult = import_zod11.z.strictObject({
+  /** True when an instance with this profile was already running; it is brought forward. */
+  already_running: import_zod11.z.boolean(),
+  folder: AbsPath.nullable()
 });
 
 // src/schema/registry.ts
@@ -718,7 +929,17 @@ var OPS = {
   "session.attach": { params: SessionAttachParams, result: SessionAttachResult, kind: "stream", since: "1.0", errors: ["RESOURCE_GONE", "AUTH_FORBIDDEN", "RESOURCE_BUSY"] },
   "session.detach": { params: SessionDetachParams, result: SessionDetachResult, kind: "unary", since: "1.0", errors: ["RESOURCE_GONE"] },
   "session.release": { params: SessionReleaseParams, result: SessionReleaseResult, kind: "unary", since: "1.0", errors: ["RESOURCE_GONE", "AUTH_FORBIDDEN"] },
-  "session.list": { params: SessionListParams, result: SessionListResult, kind: "unary", since: "1.0", errors: ["INTERNAL"] }
+  "session.list": { params: SessionListParams, result: SessionListResult, kind: "unary", since: "1.0", errors: ["INTERNAL"] },
+  // Local models (SPEC §6), served by the `ml` Python service through SERVICES below.
+  "models.status": { params: ModelsStatusParams, result: ModelsStatusResult, kind: "unary", since: "1.2", errors: ["INTERNAL"] },
+  "models.install": { params: ModelsInstallParams, result: ModelsInstallResult, kind: "unary", since: "1.2", errors: ["RESOURCE_BUSY", "RESOURCE_GONE", "TIMEOUT", "CANCELLED", "INTERNAL"] },
+  "models.transcribe": { params: ModelsTranscribeParams, result: ModelsTranscribeResult, kind: "unary", since: "1.2", errors: ["NOT_FOUND", "INVALID_PARAMS", "PERMISSION_DENIED_OS", "RESOURCE_BUSY", "RESOURCE_GONE", "CANCELLED", "PAYLOAD_TOO_LARGE", "INTERNAL"] },
+  // Desktop apps and their profiles (SPEC §6 apps); profiles are rows in users.desktop_app_profile.
+  "apps.list": { params: AppsListParams, result: AppsListResult, kind: "unary", since: "1.2", errors: ["INTERNAL"] },
+  "apps.profiles.list": { params: AppsProfilesListParams, result: AppsProfilesListResult, kind: "unary", since: "1.2", errors: ["NOT_FOUND", "INVALID_PARAMS", "INTERNAL"] },
+  "apps.profiles.save": { params: AppsProfilesSaveParams, result: AppsProfilesSaveResult, kind: "unary", since: "1.2", errors: ["AUTH_REQUIRED", "AUTH_FORBIDDEN", "NOT_FOUND", "INVALID_PARAMS", "CONFLICT", "PLATFORM_UNSUPPORTED", "DEVICE_OFFLINE", "INTERNAL"] },
+  "apps.profiles.remove": { params: AppsProfilesRemoveParams, result: AppsProfilesRemoveResult, kind: "unary", since: "1.2", errors: ["AUTH_REQUIRED", "AUTH_FORBIDDEN", "NOT_FOUND", "DEVICE_OFFLINE", "INTERNAL"] },
+  "apps.open": { params: AppsOpenParams, result: AppsOpenResult, kind: "unary", since: "1.2", errors: ["NOT_FOUND", "PLATFORM_UNSUPPORTED", "AUTH_REQUIRED", "DEVICE_OFFLINE", "INTERNAL"] }
 };
 var EVENTS = {
   "fs.changed": FsChangedEvent,
@@ -726,19 +947,13 @@ var EVENTS = {
   "exec.title": ExecTitleEvent,
   "exec.cwd": ExecCwdEvent,
   "session.control_changed": SessionControlChangedEvent,
+  "models.progress": ModelsProgressEvent,
   "relay.device_status": RelayDeviceStatusEvent,
   "relay.auth_expiring": RelayAuthExpiringEvent
 };
 
 // src/client/client.ts
 var WS_OPEN = 1;
-var TERMINAL_CLOSE = /* @__PURE__ */ new Map([
-  [CloseCode.DEVICE_REVOKED, ["AUTH_DEVICE_REVOKED", "This device was revoked"]],
-  [CloseCode.AUTH_FORBIDDEN, ["AUTH_FORBIDDEN", "Not this device's owner"]],
-  [CloseCode.DEVICE_NOT_FOUND, ["NOT_FOUND", "Device not found"]],
-  [CloseCode.REPLACED, ["CONFLICT", "Replaced by a newer connection"]],
-  [CloseCode.UPGRADE_REQUIRED, ["PROTOCOL_VERSION_UNSUPPORTED", "Protocol upgrade required"]]
-]);
 var defaultTimers = {
   setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
   clearTimeout: (handle) => globalThis.clearTimeout(handle),
@@ -781,8 +996,10 @@ function createDesktopClient(options) {
     attempts: 0,
     retryInMs: null,
     lastError: null,
-    lastCloseCode: null
+    lastCloseCode: null,
+    outcome: null
   };
+  let authRefusals = 0;
   const listeners = /* @__PURE__ */ new Set();
   const readyWaiters = /* @__PURE__ */ new Set();
   const pending = /* @__PURE__ */ new Map();
@@ -817,6 +1034,7 @@ function createDesktopClient(options) {
   }
   function connect() {
     if (state.status === "connecting" || state.status === "handshaking" || state.status === "open") return;
+    if (state.status === "closed" || state.status === "idle") authRefusals = 0;
     closedByUser = false;
     if (reconnectTimer !== null) {
       timers.clearTimeout(reconnectTimer);
@@ -898,8 +1116,11 @@ function createDesktopClient(options) {
       timers.clearTimeout(probeTimer);
       probeTimer = null;
     }
-    const terminal = code === null ? void 0 : TERMINAL_CLOSE.get(code);
-    const lost = error ?? (terminal ? new DesktopProtocolError(terminal[0], terminal[1]) : new DesktopProtocolError("DEVICE_OFFLINE", "Connection lost", { retryable: true }));
+    const rule = code === null ? null : closeRule(code);
+    if (rule?.action === "reauth") authRefusals++;
+    const stopped = rule !== null && (rule.action === "stop" || rule.action === "reauth" && authRefusals >= 2);
+    const terminal = stopped && rule ? rule : void 0;
+    const lost = error ?? (terminal ? new DesktopProtocolError(terminal.error[0], terminal.error[1]) : rule && rule.action === "reauth" ? new DesktopProtocolError(rule.error[0], rule.error[1], { retryable: true }) : new DesktopProtocolError("DEVICE_OFFLINE", "Connection lost", { retryable: true }));
     for (const [id, p] of pending) {
       pending.delete(id);
       p.cleanup();
@@ -916,7 +1137,14 @@ function createDesktopClient(options) {
       endStream(s, null, lost);
     }
     if (closedByUser || terminal) {
-      setState({ status: "closed", welcome: null, lastError: closedByUser ? state.lastError : lost, lastCloseCode: code, retryInMs: null });
+      setState({
+        status: "closed",
+        welcome: null,
+        lastError: closedByUser ? state.lastError : lost,
+        lastCloseCode: code,
+        retryInMs: null,
+        outcome: closedByUser ? null : terminal?.outcome ?? null
+      });
       rejectReadyWaiters(lost);
       return;
     }
@@ -1070,7 +1298,8 @@ function createDesktopClient(options) {
     }
     helloId = null;
     backoff.markConnected();
-    setState({ status: "open", welcome: welcome.data, attempts: 0, retryInMs: null, lastError: null });
+    authRefusals = 0;
+    setState({ status: "open", welcome: welcome.data, attempts: 0, retryInMs: null, lastError: null, outcome: null });
     for (const w of [...readyWaiters]) {
       readyWaiters.delete(w);
       w.resolve(welcome.data);
@@ -1232,6 +1461,7 @@ function createDesktopClient(options) {
     }
     await ready(opts);
     const id = newId("r");
+    if (opts.onRequestId) safeCall("onRequestId", () => opts.onRequestId?.(id));
     return new Promise((resolve, reject) => {
       const timeoutMs = opts.timeoutMs ?? requestTimeoutMs;
       const timer = timers.setTimeout(() => {