@clawhive/openclaw-plugin 0.2.0

package/dist/src/config.js

@@ -0,0 +1,94 @@
+import { DEFAULT_ACCOUNT_ID, } from "openclaw/plugin-sdk/core";
+import { resolveSupabaseDefaults } from "./defaults.js";
+export const CLAWHIVE_CHANNEL_ID = "clawhive";
+export function readRawChannelSection(cfg) {
+    const channels = cfg.channels ?? {};
+    return channels[CLAWHIVE_CHANNEL_ID] ?? {};
+}
+function readAllowFrom(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((entry) => typeof entry === "string" || typeof entry === "number");
+}
+export function resolveResolvedAccount(cfg, accountId) {
+    const section = readRawChannelSection(cfg);
+    const rawUserId = section.userId ?? process.env.CLAWHIVE_USER_ID;
+    const resolvedSupabase = resolveSupabaseDefaults({
+        mode: process.env.CLAWHIVE_SUPABASE_MODE,
+        sectionProjectUrl: typeof section.projectUrl === "string" ? section.projectUrl : null,
+        sectionAnonKey: typeof section.anonKey === "string" ? section.anonKey : null,
+        envProjectUrl: process.env.CLAWHIVE_PROJECT_URL,
+        envAnonKey: process.env.CLAWHIVE_SUPABASE_ANON_KEY,
+    });
+    return {
+        accountId: accountId ?? DEFAULT_ACCOUNT_ID,
+        projectUrl: resolvedSupabase.projectUrl,
+        anonKey: resolvedSupabase.anonKey,
+        pluginToken: String(section.pluginToken ?? process.env.CLAWHIVE_PLUGIN_TOKEN ?? ""),
+        userId: rawUserId ? String(rawUserId) : null,
+        pluginNodeId: section.pluginNodeId != null ? String(section.pluginNodeId) : null,
+        nodeName: String(section.nodeName ?? "OpenClaw Desktop"),
+        pluginVersion: String(section.pluginVersion ?? "0.2.0"),
+        publishSourceRef: typeof section.publishSourceRef === "string" ? section.publishSourceRef : null,
+        publishFingerprint: typeof section.publishFingerprint === "string" ? section.publishFingerprint : null,
+        minPluginVersion: typeof section.minPluginVersion === "string" ? section.minPluginVersion : null,
+        minOpenClawVersion: typeof section.minOpenClawVersion === "string" ? section.minOpenClawVersion : null,
+        dmPolicy: typeof section.dmPolicy === "string" ? section.dmPolicy : null,
+        allowFrom: readAllowFrom(section.allowFrom),
+    };
+}
+export function writeChannelSection(cfg, input) {
+    const existing = readRawChannelSection(cfg);
+    const nextSection = {
+        ...existing,
+        projectUrl: input.url ?? process.env.CLAWHIVE_PROJECT_URL ?? existing.projectUrl ?? "",
+        anonKey: process.env.CLAWHIVE_SUPABASE_ANON_KEY ?? existing.anonKey ?? "",
+        pluginToken: input.token ?? process.env.CLAWHIVE_PLUGIN_TOKEN ?? existing.pluginToken ?? "",
+        nodeName: input.name ?? existing.nodeName ?? "OpenClaw Desktop",
+        pluginVersion: existing.pluginVersion ?? "0.2.0",
+        publishSourceRef: existing.publishSourceRef ?? null,
+        publishFingerprint: existing.publishFingerprint ?? null,
+        minPluginVersion: existing.minPluginVersion ?? null,
+        minOpenClawVersion: existing.minOpenClawVersion ?? null,
+    };
+    const explicitUserId = input.userId ?? process.env.CLAWHIVE_USER_ID ?? existing.userId;
+    if (explicitUserId) {
+        nextSection.userId = explicitUserId;
+    }
+    const nextChannels = {
+        ...(cfg.channels ?? {}),
+        [CLAWHIVE_CHANNEL_ID]: nextSection,
+    };
+    return {
+        ...cfg,
+        channels: nextChannels,
+    };
+}
+export function writePluginNodeId(cfg, pluginNodeId) {
+    return patchChannelSection(cfg, { pluginNodeId });
+}
+export function writeRegistrationIdentity(cfg, patch) {
+    const next = {};
+    if (patch.userId)
+        next.userId = patch.userId;
+    if (patch.pluginNodeId)
+        next.pluginNodeId = patch.pluginNodeId;
+    if (patch.pluginToken)
+        next.pluginToken = patch.pluginToken;
+    if (patch.anonKey)
+        next.anonKey = patch.anonKey;
+    return patchChannelSection(cfg, next);
+}
+function patchChannelSection(cfg, patch) {
+    const nextChannels = {
+        ...(cfg.channels ?? {}),
+        [CLAWHIVE_CHANNEL_ID]: {
+            ...readRawChannelSection(cfg),
+            ...patch,
+        },
+    };
+    return {
+        ...cfg,
+        channels: nextChannels,
+    };
+}

