@ai-matrx/desktop-protocol 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { O as OpName } from './registry-BeY9D7h0.js';
-export { B as BEARER_PREFIX, e as CancelMsg, f as ClientToCoreMsg, C as ClientType, g as CloseCode, h as CloseCodeValue, j as CoreToClientMsg, k as CreditMsg, D as DesktopProtocolError, d as EVENTS, l as EndMsg, E as EndReason, m as ErrorCode, n as ErrorCodeName, o as ErrorData, p as ErrorMsg, q as ErrorReason, r as ErrorReasonName, s as EventMsg, t as EventName, F as FsPatchEditFailure, H as HelloMsg, L as Limits, N as NAMED_SCHEMAS, u as NamedSchemaId, c as OPS, v as OpDescriptor, a as OpParams, b as OpResult, w as OpSpec, P as PING_TEXT, x as PONG_TEXT, y as ProtocolErrorBody, R as RelayMsg, z as RequestMsg, A as ResponseMsg, G as SUBPROTOCOL, S as StreamMeta, I as StreamMsg, W as Welcome, i as isDesktopProtocolError } from './registry-BeY9D7h0.js';
+import { O as OpName } from './registry-Duc_VFN8.js';
+export { B as BEARER_PREFIX, f as CLOSE_RULES, g as CancelMsg, h as ClientToCoreMsg, e as ClientType, j as CloseAction, k as CloseCode, l as CloseCodeValue, C as CloseOutcome, m as CloseRule, n as CoreToClientMsg, o as CreditMsg, D as DesktopProtocolError, d as EVENTS, p as EndMsg, E as EndReason, q as ErrorCode, r as ErrorCodeName, s as ErrorData, t as ErrorMsg, u as ErrorReason, v as ErrorReasonName, w as EventMsg, x as EventName, F as FsPatchEditFailure, H as HelloMsg, L as Limits, N as NAMED_SCHEMAS, y as NamedSchemaId, c as OPS, z as OpDescriptor, a as OpParams, b as OpResult, A as OpSpec, P as PING_TEXT, G as PONG_TEXT, I as ProtocolErrorBody, R as RelayMsg, J as RequestMsg, K as ResponseMsg, M as SUBPROTOCOL, S as StreamMeta, Q as StreamMsg, W as Welcome, T as closeRule, i as isDesktopProtocolError, U as isTerminalClose } from './registry-Duc_VFN8.js';
 export { BROADCAST_CID, DecodedFrame, FRAME_HEADER_BYTES, FRAME_STRUCT_FORMAT, FRAME_VERSION, FrameChannel, FrameChannelValue, FrameFlag, assertFrameHeader, connectionEndFrame, decodeFrame, encodeFrame, hasFlag, isConnectionEnd, readCid, stampCid } from './frame.js';
 
 /** @ai-matrx/desktop-protocol — version and primitive schemas. Schema source: lint-enforced rules in scripts/check-schema-source.mjs. */
@@ -9,7 +9,8 @@ declare const PROTOCOL_MAJOR: 1;
 /**
  * Minor history (same major = compatible; see src/versioning.ts for the rule and FIELDS_SINCE):
  *   1.0 — the first contract.
- *   1.1 — fs.patch per-edit results; /call reports the negotiated version.
+ *   1.1 — fs.patch per-edit results; /call reports the negotiated version;
+ *         device status since_ms is null for a device that never connected.
  */
 declare const PROTOCOL_MINOR: 1;
 /** This package's version as the wire spells it ("major.minor"): hello, welcome, relay status. */
