@clawhive/openclaw-plugin 0.2.0

package/dist/src/market-install/claimLoop.js

@@ -0,0 +1,183 @@
+import { DEFAULT_ACTIVE_POLL_MS, DEFAULT_IDLE_POLL_MS, DEFAULT_RETRY_POLL_MS, jitterPollDelay, } from "../claimPolling.js";
+import { runExclusiveInstall } from "../installMutex.js";
+import { addInstallBreadcrumb, captureInstallFailure } from "../telemetry.js";
+import { executeInstallJob } from "./executor.js";
+/**
+ * Poll the durable install queue without blocking the existing heartbeat or realtime loops.
+ */
+export class InstallClaimLoop {
+    options;
+    timer = null;
+    wakeTimer = null;
+    wakePending = false;
+    claiming = false;
+    running = false;
+    activeRun = null;
+    lastError = null;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        void this.tick(true);
+    }
+    async stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.wakeTimer) {
+            clearTimeout(this.wakeTimer);
+            this.wakeTimer = null;
+        }
+        this.wakePending = false;
+        if (this.activeRun) {
+            await this.activeRun;
+        }
+        this.options.onActiveInstallChange?.(null);
+    }
+    getLastError() {
+        return this.lastError;
+    }
+    wake() {
+        if (!this.running) {
+            return;
+        }
+        this.wakePending = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.wakeTimer) {
+            return;
+        }
+        this.wakeTimer = setTimeout(() => {
+            this.wakeTimer = null;
+            if (!this.running || !this.wakePending) {
+                return;
+            }
+            this.wakePending = false;
+            void this.tick(false);
+        }, 25);
+    }
+    schedule(delayMs) {
+        if (!this.running) {
+            return;
+        }
+        const nextDelayMs = jitterPollDelay(delayMs);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick(false);
+        }, nextDelayMs);
+    }
+    async tick(initial) {
+        if (!this.running) {
+            return;
+        }
+        if (this.claiming) {
+            this.wakePending = true;
+            return;
+        }
+        if (this.activeRun) {
+            return;
+        }
+        this.claiming = true;
+        try {
+            const result = await this.options.api.claimInstallJob({
+                pluginNodeId: this.options.pluginNodeId,
+                userId: this.options.userId,
+            });
+            this.claiming = false;
+            if (!result.job) {
+                this.lastError = null;
+                this.schedule(this.options.idlePollMs ?? DEFAULT_IDLE_POLL_MS);
+                return;
+            }
+            this.activeRun = this.processJob(result.job).finally(() => {
+                this.activeRun = null;
+                this.options.onActiveInstallChange?.(null);
+            });
+            await this.activeRun;
+            this.lastError = null;
+            this.schedule(DEFAULT_ACTIVE_POLL_MS);
+        }
+        catch (error) {
+            this.lastError = error;
+            const reason = error instanceof Error ? error.message : String(error);
+            this.options.logger?.warn(`ClawHive install claim loop failed initial=${initial}: ${reason}`);
+            this.schedule(this.options.retryPollMs ?? DEFAULT_RETRY_POLL_MS);
+        }
+        finally {
+            if (this.claiming) {
+                this.claiming = false;
+            }
+            if (this.running && this.wakePending && !this.activeRun) {
+                this.wake();
+            }
+        }
+    }
+    async processJob(job) {
+        const pushStage = (stage) => {
+            this.options.onActiveInstallChange?.({
+                jobId: job.jobId,
+                listingId: job.listingId,
+                listingName: job.listingName,
+                releaseId: job.releaseId,
+                version: job.version,
+                targetNodeId: job.targetNodeId,
+                targetNodeName: job.targetNodeName,
+                stage,
+                updatedAt: new Date().toISOString(),
+            });
+        };
+        pushStage("claimed");
+        try {
+            await runExclusiveInstall(() => executeInstallJob(job, {
+                api: this.options.api,
+                pluginApi: this.options.pluginApi,
+                pluginNodeId: this.options.pluginNodeId,
+                userId: this.options.userId,
+                pluginVersion: this.options.pluginVersion,
+                openClawVersion: this.options.openClawVersion,
+                logger: this.options.logger ?? console,
+                onStageChange: pushStage,
+                onAgentsSynced: this.options.onAgentsSynced,
+            }));
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            this.options.logger?.warn(`ClawHive install executor crashed for job ${job.jobId}: ${reason}`);
+            pushStage("failed");
+            addInstallBreadcrumb({
+                stage: "executor-crashed",
+                job,
+                reasonKind: "install_apply_failed",
+                data: { error: reason },
+            });
+            captureInstallFailure({
+                error,
+                reasonKind: "install_apply_failed",
+                job,
+            });
+            await this.options.api.updateInstallJob({
+                pluginNodeId: this.options.pluginNodeId,
+                jobId: job.jobId,
+                userId: this.options.userId,
+                status: "failed",
+                reasonKind: "install_apply_failed",
+                errorMessage: reason,
+                details: {
+                    crashDuring: "claim-loop",
+                    listingId: job.listingId,
+                    releaseId: job.releaseId,
+                    targetNodeId: job.targetNodeId,
+                    version: job.version,
+                },
+            });
+        }
+    }
+}

