@decentnetwork/peer 0.1.86 → 0.1.88

package/dist/compat/packet.d.ts

@@ -20,6 +20,18 @@ export type UserInfoPacket = {
     gender: string;
     email: string;
     region: string;
+    /** AgentNet wire-protocol version (userinfo field 7, appended). 0 = a legacy
+     *  peer that predates the field (native C SDK before the extension, or an old
+     *  JS peer). Non-zero lets peers negotiate capabilities (e.g. toxcore file
+     *  transfer for large files vs. inline bulkmsg). */
+    protoVersion: number;
+    /** Client platform (field 8): "ios" | "android" | "js" | "linux" | "darwin"
+     *  | "win32" | "" (unknown/legacy). */
+    platform: string;
+    /** OS/runtime version string (field 9), e.g. "17.5", "14", "node-24.2.0". */
+    osVersion: string;
+    /** Application/SDK version (field 10), e.g. "beagle-2.3.1", "lan-0.1.166". */
+    appVersion: string;
 };
 export type FriendRequestPacket = {
     type: typeof PACKET_TYPE_FRIEND_REQUEST;
@@ -87,6 +99,13 @@ export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessage
  *   field 4 = gender : string
  *   field 5 = email  : string
  *   field 6 = region : string
+ *
+ * AgentNet extends the table with appended fields (FlatBuffers is forward/
+ * backward compatible — a peer that predates a field just reads its default):
+ *   field 7 = proto_version : uint   (AgentNet wire-protocol version, 0=legacy)
+ *   field 8 = platform      : string ("ios"/"android"/"js"/"darwin"/"linux"/…)
+ *   field 9 = os_version    : string
+ *   field 10 = app_version  : string
  */
 export declare function encodeUserInfoPacket(opts: {
     avatar?: boolean;
@@ -96,6 +115,10 @@ export declare function encodeUserInfoPacket(opts: {
     gender?: string;
     email?: string;
     region?: string;
+    protoVersion?: number;
+    platform?: string;
+    osVersion?: string;
+    appVersion?: string;
 }): Uint8Array;
 export declare function encodeFriendRequestPacket(opts: {
     name?: string;
@@ -144,3 +167,18 @@ export declare function encodeInviteRspPacket(opts: {
     data?: Uint8Array;
 }): Uint8Array;
 export declare function decodeCarrierPacket(bytes: Uint8Array): CarrierPacket;
+/**
+ * Encode a toxcore net_crypto PACKET_ID_REQUEST payload requesting retransmit
+ * of the packets MISSING in the receive window `[low, high]` (inclusive). This
+ * is the exact inverse of the decoder in peer.ts `#handleRetransmitRequest`:
+ * walk each number from `low`, keep a running counter `n` (starts at 1), and
+ * emit `n` at every MISSING number (then reset it), inserting a 0 filler byte
+ * whenever the counter reaches 255. `have(num)` returns true if we already hold
+ * that packet number. `low` is always treated as missing by construction (it is
+ * the low-water mark — the first not-yet-delivered number). Numbers are 32-bit
+ * and wrap; the window is small so the walk is bounded.
+ *
+ * Returned bytes do NOT include the leading PACKET_ID_REQUEST kind byte — the
+ * caller prepends it.
+ */
+export declare function encodeRetransmitRequest(low: number, high: number, have: (num: number) => boolean): Uint8Array;

package/dist/compat/packet.js

@@ -10,7 +10,12 @@ export const PACKET_TYPE_BULKMSG = 36;
 // of <=1024 raw bytes sharing one tid (totalsz set on the FIRST fragment
 // only), reassembled in arrival order by the receiver.
 export const CARRIER_MAX_APP_MESSAGE_LEN = 1024;
-export const CARRIER_MAX_APP_BULKMSG_LEN = 5 * 1024 * 1024;
+// Raised 5 MB -> 16 MB (matches the native SDK) so inline file sends carry
+// ~11 MB real files. The receive reorder buffer + retransmit (peer.ts) keep the
+// many fragments in order; the reliable window still bounds lossy-path
+// throughput — very large / streaming transfers should use sendFile() (toxcore
+// messenger file transfer), not inline bulkmsg.
+export const CARRIER_MAX_APP_BULKMSG_LEN = 16 * 1024 * 1024;
 // Carrier friend-invite constants (carrier.c / carrier.h). An invite carries
 // up to 8192 bytes of application data, fragmented into INVITE_DATA_UNIT-byte
 // chunks sharing one tid — the first fragment carries totalsz (and the
@@ -48,6 +53,13 @@ const ANYBODY_BULKMSG = 6;
  *   field 4 = gender : string
  *   field 5 = email  : string
  *   field 6 = region : string
+ *
+ * AgentNet extends the table with appended fields (FlatBuffers is forward/
+ * backward compatible — a peer that predates a field just reads its default):
+ *   field 7 = proto_version : uint   (AgentNet wire-protocol version, 0=legacy)
+ *   field 8 = platform      : string ("ios"/"android"/"js"/"darwin"/"linux"/…)
+ *   field 9 = os_version    : string
+ *   field 10 = app_version  : string
  */
 export function encodeUserInfoPacket(opts) {
     const builder = new Builder(256);
@@ -57,8 +69,21 @@ export function encodeUserInfoPacket(opts) {
     const gender = builder.createString(opts.gender ?? "");
     const email = builder.createString(opts.email ?? "");
     const region = builder.createString(opts.region ?? "");
-    builder.startObject(7);
+    // Only emit the AgentNet extension strings when set (an all-legacy userinfo
+    // stays byte-identical to what the C SDK sends).
+    const platform = opts.platform ? builder.createString(opts.platform) : 0;
+    const osVersion = opts.osVersion ? builder.createString(opts.osVersion) : 0;
+    const appVersion = opts.appVersion ? builder.createString(opts.appVersion) : 0;
+    builder.startObject(11);
     // Add high field numbers first so vtable reflects all slots.
+    if (appVersion)
+        builder.addFieldOffset(10, appVersion, 0);
+    if (osVersion)
+        builder.addFieldOffset(9, osVersion, 0);
+    if (platform)
+        builder.addFieldOffset(8, platform, 0);
+    if (opts.protoVersion)
+        builder.addFieldInt32(7, opts.protoVersion >>> 0, 0);
     builder.addFieldOffset(6, region, 0);
     builder.addFieldOffset(5, email, 0);
     builder.addFieldOffset(4, gender, 0);
@@ -205,7 +230,12 @@ export function decodeCarrierPacket(bytes) {
             phone: readStringField(body, 3) ?? "",
             gender: readStringField(body, 4) ?? "",
             email: readStringField(body, 5) ?? "",
-            region: readStringField(body, 6) ?? ""
+            region: readStringField(body, 6) ?? "",
+            // Appended AgentNet fields — absent (default) from legacy peers.
+            protoVersion: readUint32Field(body, 7),
+            platform: readStringField(body, 8) ?? "",
+            osVersion: readStringField(body, 9) ?? "",
+            appVersion: readStringField(body, 10) ?? ""
         };
     }
     if (type === PACKET_TYPE_FRIEND_REQUEST && bodyType === ANYBODY_FRIENDREQ) {
@@ -312,3 +342,36 @@ function readByteVectorField(table, field) {
     const length = table.bb.__vector_len(table.bb_pos + offset);
     return table.bb.bytes().slice(vector, vector + length);
 }
+/**
+ * Encode a toxcore net_crypto PACKET_ID_REQUEST payload requesting retransmit
+ * of the packets MISSING in the receive window `[low, high]` (inclusive). This
+ * is the exact inverse of the decoder in peer.ts `#handleRetransmitRequest`:
+ * walk each number from `low`, keep a running counter `n` (starts at 1), and
+ * emit `n` at every MISSING number (then reset it), inserting a 0 filler byte
+ * whenever the counter reaches 255. `have(num)` returns true if we already hold
+ * that packet number. `low` is always treated as missing by construction (it is
+ * the low-water mark — the first not-yet-delivered number). Numbers are 32-bit
+ * and wrap; the window is small so the walk is bounded.
+ *
+ * Returned bytes do NOT include the leading PACKET_ID_REQUEST kind byte — the
+ * caller prepends it.
+ */
+export function encodeRetransmitRequest(low, high, have) {
+    const out = [];
+    let n = 1;
+    const end = (high + 1) >>> 0;
+    for (let i = low >>> 0; i !== end; i = (i + 1) >>> 0) {
+        if (!have(i)) {
+            out.push(n & 0xff);
+            n = 0;
+        }
+        if (n === 255) {
+            out.push(0);
+            n = 1;
+        }
+        else {
+            n++;
+        }
+    }
+    return Uint8Array.from(out);
+}

package/dist/crypto/rendezvous.d.ts

@@ -0,0 +1,7 @@
+export declare const RENDEZVOUS_AUTH_KEY_DOMAIN = "RSP-CARRIER-AUTH-KEY/1";
+export declare const RENDEZVOUS_AUTH_PROOF_LENGTH = 32;
+/**
+ * Create an RSP/1 Carrier identity proof without starting Carrier discovery.
+ * The secret key remains caller-owned and temporary shared material is wiped.
+ */
+export declare function createCarrierRendezvousAuthProof(identitySecretKey: Uint8Array, serverEphemeralPublicKey: Uint8Array, authTranscript: Uint8Array): Uint8Array;

package/dist/crypto/rendezvous.js

@@ -0,0 +1,32 @@
+import { createHmac } from "node:crypto";
+import nacl from "tweetnacl";
+export const RENDEZVOUS_AUTH_KEY_DOMAIN = "RSP-CARRIER-AUTH-KEY/1";
+export const RENDEZVOUS_AUTH_PROOF_LENGTH = 32;
+/**
+ * Create an RSP/1 Carrier identity proof without starting Carrier discovery.
+ * The secret key remains caller-owned and temporary shared material is wiped.
+ */
+export function createCarrierRendezvousAuthProof(identitySecretKey, serverEphemeralPublicKey, authTranscript) {
+    if (identitySecretKey.length !== nacl.box.secretKeyLength) {
+        throw new RangeError(`identitySecretKey must be ${nacl.box.secretKeyLength} bytes`);
+    }
+    if (serverEphemeralPublicKey.length !== nacl.box.publicKeyLength) {
+        throw new RangeError(`serverEphemeralPublicKey must be ${nacl.box.publicKeyLength} bytes`);
+    }
+    if (authTranscript.length === 0)
+        throw new RangeError("authTranscript must not be empty");
+    const rawShared = nacl.scalarMult(identitySecretKey, serverEphemeralPublicKey);
+    const isLowOrder = rawShared.every((byte) => byte === 0);
+    rawShared.fill(0);
+    if (isLowOrder)
+        throw new Error("serverEphemeralPublicKey is low order");
+    const shared = nacl.box.before(serverEphemeralPublicKey, identitySecretKey);
+    const authKey = createHmac("sha256", Buffer.from(shared)).update(RENDEZVOUS_AUTH_KEY_DOMAIN, "utf8").digest();
+    shared.fill(0);
+    try {
+        return Uint8Array.from(createHmac("sha256", authKey).update(authTranscript).digest());
+    }
+    finally {
+        authKey.fill(0);
+    }
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, PACKET_TYPE_INVITE_REQ
 export { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, CRYPTO_PACKET_NAT_PING, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_REQUEST, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID } from "./compat/tox-onion.js";
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";
+export { createCarrierRendezvousAuthProof, RENDEZVOUS_AUTH_KEY_DOMAIN, RENDEZVOUS_AUTH_PROOF_LENGTH } from "./crypto/rendezvous.js";
 export { base58ToBytes, bytesToBase58 } from "./utils/base58.js";
 export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
 export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";

package/dist/index.js

@@ -4,5 +4,6 @@ export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, PACKET_TYPE_INVITE_REQ
 export { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, CRYPTO_PACKET_NAT_PING, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_REQUEST, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID } from "./compat/tox-onion.js";
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";
+export { createCarrierRendezvousAuthProof, RENDEZVOUS_AUTH_KEY_DOMAIN, RENDEZVOUS_AUTH_PROOF_LENGTH } from "./crypto/rendezvous.js";
 export { base58ToBytes, bytesToBase58 } from "./utils/base58.js";
 export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";

package/dist/peer.js

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import nacl from "tweetnacl";
 import { carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
 import { LegacyBootstrapClient } from "./compat/bootstrap.js";
-import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket, encodeInviteReqPacket } from "./compat/packet.js";
+import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket, encodeInviteReqPacket, encodeRetransmitRequest } from "./compat/packet.js";
 import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, createOnionRequest0Tcp, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.js";
 import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 import { NET_PACKET_PING_REQUEST, NET_PACKET_PING_RESPONSE, NET_PACKET_GET_NODES, NET_PACKET_SEND_NODES, encodeDhtRpc, decodeDhtRpc, buildPingPlain, parsePingPlain, buildGetNodesPlain, parseGetNodesPlain, buildSendNodesPlain, parseSendNodesNodeBytes, packUdpNodeV4 } from "./compat/dht-rpc.js";
@@ -165,6 +165,16 @@ const LAN_DISCOVERY_PORTS = (process.env.DECENT_LAN_DISCOVERY_PORTS ?? "33445,33
 const PEER_NICKNAME = process.env.DECENT_PEER_NAME ?? "@decentnetwork/peer";
 const PEER_STATUS_MESSAGE = process.env.DECENT_PEER_STATUS_MESSAGE ?? "decent peer";
 const GREETING_TEXT = process.env.DECENT_GREETING_TEXT ?? "";
+// AgentNet wire-protocol version advertised in the userinfo profile (field 7).
+// Bump when the wire capabilities change so peers can negotiate. v1 marks a peer
+// that carries this field AND supports the toxcore file-transfer channel
+// (PACKET_ID_FILE 80-82) for large files — a sender can prefer that over inline
+// bulkmsg (capped at CARRIER_MAX_APP_BULKMSG_LEN) when the peer's protoVersion>=1.
+const AGENTNET_PROTO_VERSION = 1;
+// Peer package version, advertised as the default appVersion when the embedder
+// doesn't override it. Read lazily so a bundler that inlines this file doesn't
+// need the package.json at runtime.
+const PEER_PKG_VERSION = "0.1.88";
 // Toxcore Messenger.h packet IDs (live inside encrypted 0x1b crypto data plain payload)
 const PACKET_ID_PADDING = 0;
 const PACKET_ID_REQUEST = 1; // request retransmission of unreceived packets
@@ -186,6 +196,17 @@ const PACKET_ID_ACTION = 65; // /me action message
 // understand this ID simply fall through and ignore it. Payload is 6
 // bytes: 4-byte IPv4 + 2-byte big-endian port.
 const PACKET_ID_UDP_ENDPOINT = 160;
+// Receive reorder buffer bound. A reliable lossless packet more than this many
+// numbers AHEAD of the contiguous low-water mark forces the stream forward
+// (skipping the gap) rather than buffering unboundedly — a safety valve against
+// a genuinely-lost packet that never retransmits wedging the whole stream (and
+// against memory blowup). Sized generously (8192 * ~1KB ≈ 8 MB headroom) so a
+// large multi-fragment inline file (16 MB bulkmsg ≈ 16k fragments) has ample
+// grace for a lost fragment to be retransmitted before we give up on it.
+const RECV_REORDER_WINDOW = 8192;
+// Minimum gap between PACKET_ID_REQUEST packets we send for our own receive gaps
+// (toxcore paces requests ~ once per RTT; this floor avoids flooding on a burst).
+const RECV_REQUEST_MIN_INTERVAL_MS = 200;
 export class Peer {
     #opts;
     #events = new EventEmitter();
@@ -1816,6 +1837,10 @@ export class Peer {
                 // colliding numbers). Drop them.
                 state.sendArray = undefined;
                 state.sendBufferStartNum = undefined;
+                // Receive reorder buffer is keyed by the OLD stream's packet numbers —
+                // discard it so stale fragments can't drain into the fresh stream.
+                state.recvBuffer = undefined;
+                state.lastRecvRequestMs = undefined;
             }
             else {
                 state.sendPacketNumber ??= 0;
@@ -2020,244 +2045,36 @@ export class Peer {
                         incrementNonce(state.peerBaseNonce);
                     }
                 }
-                const kind = opened.payload[0];
+                const kind = opened.payload[0] ?? -1;
                 const inner = opened.payload.slice(1);
-                // Advance our ack point ONLY for kinds that actually consume a
-                // reliable packet number on the sender. Toxcore sends REQUEST(1)
-                // and lossy (>=192) packets with num = send_array.buffer_end — the
-                // NEXT UNUSED number, not stored in its send array. Counting those
-                // advanced our receiveBufferStart to buffer_end+1, i.e. we then
-                // acked one more packet than the peer ever sent — and toxcore's
-                // handle_data_packet_core REJECTS any packet whose buffer_start is
-                // out of its send window (clear_buffer_until -> return -1). Result:
-                // from the peer's FIRST retransmit request onward, every packet we
-                // sent was discarded whole (fresh and retransmitted alike) and the
-                // peer went deaf until it re-keyed — the final piece of the iOS
-                // session churn. The JS droppable bulk channel (bulkDataPacketId)
-                // reuses the current number without consuming it, so it must not
-                // advance the ack point either (also fixes reliable packets being
-                // dropped as duplicates after a droppable burst under the same
-                // number).
+                // Route the decrypted packet by delivery class:
+                //  - REQUEST(1), lossy (>=192) and the app's droppable bulk channel
+                //    (bulkDataPacketId) do NOT consume a reliable send number on the
+                //    peer (toxcore sends them at buffer_end without storing them), so
+                //    they must NOT advance our ack point — deliver immediately.
+                //  - Single-transport reliable kinds — toxcore file transfer (80-82) —
+                //    carry their own reliability and are never dual-sent, so they also
+                //    deliver immediately (a reorder buffer would only add latency and
+                //    would wait forever for retransmits that arrive at fresh numbers);
+                //    they still advance the ack point eagerly, exactly as before.
+                //  - Everything else is a reliable message (chat 64, bulkmsg, invites,
+                //    profile, control): deliver immediately and advance the ack point.
+                //
+                // NOTE: a strict in-order recv_array (buffer-ahead + retransmit-request)
+                // was tried here to fix reordered multi-fragment inline files, but it
+                // STALLED the whole reliable stream against native peers whose retransmit
+                // didn't recover our gaps — breaking chat + files in BOTH directions
+                // (the stalled ack point starved the peer's send window). Reverted to the
+                // forgiving skip-the-gap behavior: a lost fragment corrupts one message
+                // (rare) instead of wedging the session. Large files should use the
+                // toxcore file-transfer channel (sendFile), which has its own reliability.
                 const consumesReliableNumber = kind !== PACKET_ID_REQUEST &&
-                    !(kind !== undefined && kind >= 192) &&
+                    kind < 192 &&
                     kind !== this.#opts.bulkDataPacketId;
                 if (consumesReliableNumber) {
                     state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
                 }
-                // Toxcore file transfer (FILE_SENDREQUEST/CONTROL/DATA = 80/81/82).
-                if (this.#fileTransfer.handlePacket(friendId, kind, inner))
-                    return;
-                if (kind === PACKET_ID_ONLINE) {
-                    this.#setFriendOnline(friendId, remote.address, remote.port);
-                    this.#debugLog(`crypto online packet received from ${friendId}`);
-                    // First time the friend signals ONLINE, push our profile
-                    // (nickname + status message) and any configured greeting so the
-                    // other side updates "unknown" to a real name. Toxcore semantics:
-                    // these are sent on every reconnect by the friend_connection layer.
-                    this.#sendProfileAndGreeting(friendId);
-                    return;
-                }
-                if (kind === PACKET_ID_OFFLINE) {
-                    this.#setFriendOffline(friendId);
-                    this.#debugLog(`crypto offline packet received from ${friendId}`);
-                    return;
-                }
-                if (kind === PACKET_ID_KILL) {
-                    this.#friendSessions.delete(friendId);
-                    this.#setFriendOffline(friendId);
-                    this.#debugLog(`crypto kill received from ${friendId}, session torn down`);
-                    return;
-                }
-                if (kind === PACKET_ID_ALIVE) {
-                    // Pure liveness signal; lastPingRecvMs already updated above.
-                    this.#debugVerboseLog(`crypto alive (keepalive) received from ${friendId}`);
-                    return;
-                }
-                if (kind === PACKET_ID_UDP_ENDPOINT) {
-                    // Peer told us their public UDP endpoint — hole-punch to it.
-                    this.#handleUdpEndpointOffer(friendId, inner);
-                    return;
-                }
-                if (kind === PACKET_ID_REQUEST) {
-                    // Lossless retransmission request (toxcore handle_request_packet).
-                    // Bytes are 1-based deltas walking our send window from
-                    // sendBufferStartNum: a matching delta marks that packet number
-                    // REQUESTED (peer is missing it — resend); every walked number
-                    // that doesn't match is implicitly ACKED (peer has it — drop from
-                    // the buffer). 0 is a +255 filler.
-                    this.#handleRetransmitRequest(friendId, state, inner);
-                    return;
-                }
-                if (kind === PACKET_ID_SHARE_RELAYS) {
-                    // Peer is sharing TCP relay endpoints they're connected to. We
-                    // don't have a TCP relay client yet, so cache nothing — just log.
-                    this.#debugVerboseLog(`crypto share-relays from ${friendId} (TCP relay client not implemented)`);
-                    return;
-                }
-                if (kind === PACKET_ID_NICKNAME) {
-                    const name = decodeUtf8Best(inner);
-                    const friend = this.#friends.get(friendId);
-                    if (friend && name && friend.name !== name) {
-                        this.#friends.set(friendId, { ...friend, name });
-                        this.#persistFriends();
-                        this.#events.emit("friendInfo", {
-                            pubkey: friendId,
-                            userid: friend.userid ?? friendId,
-                            name,
-                            description: friend.description
-                        });
-                    }
-                    this.#debugLog(`crypto nickname received from ${friendId}: "${name}"`);
-                    return;
-                }
-                if (kind === PACKET_ID_STATUSMESSAGE) {
-                    // Carrier C SDK wraps the user-profile in a FlatBuffers
-                    // PACKET_TYPE_USERINFO packet here (name + descr + gender + phone
-                    // + email + region + has_avatar). Some non-Carrier toxcore peers
-                    // may still send raw UTF-8, so try the FB decode first and fall
-                    // back to plain UTF-8 for compatibility.
-                    let userInfoName;
-                    let userInfoDescr;
-                    try {
-                        const decoded = decodeCarrierPacket(inner);
-                        if (decoded.type === PACKET_TYPE_USERINFO) {
-                            userInfoName = decoded.name;
-                            userInfoDescr = decoded.descr;
-                        }
-                    }
-                    catch {
-                        // Not a Carrier userinfo packet — fall through.
-                    }
-                    if (userInfoName !== undefined || userInfoDescr !== undefined) {
-                        const friend = this.#friends.get(friendId);
-                        const newName = userInfoName && userInfoName.length > 0 ? userInfoName : friend?.name;
-                        const newDescr = userInfoDescr ?? friend?.description;
-                        if (friend && (friend.name !== newName || friend.description !== newDescr)) {
-                            this.#friends.set(friendId, { ...friend, name: newName, description: newDescr });
-                            this.#persistFriends();
-                            this.#events.emit("friendInfo", {
-                                pubkey: friendId,
-                                userid: friend.userid ?? friendId,
-                                name: newName,
-                                description: newDescr
-                            });
-                        }
-                        this.#debugLog(`crypto userinfo received from ${friendId}: name="${userInfoName ?? ""}" descr="${userInfoDescr ?? ""}"`);
-                    }
-                    else {
-                        const status = decodeUtf8Best(inner);
-                        const friend = this.#friends.get(friendId);
-                        if (friend && status && friend.description !== status) {
-                            this.#friends.set(friendId, { ...friend, description: status });
-                            this.#persistFriends();
-                        }
-                        this.#debugVerboseLog(`crypto status message (raw) received from ${friendId}: "${status}"`);
-                    }
-                    return;
-                }
-                if (kind === PACKET_ID_USERSTATUS) {
-                    this.#debugVerboseLog(`crypto user-status received from ${friendId} (${inner[0] ?? "?"})`);
-                    return;
-                }
-                if (kind === PACKET_ID_TYPING) {
-                    this.#debugVerboseLog(`crypto typing received from ${friendId} (${inner[0] ?? "?"})`);
-                    return;
-                }
-                if (kind === PACKET_ID_MESSAGE || kind === PACKET_ID_ACTION) {
-                    this.#setFriendOnline(friendId, remote.address, remote.port);
-                    // Decode the Carrier FlatBuffers wrapper when present. A BULKMSG
-                    // fragment (Carrier C splits any message >1024 bytes this way —
-                    // e.g. iOS Beagle images, which are FileModel JSON envelopes)
-                    // goes to the reassembler and only emits once complete; before
-                    // this, every fragment surfaced as a separate garbage "text".
-                    let text;
-                    let carrier;
-                    try {
-                        carrier = decodeCarrierPacket(inner);
-                    }
-                    catch { /* raw utf-8 peer */ }
-                    // Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST/RESPONSE = 34/35)
-                    // rides this same PACKET_ID_MESSAGE channel — it's what the iOS/Android
-                    // WebRTC SDK uses for call signaling via the "carrier" extension. Large
-                    // signals (SDP offers) fragment by tid like bulkmsg; reassemble then
-                    // surface as an "invite" event (NOT chat text).
-                    if (carrier?.type === PACKET_TYPE_INVITE_REQUEST) {
-                        const complete = this.#assembleInvite(friendId, carrier);
-                        if (!complete)
-                            return; // more fragments pending
-                        this.#events.emit("invite", {
-                            pubkey: friendId,
-                            ext: carrier.ext,
-                            bundle: carrier.bundle,
-                            data: complete
-                        });
-                        this.#debugLog(`invite from ${friendId}: ext="${carrier.ext ?? ""}" (${complete.length} bytes)`);
-                        return;
-                    }
-                    if (carrier?.type === PACKET_TYPE_INVITE_RESPONSE) {
-                        const complete = carrier.status === 0 ? this.#assembleInvite(friendId, carrier) : new Uint8Array();
-                        if (carrier.status === 0 && !complete)
-                            return; // more fragments pending
-                        this.#events.emit("inviteResponse", {
-                            pubkey: friendId,
-                            ext: carrier.ext,
-                            bundle: carrier.bundle,
-                            status: carrier.status,
-                            reason: carrier.reason,
-                            data: complete ?? new Uint8Array()
-                        });
-                        this.#debugLog(`invite-response from ${friendId}: status=${carrier.status} ext="${carrier.ext ?? ""}"`);
-                        return;
-                    }
-                    if (carrier?.type === PACKET_TYPE_BULKMSG) {
-                        const complete = this.#assembleBulkMsg(friendId, carrier);
-                        if (!complete)
-                            return; // more fragments pending
-                        text = decodeUtf8Best(complete);
-                        this.#debugLog(`bulkmsg complete from ${friendId} (${complete.length} bytes)`);
-                    }
-                    else if (carrier?.type === PACKET_TYPE_MESSAGE) {
-                        text = new TextDecoder().decode(carrier.data);
-                    }
-                    else {
-                        text = decodeUtf8Best(inner);
-                    }
-                    // Carrier C peers terminate strings with a NUL — strip it so chat
-                    // text doesn't carry an invisible trailing byte.
-                    text = text?.replace(/\0+$/u, "");
-                    if (!text) {
-                        this.#debugLog(`crypto message packet decode failed from ${friendId}`);
-                        return;
-                    }
-                    // iOS Beagle sends files inline as a FileModel JSON envelope
-                    // ({data: base64, fileExtension, fileName, type}) — surface those
-                    // as files, not as a wall of base64 text.
-                    if (this.#tryEmitInlineFile(friendId, text, "online"))
-                        return;
-                    this.#events.emit("text", {
-                        pubkey: friendId,
-                        text,
-                        via: "online"
-                    });
-                    this.#debugLog(`crypto ${kind === PACKET_ID_ACTION ? "action" : "message"} from ${friendId}: "${text}"`);
-                    return;
-                }
-                if (kind >= 160 && kind <= 254) {
-                    // Application custom packet (toxcore lossless 160-191 / lossy
-                    // 192-254). SDK-reserved IDs (160 UDP_ENDPOINT, 254 NAT_PING, …)
-                    // are handled by earlier branches and never reach here; anything
-                    // else belongs to the application layer (e.g. decentlan IP traffic
-                    // on 192, control on 161/162). Receiving one proves the friend is
-                    // reachable, so mark online.
-                    this.#setFriendOnline(friendId, remote.address, remote.port);
-                    this.#events.emit("customPacket", {
-                        pubkey: friendId,
-                        id: kind,
-                        data: inner
-                    });
-                    return;
-                }
-                this.#debugVerboseLog(`unknown messenger packet kind ${kind} from ${friendId}`);
+                this.#deliverLosslessPayload(friendId, state, kind, inner, remote);
                 return;
             }
             // Reverted: we used to DELETE a "desynced" session here to force a clean