package/dist/src/defaults.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Default ClawHive cloud project URL baked into the plugin.
+ *
+ * Override at build time by setting `CLAWHIVE_DEFAULT_PROJECT_URL` before `tsc`.
+ */
+export declare const DEFAULT_PROJECT_URL: string;
+/**
+ * Default ClawHive cloud anon key baked into the plugin.
+ */
+export declare const DEFAULT_SUPABASE_ANON_KEY: string;
+export type ClawHiveSupabaseMode = "cloud" | "local";
+/**
+ * Normalize the optional runtime mode switch for choosing the Supabase target.
+ */
+export declare function normalizeSupabaseMode(value: string | undefined): ClawHiveSupabaseMode | null;
+type ResolveSupabaseDefaultsInput = {
+    mode?: string;
+    sectionProjectUrl?: string | null;
+    sectionAnonKey?: string | null;
+    envProjectUrl?: string | null;
+    envAnonKey?: string | null;
+};
+/**
+ * Resolve the plugin Supabase URL and anon key from legacy config sources or the
+ * explicit mode switch when present.
+ */
+export declare function resolveSupabaseDefaults({ mode, sectionProjectUrl, sectionAnonKey, envProjectUrl, envAnonKey, }: ResolveSupabaseDefaultsInput): {
+    supabaseMode: "cloud";
+    projectUrl: string;
+    anonKey: string;
+} | {
+    supabaseMode: "local";
+    projectUrl: string;
+    anonKey: string;
+} | {
+    supabaseMode: "legacy";
+    projectUrl: string;
+    anonKey: string;
+};
+export {};

package/dist/src/defaults.js

@@ -0,0 +1,52 @@
+/**
+ * Default ClawHive cloud project URL baked into the plugin.
+ *
+ * Override at build time by setting `CLAWHIVE_DEFAULT_PROJECT_URL` before `tsc`.
+ */
+export const DEFAULT_PROJECT_URL = process.env.CLAWHIVE_DEFAULT_PROJECT_URL ?? "https://idqnatwcrdxdzgcxtwdr.supabase.co";
+/**
+ * Default ClawHive cloud anon key baked into the plugin.
+ */
+export const DEFAULT_SUPABASE_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImlkcW5hdHdjcmR4ZHpnY3h0d2RyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzY2NTMyOTIsImV4cCI6MjA5MjIyOTI5Mn0.nfU8hxlOaHlC2lRBwaO13FQ1mcIueqsWoyYbkLRo4-8";
+/**
+ * Normalize the optional runtime mode switch for choosing the Supabase target.
+ */
+export function normalizeSupabaseMode(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    if (normalized === "cloud" || normalized === "managed") {
+        return "cloud";
+    }
+    if (normalized === "local") {
+        return "local";
+    }
+    throw new Error(`Unsupported CLAWHIVE_SUPABASE_MODE: ${value}. Use "cloud" or "local".`);
+}
+/**
+ * Resolve the plugin Supabase URL and anon key from legacy config sources or the
+ * explicit mode switch when present.
+ */
+export function resolveSupabaseDefaults({ mode, sectionProjectUrl, sectionAnonKey, envProjectUrl, envAnonKey, }) {
+    const resolvedMode = normalizeSupabaseMode(mode);
+    if (resolvedMode === "cloud") {
+        return {
+            supabaseMode: resolvedMode,
+            projectUrl: DEFAULT_PROJECT_URL,
+            anonKey: DEFAULT_SUPABASE_ANON_KEY,
+        };
+    }
+    if (resolvedMode === "local") {
+        return {
+            supabaseMode: resolvedMode,
+            projectUrl: envProjectUrl ?? sectionProjectUrl ?? "",
+            anonKey: envAnonKey ?? sectionAnonKey ?? "",
+        };
+    }
+    return {
+        supabaseMode: "legacy",
+        projectUrl: sectionProjectUrl ?? envProjectUrl ?? DEFAULT_PROJECT_URL,
+        anonKey: sectionAnonKey ?? envAnonKey ?? DEFAULT_SUPABASE_ANON_KEY,
+    };
+}

