@indigoai-us/hq-cli 5.345.199 → 5.345.200

package/dist/lib/bot/fleet-download.d.ts

@@ -0,0 +1,27 @@
+/** A download that receives no bytes for this long is treated as stalled and retried. */
+export declare const FLEET_DOWNLOAD_STALL_MS = 90000;
+/** How many times a stalled or broken download is resumed before giving up. */
+export declare const FLEET_DOWNLOAD_MAX_RESUMES = 5;
+export interface FleetDownloadProgress {
+    name: string;
+    received: number;
+    total: number | null;
+}
+export interface FleetDownloadOptions {
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    stallMs?: number;
+    maxResumes?: number;
+    onProgress?: (progress: FleetDownloadProgress) => void;
+}
+/**
+ * Download `url` into `destination`, writing through `<destination>.part` and
+ * resuming from the bytes already there. Every attempt that receives nothing
+ * for `stallMs` is retried from where it stopped, up to `maxResumes` times.
+ * The file is renamed into place only when the body ended cleanly and, when
+ * the server told us its size, the sizes match.
+ */
+export declare function downloadFleetFile(url: string, destination: string, options?: FleetDownloadOptions): Promise<string>;
+/** sha256 of a file on disk, streamed. */
+export declare function fileSha256(file: string): string;
+//# sourceMappingURL=fleet-download.d.ts.map

package/dist/lib/bot/fleet-download.js

