@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/format/mentions.js

@@ -0,0 +1,140 @@
+/**
+ * Zalo @-mention offsets.
+ *
+ * A mention is `{ pos, uid, len }`, where `pos` and `len` are **UTF-16
+ * code-unit offsets into the message string** — not byte offsets, and not
+ * grapheme counts. Zalo renders the tag over exactly `text.slice(pos, pos +
+ * len)`, so an offset that is off by one paints the highlight over the wrong
+ * span and the tagged person may not be notified at all.
+ *
+ * Measured against real mentions in a local cache (name changed):
+ *
+ *     text  "Em ko biết mở ch ạ @Trần Bích Ngọc"   { pos: 19, len: 15 }
+ *     text.slice(19, 34)              === "@Trần Bích Ngọc"       correct
+ *     Buffer.from(text).slice(19, 34) -> "h ạ @Trần Bí…"          wrong
+ *
+ * Accented Vietnamese is exactly where hand-counted offsets break, and it is
+ * most of what this CLI sends. So `--mention <pos:uid:len>` stays for
+ * back-compat, but the `@[uid]` token form below computes the offsets from
+ * the string it just built and is the one to reach for.
+ */
+
+/** The uid Zalo reserves for @All. The send turns it into `type: 1`. */
+export const ALL_MENTION_UID = "-1";
+
+/**
+ * Label used for `@[-1]` when no name is supplied.
+ *
+ * Zalo's own clients write the literal "@All" (confirmed on real @All rows
+ * in the cache: `{ uid: "-1", pos: 0, len: 4, type: 1 }`), including in
+ * Vietnamese groups. Do not localize this.
+ */
+export const ALL_MENTION_LABEL = "All";
+
+/**
+ * `@[uid]` — the token expanded by {@link expandMentions}.
+ *
+ * Deliberately restricted to decimal ids (plus `-1` for @All), which is every
+ * uid Zalo accepts in a mention. Anything else in brackets — `@[see below]`,
+ * `@[TODO]` — is left in the text verbatim rather than turned into a mention
+ * of a uid that does not exist.
+ */
+const MENTION_TOKEN = /@\[(-?\d+)\]/g;
+
+/**
+ * Parse the legacy `--mention pos:uid:len` specs.
+ *
+ * Kept because scripts pass it; `@[uid]` tokens are the safe way in. Specs
+ * that are not three colon-separated parts, or whose pos/len are not numbers,
+ * are dropped rather than sent as NaN — the send's own filter would discard
+ * them anyway, silently and later.
+ *
+ * @param {string[]} [specs] - raw `pos:uid:len` strings
+ * @returns {{pos: number, uid: string, len: number}[]}
+ */
+export function parseMentionSpecs(specs) {
+    return (specs || [])
+        .map((spec) => {
+            const [pos, uid, len] = String(spec).split(":");
+            if (!uid) return null;
+            const parsed = { pos: Number(pos), uid, len: Number(len) };
+            if (!Number.isFinite(parsed.pos) || !Number.isFinite(parsed.len)) return null;
+            return parsed;
+        })
+        .filter(Boolean);
+}
+
+/**
+ * Expand `@[uid]` tokens into `@Display Name`, recording each mention's
+ * offsets in the string that comes out.
+ *
+ * Because the offsets are measured on the built string rather than counted by
+ * hand, they are correct whatever the surrounding text contains — accents,
+ * emoji, earlier mentions of different lengths.
+ *
+ * `edits` reports each substitution in *input* coordinates so that text
+ * styles counted against the pre-expansion message can be moved with
+ * {@link shiftStyles}.
+ *
+ * @param {string} text - message body, possibly containing `@[uid]` tokens
+ * @param {(uid: string) => (string|null|undefined)} [resolveName] - uid → display
+ *   name; anything falsy falls back to "All" for `@[-1]` and to the uid itself
+ *   otherwise, so an unknown user still gets a syntactically valid mention
+ * @returns {{text: string, mentions: {pos: number, uid: string, len: number}[],
+ *            edits: {start: number, oldLen: number, newLen: number}[]}}
+ */
+export function expandMentions(text, resolveName) {
+    const src = String(text ?? "");
+    const mentions = [];
+    const edits = [];
+    let out = "";
+    let cursor = 0;
+
+    // lastIndex is shared state on a module-level regex, so iterate a fresh copy.
+    const token = new RegExp(MENTION_TOKEN.source, "g");
+    let match;
+    while ((match = token.exec(src)) !== null) {
+        const uid = match[1];
+        const resolved = typeof resolveName === "function" ? resolveName(uid) : null;
+        const name = resolved || (uid === ALL_MENTION_UID ? ALL_MENTION_LABEL : uid);
+        const label = `@${name}`;
+
+        out += src.slice(cursor, match.index);
+        mentions.push({ pos: out.length, uid, len: label.length });
+        edits.push({ start: match.index, oldLen: match[0].length, newLen: label.length });
+        out += label;
+        cursor = match.index + match[0].length;
+    }
+    out += src.slice(cursor);
+
+    return { text: out, mentions, edits };
+}
+
+/**
+ * Move text styles across the edits {@link expandMentions} made.
+ *
+ * `--style start:len:style` and `--md` both produce offsets against the
+ * message *before* mentions expand, and a `@[uid]` token is almost always
+ * shorter than the name it becomes. Without this, `--md` plus a mention
+ * silently paints bold over the wrong words.
+ *
+ * A style that starts after an edit moves by the edit's delta; a style that
+ * spans one grows by it (`**hi @[123]**` keeps the whole run bold).
+ *
+ * @param {{start: number, len: number, st: string}[]} styles
+ * @param {{start: number, oldLen: number, newLen: number}[]} edits
+ * @returns {{start: number, len: number, st: string}[]}
+ */
+export function shiftStyles(styles, edits) {
+    if (!edits || edits.length === 0) return styles;
+    return styles.map((style) => {
+        let start = style.start;
+        let len = style.len;
+        for (const edit of edits) {
+            const delta = edit.newLen - edit.oldLen;
+            if (edit.start < style.start) start += delta;
+            else if (edit.start < style.start + style.len) len += delta;
+        }
+        return { ...style, start, len };
+    });
+}