package/dist/src/deviceCode.d.ts

@@ -0,0 +1,16 @@
+import { ClawHiveCloudApi, type DeviceCodeStartResult } from "./client.js";
+export type DeviceCodeLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+};
+export type DeviceCodeAwaitResult = {
+    user_id: string;
+    plugin_token: string;
+};
+export declare function printDeviceCodePrompt(start: DeviceCodeStartResult, logger: DeviceCodeLogger): Promise<void>;
+export declare function awaitDeviceCodeApproval(params: {
+    api: ClawHiveCloudApi;
+    start: DeviceCodeStartResult;
+    logger: DeviceCodeLogger;
+    signal?: AbortSignal;
+}): Promise<DeviceCodeAwaitResult>;

package/dist/src/deviceCode.js

@@ -0,0 +1,65 @@
+import qrcodeTerminal from "qrcode-terminal";
+import { DeviceCodeDeniedError, DeviceCodeExpiredError, } from "./client.js";
+async function renderQr(text) {
+    return await new Promise((resolve) => {
+        qrcodeTerminal.generate(text, { small: true }, (qr) => resolve(qr));
+    });
+}
+export async function printDeviceCodePrompt(start, logger) {
+    const qr = await renderQr(start.verification_uri_complete);
+    const expiresInMin = Math.floor(start.expires_in / 60);
+    const lines = [
+        "",
+        "════════════════════════════════════════════════════════════",
+        "  ClawHive: authorize this OpenClaw install.",
+        "",
+        `  Visit: ${start.verification_uri}`,
+        `  Enter the code: ${start.user_code}`,
+        "",
+        "  Or scan this QR to jump straight to the approval page:",
+        qr,
+        `  (Expires in ${expiresInMin}m; polling for approval…)`,
+        "════════════════════════════════════════════════════════════",
+        "",
+    ];
+    for (const line of lines)
+        logger.info(line);
+}
+export async function awaitDeviceCodeApproval(params) {
+    const { api, start, logger, signal } = params;
+    const deadline = Date.now() + start.expires_in * 1000;
+    let interval = Math.max(start.interval, 1) * 1000;
+    while (Date.now() < deadline) {
+        if (signal?.aborted) {
+            throw new Error("Device authorization aborted");
+        }
+        await sleep(interval);
+        let result;
+        try {
+            result = await api.exchangeDeviceCode(start.device_code);
+        }
+        catch (error) {
+            if (error instanceof DeviceCodeDeniedError) {
+                throw error;
+            }
+            if (error instanceof DeviceCodeExpiredError) {
+                throw error;
+            }
+            const reason = error instanceof Error ? error.message : String(error);
+            logger.warn(`ClawHive: device-code poll failed, will retry: ${reason}`);
+            continue;
+        }
+        if (result.status === "approved") {
+            return {
+                user_id: result.user_id,
+                plugin_token: result.plugin_token,
+            };
+        }
+        // result.status === "pending"
+        interval = Math.max(result.interval, 1) * 1000;
+    }
+    throw new DeviceCodeExpiredError();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/src/heartbeat.d.ts

@@ -0,0 +1,25 @@
+import type { ClawHiveCloudApi } from "./client.js";
+export type HeartbeatStatus = "online" | "offline" | "degraded";
+export type HeartbeatLoopLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+};
+export type HeartbeatLoopOptions = {
+    api: ClawHiveCloudApi;
+    pluginNodeId: string;
+    intervalSeconds: number;
+    logger?: HeartbeatLoopLogger;
+};
+export declare class HeartbeatLoop {
+    private readonly options;
+    private timer;
+    private running;
+    private lastError;
+    constructor(options: HeartbeatLoopOptions);
+    start(): void;
+    stop(): Promise<void>;
+    getLastError(): unknown;
+    private schedule;
+    private tick;
+    private jittered;
+}