@@ -921,7 +922,7 @@ declare const RELAY_CALL_HELLO_ID: "hello";
 declare const RELAY_CALL_REQUEST_ID: "call";
 declare const RelayDeviceStatusEvent: z.ZodObject<{
     online: z.ZodBoolean;
-    since_ms: z.ZodInt;
+    since_ms: z.ZodNullable<z.ZodInt>;
     app_version: z.ZodNullable<z.ZodString>;
     protocol_version: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
@@ -1009,7 +1010,7 @@ type RelayCallResponse = z.output<typeof RelayCallResponse>;
 /** HTTP GET /v1/devices/{device_id}/status (owner JWT). */
 declare const RelayStatusResponse: z.ZodObject<{
     online: z.ZodBoolean;
-    since_ms: z.ZodInt;
+    since_ms: z.ZodNullable<z.ZodInt>;
     app_version: z.ZodNullable<z.ZodString>;
     protocol_version: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
@@ -1065,6 +1066,28 @@ declare const FIELDS_SINCE: {
     };
 };
 type FieldsSincePath = keyof typeof FIELDS_SINCE;
+/**
+ * 1.0 fields that a later minor lets be null, and what a peer older than that minor is sent
+ * instead (the value that meant the same thing before). Widening a field any other way is a major.
+ */
+declare const NULL_SINCE: {
+    readonly "RelayDeviceStatusEvent.since_ms": {
+        readonly since: "1.1";
+        readonly olderPeersGet: 0;
+    };
+};
+/** A device status for a reader at `version`: `since_ms` null ("never") becomes 0 before 1.1. */
+declare function statusForPeer<T extends {
+    since_ms: number | null;
+}>(status: T, version: string): T;
+/**
+ * A WebSocket client announces the newest minor it reads at connect time by also offering
+ * `matrx.v<major>.<minor>` beside SUBPROTOCOL (servers still answer SUBPROTOCOL). Before hello is
+ * possible, this is how the relay picks the right shape for its greeting.
+ */
+declare function versionSubprotocol(version: string): string;
+/** The version a client announced in its offered subprotocols; "1.0" when it did not. */
+declare function announcedVersion(offered: readonly string[]): string;
 /** "1.10" > "1.9". Same-major comparison of "major.minor" strings. */
 declare function compareVersions(a: string, b: string): number;
 /** True when a peer at `version` knows a field added in `since`. */
@@ -1080,4 +1103,4 @@ declare function forPeer(op: OpName | null, part: "error", value: unknown, versi
 /** Every op whose result has a versioned field is wired into forPeer (checked by the test). */
 declare const VERSIONED_RESULT_OPS: readonly OpName[];
 
-export { AbsPath, DEFAULT_MAX_FRAME_PAYLOAD_BYTES, DEFAULT_MAX_MESSAGE_BYTES, DEFAULT_WINDOW_BYTES, DeviceId, ExecCwdEvent, ExecExitedEvent, ExecListParams, ExecListResult, ExecPtyKillParams, ExecPtyKillResult, ExecPtyResizeParams, ExecPtyResizeResult, ExecPtySignalParams, ExecPtySignalResult, ExecPtyStartParams, ExecPtyStartResult, ExecPtyWriteParams, ExecPtyWriteResult, ExecRunParams, ExecRunResult, ExecTitleEvent, FIELDS_SINCE, type FieldsSincePath, FrameHeader, FsChange, FsChangedEvent, FsDeleteParams, FsDeleteResult, FsEncoding, FsEntry, FsKind, FsListParams, FsListResult, FsMkdirParams, FsMkdirResult, FsMoveParams, FsMoveResult, FsPatchEditApplied, FsPatchParams, FsPatchResult, FsReadParams, FsReadResult, FsReadStreamParams, FsReadStreamResult, FsSearchContentParams, FsSearchContentResult, FsSearchPathsParams, FsSearchPathsResult, FsStatParams, FsStatResult, FsWatchParams, FsWatchResult, FsWriteParams, FsWriteResult, OpName, OsPermissionName, PROTOCOL_MAJOR, PROTOCOL_MINOR, PROTOCOL_VERSION, ProtocolVersion, PtyInfo, RELAY_CALL_HELLO_ID, RELAY_CALL_REQUEST_ID, RELAY_CALL_VERSION_HEADER, RelayAuthExpiringEvent, RelayCallEnvelope, RelayCallHello, RelayCallRequest, RelayCallResponse, RelayDeviceStatusEvent, RelayHopConnectionEnd, RelayHopEnvelopeHeader, RelayStatusResponse, RequestId, ResourceId, ResourceInfo, SessionAttachParams, SessionAttachResult, SessionControlChangedEvent, SessionDetachParams, SessionDetachResult, SessionListParams, SessionListResult, SessionReleaseParams, SessionReleaseResult, Signal, SysinfoGetParams, SysinfoGetResult, VERSIONED_RESULT_OPS, compareVersions, epochMs, forPeer, knows, negotiate, nonNegInt, u32 };
+export { AbsPath, DEFAULT_MAX_FRAME_PAYLOAD_BYTES, DEFAULT_MAX_MESSAGE_BYTES, DEFAULT_WINDOW_BYTES, DeviceId, ExecCwdEvent, ExecExitedEvent, ExecListParams, ExecListResult, ExecPtyKillParams, ExecPtyKillResult, ExecPtyResizeParams, ExecPtyResizeResult, ExecPtySignalParams, ExecPtySignalResult, ExecPtyStartParams, ExecPtyStartResult, ExecPtyWriteParams, ExecPtyWriteResult, ExecRunParams, ExecRunResult, ExecTitleEvent, FIELDS_SINCE, type FieldsSincePath, FrameHeader, FsChange, FsChangedEvent, FsDeleteParams, FsDeleteResult, FsEncoding, FsEntry, FsKind, FsListParams, FsListResult, FsMkdirParams, FsMkdirResult, FsMoveParams, FsMoveResult, FsPatchEditApplied, FsPatchParams, FsPatchResult, FsReadParams, FsReadResult, FsReadStreamParams, FsReadStreamResult, FsSearchContentParams, FsSearchContentResult, FsSearchPathsParams, FsSearchPathsResult, FsStatParams, FsStatResult, FsWatchParams, FsWatchResult, FsWriteParams, FsWriteResult, NULL_SINCE, OpName, OsPermissionName, PROTOCOL_MAJOR, PROTOCOL_MINOR, PROTOCOL_VERSION, ProtocolVersion, PtyInfo, RELAY_CALL_HELLO_ID, RELAY_CALL_REQUEST_ID, RELAY_CALL_VERSION_HEADER, RelayAuthExpiringEvent, RelayCallEnvelope, RelayCallHello, RelayCallRequest, RelayCallResponse, RelayDeviceStatusEvent, RelayHopConnectionEnd, RelayHopEnvelopeHeader, RelayStatusResponse, RequestId, ResourceId, ResourceInfo, SessionAttachParams, SessionAttachResult, SessionControlChangedEvent, SessionDetachParams, SessionDetachResult, SessionListParams, SessionListResult, SessionReleaseParams, SessionReleaseResult, Signal, SysinfoGetParams, SysinfoGetResult, VERSIONED_RESULT_OPS, announcedVersion, compareVersions, epochMs, forPeer, knows, negotiate, nonNegInt, statusForPeer, u32, versionSubprotocol };

package/dist/index.js

@@ -638,7 +638,11 @@ var SessionControlChangedEvent = z8.strictObject({ controller_client_id: z8.stri
 import { z as z9 } from "zod";
 var RelayDeviceStatusEvent = z9.strictObject({
   online: z9.boolean(),
-  since_ms: epochMs,
+  /**
+   * 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(),
   protocol_version: ProtocolVersion.nullable()
 });
@@ -825,6 +829,24 @@ var FIELDS_SINCE = {
   "RelayCallResponse|0": { protocol_version: "1.1" },
   "RelayCallResponse|1": { protocol_version: "1.1" }
 };
+var NULL_SINCE = {
+  "RelayDeviceStatusEvent.since_ms": { since: "1.1", olderPeersGet: 0 }
+};
+function statusForPeer(status, version) {
+  const rule = NULL_SINCE["RelayDeviceStatusEvent.since_ms"];
+  return status.since_ms === null && !knows(version, rule.since) ? { ...status, since_ms: rule.olderPeersGet } : status;
+}
+function versionSubprotocol(version) {
+  return `matrx.v${version}`;
+}
+function announcedVersion(offered) {
+  let best = `${PROTOCOL_MAJOR}.0`;
+  for (const p of offered) {
+    const m = /^matrx\.v(\d+\.\d+)$/.exec(p.trim());
+    if (m?.[1] && compareVersions(m[1], best) > 0 && m[1].startsWith(`${PROTOCOL_MAJOR}.`)) best = m[1];
+  }
+  return best;
+}
 function compareVersions(a, b) {
   const [am = 0, an = 0] = a.split(".").map(Number);
   const [bm = 0, bn = 0] = b.split(".").map(Number);
@@ -862,10 +884,37 @@ function forPeer(op, part, value, version) {
   return data === body.data ? value : { ...body, data };
 }
 var VERSIONED_RESULT_OPS = [...RESULT_PATH.keys()];
+
+// 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;
+}
+function isTerminalClose(code) {
+  return closeRule(code).action === "stop";
+}
 export {
   AbsPath,
   BEARER_PREFIX,
   BROADCAST_CID,
+  CLOSE_RULES,
   CancelMsg,
   ClientToCoreMsg,
   ClientType,
@@ -943,6 +992,7 @@ export {
   HelloMsg,
   Limits,
   NAMED_SCHEMAS,
+  NULL_SINCE,
   OPS,
   OpDescriptor,
   OsPermissionName,
@@ -989,7 +1039,9 @@ export {
   SysinfoGetResult,
   VERSIONED_RESULT_OPS,
   Welcome,
+  announcedVersion,
   assertFrameHeader,
+  closeRule,
   compareVersions,
   connectionEndFrame,
   decodeFrame,
@@ -999,11 +1051,14 @@ export {
   hasFlag,
   isConnectionEnd,
   isDesktopProtocolError,
+  isTerminalClose,
   knows,
   negotiate,
   nonNegInt,
   readCid,
   stampCid,
-  u32
+  statusForPeer,
+  u32,
+  versionSubprotocol
 };
 //# sourceMappingURL=index.js.map