package/src/zalo/format/split-message.js

@@ -0,0 +1,222 @@
+/**
+ * Splitting a long text message the way Zalo does.
+ *
+ * Zalo refuses one oversized message instead of cutting it: `114 "Tham số không hợp lệ"` for plain text past 3000
+ * UTF-16 units, and `112 "Lỗi không xác định"` for a styled message (what Markdown becomes) whose text plus style
+ * list passes roughly 3.1 to 3.5 KB. Chinese and long bulleted answers hit the second one early, because a Chinese
+ * character is three bytes and each bullet carries a style entry. Measured live, 2026-10-29.
+ *
+ * Zalo's own apps never send such a message. They budget every message at 3000 UTF-8 bytes of the
+ * text plus, for a styled message, the JSON of its styles; cuts at a newline when it can, else at a sentence end or
+ * a space; trims the pieces; and sends them one after another, 300 ms apart. This does the same.
+ *
+ * Pure: no I/O, no Zalo. Styles are `{ start, len, st }` and mentions `{ pos, len, uid }`, both in UTF-16 units of
+ * the text they belong to; each part gets its own text and the ranges re-based to it.
+ */
+
+/** The most UTF-8 bytes of text (plus style JSON) in one message. */
+export const MESSAGE_BYTE_LIMIT = 3000;
+
+/** The pause between parts of one split message. */
+export const PART_GAP_MS = 300;
+
+const byteLength = (s) => Buffer.byteLength(s, "utf8");
+
+const graphemes = new Intl.Segmenter("und", { granularity: "grapheme" });
+
+/**
+ * Move `cut` back to the nearest boundary between user-perceived characters, so a hard cut never splits a Thai or
+ * Devanagari syllable (a base letter and its vowel and tone marks), an Arabic letter and its marks, a flag, a skin
+ * tone or an emoji joined by zero-width joiners. Only looks a little either side: a cluster is never that long.
+ *
+ * @returns {number} a boundary in `(pos, cut]`, or `cut` itself when none is found
+ */
+function snapToGrapheme(text, pos, cut) {
+    if (cut <= pos || cut >= text.length) return cut;
+    const from = Math.max(pos, cut - 64);
+    let best = -1;
+    for (const { index } of graphemes.segment(text.slice(from, cut + 64))) {
+        const at = from + index;
+        if (at > cut) break;
+        if (at > pos) best = at;
+    }
+    return best > pos ? best : cut;
+}
+
+/** Style ranges clipped to `[from, to)` and re-based to `from`. */
+function clipStyles(styles, from, to) {
+    const out = [];
+    for (const s of styles) {
+        const a = Math.max(s.start, from);
+        const b = Math.min(s.start + s.len, to);
+        if (b > a) out.push({ ...s, start: a - from, len: b - a });
+    }
+    return out;
+}
+
+/** What one message costs against the limit: its text bytes plus its style list. */
+function cost(text, styles) {
+    return byteLength(text) + (styles.length > 0 ? byteLength(JSON.stringify(styles)) : 0);
+}
+
+/**
+ * Sentence and clause marks of the scripts Zalo is used in, ranked like the ASCII ones (a full stop strongest). They
+ * need no space after them: Chinese, Japanese, Thai, Burmese and Khmer write none.
+ */
+const MARKS = {
+    // full stops: CJK, fullwidth, Devanagari danda and double danda, Arabic/Urdu, Armenian, Ethiopic, Burmese, Khmer
+    "。": 6,
+    "．": 6,
+    "।": 6,
+    "॥": 6,
+    "۔": 6,
+    "։": 6,
+    "።": 6,
+    "။": 6,
+    "។": 6,
+    "៕": 6,
+    // question marks: fullwidth, Arabic
+    "？": 5,
+    "؟": 5,
+    // exclamation: fullwidth
+    "！": 4,
+    // semicolons: fullwidth, Arabic
+    "；": 2,
+    "؛": 2,
+    // commas: fullwidth, ideographic, halfwidth ideographic, Arabic, Ethiopic; and the ideographic space
+    "，": 1,
+    "、": 1,
+    "､": 1,
+    "،": 1,
+    "፣": 1,
+    "\u3000": 0,
+};
+
+/**
+ * How good a place `text[i]` is to end a part after: higher is better, null when it is no break at all.
+ * The ASCII order (`" ,;)!?."`, a full stop strongest), a newline above all, and the marks other scripts use for the
+ * same jobs (an ASCII-only list would cut a long Chinese, Hindi or Arabic text with few spaces blind).
+ */
+function breakRank(text, i) {
+    const c = text[i];
+    if (c === "\n") return 7;
+    const mark = MARKS[c];
+    if (mark !== undefined) return mark;
+    const ascii = " ,;)!?.".indexOf(c);
+    if (ascii === -1) return null;
+    const next = text[i + 1];
+    return c === " " || next === undefined || next === " " || next === "\n" ? ascii : null;
+}
+
+/**
+ * Where to cut `text` between `pos` and `end` (the farthest the budget allows): the nearest newline in the last two
+ * thirds of the window, else the strongest sentence or clause end there, else `end` itself.
+ *
+ * @returns {number} the cut: the part is `text.slice(pos, cut)`
+ */
+function chooseCut(text, pos, end) {
+    const floor = pos + Math.floor((end - pos) / 3);
+    let best = -1;
+    let bestRank = -1;
+    for (let i = end - 1; i >= floor && i >= pos; i--) {
+        const rank = breakRank(text, i);
+        if (rank === null) continue;
+        if (rank === 7) return i; // the newline is dropped with the whitespace that follows
+        if (rank > bestRank) {
+            best = i + 1;
+            bestRank = rank;
+        }
+    }
+    return best > pos ? best : end;
+}
+
+/**
+ * Split one message into parts that each fit {@link MESSAGE_BYTE_LIMIT}. A message that fits comes back untouched
+ * (the same text, no trimming), so only a message that needed splitting is ever changed.
+ *
+ * A style range that spans a cut is clipped into both parts. A mention is never cut: the cut moves before it. A
+ * user-perceived character (an emoji, a flag, a Thai or Devanagari syllable with its marks) is never cut. Whitespace
+ * at a cut is dropped: the parts are trimmed.
+ *
+ * @param {{text: string, styles?: Array<{start: number, len: number, st: string}>, mentions?: Array<{pos: number, len: number, uid: string}>}} message
+ * @param {number} [limit] - bytes per part
+ * @returns {Array<{text: string, styles: object[], mentions: object[]}>} at least one part
+ */
+export function splitMessage({ text, styles = [], mentions = [] }, limit = MESSAGE_BYTE_LIMIT) {
+    if (cost(text, styles) <= limit) return [{ text, styles, mentions }];
+
+    const parts = [];
+    let pos = 0;
+    while (pos < text.length) {
+        // The farthest end this part can reach inside the budget (always at least one character).
+        let lo = pos + 1;
+        let hi = text.length;
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            if (cost(text.slice(pos, mid), clipStyles(styles, pos, mid)) <= limit) lo = mid;
+            else hi = mid - 1;
+        }
+        let cut = lo;
+
+        if (cut < text.length) {
+            cut = chooseCut(text, pos, cut);
+            for (const m of mentions) {
+                if (m.pos > pos && m.pos < cut && cut < m.pos + m.len) cut = m.pos;
+            }
+            cut = snapToGrapheme(text, pos, cut);
+            const high = text.charCodeAt(cut - 1);
+            if (high >= 0xd800 && high <= 0xdbff) cut -= 1;
+            if (cut <= pos) cut = Math.min(text.length, pos + 2);
+        }
+
+        const raw = text.slice(pos, cut);
+        const body = raw.trimEnd();
+        if (body.length > 0) {
+            const end = pos + body.length;
+            parts.push({
+                text: body,
+                styles: clipStyles(styles, pos, end),
+                mentions: mentions
+                    .filter((m) => m.pos >= pos && m.pos + m.len <= end)
+                    .map((m) => ({ ...m, pos: m.pos - pos })),
+            });
+        }
+        pos = cut;
+        // Trim each remainder: the whitespace at a cut belongs to no part.
+        while (pos < text.length && /\s/.test(text[pos])) pos++;
+    }
+    return parts.length > 0 ? parts : [{ text, styles, mentions }];
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Send the parts of one message one after another, {@link PART_GAP_MS} apart. Stops at the first part Zalo refuses
+ * and says how many had already gone out, because nothing can take those back.
+ *
+ * @template T
+ * @param {Array<object>} parts - from {@link splitMessage}
+ * @param {(part: object, index: number) => Promise<T>} send - sends one part, resolves what Zalo answered
+ * @param {{gapMs?: number, sleep?: (ms: number) => Promise<void>}} [opts]
+ * @returns {Promise<T[]>} what Zalo answered for each part, in order
+ * @throws {Error} with `.sent` (the answers of the parts that went out) set when a later part failed
+ */
+export async function sendParts(parts, send, { gapMs = PART_GAP_MS, sleep = defaultSleep } = {}) {
+    const answers = [];
+    for (let i = 0; i < parts.length; i++) {
+        if (i > 0) await sleep(gapMs);
+        try {
+            answers.push(await send(parts[i], i));
+        } catch (e) {
+            if (i === 0) throw e;
+            const failure = new Error(
+                `${e?.message ?? e} (part ${i + 1} of ${parts.length} failed; the ${i} earlier part(s) were already delivered)`,
+                { cause: e },
+            );
+            failure.sent = answers;
+            if (e?.code !== undefined) failure.code = e.code;
+            throw failure;
+        }
+    }
+    return answers;
+}