@@ -0,0 +1,162 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** A download that receives no bytes for this long is treated as stalled and retried. */
+export const FLEET_DOWNLOAD_STALL_MS = 90_000;
+/** How many times a stalled or broken download is resumed before giving up. */
+export const FLEET_DOWNLOAD_MAX_RESUMES = 5;
+function expectedError(message) {
+    return Object.assign(new Error(message), { expected: true });
+}
+function partFileSize(file) {
+    try {
+        return fs.statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function contentLength(response) {
+    const raw = response.headers.get("content-length");
+    if (!raw)
+        return null;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value >= 0 ? value : null;
+}
+function contentRangeTotal(response) {
+    const raw = response.headers.get("content-range");
+    const match = raw ? /\/(\d+)\s*$/.exec(raw) : null;
+    if (!match)
+        return null;
+    const value = Number.parseInt(match[1], 10);
+    return Number.isFinite(value) ? value : null;
+}
+async function pumpBody(response, fd, offset, name, total, stallMs, onProgress) {
+    if (!response.body) {
+        const bytes = Buffer.from(await response.arrayBuffer());
+        fs.writeSync(fd, bytes, 0, bytes.length, offset);
+        const received = offset + bytes.length;
+        onProgress?.({ name, received, total });
+        return received;
+    }
+    const reader = response.body.getReader();
+    let received = offset;
+    let lastReport = 0;
+    for (;;) {
+        let timer;
+        const stalled = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(expectedError(`stalled: no data for ${Math.round(stallMs / 1000)}s`)), stallMs);
+        });
+        let chunk;
+        try {
+            chunk = await Promise.race([reader.read(), stalled]);
+        }
+        catch (error) {
+            void reader.cancel().catch(() => undefined);
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (chunk.done)
+            break;
+        fs.writeSync(fd, chunk.value, 0, chunk.value.length, received);
+        received += chunk.value.length;
+        const now = Date.now();
+        if (now - lastReport >= 250 || (total !== null && received >= total)) {
+            lastReport = now;
+            onProgress?.({ name, received, total });
+        }
+    }
+    onProgress?.({ name, received, total });
+    return received;
+}
+/**
+ * Download `url` into `destination`, writing through `<destination>.part` and
+ * resuming from the bytes already there. Every attempt that receives nothing
+ * for `stallMs` is retried from where it stopped, up to `maxResumes` times.
+ * The file is renamed into place only when the body ended cleanly and, when
+ * the server told us its size, the sizes match.
+ */
+export async function downloadFleetFile(url, destination, options = {}) {
+    const fetcher = options.fetch ?? fetch;
+    const stallMs = options.stallMs ?? FLEET_DOWNLOAD_STALL_MS;
+    const maxResumes = options.maxResumes ?? FLEET_DOWNLOAD_MAX_RESUMES;
+    const name = path.basename(destination);
+    const part = `${destination}.part`;
+    fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+    let lastFailure = null;
+    for (let attempt = 0; attempt <= maxResumes; attempt += 1) {
+        const have = partFileSize(part);
+        const headers = { ...options.headers };
+        if (have > 0)
+            headers.Range = `bytes=${have}-`;
+        let response;
+        try {
+            response = await (Object.keys(headers).length > 0 ? fetcher(url, { headers }) : fetcher(url));
+        }
+        catch (error) {
+            lastFailure = error;
+            continue;
+        }
+        let offset = have;
+        let total;
+        if (response.status === 206 && have > 0) {
+            total = contentRangeTotal(response) ?? (contentLength(response) !== null ? have + contentLength(response) : null);
+        }
+        else if (response.status === 416 && have > 0) {
+            void response.body?.cancel().catch(() => undefined);
+            fs.renameSync(part, destination);
+            return destination;
+        }
+        else if (response.ok) {
+            offset = 0;
+            total = contentLength(response);
+        }
+        else {
+            void response.body?.cancel().catch(() => undefined);
+            throw expectedError(`Could not download ${name}: HQ storage returned HTTP ${response.status}.`);
+        }
+        const fd = fs.openSync(part, offset === 0 ? "w" : "r+", 0o600);
+        let received;
+        try {
+            received = await pumpBody(response, fd, offset, name, total, stallMs, options.onProgress);
+        }
+        catch (error) {
+            fs.closeSync(fd);
+            lastFailure = error;
+            continue;
+        }
+        fs.closeSync(fd);
+        if (total !== null && received !== total) {
+            if (received > total)
+                fs.rmSync(part, { force: true });
+            lastFailure = expectedError(`ended early at ${received} of ${total} bytes`);
+            continue;
+        }
+        fs.renameSync(part, destination);
+        return destination;
+    }
+    const cause = lastFailure instanceof Error ? lastFailure.message : String(lastFailure ?? "unknown error");
+    throw expectedError(`Could not download ${name} after ${maxResumes + 1} attempts (${cause}). Check your internet connection and retry; the download continues where it stopped.`);
+}
+/** sha256 of a file on disk, streamed. */
+export function fileSha256(file) {
+    const hash = crypto.createHash("sha256");
+    const fd = fs.openSync(file, "r");
+    try {
+        const chunk = Buffer.allocUnsafe(1 << 20);
+        for (;;) {
+            const read = fs.readSync(fd, chunk, 0, chunk.length, null);
+            if (read === 0)
+                break;
+            hash.update(chunk.subarray(0, read));
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return hash.digest("hex");
+}
+//# sourceMappingURL=fleet-download.js.map

package/dist/lib/bot/fleet-local.d.ts

@@ -65,6 +65,9 @@ export interface FleetLocalInstallDeps {
     now?: () => Date;
     release?: FleetLocalReleasePin;
     publicKey?: string | readonly string[];
+    onProgress?: FleetInstallProgressListener;
+    /** How long a download may go without bytes before it is resumed (tests). */
+    downloadStallMs?: number;
 }
 export interface FleetLocalProfileInput {
     agentUid: string;
@@ -113,6 +116,7 @@ export interface FleetLocalBootstrapDeps {
     spawn?: FleetLocalSpawn;
     start?: boolean;
     python?: FleetPython;
+    onProgress?: FleetInstallProgressListener;
 }
 interface SharedFleetRuntime {
     id: string;
@@ -257,9 +261,35 @@ export declare function installTargetFleetLocalDistribution(deps?: Omit<FleetLoc
     target?: FleetLocalTargetRelease;
     now?: () => number;
 }): Promise<FleetLocalInstallation>;
+/** What an install is doing right now, for a progress bar or a log line. */
+export type FleetInstallProgress = {
+    phase: "download";
+    file: string;
+    received: number;
+    total: number | null;
+} | {
+    phase: "verify";
+} | {
+    phase: "python";
+} | {
+    phase: "extract";
+} | {
+    phase: "environment";
+} | {
+    phase: "packages";
+} | {
+    phase: "ready";
+    step: "download" | "runtime";
+    cached: boolean;
+};
+export type FleetInstallProgressListener = (progress: FleetInstallProgress) => void;
 export declare const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30000;
-export declare const FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS: number;
-export declare const FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS: number;
+/** One machine-wide lock: concurrent creates and adopts share one download instead of repeating it. */
+export declare const FLEET_LOCAL_DISTRIBUTION_LOCK_NAME = "hq-fleet-local-distribution";
+export declare const FLEET_LOCAL_DISTRIBUTION_LOCK_WAIT_MS: number;
+export declare const FLEET_LOCAL_DISTRIBUTION_LOCK_STALE_MS: number;
+/** Whether the pinned release is installed on this machine (no download needed). */
+export declare function fleetLocalDistributionInstalled(release?: FleetLocalReleasePin, root?: string): boolean;
 export declare function installPinnedFleetLocalDistribution(deps?: FleetLocalInstallDeps): Promise<FleetLocalInstallation>;
 /** The process id the bot's gateway recorded, when its file reads; the caller checks whether it is alive. */
 export declare function fleetLocalGatewayPid(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome">): number | null;
@@ -339,6 +369,25 @@ export declare function windowsExtractionPathProblem(destination: string, longes
 export declare function importFleetLocalMachineCredential(agentUid: string, machineCredentials: string, deps?: FleetLocalControlDeps, opts?: {
     keepSource?: boolean;
 }): void;
+export interface FleetRuntimeInstallResult {
+    release: FleetLocalReleasePin;
+    distributionDir: string;
+    runtimeDir: string;
+    runtimeId: string;
+}
+/**
+ * Everything a bot needs that is shared by every bot on this machine: the
+ * pinned distribution and runtime archive, the private Python, and the built
+ * runtime environment. Safe to run any number of times; a complete install
+ * returns at once.
+ */
+export declare function ensureFleetRuntimeInstalled(installation: FleetLocalInstallation, deps?: FleetLocalBootstrapDeps): Promise<FleetRuntimeInstallResult>;
+/** Whether the shared runtime for this release is already built on this machine. */
+export declare function fleetRuntimeReady(installation: Pick<FleetLocalInstallation, "release">, deps?: {
+    fleetHome?: string;
+    platform?: NodeJS.Platform;
+    python?: FleetPython;
+}): boolean;
 export declare function bootstrapFleetLocalBot(input: FleetLocalProfileInput & {
     machineCredentials?: string;
 }, deps?: FleetLocalBootstrapDeps): Promise<FleetLocalBootstrapResult>;