@ai-matrx/desktop-protocol 0.7.0 → 0.10.0

package/dist/client.d.cts

@@ -1,8 +1,8 @@
 import { BackoffOptions } from '@ai-matrx/realtime';
 export { RECONNECT_ALARM_ATTEMPTS } from '@ai-matrx/realtime';
 import { z } from 'zod';
-import { W as Welcome, D as DesktopProtocolError, C as CloseOutcome, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, e as ClientType } from './registry-Duc_VFN8.cjs';
-export { i as isDesktopProtocolError } from './registry-Duc_VFN8.cjs';
+import { W as Welcome, D as DesktopProtocolError, C as CloseOutcome, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, e as ClientType } from './registry-B3NqARgh.cjs';
+export { i as isDesktopProtocolError } from './registry-B3NqARgh.cjs';
 import { FrameHeader } from './frame.cjs';
 
 /** The subset of the WHATWG WebSocket the client uses — browser, React Native, `ws` and Workers all fit. */
@@ -114,6 +114,11 @@ interface DesktopClientOptions {
 interface RequestOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
+    /**
+     * Called with the request's id before it is sent, so progress events for it (e.g.
+     * `models.progress`, whose payload carries `request_id`) can be matched to this call.
+     */
+    onRequestId?: (id: string) => void;
 }
 type StreamOpName = {
     [N in OpName]: (typeof OPS)[N]["kind"] extends "unary" ? never : N;

package/dist/client.d.ts

@@ -1,8 +1,8 @@
 import { BackoffOptions } from '@ai-matrx/realtime';
 export { RECONNECT_ALARM_ATTEMPTS } from '@ai-matrx/realtime';
 import { z } from 'zod';
-import { W as Welcome, D as DesktopProtocolError, C as CloseOutcome, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, e as ClientType } from './registry-Duc_VFN8.js';
-export { i as isDesktopProtocolError } from './registry-Duc_VFN8.js';
+import { W as Welcome, D as DesktopProtocolError, C as CloseOutcome, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, e as ClientType } from './registry-B3NqARgh.js';
+export { i as isDesktopProtocolError } from './registry-B3NqARgh.js';
 import { FrameHeader } from './frame.js';
 
 /** The subset of the WHATWG WebSocket the client uses — browser, React Native, `ws` and Workers all fit. */
@@ -114,6 +114,11 @@ interface DesktopClientOptions {
 interface RequestOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
+    /**
+     * Called with the request's id before it is sent, so progress events for it (e.g.
+     * `models.progress`, whose payload carries `request_id`) can be matched to this call.
+     */
+    onRequestId?: (id: string) => void;
 }
 type StreamOpName = {
     [N in OpName]: (typeof OPS)[N]["kind"] extends "unary" ? never : N;

package/dist/client.js

@@ -94,7 +94,7 @@ import { z as z2 } from "zod";
 // src/schema/primitives.ts
 import { z } from "zod";
 var PROTOCOL_MAJOR = 1;
-var PROTOCOL_MINOR = 1;
+var PROTOCOL_MINOR = 2;
 var PROTOCOL_VERSION = `${PROTOCOL_MAJOR}.${PROTOCOL_MINOR}`;
 var ProtocolVersion = z.string().regex(/^[1-9][0-9]{0,2}\.[0-9]{1,3}$/);
 var RequestId = z.string().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/);
@@ -152,7 +152,22 @@ var ErrorReason = z2.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 = z2.strictObject({ edit_index: nonNegInt, reason: z2.string().max(300) });
 var ProtocolErrorBody = z2.strictObject({
@@ -635,34 +650,115 @@ var SessionListParams = z8.strictObject({});
 var SessionListResult = z8.strictObject({ resources: z8.array(ResourceInfo) });
 var SessionControlChangedEvent = z8.strictObject({ controller_client_id: z8.string().max(64).nullable(), your_mode: z8.enum(["control", "read_only"]) });
 
-// src/schema/relay.ts
+// src/schema/models.ts
 import { z as z9 } from "zod";
-var RelayDeviceStatusEvent = z9.strictObject({
-  online: z9.boolean(),
+var TranscriptionModelId = z9.enum(["tiny", "base", "small", "large-v3-turbo"]);
+var MlRuntimeState = z9.enum(["not_installed", "installing", "installed", "failed"]);
+var MlInstallPhase = z9.enum(["packages", "model", "verifying"]);
+var MlInstallProgress = z9.strictObject({
+  phase: MlInstallPhase,
+  /** What is being fetched now: a package or a model file name. */
+  item: z9.string().max(200),
+  bytes_done: nonNegInt,
+  /** Null while the total is not known yet. */
+  bytes_total: nonNegInt.nullable()
+});
+var TranscriptionModelInfo = z9.strictObject({
+  id: TranscriptionModelId,
+  /** Download size of the weights. */
+  size_bytes: nonNegInt,
+  multilingual: z9.boolean(),
+  installed: z9.boolean()
+});
+var TranscriptSegment = z9.strictObject({
+  start_s: z9.number().min(0),
+  end_s: z9.number().min(0),
+  text: z9.string().max(4e3)
+});
+var MlStatusParams = z9.strictObject({});
+var MlStatusResult = z9.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: z9.string().max(300).nullable(),
+  /** Where inference runs once the runtime is installed: `cuda` only when a usable GPU is present. */
+  accelerator: z9.enum(["cpu", "cuda"]),
+  models: z9.array(TranscriptionModelInfo).max(16),
+  default_model: TranscriptionModelId
+});
+var ModelsInstallParams = z9.strictObject({ model: TranscriptionModelId.optional() });
+var ModelsInstallResult = z9.strictObject({ model: TranscriptionModelId, elapsed_ms: nonNegInt });
+var ModelsTranscribeParams = z9.strictObject({
+  path: AbsPath,
+  model: TranscriptionModelId.optional(),
+  language: z9.string().regex(/^[a-z]{2,3}$/).optional(),
+  task: z9.enum(["transcribe", "translate"]).default("transcribe")
+});
+var ModelsTranscribeResult = z9.strictObject({
+  text: z9.string().max(4e5),
+  language: z9.string().max(8),
+  language_probability: z9.number().min(0).max(1),
+  duration_s: z9.number().min(0),
+  model: TranscriptionModelId,
+  segments: z9.array(TranscriptSegment).max(2e4),
+  elapsed_ms: nonNegInt
+});
+var MlProgress = z9.strictObject({
+  kind: z9.enum(["install", "transcribe"]),
+  /** 0–1 when known (transcribe: audio covered so far; install: bytes so far). */
+  fraction: z9.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 = z9.enum(["starting", "ready", "restarting", "failed", "stopped"]);
+var MlServiceStatus = z9.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: z9.string().max(32).nullable(),
+  /** Why the service is restarting or failed, one human line. */
+  error: z9.string().max(300).nullable()
+});
+var ModelsStatusParams = z9.strictObject({});
+var ModelsStatusResult = z9.strictObject({
+  service: MlServiceStatus,
+  /** Null until the service has answered (starting, restarting, failed). */
+  transcription: MlStatusResult.nullable()
+});
+var ModelsProgressEvent = z9.strictObject({ request_id: RequestId, progress: MlProgress });
+
+// src/schema/relay.ts
+import { z as z10 } from "zod";
+var RelayDeviceStatusEvent = z10.strictObject({
+  online: z10.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: z9.string().max(32).nullable(),
+  app_version: z10.string().max(32).nullable(),
   protocol_version: ProtocolVersion.nullable()
 });
-var RelayAuthExpiringEvent = z9.strictObject({ expires_at_ms: epochMs });
-var RelayCallRequest = z9.strictObject({
-  cap: z9.string().min(1).max(32),
-  op: z9.string().min(1).max(64),
-  params: z9.unknown(),
-  timeout_ms: z9.int().min(100).max(37e5).default(7e4)
+var RelayAuthExpiringEvent = z10.strictObject({ expires_at_ms: epochMs });
+var RelayCallRequest = z10.strictObject({
+  cap: z10.string().min(1).max(32),
+  op: z10.string().min(1).max(64),
+  params: z10.unknown(),
+  timeout_ms: z10.int().min(100).max(37e5).default(7e4)
 });
-var RelayCallResponse = z9.discriminatedUnion("ok", [
-  z9.strictObject({
-    ok: z9.literal(true),
-    result: z9.unknown(),
+var RelayCallResponse = z10.discriminatedUnion("ok", [
+  z10.strictObject({
+    ok: z10.literal(true),
+    result: z10.unknown(),
     /** Since 1.1: the version the device negotiated for this call (its welcome). */
     protocol_version: ProtocolVersion.optional()
   }),
-  z9.strictObject({
-    ok: z9.literal(false),
+  z10.strictObject({
+    ok: z10.literal(false),
     error: ProtocolErrorBody,
     /** Since 1.1, as above (absent when the device never answered hello). */
     protocol_version: ProtocolVersion.optional()
@@ -670,19 +766,111 @@ var RelayCallResponse = z9.discriminatedUnion("ok", [
 ]);
 var RELAY_CALL_HELLO_ID = "hello";
 var RELAY_CALL_REQUEST_ID = "call";
-var RelayCallHello = z9.strictObject({
-  type: z9.literal("hello"),
-  id: z9.literal(RELAY_CALL_HELLO_ID),
+var RelayCallHello = z10.strictObject({
+  type: z10.literal("hello"),
+  id: z10.literal(RELAY_CALL_HELLO_ID),
   protocolVersion: ProtocolVersion,
-  clientType: z9.literal("server"),
-  clientVersion: z9.string().min(1).max(32)
+  clientType: z10.literal("server"),
+  clientVersion: z10.string().min(1).max(32)
+});
+var RelayCallEnvelope = z10.strictObject({
+  id: z10.literal(RELAY_CALL_REQUEST_ID),
+  type: z10.literal("request"),
+  cap: z10.string().min(1).max(32),
+  op: z10.string().min(1).max(64),
+  params: z10.unknown()
+});
+
+// src/schema/apps.ts
+import { z as z11 } from "zod";
+var AppKey = z11.string().regex(/^[a-z][a-z0-9_-]{0,39}$/);
+var AppProfileId = z11.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 = z11.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 = z11.enum(["supported", "partial", "unsupported"]);
+var AppFeatureStatus = z11.strictObject({
+  status: AppSupport,
+  /** One line, set whenever status is not "supported". */
+  reason: z11.string().max(140).nullable()
+});
+var AppInfo = z11.strictObject({
+  app_key: AppKey,
+  name: z11.string().max(64),
+  installed: z11.boolean(),
+  /** The app's own version string, or null when it is not installed or does not say. */
+  version: z11.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 = z11.strictObject({
+  window: z11.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: z11.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: z11.boolean()
+});
+var AppProfile = z11.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: z11.string().min(1).max(120),
+  /** The account the person means to be signed in here; null when not stated (never guessed). */
+  account_identity: z11.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: z11.boolean(),
+  /** An instance with this profile is running; null when it could not be determined. */
+  running: z11.boolean().nullable(),
+  /** Usage the app recorded for this profile; null when the app exposes none here. */
+  usage: z11.array(AppUsageReading).nullable(),
+  last_opened_ms: epochMs.nullable()
+});
+var AppsListParams = z11.strictObject({});
+var AppsListResult = z11.strictObject({ apps: z11.array(AppInfo) });
+var AppsProfilesListParams = z11.strictObject({
+  /** Only this app's profiles; every app's when absent. */
+  app_key: AppKey.optional()
+});
+var AppsProfilesListResult = z11.strictObject({
+  profiles: z11.array(AppProfile),
+  /**
+   * Whether the saved rows could be read: false while signed out or offline, when only folders
+   * found on disk are listed.
+   */
+  registry: z11.enum(["ok", "signed_out", "unavailable"])
+});
+var AppsProfilesSaveParams = z11.strictObject({
+  id: AppProfileId.optional(),
+  app_key: AppKey,
+  display_name: z11.string().min(1).max(120),
+  account_identity: z11.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: z11.boolean().default(false)
+});
+var AppsProfilesSaveResult = AppProfile;
+var AppsProfilesRemoveParams = z11.strictObject({ id: AppProfileId });
+var AppsProfilesRemoveResult = z11.strictObject({ removed: z11.boolean() });
+var AppsOpenParams = z11.strictObject({
+  app_key: AppKey,
+  profile_id: AppProfileId.optional()
 });
-var RelayCallEnvelope = z9.strictObject({
-  id: z9.literal(RELAY_CALL_REQUEST_ID),
-  type: z9.literal("request"),
-  cap: z9.string().min(1).max(32),
-  op: z9.string().min(1).max(64),
-  params: z9.unknown()
+var AppsOpenResult = z11.strictObject({
+  /** True when an instance with this profile was already running; it is brought forward. */
+  already_running: z11.boolean(),
+  folder: AbsPath.nullable()
 });
 
 // src/schema/registry.ts
@@ -711,7 +899,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,
@@ -719,6 +917,7 @@ var EVENTS = {
   "exec.title": ExecTitleEvent,
   "exec.cwd": ExecCwdEvent,
   "session.control_changed": SessionControlChangedEvent,
+  "models.progress": ModelsProgressEvent,
   "relay.device_status": RelayDeviceStatusEvent,
   "relay.auth_expiring": RelayAuthExpiringEvent
 };
@@ -1232,6 +1431,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(() => {