@vdoninja/ninja-p2p 0.1.2 → 0.2.0

package/dist/file-transfer.js

@@ -1,11 +1,31 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { appendFileSync, constants, closeSync, copyFileSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { createMessageId, } from "./protocol.js";
 export const DEFAULT_TRANSFER_CHUNK_SIZE = 12_000;
+/** The simple transfer path buffers at the sender; use swarm transfer above this. */
+export const MAX_BASIC_TRANSFER_SIZE = 256 * 1024 * 1024;
+export const MAX_BASIC_TRANSFER_CHUNK_SIZE = 1024 * 1024;
+export const MAX_BASIC_TRANSFER_CHUNKS = Math.ceil(MAX_BASIC_TRANSFER_SIZE / 1_024);
+export const MAX_INCOMPLETE_TRANSFER_BYTES = 512 * 1024 * 1024;
+export const MAX_INCOMPLETE_TRANSFERS = 16;
+export const INCOMPLETE_TRANSFER_STALE_MS = 24 * 60 * 60_000;
+export const TRANSFER_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 export function prepareFileTransferFromPath(filePath, kind = "file") {
     const resolved = path.resolve(filePath);
+    const file = statSync(resolved);
+    if (!file.isFile())
+        throw new Error(`not a file: ${resolved}`);
+    if (file.size > MAX_BASIC_TRANSFER_SIZE) {
+        throw new Error(`file is ${file.size} bytes; simple transfers are limited to ${MAX_BASIC_TRANSFER_SIZE} bytes ` +
+            "(use `ninja-p2p seed` / `fetch` for larger files)");
+    }
     const bytes = new Uint8Array(readFileSync(resolved));
+    if (bytes.byteLength > MAX_BASIC_TRANSFER_SIZE) {
+        throw new Error(`file grew beyond the ${MAX_BASIC_TRANSFER_SIZE}-byte simple-transfer limit while reading`);
+    }
     const name = path.basename(resolved);
     return {
         name,
@@ -24,7 +44,16 @@ export function sendPreparedFileTransfer(bridge, targetStreamId, prepared, chunk
     if (!bridge.peers.isConnected(targetStreamId)) {
         throw new Error(`peer is not connected: ${targetStreamId}`);
     }
-    const normalizedChunkSize = Math.max(1_024, chunkSize);
+    if (!Number.isFinite(chunkSize) || chunkSize <= 0) {
+        throw new Error(`invalid chunk size: ${chunkSize}`);
+    }
+    if (prepared.size > MAX_BASIC_TRANSFER_SIZE) {
+        throw new Error(`simple transfers are limited to ${MAX_BASIC_TRANSFER_SIZE} bytes`);
+    }
+    const normalizedChunkSize = Math.max(1_024, Math.floor(chunkSize));
+    if (normalizedChunkSize > MAX_BASIC_TRANSFER_CHUNK_SIZE) {
+        throw new Error(`chunk size exceeds ${MAX_BASIC_TRANSFER_CHUNK_SIZE} bytes`);
+    }
     const totalChunks = prepared.size === 0 ? 0 : Math.ceil(prepared.size / normalizedChunkSize);
     const transferId = createMessageId();
     const offer = {
@@ -37,7 +66,9 @@ export function sendPreparedFileTransfer(bridge, targetStreamId, prepared, chunk
         chunkSize: normalizedChunkSize,
         totalChunks,
     };
-    bridge.bus.send(targetStreamId, "file_offer", offer);
+    if (!bridge.bus.trySend(targetStreamId, "file_offer", offer)) {
+        throw new Error(`peer did not accept file offer: ${targetStreamId}`);
+    }
     for (let index = 0; index < totalChunks; index += 1) {
         const start = index * normalizedChunkSize;
         const end = Math.min(start + normalizedChunkSize, prepared.size);
@@ -48,27 +79,44 @@ export function sendPreparedFileTransfer(bridge, targetStreamId, prepared, chunk
             totalChunks,
             data: bytesToBase64(chunk),
         };
-        bridge.bus.send(targetStreamId, "file_chunk", payload);
+        if (!bridge.bus.trySend(targetStreamId, "file_chunk", payload)) {
+            throw new Error(`peer stopped accepting ${prepared.name} at chunk ${index}/${totalChunks}`);
+        }
     }
-    bridge.bus.send(targetStreamId, "file_complete", {
+    if (!bridge.bus.trySend(targetStreamId, "file_complete", {
         transferId,
         totalChunks,
         size: prepared.size,
         sha256: prepared.sha256,
-    });
+    })) {
+        throw new Error(`peer did not accept completion for ${prepared.name}`);
+    }
     return offer;
 }
 export function sendFileFromPath(bridge, targetStreamId, filePath, kind = "file", chunkSize = DEFAULT_TRANSFER_CHUNK_SIZE) {
     return sendPreparedFileTransfer(bridge, targetStreamId, prepareFileTransferFromPath(filePath, kind), chunkSize);
 }
 export function beginIncomingTransfer(stateDir, from, offer) {
+    validateFileOffer(offer);
+    if (!from || typeof from.streamId !== "string" || !from.streamId) {
+        throw new Error("file offer has no valid sender");
+    }
     const paths = getTransferPaths(stateDir, offer.transferId);
     mkdirSync(paths.transfersDir, { recursive: true });
     mkdirSync(paths.downloadsDir, { recursive: true });
     const existing = readTransferManifest(stateDir, offer.transferId);
     if (existing) {
+        if (existing.from.streamId !== from.streamId ||
+            existing.name !== offer.name ||
+            existing.size !== offer.size ||
+            existing.sha256 !== offer.sha256 ||
+            existing.chunkSize !== offer.chunkSize ||
+            existing.totalChunks !== offer.totalChunks) {
+            throw new Error(`transfer id is already in use: ${offer.transferId}`);
+        }
         return existing;
     }
+    enforceIncomingTransferQuota(stateDir, offer.size);
     writeFileSync(paths.tempPath, new Uint8Array(0));
     const safeName = sanitizeFileName(offer.name);
     const manifest = {
@@ -92,18 +140,35 @@ export function beginIncomingTransfer(stateDir, from, offer) {
     writeManifest(paths.manifestPath, manifest);
     return manifest;
 }
-export function appendIncomingTransferChunk(stateDir, payload) {
+export function appendIncomingTransferChunk(stateDir, payload, fromStreamId) {
+    validateTransferId(payload?.transferId);
     const manifest = mustReadTransferManifest(stateDir, payload.transferId);
+    if (fromStreamId && manifest.from.streamId !== fromStreamId) {
+        throw new Error(`chunk sender does not own transfer ${payload.transferId}`);
+    }
     if (manifest.completedAt) {
         return manifest;
     }
+    if (!Number.isInteger(payload.index) || payload.index < 0 || payload.index >= manifest.totalChunks) {
+        throw new Error(`invalid chunk index ${payload.index}`);
+    }
     if (payload.index !== manifest.receivedChunks) {
         throw new Error(`unexpected chunk index ${payload.index}; expected ${manifest.receivedChunks}`);
     }
     if (payload.totalChunks !== manifest.totalChunks) {
         throw new Error(`unexpected totalChunks ${payload.totalChunks}; expected ${manifest.totalChunks}`);
     }
+    if (typeof payload.data !== "string" || !BASE64_PATTERN.test(payload.data)) {
+        throw new Error("chunk data is not valid base64");
+    }
     const bytes = base64ToBytes(payload.data);
+    const expectedLength = Math.min(manifest.chunkSize, manifest.size - payload.index * manifest.chunkSize);
+    if (bytes.byteLength !== expectedLength) {
+        throw new Error(`unexpected chunk length ${bytes.byteLength}; expected ${expectedLength}`);
+    }
+    if (manifest.receivedBytes + bytes.byteLength > manifest.size) {
+        throw new Error("chunk would exceed the offered file size");
+    }
     appendFileSync(manifest.tempPath, bytes);
     manifest.receivedChunks += 1;
     manifest.receivedBytes += bytes.byteLength;
@@ -111,9 +176,19 @@ export function appendIncomingTransferChunk(stateDir, payload) {
     writeManifest(getTransferPaths(stateDir, payload.transferId).manifestPath, manifest);
     return manifest;
 }
-export function completeIncomingTransfer(stateDir, payload) {
+export function completeIncomingTransfer(stateDir, payload, fromStreamId) {
+    validateTransferId(payload?.transferId);
     const manifest = mustReadTransferManifest(stateDir, payload.transferId);
+    if (fromStreamId && manifest.from.streamId !== fromStreamId) {
+        throw new Error(`completion sender does not own transfer ${payload.transferId}`);
+    }
     if (!manifest.completedAt) {
+        if (!Number.isInteger(payload.totalChunks) || !Number.isSafeInteger(payload.size)) {
+            throw new Error("invalid completion metadata");
+        }
+        if (typeof payload.sha256 !== "string" || !SHA256_PATTERN.test(payload.sha256)) {
+            throw new Error("invalid completion sha256");
+        }
         if (payload.totalChunks !== manifest.totalChunks) {
             throw new Error(`unexpected totalChunks ${payload.totalChunks}; expected ${manifest.totalChunks}`);
         }
@@ -123,12 +198,14 @@ export function completeIncomingTransfer(stateDir, payload) {
         if (manifest.receivedBytes !== manifest.size || payload.size !== manifest.size) {
             throw new Error(`transfer size mismatch: received ${manifest.receivedBytes}, expected ${manifest.size}`);
         }
-        const bytes = new Uint8Array(readFileSync(manifest.tempPath));
-        const sha256 = sha256Hex(bytes);
-        if (sha256 !== manifest.sha256 || payload.sha256 !== manifest.sha256) {
+        const file = sha256File(manifest.tempPath);
+        if (file.size !== manifest.size) {
+            throw new Error(`transfer size mismatch on disk: ${file.size}, expected ${manifest.size}`);
+        }
+        if (file.sha256 !== manifest.sha256 || payload.sha256 !== manifest.sha256) {
             throw new Error("transfer sha256 mismatch");
         }
-        renameSync(manifest.tempPath, manifest.savedPath);
+        moveFileExclusive(manifest.tempPath, manifest.savedPath);
         manifest.completedAt = Date.now();
         manifest.updatedAt = manifest.completedAt;
         writeManifest(getTransferPaths(stateDir, payload.transferId).manifestPath, manifest);
@@ -168,6 +245,25 @@ export function readTransferManifest(stateDir, transferId) {
         return null;
     return JSON.parse(readFileSync(manifestPath, "utf8"));
 }
+/**
+ * Remove a transfer that cannot be completed. Sender matching prevents a peer
+ * from aborting somebody else's transfer by guessing its id.
+ */
+export function discardIncomingTransfer(stateDir, transferId, expectedSender) {
+    try {
+        validateTransferId(transferId);
+        const manifest = readTransferManifest(stateDir, transferId);
+        if (expectedSender && manifest?.from.streamId !== expectedSender)
+            return false;
+        const paths = getTransferPaths(stateDir, transferId);
+        rmSync(paths.tempPath, { force: true });
+        rmSync(paths.manifestPath, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function mustReadTransferManifest(stateDir, transferId) {
     const manifest = readTransferManifest(stateDir, transferId);
     if (!manifest) {
@@ -176,6 +272,7 @@ function mustReadTransferManifest(stateDir, transferId) {
     return manifest;
 }
 function getTransferPaths(stateDir, transferId) {
+    validateTransferId(transferId);
     const transfersDir = path.join(path.resolve(stateDir), "transfers");
     const downloadsDir = path.join(path.resolve(stateDir), "downloads");
     return {
@@ -196,11 +293,24 @@ function chooseSavedPath(downloadsDir, safeName, transferId) {
     if (!existsSync(direct)) {
         return direct;
     }
-    return path.join(downloadsDir, `${base}_${transferId}${ext}`);
+    const tagged = path.join(downloadsDir, `${base}_${transferId}${ext}`);
+    if (!existsSync(tagged))
+        return tagged;
+    for (let suffix = 2; suffix < 100_000; suffix += 1) {
+        const candidate = path.join(downloadsDir, `${base}_${transferId}_${suffix}${ext}`);
+        if (!existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`could not choose a free destination for ${safeName}`);
 }
 function sanitizeFileName(name) {
-    const base = path.basename(name || "download");
-    return base.replace(/[<>:"/\\|?*\x00-\x1F]/g, "_") || "download";
+    let safe = path.basename(name || "download")
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, "_")
+        .replace(/[. ]+$/g, "")
+        .slice(0, 180) || "download";
+    if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(safe))
+        safe = `_${safe}`;
+    return safe;
 }
 function guessMimeType(name, kind) {
     const ext = path.extname(name).toLowerCase();
@@ -233,6 +343,130 @@ export function bytesToBase64(bytes) {
 export function base64ToBytes(value) {
     return new Uint8Array(Buffer.from(value, "base64"));
 }
+function validateTransferId(transferId) {
+    if (typeof transferId !== "string" || !TRANSFER_ID_PATTERN.test(transferId)) {
+        throw new Error("invalid transfer id");
+    }
+}
+function validateFileOffer(offer) {
+    if (!offer || typeof offer !== "object")
+        throw new Error("file offer is not an object");
+    validateTransferId(offer.transferId);
+    if (typeof offer.name !== "string" || !offer.name.trim() || offer.name.length > 1_024 || offer.name.includes("\0")) {
+        throw new Error("invalid file name");
+    }
+    if (typeof offer.mimeType !== "string" || offer.mimeType.length > 256) {
+        throw new Error("invalid mime type");
+    }
+    if (offer.kind !== "file" && offer.kind !== "image")
+        throw new Error("invalid transfer kind");
+    if (!Number.isSafeInteger(offer.size) || offer.size < 0 || offer.size > MAX_BASIC_TRANSFER_SIZE) {
+        throw new Error(`invalid file size; maximum is ${MAX_BASIC_TRANSFER_SIZE} bytes`);
+    }
+    if (typeof offer.sha256 !== "string" || !SHA256_PATTERN.test(offer.sha256)) {
+        throw new Error("invalid file sha256");
+    }
+    if (!Number.isInteger(offer.chunkSize) ||
+        offer.chunkSize < 1_024 ||
+        offer.chunkSize > MAX_BASIC_TRANSFER_CHUNK_SIZE) {
+        throw new Error("invalid file chunk size");
+    }
+    if (!Number.isInteger(offer.totalChunks) ||
+        offer.totalChunks < 0 ||
+        offer.totalChunks > MAX_BASIC_TRANSFER_CHUNKS) {
+        throw new Error("invalid file chunk count");
+    }
+    const expected = offer.size === 0 ? 0 : Math.ceil(offer.size / offer.chunkSize);
+    if (offer.totalChunks !== expected) {
+        throw new Error(`file chunk count ${offer.totalChunks} does not match size/chunkSize (${expected})`);
+    }
+}
+function moveFileExclusive(source, destination) {
+    try {
+        linkSync(source, destination);
+        try {
+            rmSync(source);
+        }
+        catch {
+            // The destination is already a complete independent directory entry.
+            // A leftover temp file is cleanup debt, not a failed delivery.
+        }
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EEXIST")
+            throw new Error(`destination already exists: ${destination}`);
+        if (existsSync(destination))
+            throw error;
+        if (code !== "EXDEV" && code !== "EPERM" && code !== "EACCES")
+            throw error;
+    }
+    copyFileSync(source, destination, constants.COPYFILE_EXCL);
+    try {
+        rmSync(source);
+    }
+    catch {
+        // See the hard-link path above.
+    }
+}
+function enforceIncomingTransferQuota(stateDir, incomingSize) {
+    const transfersDir = path.join(path.resolve(stateDir), "transfers");
+    if (!existsSync(transfersDir))
+        return;
+    let activeCount = 0;
+    let promisedBytes = 0;
+    const now = Date.now();
+    for (const name of readdirSync(transfersDir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const transferId = name.slice(0, -5);
+        if (!TRANSFER_ID_PATTERN.test(transferId))
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(path.join(transfersDir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (manifest.completedAt || !existsSync(path.join(transfersDir, `${transferId}.part`)))
+            continue;
+        if (Number.isFinite(manifest.updatedAt) && now - manifest.updatedAt >= INCOMPLETE_TRANSFER_STALE_MS) {
+            discardIncomingTransfer(stateDir, transferId);
+            continue;
+        }
+        activeCount += 1;
+        promisedBytes += Number.isSafeInteger(manifest.size) && manifest.size >= 0
+            ? manifest.size
+            : MAX_BASIC_TRANSFER_SIZE;
+    }
+    if (activeCount >= MAX_INCOMPLETE_TRANSFERS) {
+        throw new Error(`too many incomplete file transfers (${activeCount}/${MAX_INCOMPLETE_TRANSFERS})`);
+    }
+    if (promisedBytes + incomingSize > MAX_INCOMPLETE_TRANSFER_BYTES) {
+        throw new Error(`incomplete file transfers would exceed the ${MAX_INCOMPLETE_TRANSFER_BYTES}-byte quota`);
+    }
+}
+function sha256File(filePath) {
+    const fd = openSync(filePath, "r");
+    try {
+        const hash = createHash("sha256");
+        const buffer = new Uint8Array(1024 * 1024);
+        let position = 0;
+        for (;;) {
+            const read = readSync(fd, buffer, 0, buffer.length, position);
+            if (read === 0)
+                break;
+            hash.update(buffer.subarray(0, read));
+            position += read;
+        }
+        return { sha256: hash.digest("hex"), size: position };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function readSavedTransferBytes(savedPath) {
     return new Uint8Array(readFileSync(savedPath));
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { MessageBus, type KeywordTrigger, type MessageBusOptions, type SendDataFn } from "./message-bus.js";
 export { PeerRegistry, type PeerRecord, type PeerRegistryEvents } from "./peer-registry.js";
 export { ensureAgentState, getInboxSummary, isInboxWorthy, listInboxMessages, listQueuedAgentActions, queueAgentAction, readAgentSession, readPeersSnapshot, removeQueuedAgentAction, storeInboxMessage, takeInboxMessages, writeAgentSession, writePeersSnapshot, type AgentSessionState, type InboxMessage, type InboxSummary, type QueuedAgentAction, type QueuedAgentActionInput, } from "./agent-state.js";
-export { DEFAULT_TRANSFER_CHUNK_SIZE, appendIncomingTransferChunk, beginIncomingTransfer, bytesToBase64, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, prepareFileTransferFromPath, readSavedTransferBytes, readTransferManifest, sendFileFromPath, sendPreparedFileTransfer, sha256Hex, type CompletedTransferResult, type IncomingTransferManifest, type PreparedFileTransfer, } from "./file-transfer.js";
+export { DEFAULT_TRANSFER_CHUNK_SIZE, appendIncomingTransferChunk, beginIncomingTransfer, bytesToBase64, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, discardIncomingTransfer, INCOMPLETE_TRANSFER_STALE_MS, MAX_BASIC_TRANSFER_CHUNK_SIZE, MAX_BASIC_TRANSFER_CHUNKS, MAX_BASIC_TRANSFER_SIZE, MAX_INCOMPLETE_TRANSFER_BYTES, MAX_INCOMPLETE_TRANSFERS, prepareFileTransferFromPath, readSavedTransferBytes, readTransferManifest, sendFileFromPath, sendPreparedFileTransfer, sha256Hex, type CompletedTransferResult, type IncomingTransferManifest, type PreparedFileTransfer, } from "./file-transfer.js";
 export { createEnvelope, createInstanceId, createMessageId, envelopeToWire, type FileAckPayload, type FileChunkPayload, type FileCompletePayload, type FileOfferPayload, type FileTransferKind, generateRoomName, isValidEnvelope, parseEnvelope, type AgentAsk, type AgentProfile, type AnnouncePayload, type MessageEnvelope, type MessageType, type PeerIdentity, type SharedFolderSummary, type SkillUpdatePayload, } from "./protocol.js";
 export { inferTransferKind, listSharedFolderEntries, parseSharedFolderSpecs, resolveSharedFile, toSharedFolderSummaries, type ResolvedSharedFile, type SharedFolderConfig, type SharedFolderEntry, type SharedFolderListing, } from "./shared-folders.js";
 export { VDOBridge, type VDOBridgeOptions } from "./vdo-bridge.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { MessageBus } from "./message-bus.js";
 export { PeerRegistry } from "./peer-registry.js";
 export { ensureAgentState, getInboxSummary, isInboxWorthy, listInboxMessages, listQueuedAgentActions, queueAgentAction, readAgentSession, readPeersSnapshot, removeQueuedAgentAction, storeInboxMessage, takeInboxMessages, writeAgentSession, writePeersSnapshot, } from "./agent-state.js";
-export { DEFAULT_TRANSFER_CHUNK_SIZE, appendIncomingTransferChunk, beginIncomingTransfer, bytesToBase64, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, prepareFileTransferFromPath, readSavedTransferBytes, readTransferManifest, sendFileFromPath, sendPreparedFileTransfer, sha256Hex, } from "./file-transfer.js";
+export { DEFAULT_TRANSFER_CHUNK_SIZE, appendIncomingTransferChunk, beginIncomingTransfer, bytesToBase64, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, discardIncomingTransfer, INCOMPLETE_TRANSFER_STALE_MS, MAX_BASIC_TRANSFER_CHUNK_SIZE, MAX_BASIC_TRANSFER_CHUNKS, MAX_BASIC_TRANSFER_SIZE, MAX_INCOMPLETE_TRANSFER_BYTES, MAX_INCOMPLETE_TRANSFERS, prepareFileTransferFromPath, readSavedTransferBytes, readTransferManifest, sendFileFromPath, sendPreparedFileTransfer, sha256Hex, } from "./file-transfer.js";
 export { createEnvelope, createInstanceId, createMessageId, envelopeToWire, generateRoomName, isValidEnvelope, parseEnvelope, } from "./protocol.js";
 export { inferTransferKind, listSharedFolderEntries, parseSharedFolderSpecs, resolveSharedFile, toSharedFolderSummaries, } from "./shared-folders.js";
 export { VDOBridge } from "./vdo-bridge.js";

package/dist/message-bus.d.ts

@@ -16,7 +16,8 @@ export type KeywordTrigger = {
     pattern: RegExp;
     handler: (msg: MessageEnvelope) => void;
 };
-export type SendDataFn = (data: object, target?: unknown) => void;
+/** Return false when the transport could not accept the message yet. */
+export type SendDataFn = (data: object, target?: unknown) => boolean | void;
 export type MessageBusOptions = {
     /** Max messages kept in history ring buffer. Default: 200. */
     historySize?: number;
@@ -47,6 +48,21 @@ export declare class MessageBus extends EventEmitter {
     getSubscriptions(): string[];
     /** Broadcast a message to all connected peers. */
     broadcast(type: MessageType, payload: unknown, topic?: string): MessageEnvelope;
+    /**
+     * Send something that is only worth delivering right now, reporting whether
+     * the transport took it.
+     *
+     * Unlike `send`, a failure is not queued for replay and nothing enters the
+     * history ring. Both matter for swarm traffic: a chunk request replayed from
+     * a queue asks for something the requester already has, and a few seconds of
+     * transfer is enough to evict every real message from history.
+     *
+     * The returned boolean is the point. A caller that assumes a send succeeded
+     * will sit waiting out a request timeout for a message that never left.
+     */
+    trySend(targetStreamId: string, type: MessageType, payload: unknown): boolean;
+    /** Broadcast counterpart of `trySend`: not retained, not replayed. */
+    tryBroadcast(type: MessageType, payload: unknown): boolean;
     /** Send a message to a specific peer (by streamId). */
     send(targetStreamId: string, type: MessageType, payload: unknown): MessageEnvelope;
     /** Publish a message to a topic (only peers subscribed to that topic receive it).

package/dist/message-bus.js

@@ -10,7 +10,7 @@
  * Zero dependencies on stevesbot internals.
  */
 import { EventEmitter } from "node:events";
-import { createEnvelope, envelopeToWire, } from "./protocol.js";
+import { createEnvelope, envelopeToWire, isTransientType, } from "./protocol.js";
 // ── Class ────────────────────────────────────────────────────────────────────
 export class MessageBus extends EventEmitter {
     identity;
@@ -65,15 +65,39 @@ export class MessageBus extends EventEmitter {
         this.rawSend(envelope, null);
         return envelope;
     }
+    /**
+     * Send something that is only worth delivering right now, reporting whether
+     * the transport took it.
+     *
+     * Unlike `send`, a failure is not queued for replay and nothing enters the
+     * history ring. Both matter for swarm traffic: a chunk request replayed from
+     * a queue asks for something the requester already has, and a few seconds of
+     * transfer is enough to evict every real message from history.
+     *
+     * The returned boolean is the point. A caller that assumes a send succeeded
+     * will sit waiting out a request timeout for a message that never left.
+     */
+    trySend(targetStreamId, type, payload) {
+        if (!this.peers.isConnected(targetStreamId))
+            return false;
+        const envelope = createEnvelope(this.identity, type, payload, { to: targetStreamId });
+        return this.rawSend(envelope, targetStreamId);
+    }
+    /** Broadcast counterpart of `trySend`: not retained, not replayed. */
+    tryBroadcast(type, payload) {
+        const envelope = createEnvelope(this.identity, type, payload);
+        return this.rawSend(envelope, null);
+    }
     /** Send a message to a specific peer (by streamId). */
     send(targetStreamId, type, payload) {
         const envelope = createEnvelope(this.identity, type, payload, { to: targetStreamId });
-        this.addToHistory(envelope);
-        if (this.peers.isConnected(targetStreamId)) {
-            this.rawSend(envelope, targetStreamId);
-        }
-        else {
-            this.enqueueOffline(targetStreamId, envelope);
+        // Transient types are still deliverable this way, but never retained or
+        // queued, so a caller reaching for the wrong method cannot flood history.
+        if (!isTransientType(type))
+            this.addToHistory(envelope);
+        if (!this.peers.isConnected(targetStreamId) || !this.rawSend(envelope, targetStreamId)) {
+            if (!isTransientType(type))
+                this.enqueueOffline(targetStreamId, envelope);
         }
         return envelope;
     }
@@ -142,13 +166,21 @@ export class MessageBus extends EventEmitter {
         const queue = this.offlineQueues.get(streamId);
         if (!queue || queue.length === 0)
             return [];
-        this.offlineQueues.delete(streamId);
-        // Send each queued message wrapped as history_replay
+        const flushed = [];
         for (const msg of queue) {
-            const replay = createEnvelope(this.identity, "history_replay", msg, { to: streamId });
-            this.rawSend(replay, streamId);
+            // Preserve the original type and ID. Wrapping queued commands as
+            // history_replay prevented normal command/file handlers from seeing them.
+            if (!this.rawSend(msg, streamId))
+                break;
+            flushed.push(msg);
+        }
+        if (flushed.length === queue.length) {
+            this.offlineQueues.delete(streamId);
+        }
+        else if (flushed.length > 0) {
+            this.offlineQueues.set(streamId, queue.slice(flushed.length));
         }
-        return queue;
+        return flushed;
     }
     /** Get the number of queued messages for a peer. */
     getOfflineQueueSize(streamId) {
@@ -174,25 +206,31 @@ export class MessageBus extends EventEmitter {
     // ── Internals ────────────────────────────────────────────────────────────
     rawSend(envelope, target) {
         if (!this.sendDataFn)
-            return;
+            return false;
         const wire = envelopeToWire(envelope);
+        let accepted;
         if (target) {
             // Prefer uuid targeting once we know it; streamID targeting can be ambiguous
             // before announce/rekey completes on some SDK connection paths.
             const peer = this.peers.getPeer(target);
             if (peer?.uuid) {
-                this.sendDataFn(wire, { uuid: peer.uuid });
+                accepted = this.sendDataFn(wire, { uuid: peer.uuid });
             }
             else {
-                this.sendDataFn(wire, { streamID: target });
+                accepted = this.sendDataFn(wire, { streamID: target });
             }
         }
         else {
             // Broadcast to all
-            this.sendDataFn(wire);
+            accepted = this.sendDataFn(wire);
         }
+        // Void preserves compatibility with existing transports written before
+        // acceptance results were supported. Only an explicit false is a failure.
+        return accepted !== false;
     }
     addToHistory(envelope) {
+        if (isTransientType(envelope.type))
+            return;
         // Don't store heartbeat or file chunk traffic in history.
         if (envelope.type === "ping" || envelope.type === "pong" || envelope.type === "file_chunk")
             return;
@@ -221,6 +259,7 @@ export class MessageBus extends EventEmitter {
         if (!text)
             return;
         for (const trigger of this.triggers) {
+            trigger.pattern.lastIndex = 0;
             if (trigger.pattern.test(text)) {
                 try {
                     trigger.handler(envelope);

package/dist/peer-registry.js

@@ -18,6 +18,13 @@ export class PeerRegistry extends EventEmitter {
     addPeer(streamId, uuid) {
         const existing = this.peers.get(streamId);
         if (existing) {
+            const duplicateForUuid = this.resolve(uuid);
+            if (duplicateForUuid && duplicateForUuid !== existing) {
+                this.peers.delete(duplicateForUuid.streamId);
+                this.uuidToStream.delete(duplicateForUuid.uuid);
+            }
+            if (existing.uuid !== uuid)
+                this.uuidToStream.delete(existing.uuid);
             existing.uuid = uuid;
             existing.connected = true;
             existing.connectedAt = Date.now();

package/dist/protocol.d.ts

@@ -5,7 +5,19 @@
  * WebRTC data channels. This module has zero dependencies on stevesbot
  * internals — it can be extracted and reused by any bot.
  */
-export type MessageType = "chat" | "announce" | "skill_update" | "command" | "command_response" | "file_offer" | "file_chunk" | "file_complete" | "file_ack" | "event" | "ping" | "pong" | "ack" | "history_replay" | "history_request";
+export type MessageType = "chat" | "announce" | "skill_update" | "command" | "command_response" | "file_offer" | "file_chunk" | "file_complete" | "file_ack" | "event" | "ping" | "pong" | "ack" | "history_replay" | "history_request" | "swarm_offer" | "swarm_manifest_request" | "swarm_manifest_page" | "swarm_announce" | "swarm_request" | "swarm_chunk" | "swarm_have";
+/**
+ * Messages that are only worth delivering right now.
+ *
+ * Transfer traffic is high volume and stateful: a chunk request replayed from
+ * an offline queue minutes later asks for something the requester already has,
+ * while replaying half of a simple file transfer cannot restore its missing
+ * half. A history ring full of chunks also evicts every real message a peer
+ * asking for history actually wanted. Swarm state is re-announced; a rejected
+ * simple transfer fails explicitly and can be retried from the start.
+ */
+export declare const TRANSIENT_MESSAGE_TYPES: ReadonlySet<MessageType>;
+export declare function isTransientType(type: MessageType): boolean;
 export type PeerIdentity = {
     streamId: string;
     role: string;
@@ -32,6 +44,71 @@ export type AgentProfile = {
     asks?: AgentAsk[];
     shares?: SharedFolderSummary[];
 };
+/** Announces that a file exists in the swarm and describes how it is chunked. */
+export type SwarmOfferPayload = {
+    fileId: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    chunkSize: number;
+    totalChunks: number;
+    /** sha256 over the raw 32-byte chunk hashes, in chunk order. */
+    chunkHashesHash?: string;
+    /**
+     * Small manifests ride inline. Large manifests are requested in bounded
+     * pages, otherwise one offer eventually exceeds the negotiated SCTP message
+     * limit and silently becomes impossible to send.
+     */
+    chunkHashes?: string[];
+    manifestPageSize?: number;
+    manifestPages?: number;
+};
+/** Ask a source for selected pages of a large chunk-hash manifest. */
+export type SwarmManifestRequestPayload = {
+    fileId: string;
+    pageSize: number;
+    pages: number[];
+};
+/** One bounded page of chunk hashes. */
+export type SwarmManifestPagePayload = {
+    fileId: string;
+    page: number;
+    totalPages: number;
+    pageSize: number;
+    chunkHashesHash: string;
+    hashes: string[];
+};
+/** A peer's full chunk bitfield, base64 encoded. */
+export type SwarmAnnouncePayload = {
+    fileId: string;
+    totalChunks: number;
+    chunks: string;
+};
+export type SwarmRequestPayload = {
+    fileId: string;
+    index: number;
+    /**
+     * Set when the requester can receive the chunk as raw bytes on the binary
+     * lane. Carrying it on the request rather than negotiating up front means
+     * there is no capability table to keep in sync and no window where a peer
+     * that just joined is assumed to be one thing or the other — each request
+     * states how its own reply should come back.
+     */
+    bin?: 1;
+};
+export type SwarmChunkPayload = {
+    fileId: string;
+    index: number;
+    data: string;
+};
+/** Incremental "I now hold these chunks", so peers learn without a full re-announce. */
+export type SwarmHavePayload = {
+    fileId: string;
+    /** Batched indexes. Preferred; one message can carry a whole burst. */
+    indexes?: number[];
+    /** Single index, kept so a peer running an older build is still understood. */
+    index?: number;
+};
 export type FileTransferKind = "file" | "image";
 export type FileOfferPayload = {
     transferId: string;