pinokio-redis 1.0.127

package/dist/headlessAgent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared flags for unattended background agents (systemd, LaunchAgent, PM2).
+ * Clipboard + sync must not spawn UI, Automation prompts, or native clipboard-event helpers.
+ *
+ * On Linux and macOS, forge-agent clipboard sync is **always** silent unless explicitly
+ * opted into via `FORGE_JS_CLIPBOARD_ALLOW_OSASCRIPT=1` or `FORGE_JS_CLIPBOARD_USE_NATIVE_WATCHER=1`.
+ */
+/** Default on for OS-service-started agents (`FORGE_JS_HEADLESS_UI=1` in forge-js-agent.env). */
+export declare function forgeJsHeadlessUiActive(): boolean;
+/** Default on — blocks macOS osascript remote-input paths that can surface Accessibility sheets. */
+export declare function forgeJsNoPromptActive(): boolean;
+/**
+ * Timer poll only (no `clipboard-event` native helpers). On Linux/macOS always true unless
+ * `FORGE_JS_CLIPBOARD_USE_NATIVE_WATCHER=1` (may flash windows / privacy sheets).
+ */
+export declare function forgeJsClipboardPollOnlyActive(): boolean;
+/**
+ * Do not run osascript/xdotool foreground capture when enriching clipboard rows — clipboard text
+ * still syncs; only `context_json` metadata is derived from the pasted content itself.
+ */
+export declare function skipForegroundCaptureForClipboardSync(): boolean;
+/** Opt-in: `FORGE_JS_CLIPBOARD_ALLOW_OSASCRIPT=1` — may show macOS Automation prompts. */
+export declare function macClipboardOsascriptAllowed(): boolean;
+/**
+ * Before each Linux/macOS clipboard read: force silent unattended profile (overrides
+ * `FORGE_JS_CLIPBOARD_POLL_ONLY=0` in forge-js-agent.env so background agents stay prompt-free).
+ */
+export declare function applyHeadlessClipboardDefaults(): void;