package/dist/src/market-install/downloader.d.ts

@@ -0,0 +1,36 @@
+import type { ClawHiveCloudApi } from "../client.js";
+/**
+ * Error thrown when download fails after all retries.
+ */
+export declare class DownloadError extends Error {
+    readonly releaseId: string;
+    readonly attempts: number;
+    constructor(message: string, releaseId: string, attempts: number);
+}
+/**
+ * Error thrown when signed URL has expired (403 from Storage).
+ */
+export declare class SignedUrlExpiredError extends Error {
+    constructor();
+}
+type DownloadOptions = {
+    releaseId: string;
+    destinationPath: string;
+    accessToken: string;
+    maxRetries?: number;
+    onProgress?: (bytesDownloaded: number) => void;
+};
+/**
+ * Download release package from Storage with retry and signed URL expiry handling.
+ *
+ * Retry strategy:
+ * - Max 3 attempts by default
+ * - Exponential backoff with jitter (1s → 2s → 4s, capped at 10s)
+ * - Automatic signed URL refresh on 403 (expiry)
+ *
+ * @param api - ClawHiveCloudApi instance
+ * @param options - Download options
+ * @throws {DownloadError} If download fails after all retries
+ */
+export declare function downloadReleasePackage(api: ClawHiveCloudApi, options: DownloadOptions): Promise<void>;
+export {};

package/dist/src/market-install/downloader.js

