@helmio/openclaw-helmio-chat 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @helmio/openclaw-helmio-chat
+
+OpenClaw plugin that bridges Helmio's SignalR `ChatHub` to per-agent turns inside the Company VM. Phase 1 scope per ADR-0008.
+
+## What it does
+
+- Connects to `${HELMIO_API_URL}/api/chat-hub` with the per-Company bridge token in env (`HELMIO_CHAT_BRIDGE_TOKEN`). The hub auto-joins the connection to the Company's `TeamDefault` conversation group.
+- On every inbound `messageCreated` event with `participantTypeId === 1` (user-originated), dispatches a turn to the CEO agent (phase 1 routes CEO-only; multi-agent fan-out is phase 2).
+- Registers a `helmio_chat_send({ body })` tool on each agent. When the agent's LLM calls it, the tool POSTs to `${HELMIO_API_URL}/api/chat/messages` with the calling agent's id, idempotency key (ULID), and the body. The backend persists + broadcasts; both browser tabs and this plugin see the new message.
+
+## Env vars
+
+- `HELMIO_API_URL` — backend base URL, e.g. `https://10.0.0.2`. Required.
+- `HELMIO_CHAT_BRIDGE_TOKEN` — per-Company bridge token, 32-byte URL-safe base64. Required.
+
+Both are written into the VM `.env` by `CompanyProvisionService.RenderEnv` during provisioning.
+
+## Agent metadata contract
+
+The plugin reads each agent's `metadata.isCeo` from the OpenClaw runtime config to identify the CEO. The agent's `id` field is the Helmio `Agent.Id` (stringified) per `CanonicalAgentList.Build`.
+
+## Install (cloud-init)
+
+```bash
+docker exec openclaw openclaw plugins install npm:@helmio/openclaw-helmio-chat@<pinned-version>
+```
+
+Retry up to 3 times with 10s backoff; second + third attempts pass `--force` (race against gateway startup writes — see `project_openclaw_external_plugin_pattern.md` memory).
+
+## Out of scope (phase 2)
+
+- `@mention` parsing + multi-agent fan-out via `AgentRouteBinding[]`
+- Token redaction (Notion/Linear paste → `(secret redacted)`)
+- `helmio_chat_create_group` tool
+- DM conversations and `conversationKindCode != 1`
+- Threading (`ParentMessageId`)

package/dist/agent-resolver.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeAgentConfig } from "openclaw/plugin-sdk/plugin-entry";
+export interface ResolvedAgent {
+    openclawAgentId: string;
+    helmioAgentId: number;
+    isCeo: boolean;
+}
+export interface ResolverResult {
+    agents: ResolvedAgent[];
+    ceo: ResolvedAgent | undefined;
+}
+export declare function resolveAgents(configs: RuntimeAgentConfig[]): ResolverResult;
+export declare function parseHelmioAgentId(openclawAgentId: string): number | null;

package/dist/agent-resolver.js

