@peers-app/peers-sdk 0.28.12 → 0.29.0

package/dist/contracts/index.d.ts

@@ -14,7 +14,7 @@ export { hostContractConsumer, type IHostContractConsumer, type IHostContractCon
 export { getHostContractTransport, type HostContractTransportListener, registerHostContractTransport, subscribeHostContractTransport, waitForHostContractTransport, } from "./host-contract-transport";
 export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry, type IContractProviderRegistration } from "./registry";
-export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type IRemoteContractHost, type IRemoteContractTarget, type RemoteContractTransportFactory, resolveRemoteTargetEndpoint, setRemoteContractTransportFactory, } from "./remote-contract-transport";
+export { connectToRemoteDevice, createRemoteContractEndpoint, getRemoteContractTransportFactory, type IRemoteContractHost, type IRemoteContractTarget, type RemoteContractTransportFactory, type RemoteDeviceConnector, resolveRemoteTargetEndpoint, setRemoteContractTransportFactory, setRemoteDeviceConnector, } from "./remote-contract-transport";
 export * from "./system/app-updates-contract";
 export { CONTRACT_CATALOG_VERSION, contractCatalogProviderPackageId, getContractCatalogDefinition, type IContractCatalogConsumer, type IContractDefinitionWithPolicy, type IContractProviderInfo, type IContractToolPolicy, type IExposedContractInfo, type IExposedToolInfo, type IGetContractDefinitionInput, type IListContractProvidersInput, } from "./system/contract-catalog-contract";
 export * from "./system/desktop-tools-contract";

package/dist/contracts/index.js