package/src/zalo/format/urgency.js

@@ -0,0 +1,29 @@
+/**
+ * Zalo's message urgency, as the apps' Important/Urgent option sends it.
+ *
+ * Zalo marks a text message `metaData: {urgency: 1}` (important) or
+ * `metaData: {urgency: 2}` (urgent) on the ordinary send endpoints, group and
+ * 1-1 alike; the session builds that object from `sendMessage({msg, urgency})` and
+ * ignores any other value. `msg send --urgency` and `zalo_send_message`'s
+ * `urgency` both map a name to the level here, so the two cannot drift.
+ */
+
+/** Zalo's message urgency levels, as the apps offer them. */
+export const URGENCY_LEVELS = { important: 1, urgent: 2 };
+
+/**
+ * The level for an urgency name, or null for anything that is not one.
+ *
+ * Case and surrounding spaces are ignored, as `msg send --urgency` always has.
+ * "normal" is not a level: an ordinary message carries no urgency at all.
+ * Only the table's own keys count: a plain lookup also found what every
+ * object inherits, so `--urgency constructor` came back as a function and
+ * was sent instead of refused.
+ *
+ * @param {string} value - `important` or `urgent`
+ * @returns {number|null} 1 or 2, or null
+ */
+export function urgencyLevel(value) {
+    const key = String(value).trim().toLowerCase();
+    return Object.hasOwn(URGENCY_LEVELS, key) ? URGENCY_LEVELS[key] : null;
+}