package/dist/src/heartbeat.js

@@ -0,0 +1,65 @@
+export class HeartbeatLoop {
+    options;
+    timer = null;
+    running = false;
+    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;
+        }
+        try {
+            await this.options.api.heartbeat({
+                pluginNodeId: this.options.pluginNodeId,
+                status: "offline",
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            this.options.logger?.warn(`ClawHive heartbeat: failed to mark plugin offline on shutdown: ${reason}`);
+        }
+    }
+    getLastError() {
+        return this.lastError;
+    }
+    schedule(delayMs) {
+        if (!this.running)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick(false);
+        }, delayMs);
+    }
+    async tick(initial) {
+        if (!this.running)
+            return;
+        try {
+            await this.options.api.heartbeat({
+                pluginNodeId: this.options.pluginNodeId,
+                status: "online",
+            });
+            this.lastError = null;
+            this.schedule(this.jittered(this.options.intervalSeconds * 1000));
+        }
+        catch (error) {
+            this.lastError = error;
+            const reason = error instanceof Error ? error.message : String(error);
+            this.options.logger?.warn(`ClawHive heartbeat failed initial=${initial}: ${reason}`);
+            this.schedule(this.jittered(Math.min(this.options.intervalSeconds, 15) * 1000));
+        }
+    }
+    jittered(baseMs) {
+        const spread = Math.floor(baseMs * 0.1);
+        return baseMs + Math.floor(Math.random() * spread);
+    }
+}

package/dist/src/imageAttachments.d.ts

