@ai-matrx/desktop-protocol 0.7.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # 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

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({
@@ -665,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()
@@ -700,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 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 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 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
@@ -741,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,
@@ -749,6 +947,7 @@ var EVENTS = {
   "exec.title": ExecTitleEvent,
   "exec.cwd": ExecCwdEvent,
   "session.control_changed": SessionControlChangedEvent,
+  "models.progress": ModelsProgressEvent,
   "relay.device_status": RelayDeviceStatusEvent,
   "relay.auth_expiring": RelayAuthExpiringEvent
 };
@@ -1262,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(() => {