@ai-matrx/desktop-protocol 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,13 +1,19 @@
 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, 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, F as SUBPROTOCOL, S as StreamMeta, G as StreamMsg, W as Welcome, i as isDesktopProtocolError } from './registry-DQ5_mP_5.cjs';
+import { O as OpName } from './registry-BeY9D7h0.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-BeY9D7h0.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.
+ */
+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;
@@ -366,13 +372,43 @@ declare const FsPatchParams: z.ZodObject<{
     create_if_missing: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 type FsPatchParams = z.output<typeof FsPatchParams>;
+/**
+ * = the daemon's /fs/patch answer per edit: edits apply in order, each sees the previous result; an
+ * edit whose old_text is missing, or matches more than once without replace_all, is skipped and
+ * listed in edits_failed with the daemon's reason; the file is written when at least one applied.
+ * (Every edit failing is a CONFLICT whose data.edits_failed lists them — the daemon's 422.)
+ */
 declare const FsPatchResult: z.ZodObject<{
     path: z.ZodString;
     applied: z.ZodInt;
     size: z.ZodInt;
     mtime_ms: z.ZodInt;
+    edits_applied: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        edit_index: z.ZodInt;
+        mode: z.ZodEnum<{
+            replace_all: "replace_all";
+            create: "create";
+            replace: "replace";
+        }>;
+        matches_replaced: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>>;
+    edits_failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        edit_index: z.ZodInt;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type FsPatchResult = z.output<typeof FsPatchResult>;
+/** One edit fs.patch applied — the daemon's `edits_applied[]` entry, verbatim. */
+declare const FsPatchEditApplied: z.ZodObject<{
+    edit_index: z.ZodInt;
+    mode: z.ZodEnum<{
+        replace_all: "replace_all";
+        create: "create";
+        replace: "replace";
+    }>;
+    matches_replaced: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+type FsPatchEditApplied = z.output<typeof FsPatchEditApplied>;
 /** = daemon SearchPathRequest (/search/paths). */
 declare const FsSearchPathsParams: z.ZodObject<{
     pattern: z.ZodString;
@@ -871,6 +907,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"
@@ -900,6 +941,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<{
@@ -950,6 +992,10 @@ declare const RelayCallResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
             settings_url: z.ZodOptional<z.ZodString>;
             retry_after_ms: z.ZodOptional<z.ZodInt>;
             limit_bytes: z.ZodOptional<z.ZodInt>;
+            edits_failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                edit_index: z.ZodInt;
+                reason: z.ZodString;
+            }, z.core.$strict>>>;
             upgrade: z.ZodOptional<z.ZodObject<{
                 min_version: z.ZodString;
                 max_version: z.ZodString;
@@ -957,6 +1003,7 @@ 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). */
@@ -984,4 +1031,53 @@ 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, 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.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, 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 };

package/dist/index.d.ts

@@ -1,13 +1,19 @@
 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, 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, F as SUBPROTOCOL, S as StreamMeta, G as StreamMsg, W as Welcome, i as isDesktopProtocolError } from './registry-DQ5_mP_5.js';
+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';
 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.
+ */
+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;
@@ -366,13 +372,43 @@ declare const FsPatchParams: z.ZodObject<{
     create_if_missing: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 type FsPatchParams = z.output<typeof FsPatchParams>;
+/**
+ * = the daemon's /fs/patch answer per edit: edits apply in order, each sees the previous result; an
+ * edit whose old_text is missing, or matches more than once without replace_all, is skipped and
+ * listed in edits_failed with the daemon's reason; the file is written when at least one applied.
+ * (Every edit failing is a CONFLICT whose data.edits_failed lists them — the daemon's 422.)
+ */
 declare const FsPatchResult: z.ZodObject<{
     path: z.ZodString;
     applied: z.ZodInt;
     size: z.ZodInt;
     mtime_ms: z.ZodInt;
+    edits_applied: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        edit_index: z.ZodInt;
+        mode: z.ZodEnum<{
+            replace_all: "replace_all";
+            create: "create";
+            replace: "replace";
+        }>;
+        matches_replaced: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>>;
+    edits_failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        edit_index: z.ZodInt;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type FsPatchResult = z.output<typeof FsPatchResult>;
+/** One edit fs.patch applied — the daemon's `edits_applied[]` entry, verbatim. */
+declare const FsPatchEditApplied: z.ZodObject<{
+    edit_index: z.ZodInt;
+    mode: z.ZodEnum<{
+        replace_all: "replace_all";
+        create: "create";
+        replace: "replace";
+    }>;
+    matches_replaced: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+type FsPatchEditApplied = z.output<typeof FsPatchEditApplied>;
 /** = daemon SearchPathRequest (/search/paths). */
 declare const FsSearchPathsParams: z.ZodObject<{
     pattern: z.ZodString;
@@ -871,6 +907,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"
@@ -900,6 +941,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<{
@@ -950,6 +992,10 @@ declare const RelayCallResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
             settings_url: z.ZodOptional<z.ZodString>;
             retry_after_ms: z.ZodOptional<z.ZodInt>;
             limit_bytes: z.ZodOptional<z.ZodInt>;
+            edits_failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                edit_index: z.ZodInt;
+                reason: z.ZodString;
+            }, z.core.$strict>>>;
             upgrade: z.ZodOptional<z.ZodObject<{
                 min_version: z.ZodString;
                 max_version: z.ZodString;
@@ -957,6 +1003,7 @@ 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). */
@@ -984,4 +1031,53 @@ 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, 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.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, 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 };

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_-]+$/);
@@ -62,6 +62,7 @@ var ErrorReason = z2.enum([
   // another client of the same user took control
   "window_exhausted"
 ]);
+var FsPatchEditFailure = z2.strictObject({ edit_index: nonNegInt, reason: z2.string().max(300) });
 var ProtocolErrorBody = z2.strictObject({
   code: ErrorCode,
   message: z2.string().max(300),
@@ -76,6 +77,8 @@ var ProtocolErrorBody = z2.strictObject({
     // PERMISSION_DENIED_OS deep link
     retry_after_ms: nonNegInt.optional(),
     limit_bytes: nonNegInt.optional(),
+    /** fs.patch when every edit failed (CONFLICT, patch_no_match / patch_ambiguous): the daemon's 422 `failures`. */
+    edits_failed: z2.array(FsPatchEditFailure).max(256).optional(),
     upgrade: z2.strictObject({
       min_version: ProtocolVersion,
       max_version: ProtocolVersion,
@@ -481,7 +484,22 @@ var FsPatchParams = z6.strictObject({
   ).min(1).max(256),
   create_if_missing: z6.boolean().default(false)
 });
-var FsPatchResult = z6.strictObject({ path: AbsPath, applied: nonNegInt, size: nonNegInt, mtime_ms: epochMs });
+var FsPatchEditApplied = z6.strictObject({
+  edit_index: nonNegInt,
+  mode: z6.enum(["create", "replace", "replace_all"]),
+  /** Present for replace_all only, as the daemon sends it. */
+  matches_replaced: nonNegInt.optional()
+});
+var FsPatchResult = z6.strictObject({
+  path: AbsPath,
+  applied: nonNegInt,
+  size: nonNegInt,
+  mtime_ms: epochMs,
+  /** 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),
   cwd: AbsPath,
@@ -631,9 +649,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";
@@ -698,6 +727,7 @@ var NAMED_SCHEMAS = {
   AbsPath,
   ErrorCode,
   ErrorReason,
+  FsPatchEditFailure,
   ProtocolErrorBody,
   FrameHeader,
   ClientType,
@@ -741,6 +771,7 @@ var NAMED_SCHEMAS = {
   FsDeleteResult,
   FsWatchParams,
   FsWatchResult,
+  FsPatchEditApplied,
   FsPatchParams,
   FsPatchResult,
   FsSearchPathsParams,
@@ -786,6 +817,51 @@ 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" }
+};
+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,
@@ -826,6 +902,7 @@ export {
   ExecRunParams,
   ExecRunResult,
   ExecTitleEvent,
+  FIELDS_SINCE,
   FRAME_HEADER_BYTES,
   FRAME_STRUCT_FORMAT,
   FRAME_VERSION,
@@ -845,6 +922,8 @@ export {
   FsMkdirResult,
   FsMoveParams,
   FsMoveResult,
+  FsPatchEditApplied,
+  FsPatchEditFailure,
   FsPatchParams,
   FsPatchResult,
   FsReadParams,
@@ -877,6 +956,7 @@ export {
   PtyInfo,
   RELAY_CALL_HELLO_ID,
   RELAY_CALL_REQUEST_ID,
+  RELAY_CALL_VERSION_HEADER,
   RelayAuthExpiringEvent,
   RelayCallEnvelope,
   RelayCallHello,
@@ -907,15 +987,20 @@ export {
   StreamMsg,
   SysinfoGetParams,
   SysinfoGetResult,
+  VERSIONED_RESULT_OPS,
   Welcome,
   assertFrameHeader,
+  compareVersions,
   connectionEndFrame,
   decodeFrame,
   encodeFrame,
   epochMs,
+  forPeer,
   hasFlag,
   isConnectionEnd,
   isDesktopProtocolError,
+  knows,
+  negotiate,
   nonNegInt,
   readCid,
   stampCid,