@@ -0,0 +1,133 @@
+import { createWriteStream } from "node:fs";
+/**
+ * Error thrown when download fails after all retries.
+ */
+export class DownloadError extends Error {
+    releaseId;
+    attempts;
+    constructor(message, releaseId, attempts) {
+        super(message);
+        this.releaseId = releaseId;
+        this.attempts = attempts;
+        this.name = "DownloadError";
+    }
+}
+/**
+ * Error thrown when signed URL has expired (403 from Storage).
+ */
+export class SignedUrlExpiredError extends Error {
+    constructor() {
+        super("Signed URL has expired");
+        this.name = "SignedUrlExpiredError";
+    }
+}
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    multiplier: 2,
+    maxDelayMs: 10000,
+};
+/**
+ * Calculate exponential backoff delay with jitter.
+ */
+function calculateBackoffDelay(attempt, config) {
+    const exponentialDelay = Math.min(config.initialDelayMs * Math.pow(config.multiplier, attempt - 1), config.maxDelayMs);
+    // Add jitter: ±20% of the delay
+    const jitter = exponentialDelay * 0.2 * (Math.random() * 2 - 1);
+    return Math.floor(exponentialDelay + jitter);
+}
+/**
+ * Sleep for specified milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Download file from signed URL with progress tracking.
+ */
+async function downloadFromSignedUrl(signedUrl, destinationPath, onProgress) {
+    const response = await fetch(signedUrl);
+    if (!response.ok) {
+        if (response.status === 403) {
+            throw new SignedUrlExpiredError();
+        }
+        throw new Error(`Download failed with status ${response.status}: ${response.statusText}`);
+    }
+    if (!response.body) {
+        throw new Error("Response body is null");
+    }
+    const writeStream = createWriteStream(destinationPath);
+    const reader = response.body.getReader();
+    try {
+        let bytesDownloaded = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            writeStream.write(value);
+            bytesDownloaded += value.length;
+            if (onProgress) {
+                onProgress(bytesDownloaded);
+            }
+        }
+        writeStream.end();
+        // Wait for write stream to finish
+        await new Promise((resolve, reject) => {
+            writeStream.on("finish", resolve);
+            writeStream.on("error", reject);
+        });
+    }
+    catch (error) {
+        writeStream.destroy();
+        throw error;
+    }
+}
+/**
+ * Download release package from Storage with retry and signed URL expiry handling.
+ *
+ * Retry strategy:
+ * - Max 3 attempts by default
+ * - Exponential backoff with jitter (1s → 2s → 4s, capped at 10s)
+ * - Automatic signed URL refresh on 403 (expiry)
+ *
+ * @param api - ClawHiveCloudApi instance
+ * @param options - Download options
+ * @throws {DownloadError} If download fails after all retries
+ */
+export async function downloadReleasePackage(api, options) {
+    const config = {
+        ...DEFAULT_RETRY_CONFIG,
+        maxRetries: options.maxRetries ?? DEFAULT_RETRY_CONFIG.maxRetries,
+    };
+    let lastError = null;
+    for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+        try {
+            // Get fresh signed URL (handles expiry on retry)
+            const { signed_url, fingerprint } = await api.getSignedDownloadUrl(options.releaseId, options.accessToken);
+            // Download from signed URL
+            await downloadFromSignedUrl(signed_url, options.destinationPath, options.onProgress);
+            // Success - return fingerprint for verification
+            return;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // If signed URL expired, retry immediately (no backoff)
+            if (error instanceof SignedUrlExpiredError) {
+                if (attempt < config.maxRetries) {
+                    continue; // Retry immediately with fresh signed URL
+                }
+            }
+            // For other errors, apply exponential backoff
+            if (attempt < config.maxRetries) {
+                const delayMs = calculateBackoffDelay(attempt, config);
+                await sleep(delayMs);
+                continue;
+            }
+            // All retries exhausted
+            break;
+        }
+    }
+    // All retries failed
+    throw new DownloadError(`Failed to download release package after ${config.maxRetries} attempts: ${lastError?.message ?? "unknown error"}`, options.releaseId, config.maxRetries);
+}

package/dist/src/market-install/executor.d.ts

@@ -0,0 +1,28 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { type ClawHiveCloudApi, type SyncedAgent } from "../client.js";
+import type { ActiveInstallStage, MarketInstallClaimedJob } from "./types.js";
+type InstallExecutorLogger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+};
+export type ExecuteInstallJobOptions = {
+    api: ClawHiveCloudApi;
+    pluginApi: OpenClawPluginApi;
+    pluginNodeId: string;
+    userId: string;
+    pluginVersion: string;
+    openClawVersion: string | null;
+    logger: InstallExecutorLogger;
+    onStageChange?: (stage: ActiveInstallStage) => void;
+    onAgentsSynced?: (items: SyncedAgent[]) => void;
+    requireClaimedArtifact?: boolean;
+};
+/**
+ * Compare dotted versions without pulling in a full semver dependency.
+ */
+export declare function compareLooseVersions(current: string, minimum: string): number;
+/**
+ * Execute one claimed install job and always durably report the final result.
+ */
+export declare function executeInstallJob(job: MarketInstallClaimedJob, options: ExecuteInstallJobOptions): Promise<void>;
+export {};