@clawhive/openclaw-plugin 0.2.0

package/dist/src/agents.d.ts

@@ -0,0 +1,44 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import type { ClawHiveCloudApi, SyncAgentInput, SyncAgentsResult, SyncedAgent } from "./client.js";
+type GatewayAgent = {
+    id?: string;
+    name?: string;
+    identity?: {
+        name?: string;
+        avatar?: string;
+        avatarUrl?: string;
+    };
+    workspace?: string;
+};
+type GatewayAgentsResult = {
+    agents?: GatewayAgent[];
+};
+type ReadLocalAgentsDeps = {
+    listGatewayAgents?: (cfg: OpenClawConfig) => GatewayAgentsResult;
+    listExistingAgentIdsFromDisk?: () => string[];
+};
+export declare function readLocalAgents(cfg: OpenClawConfig, deps?: ReadLocalAgentsDeps): SyncAgentInput[];
+export declare function pushLocalAgents(cloudApi: ClawHiveCloudApi, cfg: OpenClawConfig): Promise<SyncAgentsResult>;
+export type AgentSyncLoopLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+};
+export type AgentSyncLoopOptions = {
+    cloudApi: ClawHiveCloudApi;
+    loadConfig: () => OpenClawConfig;
+    intervalSeconds: number;
+    logger?: AgentSyncLoopLogger;
+    onAgentsSynced?: (items: SyncedAgent[]) => void;
+};
+export declare class AgentSyncLoop {
+    private readonly options;
+    private timer;
+    private running;
+    private lastSignature;
+    constructor(options: AgentSyncLoopOptions);
+    start(): void;
+    stop(): void;
+    private schedule;
+    private tick;
+}
+export {};