@@ -0,0 +1,20 @@
+export function resolveAgents(configs) {
+    const agents = [];
+    for (const cfg of configs) {
+        const helmioAgentId = Number.parseInt(cfg.id, 10);
+        if (!Number.isFinite(helmioAgentId) || helmioAgentId <= 0)
+            continue;
+        agents.push({
+            openclawAgentId: cfg.id,
+            helmioAgentId,
+            isCeo: cfg.metadata?.isCeo === true,
+        });
+    }
+    const ceo = agents.find((a) => a.isCeo);
+    return { agents, ceo };
+}
+export function parseHelmioAgentId(openclawAgentId) {
+    const n = Number.parseInt(openclawAgentId, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+//# sourceMappingURL=agent-resolver.js.map

package/dist/agent-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-resolver.js","sourceRoot":"","sources":["../src/agent-resolver.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,IAAI,CAAC;YAAE,SAAS;QACpE,MAAM,CAAC,IAAI,CAAC;YACV,eAAe,EAAE,GAAG,CAAC,EAAE;YACvB,aAAa;YACb,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,KAAK,IAAI;SACpC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,eAAuB;IACxD,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/dist/chat-connection.d.ts

@@ -0,0 +1,14 @@
+import { HubConnectionState } from "@microsoft/signalr";
+import type { ChatMessageDto } from "./events.js";
+import type { PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+export interface ChatConnectionOptions {
+    hubUrl: string;
+    bridgeToken: string;
+    logger: PluginLogger;
+    onMessage: (msg: ChatMessageDto) => void | Promise<void>;
+}
+export interface ChatConnection {
+    stop(): Promise<void>;
+    state(): HubConnectionState;
+}
+export declare function startChatConnection(opts: ChatConnectionOptions): ChatConnection;

package/dist/chat-connection.js

@@ -0,0 +1,73 @@
+// SignalR connection lifecycle to Helmio's ChatHub. Mirrors the probe plugin's
+// runner pattern: build → wire lifecycle handlers → start → on unrecoverable
+// close, restart with 5s backoff. The hub auto-joins this connection to the
+// Company's TeamDefault group on connect (see ChatHub.OnConnectedAsync) — the
+// plugin doesn't need to call JoinConversation.
+import { HubConnectionBuilder, HubConnectionState, LogLevel, } from "@microsoft/signalr";
+const RECONNECT_DELAYS_MS = [0, 2000, 5000, 10000];
+const RESTART_BACKOFF_MS = 5000;
+const HEARTBEAT_INTERVAL_MS = 60_000;
+export function startChatConnection(opts) {
+    let conn;
+    let stopped = false;
+    const buildConnection = () => new HubConnectionBuilder()
+        .withUrl(opts.hubUrl, {
+        accessTokenFactory: () => opts.bridgeToken,
+    })
+        .withAutomaticReconnect({
+        nextRetryDelayInMilliseconds: (ctx) => RECONNECT_DELAYS_MS[ctx.previousRetryCount] ?? 15_000,
+    })
+        .configureLogging(LogLevel.Information)
+        .build();
+    const wire = (c) => {
+        c.on("messageCreated", (msg) => {
+            void Promise.resolve(opts.onMessage(msg)).catch((err) => opts.logger.error(`helmio-chat: onMessage threw for messageId=${msg?.id}: ${err.message}`));
+        });
+        c.onreconnecting((err) => {
+            opts.logger.warn(`helmio-chat: reconnecting (${err?.message ?? "no-error"})`);
+        });
+        c.onreconnected((connectionId) => {
+            opts.logger.info(`helmio-chat: reconnected (connectionId=${connectionId})`);
+        });
+        c.onclose((err) => {
+            opts.logger.warn(`helmio-chat: connection closed (${err?.message ?? "graceful"})`);
+            // Manual restart covers the unrecoverable-error case
+            // (auth rejected, etc.) where withAutomaticReconnect has given up.
+            if (!stopped)
+                setTimeout(() => void restart(), RESTART_BACKOFF_MS);
+        });
+    };
+    const restart = async () => {
+        if (stopped)
+            return;
+        conn = buildConnection();
+        wire(conn);
+        try {
+            await conn.start();
+            opts.logger.info(`helmio-chat: connected to ${opts.hubUrl}; auto-joined Team group on hub side`);
+        }
+        catch (err) {
+            opts.logger.error(`helmio-chat: connect failed: ${err.message}`);
+            if (!stopped)
+                setTimeout(() => void restart(), RESTART_BACKOFF_MS);
+        }
+    };
+    void restart();
+    const heartbeat = setInterval(() => {
+        opts.logger.debug?.(`helmio-chat: state=${conn?.state ?? HubConnectionState.Disconnected} connectionId=${conn?.connectionId ?? "none"}`);
+    }, HEARTBEAT_INTERVAL_MS);
+    return {
+        async stop() {
+            stopped = true;
+            clearInterval(heartbeat);
+            try {
+                await conn?.stop();
+            }
+            catch (err) {
+                opts.logger.warn(`helmio-chat: stop failed: ${err.message}`);
+            }
+        },
+        state: () => conn?.state ?? HubConnectionState.Disconnected,
+    };
+}
+//# sourceMappingURL=chat-connection.js.map

package/dist/chat-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-connection.js","sourceRoot":"","sources":["../src/chat-connection.ts"],"names":[],"mappings":"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"}

package/dist/chat-send-tool.d.ts

@@ -0,0 +1,14 @@
+import type { PluginApi, PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+export interface ChatSendToolOptions {
+    helmioApiUrl: string;
+    bridgeToken: string;
+    logger: PluginLogger;
+    fetchFn?: typeof fetch;
+    idFactory?: () => string;
+}
+export interface ChatSendResult {
+    ok: true;
+    messageId: number;
+    deduplicated?: true;
+}
+export declare function registerChatSendTool(api: PluginApi, opts: ChatSendToolOptions): void;

package/dist/chat-send-tool.js

@@ -0,0 +1,99 @@
+// Outbound chat-send tool. Registered once globally; the runtime passes the
+// calling agent's id in the tool execute context, which we parse as the
+// Helmio Agent.Id (CanonicalAgentList.Build sets openclaw agent id =
+// Agent.Id.ToString()).
+//
+// Wire format matches ChatMessagesController.cs InboundMessageRequest:
+//   { clientMsgId, agentId, conversationKindCode: 1, body }
+// 201 → fresh persist; 200 → idempotent duplicate (existing messageId
+// returned, see ChatMessagesController.cs:164-171).
+import { ulid } from "ulid";
+import { ConversationKind } from "./events.js";
+import { parseHelmioAgentId } from "./agent-resolver.js";
+const MAX_RETRIES = 3;
+const BASE_BACKOFF_MS = 250;
+export function registerChatSendTool(api, opts) {
+    const fetchFn = opts.fetchFn ?? globalThis.fetch;
+    const newId = opts.idFactory ?? ulid;
+    const endpoint = `${opts.helmioApiUrl.replace(/\/+$/, "")}/api/chat/messages`;
+    api.registerTool({
+        name: "helmio_chat_send",
+        description: "Send a message to the Company's Team conversation. The message appears to all participants (the Company owner and every active agent). Use this to reply to user messages.",
+        parameters: {
+            type: "object",
+            properties: {
+                body: {
+                    type: "string",
+                    description: "Message text. Plain or markdown.",
+                },
+            },
+            required: ["body"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            const helmioAgentId = parseHelmioAgentId(ctx.agentId);
+            if (helmioAgentId === null) {
+                throw new Error(`helmio_chat_send: cannot derive Helmio agent id from openclaw agentId=${ctx.agentId}`);
+            }
+            if (!args.body || args.body.trim().length === 0) {
+                throw new Error("helmio_chat_send: body must be non-empty");
+            }
+            const payload = {
+                clientMsgId: newId(),
+                agentId: helmioAgentId,
+                conversationKindCode: ConversationKind.TeamDefault,
+                body: args.body,
+            };
+            return await postWithRetry(fetchFn, endpoint, opts.bridgeToken, payload, opts.logger);
+        },
+    });
+}
+async function postWithRetry(fetchFn, endpoint, bridgeToken, payload, logger) {
+    let lastErr;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const res = await fetchFn(endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${bridgeToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(payload),
+            });
+            if (res.status === 201) {
+                const body = (await res.json());
+                return { ok: true, messageId: body.messageId };
+            }
+            if (res.status === 200) {
+                // Idempotent replay path — same (conversationId, clientMsgId) already
+                // exists server-side. ChatMessagesController returns the prior id.
+                const body = (await res.json());
+                return { ok: true, messageId: body.messageId, deduplicated: true };
+            }
+            if (res.status >= 400 && res.status < 500) {
+                const text = await res.text();
+                throw new Error(`helmio_chat_send: ${res.status} ${text}`);
+            }
+            // 5xx — retry
+            const text = await res.text();
+            lastErr = new Error(`helmio_chat_send: ${res.status} ${text}`);
+            logger.warn(`helmio_chat_send: attempt ${attempt}/${MAX_RETRIES} failed (${res.status}); will retry`);
+        }
+        catch (err) {
+            if (err.message?.startsWith("helmio_chat_send: 4"))
+                throw err;
+            lastErr = err;
+            logger.warn(`helmio_chat_send: attempt ${attempt}/${MAX_RETRIES} threw: ${err.message}`);
+        }
+        if (attempt < MAX_RETRIES) {
+            await sleep(BASE_BACKOFF_MS * 2 ** (attempt - 1));
+        }
+    }
+    throw lastErr instanceof Error
+        ? lastErr
+        : new Error("helmio_chat_send: exhausted retries");
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=chat-send-tool.js.map

package/dist/chat-send-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-send-tool.js","sourceRoot":"","sources":["../src/chat-send-tool.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,17 @@
+export interface ChatMessageDto {
+    id: number;
+    conversationId: number;
+    participantTypeId: number;
+    senderId: number;
+    body: string;
+    createdAt: string;
+}
+export declare const ParticipantType: {
+    readonly User: 1;
+    readonly Agent: 2;
+};
+export declare const ConversationKind: {
+    readonly TeamDefault: 1;
+    readonly Group: 2;
+    readonly DirectMessage: 3;
+};

package/dist/events.js

@@ -0,0 +1,16 @@
+// Wire-format DTO emitted by SignalRChatBroadcaster (backend) on every
+// `messageCreated` event. Mirrors Helmio.WebAPI/Hubs/IChatBroadcaster.cs
+// `ChatMessageDto` exactly — renaming a field on one side without the other
+// breaks the bridge silently.
+// Matches Helmio.Business.Enums.ParticipantTypeCodes.
+export const ParticipantType = {
+    User: 1,
+    Agent: 2,
+};
+// Matches Helmio.Business.Enums.ConversationKindCodes.
+export const ConversationKind = {
+    TeamDefault: 1,
+    Group: 2,
+    DirectMessage: 3,
+};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,yEAAyE;AACzE,4EAA4E;AAC5E,8BAA8B;AAW9B,sDAAsD;AACtD,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACA,CAAC;AAEX,uDAAuD;AACvD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW,EAAE,CAAC;IACd,KAAK,EAAE,CAAC;IACR,aAAa,EAAE,CAAC;CACR,CAAC"}

package/dist/inbound-router.d.ts

@@ -0,0 +1,9 @@
+import { type ChatMessageDto } from "./events.js";
+import type { ResolvedAgent } from "./agent-resolver.js";
+import type { PluginLogger, PluginRuntime } from "openclaw/plugin-sdk/plugin-entry";
+export interface InboundRouterDeps {
+    runtime: PluginRuntime;
+    logger: PluginLogger;
+    ceo: ResolvedAgent | undefined;
+}
+export declare function routeInbound(msg: ChatMessageDto, deps: InboundRouterDeps): Promise<"dispatched" | "ignored-agent" | "ignored-no-ceo">;

package/dist/inbound-router.js

@@ -0,0 +1,29 @@
+// Routes inbound chat messages to agents. Phase 1: CEO-only — every
+// user-typed message in the Team conversation dispatches a turn to the
+// CEO agent. Agent-typed messages (participantTypeId === 2) are dropped
+// to prevent self-loops (the CEO's own outbound reply is broadcast back
+// to the plugin's connection).
+//
+// Phase 2 will replace this with @mention parsing + AgentRouteBinding[]
+// fan-out per ADR-0008 probe C3 findings.
+import { ParticipantType } from "./events.js";
+export async function routeInbound(msg, deps) {
+    if (msg.participantTypeId !== ParticipantType.User) {
+        return "ignored-agent";
+    }
+    if (!deps.ceo) {
+        deps.logger.warn(`helmio-chat: dropped messageId=${msg.id} — no CEO agent found in runtime config`);
+        return "ignored-no-ceo";
+    }
+    await deps.runtime.channel.turn.run({
+        agentId: deps.ceo.openclawAgentId,
+        conversationId: String(msg.conversationId),
+        input: {
+            body: msg.body,
+            senderId: String(msg.senderId),
+            senderType: "user",
+        },
+    });
+    return "dispatched";
+}
+//# sourceMappingURL=inbound-router.js.map

package/dist/inbound-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-router.js","sourceRoot":"","sources":["../src/inbound-router.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,uEAAuE;AACvE,wEAAwE;AACxE,wEAAwE;AACxE,+BAA+B;AAC/B,EAAE;AACF,wEAAwE;AACxE,0CAA0C;AAE1C,OAAO,EAAuB,eAAe,EAAE,MAAM,aAAa,CAAC;AAUnE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAmB,EACnB,IAAuB;IAEvB,IAAI,GAAG,CAAC,iBAAiB,KAAK,eAAe,CAAC,IAAI,EAAE,CAAC;QACnD,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,kCAAkC,GAAG,CAAC,EAAE,yCAAyC,CAClF,CAAC;QACF,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QAClC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,eAAe;QACjC,cAAc,EAAE,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC;QAC1C,KAAK,EAAE;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAC9B,UAAU,EAAE,MAAM;SACnB;KACF,CAAC,CAAC;IACH,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("openclaw/plugin-sdk/plugin-entry").PluginEntryDefinition;
+export default _default;

package/dist/index.js

@@ -0,0 +1,58 @@
+// @helmio/openclaw-helmio-chat — ADR-0008 phase 1.
+//
+// Wires three pieces:
+//   1. SignalR connection to ${HELMIO_API_URL}/api/chat-hub (bridge token in
+//      env). Hub auto-joins us to the Company's Team conversation.
+//   2. Outbound chat-send tool registered globally; agents call it to reply,
+//      tool POSTs to /api/chat/messages.
+//   3. Inbound router: user-typed messages dispatch a turn to the CEO agent.
+//      (Phase 2 will add @mention parsing + multi-agent fan-out.)
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { resolveAgents } from "./agent-resolver.js";
+import { startChatConnection } from "./chat-connection.js";
+import { registerChatSendTool } from "./chat-send-tool.js";
+import { routeInbound } from "./inbound-router.js";
+let connection;
+export default definePluginEntry({
+    id: "helmio-chat",
+    displayName: "Helmio Chat",
+    version: "0.1.0",
+    register(api) {
+        const helmioApiUrl = process.env.HELMIO_API_URL;
+        const bridgeToken = process.env.HELMIO_CHAT_BRIDGE_TOKEN;
+        if (!helmioApiUrl || !bridgeToken) {
+            api.logger.error("helmio-chat: HELMIO_API_URL or HELMIO_CHAT_BRIDGE_TOKEN not set; plugin loaded but disabled.");
+            return;
+        }
+        // Plugin is installed at provision time BEFORE agents.create runs, so
+        // agents.list is empty at register(). Re-resolve on every inbound
+        // message instead of caching once.
+        const initial = resolveAgents(api.runtime.agents.list());
+        api.logger.info(`helmio-chat: register-time agents=${initial.agents.length} ceo=${initial.ceo?.openclawAgentId ?? "<none>"}`);
+        registerChatSendTool(api, {
+            helmioApiUrl,
+            bridgeToken,
+            logger: api.logger,
+        });
+        const hubUrl = `${helmioApiUrl.replace(/\/+$/, "")}/api/chat-hub`;
+        connection = startChatConnection({
+            hubUrl,
+            bridgeToken,
+            logger: api.logger,
+            onMessage: async (msg) => {
+                const { ceo } = resolveAgents(api.runtime.agents.list());
+                const verdict = await routeInbound(msg, {
+                    runtime: api.runtime,
+                    logger: api.logger,
+                    ceo,
+                });
+                api.logger.info(`helmio-chat: messageId=${msg.id} participantType=${msg.participantTypeId} verdict=${verdict}`);
+            },
+        });
+    },
+    async dispose() {
+        await connection?.stop();
+        connection = undefined;
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,sBAAsB;AACtB,6EAA6E;AAC7E,mEAAmE;AACnE,6EAA6E;AAC7E,yCAAyC;AACzC,6EAA6E;AAC7E,kEAAkE;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,IAAI,UAAsC,CAAC;AAE3C,eAAe,iBAAiB,CAAC;IAC/B,EAAE,EAAE,aAAa;IACjB,WAAW,EAAE,aAAa;IAC1B,OAAO,EAAE,OAAO;IAChB,QAAQ,CAAC,GAAG;QACV,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QAChD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;QACzD,IAAI,CAAC,YAAY,IAAI,CAAC,WAAW,EAAE,CAAC;YAClC,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,8FAA8F,CAC/F,CAAC;YACF,OAAO;QACT,CAAC;QAED,sEAAsE;QACtE,kEAAkE;QAClE,mCAAmC;QACnC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACzD,GAAG,CAAC,MAAM,CAAC,IAAI,CACb,qCAAqC,OAAO,CAAC,MAAM,CAAC,MAAM,QAAQ,OAAO,CAAC,GAAG,EAAE,eAAe,IAAI,QAAQ,EAAE,CAC7G,CAAC;QAEF,oBAAoB,CAAC,GAAG,EAAE;YACxB,YAAY;YACZ,WAAW;YACX,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC;QAClE,UAAU,GAAG,mBAAmB,CAAC;YAC/B,MAAM;YACN,WAAW;YACX,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBACvB,MAAM,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;gBACzD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE;oBACtC,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,GAAG;iBACJ,CAAC,CAAC;gBACH,GAAG,CAAC,MAAM,CAAC,IAAI,CACb,0BAA0B,GAAG,CAAC,EAAE,oBAAoB,GAAG,CAAC,iBAAiB,YAAY,OAAO,EAAE,CAC/F,CAAC;YACJ,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,OAAO;QACX,MAAM,UAAU,EAAE,IAAI,EAAE,CAAC;QACzB,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC;CACF,CAAC,CAAC"}

package/openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "helmio-chat",
+  "name": "Helmio Chat",
+  "description": "Bridges Helmio's SignalR ChatHub to per-agent turns inside the Company VM. Inbound user messages dispatch to agents via the runtime turn API; agent replies emit through the `helmio_chat_send` tool which POSTs to /api/chat/messages. ADR-0008.",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@helmio/openclaw-helmio-chat",
+  "version": "0.1.0",
+  "private": false,
+  "description": "OpenClaw plugin that bridges Helmio's SignalR ChatHub to per-agent turns inside the Company VM. Installed at cloud-init via `openclaw plugins install npm:@helmio/openclaw-helmio-chat@<pinned>`. ADR-0008.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md",
+    "openclaw.plugin.json"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "minGatewayVersion": "2026.2.26"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test src/__tests__/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@microsoft/signalr": "^8.0.7",
+    "ulid": "^2.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "tsx": "^4.19.2",
+    "@types/node": "^20.12.7"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}