@@ -3349,6 +3166,323 @@ export class Peer {
             });
         }
     }
+    /** Deliver ONE decrypted lossless payload to the application layer. Split
+     *  out of the datagram handler so the receive reorder buffer can replay
+     *  buffered packets through the exact same dispatch. `kind` is the first
+     *  payload byte (never undefined here — the caller defaults it). */
+    #deliverLosslessPayload(friendId, state, kind, inner, remote) {
+        // Toxcore file transfer (FILE_SENDREQUEST/CONTROL/DATA = 80/81/82).
+        if (this.#fileTransfer.handlePacket(friendId, kind, inner))
+            return;
+        if (kind === PACKET_ID_ONLINE) {
+            this.#setFriendOnline(friendId, remote.address, remote.port);
+            this.#debugLog(`crypto online packet received from ${friendId}`);
+            // First time the friend signals ONLINE, push our profile
+            // (nickname + status message) and any configured greeting so the
+            // other side updates "unknown" to a real name. Toxcore semantics:
+            // these are sent on every reconnect by the friend_connection layer.
+            this.#sendProfileAndGreeting(friendId);
+            return;
+        }
+        if (kind === PACKET_ID_OFFLINE) {
+            this.#setFriendOffline(friendId);
+            this.#debugLog(`crypto offline packet received from ${friendId}`);
+            return;
+        }
+        if (kind === PACKET_ID_KILL) {
+            this.#friendSessions.delete(friendId);
+            this.#setFriendOffline(friendId);
+            this.#debugLog(`crypto kill received from ${friendId}, session torn down`);
+            return;
+        }
+        if (kind === PACKET_ID_ALIVE) {
+            // Pure liveness signal; lastPingRecvMs already updated above.
+            this.#debugVerboseLog(`crypto alive (keepalive) received from ${friendId}`);
+            return;
+        }
+        if (kind === PACKET_ID_UDP_ENDPOINT) {
+            // Peer told us their public UDP endpoint — hole-punch to it.
+            this.#handleUdpEndpointOffer(friendId, inner);
+            return;
+        }
+        if (kind === PACKET_ID_REQUEST) {
+            // Lossless retransmission request (toxcore handle_request_packet).
+            // Bytes are 1-based deltas walking our send window from
+            // sendBufferStartNum: a matching delta marks that packet number
+            // REQUESTED (peer is missing it — resend); every walked number
+            // that doesn't match is implicitly ACKED (peer has it — drop from
+            // the buffer). 0 is a +255 filler.
+            this.#handleRetransmitRequest(friendId, state, inner);
+            return;
+        }
+        if (kind === PACKET_ID_SHARE_RELAYS) {
+            // Peer is sharing TCP relay endpoints they're connected to. We
+            // don't have a TCP relay client yet, so cache nothing — just log.
+            this.#debugVerboseLog(`crypto share-relays from ${friendId} (TCP relay client not implemented)`);
+            return;
+        }
+        if (kind === PACKET_ID_NICKNAME) {
+            const name = decodeUtf8Best(inner);
+            const friend = this.#friends.get(friendId);
+            if (friend && name && friend.name !== name) {
+                this.#friends.set(friendId, { ...friend, name });
+                this.#persistFriends();
+                this.#events.emit("friendInfo", {
+                    pubkey: friendId,
+                    userid: friend.userid ?? friendId,
+                    name,
+                    description: friend.description
+                });
+            }
+            this.#debugLog(`crypto nickname received from ${friendId}: "${name}"`);
+            return;
+        }
+        if (kind === PACKET_ID_STATUSMESSAGE) {
+            // Carrier C SDK wraps the user-profile in a FlatBuffers
+            // PACKET_TYPE_USERINFO packet here (name + descr + gender + phone
+            // + email + region + has_avatar). Some non-Carrier toxcore peers
+            // may still send raw UTF-8, so try the FB decode first and fall
+            // back to plain UTF-8 for compatibility.
+            let userInfoName;
+            let userInfoDescr;
+            let clientMeta;
+            try {
+                const decoded = decodeCarrierPacket(inner);
+                if (decoded.type === PACKET_TYPE_USERINFO) {
+                    userInfoName = decoded.name;
+                    userInfoDescr = decoded.descr;
+                    // AgentNet appended fields — present only for updated peers.
+                    if (decoded.protoVersion || decoded.platform || decoded.appVersion) {
+                        clientMeta = {
+                            protoVersion: decoded.protoVersion,
+                            platform: decoded.platform,
+                            osVersion: decoded.osVersion,
+                            appVersion: decoded.appVersion
+                        };
+                    }
+                }
+            }
+            catch {
+                // Not a Carrier userinfo packet — fall through.
+            }
+            if (userInfoName !== undefined || userInfoDescr !== undefined) {
+                const friend = this.#friends.get(friendId);
+                const newName = userInfoName && userInfoName.length > 0 ? userInfoName : friend?.name;
+                const newDescr = userInfoDescr ?? friend?.description;
+                const metaChanged = friend != null && clientMeta != null &&
+                    (friend.protoVersion !== clientMeta.protoVersion ||
+                        friend.platform !== clientMeta.platform ||
+                        friend.osVersion !== clientMeta.osVersion ||
+                        friend.appVersion !== clientMeta.appVersion);
+                if (friend && (friend.name !== newName || friend.description !== newDescr || metaChanged)) {
+                    this.#friends.set(friendId, { ...friend, name: newName, description: newDescr, ...(clientMeta ?? {}) });
+                    this.#persistFriends();
+                    this.#events.emit("friendInfo", {
+                        pubkey: friendId,
+                        userid: friend.userid ?? friendId,
+                        name: newName,
+                        description: newDescr,
+                        ...(clientMeta ?? {})
+                    });
+                }
+                this.#debugLog(`crypto userinfo received from ${friendId}: name="${userInfoName ?? ""}" descr="${userInfoDescr ?? ""}"${clientMeta ? ` proto=${clientMeta.protoVersion} platform=${clientMeta.platform} app=${clientMeta.appVersion}` : ""}`);
+            }
+            else {
+                const status = decodeUtf8Best(inner);
+                const friend = this.#friends.get(friendId);
+                if (friend && status && friend.description !== status) {
+                    this.#friends.set(friendId, { ...friend, description: status });
+                    this.#persistFriends();
+                }
+                this.#debugVerboseLog(`crypto status message (raw) received from ${friendId}: "${status}"`);
+            }
+            return;
+        }
+        if (kind === PACKET_ID_USERSTATUS) {
+            this.#debugVerboseLog(`crypto user-status received from ${friendId} (${inner[0] ?? "?"})`);
+            return;
+        }
+        if (kind === PACKET_ID_TYPING) {
+            this.#debugVerboseLog(`crypto typing received from ${friendId} (${inner[0] ?? "?"})`);
+            return;
+        }
+        if (kind === PACKET_ID_MESSAGE || kind === PACKET_ID_ACTION) {
+            this.#setFriendOnline(friendId, remote.address, remote.port);
+            // Decode the Carrier FlatBuffers wrapper when present. A BULKMSG
+            // fragment (Carrier C splits any message >1024 bytes this way —
+            // e.g. iOS Beagle images, which are FileModel JSON envelopes)
+            // goes to the reassembler and only emits once complete; before
+            // this, every fragment surfaced as a separate garbage "text".
+            let text;
+            let carrier;
+            try {
+                carrier = decodeCarrierPacket(inner);
+            }
+            catch { /* raw utf-8 peer */ }
+            // Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST/RESPONSE = 34/35)
+            // rides this same PACKET_ID_MESSAGE channel — it's what the iOS/Android
+            // WebRTC SDK uses for call signaling via the "carrier" extension. Large
+            // signals (SDP offers) fragment by tid like bulkmsg; reassemble then
+            // surface as an "invite" event (NOT chat text).
+            if (carrier?.type === PACKET_TYPE_INVITE_REQUEST) {
+                const complete = this.#assembleInvite(friendId, carrier);
+                if (!complete)
+                    return; // more fragments pending
+                this.#events.emit("invite", {
+                    pubkey: friendId,
+                    ext: carrier.ext,
+                    bundle: carrier.bundle,
+                    data: complete
+                });
+                this.#debugLog(`invite from ${friendId}: ext="${carrier.ext ?? ""}" (${complete.length} bytes)`);
+                return;
+            }
+            if (carrier?.type === PACKET_TYPE_INVITE_RESPONSE) {
+                const complete = carrier.status === 0 ? this.#assembleInvite(friendId, carrier) : new Uint8Array();
+                if (carrier.status === 0 && !complete)
+                    return; // more fragments pending
+                this.#events.emit("inviteResponse", {
+                    pubkey: friendId,
+                    ext: carrier.ext,
+                    bundle: carrier.bundle,
+                    status: carrier.status,
+                    reason: carrier.reason,
+                    data: complete ?? new Uint8Array()
+                });
+                this.#debugLog(`invite-response from ${friendId}: status=${carrier.status} ext="${carrier.ext ?? ""}"`);
+                return;
+            }
+            if (carrier?.type === PACKET_TYPE_BULKMSG) {
+                const complete = this.#assembleBulkMsg(friendId, carrier);
+                if (!complete)
+                    return; // more fragments pending
+                text = decodeUtf8Best(complete);
+                this.#debugLog(`bulkmsg complete from ${friendId} (${complete.length} bytes)`);
+            }
+            else if (carrier?.type === PACKET_TYPE_MESSAGE) {
+                text = new TextDecoder().decode(carrier.data);
+            }
+            else {
+                text = decodeUtf8Best(inner);
+            }
+            // Carrier C peers terminate strings with a NUL — strip it so chat
+            // text doesn't carry an invisible trailing byte.
+            text = text?.replace(/\0+$/u, "");
+            if (!text) {
+                this.#debugLog(`crypto message packet decode failed from ${friendId}`);
+                return;
+            }
+            // iOS Beagle sends files inline as a FileModel JSON envelope
+            // ({data: base64, fileExtension, fileName, type}) — surface those
+            // as files, not as a wall of base64 text.
+            if (this.#tryEmitInlineFile(friendId, text, "online"))
+                return;
+            this.#events.emit("text", {
+                pubkey: friendId,
+                text,
+                via: "online"
+            });
+            this.#debugLog(`crypto ${kind === PACKET_ID_ACTION ? "action" : "message"} from ${friendId}: "${text}"`);
+            return;
+        }
+        if (kind >= 160 && kind <= 254) {
+            // Application custom packet (toxcore lossless 160-191 / lossy
+            // 192-254). SDK-reserved IDs (160 UDP_ENDPOINT, 254 NAT_PING, …)
+            // are handled by earlier branches and never reach here; anything
+            // else belongs to the application layer (e.g. decentlan IP traffic
+            // on 192, control on 161/162). Receiving one proves the friend is
+            // reachable, so mark online.
+            this.#setFriendOnline(friendId, remote.address, remote.port);
+            this.#events.emit("customPacket", {
+                pubkey: friendId,
+                id: kind,
+                data: inner
+            });
+            return;
+        }
+        this.#debugVerboseLog(`unknown messenger packet kind ${kind} from ${friendId}`);
+    }
+    /** Drain the receive reorder buffer forward from receiveBufferStart while it
+     *  holds the next contiguous packet, delivering each in strict order. */
+    #drainRecvBufferContiguous(friendId, state, remote) {
+        const buf = state.recvBuffer;
+        if (!buf)
+            return;
+        for (let held = buf.get(state.receiveBufferStart ?? 0); held; held = buf.get(state.receiveBufferStart ?? 0)) {
+            buf.delete(state.receiveBufferStart ?? 0);
+            state.receiveBufferStart = ((state.receiveBufferStart ?? 0) + 1) >>> 0;
+            this.#deliverLosslessPayload(friendId, state, held.kind, held.inner, remote);
+        }
+    }
+    /** Safety valve: the reorder buffer grew past the window, so a packet below
+     *  it is (almost certainly) a genuine loss that will never retransmit. Jump
+     *  the low-water mark to the lowest buffered number — abandoning the gap
+     *  (partial messages are dropped gracefully by the reassemblers) — rather
+     *  than wedging every later packet (incl. chat) forever. */
+    #forceAdvanceRecvBuffer(friendId, state, remote) {
+        const buf = state.recvBuffer;
+        if (!buf || buf.size === 0)
+            return;
+        const expected = state.receiveBufferStart ?? 0;
+        let lowest = expected;
+        let bestDist = Infinity;
+        for (const n of buf.keys()) {
+            const d = (n - expected) >>> 0;
+            if (d < bestDist) {
+                bestDist = d;
+                lowest = n;
+            }
+        }
+        this.#debugLog(`recv reorder overflow from ${friendId}: abandoning gap [${expected}..${lowest}), ${buf.size} held`);
+        state.receiveBufferStart = lowest;
+        this.#drainRecvBufferContiguous(friendId, state, remote);
+    }
+    /** Ask the sender to retransmit the packets missing below our highest
+     *  buffered number. Encodes the toxcore PACKET_ID_REQUEST byte stream
+     *  (the exact inverse of #handleRetransmitRequest): walk [low, high] and
+     *  emit the running gap-counter at each MISSING number. Rate-limited. */
+    #requestMissingReliablePackets(friendId, state) {
+        const buf = state.recvBuffer;
+        if (!buf || buf.size === 0)
+            return;
+        const now = Date.now();
+        if (state.lastRecvRequestMs && now - state.lastRecvRequestMs < RECV_REQUEST_MIN_INTERVAL_MS)
+            return;
+        const low = state.receiveBufferStart ?? 0;
+        let high = low;
+        let bestDist = -1;
+        for (const n of buf.keys()) {
+            const d = (n - low) >>> 0;
+            if (d > bestDist) {
+                bestDist = d;
+                high = n;
+            }
+        }
+        const bytes = encodeRetransmitRequest(low, high, (n) => buf.has(n));
+        if (bytes.length === 0)
+            return;
+        state.lastRecvRequestMs = now;
+        void this.#sendRequestPacket(friendId, state, bytes).catch(() => { });
+    }
+    /** Send a PACKET_ID_REQUEST. Like a retransmit (#resendReliablePacket) it
+     *  rides the CURRENT nonce but does NOT consume a reliable send number —
+     *  toxcore sends requests at buffer_end without storing them. */
+    async #sendRequestPacket(friendId, state, requestBytes) {
+        if (!state.established || !state.sessionSharedKey || !state.ourBaseNonce)
+            return;
+        if (!state.remote && !state.hasTcpRoute)
+            return;
+        const payload = concatBytes([Uint8Array.of(PACKET_ID_REQUEST), requestBytes]);
+        const encrypted = createCryptoDataPacket({
+            sessionSharedKey: state.sessionSharedKey,
+            sentNonce: state.ourBaseNonce,
+            bufferStart: state.receiveBufferStart ?? 0,
+            packetNumber: state.sendPacketNumber ?? 0,
+            payload
+        });
+        incrementNonce(state.ourBaseNonce);
+        await this.#sendToFriend(friendId, encrypted, state, false, false);
+    }
     /** Append a Carrier BULKMSG fragment; returns the full reassembled
      *  message when the last fragment lands, undefined while pending.
      *  Mirrors the C SDK's handle_friend_bulkmsg: totalsz on the first
@@ -3562,8 +3696,11 @@ export class Peer {
             session.sendBufferStartNum ??= packetNumber;
             session.sendArray.set(packetNumber, payload);
             // Bound the buffer: beyond this window the peer has either acked via
-            // REQUEST packets or the session is beyond saving anyway.
-            while (session.sendArray.size > 1024 && session.sendBufferStartNum !== session.sendPacketNumber) {
+            // REQUEST packets or the session is beyond saving anyway. Sized to match
+            // the receive reorder window (8192) so a large multi-fragment bulk send
+            // (16 MB inline file ≈ 16k fragments) can retransmit any fragment the peer
+            // is still missing within the window rather than evicting it too early.
+            while (session.sendArray.size > 8192 && session.sendBufferStartNum !== session.sendPacketNumber) {
                 session.sendArray.delete(session.sendBufferStartNum);
                 session.sendBufferStartNum = (session.sendBufferStartNum + 1) >>> 0;
             }
@@ -3775,10 +3912,17 @@ export class Peer {
                     await sleep(250);
                     const userInfo = encodeUserInfoPacket({
                         name: nick,
-                        descr
+                        descr,
+                        // AgentNet client metadata (appended userinfo fields 7-10). Old
+                        // peers ignore them; updated peers negotiate capabilities + display
+                        // the friend's platform/build.
+                        protoVersion: AGENTNET_PROTO_VERSION,
+                        platform: this.#opts.platform ?? process.platform,
+                        osVersion: this.#opts.osVersion ?? `node-${process.versions?.node ?? ""}`,
+                        appVersion: this.#opts.appVersion ?? `peer-${PEER_PKG_VERSION}`
                     });
                     await this.#sendMessengerPacket(friendId, PACKET_ID_STATUSMESSAGE, userInfo);
-                    this.#debugLog(`userinfo sent to ${friendId} (name="${nick}", descr="${descr}")`);
+                    this.#debugLog(`userinfo sent to ${friendId} (name="${nick}", descr="${descr}", proto=${AGENTNET_PROTO_VERSION}, platform=${this.#opts.platform ?? process.platform})`);
                 }
                 catch (error) {
                     this.#debugLog(`send profile failed for ${friendId}: ${error.message}`);

package/dist/store/friends.d.ts

@@ -19,4 +19,12 @@ export type FriendRecord = {
      *  can immediately park relay ROUTING_REQUESTs under the right key
      *  instead of waiting for the friend's next DHT-PK announce. */
     dhtPubkey?: string;
