@beeos-ai/device-agent 0.7.2 → 0.9.1

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

@@ -0,0 +1,180 @@
+/**
+ * Inbound — `chat_message` / `agent_request` envelope handler.
+ *
+ * v0.9.0 — wires `MessageSDK.onMessage(...)` directly 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).
+ *   2. Reject if no `channelId` or no `messageId` — replies must round
+ *      trip through `ch:{channelId}` with `in_reply_to=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.
+ *   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
+ *      sid for the duration of the turn.
+ *   5. Build the prompt (text + a minimal `[attachments]` block when
+ *      `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`)
+ *      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 { 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.
+ */
+export function buildMessageBusInboundHandler(opts) {
+    return async (envelope) => {
+        const prompt = extractChatPrompt(envelope, {
+            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)");
+            return;
+        }
+        if (!prompt.channelId || !prompt.messageId) {
+            opts.logger.warn({
+                type: envelope.type,
+                hasChannelId: !!prompt.channelId,
+                hasMessageId: !!prompt.messageId,
+            }, "message-bus: dropped envelope (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,
+                incomingChannelId: prompt.channelId,
+            }, "message-bus: agent busy — sending agent_busy reply");
+            await opts.busyReply.replyBusy({
+                channelId: prompt.channelId,
+                inboundMessageId: prompt.messageId,
+                sessionKey: prompt.sessionKey,
+            });
+            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,
+            channelId: prompt.channelId,
+            inboundMessageId: prompt.messageId,
+            sessionKey: prompt.sessionKey,
+            logger: opts.logger,
+        });
+        opts.sessionManager.bindNotifier(sid, notifier);
+        opts.tracker.set({
+            messageId: prompt.messageId,
+            channelId: prompt.channelId,
+            sid,
+        });
+        const promptText = appendAttachments(prompt.message, prompt.files);
+        opts.logger.info({
+            sid,
+            channelId: prompt.channelId,
+            inboundMessageId: prompt.messageId,
+            contextId: prompt.contextId,
+            sessionKey: prompt.sessionKey,
+            files: prompt.files.length,
+        }, "message-bus: turn started");
+        try {
+            const result = await opts.sessionManager.promptForSession(sid, promptText);
+            opts.logger.info({
+                sid,
+                channelId: prompt.channelId,
+                inboundMessageId: prompt.messageId,
+                stopReason: result.stopReason,
+            }, "message-bus: turn finished");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            opts.logger.warn({
+                sid,
+                channelId: prompt.channelId,
+                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,
+                    inboundMessageId: prompt.messageId,
+                    sessionKey: prompt.sessionKey,
+                });
+            }
+            else if (!notifier.isFinalized) {
+                // Surface the error as a terminal agent_reply so callers see
+                // a definite outcome instead of a /wait timeout.
+                try {
+                    await opts.sdk.sendToChannel(prompt.channelId, "agent_reply", {
+                        session_key: prompt.sessionKey,
+                        error: message,
+                        text: notifier.currentText,
+                    }, { inReplyTo: prompt.messageId });
+                }
+                catch (publishErr) {
+                    opts.logger.error({
+                        err: publishErr instanceof Error
+                            ? publishErr.message
+                            : String(publishErr),
+                        channelId: prompt.channelId,
+                    }, "message-bus: failed to publish fallback agent_reply");
+                }
+            }
+        }
+        finally {
+            opts.sessionManager.unbindNotifier(sid);
+            opts.tracker.clear(prompt.messageId);
+        }
+    };
+}
+/**
+ * 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;
+    const list = files.map((u) => `- ${u}`).join("\n");
+    return `${message}\n\n[attachments]\n${list}`;
+}
+//# sourceMappingURL=inbound.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,146 @@
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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)`.
+ */
+import { MessageSDK, type TokenProvider } from "@beeos-ai/message-sdk";
+import type { Logger } from "../../logger/index.js";
+import type { AgentPlugin, PluginContext } from "../../ports/plugin.js";
+/**
+ * Backoff schedule for token / connect failures (milliseconds). Each
+ * entry is the delay BEFORE the next retry. The last entry caps the
+ * delay; once we hit the cap we keep retrying forever at that interval.
+ *
+ * Tunable via `MessageBusPluginOptions.retrySchedule` — tests pin a
+ * tighter schedule (e.g. `[5, 5, 5]`) to keep `vi.useFakeTimers()`
+ * runs cheap.
+ */
+export declare const DEFAULT_RETRY_SCHEDULE_MS: readonly number[];
+export interface MessageBusPluginOptions {
+    /**
+     * Ed25519 keypair used to sign `POST /api/v1/messaging/token`. When
+     * absent the plugin self-disables.
+     */
+    keypair?: {
+        publicKey: Uint8Array;
+        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`.
+     */
+    sdkFactory?: (logger: Logger) => MessageSDK;
+    /**
+     * Override the token provider builder — used by tests to skip the
+     * real Agent Gateway round-trip.
+     */
+    tokenProviderFactory?: (opts: {
+        agentGatewayUrl: string;
+        keypair: {
+            publicKey: Uint8Array;
+            privateKey: Uint8Array;
+        };
+    }) => TokenProvider;
+    /**
+     * Local agent identity surfaced into `extractChatPrompt` for
+     * sessionKey prefixing. Defaults to the empty string — fine for the
+     * single-session-multiplex topology.
+     */
+    localAgentId?: string;
+    /**
+     * Override the retry backoff schedule (ms). Defaults to
+     * `DEFAULT_RETRY_SCHEDULE_MS`. Tests pass small numbers; production
+     * leaves it `undefined`.
+     */
+    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.
+     */
+    scheduler?: {
+        setTimeout: (cb: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+    };
+}
+export declare class MessageBusPlugin implements AgentPlugin {
+    private readonly opts;
+    readonly name = "message-bus";
+    private ctx?;
+    private sdk;
+    private tracker;
+    private resolvedPrincipalId;
+    private stopped;
+    private retryHandle;
+    private retryResolve;
+    private connectAttempt;
+    private legacyDeprecationLogged;
+    private connectSettled;
+    private resolveConnectSettled;
+    constructor(opts?: MessageBusPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    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).
+     *
+     * 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.
+     */
+    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;
+}