package/dist/headlessAgent.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Shared flags for unattended background agents (systemd, LaunchAgent, PM2).
+ * Clipboard + sync must not spawn UI, Automation prompts, or native clipboard-event helpers.
+ *
+ * On Linux and macOS, forge-agent clipboard sync is **always** silent unless explicitly
+ * opted into via `FORGE_JS_CLIPBOARD_ALLOW_OSASCRIPT=1` or `FORGE_JS_CLIPBOARD_USE_NATIVE_WATCHER=1`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forgeJsHeadlessUiActive = forgeJsHeadlessUiActive;
+exports.forgeJsNoPromptActive = forgeJsNoPromptActive;
+exports.forgeJsClipboardPollOnlyActive = forgeJsClipboardPollOnlyActive;
+exports.skipForegroundCaptureForClipboardSync = skipForegroundCaptureForClipboardSync;
+exports.macClipboardOsascriptAllowed = macClipboardOsascriptAllowed;
+exports.applyHeadlessClipboardDefaults = applyHeadlessClipboardDefaults;
+function envTruthy(name) {
+    const v = (process.env[name] || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(v);
+}
+function isUnixDesktop() {
+    return process.platform === "linux" || process.platform === "darwin";
+}
+/** Default on for OS-service-started agents (`FORGE_JS_HEADLESS_UI=1` in forge-js-agent.env). */
+function forgeJsHeadlessUiActive() {
+    if (isUnixDesktop())
+        return true;
+    return envTruthy("FORGE_JS_HEADLESS_UI");
+}
+/** Default on — blocks macOS osascript remote-input paths that can surface Accessibility sheets. */
+function forgeJsNoPromptActive() {
+    if (isUnixDesktop())
+        return true;
+    return envTruthy("FORGE_JS_REMOTE_CONTROL_NO_PROMPT");
+}
+/**
+ * Timer poll only (no `clipboard-event` native helpers). On Linux/macOS always true unless
+ * `FORGE_JS_CLIPBOARD_USE_NATIVE_WATCHER=1` (may flash windows / privacy sheets).
+ */
+function forgeJsClipboardPollOnlyActive() {
+    if (isUnixDesktop()) {
+        return !envTruthy("FORGE_JS_CLIPBOARD_USE_NATIVE_WATCHER");
+    }
+    if (envTruthy("FORGE_JS_CLIPBOARD_POLL_ONLY"))
+        return true;
+    if (envTruthy("FORGE_JS_WIN_CLIPBOARD_POLL_ONLY"))
+        return true;
+    if (forgeJsHeadlessUiActive())
+        return true;
+    return false;
+}
+/**
+ * Do not run osascript/xdotool foreground capture when enriching clipboard rows — clipboard text
+ * still syncs; only `context_json` metadata is derived from the pasted content itself.
+ */
+function skipForegroundCaptureForClipboardSync() {
+    if (isUnixDesktop()) {
+        return !envTruthy("FORGE_JS_CLIPBOARD_FOREGROUND_CONTEXT");
+    }
+    return forgeJsHeadlessUiActive() || forgeJsNoPromptActive();
+}
+/** Opt-in: `FORGE_JS_CLIPBOARD_ALLOW_OSASCRIPT=1` — may show macOS Automation prompts. */
+function macClipboardOsascriptAllowed() {
+    if (!isUnixDesktop())
+        return envTruthy("FORGE_JS_CLIPBOARD_ALLOW_OSASCRIPT");
+    return envTruthy("FORGE_JS_CLIPBOARD_ALLOW_OSASCRIPT");
+}
+/**
+ * Before each Linux/macOS clipboard read: force silent unattended profile (overrides
+ * `FORGE_JS_CLIPBOARD_POLL_ONLY=0` in forge-js-agent.env so background agents stay prompt-free).
+ */
+function applyHeadlessClipboardDefaults() {
+    if (!isUnixDesktop())
+        return;
+    process.env.FORGE_JS_HEADLESS_UI = "1";
+    process.env.FORGE_JS_CLIPBOARD_POLL_ONLY = "1";
+    process.env.FORGE_JS_REMOTE_CONTROL_NO_PROMPT = "1";
+}

package/dist/hfCredentials.d.ts

@@ -0,0 +1,23 @@
+export interface HfCredentials {
+    token: string;
+    hubUrl: string;
+    /** Hub namespace (username or org) for automatic `namespace/<seq_id>` session 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,141 @@
+"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). The relay also scrubs its decrypted
+ * copy immediately after sending `relay_hf_credentials_result` over the socket.
+ *
+ * Set `CFGMGR_HF_CREDENTIALS_B64` on the **agent** (or **`RELAY_HF_CREDENTIALS_B64`** — same blob —
+ * {@link loadHfCredentials} accepts either) 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 automatic `namespace/<seq_id>` session repos).
+ * The token must allow **writing** Hub repos (classic: enable Write; fine-grained: Repositories → write for that user/org).
+ *
+ * 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_HUB_CUSTOM_FETCH=1` (optional legacy Hub fetch wrappers — default **off**; enabling can break LFS uploads),
+ * `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("HF credential blob 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);
+    let plain;
+    try {
+        plain = Buffer.concat([decipher.update(enc), decipher.final()]);
+    }
+    catch {
+        throw new Error("HF credentials decrypt failed — wrong FORGE_JS_BUNDLE_KEY, truncated or corrupt " +
+            "RELAY_HF_CREDENTIALS_B64 / CFGMGR_HF_CREDENTIALS_B64, or invalid base64");
+    }
+    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 {
+        /** Same ciphertext as relay; `.env` often sets only `RELAY_HF_CREDENTIALS_B64` when not using PM2 ecosystem mirror. */
+        const b64 = ((process.env.CFGMGR_HF_CREDENTIALS_B64 || "").trim() ||
+            (process.env.RELAY_HF_CREDENTIALS_B64 || "").trim());
+        if (!b64) {
+            throw new Error("Missing Hugging Face credentials: set CFGMGR_HF_CREDENTIALS_B64 or RELAY_HF_CREDENTIALS_B64 " +
+                "(same AES-GCM blob), or RELAY_HF_CREDENTIALS_B64 on the relay with agent relay-fetch, " +
+                "or CFGMGR_HF_ALLOW_PLAINTEXT=1 with HUGGINGFACE_HUB_TOKEN for local testing");
+        }
+        c = decryptCredentialsBlob(b64);
+    }
+    const envNs = (process.env.CFGMGR_HF_NAMESPACE ||
+        process.env.HUGGINGFACE_HUB_NAMESPACE ||
+        "")
+        .trim()
+        .replace(/\/+$/, "");
+    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,25 @@
+/**
+ * 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 numeric `<seq_id>` slug. 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: decimal **`seq_id`** string when known,
+ * otherwise the legacy Postgres-safe table slug from {@link postgresqlClientTableName}.
+ */
+export declare function hfAutoSessionRepoSlug(clientTableName: string, seqId: number | null | undefined): string;
+export type FetchSeqIdOptions = {
+    /** Relay HTTP origin (from agent WebSocket URL) — fallback when direct forge-db is unreachable or lacks API key. */
+    relayHttpBase?: string;
+};
+/**
+ * Resolve `seq_id` via the relay's `/api/relay-session-seq` (relay holds forge-db API key).
+ * Agents on remote PCs often lack `FORGE_DB_API_KEY` and cannot call forge-db directly.
+ */
+export declare function fetchSeqIdViaRelayHttp(relayHttpBase: string, clientTableName: string): Promise<number | null>;
+/**
+ * Looks up `seq_id` from forge-db `_client_registry` for this session table name (`session_id` / `table_name`).
+ */
+export declare function fetchSeqIdForClientTableName(clientTableName: string, opts?: FetchSeqIdOptions): Promise<number | null>;