@@ -0,0 +1,14 @@
+export type RuntimeImageContent = {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export type ImageMessageAttachment = {
+    storagePath: string;
+    mimeType: string;
+};
+export declare function parseImageMessageAttachment(metadata: unknown): ImageMessageAttachment | null;
+export declare function downloadImageAsContent(input: {
+    signedUrl: string;
+    mimeType: string;
+}): Promise<RuntimeImageContent>;

package/dist/src/imageAttachments.js

@@ -0,0 +1,81 @@
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function parseImageMessageAttachment(metadata) {
+    const record = asRecord(metadata);
+    const attachments = record?.attachments;
+    if (!Array.isArray(attachments) || attachments.length === 0) {
+        return null;
+    }
+    const attachment = asRecord(attachments[0]);
+    if (!attachment || attachment.kind !== "image") {
+        return null;
+    }
+    if (typeof attachment.storagePath !== "string" ||
+        typeof attachment.mimeType !== "string") {
+        return null;
+    }
+    return {
+        storagePath: attachment.storagePath,
+        mimeType: attachment.mimeType,
+    };
+}
+function dataUrlToImageContent(dataUrl, fallbackMimeType) {
+    const match = dataUrl.match(/^data:([^;]+);base64,(.+)$/);
+    if (!match) {
+        throw new Error("Invalid image data URL returned for attachment");
+    }
+    return {
+        type: "image",
+        mimeType: match[1] || fallbackMimeType,
+        data: match[2],
+    };
+}
+function redactImageUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        if (url.searchParams.has("token")) {
+            url.searchParams.set("token", "[redacted]");
+        }
+        return url.toString();
+    }
+    catch {
+        return "<invalid-url>";
+    }
+}
+function formatFetchFailure(error, signedUrl) {
+    const details = error instanceof Error ? [error.message] : [String(error)];
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (cause instanceof Error) {
+        details.push(`cause=${cause.name}: ${cause.message}`);
+    }
+    else if (cause !== undefined) {
+        details.push(`cause=${String(cause)}`);
+    }
+    details.push(`url=${redactImageUrl(signedUrl)}`);
+    return details.join("; ");
+}
+export async function downloadImageAsContent(input) {
+    if (input.signedUrl.startsWith("data:")) {
+        return dataUrlToImageContent(input.signedUrl, input.mimeType);
+    }
+    let response;
+    try {
+        response = await fetch(input.signedUrl);
+    }
+    catch (error) {
+        throw new Error(`Failed to download image attachment: ${formatFetchFailure(error, input.signedUrl)}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to download image attachment: status=${response.status}; url=${redactImageUrl(input.signedUrl)}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    return {
+        type: "image",
+        data: buffer.toString("base64"),
+        mimeType: response.headers.get("content-type") ?? input.mimeType,
+    };
+}

package/dist/src/inbound.d.ts

@@ -0,0 +1,10 @@
+import type { InboundMessage } from "./transport.js";
+import { type ClawHiveRuntime } from "./runtime.js";
+type DispatchOptions = {
+    runtime?: ClawHiveRuntime;
+};
+/**
+ * Dispatches a ClawHive inbound user message into the mapped local OpenClaw agent.
+ */
+export declare function handleInboundMessage(message: InboundMessage, options?: DispatchOptions): Promise<void>;
+export {};

package/dist/src/inbound.js

@@ -0,0 +1,140 @@
+import { resolveDefaultModelForAgent } from "openclaw/plugin-sdk/agent-runtime";
+import { CLAWHIVE_CHANNEL_ID } from "./config.js";
+import { downloadImageAsContent, parseImageMessageAttachment, } from "./imageAttachments.js";
+import { sendAgentText } from "./outbound.js";
+import { buildClawHiveSessionKey, clawhiveRuntimeStore, indexSession, resolveLocalAgentId, } from "./runtime.js";
+/**
+ * Resolves the effective provider/model pair for a local OpenClaw agent.
+ */
+function resolveAgentModelSelection(runtime, localAgentId) {
+    const cfg = runtime.pluginApi.runtime.config.loadConfig();
+    return resolveDefaultModelForAgent({
+        cfg,
+        agentId: localAgentId,
+    });
+}
+/**
+ * Extracts the final user-visible reply text when OpenClaw did not send it itself.
+ */
+function extractVisibleReplyText(result) {
+    const finalText = result.meta?.finalAssistantVisibleText?.trim();
+    if (finalText)
+        return finalText;
+    const payloadText = (result.payloads ?? [])
+        .filter((payload) => !payload?.isReasoning && !payload?.isError)
+        .map((payload) => payload?.text?.trim() ?? "")
+        .filter((text) => text.length > 0)
+        .join("\n\n")
+        .trim();
+    return payloadText || null;
+}
+function resolveInboundPrompt(message) {
+    if (message.type !== "image") {
+        return message.content;
+    }
+    const content = message.content.trim();
+    if (!content || content === "Image") {
+        return "Please analyze this image.";
+    }
+    return message.content;
+}
+async function sendImageReadFailure(input) {
+    await input.runtime.api.writeAgentMessage({
+        pluginNodeId: input.runtime.pluginNodeId,
+        sessionId: input.message.sessionId,
+        agentId: input.message.agentId,
+        content: `I couldn't read the image attachment: ${input.reason}`,
+    }).catch(() => undefined);
+}
+/**
+ * Dispatches a ClawHive inbound user message into the mapped local OpenClaw agent.
+ */
+export async function handleInboundMessage(message, options = {}) {
+    const runtime = options.runtime ?? clawhiveRuntimeStore.tryGetRuntime();
+    if (!runtime)
+        return;
+    if (message.userId !== runtime.userId)
+        return;
+    if (message.role !== "user")
+        return;
+    const localAgentId = resolveLocalAgentId(runtime, message.agentId);
+    if (!localAgentId) {
+        runtime.pluginApi.logger.error(`ClawHive inbound dispatch failed session=${message.sessionId} agent=${message.agentId} msg=${message.id}: no local OpenClaw agent mapping for cloud agent id`);
+        return;
+    }
+    const sessionKey = buildClawHiveSessionKey(message.sessionId);
+    const binding = {
+        sessionId: message.sessionId,
+        cloudAgentId: message.agentId,
+        localAgentId,
+        userId: message.userId,
+        sessionKey,
+        lastSeenSequence: message.sequence,
+    };
+    indexSession(runtime, binding);
+    const logger = runtime.pluginApi.logger;
+    try {
+        const cfg = runtime.pluginApi.runtime.config.loadConfig();
+        const modelSelection = resolveAgentModelSelection(runtime, localAgentId);
+        const workspaceDir = runtime.pluginApi.runtime.agent.resolveAgentWorkspaceDir(cfg, localAgentId);
+        const sessionFile = runtime.pluginApi.runtime.agent.session.resolveSessionFilePath(message.sessionId, undefined, { agentId: localAgentId });
+        const timeoutMs = runtime.pluginApi.runtime.agent.resolveAgentTimeoutMs({
+            cfg,
+        });
+        const imageAttachment = message.type === "image"
+            ? parseImageMessageAttachment(message.metadata)
+            : null;
+        const images = imageAttachment
+            ? [
+                await downloadImageAsContent(await runtime.api.getMessageAttachmentDownloadUrl({
+                    messageId: message.id,
+                    storagePath: imageAttachment.storagePath,
+                })),
+            ]
+            : undefined;
+        const prompt = resolveInboundPrompt(message);
+        const result = await runtime.pluginApi.runtime.agent.runEmbeddedPiAgent({
+            runId: `clawhive-inbound-${message.id}`,
+            trigger: "user",
+            sessionId: message.sessionId,
+            sessionKey,
+            agentId: localAgentId,
+            messageChannel: CLAWHIVE_CHANNEL_ID,
+            messageTo: sessionKey,
+            senderId: message.userId,
+            currentMessageId: message.id,
+            sessionFile,
+            workspaceDir,
+            config: cfg,
+            provider: modelSelection.provider,
+            model: modelSelection.model,
+            prompt,
+            images,
+            timeoutMs,
+        });
+        if (!result.didSendViaMessagingTool) {
+            const replyText = extractVisibleReplyText(result);
+            if (replyText) {
+                await sendAgentText({
+                    cfg,
+                    to: sessionKey,
+                    text: replyText,
+                });
+            }
+            else {
+                logger.warn(`ClawHive inbound dispatch completed without a visible reply session=${message.sessionId} agent=${localAgentId} cloudAgent=${message.agentId} msg=${message.id}`);
+            }
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        logger.error(`ClawHive inbound dispatch failed session=${message.sessionId} agent=${localAgentId} cloudAgent=${message.agentId} msg=${message.id}: ${reason}`);
+        if (message.type === "image") {
+            await sendImageReadFailure({
+                runtime,
+                message,
+                reason,
+            });
+        }
+    }
+}

package/dist/src/installMutex.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Serialize local install application because each install rewrites the shared OpenClaw config.
+ */
+export declare function runExclusiveInstall<T>(operation: () => Promise<T>): Promise<T>;

package/dist/src/installMutex.js

@@ -0,0 +1,18 @@
+let tail = Promise.resolve();
+/**
+ * Serialize local install application because each install rewrites the shared OpenClaw config.
+ */
+export async function runExclusiveInstall(operation) {
+    const previous = tail;
+    let release = () => { };
+    tail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous.catch(() => { });
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+    }
+}

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