package/src/zalo/headers.js

@@ -0,0 +1,93 @@
+/**
+ * The headers a browser adds to every XHR it makes, which the previous engine left out (plan item L7).
+ *
+ * The previous engine sent `Accept`, `Accept-Language`, `Content-Type`, `Cookie`, `Origin`, `Referer` and `User-Agent`.
+ * A real browser also sends the Client Hints that match its User-Agent, the three `sec-fetch-*` headers
+ * and, in Chromium, `priority`. Other extras a browser may add (`cache-control`, `pragma`, `dnt`) come from DevTools
+ * and user settings, not the page, and are not sent.
+ *
+ * Everything is derived from the saved User-Agent, so a session always presents ONE coherent browser. A
+ * User-Agent that is not Chromium (an older login made with a Firefox one) gets the `sec-fetch-*` headers
+ * only: Firefox sends no Client Hints, and claiming some would be the oddity this module exists to remove.
+ */
+
+/**
+ * The Client Hints a Chromium User-Agent implies.
+ *
+ * @param {string} userAgent
+ * @returns {{secChUa: string, secChUaPlatform: string, secChUaMobile: string}|null} null for a User-Agent
+ *   that is not Chromium-based
+ */
+export function secChUaFor(userAgent) {
+    const ua = String(userAgent ?? "");
+    const chrome = /Chrome\/(\d+)/.exec(ua);
+    if (!chrome) return null;
+    const major = chrome[1];
+    const edge = /Edg\/(\d+)/.exec(ua);
+    const brand = edge ? `"Microsoft Edge";v="${edge[1]}"` : `"Google Chrome";v="${major}"`;
+    // The shape real Chromium sends: the engine, the browser, and the GREASE filler entry.
+    const secChUa = `"Chromium";v="${major}", ${brand}, "Not?A_Brand";v="99"`;
+    let platform = '"Windows"';
+    if (/Android/i.test(ua)) platform = '"Android"';
+    else if (/Macintosh|Mac OS X/i.test(ua)) platform = '"macOS"';
+    else if (/Linux|X11/i.test(ua)) platform = '"Linux"';
+    return { secChUa, secChUaPlatform: platform, secChUaMobile: /Mobile/i.test(ua) ? "?1" : "?0" };
+}
+
+/**
+ * `sec-fetch-site` for a request from chat.zalo.me: same-site inside zalo.me, cross-site everywhere else.
+ *
+ * @param {string} url
+ * @returns {"same-site"|"cross-site"}
+ */
+export function fetchSiteOf(url) {
+    const host = new URL(url).hostname;
+    return host === "zalo.me" || host.endsWith(".zalo.me") ? "same-site" : "cross-site";
+}
+
+/**
+ * The headers to add to one request.
+ *
+ * @param {string} userAgent
+ * @param {string} url
+ * @returns {Record<string, string>}
+ */
+export function browserHeadersFor(userAgent, url) {
+    const hints = secChUaFor(userAgent);
+    const out = {};
+    if (hints) {
+        out.priority = "u=1, i";
+        out["sec-ch-ua"] = hints.secChUa;
+        out["sec-ch-ua-mobile"] = hints.secChUaMobile;
+        out["sec-ch-ua-platform"] = hints.secChUaPlatform;
+    }
+    out["sec-fetch-dest"] = "empty";
+    out["sec-fetch-mode"] = "cors";
+    out["sec-fetch-site"] = fetchSiteOf(url);
+    return out;
+}
+
+/**
+ * Wrap a fetch so every request carries the browser headers it lacks. A header the caller already set (in
+ * any letter case) is never replaced.
+ *
+ * @param {typeof fetch} inner - the fetch to call, the proxy-aware one when a proxy is configured
+ * @param {string} userAgent
+ * @returns {typeof fetch}
+ */
+export function withBrowserHeaders(inner, userAgent) {
+    return (input, init = {}) => {
+        const extra = browserHeadersFor(userAgent, String(input));
+        const given = init.headers;
+        let headers;
+        if (given instanceof Headers) {
+            headers = new Headers(given);
+            for (const [k, v] of Object.entries(extra)) if (!headers.has(k)) headers.set(k, v);
+        } else {
+            headers = { ...(given ?? {}) };
+            const have = new Set(Object.keys(headers).map((k) => k.toLowerCase()));
+            for (const [k, v] of Object.entries(extra)) if (!have.has(k)) headers[k] = v;
+        }
+        return inner(input, { ...init, headers });
+    };
+}