package/dist/src/agents.js

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function normalizeAgentId(id) {
+    return (id ?? "").trim().toLowerCase();
+}
+function resolveUserPath(input) {
+    if (input === "~")
+        return os.homedir();
+    if (input.startsWith("~/"))
+        return path.join(os.homedir(), input.slice(2));
+    return input;
+}
+function resolveStateDir() {
+    return process.env.OPENCLAW_STATE_DIR?.trim()
+        ? resolveUserPath(process.env.OPENCLAW_STATE_DIR.trim())
+        : path.join(os.homedir(), ".openclaw");
+}
+function resolveDefaultAgentId(cfg) {
+    const section = cfg.agents ?? {};
+    const list = Array.isArray(section.list) ? section.list : [];
+    if (list.length === 0)
+        return "main";
+    const defaultEntry = list.find((entry) => entry?.default);
+    return normalizeAgentId((defaultEntry ?? list[0])?.id) || "main";
+}
+function resolveAgentWorkspaceDir(cfg, id) {
+    const section = cfg.agents ?? {};
+    const list = Array.isArray(section.list) ? section.list : [];
+    const configured = list.find((entry) => normalizeAgentId(entry.id) === id);
+    if (configured?.workspace?.trim()) {
+        return resolveUserPath(configured.workspace.trim());
+    }
+    const defaultWorkspace = section.defaults?.workspace?.trim();
+    if (defaultWorkspace) {
+        const root = resolveUserPath(defaultWorkspace);
+        return id === resolveDefaultAgentId(cfg) ? root : path.join(root, id);
+    }
+    return id === resolveDefaultAgentId(cfg)
+        ? path.join(resolveStateDir(), "workspace")
+        : path.join(resolveStateDir(), `workspace-${id}`);
+}
+function resolveAgentDir(cfg, id) {
+    const section = cfg.agents ?? {};
+    const list = Array.isArray(section.list) ? section.list : [];
+    const configured = list.find((entry) => normalizeAgentId(entry.id) === id);
+    if (configured?.agentDir?.trim()) {
+        return resolveUserPath(configured.agentDir.trim());
+    }
+    return path.join(resolveStateDir(), "agents", id, "agent");
+}
+function listExistingAgentIdsFromDisk() {
+    const agentsDir = path.join(resolveStateDir(), "agents");
+    try {
+        return fs
+            .readdirSync(agentsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => normalizeAgentId(entry.name))
+            .filter((id) => id.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function listGatewayAgents(cfg) {
+    const section = cfg.agents ?? {};
+    const configured = Array.isArray(section.list) ? section.list : [];
+    const explicitIds = new Set(configured.map((entry) => normalizeAgentId(entry.id)).filter((id) => id.length > 0));
+    const defaultId = normalizeAgentId(resolveDefaultAgentId(cfg));
+    explicitIds.add(defaultId);
+    for (const id of listExistingAgentIdsFromDisk()) {
+        explicitIds.add(id);
+    }
+    const ids = Array.from(explicitIds).sort((a, b) => a.localeCompare(b));
+    const orderedIds = ids.includes(defaultId)
+        ? [defaultId, ...ids.filter((id) => id !== defaultId)]
+        : ids;
+    return {
+        agents: orderedIds.map((id) => {
+            const entry = configured.find((item) => normalizeAgentId(item.id) === id);
+            return {
+                id,
+                name: entry?.name,
+                identity: entry?.identity,
+                workspace: resolveAgentWorkspaceDir(cfg, id),
+            };
+        }),
+    };
+}
+export function readLocalAgents(cfg, deps = {}) {
+    const section = cfg.agents ?? {};
+    const list = Array.isArray(section.list) ? section.list : [];
+    const byId = new Map();
+    const configuredById = new Map(list
+        .filter((entry) => typeof entry?.id === "string" && entry.id.trim().length > 0)
+        .map((entry) => [normalizeAgentId(entry.id), entry]));
+    for (const agent of (deps.listGatewayAgents ?? listGatewayAgents)(cfg).agents ?? []) {
+        const id = normalizeAgentId(agent.id);
+        if (!id)
+            continue;
+        const configured = configuredById.get(id);
+        byId.set(id, {
+            openclawAgentId: id,
+            name: (agent.name?.trim() ||
+                agent.identity?.name?.trim() ||
+                configured?.name?.trim() ||
+                id),
+            description: configured?.description ?? null,
+            avatarUrl: agent.identity?.avatarUrl ?? agent.identity?.avatar ?? null,
+            config: {
+                agency: configured?.agency,
+                workspace: agent.workspace ?? configured?.workspace,
+                agentDir: configured?.agentDir ?? resolveAgentDir(cfg, id),
+            },
+        });
+    }
+    for (const entry of list) {
+        const id = normalizeAgentId(entry.id);
+        if (!id || byId.has(id))
+            continue;
+        byId.set(id, {
+            openclawAgentId: id,
+            name: (entry.name?.trim() || id),
+            description: entry.description ?? null,
+            config: {
+                agency: entry.agency,
+                workspace: entry.workspace,
+                agentDir: entry.agentDir,
+            },
+        });
+    }
+    return Array.from(byId.values());
+}
+export async function pushLocalAgents(cloudApi, cfg) {
+    const agents = readLocalAgents(cfg);
+    if (agents.length === 0) {
+        return { items: [], skipped: 0 };
+    }
+    return await cloudApi.syncAgents(agents);
+}
+export class AgentSyncLoop {
+    options;
+    timer = null;
+    running = false;
+    lastSignature = null;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        void this.tick(true);
+    }
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    schedule() {
+        if (!this.running)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick(false);
+        }, this.options.intervalSeconds * 1000);
+    }
+    async tick(initial) {
+        if (!this.running)
+            return;
+        try {
+            const agents = readLocalAgents(this.options.loadConfig());
+            const signature = JSON.stringify(agents);
+            if (signature !== this.lastSignature) {
+                this.lastSignature = signature;
+                if (agents.length > 0) {
+                    const result = await this.options.cloudApi.syncAgents(agents);
+                    this.options.onAgentsSynced?.(result.items);
+                    if (!initial || result.items.length > 0 || result.skipped > 0) {
+                        this.options.logger?.info(`ClawHive synced ${result.items.length} agent(s) to cloud (skipped ${result.skipped}).`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            this.options.logger?.warn(`ClawHive: failed to refresh local agents: ${reason}`);
+        }
+        finally {
+            this.schedule();
+        }
+    }
+}

package/dist/src/authorization.d.ts

@@ -0,0 +1,34 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { ClawHiveCloudApi } from "./client.js";
+import { resolveResolvedAccount } from "./config.js";
+import { awaitDeviceCodeApproval, printDeviceCodePrompt } from "./deviceCode.js";
+/**
+ * Build the cloud API client from the latest OpenClaw config state.
+ */
+export declare function createClawHiveCloudApi(api: OpenClawPluginApi): {
+    account: ReturnType<typeof resolveResolvedAccount>;
+    anonKey: string;
+    cloudApi: ClawHiveCloudApi;
+};
+/**
+ * Print the next-step hint shown when the plugin is installed but not yet authorized.
+ */
+export declare function printAuthorizationCommandHint(logger: OpenClawPluginApi["logger"]): void;
+type AuthorizationDeps = {
+    createCloudApi?: typeof createClawHiveCloudApi;
+    printDeviceCodePrompt?: typeof printDeviceCodePrompt;
+    awaitDeviceCodeApproval?: typeof awaitDeviceCodeApproval;
+};
+/**
+ * Print a fresh mobile pairing QR and short code on demand.
+ */
+export declare function printManualPairingCode(api: OpenClawPluginApi, ttlSeconds?: number): Promise<void>;
+/**
+ * Run the explicit device-authorization command for the ClawHive plugin.
+ */
+export declare function authorizeClawHivePlugin(api: OpenClawPluginApi, deps?: AuthorizationDeps): Promise<void>;
+/**
+ * Register the top-level `openclaw clawhive` CLI group for manual plugin authorization.
+ */
+export declare function registerClawHiveCli(api: OpenClawPluginApi): void;
+export {};

package/dist/src/authorization.js

@@ -0,0 +1,183 @@
+import { ClawHiveCloudApi, ClawHiveApiError, DeviceCodeDeniedError, DeviceCodeExpiredError, } from "./client.js";
+import { resolveResolvedAccount, writeRegistrationIdentity } from "./config.js";
+import { awaitDeviceCodeApproval, printDeviceCodePrompt, } from "./deviceCode.js";
+import { getPairedDeviceCount, printPairingQr } from "./pairing.js";
+/**
+ * Build the cloud API client from the latest OpenClaw config state.
+ */
+export function createClawHiveCloudApi(api) {
+    const cfg = api.runtime.config.loadConfig();
+    const account = resolveResolvedAccount(cfg);
+    const anonKey = account.anonKey;
+    if (!anonKey) {
+        throw new Error("ClawHive plugin requires a Supabase anon key. Set `channels.clawhive.anonKey` in OpenClaw config or export `CLAWHIVE_SUPABASE_ANON_KEY` in the current terminal.");
+    }
+    const cloudApi = new ClawHiveCloudApi({
+        projectUrl: account.projectUrl,
+        pluginToken: account.pluginToken ?? null,
+        userId: account.userId ?? null,
+        anonKey,
+        pluginNodeId: account.pluginNodeId,
+        nodeName: account.nodeName,
+        pluginVersion: account.pluginVersion,
+    });
+    return { account, anonKey, cloudApi };
+}
+/**
+ * Print the next-step hint shown when the plugin is installed but not yet authorized.
+ */
+export function printAuthorizationCommandHint(logger) {
+    logger.warn("ClawHive plugin is installed but not authorized yet.");
+    logger.info("Run `openclaw clawhive authorize` in your terminal to display the approval URL and user code.");
+    logger.info("If the command reports a missing anon key, set `channels.clawhive.anonKey` in config or export `CLAWHIVE_SUPABASE_ANON_KEY` first.");
+}
+/**
+ * Persist any plugin-register identity drift back into the user's OpenClaw config.
+ */
+async function syncRegistrationIdentity(api, input) {
+    const patch = {};
+    if (!input.account.userId || input.account.userId !== input.registration.user_id) {
+        patch.userId = input.registration.user_id;
+    }
+    if (input.account.pluginNodeId !== input.registration.plugin_node.id) {
+        patch.pluginNodeId = input.registration.plugin_node.id;
+    }
+    const latestCfg = api.runtime.config.loadConfig();
+    const latestChannels = latestCfg.channels ?? {};
+    const latestChannel = latestChannels.clawhive ?? {};
+    if (!latestChannel.anonKey && input.account.anonKey) {
+        patch.anonKey = input.account.anonKey;
+    }
+    if (!patch.userId && !patch.pluginNodeId && !patch.anonKey) {
+        return;
+    }
+    await api.runtime.config.writeConfigFile(writeRegistrationIdentity(latestCfg, patch));
+}
+/**
+ * Print a fresh mobile pairing QR and short code on demand.
+ */
+export async function printManualPairingCode(api, ttlSeconds = 300) {
+    const { account, cloudApi } = createClawHiveCloudApi(api);
+    if (!cloudApi.pluginToken) {
+        api.logger.warn("ClawHive is not authorized yet, so a pairing code cannot be created.");
+        printAuthorizationCommandHint(api.logger);
+        return;
+    }
+    api.logger.info(`ClawHive: generating a mobile pairing code against ${account.projectUrl}.`);
+    const registration = await cloudApi.registerPluginNode();
+    await syncRegistrationIdentity(api, { account, registration });
+    let pairedDeviceCount = 0;
+    try {
+        pairedDeviceCount = await getPairedDeviceCount({
+            registration,
+            projectUrl: account.projectUrl,
+            anonKey: account.anonKey,
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`ClawHive: could not determine existing paired devices before printing the QR (${reason}).`);
+    }
+    await printPairingQr({
+        api: cloudApi,
+        pluginNodeId: registration.plugin_node.id,
+        ttlSeconds,
+        banner: pairedDeviceCount > 0
+            ? `ClawHive: ${pairedDeviceCount} phone(s) already paired. Scan this QR with the ClawHive mobile app to pair an additional phone or recover after reinstall (${ttlSeconds} second TTL).`
+            : `ClawHive: no phones paired yet. Scan this QR with the ClawHive mobile app to pair (${ttlSeconds} second TTL).`,
+    });
+}
+/**
+ * Run the explicit device-authorization command for the ClawHive plugin.
+ */
+export async function authorizeClawHivePlugin(api, deps = {}) {
+    const { account, cloudApi } = (deps.createCloudApi ?? createClawHiveCloudApi)(api);
+    if (cloudApi.pluginToken) {
+        try {
+            await cloudApi.registerPluginNode();
+            api.logger.info("ClawHive is already authorized. Restart the gateway if you are waiting for it to connect.");
+            return;
+        }
+        catch (error) {
+            if (!isInvalidStoredPluginTokenError(error)) {
+                throw error;
+            }
+            api.logger.warn("ClawHive stored plugin token is no longer valid; starting authorization again.");
+        }
+    }
+    api.logger.info(`ClawHive: starting manual device authorization against ${account.projectUrl}.`);
+    try {
+        const start = await cloudApi.startDeviceCode({
+            nodeName: account.nodeName,
+            pluginVersion: account.pluginVersion,
+            description: `OpenClaw plugin device authorization (${account.nodeName})`,
+        });
+        await (deps.printDeviceCodePrompt ?? printDeviceCodePrompt)(start, api.logger);
+        const approval = await (deps.awaitDeviceCodeApproval ?? awaitDeviceCodeApproval)({
+            api: cloudApi,
+            start,
+            logger: api.logger,
+        });
+        const latestCfg = api.runtime.config.loadConfig();
+        await api.runtime.config.writeConfigFile(writeRegistrationIdentity(latestCfg, {
+            anonKey: account.anonKey,
+            pluginToken: approval.plugin_token,
+            userId: approval.user_id,
+        }));
+        api.logger.info("ClawHive authorization completed. Restart the gateway to finish plugin registration.");
+    }
+    catch (error) {
+        if (error instanceof DeviceCodeDeniedError) {
+            api.logger.warn("ClawHive: the user denied the plugin authorization request.");
+            return;
+        }
+        if (error instanceof DeviceCodeExpiredError) {
+            api.logger.warn("ClawHive: device code expired before it was approved. Run `openclaw clawhive authorize` again.");
+            return;
+        }
+        throw error;
+    }
+}
+function isInvalidStoredPluginTokenError(error) {
+    if (!(error instanceof ClawHiveApiError)) {
+        return false;
+    }
+    return (error.status === 401 ||
+        error.status === 403 ||
+        error.errorCode === "Invalid plugin token" ||
+        error.errorCode === "Plugin token has been revoked" ||
+        error.errorCode === "Missing plugin token");
+}
+/**
+ * Register the top-level `openclaw clawhive` CLI group for manual plugin authorization.
+ */
+export function registerClawHiveCli(api) {
+    api.registerCli(({ program }) => {
+        const clawhive = program
+            .command("clawhive")
+            .description("Manage ClawHive plugin authorization and pairing");
+        clawhive
+            .command("authorize")
+            .description("Display the approval URL and user code, then wait for plugin authorization")
+            .action(async () => {
+            await authorizeClawHivePlugin(api);
+        });
+        clawhive
+            .command("pair")
+            .description("Print a fresh mobile pairing QR code and short code")
+            .option("--ttl-seconds <seconds>", "Pairing code TTL in seconds", "300")
+            .action(async (options) => {
+            const ttlSeconds = Number.parseInt(options.ttlSeconds ?? "300", 10);
+            if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+                throw new Error("`--ttl-seconds` must be a positive integer.");
+            }
+            await printManualPairingCode(api, ttlSeconds);
+        });
+    }, {
+        descriptors: [{
+                name: "clawhive",
+                description: "Manage ClawHive plugin authorization and pairing",
+                hasSubcommands: true,
+            }],
+    });
+}

package/dist/src/channel.d.ts

@@ -0,0 +1,5 @@
+import { type ClawHiveResolvedAccount } from "./config.js";
+/**
+ * Keep install/setup permissive so runtime bootstrap can mint the first plugin token.
+ */
+export declare const clawhiveChannelPlugin: import("openclaw/plugin-sdk/channel-core").ChannelPlugin<ClawHiveResolvedAccount, unknown, unknown>;

package/dist/src/channel.js

@@ -0,0 +1,93 @@
+import { createChatChannelPlugin } from "openclaw/plugin-sdk/channel-core";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/core";
+import { CLAWHIVE_CHANNEL_ID, readRawChannelSection, resolveResolvedAccount, writeChannelSection, } from "./config.js";
+import { normalizeSupabaseMode } from "./defaults.js";
+import { rejectMedia, sendAgentText } from "./outbound.js";
+import { clawhiveRuntimeStore } from "./runtime.js";
+/**
+ * Keep install/setup permissive so runtime bootstrap can mint the first plugin token.
+ */
+export const clawhiveChannelPlugin = createChatChannelPlugin({
+    base: {
+        id: CLAWHIVE_CHANNEL_ID,
+        meta: {
+            id: CLAWHIVE_CHANNEL_ID,
+            label: "ClawHive",
+            selectionLabel: "ClawHive",
+            docsPath: "/channels",
+            blurb: "ClawHive cloud pairing and messaging channel",
+            exposure: {
+                configured: true,
+                setup: true,
+                docs: true,
+            },
+        },
+        capabilities: {
+            chatTypes: ["direct"],
+            reply: true,
+            media: false,
+        },
+        config: {
+            listAccountIds: (cfg) => {
+                const section = readRawChannelSection(cfg);
+                return section.projectUrl ? [DEFAULT_ACCOUNT_ID] : [];
+            },
+            resolveAccount: resolveResolvedAccount,
+            defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+            isEnabled: () => true,
+            isConfigured: (account) => Boolean(account.projectUrl),
+            unconfiguredReason: () => "ClawHive needs a Supabase target. Use CLAWHIVE_SUPABASE_MODE=cloud for the baked-in managed project, or set CLAWHIVE_SUPABASE_MODE=local with CLAWHIVE_PROJECT_URL and CLAWHIVE_SUPABASE_ANON_KEY.",
+        },
+        setup: {
+            applyAccountConfig: ({ cfg, input }) => writeChannelSection(cfg, input),
+            validateInput: ({ input }) => {
+                if (normalizeSupabaseMode(process.env.CLAWHIVE_SUPABASE_MODE) !== "local") {
+                    return null;
+                }
+                if (!input.url && !process.env.CLAWHIVE_PROJECT_URL) {
+                    return "ClawHive local mode requires CLAWHIVE_PROJECT_URL or an explicit setup URL.";
+                }
+                return null;
+            },
+        },
+    },
+    security: {
+        dm: {
+            channelKey: CLAWHIVE_CHANNEL_ID,
+            resolvePolicy: (account) => account.dmPolicy ?? null,
+            resolveAllowFrom: (account) => account.allowFrom,
+            defaultPolicy: "allowlist",
+        },
+    },
+    pairing: {
+        text: {
+            idLabel: "ClawHive mobile device",
+            message: "Scan this QR or enter the short code in the ClawHive mobile app to pair:",
+            notify: async ({ id, message }) => {
+                const runtime = clawhiveRuntimeStore.tryGetRuntime();
+                runtime?.pluginApi.logger.info(`ClawHive pairing notification target=${id} message=${message}`);
+            },
+        },
+    },
+    threading: {
+        topLevelReplyToMode: "reply",
+    },
+    outbound: {
+        base: {
+            deliveryMode: "direct",
+        },
+        attachedResults: {
+            channel: CLAWHIVE_CHANNEL_ID,
+            sendText: async (ctx) => {
+                const result = await sendAgentText({
+                    cfg: ctx.cfg,
+                    to: ctx.to,
+                    text: ctx.text,
+                    accountId: ctx.accountId,
+                });
+                return result;
+            },
+            sendMedia: async () => rejectMedia(),
+        },
+    },
+});

package/dist/src/claimPolling.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_IDLE_POLL_MS = 180000;
+export declare const DEFAULT_RETRY_POLL_MS = 30000;
+export declare const DEFAULT_ACTIVE_POLL_MS = 1500;
+export declare const DEFAULT_POLL_JITTER_RATIO = 0.2;
+/**
+ * Add bounded jitter so multiple background claim loops do not keep hitting
+ * Edge Functions in the same narrow CPU window.
+ */
+export declare function jitterPollDelay(delayMs: number, random?: () => number): number;

package/dist/src/claimPolling.js

@@ -0,0 +1,13 @@
+export const DEFAULT_IDLE_POLL_MS = 180_000;
+export const DEFAULT_RETRY_POLL_MS = 30_000;
+export const DEFAULT_ACTIVE_POLL_MS = 1_500;
+export const DEFAULT_POLL_JITTER_RATIO = 0.2;
+/**
+ * Add bounded jitter so multiple background claim loops do not keep hitting
+ * Edge Functions in the same narrow CPU window.
+ */
+export function jitterPollDelay(delayMs, random = Math.random) {
+    const jitterRange = Math.max(0, delayMs * DEFAULT_POLL_JITTER_RATIO);
+    const offset = (random() * 2 - 1) * jitterRange;
+    return Math.max(250, Math.round(delayMs + offset));
+}