+    /** Client metadata the friend advertised in its userinfo profile. Lets the
+     *  app negotiate capabilities (e.g. large-file transfer support) and show
+     *  the peer's platform/build. Undefined / protoVersion 0 for a legacy peer
+     *  that predates the userinfo extension. */
+    protoVersion?: number;
+    platform?: string;
+    osVersion?: string;
+    appVersion?: string;
 };

package/dist/types/peer.d.ts

@@ -68,6 +68,20 @@ export type PeerOptions = {
     nickname?: string;
     /** Status/description line shown alongside the nickname. */
     statusMessage?: string;
+    /**
+     * Client platform advertised to friends in the userinfo profile — e.g.
+     * "js", "darwin", "linux", "ios", "android". Defaults to the Node
+     * `process.platform` value. Native Beagle apps advertise "ios" / "android".
+     */
+    platform?: string;
+    /** OS/runtime version advertised in the profile (e.g. "node-24.2.0"). */
+    osVersion?: string;
+    /**
+     * Application/SDK version advertised in the profile (e.g. "lan-0.1.167").
+     * Lets peers see which build a friend is on. Defaults to the peer package
+     * version.
+     */
+    appVersion?: string;
     compatibilityMode?: CompatibilityMode;
     debugLabel?: string;
 };
@@ -90,6 +104,14 @@ export type FriendInfoEvent = {
     userid?: string;
     name?: string;
     description?: string;
+    /** Peer's advertised client metadata (from the userinfo profile). Present
+     *  only once the friend has sent a profile with these fields — a legacy
+     *  peer (native C SDK before the extension, or an old JS build) leaves them
+     *  undefined / protoVersion 0. */
+    protoVersion?: number;
+    platform?: string;
+    osVersion?: string;
+    appVersion?: string;
 };
 export type TextMessage = {
     pubkey: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,6 +68,8 @@
     "demo:tox-dht-crypto": "pnpm run build && node scripts/tox-dht-crypto-demo.mjs",
     "test:compat": "pnpm run build && node scripts/compat-selftest.mjs",
     "test:invite": "pnpm run build && node scripts/invite-selftest.mjs",
+    "test:reorder": "pnpm run build && node scripts/reorder-selftest.mjs",
+    "test:userinfo": "pnpm run build && node scripts/userinfo-selftest.mjs",
     "test:tcp-onion": "pnpm run build && node scripts/tcp-onion-selftest.mjs",
     "smoke:join": "node scripts/smoke-join.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",