@@ -15,8 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.hostContractConsumer = exports.hostContract = exports.freezeContracts = exports.FROZEN_CONTRACTS_FILE = exports.describeFrozenContractChanges = exports.checkFrozenContracts = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.isLocalOnlyContractId = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.requireWorkflowRunContext = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.RetiredContractProviderEndpointError = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.listSystemContracts = exports.isSystemContractId = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.schedulerProviderPackageId = exports.SCHEDULER_MAX_DELAY_MS = exports.SCHEDULER_CONTRACT_VERSION = exports.getSchedulerContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_HAVE_BATCH = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BYTES = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BLOCKS = exports.LOCAL_FOLDERS_CONTRACT_VERSION = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.LOCAL_FOLDERS_ASSEMBLE_STALL_MS = exports.getLocalFoldersContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.httpProviderPackageId = exports.HTTP_MAX_TIMEOUT_MS = exports.HTTP_MAX_BODY_BYTES = exports.HTTP_DEFAULT_TIMEOUT_MS = exports.HTTP_CONTRACT_VERSION = exports.getHttpContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.getContractCatalogDefinition = exports.contractCatalogProviderPackageId = exports.CONTRACT_CATALOG_VERSION = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractShapeChanges = exports.contractKey = exports.registerSystemContract = void 0;
+exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.schedulerProviderPackageId = exports.SCHEDULER_MAX_DELAY_MS = exports.SCHEDULER_CONTRACT_VERSION = exports.getSchedulerContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_HAVE_BATCH = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BYTES = exports.LOCAL_FOLDERS_GETBLOCKS_MAX_BLOCKS = exports.LOCAL_FOLDERS_CONTRACT_VERSION = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.LOCAL_FOLDERS_ASSEMBLE_STALL_MS = exports.getLocalFoldersContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.httpProviderPackageId = exports.HTTP_MAX_TIMEOUT_MS = exports.HTTP_MAX_BODY_BYTES = exports.HTTP_DEFAULT_TIMEOUT_MS = exports.HTTP_CONTRACT_VERSION = exports.getHttpContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.getContractCatalogDefinition = exports.contractCatalogProviderPackageId = exports.CONTRACT_CATALOG_VERSION = exports.setRemoteDeviceConnector = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = exports.connectToRemoteDevice = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractShapeChanges = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.isSystemContractId = void 0;
 __exportStar(require("./action-dispatch"), exports);
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
@@ -84,10 +84,12 @@ Object.defineProperty(exports, "PersistentContractRegistry", { enumerable: true,
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "ContractRegistry", { enumerable: true, get: function () { return registry_1.ContractRegistry; } });
 var remote_contract_transport_1 = require("./remote-contract-transport");
+Object.defineProperty(exports, "connectToRemoteDevice", { enumerable: true, get: function () { return remote_contract_transport_1.connectToRemoteDevice; } });
 Object.defineProperty(exports, "createRemoteContractEndpoint", { enumerable: true, get: function () { return remote_contract_transport_1.createRemoteContractEndpoint; } });
 Object.defineProperty(exports, "getRemoteContractTransportFactory", { enumerable: true, get: function () { return remote_contract_transport_1.getRemoteContractTransportFactory; } });
 Object.defineProperty(exports, "resolveRemoteTargetEndpoint", { enumerable: true, get: function () { return remote_contract_transport_1.resolveRemoteTargetEndpoint; } });
 Object.defineProperty(exports, "setRemoteContractTransportFactory", { enumerable: true, get: function () { return remote_contract_transport_1.setRemoteContractTransportFactory; } });
+Object.defineProperty(exports, "setRemoteDeviceConnector", { enumerable: true, get: function () { return remote_contract_transport_1.setRemoteDeviceConnector; } });
 __exportStar(require("./system/app-updates-contract"), exports);
 var contract_catalog_contract_1 = require("./system/contract-catalog-contract");
 Object.defineProperty(exports, "CONTRACT_CATALOG_VERSION", { enumerable: true, get: function () { return contract_catalog_contract_1.CONTRACT_CATALOG_VERSION; } });

package/dist/contracts/remote-contract-transport.d.ts

@@ -43,6 +43,33 @@ export declare function setRemoteContractTransportFactory(factory: RemoteContrac
  * @param userContext Optional owning user context.
  */
 export declare function getRemoteContractTransportFactory(userContext?: UserContext): RemoteContractTransportFactory | undefined;
+/**
+ * Host-registered function that asks for a direct connection to one device, for a caller about
+ * to make calls that benefit from one (a large transfer, say). Calls never dial on their own:
+ * they use a direct connection when one exists and the mesh otherwise.
+ *
+ * Resolves `true` when a verified direct connection to `target.deviceId` exists, `false` when
+ * none could be made in time (unreachable, no free connection slot, a recent failed attempt).
+ * Never rejects for an unreachable device, and promises nothing about how long the connection
+ * stays up. Only devices that share `target.dataContextId` answer.
+ */
+export type RemoteDeviceConnector = (target: IRemoteContractTarget) => Promise<boolean>;
+/**
+ * Register (or clear, with `undefined`) the {@link RemoteDeviceConnector} for one user context.
+ * A connection manager registers its own beside its transport factory.
+ *
+ * @param connector Connector, or `undefined` to unregister.
+ * @param userContext Owning user context.
+ */
+export declare function setRemoteDeviceConnector(connector: RemoteDeviceConnector | undefined, userContext: UserContext): void;
+/**
+ * Ask for a direct connection to `target.deviceId` through the connector registered for
+ * `userContext`. Resolves `false` when none is registered (a host without device connections).
+ *
+ * @param target Device to connect to, and the data context it must share.
+ * @param userContext Owning user context.
+ */
+export declare function connectToRemoteDevice(target: IRemoteContractTarget, userContext: UserContext | undefined): Promise<boolean>;
 /**
  * Shared chokepoint for trusted local hosts: when an authorized route names a device
  * other than this one, return a forwarding endpoint; otherwise return `undefined` so the

package/dist/contracts/remote-contract-transport.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setRemoteContractTransportFactory = setRemoteContractTransportFactory;
 exports.getRemoteContractTransportFactory = getRemoteContractTransportFactory;
+exports.setRemoteDeviceConnector = setRemoteDeviceConnector;
+exports.connectToRemoteDevice = connectToRemoteDevice;
 exports.resolveRemoteTargetEndpoint = resolveRemoteTargetEndpoint;
 exports.createRemoteContractEndpoint = createRemoteContractEndpoint;
 const contract_transport_1 = require("./contract-transport");
@@ -47,6 +49,31 @@ function setRemoteContractTransportFactory(factory, opts = {}) {
 function getRemoteContractTransportFactory(userContext) {
     return (userContext && factoriesByUserContext.get(userContext)) ?? defaultFactory;
 }
+const connectorsByUserContext = new WeakMap();
+/**
+ * Register (or clear, with `undefined`) the {@link RemoteDeviceConnector} for one user context.
+ * A connection manager registers its own beside its transport factory.
+ *
+ * @param connector Connector, or `undefined` to unregister.
+ * @param userContext Owning user context.
+ */
+function setRemoteDeviceConnector(connector, userContext) {
+    if (connector)
+        connectorsByUserContext.set(userContext, connector);
+    else
+        connectorsByUserContext.delete(userContext);
+}
+/**
+ * Ask for a direct connection to `target.deviceId` through the connector registered for
+ * `userContext`. Resolves `false` when none is registered (a host without device connections).
+ *
+ * @param target Device to connect to, and the data context it must share.
+ * @param userContext Owning user context.
+ */
+function connectToRemoteDevice(target, userContext) {
+    const connector = userContext && connectorsByUserContext.get(userContext);
+    return connector ? connector(target) : Promise.resolve(false);
+}
 /**
  * Shared chokepoint for trusted local hosts: when an authorized route names a device
  * other than this one, return a forwarding endpoint; otherwise return `undefined` so the

package/dist/contracts/system/network-contracts.js

@@ -158,7 +158,7 @@ function getNetworkControlContractDefinition() {
             },
             {
                 name: "connectToDevice",
-                usageDescription: "Start a connection attempt to one known device.",
+                usageDescription: "Connect directly to one known device, waiting up to 15 seconds, and report whether a direct connection exists.",
                 inputFields: deviceInput,
                 outputFields: resultFields,
             },

package/dist/define/context.d.ts

@@ -29,6 +29,15 @@ export interface IPackageContext {
     readonly deviceId: string;
     /** Run a tool on a contract this package consumes (or provides), as this call's caller. */
     callConsumedTool(contractId: string, version: number, toolName: string, args?: unknown, options?: IPackageProviderOptions): Promise<unknown>;
+    /**
+     * Ask for a direct connection to another device in this package's data context, before calls
+     * that benefit from one (a large transfer, say). Remote calls use a direct connection when one
+     * exists and the Peers mesh otherwise; they never dial on their own. Resolves `true` when a
+     * direct connection exists (at most about 15 seconds), `false` when none could be made; never
+     * rejects for an unreachable device. The connection may still drop later, and calls then go
+     * through the mesh.
+     */
+    connectToDevice(deviceId: string): Promise<boolean>;
     /** Run a tool on another device. The remote device authorizes the call. */
     callRemoteTool(contractId: string, version: number, deviceId: string, toolName: string, args?: unknown): Promise<unknown>;
     /** Subscribe to an event on a consumed or provided contract. */

package/dist/device/binary-peer-connection-v2.d.ts

@@ -5,8 +5,8 @@
  * separated modes:
  *
  * 1. **RPC mode** (emit/on): request/response interactions with automatic
- *    encoding (txEncode for objects, passthrough for Uint8Array) and transparent
- *    chunking for large payloads.
+ *    encoding (txEncode with bytes kept binary for objects, passthrough for a
+ *    top-level Uint8Array) and transparent chunking for large payloads.
  *
  * 2. **Stream mode** (sendRawBytes/onRawBytes): continuous byte transfer for
  *    file syncing, log streaming, etc. Each sendRawBytes

package/dist/device/binary-peer-connection-v2.js

@@ -6,8 +6,8 @@
  * separated modes:
  *
  * 1. **RPC mode** (emit/on): request/response interactions with automatic
- *    encoding (txEncode for objects, passthrough for Uint8Array) and transparent
- *    chunking for large payloads.
+ *    encoding (txEncode with bytes kept binary for objects, passthrough for a
+ *    top-level Uint8Array) and transparent chunking for large payloads.
  *
  * 2. **Stream mode** (sendRawBytes/onRawBytes): continuous byte transfer for
  *    file syncing, log streaming, etc. Each sendRawBytes
@@ -27,6 +27,7 @@ exports.createBinaryPeerSocket = createBinaryPeerSocket;
 exports.wrapBinaryPeer = wrapBinaryPeer;
 exports.wrapWrtc = wrapWrtc;
 const msgpack_1 = require("@msgpack/msgpack");
+const peer_device_1 = require("../types/peer-device");
 const utils_1 = require("../utils");
 const connection_1 = require("./connection");
 const frame_cipher_1 = require("./frame-cipher");
@@ -100,6 +101,8 @@ function decodeStreamId(bytes) {
     streamIdStringCache.set(key, cached);
     return cached;
 }
+/** RPC payloads carry bytes as msgpack binary, not base64 text. */
+const RPC_ENCODING = { binaryBytes: true };
 function encodeMessage(message) {
     let isUint8ArrayData = false;
     if (message.type === "call" && message.args instanceof Uint8Array) {
@@ -122,18 +125,18 @@ function encodeMessage(message) {
             dataBytes = message.args;
         }
         else {
-            dataBytes = (0, tx_encoding_1.txEncode)(message.args);
+            dataBytes = (0, tx_encoding_1.txEncode)(message.args, RPC_ENCODING);
         }
     }
     else if (message.type === "callback") {
         if (message.error !== undefined) {
-            dataBytes = (0, tx_encoding_1.txEncode)({ error: message.error });
+            dataBytes = (0, tx_encoding_1.txEncode)({ error: message.error }, RPC_ENCODING);
         }
         else if (isUint8ArrayData) {
             dataBytes = message.result;
         }
         else {
-            dataBytes = (0, tx_encoding_1.txEncode)({ result: message.result });
+            dataBytes = (0, tx_encoding_1.txEncode)({ result: message.result }, RPC_ENCODING);
         }
     }
     else {
@@ -244,7 +247,8 @@ function buildStreamCont(sidBytes, chunkData) {
  */
 function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receiveLimitOverrides = {}) {
     const handlers = {};
-    const callbacks = {};
+    /** Reply callbacks for this side's calls that are still waiting, by callback id. */
+    const callbacks = new Map();
     const rawBytesHandlers = {};
     let isClosed = false;
     const stats = (0, socket_type_1.createSocketStats)();
@@ -432,6 +436,26 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
         streamReassemblyBuffers.clear();
         inFlightReassemblyBytes = 0;
     }
+    /**
+     * Fail every call still waiting for a reply. The peer can no longer answer, so waiting would
+     * only hold each caller until its own timer fired; failing now lets it move on (a remote
+     * contract call's next attempt picks another route).
+     */
+    function rejectPendingCalls() {
+        const pending = [...callbacks.values()];
+        callbacks.clear();
+        // A transport may close synchronously from send(), inside emit().
+        queueMicrotask(() => {
+            for (const callback of pending) {
+                try {
+                    callback(new Error(peer_device_1.CONNECTION_CLOSED_MESSAGE));
+                }
+                catch (err) {
+                    console.error(`Error failing a pending ${protocol} call on close:`, err);
+                }
+            }
+        });
+    }
     function closeForProtocolViolation(reason) {
         if (isClosed) {
             return;
@@ -441,6 +465,7 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
         clearAllReassemblies();
         destroyFrameCipher();
         socket.connected = false;
+        rejectPendingCalls();
         peer.destroy();
     }
     function reserveReassembly(key, totalSize, maximumMessageBytes, onTimeout) {
@@ -469,9 +494,9 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
     function handleIncomingRPC(bytes) {
         const message = decodeMessage(bytes);
         if (message.type === "callback") {
-            const callback = callbacks[message.callbackId];
+            const callback = callbacks.get(message.callbackId);
             if (callback) {
-                delete callbacks[message.callbackId];
+                callbacks.delete(message.callbackId);
                 callback(message.error, message.result);
             }
             return;
@@ -739,16 +764,21 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
             console.error(`Error parsing ${protocol} frame:`, err);
         }
     });
-    // Handle closure. Cipher teardown waits until queued RPC replies have sealed;
-    // see {@link releaseCipherAfterTurn}.
-    peer.on("close", () => {
+    /**
+     * Handle closure, from the peer or from {@link ISocket.disconnect}. Calls waiting for a reply
+     * fail now. Cipher teardown waits until queued replies to the peer's calls have sealed; see
+     * {@link releaseCipherAfterTurn}.
+     */
+    function markClosed() {
         if (isClosed)
             return;
         isClosed = true;
         socket.connected = false;
         clearAllReassemblies();
+        rejectPendingCalls();
         releaseCipherAfterTurn();
-    });
+    }
+    peer.on("close", markClosed);
     // ─── ISocket Implementation ──────────────────────────────────────
     const socket = {
         id: connectionId,
@@ -763,10 +793,16 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
             plaintextStreamsAllowed = allowed;
         },
         emit(eventName, args, callback) {
+            if (isClosed) {
+                // Nothing can answer; fail on a later turn so the caller never sees a synchronous reply.
+                queueMicrotask(() => callback(new Error(peer_device_1.CONNECTION_CLOSED_MESSAGE)));
+                return;
+            }
             const callbackId = (0, utils_1.newid)();
-            callbacks[callbackId] = callback;
             const message = { type: "call", eventName, args, callbackId };
+            // Encoded first: a call that can't be encoded throws to its caller and leaves no callback.
             const encoded = encodeMessage(message);
+            callbacks.set(callbackId, callback);
             sendRPC(encoded);
         },
         on(eventName, handler) {
@@ -783,6 +819,8 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
             }
         },
         disconnect() {
+            // The WebRTC peers don't report their own destroy() as a close.
+            markClosed();
             peer.destroy();
         },
         sendRawBytes: sendStreamData,

package/dist/device/tx-encoding.d.ts

@@ -1,2 +1,23 @@
-export declare function txEncode(data: unknown): Uint8Array;
+/** Options for {@link txEncode}. */
+export interface TxEncodeOptions {
+    /**
+     * Write `Uint8Array` and `Buffer` values as msgpack binary instead of {@link toJSON}'s base64
+     * strings. Device connections' RPC messages use it; a payload that is signed or boxed keeps the
+     * default, so its format is unchanged. {@link txDecode} reads both.
+     */
+    binaryBytes?: boolean;
+}
+/**
+ * Encodes `data` for a device connection or a box: {@link toJSON} (cycles, dates, bytes), msgpack,
+ * then gzip when that saves at least 20% (judged from a 64 KiB sample first for a large payload).
+ * The first byte is a flag: 0 plain, 1 gzip. With `binaryBytes`, bytes stay binary (see
+ * {@link TxEncodeOptions}).
+ */
+export declare function txEncode(data: unknown, options?: TxEncodeOptions): Uint8Array;
+/**
+ * Inverse of {@link txEncode}, with or without `binaryBytes`. Bytes that were written as binary
+ * come back as views into `data` (or into its inflated copy), so a caller that keeps a small piece
+ * of a large message for long should copy it.
+ * @throws If `data` is empty, has an unknown flag, or doesn't inflate or decode
+ */
 export declare function txDecode(data: Uint8Array): unknown;

package/dist/device/tx-encoding.js

@@ -4,6 +4,7 @@ exports.txEncode = txEncode;
 exports.txDecode = txDecode;
 const msgpack_1 = require("@msgpack/msgpack");
 const fflate_1 = require("fflate");
+const native_codecs_1 = require("../native-codecs");
 const serial_json_1 = require("../serial-json");
 // Minimum size before attempting compression (bytes)
 // Small payloads don't benefit much from compression
@@ -14,35 +15,70 @@ const MIN_COMPRESSION_RATIO = 0.8;
 // Compression level: 1 (fastest) to 9 (best compression)
 // Level 1 is ~5-10x faster than level 6 with reasonable compression
 const COMPRESSION_LEVEL = 1;
-function txEncode(data) {
-    const noCycles = (0, serial_json_1.toJSON)(data); // remove cycles and encode dates, etc.
-    // First encode to msgpack
-    const encoded = (0, msgpack_1.encode)(noCycles);
-    let body;
-    let flag;
-    if (encoded.length > COMPRESSION_THRESHOLD) {
-        // Try to compress - use fast compression level
-        const compressed = (0, fflate_1.compressSync)(encoded, { level: COMPRESSION_LEVEL });
-        // Only use compression if it actually helps significantly
-        if (compressed.length < encoded.length * MIN_COMPRESSION_RATIO) {
-            body = compressed;
-            flag = 1; // compressed
-        }
-        else {
-            // Compression didn't help much, skip it
-            body = encoded;
-            flag = 0; // not compressed
-        }
-    }
-    else {
-        body = encoded;
-        flag = 0; // not compressed
+/**
+ * A payload over twice this size is gzipped only when its first this-many bytes compress well, so
+ * bytes that are already compressed (Git packs, media, ciphertext) skip gzip at both ends.
+ */
+const COMPRESSION_SAMPLE_BYTES = 64 * 1024;
+/**
+ * msgpack extension type for a Node `Buffer` in a `binaryBytes` payload. Without it a `Buffer`
+ * would arrive as a plain `Uint8Array`, and {@link toJSON} encodes the two differently, so a
+ * signature over a received value that held a `Buffer` would no longer verify.
+ */
+const BUFFER_EXTENSION_TYPE = 1;
+const extensionCodec = new msgpack_1.ExtensionCodec();
+extensionCodec.register({
+    type: BUFFER_EXTENSION_TYPE,
+    encode: (value) => (Buffer.isBuffer(value) ? value : null),
+    decode: (data) => Buffer.from(data.buffer, data.byteOffset, data.byteLength),
+});
+function gzip(data) {
+    // Both produce gzip, which either side inflates.
+    return ((0, native_codecs_1.getNativeCodecs)()?.gzip(data, COMPRESSION_LEVEL) ??
+        (0, fflate_1.compressSync)(data, { level: COMPRESSION_LEVEL }));
+}
+/** True when gzip saves enough of `data` to be worth inflating at the other end. */
+function compressesWell(data, compressed) {
+    return compressed.length < data.length * MIN_COMPRESSION_RATIO;
+}
+/** `encoded` gzipped when that saves at least 20%, else `undefined`. */
+function compressIfWorthwhile(encoded) {
+    if (encoded.length <= COMPRESSION_THRESHOLD)
+        return undefined;
+    if (encoded.length > COMPRESSION_SAMPLE_BYTES * 2) {
+        const sample = encoded.subarray(0, COMPRESSION_SAMPLE_BYTES);
+        if (!compressesWell(sample, gzip(sample)))
+            return undefined;
     }
+    const compressed = gzip(encoded);
+    return compressesWell(encoded, compressed) ? compressed : undefined;
+}
+/**
+ * Encodes `data` for a device connection or a box: {@link toJSON} (cycles, dates, bytes), msgpack,
+ * then gzip when that saves at least 20% (judged from a 64 KiB sample first for a large payload).
+ * The first byte is a flag: 0 plain, 1 gzip. With `binaryBytes`, bytes stay binary (see
+ * {@link TxEncodeOptions}).
+ */
+function txEncode(data, options) {
+    // Remove cycles and encode dates, etc.
+    const tree = options?.binaryBytes ? (0, serial_json_1.toJSONKeepingBytes)(data) : (0, serial_json_1.toJSON)(data);
+    const encoded = (0, msgpack_1.encode)(tree, { extensionCodec });
+    const compressed = compressIfWorthwhile(encoded);
+    const body = compressed ?? encoded;
     const out = new Uint8Array(1 + body.length);
-    out[0] = flag;
+    out[0] = compressed ? 1 : 0;
     out.set(body, 1);
     return out;
 }
+function isGzip(data) {
+    return data.length > 2 && data[0] === 0x1f && data[1] === 0x8b;
+}
+/**
+ * Inverse of {@link txEncode}, with or without `binaryBytes`. Bytes that were written as binary
+ * come back as views into `data` (or into its inflated copy), so a caller that keeps a small piece
+ * of a large message for long should copy it.
+ * @throws If `data` is empty, has an unknown flag, or doesn't inflate or decode
+ */
 function txDecode(data) {
     if (data.length === 0) {
         throw new Error("Empty payload");
@@ -50,13 +86,14 @@ function txDecode(data) {
     const flag = data[0];
     let body = data.subarray(1);
     if (flag === 1) {
-        body = (0, fflate_1.decompressSync)(body);
+        const native = (0, native_codecs_1.getNativeCodecs)();
+        body = native && isGzip(body) ? native.gunzip(body) : (0, fflate_1.decompressSync)(body);
     }
     else if (flag !== 0) {
         // Optional: future versioning or legacy handling
         throw new Error(`Unknown tx flag: ${flag}`);
     }
-    const unpacked = (0, msgpack_1.decode)(body);
+    const unpacked = (0, msgpack_1.decode)(body, { extensionCodec });
     const restored = (0, serial_json_1.fromJSON)(unpacked); // restore cycles, dates, etc.
     return restored;
 }

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export * from "./invites";
 export * from "./keys";
 export * from "./logging";
 export * from "./mentions";
+export * from "./native-codecs";
 export * from "./observable";
 export * from "./package-installer";
 export * from "./package-loader";

package/dist/index.js

@@ -55,6 +55,7 @@ __exportStar(require("./invites"), exports);
 __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./mentions"), exports);
+__exportStar(require("./native-codecs"), exports);
 __exportStar(require("./observable"), exports);
 __exportStar(require("./package-installer"), exports);
 __exportStar(require("./package-loader"), exports);

package/dist/keys.d.ts

@@ -21,11 +21,16 @@ export declare function hashObject(obj: {
  * legacy insertion-order fallback that keeps pre-existing signatures valid.
  */
 export declare function canonicalJSONString(obj: any): string;
-/** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
+/**
+ * Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats).
+ * Uses `Buffer` (native in Node, the `buffer` package in browsers).
+ */
 export declare function encodeBase64(data: Uint8Array): string;
 /**
  * Inverse of {@link encodeBase64}; accepts standard or URL-safe base64 and repads as needed.
- * @throws TypeError if `data` is not a string
+ * Accepts exactly what `tweetnacl-util` did (whole groups of four, then at most two `=`), and
+ * returns a fresh `Uint8Array` that owns its buffer.
+ * @throws TypeError if `data` is not a string or not valid base64
  */
 export declare function decodeBase64(data: string): Uint8Array;
 /** Random token as base64url string (`size` raw bytes, default 32). */

package/dist/keys.js

@@ -33,9 +33,9 @@ const sha2_1 = require("@noble/hashes/sha2");
 const buffer_1 = require("buffer");
 const ed2curve = require("ed2curve");
 const nacl = require("tweetnacl");
-const utils = require("tweetnacl-util");
 const tweetnacl_util_1 = require("tweetnacl-util");
 const tx_encoding_1 = require("./device/tx-encoding");
+const native_codecs_1 = require("./native-codecs");
 const serial_json_1 = require("./serial-json");
 globalThis.Buffer = buffer_1.Buffer; // shim for browsers/RN
 const _stableStringify = require("fast-json-stable-stringify");
@@ -113,15 +113,42 @@ function canonicalJSONString(obj) {
 function legacySignatureJSONString(obj) {
     return (0, serial_json_1.toJSONString)(obj);
 }
-/** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
+const utf8Encoder = new TextEncoder();
+const supportsBase64Url = buffer_1.Buffer.isEncoding("base64url");
+/**
+ * UTF-8 bytes of `str`, rejecting what `tweetnacl-util`'s `decodeUTF8` rejected (non-strings and
+ * lone surrogates), so signatures are unchanged. `TextEncoder` is native and far faster.
+ * @throws TypeError if `str` is not a string; URIError if it has a lone surrogate
+ */
+function decodeUTF8(str) {
+    if (typeof str !== "string")
+        throw new TypeError("expected string");
+    const wellFormed = str.isWellFormed;
+    if (wellFormed ? !wellFormed.call(str) : /[\uD800-\uDFFF]/.test(str)) {
+        // Slow path only when a surrogate may be unpaired; matches encodeURIComponent's check.
+        encodeURIComponent(str);
+    }
+    return utf8Encoder.encode(str);
+}
+/**
+ * Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats).
+ * Uses `Buffer` (native in Node, the `buffer` package in browsers).
+ */
 function encodeBase64(data) {
-    // return Buffer.from(data).toString("base64url"); // no padding by default
-    const str = utils.encodeBase64(data);
-    return str.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    // Keep tweetnacl-util's coercion and errors for callers passing other array-like values.
+    if (!(data instanceof Uint8Array)) {
+        return (0, tweetnacl_util_1.encodeBase64)(data).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    }
+    const bytes = buffer_1.Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    if (supportsBase64Url)
+        return bytes.toString("base64url");
+    return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 /**
  * Inverse of {@link encodeBase64}; accepts standard or URL-safe base64 and repads as needed.
- * @throws TypeError if `data` is not a string
+ * Accepts exactly what `tweetnacl-util` did (whole groups of four, then at most two `=`), and
+ * returns a fresh `Uint8Array` that owns its buffer.
+ * @throws TypeError if `data` is not a string or not valid base64
  */
 function decodeBase64(data) {
     if (typeof data !== "string") {
@@ -131,7 +158,11 @@ function decodeBase64(data) {
     while (data.length % 4 !== 0) {
         data += "=";
     }
-    return utils.decodeBase64(data);
+    // A single character class, so it doesn't grow V8's regex stack on large inputs.
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+        throw new TypeError("invalid encoding");
+    }
+    return new Uint8Array(buffer_1.Buffer.from(data, "base64"));
 }
 /** Random token as base64url string (`size` raw bytes, default 32). */
 function newToken(size = 32) {
@@ -178,10 +209,28 @@ function derivePublicBoxKey(publicKey) {
     const converted = ed2curve.convertPublicKey(bytes);
     return converted ? encodeBase64(converted) : null;
 }
+/** Ed25519 detached signature; native when the host installed it (identical bytes), else tweetnacl. */
+function signDetached(message, secretKey) {
+    const native = secretKey.length === 64 ? (0, native_codecs_1.getNativeCodecs)()?.sign(message, secretKey) : undefined;
+    return native ?? nacl.sign.detached(message, secretKey);
+}
+/**
+ * Ed25519 detached verify. A native "valid" is trusted (OpenSSL is at least as strict as tweetnacl:
+ * it also rejects a non-canonical S); anything else is decided by tweetnacl, so every signature
+ * tweetnacl accepted still verifies, and its size errors still throw.
+ */
+function verifyDetached(message, signature, publicKey) {
+    const native = (0, native_codecs_1.getNativeCodecs)();
+    if (native && signature.length === 64 && publicKey.length === 32) {
+        if (native.verify(message, signature, publicKey))
+            return true;
+    }
+    return nacl.sign.detached.verify(message, signature, publicKey);
+}
 /** Signs a UTF-8 message with Ed25519; returns base64url signed message (NaCl `sign` combined format). */
 function signMessageWithSecretKey(msg, secretKey) {
     const _secretKey = decodeBase64(secretKey);
-    const msgDecoded = (0, tweetnacl_util_1.decodeUTF8)(msg);
+    const msgDecoded = decodeUTF8(msg);
     const msgSigned = nacl.sign(msgDecoded, _secretKey);
     return encodeBase64(msgSigned);
 }
@@ -213,8 +262,8 @@ function signObjectWithSecretKey(obj, secretKey) {
         obj = { __isNull: true };
     }
     const objStr = canonicalJSONString(obj);
-    const objDecoded = (0, tweetnacl_util_1.decodeUTF8)(objStr);
-    const signatureByteArray = nacl.sign.detached(objDecoded, _secretKey);
+    const objDecoded = decodeUTF8(objStr);
+    const signatureByteArray = signDetached(objDecoded, _secretKey);
     return {
         contents: obj,
         signature: encodeBase64(signatureByteArray),
@@ -231,7 +280,7 @@ function signObjectWithSecretKey(obj, secretKey) {
 function openSignedObject(signedObj) {
     const _publicKey = decodeBase64(signedObj.publicKey);
     const signature = decodeBase64(signedObj.signature);
-    const verify = (objStr) => nacl.sign.detached.verify((0, tweetnacl_util_1.decodeUTF8)(objStr), signature, _publicKey);
+    const verify = (objStr) => verifyDetached(decodeUTF8(objStr), signature, _publicKey);
     const valid = verify(canonicalJSONString(signedObj.contents)) ||
         verify(legacySignatureJSONString(signedObj.contents));
     if (!valid) {
@@ -317,7 +366,7 @@ function openBoxWithSecretKey(box, mySecretKey) {
 }
 function encryptString(data, secretKey) {
     const _secretKey = decodeBase64(secretKey);
-    const _data = (0, tweetnacl_util_1.decodeUTF8)(data);
+    const _data = decodeUTF8(data);
     const nonce = nacl.randomBytes(24);
     const encryptedData = nacl.secretbox(_data, nonce, _secretKey.slice(0, 32));
     return `${encodeBase64(encryptedData)}~${encodeBase64(nonce)}`;

package/dist/native-codecs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Native implementations a Node host can install for the two most expensive steps of a device
+ * message: gzip and Ed25519. Without them the pure-JS paths (`fflate`, `tweetnacl`) run, so
+ * browsers keep working; with them a large device message costs a fraction of the CPU.
+ *
+ * Every implementation must be interchangeable with the pure-JS one on the wire: a peer without
+ * native codecs must accept what this one sends, and the reverse.
+ */
+export interface INativeCodecs {
+    /** gzip `data` at `level` (1-9). Any valid gzip stream will do; receivers only inflate it. */
+    gzip(data: Uint8Array, level: number): Uint8Array;
+    /** Inflate one gzip stream (from {@link INativeCodecs.gzip} or from `fflate`). */
+    gunzip(data: Uint8Array): Uint8Array;
+    /**
+     * Ed25519 detached signature of `message` with a tweetnacl-format 64-byte secret key (seed then
+     * public key). Ed25519 is deterministic, so this must equal tweetnacl's signature byte for byte;
+     * return `undefined` when that can't be guaranteed (for example, a key whose public half doesn't
+     * match its seed) and the caller signs with tweetnacl.
+     */
+    sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array | undefined;
+    /**
+     * Whether `signature` is a valid Ed25519 signature of `message` by the 32-byte `publicKey`.
+     * Callers fall back to tweetnacl when this returns false, so it may be stricter than tweetnacl
+     * but never more lenient.
+     */
+    verify(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean;
+}
+/**
+ * Install (or with no argument, remove) native codecs for this process. Node hosts call this once
+ * at startup, before any device message is signed or sent.
+ */
+export declare function installNativeCodecs(codecs?: INativeCodecs): void;
+/** The installed native codecs, or `undefined` when the pure-JS paths should run. */
+export declare function getNativeCodecs(): INativeCodecs | undefined;

package/dist/native-codecs.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installNativeCodecs = installNativeCodecs;
+exports.getNativeCodecs = getNativeCodecs;
+let installed;
+/**
+ * Install (or with no argument, remove) native codecs for this process. Node hosts call this once
+ * at startup, before any device message is signed or sent.
+ */
+function installNativeCodecs(codecs) {
+    installed = codecs;
+}
+/** The installed native codecs, or `undefined` when the pure-JS paths should run. */
+function getNativeCodecs() {
+    return installed;
+}

package/dist/package-loader/isolated-artifact.d.ts

@@ -270,6 +270,8 @@ export declare const ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
 export declare const ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 /** Host-contract member guests use to publish an in-memory provided-contract observable. */
 export declare const ISOLATED_OBSERVABLE_HOST_MEMBER = "package.observable";
+/** Host-contract member guests use to ask for a direct connection to another device. */
+export declare const ISOLATED_CONNECT_HOST_MEMBER = "device.connect";
 /**
  * How deep field lists may nest through object `fields`: a tool's inputs, say, are level 1.
  * Deeper nesting is refused, so a hostile manifest can't exhaust the validator's stack.

package/dist/package-loader/isolated-artifact.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_MAX_FIELD_DEPTH = exports.ISOLATED_OBSERVABLE_HOST_MEMBER = exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = exports.ISOLATED_GUEST_API_VERSION = exports.ISOLATED_PACKAGE_MAGIC = void 0;
+exports.ISOLATED_MAX_FIELD_DEPTH = exports.ISOLATED_CONNECT_HOST_MEMBER = exports.ISOLATED_OBSERVABLE_HOST_MEMBER = exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = exports.ISOLATED_GUEST_API_VERSION = exports.ISOLATED_PACKAGE_MAGIC = void 0;
 exports.enumValueFits = enumValueFits;
 exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
 exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
@@ -45,6 +45,8 @@ exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
 exports.ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 /** Host-contract member guests use to publish an in-memory provided-contract observable. */
 exports.ISOLATED_OBSERVABLE_HOST_MEMBER = "package.observable";
+/** Host-contract member guests use to ask for a direct connection to another device. */
+exports.ISOLATED_CONNECT_HOST_MEMBER = "device.connect";
 const FIELD_TYPES = new Set(Object.values(field_type_1.FieldType));
 const OBSERVABLE_FIELD_TYPES = new Set([
     field_type_1.FieldType.id,

package/dist/package-loader/isolated-runtime.d.ts

@@ -351,6 +351,12 @@ export interface IIsolatedPackageRuntimeFactoryOptions {
     onWorkerOutput?: (output: IIsolatedWorkerOutput) => void;
     /** This device's id, which package code reads as `ctx.deviceId`. */
     getDeviceId?: () => string | undefined;
+    /**
+     * Ask for a direct connection to `deviceId` within this data context, for package code's
+     * `ctx.connectToDevice`. Resolves whether a verified direct connection exists; never rejects
+     * for an unreachable device. Without it, `ctx.connectToDevice` resolves false.
+     */
+    connectToDevice?: (deviceId: string) => Promise<boolean>;
 }
 /**
  * Host callback that builds an {@link IIsolatedPackageRuntime} for one

package/dist/package-loader/package-loader.js

@@ -127,6 +127,7 @@ class PackageLoader {
                 },
                 onWorkerOutput: (output) => this.logWorkerOutput(output),
                 getDeviceId: () => this.dataContext.userContext?.deviceId(),
+                connectToDevice: (deviceId) => (0, remote_contract_transport_1.connectToRemoteDevice)({ deviceId, dataContextId: this.dataContext.dataContextId }, this.dataContext.userContext),
             });
             this.unsubscribePackageHealth = this.isolatedRuntime.subscribePackageHealth?.((packageId) => {
                 const previous = this.runtimeStates()[packageId];

package/dist/serial-json.d.ts

@@ -26,6 +26,13 @@ export declare function isObject(x: any): x is Record<string, any>;
  * @returns A new tree; the input is never modified. Top-level primitives are returned as-is.
  */
 export declare function toJSON(obj: any): any;
+/**
+ * {@link toJSON}, except that `Uint8Array` and `Buffer` values stay in the tree as they are (the
+ * same instances), for an encoder that writes bytes natively: `txEncode` with `binaryBytes`
+ * hands the tree to msgpack. {@link fromJSON} passes them through, so the round trip still
+ * restores everything else. Never sign this output; signatures cover {@link toJSON}'s.
+ */
+export declare function toJSONKeepingBytes(obj: any): any;
 /**
  * Reverses {@link toJSON}: restores the sentinel values, shared objects and cycles, and keys
  * escaped with `__DOLLAR_`.

package/dist/serial-json.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isObject = isObject;
 exports.toJSON = toJSON;
+exports.toJSONKeepingBytes = toJSONKeepingBytes;
 exports.fromJSON = fromJSON;
 exports.toJSONString = toJSONString;
 exports.fromJSONString = fromJSONString;
@@ -40,6 +41,19 @@ const ARRAY_TAG_PREFIX = "__this_ref:";
  * @returns A new tree; the input is never modified. Top-level primitives are returned as-is.
  */
 function toJSON(obj) {
+    return encodeTree(obj, false);
+}
+/**
+ * {@link toJSON}, except that `Uint8Array` and `Buffer` values stay in the tree as they are (the
+ * same instances), for an encoder that writes bytes natively: `txEncode` with `binaryBytes`
+ * hands the tree to msgpack. {@link fromJSON} passes them through, so the round trip still
+ * restores everything else. Never sign this output; signatures cover {@link toJSON}'s.
+ */
+function toJSONKeepingBytes(obj) {
+    return encodeTree(obj, true);
+}
+/** The walk behind {@link toJSON} and {@link toJSONKeepingBytes}. */
+function encodeTree(obj, keepBytes) {
     if (!_.isObject(obj)) {
         return obj;
     }
@@ -76,9 +90,9 @@ function toJSON(obj) {
         if (_.isError(value))
             return `__ERROR ${value.stack}`;
         if (Buffer.isBuffer(value))
-            return `__BUFFER ${value.toString("base64")}`;
+            return keepBytes ? value : `__BUFFER ${value.toString("base64")}`;
         if (value instanceof Uint8Array)
-            return `__UINT8ARRAY ${Buffer.from(value).toString("base64")}`;
+            return keepBytes ? value : `__UINT8ARRAY ${Buffer.from(value).toString("base64")}`;
         const known = seen.get(value);
         if (known) {
             const target = known.copy;

package/dist/types/peer-device.d.ts

@@ -73,6 +73,12 @@ export interface IDeviceConnection {
     /** Whether the connection has already closed. */
     closed?: boolean;
 }
+/**
+ * Message of the error a device RPC fails with when its connection closes before the reply
+ * arrives, or when it is sent on a connection that has already closed. Sync treats it as an
+ * expected disconnect, not a failure.
+ */
+export declare const CONNECTION_CLOSED_MESSAGE = "connection has been closed";
 /** Shared tuning constants for device synchronization and routing. */
 export declare const PeerDeviceConsts: Readonly<{
     readonly MAX_CONNECTIONS: 30;

package/dist/types/peer-device.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeerDeviceConsts = void 0;
+exports.PeerDeviceConsts = exports.CONNECTION_CLOSED_MESSAGE = void 0;
+/**
+ * Message of the error a device RPC fails with when its connection closes before the reply
+ * arrives, or when it is sent on a connection that has already closed. Sync treats it as an
+ * expected disconnect, not a failure.
+ */
+exports.CONNECTION_CLOSED_MESSAGE = "connection has been closed";
 /** Shared tuning constants for device synchronization and routing. */
 exports.PeerDeviceConsts = Object.freeze({
     // TODO set this based on device type (desktops and servers should be able to handle 100 connections)

package/dist/utils.js

@@ -293,7 +293,7 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
             timeoutCount++;
             finalError = undefined;
             if (connection.closed) {
-                throw new Error(`connection has been closed`);
+                throw new Error(peer_device_1.CONNECTION_CLOSED_MESSAGE);
             }
         }
         catch (error) {
@@ -303,7 +303,7 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
             if (opts.shouldRetry?.(error) === false)
                 throw error;
             if (connection.closed) {
-                throw new Error(`connection has been closed`);
+                throw new Error(peer_device_1.CONNECTION_CLOSED_MESSAGE);
             }
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.28.12",
+  "version": "0.29.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"