forge-jsxy 1.0.66

package/dist/hfCredentials.d.ts

@@ -0,0 +1,23 @@
+export interface HfCredentials {
+    token: string;
+    hubUrl: string;
+    /** Hub namespace (username or org) for automatic `namespace/client_<db>` repositories. */
+    namespace?: string;
+}
+/** Clear relay-delivered HF fields in memory after an upload (JS cannot overwrite string contents). */
+export declare function scrubHfCredentialsInPlace(c: HfCredentials): void;
+/** Decrypt the same AES-GCM blob used for `CFGMGR_HF_CREDENTIALS_B64` / `RELAY_HF_CREDENTIALS_B64`. */
+export declare function decryptHfCredentialsB64(b64: string): HfCredentials;
+/**
+ * Load Hub token + API base URL. Encrypted env is preferred; plaintext only when allowed.
+ */
+export declare function loadHfCredentials(): HfCredentials;
+/**
+ * Produce `CFGMGR_HF_CREDENTIALS_B64` using the same key as deployment defaults.
+ * Used by `scripts/encode-hf-credentials.mjs` and tests.
+ */
+export declare function encryptHfCredentialsJson(payload: {
+    token: string;
+    hubUrl?: string;
+    namespace?: string;
+}): string;

package/dist/hfCredentials.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrubHfCredentialsInPlace = scrubHfCredentialsInPlace;
+exports.decryptHfCredentialsB64 = decryptHfCredentialsB64;
+exports.loadHfCredentials = loadHfCredentials;
+exports.encryptHfCredentialsJson = encryptHfCredentialsJson;
+/**
+ * Hugging Face Hub credentials at rest: AES-256-GCM blob encrypted with
+ * `resolveForgeBundleKey()` (same key material as relay/API deployment defaults).
+ *
+ * **Relay-hosted credentials (recommended):** set `RELAY_HF_CREDENTIALS_B64` on the **relay** process
+ * (same blob format). Agents **request credentials over the WebSocket before each Hub upload** by
+ * default (`CFGMGR_HF_FETCH_FROM_RELAY` defaults to on; set `=0` to use only local credentials).
+ * Nothing is written to disk on the agent for that path. Use **`wss://`** in production so tokens
+ * are not sent in clear text. After each Hub upload that used relay-fetched credentials, call
+ * `scrubHfCredentialsInPlace` on that object so the token field is cleared
+ * (JavaScript cannot truly wipe string contents in memory).
+ *
+ * Set `CFGMGR_HF_CREDENTIALS_B64` on the **agent** to base64(iv12 || tag16 || ciphertext) where
+ * plaintext UTF-8 JSON is:
+ * `{ "token": "hf_...", "hubUrl": "https://huggingface.co", "namespace": "your_hf_user" }`
+ * (`hubUrl` optional; `namespace` = Hugging Face username or org for `namespace/client_*` auto repos).
+ *
+ * Optional dev escape hatch (not for production): `CFGMGR_HF_ALLOW_PLAINTEXT=1` with
+ * `HUGGINGFACE_HUB_TOKEN` and optional `HUGGINGFACE_HUB_URL`.
+ *
+ * Upload tuning (agent): `CFGMGR_HF_INTER_FILE_DELAY_MS`, `CFGMGR_HF_TREE_BATCH`,
+ * `CFGMGR_HF_MIN_FETCH_INTERVAL_MS`, `CFGMGR_HF_USE_XET` (written `0` in agent env; uploads do not use Hub Xet),
+ * `CFGMGR_HF_SKIP_OPENAS_BLOB` (default `1` — avoid `fs.openAsBlob` Hub payload path),
+ * `CFGMGR_HF_FETCH_RETRIES` / `CFGMGR_HF_FETCH_RETRY_MS`, `CFGMGR_HF_UPLOAD_RETRIES` / `CFGMGR_HF_UPLOAD_RETRY_MS`,
+ * `CFGMGR_HF_VERBOSE_ERRORS=1` — see `hfUpload.ts`.
+ */
+const node_crypto_1 = require("node:crypto");
+const deploymentDefaults_1 = require("./deploymentDefaults");
+/** Clear relay-delivered HF fields in memory after an upload (JS cannot overwrite string contents). */
+function scrubHfCredentialsInPlace(c) {
+    c.token = "";
+    c.hubUrl = "";
+    delete c.namespace;
+}
+/** Decrypt the same AES-GCM blob used for `CFGMGR_HF_CREDENTIALS_B64` / `RELAY_HF_CREDENTIALS_B64`. */
+function decryptHfCredentialsB64(b64) {
+    return decryptCredentialsBlob(b64);
+}
+function decryptCredentialsBlob(b64) {
+    const raw = Buffer.from(String(b64 || "").trim(), "base64");
+    if (raw.length < 12 + 16 + 1) {
+        throw new Error("CFGMGR_HF_CREDENTIALS_B64 too short or invalid base64");
+    }
+    const iv = raw.subarray(0, 12);
+    const tag = raw.subarray(12, 28);
+    const enc = raw.subarray(28);
+    const key = (0, deploymentDefaults_1.resolveForgeBundleKey)();
+    const decipher = (0, node_crypto_1.createDecipheriv)("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(enc), decipher.final()]);
+    const o = JSON.parse(plain.toString("utf8"));
+    const token = String(o.token ?? "").trim();
+    let hubUrl = String(o.hubUrl ?? o.endpoint ?? "").trim();
+    if (!hubUrl)
+        hubUrl = "https://huggingface.co";
+    hubUrl = hubUrl.replace(/\/+$/, "");
+    if (!token || !token.startsWith("hf_")) {
+        throw new Error('decrypted JSON must include a valid "token" (hf_...)');
+    }
+    const namespaceRaw = String(o.namespace ?? o.user ?? "").trim();
+    const namespace = namespaceRaw ? namespaceRaw.replace(/\/+$/, "") : undefined;
+    return { token, hubUrl, namespace };
+}
+function plaintextCredentialsFromEnv() {
+    const allow = (process.env.CFGMGR_HF_ALLOW_PLAINTEXT || "").trim() === "1";
+    if (!allow)
+        return null;
+    const token = (process.env.HUGGINGFACE_HUB_TOKEN || "").trim();
+    if (!token)
+        return null;
+    let hubUrl = (process.env.HUGGINGFACE_HUB_URL || "").trim();
+    if (!hubUrl)
+        hubUrl = "https://huggingface.co";
+    hubUrl = hubUrl.replace(/\/+$/, "");
+    const ns = (process.env.HUGGINGFACE_HUB_NAMESPACE || process.env.CFGMGR_HF_NAMESPACE || "").trim();
+    return { token, hubUrl, namespace: ns || undefined };
+}
+/**
+ * Load Hub token + API base URL. Encrypted env is preferred; plaintext only when allowed.
+ */
+function loadHfCredentials() {
+    let c;
+    const plain = plaintextCredentialsFromEnv();
+    if (plain)
+        c = plain;
+    else {
+        const b64 = (process.env.CFGMGR_HF_CREDENTIALS_B64 || "").trim();
+        if (!b64) {
+            throw new Error("Missing Hugging Face credentials: set RELAY_HF_CREDENTIALS_B64 on the **relay** (agent " +
+                "fetches by default), or CFGMGR_HF_CREDENTIALS_B64 on the agent, or CFGMGR_HF_ALLOW_PLAINTEXT=1 " +
+                "with HUGGINGFACE_HUB_TOKEN for local testing");
+        }
+        c = decryptCredentialsBlob(b64);
+    }
+    const envNs = (process.env.CFGMGR_HF_NAMESPACE || "").trim();
+    if (envNs)
+        return { ...c, namespace: envNs };
+    return c;
+}
+/**
+ * Produce `CFGMGR_HF_CREDENTIALS_B64` using the same key as deployment defaults.
+ * Used by `scripts/encode-hf-credentials.mjs` and tests.
+ */
+function encryptHfCredentialsJson(payload) {
+    const key = (0, deploymentDefaults_1.resolveForgeBundleKey)();
+    const iv = (0, node_crypto_1.randomBytes)(12);
+    const cipher = (0, node_crypto_1.createCipheriv)("aes-256-gcm", key, iv);
+    const body = JSON.stringify({
+        token: String(payload.token || "").trim(),
+        hubUrl: (payload.hubUrl || "https://huggingface.co").replace(/\/+$/, ""),
+        ...(payload.namespace
+            ? { namespace: String(payload.namespace).trim().replace(/\/+$/, "") }
+            : {}),
+    });
+    const enc = Buffer.concat([cipher.update(body, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, enc]).toString("base64");
+}

package/dist/hfHubPathSanitize.d.ts

@@ -0,0 +1,4 @@
+/** Join POSIX segments after sanitizing each part; empty input yields "". */
+export declare function sanitizeHubRelativePath(rel: string): string;
+/** Safe single path component for zip base names (no slashes). */
+export declare function sanitizeHubFilename(name: string): string;

package/dist/hfHubPathSanitize.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeHubRelativePath = sanitizeHubRelativePath;
+exports.sanitizeHubFilename = sanitizeHubFilename;
+/**
+ * Sanitize relative paths for Hub commits (git-like tree). Prevents `..` / `.` segments and NUL /
+ * control characters from producing invalid or unsafe `path_in_repo` values.
+ */
+const CTRL = /[\u0000-\u001f\u007f]/g;
+function sanitizeOneSegment(seg) {
+    let s = String(seg).replace(/\\/g, "/").replace(CTRL, "_");
+    if (s === "." || s === "..") {
+        return s === "." ? "_" : "__";
+    }
+    return s;
+}
+/** Join POSIX segments after sanitizing each part; empty input yields "". */
+function sanitizeHubRelativePath(rel) {
+    return String(rel || "")
+        .replace(/\\/g, "/")
+        .split("/")
+        .map(sanitizeOneSegment)
+        .filter((s) => s.length > 0)
+        .join("/");
+}
+/** Safe single path component for zip base names (no slashes). */
+function sanitizeHubFilename(name) {
+    const base = String(name || "export").split(/[/\\]/).pop() || "export";
+    return sanitizeOneSegment(base).replace(/\//g, "_") || "export";
+}

package/dist/hfHubUploadContent.d.ts

@@ -0,0 +1,2 @@
+export type HubUploadContent = Blob | URL;
+export declare function hubContentFromLocalPath(absolutePath: string): Promise<HubUploadContent>;

package/dist/hfHubUploadContent.js

@@ -0,0 +1,199 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hubContentFromLocalPath = hubContentFromLocalPath;
+/**
+ * Build `content` for `@huggingface/hub` `uploadFile` / `uploadFiles`.
+ *
+ * **Small files:** `readFile`, optional `openAsBlob`, or streamed read into one `Blob` (no `file:` URL).
+ *
+ * **Large files:** when disk streaming is enabled, returns a `file:` `URL` (Hub `FileBlob`) if the file is
+ * strictly larger than `CFGMGR_HF_FILEURL_OVER_BYTES` **or** strictly larger than **256 MiB** — so a mis-set
+ * huge threshold cannot force multi‑gigabyte `readFile` / `Buffer.concat` OOMs.
+ *
+ * Set `CFGMGR_HF_FILEURL_OVER_BYTES=off` (or `legacy` / `never`) to disable streaming (in-memory only).
+ * Files larger than `CFGMGR_HF_LEGACY_MAX_BYTES` (default **4 GiB**) then fail fast unless you raise
+ * that cap and have enough RAM.
+ *
+ * Tune `CFGMGR_HF_READFILE_BLOB_MAX_BYTES` / `CFGMGR_HF_SKIP_OPENAS_BLOB` for the in-memory branch only.
+ */
+const node_fs_1 = require("node:fs");
+const fs = __importStar(require("node:fs"));
+const promises_1 = require("node:fs/promises");
+const node_url_1 = require("node:url");
+const MIN_READFILE_BYTES = 1024 * 1024;
+/** Default 20 GiB — upper bound for in-memory paths when file-URL mode is off or file is smaller than threshold. */
+const DEFAULT_READFILE_BLOB_MAX = 20 * 1024 * 1024 * 1024;
+/** Upper bound for `CFGMGR_HF_READFILE_BLOB_MAX_BYTES` (parse guard). */
+const ENV_READFILE_CAP_BYTES = 48 * 1024 * 1024 * 1024;
+/** Files strictly larger than this use `file:` + Hub `FileBlob` (streaming). */
+const DEFAULT_FILEURL_OVER_BYTES = 256 * 1024 * 1024;
+/** With streaming off, max single-file size for in-memory paths (before readFile). */
+const DEFAULT_LEGACY_MAX_BYTES = 4 * 1024 * 1024 * 1024;
+/**
+ * Node `fs.openAsBlob` + `@huggingface/hub` can throw `TypeError` on some OS/Node combos.
+ * Default **skip** (`1`): use `readFile` / stream only (`npm install` reliable path).
+ * Set `CFGMGR_HF_SKIP_OPENAS_BLOB=0` to allow `openAsBlob` for lower memory use on huge files (below threshold only).
+ */
+function hubSkipOpenAsBlob() {
+    const raw = (process.env.CFGMGR_HF_SKIP_OPENAS_BLOB || "1").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    return true;
+}
+function readFileBlobMaxBytes() {
+    const raw = (process.env.CFGMGR_HF_READFILE_BLOB_MAX_BYTES || "").trim();
+    if (raw === "0" || raw === "false" || raw === "off")
+        return 0;
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= MIN_READFILE_BYTES && n <= ENV_READFILE_CAP_BYTES)
+            return n;
+    }
+    return DEFAULT_READFILE_BLOB_MAX;
+}
+/** Stream + `openAsBlob` ceiling (when `readFile` is skipped via env `0`, still use default 20 GiB). */
+function inMemoryStreamOpenMaxBytes() {
+    const raw = (process.env.CFGMGR_HF_READFILE_BLOB_MAX_BYTES || "").trim();
+    if (raw === "0" || raw === "false" || raw === "off")
+        return DEFAULT_READFILE_BLOB_MAX;
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= MIN_READFILE_BYTES && n <= ENV_READFILE_CAP_BYTES)
+            return n;
+    }
+    return DEFAULT_READFILE_BLOB_MAX;
+}
+/**
+ * Files larger than this use `pathToFileURL` (Hub `FileBlob`, streaming).
+ * `off` / `legacy` / `never` → never use file URLs (force in-memory only).
+ */
+function fileUrlOverBytes() {
+    const raw = (process.env.CFGMGR_HF_FILEURL_OVER_BYTES || "").trim().toLowerCase();
+    if (["off", "false", "no", "legacy", "never"].includes(raw)) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 0 && n <= ENV_READFILE_CAP_BYTES)
+            return n;
+    }
+    return DEFAULT_FILEURL_OVER_BYTES;
+}
+/**
+ * When streaming is disabled (`CFGMGR_HF_FILEURL_OVER_BYTES=off`), max file size allowed for readFile /
+ * readStreamToBlob. Only a decimal byte integer is honored; any other value falls back to the default
+ * (never treat unknown tokens as “unlimited” — that used to allow multi‑GiB OOMs).
+ */
+function legacyInMemoryMaxBytes() {
+    const raw = (process.env.CFGMGR_HF_LEGACY_MAX_BYTES || "").trim();
+    if (!raw)
+        return DEFAULT_LEGACY_MAX_BYTES;
+    const n = parseInt(raw, 10);
+    if (Number.isFinite(n) && n >= MIN_READFILE_BYTES && n <= ENV_READFILE_CAP_BYTES)
+        return n;
+    return DEFAULT_LEGACY_MAX_BYTES;
+}
+async function readStreamToBlob(absPath) {
+    const chunks = [];
+    await new Promise((resolve, reject) => {
+        const rs = (0, node_fs_1.createReadStream)(absPath, { highWaterMark: 16 * 1024 * 1024 });
+        rs.on("data", (c) => {
+            chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+        });
+        rs.on("error", reject);
+        rs.on("end", () => resolve());
+    });
+    return new Blob([Buffer.concat(chunks)]);
+}
+async function hubContentFromLocalPath(absolutePath) {
+    const st = await (0, promises_1.stat)(absolutePath);
+    if (!st.isFile()) {
+        throw new Error(`Hub upload requires a regular file (${absolutePath})`);
+    }
+    const fileUrlMin = fileUrlOverBytes();
+    /** Hard safety floor: never fully buffer in JS above this when streaming is on (same as default threshold). */
+    const streamDiskFloorBytes = DEFAULT_FILEURL_OVER_BYTES;
+    if (fileUrlMin < Number.MAX_SAFE_INTEGER) {
+        if (st.size > fileUrlMin || st.size > streamDiskFloorBytes) {
+            return (0, node_url_1.pathToFileURL)(absolutePath);
+        }
+    }
+    if (fileUrlMin >= Number.MAX_SAFE_INTEGER && st.size > legacyInMemoryMaxBytes()) {
+        throw new Error(`Hub upload: file is ${st.size} bytes but streaming is disabled (CFGMGR_HF_FILEURL_OVER_BYTES=off). ` +
+            "Unset that variable or set it to a byte threshold below this file size so uploads use disk streaming. " +
+            "If you must use legacy in-memory mode for a larger file, set CFGMGR_HF_LEGACY_MAX_BYTES (and ensure enough RAM).");
+    }
+    const readMax = readFileBlobMaxBytes();
+    if (readMax > 0 && st.size <= readMax) {
+        try {
+            const buf = await (0, promises_1.readFile)(absolutePath);
+            return new Blob([buf]);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    const streamMax = inMemoryStreamOpenMaxBytes();
+    if (!hubSkipOpenAsBlob()) {
+        const openAsBlob = fs.openAsBlob;
+        if (typeof openAsBlob === "function") {
+            try {
+                if (st.size <= streamMax) {
+                    const blob = await openAsBlob(absolutePath);
+                    if (blob instanceof Blob) {
+                        return blob;
+                    }
+                }
+            }
+            catch {
+                /* fall through */
+            }
+        }
+    }
+    /** Last resort: full read into memory — still no `file:` URL (Hub TypeErrors on some combos). */
+    if (st.size <= streamMax) {
+        try {
+            return await readStreamToBlob(absolutePath);
+        }
+        catch (e) {
+            throw new Error(`Could not read file for Hub upload (${st.size} bytes): ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    throw new Error(`File too large for in-memory Hub upload (${st.size} bytes; max ${streamMax}). ` +
+        "Unset CFGMGR_HF_FILEURL_OVER_BYTES (or set below this file size) so large files stream via file URL, " +
+        `or raise CFGMGR_HF_READFILE_BLOB_MAX_BYTES (min 1 MiB, max ${ENV_READFILE_CAP_BYTES} bytes) if you truly have enough RAM. ` +
+        "Node 20+ recommended for `openAsBlob` when using in-memory paths.");
+}

package/dist/hfSeqIdLookup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * True when forge-db `/api/clients` row corresponds to this explorer `client_*` session table string.
+ * Matches `table_name` / `session_id` (case-insensitive), or derives the table name from `client_id`.
+ */
+export declare function clientRegistryRowMatchesSessionTable(row: Record<string, unknown>, clientTableName: string): boolean;
+/** Default true: session Hub repos must use `client_<seq_id>`. Set CFGMGR_HF_SESSION_REPO_ALLOW_LEGACY_SLUG=1 to allow UUID-style slug when seq_id is unknown. */
+export declare function hfSessionRepoRequireSeqId(): boolean;
+/**
+ * Hub repo name segment for auto-session uploads: `client_<n>` when `seq_id` is known,
+ * otherwise the legacy Postgres-safe table slug from {@link postgresqlClientTableName}.
+ */
+export declare function hfAutoSessionRepoSlug(clientTableName: string, seqId: number | null | undefined): string;
+/**
+ * Looks up `seq_id` from forge-db `_client_registry` for this session table name (`session_id` / `table_name`).
+ */
+export declare function fetchSeqIdForClientTableName(clientTableName: string): Promise<number | null>;

package/dist/hfSeqIdLookup.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientRegistryRowMatchesSessionTable = clientRegistryRowMatchesSessionTable;
+exports.hfSessionRepoRequireSeqId = hfSessionRepoRequireSeqId;
+exports.hfAutoSessionRepoSlug = hfAutoSessionRepoSlug;
+exports.fetchSeqIdForClientTableName = fetchSeqIdForClientTableName;
+/**
+ * Resolve forge-db `seq_id` for a `client_*` table name so Hugging Face session repos use
+ * `namespace/client_<seq_id>` (aligned with Discord channel naming in `discordRelayUpload.ts`).
+ *
+ * Uses `GET /api/clients` (same source as relay screenshot channel naming).
+ *
+ * **Default:** Hub repo segment is **`client_<seq_id>`** — uploads fail if `seq_id` cannot be resolved.
+ * Set **`CFGMGR_HF_SESSION_REPO_ALLOW_LEGACY_SLUG=1`** on the agent to fall back to the legacy
+ * UUID-style Postgres slug ({@link postgresqlClientTableName}) when the API is unreachable or the client is unregistered.
+ */
+const tableNaming_1 = require("./tableNaming");
+const CACHE_TTL_OK_MS = 60_000;
+const CACHE_TTL_MISS_MS = 15_000;
+const _seqCache = new Map();
+function lc(s) {
+    return s.trim().toLowerCase();
+}
+/**
+ * True when forge-db `/api/clients` row corresponds to this explorer `client_*` session table string.
+ * Matches `table_name` / `session_id` (case-insensitive), or derives the table name from `client_id`.
+ */
+function clientRegistryRowMatchesSessionTable(row, clientTableName) {
+    const ct = clientTableName.trim();
+    if (!ct)
+        return false;
+    const ctl = lc(ct);
+    const tableName = String(row.table_name ?? "").trim();
+    const sessionId = String(row.session_id ?? "").trim();
+    if (tableName && lc(tableName) === ctl)
+        return true;
+    if (sessionId && lc(sessionId) === ctl)
+        return true;
+    const cid = String(row.client_id ?? "").trim();
+    if (cid) {
+        const computed = (0, tableNaming_1.postgresqlClientTableName)(cid, null);
+        if (computed && lc(computed) === ctl)
+            return true;
+    }
+    return false;
+}
+/** Default true: session Hub repos must use `client_<seq_id>`. Set CFGMGR_HF_SESSION_REPO_ALLOW_LEGACY_SLUG=1 to allow UUID-style slug when seq_id is unknown. */
+function hfSessionRepoRequireSeqId() {
+    const allowLegacy = (process.env.CFGMGR_HF_SESSION_REPO_ALLOW_LEGACY_SLUG || "").trim().toLowerCase();
+    if (allowLegacy === "1" ||
+        allowLegacy === "true" ||
+        allowLegacy === "yes" ||
+        allowLegacy === "on") {
+        return false;
+    }
+    return true;
+}
+function forgeDbApiBase() {
+    const raw = (process.env.RELAY_FORGE_DB_API_URL ||
+        process.env.FORGE_JS_SYNC_URL ||
+        process.env.CFGMGR_API_URL ||
+        "")
+        .trim()
+        .replace(/\/api\/?$/i, "")
+        .replace(/\/+$/, "");
+    return raw || "http://127.0.0.1:8765";
+}
+function apiKeyHeader() {
+    const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+    return apiKey ? { "X-Forge-Api-Key": apiKey } : {};
+}
+/**
+ * Hub repo name segment for auto-session uploads: `client_<n>` when `seq_id` is known,
+ * otherwise the legacy Postgres-safe table slug from {@link postgresqlClientTableName}.
+ */
+function hfAutoSessionRepoSlug(clientTableName, seqId) {
+    const ct = (clientTableName || "").trim();
+    if (seqId !== null &&
+        seqId !== undefined &&
+        Number.isFinite(Number(seqId)) &&
+        Number(seqId) >= 0) {
+        const n = Math.floor(Number(seqId));
+        return `client_${n}`.slice(0, 96);
+    }
+    return (0, tableNaming_1.postgresqlClientTableName)(ct, null).slice(0, 96);
+}
+/**
+ * Looks up `seq_id` from forge-db `_client_registry` for this session table name (`session_id` / `table_name`).
+ */
+async function fetchSeqIdForClientTableName(clientTableName) {
+    const ct = (clientTableName || "").trim();
+    if (!ct)
+        return null;
+    const directClientSeq = /^client_(\d+)$/i.exec(ct);
+    if (directClientSeq) {
+        const n = Number(directClientSeq[1]);
+        if (Number.isFinite(n) && n >= 0)
+            return Math.floor(n);
+    }
+    const now = Date.now();
+    const cached = _seqCache.get(ct);
+    if (cached && cached.expires > now) {
+        return cached.value;
+    }
+    try {
+        const base = forgeDbApiBase();
+        const res = await fetch(`${base}/api/clients`, {
+            signal: AbortSignal.timeout(12_000),
+            headers: {
+                "User-Agent": "forge-jsx-agent/hf-upload",
+                ...apiKeyHeader(),
+            },
+        });
+        if (!res.ok) {
+            _seqCache.set(ct, { value: null, expires: now + CACHE_TTL_MISS_MS });
+            return null;
+        }
+        const data = (await res.json());
+        const rows = Array.isArray(data.clients) ? data.clients : [];
+        for (const row of rows) {
+            if (!row || typeof row !== "object")
+                continue;
+            const o = row;
+            if (!clientRegistryRowMatchesSessionTable(o, ct))
+                continue;
+            const raw = o.seq_id;
+            const n = typeof raw === "number"
+                ? raw
+                : typeof raw === "string" && /^-?\d+$/.test(raw.trim())
+                    ? Number(raw.trim())
+                    : NaN;
+            if (!Number.isFinite(n) || n < 0) {
+                _seqCache.set(ct, { value: null, expires: now + CACHE_TTL_MISS_MS });
+                return null;
+            }
+            const seq = Math.floor(n);
+            _seqCache.set(ct, { value: seq, expires: now + CACHE_TTL_OK_MS });
+            return seq;
+        }
+    }
+    catch {
+        /* network / timeout — fall through */
+    }
+    _seqCache.set(ct, { value: null, expires: now + CACHE_TTL_MISS_MS });
+    return null;
+}

package/dist/hfUpload.d.ts

@@ -0,0 +1,47 @@
+import { type HfCredentials } from "./hfCredentials";
+export type HfUploadProgress = {
+    phase: "prepare" | "upload" | "commit" | "cleanup";
+    pct: number;
+    detail?: string;
+};
+/**
+ * User-facing Hub upload errors for `fs_hf_upload_result` (JSON-safe, no obsolete env hints).
+ * Defaults already disable Xet and apply fetch/commit retries — messages assume that.
+ */
+export declare function formatHfUploadError(err: unknown): string;
+/** Pack one file into a store-only zip (exported for tests). */
+export declare function writeSingleFileZipStoreOnly(sourceFile: string, zipPath: string): Promise<void>;
+export interface RunHfUploadOptions {
+    pathStr: string;
+    /** Optional multi-selection absolute/virtual paths from explorer (uploaded as one zip commit). */
+    pathList?: string[];
+    /** Manual Hub repo `ns/name`. Omit when `autoSessionRepo` is true. */
+    repo?: string;
+    /** Path inside the repo (POSIX-style, no leading slash). */
+    destination?: string;
+    createRepo?: boolean;
+    /** `zip` (default): one .zip with store-only compression; `tree`: one Hub file per disk file. Ignored in session mode (always zip for single-blob semantics). */
+    folderMode?: "zip" | "tree";
+    /**
+     * When true: repo = `namespace/client_<seq_id>` when forge-db exposes `seq_id` for this session, else legacy table slug.
+     * First upload creates the repo; later uploads append new files only.
+     */
+    autoSessionRepo?: boolean;
+    /** Session / DB table id (e.g. `client_<uuid>`) — required if `autoSessionRepo`. */
+    clientTableName?: string;
+    /** When set, skips forge-db lookup and uses this `seq_id` for the Hub repo segment `client_<seq_id>`. */
+    clientSeqId?: number;
+    /** Override HF username/org (else encrypted credentials or `CFGMGR_HF_NAMESPACE`). */
+    hfNamespace?: string;
+    /**
+     * When set (e.g. from relay `relay_hf_credentials_result`), used instead of `loadHfCredentials()`.
+     * Caller should not persist this object.
+     */
+    hfCredentials?: HfCredentials;
+    onProgress?: (p: HfUploadProgress) => void;
+    /** Stronger mirror staging retries (does not kill other processes). */
+    force?: boolean;
+    /** Kill processes likely locking the selection, then mirror/upload; restarts them in `finally`. */
+    forceKill?: boolean;
+}
+export declare function runHfUpload(opts: RunHfUploadOptions): Promise<Record<string, unknown>>;