@beeos-ai/device-agent 0.9.5 → 0.9.8

package/dist/plugins/message-bus/busy-reply.d.ts

@@ -10,17 +10,17 @@
  * `/wait` timeout.
  *
  * Type/payload alignment: uses the same `agent_reply` type that the
- * outbound listener emits, with a `{ error }` body that matches
+ * MsChannelNotifier emits, with a `{ error }` body that matches
  * `backend/pkg/chatinvoke/invoker.go::extractReplyFinal` (which reads
  * `payload.error` first, falling back to `payload.text`).
  */
-import type { MessageSDK } from "@beeos-ai/message-sdk";
+import type { MessageClient } from "@beeos-ai/message-sdk";
 export interface BusyReplyRequest {
     channelId: string;
     inboundMessageId: string;
     /**
      * Session key derived from the rejected envelope (via
-     * `extractChatPrompt(envelope).sessionKey`). Always set so the busy
+     * `extractChatPrompt(msg).sessionKey`). Always set so the busy
      * reply payload has the same `{ session_key, error }` shape as a
      * regular `agent_reply`.
      */
@@ -30,9 +30,9 @@ export interface BusyReplyHandler {
     replyBusy(req: BusyReplyRequest): Promise<void>;
 }
 export interface BusyReplyHandlerOptions {
-    sdk: MessageSDK;
+    client: MessageClient;
 }
-export declare class MessageSdkBusyReplyHandler implements BusyReplyHandler {
+export declare class MessageClientBusyReplyHandler implements BusyReplyHandler {
     private readonly opts;
     constructor(opts: BusyReplyHandlerOptions);
     replyBusy(req: BusyReplyRequest): Promise<void>;

package/dist/plugins/message-bus/busy-reply.js

@@ -10,28 +10,49 @@
  * `/wait` timeout.
  *
  * Type/payload alignment: uses the same `agent_reply` type that the
- * outbound listener emits, with a `{ error }` body that matches
+ * MsChannelNotifier emits, with a `{ error }` body that matches
  * `backend/pkg/chatinvoke/invoker.go::extractReplyFinal` (which reads
  * `payload.error` first, falling back to `payload.text`).
  */
-export class MessageSdkBusyReplyHandler {
+export class MessageClientBusyReplyHandler {
     opts;
     constructor(opts) {
         this.opts = opts;
     }
     async replyBusy(req) {
-        // Durable persist (sendChannelMessage) instead of Centrifugo direct
-        // publish — caller's /wait long-poll has reconnect race windows; a
-        // busy reply lost in that window would leave the caller hung until
-        // its own timeout. Mirrors MsChannelNotifier.publishFinal.
-        await this.opts.sdk.sendChannelMessage(req.channelId, {
+        // Persistent v2 send — MS writes to channel_messages, fans out via
+        // Centrifugo. Caller's /wait long-poll has reconnect race windows;
+        // persistence is required so the busy reply isn't lost.
+        //
+        // Wire contract (PR7 — see agents/device-agent/docs/adr/006-agent-busy-contract.md):
+        //   - `error` (string)       — legacy field surfaced as
+        //                              TaskState.Error by chatinvoke's
+        //                              msgderive.extractError. Stable.
+        //   - `error_code` (string)  — structured machine-readable code.
+        //                              Callers prefer this over fragile
+        //                              `error.includes("agent_busy")`
+        //                              string matching. Stable; future
+        //                              busy variants will add new codes
+        //                              while keeping `error_code` as the
+        //                              switch-on field.
+        //   - `text` (string)        — human-readable explanation.
+        //
+        // `replyTo` is set so MS's single_shot logic
+        // (channel.SingleShot && reply_to != "") auto-closes the channel
+        // with reason="completed". Callers therefore observe
+        // TaskState.Status === TaskFailed (msgderive extracts the
+        // embedded `error` field), not TaskSucceeded, even though
+        // close_reason is technically "completed".
+        await this.opts.client.messages.send({
+            conversationId: req.channelId,
             type: "agent_reply",
-            payload: {
+            replyTo: req.inboundMessageId,
+            content: {
                 session_key: req.sessionKey,
                 error: "agent_busy",
+                error_code: "agent_busy",
                 text: "device-agent is processing another request — please retry once it completes.",
             },
-            inReplyTo: req.inboundMessageId,
         });
     }
 }

package/dist/plugins/message-bus/busy-reply.js.map

@@ -1 +1 @@
-{"version":3,"file":"busy-reply.js","sourceRoot":"","sources":["../../../src/plugins/message-bus/busy-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwBH,MAAM,OAAO,0BAA0B;IACR;IAA7B,YAA6B,IAA6B;QAA7B,SAAI,GAAJ,IAAI,CAAyB;IAAG,CAAC;IAE9D,KAAK,CAAC,SAAS,CAAC,GAAqB;QACnC,oEAAoE;QACpE,mEAAmE;QACnE,mEAAmE;QACnE,2DAA2D;QAC3D,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,SAAS,EAAE;YACpD,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE;gBACP,WAAW,EAAE,GAAG,CAAC,UAAU;gBAC3B,KAAK,EAAE,YAAY;gBACnB,IAAI,EAAE,8EAA8E;aACrF;YACD,SAAS,EAAE,GAAG,CAAC,gBAAgB;SAChC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"busy-reply.js","sourceRoot":"","sources":["../../../src/plugins/message-bus/busy-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwBH,MAAM,OAAO,6BAA6B;IACX;IAA7B,YAA6B,IAA6B;QAA7B,SAAI,GAAJ,IAAI,CAAyB;IAAG,CAAC;IAE9D,KAAK,CAAC,SAAS,CAAC,GAAqB;QACnC,mEAAmE;QACnE,mEAAmE;QACnE,wDAAwD;QACxD,EAAE;QACF,qFAAqF;QACrF,wDAAwD;QACxD,+DAA+D;QAC/D,+DAA+D;QAC/D,iEAAiE;QACjE,gEAAgE;QAChE,8DAA8D;QAC9D,+DAA+D;QAC/D,gEAAgE;QAChE,iEAAiE;QACjE,gDAAgD;QAChD,2DAA2D;QAC3D,EAAE;QACF,6CAA6C;QAC7C,iEAAiE;QACjE,qDAAqD;QACrD,0DAA0D;QAC1D,0DAA0D;QAC1D,2CAA2C;QAC3C,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YACnC,cAAc,EAAE,GAAG,CAAC,SAAS;YAC7B,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,GAAG,CAAC,gBAAgB;YAC7B,OAAO,EAAE;gBACP,WAAW,EAAE,GAAG,CAAC,UAAU;gBAC3B,KAAK,EAAE,YAAY;gBACnB,UAAU,EAAE,YAAY;gBACxB,IAAI,EAAE,8EAA8E;aACrF;SACF,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/plugins/message-bus/cancel.d.ts

@@ -1,7 +1,7 @@
 /**
- * Inbound — `chat_cancel` envelope handler.
+ * Inbound — `chat_cancel` message handler.
  *
- * The BeeOS platform pushes a protocol-agnostic `chat_cancel` envelope
+ * The BeeOS platform pushes a protocol-agnostic `chat_cancel` message
  * onto the agent's personal Centrifugo channel when an in-flight
  * `chat_message` turn must be aborted. Triggers include:
  *
@@ -10,7 +10,7 @@
  *     disconnect / deadline)
  *   - A2A Service timeout sweeper (task exceeded `timeout_ms`)
  *
- * The wire payload (see `backend/pkg/convmsg/extract.go`
+ * The wire content (see `backend/pkg/convmsg/extract.go`
  * `MessageTypeChatCancel`) carries IM primitives only:
  *
  *   {
@@ -28,14 +28,8 @@
  * globally — so resolving by inboundMessageId is unambiguous (either
  * the current turn is THIS turn, or the cancel is for a stale /
  * already-completed turn we should silently drop).
- *
- * No-ops:
- *   - missing / non-string `target_message_id`         → drop, debug log
- *   - tracker has no entry for that message_id         → drop, debug log
- *     (the turn already finished, or this is a stray cancel for a
- *     different agent on a shared principal — both safe to ignore)
  */
-import type { MessageEnvelope } from "@beeos-ai/message-sdk";
+import type { Message } from "@beeos-ai/message-sdk";
 import type { SessionManager } from "../../app/session-manager.js";
 import type { Logger } from "../../logger/index.js";
 import type { MsInflightTracker } from "./ms-inflight-tracker.js";
@@ -45,4 +39,4 @@ export interface MessageBusCancelHandlerOptions {
     tracker: MsInflightTracker;
     logger: Logger;
 }
-export declare function buildMessageBusCancelHandler(opts: MessageBusCancelHandlerOptions): (envelope: MessageEnvelope) => Promise<void>;
+export declare function buildMessageBusCancelHandler(opts: MessageBusCancelHandlerOptions): (msg: Message) => Promise<void>;

package/dist/plugins/message-bus/cancel.js

@@ -1,7 +1,7 @@
 /**
- * Inbound — `chat_cancel` envelope handler.
+ * Inbound — `chat_cancel` message handler.
  *
- * The BeeOS platform pushes a protocol-agnostic `chat_cancel` envelope
+ * The BeeOS platform pushes a protocol-agnostic `chat_cancel` message
  * onto the agent's personal Centrifugo channel when an in-flight
  * `chat_message` turn must be aborted. Triggers include:
  *
@@ -10,7 +10,7 @@
  *     disconnect / deadline)
  *   - A2A Service timeout sweeper (task exceeded `timeout_ms`)
  *
- * The wire payload (see `backend/pkg/convmsg/extract.go`
+ * The wire content (see `backend/pkg/convmsg/extract.go`
  * `MessageTypeChatCancel`) carries IM primitives only:
  *
  *   {
@@ -28,23 +28,17 @@
  * globally — so resolving by inboundMessageId is unambiguous (either
  * the current turn is THIS turn, or the cancel is for a stale /
  * already-completed turn we should silently drop).
- *
- * No-ops:
- *   - missing / non-string `target_message_id`         → drop, debug log
- *   - tracker has no entry for that message_id         → drop, debug log
- *     (the turn already finished, or this is a stray cancel for a
- *     different agent on a shared principal — both safe to ignore)
  */
 export const MESSAGE_TYPE_CHAT_CANCEL = "chat_cancel";
 export function buildMessageBusCancelHandler(opts) {
-    return async (envelope) => {
-        const payload = (envelope.payload ?? {});
-        const targetMessageId = pickString(payload.target_message_id);
+    return async (msg) => {
+        const content = (msg.content ?? {});
+        const targetMessageId = pickString(content.target_message_id);
         if (!targetMessageId) {
-            opts.logger.debug({ type: envelope.type, message_id: envelope.message_id }, "message-bus: chat_cancel dropped (no target_message_id)");
+            opts.logger.debug({ type: msg.type, message_id: msg.id }, "message-bus: chat_cancel dropped (no target_message_id)");
             return;
         }
-        const reason = pickString(payload.reason) || "unknown";
+        const reason = pickString(content.reason) || "unknown";
         const entry = opts.tracker.findByInboundMessageId(targetMessageId);
         if (!entry) {
             opts.logger.debug({ targetMessageId, reason }, "message-bus: chat_cancel for unknown / already-finished turn — no-op");

package/dist/plugins/message-bus/cancel.js.map

@@ -1 +1 @@
-{"version":3,"file":"cancel.js","sourceRoot":"","sources":["../../../src/plugins/message-bus/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AASH,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAC;AAQtD,MAAM,UAAU,4BAA4B,CAC1C,IAAoC;IAEpC,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAA4B,CAAC;QACpE,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC9D,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,EACxD,yDAAyD,CAC1D,CAAC;YACF,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC;QAEvD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,eAAe,CAAC,CAAC;QACnE,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,eAAe,EAAE,MAAM,EAAE,EAC3B,sEAAsE,CACvE,CAAC;YACF,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,IAAI,CACd;YACE,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,eAAe;YACf,MAAM;YACN,SAAS;SACV,EACD,6DAA6D,CAC9D,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,CAAU;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC"}
+{"version":3,"file":"cancel.js","sourceRoot":"","sources":["../../../src/plugins/message-bus/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAC;AAQtD,MAAM,UAAU,4BAA4B,CAC1C,IAAoC;IAEpC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAA4B,CAAC;QAC/D,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC9D,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,EAAE,EACtC,yDAAyD,CAC1D,CAAC;YACF,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC;QAEvD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,eAAe,CAAC,CAAC;QACnE,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,EAAE,eAAe,EAAE,MAAM,EAAE,EAC3B,sEAAsE,CACvE,CAAC;YACF,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,IAAI,CACd;YACE,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,eAAe;YACf,MAAM;YACN,SAAS;SACV,EACD,6DAA6D,CAC9D,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,CAAU;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/plugins/message-bus/inbound.d.ts

@@ -1,21 +1,21 @@
 /**
- * Inbound — `chat_message` / `agent_request` envelope handler.
+ * Inbound — `chat_message` / `agent_request` handler.
  *
- * v0.9.0 — wires `MessageSDK.onMessage(...)` directly to
+ * Wires `client.on("message", ...)` to
  * `SessionManager.promptForSession(sid, prompt)`. Per-channel session
  * isolation:
  *
  *   1. Extract `{ message, channelId, messageId, contextId, sessionKey,
- *      files }` from the payload via `extractChatPrompt` (returns null
- *      on malformed envelopes — silently dropped).
+ *      files }` from the v2 `Message` via `extractChatPrompt`
+ *      (returns null on malformed messages — silently dropped).
  *   2. Reject if no `channelId` or no `messageId` — replies must round
- *      trip through `ch:{channelId}` with `in_reply_to=messageId`, so
+ *      trip through `ch:{conversationId}` with `replyTo=messageId`, so
  *      neither is optional.
  *   3. Layer 3 in-flight gate: if `sessionManager.isTurnInFlight()`
  *      returns true, send a busy-reply on the inbound channel and
  *      return. The agent serialises every prompt through a single
  *      physical device, so concurrent requests are rejected (not
- *      queued) — matches v0.8.0 contract.
+ *      queued).
  *   4. Resolve the per-channel sid from `sessionKey` (the SDK already
  *      computed `agent:{id}:invoke:ctx-{contextId}` /
  *      `:ch-{channelId}`). Bind a fresh `MsChannelNotifier` to that
@@ -24,28 +24,20 @@
  *      `files.length > 0`) and call
  *      `sessionManager.promptForSession(sid, promptText)`.
  *   6. The notifier translates streaming session/update envelopes into
- *      MS wire envelopes (`agent_reply_delta`, terminal `agent_reply`)
+ *      MS messages (`agent_reply_delta`, terminal `agent_reply`)
  *      automatically — no separate outbound listener needed.
  *   7. ALWAYS unbind the notifier on completion (success / error /
  *      cancellation) so the next turn on the same channel gets a fresh
  *      notifier with `accumulatedText = ""`.
- *
- * Defensive paths:
- *   - If `promptForSession` rejects with `"agent_busy"` (extremely
- *     rare race after the explicit `isTurnInFlight` check), fall
- *     through to the busy-reply path so the caller's `/wait` doesn't
- *     hang.
- *   - For any other thrown error, publish a terminal `agent_reply`
- *     with `error` set so callers see a definite outcome.
  */
-import { type MessageEnvelope, type MessageSDK } from "@beeos-ai/message-sdk";
+import type { Message, MessageClient } from "@beeos-ai/message-sdk";
 import type { SessionManager } from "../../app/session-manager.js";
 import type { Logger } from "../../logger/index.js";
 import type { BusyReplyHandler } from "./busy-reply.js";
 import type { MsInflightTracker } from "./ms-inflight-tracker.js";
 export interface MessageBusInboundOptions {
     sessionManager: SessionManager;
-    sdk: MessageSDK;
+    client: MessageClient;
     busyReply: BusyReplyHandler;
     tracker: MsInflightTracker;
     logger: Logger;
@@ -56,16 +48,17 @@ export interface MessageBusInboundOptions {
      */
     localAgentId?: string;
     /**
-     * Source tag passed to `extractChatPrompt`. Identifies which Centrifugo
-     * envelope type triggered the call — `chat_message` is the primary L0
-     * path, `agent_request` is the legacy A2A SendTask shim.
+     * Source tag passed to `extractChatPrompt`. Identifies which message
+     * type triggered the call — `chat_message` is the primary L0 path,
+     * `agent_request` is the legacy A2A SendTask shim.
      */
     source: "chat_message" | "agent_request";
 }
 /**
- * Build the per-envelope handler. The returned function is what gets
- * registered with `sdk.onMessage(type, handler)` — keeping the factory
- * shape lets unit tests instantiate the closure with mock collaborators
- * and feed envelopes synchronously.
+ * Build the per-message handler. The returned function is what gets
+ * dispatched from the `client.on("message", ...)` listener after a
+ * type-filter check — keeping the factory shape lets unit tests
+ * instantiate the closure with mock collaborators and feed messages
+ * synchronously.
  */
-export declare function buildMessageBusInboundHandler(opts: MessageBusInboundOptions): (envelope: MessageEnvelope) => Promise<void>;
+export declare function buildMessageBusInboundHandler(opts: MessageBusInboundOptions): (msg: Message) => Promise<void>;

package/dist/plugins/message-bus/inbound.js

@@ -1,21 +1,21 @@
 /**
- * Inbound — `chat_message` / `agent_request` envelope handler.
+ * Inbound — `chat_message` / `agent_request` handler.
  *
- * v0.9.0 — wires `MessageSDK.onMessage(...)` directly to
+ * Wires `client.on("message", ...)` to
  * `SessionManager.promptForSession(sid, prompt)`. Per-channel session
  * isolation:
  *
  *   1. Extract `{ message, channelId, messageId, contextId, sessionKey,
- *      files }` from the payload via `extractChatPrompt` (returns null
- *      on malformed envelopes — silently dropped).
+ *      files }` from the v2 `Message` via `extractChatPrompt`
+ *      (returns null on malformed messages — silently dropped).
  *   2. Reject if no `channelId` or no `messageId` — replies must round
- *      trip through `ch:{channelId}` with `in_reply_to=messageId`, so
+ *      trip through `ch:{conversationId}` with `replyTo=messageId`, so
  *      neither is optional.
  *   3. Layer 3 in-flight gate: if `sessionManager.isTurnInFlight()`
  *      returns true, send a busy-reply on the inbound channel and
  *      return. The agent serialises every prompt through a single
  *      physical device, so concurrent requests are rejected (not
- *      queued) — matches v0.8.0 contract.
+ *      queued).
  *   4. Resolve the per-channel sid from `sessionKey` (the SDK already
  *      computed `agent:{id}:invoke:ctx-{contextId}` /
  *      `:ch-{channelId}`). Bind a fresh `MsChannelNotifier` to that
@@ -24,50 +24,39 @@
  *      `files.length > 0`) and call
  *      `sessionManager.promptForSession(sid, promptText)`.
  *   6. The notifier translates streaming session/update envelopes into
- *      MS wire envelopes (`agent_reply_delta`, terminal `agent_reply`)
+ *      MS messages (`agent_reply_delta`, terminal `agent_reply`)
  *      automatically — no separate outbound listener needed.
  *   7. ALWAYS unbind the notifier on completion (success / error /
  *      cancellation) so the next turn on the same channel gets a fresh
  *      notifier with `accumulatedText = ""`.
- *
- * Defensive paths:
- *   - If `promptForSession` rejects with `"agent_busy"` (extremely
- *     rare race after the explicit `isTurnInFlight` check), fall
- *     through to the busy-reply path so the caller's `/wait` doesn't
- *     hang.
- *   - For any other thrown error, publish a terminal `agent_reply`
- *     with `error` set so callers see a definite outcome.
  */
-import { extractChatPrompt, } from "@beeos-ai/message-sdk";
+import { extractChatPrompt } from "@beeos-ai/message-sdk/chat-envelope";
 import { MsChannelNotifier } from "./ms-channel-notifier.js";
 /**
- * Build the per-envelope handler. The returned function is what gets
- * registered with `sdk.onMessage(type, handler)` — keeping the factory
- * shape lets unit tests instantiate the closure with mock collaborators
- * and feed envelopes synchronously.
+ * Build the per-message handler. The returned function is what gets
+ * dispatched from the `client.on("message", ...)` listener after a
+ * type-filter check — keeping the factory shape lets unit tests
+ * instantiate the closure with mock collaborators and feed messages
+ * synchronously.
  */
 export function buildMessageBusInboundHandler(opts) {
-    return async (envelope) => {
-        const prompt = extractChatPrompt(envelope, {
+    return async (msg) => {
+        const prompt = extractChatPrompt(msg, {
             source: opts.source,
             localAgentId: opts.localAgentId ?? "",
         });
         if (!prompt) {
-            opts.logger.warn({ type: envelope.type, message_id: envelope.message_id }, "message-bus: dropped envelope (no prompt could be extracted)");
+            opts.logger.warn({ type: msg.type, message_id: msg.id }, "message-bus: dropped message (no prompt could be extracted)");
             return;
         }
         if (!prompt.channelId || !prompt.messageId) {
             opts.logger.warn({
-                type: envelope.type,
+                type: msg.type,
                 hasChannelId: !!prompt.channelId,
                 hasMessageId: !!prompt.messageId,
-            }, "message-bus: dropped envelope (missing channelId or messageId — cannot correlate reply)");
+            }, "message-bus: dropped message (missing channelId or messageId — cannot correlate reply)");
             return;
         }
-        // Layer 3 — physical-device-serial gate. The agent has ONE device
-        // and ONE in-flight task slot. Concurrent invocations get an
-        // `agent_busy` reply so callers can retry instead of hanging on
-        // /wait.
         if (opts.sessionManager.isTurnInFlight()) {
             opts.logger.warn({
                 incomingMessageId: prompt.messageId,
@@ -80,14 +69,9 @@ export function buildMessageBusInboundHandler(opts) {
             });
             return;
         }
-        // Per-channel session anchor. `sessionKey` is the canonical id —
-        // multiple chat_message envelopes carrying the same `context_id`
-        // (or `channel_id` fallback) flow into the same sid, so the
-        // history-injection preamble in `_executePrompt` can stitch them
-        // into a continuous conversation.
         const sid = prompt.sessionKey;
         const notifier = new MsChannelNotifier({
-            sdk: opts.sdk,
+            client: opts.client,
             channelId: prompt.channelId,
             inboundMessageId: prompt.messageId,
             sessionKey: prompt.sessionKey,
@@ -125,9 +109,6 @@ export function buildMessageBusInboundHandler(opts) {
                 inboundMessageId: prompt.messageId,
                 err: message,
             }, "message-bus: promptForSession rejected — emitting fallback reply");
-            // If the notifier already published the terminal `agent_reply`
-            // (normal stream_complete path) the second publish is harmless
-            // because the notifier guards on `finalized`.
             if (message === "agent_busy") {
                 await opts.busyReply.replyBusy({
                     channelId: prompt.channelId,
@@ -136,19 +117,16 @@ export function buildMessageBusInboundHandler(opts) {
                 });
             }
             else if (!notifier.isFinalized) {
-                // Surface the error as a terminal agent_reply so callers see
-                // a definite outcome instead of a /wait timeout. Use durable
-                // sendChannelMessage (same path as MsChannelNotifier.publishFinal)
-                // so caller's /wait can match via DB even if it's mid-reconnect.
                 try {
-                    await opts.sdk.sendChannelMessage(prompt.channelId, {
+                    await opts.client.messages.send({
+                        conversationId: prompt.channelId,
                         type: "agent_reply",
-                        payload: {
+                        replyTo: prompt.messageId,
+                        content: {
                             session_key: prompt.sessionKey,
                             error: message,
                             text: notifier.currentText,
                         },
-                        inReplyTo: prompt.messageId,
                     });
                 }
                 catch (publishErr) {
@@ -167,16 +145,6 @@ export function buildMessageBusInboundHandler(opts) {
         }
     };
 }
-/**
- * Append a markdown-style `[attachments]` block listing file URLs to
- * the prompt text. KISS: today the device-agent agent-core only takes
- * a single string prompt, so the only way to surface attachments is
- * inline. Empty `files` returns the message unchanged.
- *
- * Deeper integration (downloading via the resource-resolution layer,
- * uploading to the device sandbox) is intentionally out of scope —
- * see plan §E.
- */
 function appendAttachments(message, files) {
     if (!files || files.length === 0)
         return message;

package/dist/plugins/message-bus/inbound.js.map

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

package/dist/plugins/message-bus/index.d.ts

@@ -2,33 +2,32 @@
  * Plugin — message-bus.
  *
  * Subscribes the device-agent to the BeeOS Message Service so it can
- * receive `chat_message` envelopes from L0 / A2A / MCP / OpenAPI
- * invocations and reply over `ch:{channelId}` with `agent_reply` /
- * `agent_reply_delta` (in_reply_to = original message_id).
+ * receive `chat_message` messages from L0 / A2A / MCP / OpenAPI
+ * invocations and reply over `ch:{conversationId}` with `agent_reply` /
+ * `agent_reply_delta` (replyTo = original message_id).
  *
- * Disabled by default — opt in by setting `BEEOS_MESSAGE_BUS_ENABLED=true`
- * (or `--message-bus`) AND providing both `--agent-gateway-url` and
- * an Ed25519 identity. Without those the plugin logs a one-line warning
- * during `start()` and stays disabled — the rest of the agent (Bridge
- * ACP, HTTP debug) still runs.
+ * Enabled by default since v0.9.7. Opt out with
+ * `BEEOS_MESSAGE_BUS_ENABLED=false` or `--no-message-bus`. Even when
+ * enabled, the plugin requires BOTH `--agent-gateway-url` and an
+ * Ed25519 identity to actually connect; missing either, it logs a
+ * one-line warning during `start()` and stays dormant — the rest of
+ * the agent (Bridge ACP, HTTP debug) still runs.
  *
  * Lifecycle:
  *   - `init` — read config, decide enabled / disabled.
  *   - `start` — kick off the connect loop. Returns IMMEDIATELY (does
  *     not block bootstrap on the network). The first connect attempt
  *     and any subsequent retries run in the background.
- *   - `stop` — cancel any pending retry, disconnect SDK, unsubscribe
- *     outbound listener, drop in-flight register.
+ *   - `stop` — cancel any pending retry, disconnect client, drop
+ *     in-flight register.
  *
  * Failure mode: if `tokenProvider()` rejects (e.g. the device instance
  * has not been provisioned with `agentPublicKey` yet), the plugin
  * schedules a retry with exponential backoff (30s → 60s → 120s → 240s,
  * capped at 300s) and keeps trying forever until either `connect`
- * succeeds or `stop()` cancels the loop. This mirrors beeos-claw's
- * `localServer.onceAgentMappingReady(...)` deferred-connect pattern —
- * see `[index.ts:484-498](agents/beeos-claw/src/index.ts)`.
+ * succeeds or `stop()` cancels the loop.
  */
-import { MessageSDK, type TokenProvider } from "@beeos-ai/message-sdk";
+import { MessageClient, type TokenProvider } from "@beeos-ai/message-sdk";
 import type { Logger } from "../../logger/index.js";
 import type { AgentPlugin, PluginContext } from "../../ports/plugin.js";
 /**
@@ -51,11 +50,11 @@ export interface MessageBusPluginOptions {
         privateKey: Uint8Array;
     };
     /**
-     * Override the SDK constructor — used by tests to inject a fake
-     * MessageSDK whose `connect` / `onMessage` / `sendToChannel` are
-     * spies. Production code leaves this `undefined`.
+     * Override the client constructor — used by tests to inject a fake
+     * MessageClient whose `connect` / `on` / `messages.send` are spies.
+     * Production code leaves this `undefined`.
      */
-    sdkFactory?: (logger: Logger) => MessageSDK;
+    clientFactory?: (logger: Logger) => MessageClient;
     /**
      * Override the token provider builder — used by tests to skip the
      * real Agent Gateway round-trip.
@@ -81,8 +80,7 @@ export interface MessageBusPluginOptions {
     retrySchedule?: readonly number[];
     /**
      * Test seam — `setTimeout` / `clearTimeout` shim. Defaults to
-     * the global `setTimeout` family. Tests inject a deterministic
-     * scheduler so they don't need real timers.
+     * the global `setTimeout` family.
      */
     scheduler?: {
         setTimeout: (cb: () => void, ms: number) => unknown;
@@ -93,7 +91,7 @@ export declare class MessageBusPlugin implements AgentPlugin {
     private readonly opts;
     readonly name = "message-bus";
     private ctx?;
-    private sdk;
+    private client;
     private tracker;
     private resolvedPrincipalId;
     private stopped;
@@ -108,38 +106,21 @@ export declare class MessageBusPlugin implements AgentPlugin {
     start(): Promise<void>;
     stop(): Promise<void>;
     get principalId(): string;
-    /**
-     * Test helper — resolves once `start()`'s connect loop has either
-     * successfully connected or `stop()` was called. Production code
-     * never needs this.
-     */
     whenSettled(): Promise<void>;
     private runConnectLoop;
     /**
-     * Single connect attempt. Returns `true` on success (sdk connected,
-     * handlers + listener installed) and `false` on any failure (caller
-     * should schedule a retry).
+     * Single connect attempt. Returns `true` on success, `false` on any
+     * failure (caller should schedule a retry).
      *
-     * Each attempt builds a FRESH `MessageSDK` instance — re-using one
-     * across reconnects would carry stale handlers and confuse the
-     * centrifuge-js internal state. The SDK has its own internal
-     * reconnect once `.connect()` succeeds; this loop is for the OPENING
-     * handshake only.
+     * Each attempt builds a FRESH `MessageClient` — re-using one across
+     * reconnects would carry stale handlers and confuse centrifuge-js
+     * internal state. The client has its own internal reconnect once
+     * `.connect()` succeeds; this loop is for the OPENING handshake only.
      */
     private tryConnectOnce;
     private nextDelayMs;
-    /**
-     * Log an attempt failure with attenuated severity — first attempt
-     * + a few well-spaced retries get a `warn`, the rest are `debug` to
-     * avoid log spam when an instance has never been provisioned.
-     */
     private logAttemptFailure;
     private logRetryScheduled;
-    /**
-     * Sleep `ms` milliseconds. Returns `true` when stop() cancels the
-     * timer mid-flight (so the caller breaks out of its loop), or
-     * `false` once the timer fires normally.
-     */
     private sleep;
     private cancelPendingRetry;
     private scheduler;