package/src/zalo/index.js

@@ -0,0 +1,72 @@
+/**
+ * The protocol layer's public entry: what a program that is not this CLI needs to log in to Zalo, call it, listen
+ * on its socket and restore history from the phone.
+ *
+ * Nothing under src/zalo imports the application (src/core, src/utils, src/commands, src/mcp, src/index.js); the
+ * caller hands in what is its own -- paths, a proxy, a logger, the answers of the local reads. See ./README.md.
+ * Internal until it is published as a package of its own: names here may still change.
+ */
+
+// ── making a session ───────────────────────────────────────────────────────
+export { AREAS, createApi } from "./api.js";
+export { buildSessionOptions, createProxyFetch, openQrSession, openSession, readImageMetadata } from "./client.js";
+export { createDrStore, loginWithSession, stopUpkeep } from "./login.js";
+export { qrLogin } from "./qr-login.js";
+export { TRUST_FILE, createTrustStore } from "./trust-store.js";
+export { generateDeviceFingerprint } from "./device-fingerprint.js";
+export { API_TYPE, DEFAULT_API_VERSION, getProfile, resolveApiVersion, resolveQrFlow } from "./profile.js";
+export * from "./enums.js";
+export * from "./errors.js";
+
+// ── the socket ─────────────────────────────────────────────────────────────
+export { Listener, createListener } from "./listener/listener.js";
+export { SocketSupervisor, superviseListener } from "./socket.js";
+export { startKeepAlive } from "./listener/keepalive.js";
+export { createSocketTap } from "./listener/socket-tap.js";
+export { drainReactionBacklog } from "./listener/reactions.js";
+
+// ── calls beside the session object ────────────────────────────────────────
+export { customCall, getWithParams, postWithParams } from "./session-call.js";
+export { READS, READ_NAMES, callRead, describeReads, registerLocalRead } from "./reads.js";
+export { WRITES, WRITE_NAMES, callWrite, describeWrites } from "./writes.js";
+export {
+    createDeliveredReceipts,
+    sendDeliveredReceipt,
+    sendReactionSeen,
+    sendSeenReceipt,
+    zaloPost,
+} from "./receipts.js";
+export { keySessionLogout, serverLogout } from "./logout.js";
+export { officialLogout } from "./official-logout.js";
+export * as pin from "./custom/pin.js";
+export * as forward from "./custom/forward.js";
+export * as groupHistory from "./custom/group-history.js";
+export * as groupInvite from "./custom/group-invite.js";
+export * as groupSettings from "./custom/group-settings.js";
+export * as groupVisibility from "./custom/group-visibility.js";
+export * as gid from "./custom/gid.js";
+export * as renewLink from "./custom/renewlink.js";
+export * as userInfo from "./custom/user-info.js";
+export * as zcloud from "./zcloud.js";
+export * as zcloudE2ee from "./zcloud-e2ee.js";
+
+// ── message text ───────────────────────────────────────────────────────────
+export { looksLikeMarkdown, markdownToZalo } from "./format/markdown.js";
+export { expandMentions, parseMentionSpecs } from "./format/mentions.js";
+export { MESSAGE_BYTE_LIMIT, sendParts, splitMessage } from "./format/split-message.js";
+export { urgencyLevel } from "./format/urgency.js";
+export { extractMessageText } from "./format/extract-message-text.js";
+
+// ── transfer sync (cmd 590/591) and the socket's queues ────────────────────
+export * as transfer from "./transfer-sync/transfer.js";
+export * as syncChannel from "./transfer-sync/channel.js";
+export * as syncDownload from "./transfer-sync/download.js";
+export * as syncAssets from "./transfer-sync/assets.js";
+export * as messageTypes from "./transfer-sync/message-types.js";
+export * as offlineQueue from "./queues/offline-queue.js";
+export * as controlQueue from "./queues/control-queue.js";
+export * as queueVerify from "./queues/queue-verify.js";
+
+// ── files several processes share ──────────────────────────────────────────
+export { withFileLock, writeFileAtomic } from "./kernel/atomic-file.js";
+export { plainCodec, secretFileCodec, setSecretFileCodec } from "./kernel/secret-file.js";