@clawhive/openclaw-plugin 0.2.0

package/README.md

@@ -0,0 +1,217 @@
+# ClawHive OpenClaw Plugin
+
+Desktop-side OpenClaw channel plugin that bridges a local OpenClaw node to the ClawHive cloud so the ClawHive mobile app can send messages to and receive replies from the user's local agents.
+
+For end-user setup and daily usage in Chinese, see [INSTALLATION-GUIDE.zh-CN.md](./INSTALLATION-GUIDE.zh-CN.md).
+For the latest stabilization summary, see [RELEASE-NOTES-2026-04-24.md](../RELEASE-NOTES-2026-04-24.md).
+
+## Architecture at a glance
+
+```
+ClawHive mobile app  ──►  Supabase (Postgres + Realtime + Edge Functions)  ──►  this plugin  ──►  OpenClaw core  ──►  local agent
+                                                                         ◄──  writes agent reply  ◄──
+```
+
+- Inbound: user messages are inserted by the mobile app into `public.messages`. This plugin subscribes to the `messages` Realtime publication and dispatches each `role='user'` row into the local agent via `api.runtime.subagent.run({ sessionKey, message, deliver: true })`.
+- Outbound: OpenClaw core routes the agent reply back through the channel's `outbound.attachedResults.sendText`, which calls the `plugin-message-write` edge function to persist the reply with `role='agent'`.
+- Heartbeat: a background loop calls `plugin-heartbeat` every `heartbeat_interval` seconds (default 30) to keep `plugin_nodes.plugin_status='online'`.
+- Market install orchestration: a separate background loop polls `market-install-claim`, keeps the approved `releaseId`/`version`/`publishSourceRef`/`publishFingerprint` pinned, and reports `installing` plus durable `failed`/`cancelled` outcomes through `market-install-update`.
+
+## Zero-config install
+
+The install flow is intentionally self-provisioning. `openclaw plugins install` must not require a pre-created `pluginToken` or manual edits to `~/.openclaw/openclaw.json`.
+
+Install the published npm package:
+
+```bash
+openclaw plugins install @clawhive/openclaw-plugin
+```
+
+After plugin install, run:
+
+```bash
+openclaw clawhive authorize
+```
+
+The command prints the approval URL plus `user_code`, waits for approval, and persists the resulting `pluginToken` and `userId` into the OpenClaw config. Then restart the gateway.
+
+On the next `openclaw gateway run`:
+
+1. Reads config — `pluginToken` is now present from the explicit authorization command.
+2. Calls `plugin-register` and receives `{plugin_node_id, realtime_topic, user_session}`.
+3. Persists any new `pluginNodeId` or updated `userId` into config.
+4. All subsequent calls (heartbeat, agent-reply writes, pair-code generation, agent sync) present the token via `x-plugin-token`, which the server validates against `plugin_tokens`.
+
+No shared dev secret exists; each install owns its own credential and can be revoked independently.
+
+## Configuration
+
+Minimum managed-cloud install: **nothing**. The plugin falls back to the baked `DEFAULT_PROJECT_URL` in `src/defaults.ts`, silently bootstraps, and writes everything else into config.
+
+Self-hosted or local-dev setup overrides the URL:
+
+```bash
+openclaw channels add --channel clawhive --url https://my-clawhive.example.com
+```
+
+…or via env for one-shot dev:
+
+```bash
+export CLAWHIVE_SUPABASE_MODE=local
+export CLAWHIVE_PROJECT_URL=http://127.0.0.1:54321
+export CLAWHIVE_SUPABASE_ANON_KEY=your-local-anon-or-publishable-key
+```
+
+### Runtime env vars
+
+| Name | Required | Purpose |
+|---|---|---|
+| `CLAWHIVE_SUPABASE_MODE` | optional | `cloud` uses the baked-in managed Supabase project. `local` uses `CLAWHIVE_PROJECT_URL` and `CLAWHIVE_SUPABASE_ANON_KEY`. |
+| `CLAWHIVE_PROJECT_URL` | optional | Local Supabase project base URL used when `CLAWHIVE_SUPABASE_MODE=local`. Do not include `/rest/v1`. |
+| `CLAWHIVE_PLUGIN_TOKEN` | optional | Pre-seed the plugin token instead of letting the plugin bootstrap. Normally auto-populated after first run. |
+| `CLAWHIVE_USER_ID` | optional | Pre-seed the owner user id. Normally auto-populated after bootstrap. |
+| `CLAWHIVE_SUPABASE_ANON_KEY` | optional | Local Supabase anon/publishable key used when `CLAWHIVE_SUPABASE_MODE=local` and `channels.clawhive.anonKey` is not set in OpenClaw config. |
+
+Build-time override (baked into `dist/`):
+
+| Name | Purpose |
+|---|---|
+| `CLAWHIVE_DEFAULT_PROJECT_URL` | Replace the compiled-in default project URL. Set this before `npm run build` when producing a self-hosted plugin package. |
+
+## Runtime lifecycle
+
+1. `gateway_start` fires. Resolve account from config + env + baked default.
+2. If no `pluginToken`, print a hint telling the user to run `openclaw clawhive authorize`, then stay idle.
+3. Once authorized, call `plugin-register` → receive `plugin_node_id`, `realtime_topic`, and a user-session JWT`.
+4. Persist any config drift (`pluginNodeId`, updated `userId`).
+5. Push local agents (`cfg.agents.list`) to the cloud via `plugin-agents-sync`.
+6. Open the Supabase Realtime channel on `public.messages` filtered by `user_id`.
+7. Start the heartbeat loop.
+8. Start the market install claim loop. It runs independently from messaging and heartbeat so long-running install work cannot block inbound chat.
+9. Always print an ANSI QR (via `qrcode-terminal`) with a 5-minute TTL `pair_token` so first-time installs, additional phones, and reinstalled apps can pair without manual cleanup. The banner changes when phones are already paired.
+10. On each inbound `role='user'` row, call `api.runtime.subagent.run({ sessionKey, message, deliver: true })`. Reconnects fetch missed messages via `messages-sync`.
+11. On `gateway_stop`, tear down the install loop, transport, and heartbeat, then mark `plugin_status='offline'`.
+
+## Marketplace install runner
+
+The plugin now claims durable install jobs from the market backend. The current execution contract is intentionally strict:
+
+1. Claim only jobs targeted at this `plugin_node_id`.
+2. Keep the approved `releaseId`, `version`, `publishSourceRef`, and `publishFingerprint` pinned for the whole execution attempt.
+3. Reject incompatible releases if `minPluginVersion` or `minOpenClawVersion` is not satisfied.
+4. Mark the durable job as `installing` once preflight passes.
+5. Always write a final durable `failed` or `cancelled` state with a machine-readable `reasonKind` and a plain-language `errorMessage` if local apply cannot complete.
+
+### Failure mapping
+
+The install runner currently emits these durable failure kinds:
+
+| `reasonKind` | Meaning |
+|---|---|
+| `claim_rejected` | The claimed job does not match the current node or is missing pinned release identity. |
+| `artifact_fetch_failed` | The approved release is missing `publishSourceRef` or `publishFingerprint`, so the plugin cannot verify the exact artifact. |
+| `compatibility_rejected` | `minPluginVersion` or `minOpenClawVersion` rejects the current desktop runtime. |
+| `install_apply_failed` | The job passed preflight but the local host still has no stable marketplace install API to apply the artifact. |
+| `cancelled` | Reserved for future explicit cancellation flows. |
+
+### Release metadata relevance
+
+- `publishSourceRef`: stable source locator the plugin keeps pinned after the user confirms a release on mobile.
+- `publishFingerprint`: immutable checksum/fingerprint the plugin expects before local apply.
+- `minPluginVersion`: minimum ClawHive plugin runtime required by the release.
+- `minOpenClawVersion`: minimum OpenClaw host version required by the release.
+
+The current OpenClaw SDK surface does not yet expose a stable local marketplace install API, so the runner stops after durable preflight and reports a visible failure instead of silently dropping the job or guessing how to install it.
+
+## Manual Commands
+
+- `openclaw clawhive authorize`
+  Prints the browser approval URL and device user code, then waits for authorization.
+- `openclaw clawhive pair`
+  Prints a fresh mobile pairing QR plus short code on demand so you can re-pair a phone after reinstall, add another phone, or recover if you missed the startup banner.
+- `openclaw clawhive pair --ttl-seconds 600`
+  Optional override for the pairing-code TTL when you need a longer window.
+
+## Manual smoke-testing
+
+Everything below runs against a local `supabase start`:
+
+```bash
+# 1. Start the stack
+cd /path/to/openclaw-assistant
+supabase start
+source <(supabase status -o env)
+export PROJECT_URL=http://127.0.0.1:54321
+
+# 2. Mint a real plugin token (no shared dev secret)
+BOOT=$(curl -s -X POST "$PROJECT_URL/functions/v1/plugin-bootstrap" \
+  -H "apikey: $ANON_KEY" -H "Authorization: Bearer $ANON_KEY" \
+  -H "Content-Type: application/json" -d '{"description":"manual-test"}')
+PLUGIN_TOKEN=$(echo "$BOOT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["plugin_token"])')
+
+# 3. Exercise the plugin-authed endpoints with the real token
+curl -s -X POST "$PROJECT_URL/functions/v1/plugin-register" \
+  -H "apikey: $ANON_KEY" -H "Authorization: Bearer $ANON_KEY" \
+  -H "x-plugin-token: $PLUGIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"node_name":"smoke"}'
+```
+
+To run the plugin itself against the local stack:
+
+```bash
+cd openclaw-plugin && npm install && npm run build && cd ..
+openclaw plugins install "$PWD/openclaw-plugin" --force
+
+export CLAWHIVE_PROJECT_URL="$PROJECT_URL"
+export CLAWHIVE_SUPABASE_ANON_KEY="$ANON_KEY"
+export CLAWHIVE_SUPABASE_MODE=local
+openclaw clawhive authorize
+openclaw gateway run --dev --verbose
+```
+
+The local dev flow above should not require hand-editing `~/.openclaw/openclaw.json`. The explicit authorization command persists the token, user id, and anon key before the gateway starts the runtime.
+
+## Marketplace install smoke flow
+
+Use this flow when validating Phase 9 install orchestration end to end:
+
+1. Start the plugin and confirm the desktop node registers successfully.
+2. Publish a market release whose metadata includes `publishSourceRef`, `publishFingerprint`, `minPluginVersion`, and `minOpenClawVersion` as needed.
+3. In the mobile app, discover the listing, open the detail screen, confirm a compatible node, and create the durable install job.
+4. Watch the plugin claim the job and report `installing`, then either:
+   - a durable success once a stable host install API exists, or
+   - a durable failure with `reasonKind` and plain-language `errorMessage`.
+5. Confirm the app shows the latest install status and `My installs` history, and confirm operator evidence exists via install events / health summary.
+
+### Expert Panel Sessions
+
+When ClawHive creates an expert panel session, the cloud stores the turn and contribution state. The plugin claims panel turns, runs local OpenClaw agents in two rounds, updates each contribution as it completes or times out, and writes only the moderator's final answer back to the normal message stream.
+
+The first version assumes all selected agents are available on the same OpenClaw node. Multi-node distributed execution is not supported yet.
+
+## MVP non-goals
+
+- Successful local apply of a marketplace artifact before OpenClaw exposes a stable native install API.
+- Outbound media / file attachments — `sendMedia` throws `unsupported_media`.
+- Plugin token rotation / expiry (tokens are currently long-lived; revoke manually via `update public.plugin_tokens set revoked_at = now() where id = '...'` until a rotation endpoint ships).
+
+## Development
+
+```
+npm install
+npm run check      # tsc --noEmit
+npm run build      # emits dist/
+```
+
+## Publishing to npm
+
+The package is published from this directory:
+
+```bash
+npm login
+npm publish --access public
+```
+
+`prepublishOnly` runs TypeScript checking, builds `dist/`, and prints the exact npm tarball contents with `npm pack --dry-run` before publishing.
+
+The required cloud deltas live under `supabase/` — migrations add `plugin_tokens` and enable Realtime on `messages`, and edge functions cover bootstrap, register, heartbeat, message-write, agents-sync, pair-code-create. Apply with `supabase db reset` in local dev.

package/dist/api.d.ts

@@ -0,0 +1,6 @@
+export { clawhiveChannelPlugin } from "./src/channel.js";
+export { ClawHiveApiError, ClawHiveCloudApi, type AppendedMessage, type ClawHivePluginConfig, type PairingCodeResult, type PluginNode, type PluginRegisterResult, type SyncMessagesResult, type UserSession, } from "./src/client.js";
+export { CLAWHIVE_CHANNEL_ID, readRawChannelSection, resolveResolvedAccount, writeChannelSection, writePluginNodeId, type ClawHiveResolvedAccount, } from "./src/config.js";
+export { HeartbeatLoop, type HeartbeatStatus } from "./src/heartbeat.js";
+export { inboundMessageFromRow, type InboundMessage, type TransportAdapter, type TransportHandlers, type TransportStatus, } from "./src/transport.js";
+export { RealtimeTransport } from "./src/transport/realtime.js";

package/dist/api.js

@@ -0,0 +1,6 @@
+export { clawhiveChannelPlugin } from "./src/channel.js";
+export { ClawHiveApiError, ClawHiveCloudApi, } from "./src/client.js";
+export { CLAWHIVE_CHANNEL_ID, readRawChannelSection, resolveResolvedAccount, writeChannelSection, writePluginNodeId, } from "./src/config.js";
+export { HeartbeatLoop } from "./src/heartbeat.js";
+export { inboundMessageFromRow, } from "./src/transport.js";
+export { RealtimeTransport } from "./src/transport/realtime.js";

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { clawhiveChannelPlugin } from "./src/channel.js";
+declare const clawhiveEntry: ReturnType<typeof defineChannelPluginEntry<typeof clawhiveChannelPlugin>>;
+export default clawhiveEntry;

package/dist/index.js

@@ -0,0 +1,324 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { AgentSyncLoop, pushLocalAgents } from "./src/agents.js";
+import { AgentPanelClaimLoop } from "./src/agent-panel/claimLoop.js";
+import { AgencyInstallClaimLoop } from "./src/agency-install/claimLoop.js";
+import { createClawHiveCloudApi, printAuthorizationCommandHint, registerClawHiveCli, } from "./src/authorization.js";
+import { clawhiveChannelPlugin } from "./src/channel.js";
+import { resolveResolvedAccount, writeRegistrationIdentity } from "./src/config.js";
+import { HeartbeatLoop } from "./src/heartbeat.js";
+import { handleInboundMessage } from "./src/inbound.js";
+import { InstallClaimLoop } from "./src/market-install/claimLoop.js";
+import { resolveOpenClawVersion } from "./src/openclawVersion.js";
+import { getPairedDeviceCount, printPairingQr } from "./src/pairing.js";
+import { clawhiveRuntimeStore, indexSyncedAgents, setActiveInstall, } from "./src/runtime.js";
+import { addPluginBreadcrumb, capturePluginError, initPluginTelemetry, } from "./src/telemetry.js";
+import { RealtimeTransport } from "./src/transport/realtime.js";
+import { PluginWakeSubscription } from "./src/wake.js";
+async function startRuntime(api) {
+    initPluginTelemetry();
+    const cfg = api.runtime.config.loadConfig();
+    const account = resolveResolvedAccount(cfg);
+    if (!account.projectUrl) {
+        api.logger.warn("ClawHive plugin has no projectUrl (config + env + baked default all empty); skipping runtime startup.");
+        return;
+    }
+    if (clawhiveRuntimeStore.tryGetRuntime()) {
+        api.logger.warn("ClawHive runtime already initialized; skipping re-entry.");
+        return;
+    }
+    const { anonKey, cloudApi } = createClawHiveCloudApi(api);
+    if (!cloudApi.pluginToken) {
+        api.logger.info(`ClawHive: no plugin token in config; skipping runtime startup until manual authorization is completed against ${account.projectUrl}.`);
+        printAuthorizationCommandHint(api.logger);
+        return;
+    }
+    const registration = await cloudApi.registerPluginNode();
+    const pluginNodeId = registration.plugin_node.id;
+    const resolvedUserId = registration.user_id;
+    const patch = {};
+    if (!account.userId || account.userId !== resolvedUserId) {
+        patch.userId = resolvedUserId;
+    }
+    if (account.pluginNodeId !== pluginNodeId) {
+        patch.pluginNodeId = pluginNodeId;
+    }
+    const latestCfg = api.runtime.config.loadConfig();
+    const latestChannels = latestCfg.channels ?? {};
+    const latestChannel = latestChannels.clawhive ?? {};
+    if (!latestChannel.anonKey && account.anonKey) {
+        patch.anonKey = account.anonKey;
+    }
+    if (patch.userId || patch.pluginNodeId || patch.pluginToken || patch.anonKey) {
+        await api.runtime.config.writeConfigFile(writeRegistrationIdentity(latestCfg, patch));
+    }
+    let syncResult = { items: [], skipped: 0 };
+    try {
+        syncResult = await pushLocalAgents(cloudApi, api.runtime.config.loadConfig());
+        if (syncResult.items.length > 0 || syncResult.skipped > 0) {
+            api.logger.info(`ClawHive synced ${syncResult.items.length} agent(s) to cloud (skipped ${syncResult.skipped}).`);
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`ClawHive: failed to sync local agents: ${reason}`);
+        capturePluginError(error, "sync-agents");
+    }
+    let wakeSubscription = null;
+    let rebindWakeSubscription = async () => { };
+    const transport = new RealtimeTransport({
+        api: cloudApi,
+        anonKey,
+        userSession: registration.user_session,
+        userId: resolvedUserId,
+        logger: api.logger,
+        onClientReady: () => rebindWakeSubscription(),
+    });
+    const heartbeat = new HeartbeatLoop({
+        api: cloudApi,
+        pluginNodeId,
+        intervalSeconds: registration.heartbeat_interval ?? 30,
+        logger: api.logger,
+    });
+    const agentSyncLoop = new AgentSyncLoop({
+        cloudApi,
+        loadConfig: () => api.runtime.config.loadConfig(),
+        intervalSeconds: Math.max(registration.heartbeat_interval ?? 30, 30),
+        logger: api.logger,
+        onAgentsSynced: (items) => {
+            const runtime = clawhiveRuntimeStore.tryGetRuntime();
+            if (!runtime) {
+                return;
+            }
+            indexSyncedAgents(runtime, items);
+        },
+    });
+    const installLoop = new InstallClaimLoop({
+        api: cloudApi,
+        pluginApi: api,
+        pluginNodeId,
+        userId: resolvedUserId,
+        pluginVersion: account.pluginVersion,
+        openClawVersion: resolveOpenClawVersion(),
+        logger: api.logger,
+        onActiveInstallChange: (state) => {
+            const runtime = clawhiveRuntimeStore.tryGetRuntime();
+            if (!runtime) {
+                return;
+            }
+            setActiveInstall(runtime, state);
+        },
+        onAgentsSynced: (items) => {
+            const runtime = clawhiveRuntimeStore.tryGetRuntime();
+            if (!runtime) {
+                return;
+            }
+            indexSyncedAgents(runtime, items);
+        },
+    });
+    const agencyInstallLoop = new AgencyInstallClaimLoop({
+        api: cloudApi,
+        pluginApi: api,
+        pluginNodeId,
+        userId: resolvedUserId,
+        pluginVersion: account.pluginVersion,
+        openClawVersion: resolveOpenClawVersion(),
+        logger: api.logger,
+        onActiveInstallChange: (state) => {
+            const runtime = clawhiveRuntimeStore.tryGetRuntime();
+            if (!runtime) {
+                return;
+            }
+            setActiveInstall(runtime, state);
+        },
+        onAgentsSynced: (items) => {
+            const runtime = clawhiveRuntimeStore.tryGetRuntime();
+            if (!runtime) {
+                return;
+            }
+            indexSyncedAgents(runtime, items);
+        },
+    });
+    const agentPanelLoop = new AgentPanelClaimLoop({
+        api: cloudApi,
+        pluginApi: api,
+        pluginNodeId,
+        userId: resolvedUserId,
+        logger: api.logger,
+    });
+    const createWakeSubscription = () => new PluginWakeSubscription({
+        client: transport.getClient(),
+        logger: api.logger,
+        pluginNodeId,
+        userId: resolvedUserId,
+        onWake: (event) => {
+            if (event.taskType === "agent_panel_turn") {
+                agentPanelLoop.wake();
+                return;
+            }
+            if (event.taskType === "market_install") {
+                installLoop.wake();
+                return;
+            }
+            if (event.taskType === "agency_install") {
+                agencyInstallLoop.wake();
+            }
+        },
+    });
+    let wakeRebind = Promise.resolve();
+    rebindWakeSubscription = async () => {
+        wakeRebind = wakeRebind.then(async () => {
+            try {
+                await wakeSubscription?.stop();
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                api.logger.warn(`Failed to stop previous ClawHive wake subscription during rebind: ${reason}`);
+            }
+            wakeSubscription = null;
+            clawhiveRuntimeStore.getRuntime().wakeSubscription = null;
+            wakeSubscription = createWakeSubscription();
+            await wakeSubscription.start();
+            clawhiveRuntimeStore.getRuntime().wakeSubscription = wakeSubscription;
+        });
+        await wakeRebind;
+    };
+    try {
+        clawhiveRuntimeStore.setRuntime({
+            api: cloudApi,
+            transport,
+            heartbeat,
+            agentSyncLoop,
+            agentPanelLoop,
+            installLoop,
+            agencyInstallLoop,
+            wakeSubscription,
+            pluginNodeId,
+            userId: resolvedUserId,
+            pluginApi: api,
+            sessionIndex: new Map(),
+            agentIndex: new Map(),
+            activeInstall: null,
+        });
+        indexSyncedAgents(clawhiveRuntimeStore.getRuntime(), syncResult.items);
+        await transport.start({
+            onInboundMessage: (message) => handleInboundMessage(message),
+            onStatusChange: (status) => {
+                api.logger.info(`ClawHive transport status=${status.state}`);
+                addPluginBreadcrumb({
+                    category: "realtime",
+                    message: `transport.${status.state}`,
+                    data: { userId: resolvedUserId },
+                });
+            },
+        });
+        heartbeat.start();
+        agentSyncLoop.start();
+        agentPanelLoop.start();
+        installLoop.start();
+        agencyInstallLoop.start();
+        api.logger.info(`ClawHive plugin runtime started plugin_node=${pluginNodeId} topic=${registration.realtime_topic}`);
+        try {
+            const pairedDeviceCount = await getPairedDeviceCount({
+                registration,
+                projectUrl: account.projectUrl,
+                anonKey,
+            });
+            await printPairingQr({
+                api: cloudApi,
+                pluginNodeId,
+                ttlSeconds: 300,
+                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 (5 minute TTL).`
+                    : "ClawHive: no phones paired yet. Scan this QR with the ClawHive mobile app to pair (5 minute TTL).",
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            api.logger.warn(`ClawHive: could not determine pairing status — skipping startup QR (${reason}).`);
+            capturePluginError(error, "pairing-bootstrap");
+        }
+    }
+    catch (error) {
+        await stopRuntime(api);
+        throw error;
+    }
+}
+async function stopRuntime(api) {
+    const runtime = clawhiveRuntimeStore.tryGetRuntime();
+    if (!runtime)
+        return;
+    try {
+        runtime.agentSyncLoop.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive agent sync loop cleanly: ${reason}`);
+    }
+    try {
+        await runtime.agentPanelLoop.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive panel loop cleanly: ${reason}`);
+    }
+    try {
+        await runtime.installLoop.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive install loop cleanly: ${reason}`);
+    }
+    try {
+        await runtime.agencyInstallLoop.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive Agency install loop cleanly: ${reason}`);
+    }
+    try {
+        await runtime.wakeSubscription?.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive wake subscription cleanly: ${reason}`);
+    }
+    try {
+        await runtime.transport.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive transport cleanly: ${reason}`);
+    }
+    try {
+        await runtime.heartbeat.stop();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        api.logger.warn(`Failed to stop ClawHive heartbeat cleanly: ${reason}`);
+    }
+    clawhiveRuntimeStore.clearRuntime();
+    api.logger.info("ClawHive plugin runtime stopped");
+}
+const clawhiveEntry = defineChannelPluginEntry({
+    id: "clawhive",
+    name: "ClawHive",
+    description: "ClawHive channel plugin",
+    plugin: clawhiveChannelPlugin,
+    registerFull(api) {
+        registerClawHiveCli(api);
+        api.on("gateway_start", async () => {
+            try {
+                await startRuntime(api);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                api.logger.error(`ClawHive plugin failed to start: ${reason}`);
+                capturePluginError(error, "gateway-start");
+            }
+        });
+        api.on("gateway_stop", async () => {
+            await stopRuntime(api);
+        });
+    },
+});
+export default clawhiveEntry;

