@ai-matrx/desktop-protocol 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,13 +1,20 @@
 import { z } from 'zod';
-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, O as OpName, 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-CI-NpQ6L.cjs';
+import { O as OpName } from './registry-jTmq1CsI.cjs';
+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-jTmq1CsI.cjs';
 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.cjs';
 
 /** @ai-matrx/desktop-protocol — version and primitive schemas. Schema source: lint-enforced rules in scripts/check-schema-source.mjs. */
 
 declare const PROTOCOL_MAJOR: 1;
-declare const PROTOCOL_MINOR: 0;
+/**
+ * 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;
+ *         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. */
-declare const PROTOCOL_VERSION: "1.0";
+declare const PROTOCOL_VERSION: "1.1";
 /** Internal building blocks — deliberately unnamed in $defs (inlined wherever used). */
 declare const u32: z.ZodInt;
 declare const nonNegInt: z.ZodInt;
@@ -377,7 +384,7 @@ declare const FsPatchResult: z.ZodObject<{
     applied: z.ZodInt;
     size: z.ZodInt;
     mtime_ms: z.ZodInt;
-    edits_applied: z.ZodArray<z.ZodObject<{
+    edits_applied: z.ZodOptional<z.ZodArray<z.ZodObject<{
         edit_index: z.ZodInt;
         mode: z.ZodEnum<{
             replace_all: "replace_all";
@@ -385,11 +392,11 @@ declare const FsPatchResult: z.ZodObject<{
             replace: "replace";
         }>;
         matches_replaced: z.ZodOptional<z.ZodInt>;
-    }, z.core.$strict>>;
-    edits_failed: z.ZodArray<z.ZodObject<{
+    }, z.core.$strict>>>;
+    edits_failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
         edit_index: z.ZodInt;
         reason: z.ZodString;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type FsPatchResult = z.output<typeof FsPatchResult>;
 /** One edit fs.patch applied — the daemon's `edits_applied[]` entry, verbatim. */
@@ -901,6 +908,11 @@ type SessionControlChangedEvent = z.output<typeof SessionControlChangedEvent>;
 
 /** @ai-matrx/desktop-protocol — cap relay. Schema source: lint-enforced rules in scripts/check-schema-source.mjs. */
 
+/**
+ * The caller of /call announces the newest protocol it reads in this request header; the relay
+ * includes fields newer than 1.0 only when the announced version knows them (src/versioning.ts).
+ */
+declare const RELAY_CALL_VERSION_HEADER: "x-matrx-protocol-version";
 /**
  * How the relay runs one /call on the device: a fresh cid (its own connection) carrying exactly
  * RelayCallHello then RelayCallEnvelope, answered on that cid by response/error with id "call"
@@ -910,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>;
@@ -930,6 +942,7 @@ type RelayCallRequest = z.output<typeof RelayCallRequest>;
 declare const RelayCallResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
     ok: z.ZodLiteral<true>;
     result: z.ZodUnknown;
+    protocol_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     ok: z.ZodLiteral<false>;
     error: z.ZodObject<{
@@ -991,12 +1004,13 @@ declare const RelayCallResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
+    protocol_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "ok">;
 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>;
@@ -1018,4 +1032,75 @@ declare const RelayCallEnvelope: z.ZodObject<{
 }, z.core.$strict>;
 type RelayCallEnvelope = z.output<typeof RelayCallEnvelope>;
 
-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, 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, OsPermissionName, PROTOCOL_MAJOR, PROTOCOL_MINOR, PROTOCOL_VERSION, ProtocolVersion, PtyInfo, RELAY_CALL_HELLO_ID, RELAY_CALL_REQUEST_ID, RelayAuthExpiringEvent, RelayCallEnvelope, RelayCallHello, RelayCallRequest, RelayCallResponse, RelayDeviceStatusEvent, RelayHopConnectionEnd, RelayHopEnvelopeHeader, RelayStatusResponse, RequestId, ResourceId, ResourceInfo, SessionAttachParams, SessionAttachResult, SessionControlChangedEvent, SessionDetachParams, SessionDetachResult, SessionListParams, SessionListResult, SessionReleaseParams, SessionReleaseResult, Signal, SysinfoGetParams, SysinfoGetResult, epochMs, nonNegInt, u32 };
+/**
+ * Version skew is the normal state: a phone, the server and a desktop app in the field run
+ * different package versions, and a minor protocol bump must never make any of them fail.
+ *
+ * THE RULE (enforced by src/versioning.test.ts against generated/baseline-1.0.json):
+ *   1. Within a major, a minor may only ADD. A field added after x.0 is OPTIONAL in the schema
+ *      (an older peer omits it) and is listed in FIELDS_SINCE with the minor that added it.
+ *   2. A writer never sends a field newer than the version its peer negotiated (hello/welcome, or
+ *      the /call version header): older peers' strict schemas refuse unknown keys. `forPeer`
+ *      does the stripping; the core's Router applies it to every result and error it sends.
+ *   3. A reader that needs a newer field checks the peer's version and says so loudly when the
+ *      peer is older (e.g. aidream's local_proxy marks a patch answer from a 1.0 app).
+ */
+
+/**
+ * Fields added after x.0, by schema location: a named schema (`FsPatchResult`), a property path
+ * inside one (`ProtocolErrorBody.data`), or a union branch (`RelayCallResponse|0`).
+ */
+declare const FIELDS_SINCE: {
+    readonly FsPatchResult: {
+        readonly edits_applied: "1.1";
+        readonly edits_failed: "1.1";
+    };
+    readonly "ProtocolErrorBody.data": {
+        readonly edits_failed: "1.1";
+    };
+    readonly "RelayCallResponse|0": {
+        readonly protocol_version: "1.1";
+    };
+    readonly "RelayCallResponse|1": {
+        readonly protocol_version: "1.1";
+    };
+};
+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`. */
+declare function knows(version: string, since: string): boolean;
+/** The version two peers speak: the lower minor within this major. */
+declare function negotiate(peerVersion: string): string;
+/**
+ * What to send a peer that negotiated `version`: `result` of `op`, or an error body, with every
+ * field newer than that version removed (rule 2). Unchanged for a current peer.
+ */
+declare function forPeer(op: OpName, part: "result", value: unknown, version: string): unknown;
+declare function forPeer(op: OpName | null, part: "error", value: unknown, version: string): unknown;
+/** 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, 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.d.ts

@@ -1,13 +1,20 @@
 import { z } from 'zod';
-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, O as OpName, 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-CI-NpQ6L.js';
+import { O as OpName } from './registry-jTmq1CsI.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-jTmq1CsI.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. */
 
 declare const PROTOCOL_MAJOR: 1;
-declare const PROTOCOL_MINOR: 0;
+/**
+ * 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;
+ *         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. */
-declare const PROTOCOL_VERSION: "1.0";
+declare const PROTOCOL_VERSION: "1.1";
 /** Internal building blocks — deliberately unnamed in $defs (inlined wherever used). */
 declare const u32: z.ZodInt;
 declare const nonNegInt: z.ZodInt;
@@ -377,7 +384,7 @@ declare const FsPatchResult: z.ZodObject<{
     applied: z.ZodInt;
     size: z.ZodInt;
     mtime_ms: z.ZodInt;
-    edits_applied: z.ZodArray<z.ZodObject<{
+    edits_applied: z.ZodOptional<z.ZodArray<z.ZodObject<{
         edit_index: z.ZodInt;
         mode: z.ZodEnum<{
             replace_all: "replace_all";
@@ -385,11 +392,11 @@ declare const FsPatchResult: z.ZodObject<{
             replace: "replace";
         }>;
         matches_replaced: z.ZodOptional<z.ZodInt>;
-    }, z.core.$strict>>;
-    edits_failed: z.ZodArray<z.ZodObject<{
+    }, z.core.$strict>>>;
+    edits_failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
         edit_index: z.ZodInt;
         reason: z.ZodString;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type FsPatchResult = z.output<typeof FsPatchResult>;
 /** One edit fs.patch applied — the daemon's `edits_applied[]` entry, verbatim. */
@@ -901,6 +908,11 @@ type SessionControlChangedEvent = z.output<typeof SessionControlChangedEvent>;
 
 /** @ai-matrx/desktop-protocol — cap relay. Schema source: lint-enforced rules in scripts/check-schema-source.mjs. */
 
+/**
+ * The caller of /call announces the newest protocol it reads in this request header; the relay
+ * includes fields newer than 1.0 only when the announced version knows them (src/versioning.ts).
+ */
+declare const RELAY_CALL_VERSION_HEADER: "x-matrx-protocol-version";
 /**
  * How the relay runs one /call on the device: a fresh cid (its own connection) carrying exactly
  * RelayCallHello then RelayCallEnvelope, answered on that cid by response/error with id "call"
@@ -910,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>;
@@ -930,6 +942,7 @@ type RelayCallRequest = z.output<typeof RelayCallRequest>;
 declare const RelayCallResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
     ok: z.ZodLiteral<true>;
     result: z.ZodUnknown;
+    protocol_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     ok: z.ZodLiteral<false>;
     error: z.ZodObject<{
@@ -991,12 +1004,13 @@ declare const RelayCallResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
+    protocol_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "ok">;
 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>;
@@ -1018,4 +1032,75 @@ declare const RelayCallEnvelope: z.ZodObject<{
 }, z.core.$strict>;
 type RelayCallEnvelope = z.output<typeof RelayCallEnvelope>;
 
-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, 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, OsPermissionName, PROTOCOL_MAJOR, PROTOCOL_MINOR, PROTOCOL_VERSION, ProtocolVersion, PtyInfo, RELAY_CALL_HELLO_ID, RELAY_CALL_REQUEST_ID, RelayAuthExpiringEvent, RelayCallEnvelope, RelayCallHello, RelayCallRequest, RelayCallResponse, RelayDeviceStatusEvent, RelayHopConnectionEnd, RelayHopEnvelopeHeader, RelayStatusResponse, RequestId, ResourceId, ResourceInfo, SessionAttachParams, SessionAttachResult, SessionControlChangedEvent, SessionDetachParams, SessionDetachResult, SessionListParams, SessionListResult, SessionReleaseParams, SessionReleaseResult, Signal, SysinfoGetParams, SysinfoGetResult, epochMs, nonNegInt, u32 };
+/**
+ * Version skew is the normal state: a phone, the server and a desktop app in the field run
+ * different package versions, and a minor protocol bump must never make any of them fail.
+ *
+ * THE RULE (enforced by src/versioning.test.ts against generated/baseline-1.0.json):
+ *   1. Within a major, a minor may only ADD. A field added after x.0 is OPTIONAL in the schema
+ *      (an older peer omits it) and is listed in FIELDS_SINCE with the minor that added it.
+ *   2. A writer never sends a field newer than the version its peer negotiated (hello/welcome, or
+ *      the /call version header): older peers' strict schemas refuse unknown keys. `forPeer`
+ *      does the stripping; the core's Router applies it to every result and error it sends.
+ *   3. A reader that needs a newer field checks the peer's version and says so loudly when the
+ *      peer is older (e.g. aidream's local_proxy marks a patch answer from a 1.0 app).
+ */
+
+/**
+ * Fields added after x.0, by schema location: a named schema (`FsPatchResult`), a property path
+ * inside one (`ProtocolErrorBody.data`), or a union branch (`RelayCallResponse|0`).
+ */
+declare const FIELDS_SINCE: {
+    readonly FsPatchResult: {
+        readonly edits_applied: "1.1";
+        readonly edits_failed: "1.1";
+    };
+    readonly "ProtocolErrorBody.data": {
+        readonly edits_failed: "1.1";
+    };
+    readonly "RelayCallResponse|0": {
+        readonly protocol_version: "1.1";
+    };
+    readonly "RelayCallResponse|1": {
+        readonly protocol_version: "1.1";
+    };
+};
+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`. */
+declare function knows(version: string, since: string): boolean;
+/** The version two peers speak: the lower minor within this major. */
+declare function negotiate(peerVersion: string): string;
+/**
+ * What to send a peer that negotiated `version`: `result` of `op`, or an error body, with every
+ * field newer than that version removed (rule 2). Unchanged for a current peer.
+ */
+declare function forPeer(op: OpName, part: "result", value: unknown, version: string): unknown;
+declare function forPeer(op: OpName | null, part: "error", value: unknown, version: string): unknown;
+/** 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, 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

@@ -1,7 +1,7 @@
 // src/schema/primitives.ts
 import { z } from "zod";
 var PROTOCOL_MAJOR = 1;
-var PROTOCOL_MINOR = 0;
+var PROTOCOL_MINOR = 1;
 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_-]+$/);
@@ -495,8 +495,10 @@ var FsPatchResult = z6.strictObject({
   applied: nonNegInt,
   size: nonNegInt,
   mtime_ms: epochMs,
-  edits_applied: z6.array(FsPatchEditApplied).max(256),
-  edits_failed: z6.array(FsPatchEditFailure).max(256)
+  /** Since 1.1 (FIELDS_SINCE): a 1.0 app sends only `applied`. Always sent to a ≥1.1 peer. */
+  edits_applied: z6.array(FsPatchEditApplied).max(256).optional(),
+  /** Since 1.1 (FIELDS_SINCE). */
+  edits_failed: z6.array(FsPatchEditFailure).max(256).optional()
 });
 var FsSearchPathsParams = z6.strictObject({
   pattern: z6.string().min(1).max(512),
@@ -636,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()
 });
@@ -647,9 +653,20 @@ var RelayCallRequest = z9.strictObject({
   params: z9.unknown(),
   timeout_ms: z9.int().min(100).max(37e5).default(7e4)
 });
+var RELAY_CALL_VERSION_HEADER = "x-matrx-protocol-version";
 var RelayCallResponse = z9.discriminatedUnion("ok", [
-  z9.strictObject({ ok: z9.literal(true), result: z9.unknown() }),
-  z9.strictObject({ ok: z9.literal(false), error: ProtocolErrorBody })
+  z9.strictObject({
+    ok: z9.literal(true),
+    result: z9.unknown(),
+    /** Since 1.1: the version the device negotiated for this call (its welcome). */
+    protocol_version: ProtocolVersion.optional()
+  }),
+  z9.strictObject({
+    ok: z9.literal(false),
+    error: ProtocolErrorBody,
+    /** Since 1.1, as above (absent when the device never answered hello). */
+    protocol_version: ProtocolVersion.optional()
+  })
 ]);
 var RELAY_CALL_HELLO_ID = "hello";
 var RELAY_CALL_REQUEST_ID = "call";
@@ -804,6 +821,69 @@ var NAMED_SCHEMAS = {
   RelayHopConnectionEnd,
   CloseCodeValue
 };
+
+// src/versioning.ts
+var FIELDS_SINCE = {
+  FsPatchResult: { edits_applied: "1.1", edits_failed: "1.1" },
+  "ProtocolErrorBody.data": { edits_failed: "1.1" },
+  "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);
+  return am - bm || an - bn;
+}
+function knows(version, since) {
+  return compareVersions(version, since) >= 0;
+}
+function negotiate(peerVersion) {
+  const [major = 0, minor = 0] = peerVersion.split(".").map(Number);
+  if (major !== PROTOCOL_MAJOR) return `${PROTOCOL_MAJOR}.0`;
+  return `${PROTOCOL_MAJOR}.${Math.min(minor, PROTOCOL_MINOR)}`;
+}
+function strip(value, fields, version) {
+  if (!fields || value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  let out = null;
+  for (const [field, since] of Object.entries(fields)) {
+    if (field in value && !knows(version, since)) {
+      out ??= { ...value };
+      delete out[field];
+    }
+  }
+  return out ?? value;
+}
+var RESULT_PATH = /* @__PURE__ */ new Map([["fs.patch", "FsPatchResult"]]);
+function forPeer(op, part, value, version) {
+  if (part === "result") {
+    const path = op ? RESULT_PATH.get(op) : void 0;
+    return path ? strip(value, FIELDS_SINCE[path], version) : value;
+  }
+  if (value === null || typeof value !== "object") return value;
+  const body = value;
+  if (body.data === void 0) return value;
+  const data = strip(body.data, FIELDS_SINCE["ProtocolErrorBody.data"], version);
+  return data === body.data ? value : { ...body, data };
+}
+var VERSIONED_RESULT_OPS = [...RESULT_PATH.keys()];
 export {
   AbsPath,
   BEARER_PREFIX,
@@ -844,6 +924,7 @@ export {
   ExecRunParams,
   ExecRunResult,
   ExecTitleEvent,
+  FIELDS_SINCE,
   FRAME_HEADER_BYTES,
   FRAME_STRUCT_FORMAT,
   FRAME_VERSION,
@@ -884,6 +965,7 @@ export {
   HelloMsg,
   Limits,
   NAMED_SCHEMAS,
+  NULL_SINCE,
   OPS,
   OpDescriptor,
   OsPermissionName,
@@ -897,6 +979,7 @@ export {
   PtyInfo,
   RELAY_CALL_HELLO_ID,
   RELAY_CALL_REQUEST_ID,
+  RELAY_CALL_VERSION_HEADER,
   RelayAuthExpiringEvent,
   RelayCallEnvelope,
   RelayCallHello,
@@ -927,18 +1010,26 @@ export {
   StreamMsg,
   SysinfoGetParams,
   SysinfoGetResult,
+  VERSIONED_RESULT_OPS,
   Welcome,
+  announcedVersion,
   assertFrameHeader,
+  compareVersions,
   connectionEndFrame,
   decodeFrame,
   encodeFrame,
   epochMs,
+  forPeer,
   hasFlag,
   isConnectionEnd,
   isDesktopProtocolError,
+  knows,
+  negotiate,
   nonNegInt,
   readCid,
   stampCid,
-  u32
+  statusForPeer,
+  u32,
+  versionSubprotocol
 };
 //# sourceMappingURL=index.js.map