openclaw-channel-bgos 0.6.1

package/README.md

@@ -0,0 +1,87 @@
+# openclaw-channel-bgos
+
+OpenClaw channel plugin for BGOS — chat with your OpenClaw agents inside the BGOS app.
+
+Mirrors the shape of the Telegram plugin: pairing, inbound push + REST backfill, outbound text/buttons/approvals, slash-command manifest sync.
+
+## Status
+
+**Scaffold — not yet published.** Core adapters are implemented and unit-tested. Full wiring into OpenClaw's channel-plugin SDK (the `defineChannelPluginEntry` wrapper and agent-dispatch hook) happens in Phase 4 against a live OpenClaw gateway.
+
+## Prerequisites
+
+- Node.js 20+
+- BGOS backend with the `/api/v1/integrations/*` endpoints (PR #41 merged and deployed — see `docs/superpowers/specs/2026-04-20-openclaw-bgos-integration-design.md`)
+- OpenClaw gateway ≥ 1.0 (for the SDK wrapper in Phase 4)
+
+## Install (local dev)
+
+```bash
+cd openclaw-channel-bgos
+npm install
+npm run build
+npm test   # runs vitest — 30 tests against a mock BGOS server
+```
+
+## Pair from OpenClaw CLI
+
+Once published (or `npm link`-ed into an OpenClaw workspace):
+
+```bash
+openclaw pair bgos BGOS-ABCD-EF
+```
+
+This calls `POST /api/v1/integrations/pair-exchange`, stores the raw pairing token at `~/.openclaw/secrets/bgos.json` with mode 0600, and echoes the local agent-route catalog back to BGOS so it renders the checklist.
+
+## Plugin config (channels.bgos)
+
+```json5
+{
+  "channels": {
+    "bgos": {
+      "baseUrl": "https://api.brandgrowthos.ai",
+      "pairingToken": "<token from CLI>",
+      "reconnect": { "initialDelayMs": 1000, "maxDelayMs": 30000 }
+    }
+  }
+}
+```
+
+Or via env: `BGOS_BASE_URL` + `BGOS_PAIRING_TOKEN`.
+
+## What's inside
+
+- `BgosApi` — typed axios client with the X-BGOS-Pairing header
+- `BgosWs` — Socket.IO client (pairingToken handshake, exponential-backoff reconnect, REST backfill on reconnect)
+- `BgosOutbound` — sendText / sendButtons / sendApprovalRequest / sendAgentError
+- `ApprovalHandler` — native-approval protocol using `__approval__:<decision>:<req_id>` callback_data
+- `CommandsSync` — debounced manifest PUT per assistant
+- `pairBgos(...)` — CLI entry for `openclaw pair bgos <CODE>`
+- `bgosSetupWizard` — `defineSetupPluginEntry`-compatible setup object
+- `createBgosChannel(cfg, options)` — composes all of the above; returns handles incl. a shutdown()
+
+## End-to-end testing (manual — needs a real OpenClaw gateway)
+
+See `docs/e2e-manual.md` for the human-run recipe (install, pair, tick an agent in BGOS, send a message, assert agent replies).
+
+## BGOS agent capabilities
+
+Agents reaching the BGOS app through this plugin should understand BGOS's full capability surface — markdown rendering, inline buttons, `ask_user_input`, approvals, files, and slash commands. The canonical reference lives at:
+
+> `hermes-channel-bgos/docs/bgos-agent-capabilities.md`
+
+Until OpenClaw ships a formal mechanism for surfacing this to agents at connect time (planned — see the canonical doc's per-plugin section), include a summary of relevant capabilities in your agent's system prompt.
+
+**Recent additions (Phase 4, April 2026)** — inbound messages from BGOS now carry these read-only fields, surfaced in `inbound_message` WS payloads and via the REST backfill endpoint:
+
+- `replyToId` (number | null) — when set, the user is replying to that earlier message; quote a 1-line preview of the replied-to message when relevant.
+- `forwardedFromMessageId` (number | null) — when set, the user forwarded the content from another chat; treat as a quote, not the user's own words.
+- `isPinned` (boolean) + `pinnedAt` (ISO string | null) — the user marked this important; weight pinned messages first when summarizing.
+
+A new `message_pinned` WebSocket event (`{ message_id, chat_id, user_id, is_pinned, pinned_at }`) fires on `user:<userId>` rooms when the user pins or unpins. The plugin can use this to keep any local pin-state mirror fresh; agents themselves rarely need to subscribe.
+
+Bookmarks are private to the user and not surfaced to agents.
+
+## License
+
+MIT © BrandGrowthOS

package/dist/agent-hints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * BGOS system-prompt addendum for OpenClaw agents.
+ *
+ * This block is appended to every OpenClaw agent's system prompt when the
+ * agent is dispatched via the BGOS origin. Mirrors the gobot-channel-bgos
+ * and hermes-channel-bgos PLATFORM_HINTS content so agents speaking to
+ * BGOS through OpenClaw get the same capability surface.
+ *
+ * Source of truth for what BGOS exposes: `hermes-channel-bgos/docs/
+ * bgos-agent-capabilities.md`. When that doc changes, this string MUST
+ * change too — the `bgos-plugin-capability-sync` skill enforces this.
+ *
+ * Integration note: the OpenClaw host SHOULD call
+ * `buildSystemPromptWithHints(agentSystemPrompt)` in its dispatch handler
+ * before calling the LLM. See `bgos-plugin-capability-sync` and
+ * `bgos-agent-capabilities.md` §OpenClaw for the TBD hook location.
+ */
+/**
+ * The complete addendum, including its leading separator. Append to a
+ * system prompt verbatim.
+ */
+export declare const BGOS_AGENT_HINTS: string;
+/**
+ * Append BGOS_AGENT_HINTS to a base system prompt.
+ *
+ * Idempotent — calling twice on the same input yields the same output.
+ */
+export declare function buildSystemPromptWithHints(originalPrompt: string): string;
+//# sourceMappingURL=agent-hints.d.ts.map

package/dist/agent-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-hints.d.ts","sourceRoot":"","sources":["../src/agent-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2IH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA0C,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAMzE"}

package/dist/agent-hints.js

@@ -0,0 +1,169 @@
+/**
+ * BGOS system-prompt addendum for OpenClaw agents.
+ *
+ * This block is appended to every OpenClaw agent's system prompt when the
+ * agent is dispatched via the BGOS origin. Mirrors the gobot-channel-bgos
+ * and hermes-channel-bgos PLATFORM_HINTS content so agents speaking to
+ * BGOS through OpenClaw get the same capability surface.
+ *
+ * Source of truth for what BGOS exposes: `hermes-channel-bgos/docs/
+ * bgos-agent-capabilities.md`. When that doc changes, this string MUST
+ * change too — the `bgos-plugin-capability-sync` skill enforces this.
+ *
+ * Integration note: the OpenClaw host SHOULD call
+ * `buildSystemPromptWithHints(agentSystemPrompt)` in its dispatch handler
+ * before calling the LLM. See `bgos-plugin-capability-sync` and
+ * `bgos-agent-capabilities.md` §OpenClaw for the TBD hook location.
+ */
+const SEPARATOR = "\n\n---\n# BGOS Channel — Agent Capabilities\n\n";
+const BGOS_AGENT_HINTS_BODY = [
+    "You are responding through the BGOS chat app. Replies render in a polished",
+    "mobile + desktop chat UI; the agent capabilities below are what BGOS",
+    "supports natively.",
+    "",
+    "## Markdown",
+    "Replies render as full markdown: **bold**, *italic*, `inline code`, fenced",
+    "code blocks, [links](url), `#`/`##`/`###` headers, bulleted + numbered",
+    "lists, `>` blockquotes. Tables don't render on mobile — use lists instead.",
+    "Inline image markdown (`![]()`) does NOT render — use the file send",
+    "primitives below instead.",
+    "",
+    "## Sending files / media (you → user)",
+    "Use one of the typed wrappers on `BgosOutbound`:",
+    "  - sendImage({ filename, mimeType, bytes })    cap 10 MB; mime image/*",
+    "  - sendVideo({ filename, mimeType, bytes })    cap 100 MB; mime video/*",
+    "  - sendAudio({ filename, mimeType, bytes })    cap 25 MB; mime audio/*",
+    "  - sendDocument({ filename, mimeType, bytes }) cap 25 MB; any mime",
+    "Or sendFile(...) for the low-level path. The plugin picks inline base64",
+    "(<500 KB) or presigned-PUT S3 (≥500 KB) automatically — you don't need",
+    "to think about it.",
+    "",
+    "## Inline option buttons (non-blocking)",
+    "Use BgosOutbound.sendButtons(). Offer 2–6 tappable chips without blocking.",
+    "Chips stay clickable indefinitely. Use for async nudges, check-ins,",
+    "anywhere the user is NOT actively waiting. Sentinels: `__skip__` (built-in",
+    "Skip chip) and `__custom__` (user typed free text; also arrives as a normal",
+    "message — correlate by message_id).",
+    "",
+    "## Approval bubbles (dangerous tools)",
+    "Use BgosOutbound.sendApprovalRequest(). Renders a 4-button bubble (Allow",
+    "once / Allow for session / Always allow / Deny). Callback arrives as",
+    "`callback_data` = `ea:<decision>:<reqId>` where decision ∈ {once, session,",
+    "always, deny}. Default 60 s fail-closed timeout (server-side).",
+    "",
+    "## ask_user_input — blocking pop-under",
+    "Use BgosOutbound.sendAskUserInput({ questions: [...] }). Pops a",
+    "sheet/modal over the chat and BLOCKS until the user answers. 1–4 questions",
+    "per carousel.",
+    "",
+    "Wire shape: the plugin POSTS ONE message row PER question, all sharing a",
+    "single askId (auto-generated unless you supply one). The frontend groups",
+    "rows by askId and renders them as one blocking sheet. The call returns",
+    "{ ids: number[], askId: string } — `ids` are the per-question message ids,",
+    "`askId` is the shared correlation id.",
+    "",
+    "Per-question fields:",
+    "  - question (string)          REQUIRED — shown above the answer area",
+    "  - askOrder (number, optional) 1-based display order; defaults to array index+1",
+    "  - options[] (optional)       pre-defined chips ({ text, value }), max 6",
+    "  - allowFreeText (optional)   show a free-text composer beneath chips",
+    "  - allowSkip (optional)       allow skipping (sends `__skip__`)",
+    "",
+    "Use only when the user is actively in conversation. For async/proactive",
+    "nudges, use sendButtons instead.",
+    "",
+    "## Slash commands",
+    "Bridge-local — handled by the OpenClaw daemon, never reach the agent:",
+    "  - /new       drops conversation history for this chat (context reset)",
+    "  - /retry     re-dispatches the previous user turn to the agent",
+    "  - /status    daemon liveness probe (route, gateway health, latency)",
+    "Native agent commands arrive as regular text starting with `/` and are",
+    "forwarded to you. Register your command catalog via the integrations",
+    "commands endpoint so they show in the BGOS slash picker.",
+    "",
+    "## A2A — initiate a peer message (you → another BGOS assistant)",
+    "BGOS exposes the user's other assistants as PEERS (Ava, Mario, Hades, …).",
+    "OpenClaw's native sessions_send(label=...) does NOT find them — that",
+    "registry is in-process. Instead, call the daemon's local HTTP surface:",
+    "",
+    "  GET http://127.0.0.1:31848/v1/peers?as=<your_agent_route>",
+    "    → { peers: [ { assistantId, name, avatarUrl, color, introduced, expiresAt } ] }",
+    "    Lists peers visible to your assistant (filtered by introductions).",
+    "",
+    "  POST http://127.0.0.1:31848/v1/peers/send",
+    "    body: {",
+    "      \"as\":     \"<your_agent_route>\",            // REQUIRED",
+    "      \"target\": \"Ava\" | <assistantId number>,     // REQUIRED — name OR id",
+    "      \"text\":   \"<your message>\",                  // REQUIRED",
+    "      \"parent_message_id\": <number>,               // optional — auto-uses",
+    "                                                   //   most recent inbound",
+    "      \"wait_for_reply\": true,                     // optional — block ≤ 50s",
+    "      \"timeout_seconds\": 45,                       // optional, 1–50",
+    "      \"turn_state\": \"expecting_reply\"|\"more_coming\"|\"final\"",
+    "    }",
+    "    → { messageId, chatId, conversationId, reply? }",
+    "",
+    "Routing semantics:",
+    "  - The peer assistant receives your message via THEIR channel adapter",
+    "    (n8n webhook for Ava, Hermes for hermes-routed agents, etc.).",
+    "  - The user sees a SideConversationCard in the originating chat,",
+    "    anchored to parent_message_id. Don't omit parent_message_id unless",
+    "    the daemon can auto-resolve from a recent inbound — the call errors",
+    "    cleanly with `no_parent_message` otherwise.",
+    "  - Call port is configurable via --peers-port / BGOS_PEERS_PORT (default 31848).",
+    "",
+    "Quick example (Hades reaches out to Ava):",
+    "  POST /v1/peers/send",
+    "  { \"as\": \"hades\", \"target\": \"Ava\", \"text\": \"Heads up — task X is done.\" }",
+    "",
+    "## SHARED-ASSISTANT CONTEXT",
+    "This assistant may be shared with other users. Every inbound message includes:",
+    "  - userId            : the user who sent THIS message (always trust this for isolation)",
+    "  - isSharedRecipient : true if the message is from a share recipient (not the owner)",
+    "  - shareOwnerUserId  : the original assistant creator's id, present on shared messages",
+    "",
+    "When isSharedRecipient is true, the daemon also injects a system message",
+    "naming the userId + shareOwnerUserId right before your turn. Treat it as",
+    "authoritative scoping. If you store data per-user (memory, files,",
+    "preferences), key it by `userId` so recipients are isolated from the owner",
+    "and from each other.",
+    "",
+    "## Message actions — reply / forward / pin / bookmark",
+    "Inbound messages and prior-turn history may carry read-only fields:",
+    "  - replyToId (number | null) — user is replying to an earlier message.",
+    "    Surfaces in history as the marker `[reply→#<id>]` prepended to the turn.",
+    "  - forwardedFromMessageId (number | null) — treat content as a quote.",
+    "    Surfaces as `[forwarded from #<id>]`.",
+    "  - isPinned (boolean) + pinnedAt (ISO string | null) — weight pinned",
+    "    messages heavily when summarizing. Surfaces as `[pinned]`.",
+    "  - fromAgent ({ assistantId, userId, name } | null) — the inbound was",
+    "    authored by another agent (a2a). Treat it like a peer, not a user.",
+    "These are user gestures — DO NOT auto-pin, auto-bookmark, or forward",
+    "without explicit consent.",
+    "",
+    "## Agent-to-agent (a2a) outbound",
+    "When you reply on behalf of another agent (peer) or want the recipient to",
+    "see the message as coming from a peer agent rather than yourself, pass",
+    "`fromAgent: { assistantId, userId, name }` to sendText/sendButtons/",
+    "sendImage/etc. The replyToId field correlates side-thread replies — set",
+    "it to the inbound peer message id when answering an a2a side thread so",
+    "the originator's poll matches precisely.",
+].join("\n");
+/**
+ * The complete addendum, including its leading separator. Append to a
+ * system prompt verbatim.
+ */
+export const BGOS_AGENT_HINTS = SEPARATOR + BGOS_AGENT_HINTS_BODY;
+/**
+ * Append BGOS_AGENT_HINTS to a base system prompt.
+ *
+ * Idempotent — calling twice on the same input yields the same output.
+ */
+export function buildSystemPromptWithHints(originalPrompt) {
+    const base = originalPrompt ?? "";
+    if (base.includes("BGOS Channel — Agent Capabilities")) {
+        return base;
+    }
+    return base + BGOS_AGENT_HINTS;
+}
+//# sourceMappingURL=agent-hints.js.map

package/dist/agent-hints.js.map

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

package/dist/approval-handler.d.ts

@@ -0,0 +1,71 @@
+import type { BgosOutbound } from "./outbound.js";
+import type { ApprovalMeta, CallbackResultPayload } from "./types.js";
+/**
+ * Approval request / response bridge.
+ *
+ * When an OpenClaw agent requests consent (native approval flow), call
+ * requestApproval(...). It POSTs an approval_request message to BGOS and
+ * returns a promise that resolves when the user clicks one of the four
+ * tier buttons (Allow once / Allow for session / Always allow / Deny)
+ * via the corresponding callback_result WS event.
+ *
+ * Correlation happens via ApprovalMeta.request_id, which we embed into
+ * each option's callback_data as `ea:<decision>:<req_id>`.
+ * handleCallbackResult(...) is the wiring hook for the WS listener and
+ * accepts BOTH the spec'd `ea:` prefix AND the legacy `__approval__:`
+ * prefix for one release of backwards compatibility (drop the legacy
+ * branch in plugin v0.7.0 once Kc's prod daemon is on v0.5.0+).
+ */
+export type ApprovalDecision = "once" | "session" | "always" | "deny";
+/**
+ * Parse an approval callback into `{ decision, requestId }`. Accepts
+ * both `ea:` (spec) and `__approval__:` (legacy) prefixes; aliases
+ * legacy `approve` to the spec'd `once`. Returns null when the payload
+ * is not an approval callback (regular button clicks pass through).
+ */
+export declare function parseApprovalCallback(cb: string | undefined): {
+    decision: ApprovalDecision;
+    requestId: string;
+} | null;
+export interface PendingApproval {
+    requestId: string;
+    resolve: (decision: ApprovalDecision) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+}
+export declare class ApprovalHandler {
+    private readonly outbound;
+    private readonly pending;
+    constructor(outbound: BgosOutbound);
+    /**
+     * Post an approval_request and wait for Approve/Deny.
+     * Resolves with the decision or rejects after `timeoutMs` (default 30 min).
+     */
+    requestApproval(params: {
+        assistantId: number;
+        chatId: number;
+        text: string;
+        meta: ApprovalMeta;
+        timeoutMs?: number;
+    }): Promise<ApprovalDecision>;
+    /**
+     * Wire this into BgosWs.on("callback_result", ...). Decodes the
+     * approval prefix from the option's callback_data and resolves the
+     * matching pending approval, if any.
+     *
+     * Accepts:
+     *   - `ea:<choice>:<reqId>`           (spec, since plugin v0.5.0)
+     *   - `__approval__:<choice>:<reqId>` (legacy 2-button, kept for one
+     *     release so daemons in flight don't break — drop in v0.7.0)
+     *
+     * Returns true if the payload matched a pending approval, false
+     * otherwise (regular button click — caller should route it to the
+     * agent's interaction handler).
+     */
+    handleCallbackResult(payload: CallbackResultPayload & {
+        callbackData?: string;
+    }): boolean;
+    /** Graceful teardown — rejects all pending. */
+    shutdown(): void;
+}
+//# sourceMappingURL=approval-handler.d.ts.map

package/dist/approval-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-handler.d.ts","sourceRoot":"","sources":["../src/approval-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgBtE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,GAAG,SAAS,GACrB;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqB1D;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC9C,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC;CACzB;AAED,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;gBAEjC,QAAQ,EAAE,YAAY;IAEnD;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,YAAY,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+B7B;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAClB,OAAO,EAAE,qBAAqB,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO;IAWV,+CAA+C;IAC/C,QAAQ,IAAI,IAAI;CAOjB"}

package/dist/approval-handler.js

@@ -0,0 +1,121 @@
+const APPROVAL_DECISIONS = new Set([
+    "once",
+    "session",
+    "always",
+    "deny",
+]);
+/** Legacy 2-button decisions (plugin v0.4.x and earlier). Translated
+ *  to the new 4-tier vocabulary so callers see one consistent enum. */
+const LEGACY_DECISION_ALIASES = {
+    approve: "once",
+    deny: "deny",
+};
+/**
+ * Parse an approval callback into `{ decision, requestId }`. Accepts
+ * both `ea:` (spec) and `__approval__:` (legacy) prefixes; aliases
+ * legacy `approve` to the spec'd `once`. Returns null when the payload
+ * is not an approval callback (regular button clicks pass through).
+ */
+export function parseApprovalCallback(cb) {
+    if (!cb)
+        return null;
+    let rest;
+    if (cb.startsWith("ea:")) {
+        rest = cb.slice("ea:".length);
+    }
+    else if (cb.startsWith("__approval__:")) {
+        rest = cb.slice("__approval__:".length);
+    }
+    else {
+        return null;
+    }
+    const colon = rest.indexOf(":");
+    if (colon < 0)
+        return null;
+    const rawDecision = rest.slice(0, colon);
+    const requestId = rest.slice(colon + 1);
+    if (!requestId)
+        return null;
+    const decision = (APPROVAL_DECISIONS.has(rawDecision)
+        ? rawDecision
+        : LEGACY_DECISION_ALIASES[rawDecision]) ?? null;
+    if (!decision)
+        return null;
+    return { decision, requestId };
+}
+export class ApprovalHandler {
+    outbound;
+    pending = new Map();
+    constructor(outbound) {
+        this.outbound = outbound;
+    }
+    /**
+     * Post an approval_request and wait for Approve/Deny.
+     * Resolves with the decision or rejects after `timeoutMs` (default 30 min).
+     */
+    requestApproval(params) {
+        // Register the pending entry SYNCHRONOUSLY so a callback that arrives
+        // before the POST resolves still matches. POST is fired in parallel;
+        // if it fails we reject the pending promise.
+        return new Promise((resolve, reject) => {
+            const ms = params.timeoutMs ?? 30 * 60 * 1000;
+            const timeout = setTimeout(() => {
+                this.pending.delete(params.meta.request_id);
+                reject(new Error("approval timeout"));
+            }, ms);
+            this.pending.set(params.meta.request_id, {
+                requestId: params.meta.request_id,
+                resolve,
+                reject,
+                timeout,
+            });
+            this.outbound
+                .sendApprovalRequest({
+                assistantId: params.assistantId,
+                chatId: params.chatId,
+                text: params.text,
+                meta: params.meta,
+            })
+                .catch((err) => {
+                clearTimeout(timeout);
+                this.pending.delete(params.meta.request_id);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    /**
+     * Wire this into BgosWs.on("callback_result", ...). Decodes the
+     * approval prefix from the option's callback_data and resolves the
+     * matching pending approval, if any.
+     *
+     * Accepts:
+     *   - `ea:<choice>:<reqId>`           (spec, since plugin v0.5.0)
+     *   - `__approval__:<choice>:<reqId>` (legacy 2-button, kept for one
+     *     release so daemons in flight don't break — drop in v0.7.0)
+     *
+     * Returns true if the payload matched a pending approval, false
+     * otherwise (regular button click — caller should route it to the
+     * agent's interaction handler).
+     */
+    handleCallbackResult(payload) {
+        const parsed = parseApprovalCallback(payload.callbackData);
+        if (!parsed)
+            return false;
+        const entry = this.pending.get(parsed.requestId);
+        if (!entry)
+            return false;
+        clearTimeout(entry.timeout);
+        this.pending.delete(parsed.requestId);
+        entry.resolve(parsed.decision);
+        return true;
+    }
+    /** Graceful teardown — rejects all pending. */
+    shutdown() {
+        for (const [, entry] of this.pending) {
+            clearTimeout(entry.timeout);
+            entry.reject(new Error("plugin shutting down"));
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=approval-handler.js.map

package/dist/approval-handler.js.map

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

package/dist/bgos-api.d.ts

@@ -0,0 +1,111 @@
+import { type AgentCatalogEntry, type BgosMessageEnvelope, type CommandManifestEntry, type InboundMessagePayload, type IntegrationPairing, type OutboundMessagePayload, type PairExchangeResponse, type PluginConfig } from "./types.js";
+/**
+ * Thin typed wrapper around the BGOS integration endpoints. All methods
+ * attach the X-BGOS-Pairing header from cfg.pairingToken.
+ *
+ * A 401 from any request is mapped to PairingRevokedError so callers
+ * (WS client, outbound adapter) can short-circuit and let the setup
+ * wizard prompt for re-pair.
+ */
+export declare class BgosApi {
+    private readonly http;
+    constructor(cfg: PluginConfig);
+    /** GET /integrations/me — confirms token + touches last_seen_at.
+     *  Includes assistant→agent_route bindings so the plugin can seed
+     *  its dispatch map on cold start.
+     */
+    whoami(): Promise<{
+        pairing_id: number;
+        user_id: string;
+        device_label: string;
+        integration: string;
+        assistants?: Array<{
+            assistant_id: number;
+            agent_route: string | null;
+            name: string;
+            /** Count of slash-commands currently set; lets callers decide
+             *  whether to seed defaults without a second round-trip. */
+            command_count?: number;
+        }>;
+    }>;
+    /** Pair exchange (Public; does NOT need X-BGOS-Pairing). */
+    static pairExchange(baseUrl: string, params: {
+        code: string;
+        deviceLabel: string;
+        agentCatalog?: AgentCatalogEntry[];
+    }): Promise<PairExchangeResponse>;
+    /** Plugin pushes (or updates) the agent catalog for this pairing. */
+    pushAgentCatalog(pairingId: number, agents: AgentCatalogEntry[]): Promise<void>;
+    /** Plugin replaces the slash-command manifest for a single bound assistant. */
+    putCommands(assistantId: number, commands: CommandManifestEntry[]): Promise<void>;
+    /** REST backfill after a WS reconnect. */
+    inboundSince(sinceMessageId: number): Promise<{
+        messages: InboundMessagePayload[];
+    }>;
+    /** Fetch the recent message history for a chat — used by the daemon to
+     *  rebuild conversation context before dispatching to a stateless
+     *  gateway. Backend returns up to 100 entries ASC by created_at. */
+    getMessages(chatId: number, userId: string): Promise<BgosMessageEnvelope[]>;
+    /** Agent reply — assistant message with optional inline buttons/approval. */
+    postMessage(payload: OutboundMessagePayload): Promise<{
+        id: number;
+    }>;
+    /** Request a presigned PUT for a file ≥500 KB that the agent wants to send. */
+    createUploadUrl(params: {
+        filename: string;
+        mimeType: string;
+        size: number;
+    }): Promise<{
+        upload_url: string;
+        s3_key: string;
+        expires_at: string;
+    }>;
+    /** List this pairing's active/paired state. Mostly used in setup wizard. */
+    listPairings(): Promise<IntegrationPairing[]>;
+    /**
+     * A2A peer discovery for an OpenClaw agent. Returns the user's other
+     * assistants the caller is allowed to reach (filtered by the
+     * agent_introductions table). The caller's assistant id is sent via
+     * X-Caller-Assistant-Id; backend uses it to scope visibility +
+     * enforce per-pair introduction rules.
+     *
+     * Used by the daemon's peers HTTP server (peers_list) so OpenClaw
+     * agents can discover Ava/Mario/etc. by name before initiating a
+     * peer message via sendToPeer().
+     */
+    listPeers(callerAssistantId: number): Promise<Array<{
+        assistantId: number;
+        name: string;
+        avatarUrl: string | null;
+        color: string | null;
+        introduced: boolean;
+        expiresAt: string | null;
+    }>>;
+    /**
+     * Initiate (or continue) a peer side-thread from this OpenClaw agent
+     * to another BGOS assistant. Backend creates/reuses the a2a chat,
+     * persists the message, and emits inbound_message to the target's
+     * channel adapter with peerConversationId + turnState set.
+     *
+     * @param parentMessageId  Required by the backend: anchors the
+     *   SideConversationCard in the originating chat. Daemon picks the
+     *   most-recent inbound for this caller's assistant when the agent
+     *   doesn't supply one (see peers-server.ts).
+     */
+    sendToPeer(callerAssistantId: number, targetAssistantId: number, params: {
+        text: string;
+        parentMessageId: number;
+        waitForReply?: boolean;
+        timeoutSeconds?: number;
+        turnState?: "expecting_reply" | "more_coming" | "final";
+    }): Promise<{
+        messageId: number;
+        chatId: number;
+        conversationId: number;
+        reply?: {
+            text: string;
+            messageId: number;
+        };
+    }>;
+}
+//# sourceMappingURL=bgos-api.d.ts.map

package/dist/bgos-api.d.ts.map

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