package/dist/runtime-api.d.ts

@@ -0,0 +1 @@
+export { clawhiveRuntimeStore, buildClawHiveSessionKey, indexSession, lookupSession, type ClawHiveRuntime, type SessionBinding } from "./src/runtime.js";

package/dist/runtime-api.js

@@ -0,0 +1 @@
+export { clawhiveRuntimeStore, buildClawHiveSessionKey, indexSession, lookupSession } from "./src/runtime.js";

package/dist/setup-entry.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    plugin: import("openclaw/plugin-sdk/channel-core").ChannelPlugin<import("./api.js").ClawHiveResolvedAccount, unknown, unknown>;
+};
+export default _default;

package/dist/setup-entry.js

@@ -0,0 +1,3 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { clawhiveChannelPlugin } from "./src/channel.js";
+export default defineSetupPluginEntry(clawhiveChannelPlugin);

package/dist/src/agency-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 "../market-install/types.js";
+export type AgencyInstallClaimLoopLogger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+};
+export type AgencyInstallClaimLoopOptions = {
+    api: ClawHiveCloudApi;
+    pluginApi: OpenClawPluginApi;
+    pluginNodeId: string;
+    userId: string;
+    pluginVersion: string;
+    openClawVersion: string | null;
+    logger?: AgencyInstallClaimLoopLogger;
+    onActiveInstallChange?: (state: ActiveInstallJobState | null) => void;
+    onAgentsSynced?: (items: SyncedAgent[]) => void;
+    idlePollMs?: number;
+    retryPollMs?: number;
+};
+/**
+ * Poll Agency install jobs and reuse the existing manifest executor with Agency endpoints.
+ */
+export declare class AgencyInstallClaimLoop {
+    private readonly options;
+    private timer;
+    private wakeTimer;
+    private wakePending;
+    private claiming;
+    private running;
+    private activeRun;
+    private lastError;
+    constructor(options: AgencyInstallClaimLoopOptions);
+    start(): void;
+    stop(): Promise<void>;
+    getLastError(): unknown;
+    wake(): void;
+    private schedule;
+    private tick;
+    private processJob;
+}