@@ -0,0 +1,41 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { ClawHiveCloudApi, SyncedAgent } from "../client.js";
+import type { ActiveInstallJobState } from "./types.js";
+export type InstallClaimLoopLogger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+};
+export type InstallClaimLoopOptions = {
+    api: ClawHiveCloudApi;
+    pluginApi: OpenClawPluginApi;
+    pluginNodeId: string;
+    userId: string;
+    pluginVersion: string;
+    openClawVersion: string | null;
+    logger?: InstallClaimLoopLogger;
+    onActiveInstallChange?: (state: ActiveInstallJobState | null) => void;
+    onAgentsSynced?: (items: SyncedAgent[]) => void;
+    idlePollMs?: number;
+    retryPollMs?: number;
+};
+/**
+ * Poll the durable install queue without blocking the existing heartbeat or realtime loops.
+ */
+export declare class InstallClaimLoop {
+    private readonly options;
+    private timer;
+    private wakeTimer;
+    private wakePending;
+    private claiming;
+    private running;
+    private activeRun;
+    private lastError;
+    constructor(options: InstallClaimLoopOptions);
+    start(): void;
+    stop(): Promise<void>;
+    getLastError(): unknown;
+    wake(): void;
+    private schedule;
+    private tick;
+    private processJob;
+}