@beeos-ai/device-agent 0.7.2 → 0.9.1

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

@@ -0,0 +1,382 @@
+/**
+ * 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 } from "@beeos-ai/message-sdk";
+import { createDeviceMessagingTokenProvider } from "../../messaging/token-provider.js";
+import { MessageSdkBusyReplyHandler } from "./busy-reply.js";
+import { buildMessageBusCancelHandler, MESSAGE_TYPE_CHAT_CANCEL, } from "./cancel.js";
+import { buildMessageBusInboundHandler } from "./inbound.js";
+import { MsInflightTracker } from "./ms-inflight-tracker.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 const DEFAULT_RETRY_SCHEDULE_MS = Object.freeze([
+    30_000,
+    60_000,
+    120_000,
+    240_000,
+    300_000,
+]);
+/** Attempt indices (1-based) where a `warn` log is preferred over `debug`. */
+const WARN_ATTEMPT_INDICES = new Set([1, 3, 5, 10]);
+export class MessageBusPlugin {
+    opts;
+    name = "message-bus";
+    ctx;
+    sdk = null;
+    tracker = null;
+    resolvedPrincipalId = "";
+    // Connect-loop state.
+    stopped = false;
+    retryHandle = null;
+    // When the loop is sleeping in `sleep(ms)`, this resolver lets
+    // `stop()` (or any other test-level cancel) wake it up early with
+    // `cancelled = true`. Always cleared back to `null` once the resolver
+    // fires.
+    retryResolve = null;
+    connectAttempt = 0;
+    legacyDeprecationLogged = false;
+    // Resolves once the plugin has either successfully connected OR is
+    // permanently disabled. Tests await this to avoid racing the
+    // background loop. Production callers ignore it.
+    connectSettled = Promise.resolve();
+    resolveConnectSettled = () => undefined;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async init(ctx) {
+        this.ctx = ctx;
+        if (!ctx.config.messageBus?.enabled) {
+            ctx.log.info("message-bus: disabled (set BEEOS_MESSAGE_BUS_ENABLED=true or --message-bus to enable)");
+            return;
+        }
+        if (!this.opts.keypair) {
+            ctx.log.warn("message-bus: enabled but no Ed25519 identity available — stays disabled");
+            return;
+        }
+        if (!ctx.config.agentGatewayUrl) {
+            ctx.log.warn("message-bus: enabled but no agentGatewayUrl configured — stays disabled");
+            return;
+        }
+    }
+    async start() {
+        const ctx = this.ctx;
+        if (!ctx)
+            return;
+        if (!ctx.config.messageBus?.enabled)
+            return;
+        if (!this.opts.keypair)
+            return;
+        if (!ctx.config.agentGatewayUrl)
+            return;
+        this.connectSettled = new Promise((resolve) => {
+            this.resolveConnectSettled = resolve;
+        });
+        // Kick off the loop. Do NOT await — the bootstrap should not block
+        // on a remote handshake. The loop reschedules itself via setTimeout
+        // until either `tryConnectOnce` returns true or `stop()` is called.
+        void this.runConnectLoop();
+    }
+    async stop() {
+        this.stopped = true;
+        this.cancelPendingRetry();
+        // Resolve any outstanding waiter so test code that awaits
+        // `whenSettled()` does not hang past stop().
+        this.resolveConnectSettled();
+        if (this.sdk) {
+            try {
+                await this.sdk.disconnect();
+            }
+            catch (err) {
+                this.ctx?.log.warn({ err: err instanceof Error ? err.message : String(err) }, "message-bus: disconnect failed");
+            }
+            this.sdk = null;
+        }
+        if (this.tracker) {
+            this.tracker.reset();
+            this.tracker = null;
+        }
+    }
+    // Test seam — exposes the resolved principal so integration tests can
+    // assert what the plugin actually subscribed to without poking at
+    // private state.
+    get principalId() {
+        return this.resolvedPrincipalId;
+    }
+    /**
+     * Test helper — resolves once `start()`'s connect loop has either
+     * successfully connected or `stop()` was called. Production code
+     * never needs this.
+     */
+    whenSettled() {
+        return this.connectSettled;
+    }
+    // ── Internals ──────────────────────────────────────────────────────────
+    async runConnectLoop() {
+        const ctx = this.ctx;
+        const log = ctx.log;
+        while (!this.stopped) {
+            this.connectAttempt += 1;
+            const ok = await this.tryConnectOnce(this.connectAttempt);
+            if (ok) {
+                this.resolveConnectSettled();
+                return;
+            }
+            if (this.stopped) {
+                this.resolveConnectSettled();
+                return;
+            }
+            const delayMs = this.nextDelayMs(this.connectAttempt);
+            this.logRetryScheduled(this.connectAttempt, delayMs, log);
+            const cancelled = await this.sleep(delayMs);
+            if (cancelled) {
+                this.resolveConnectSettled();
+                return;
+            }
+        }
+        this.resolveConnectSettled();
+    }
+    /**
+     * 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.
+     */
+    async tryConnectOnce(attempt) {
+        const ctx = this.ctx;
+        const log = ctx.log;
+        const keypair = this.opts.keypair;
+        const agentGatewayUrl = ctx.config.agentGatewayUrl;
+        const tokenProvider = this.opts.tokenProviderFactory?.({ agentGatewayUrl, keypair }) ??
+            createDeviceMessagingTokenProvider({ agentGatewayUrl, keypair });
+        const sdk = this.opts.sdkFactory?.(log) ??
+            new MessageSDK({
+                // No serviceUrl — agents talk to MS only via Agent Gateway
+                // proxy + Centrifugo (P6 boundary).
+                centrifugoUrl: ctx.config.messageBus.centrifugoUrl || undefined,
+            }, wrapLoggerForSdk(log));
+        let tok;
+        try {
+            tok = await tokenProvider(ctx.config.messageBus.principalIdOverride ?? "");
+        }
+        catch (err) {
+            this.logAttemptFailure(attempt, "messaging-token fetch failed", err, log);
+            return false;
+        }
+        const principalId = tok.principal_id;
+        if (!principalId) {
+            this.logAttemptFailure(attempt, "gateway returned empty principal_id", null, log);
+            return false;
+        }
+        const tracker = new MsInflightTracker();
+        const busyReply = new MessageSdkBusyReplyHandler({ sdk });
+        const sessionManager = ctx.sessionManager;
+        const chatHandler = buildMessageBusInboundHandler({
+            sessionManager,
+            sdk,
+            busyReply,
+            tracker,
+            logger: log,
+            localAgentId: this.opts.localAgentId,
+            source: "chat_message",
+        });
+        const legacyHandler = buildMessageBusInboundHandler({
+            sessionManager,
+            sdk,
+            busyReply,
+            tracker,
+            logger: log,
+            localAgentId: this.opts.localAgentId,
+            source: "agent_request",
+        });
+        sdk.onMessage("chat_message", async (env) => chatHandler(env));
+        // Gap F — fire a one-shot deprecation warn the FIRST time a legacy
+        // `agent_request` envelope arrives. Mirrors beeos-claw
+        // [`index.ts:551-557`](agents/beeos-claw/src/index.ts).
+        sdk.onMessage("agent_request", async (env) => {
+            if (!this.legacyDeprecationLogged) {
+                this.legacyDeprecationLogged = true;
+                log.warn({}, "message-bus: received legacy 'agent_request' envelope — this path is deprecated; please migrate upstream callers to 'chat_message' (L0 AgentInvocationService)");
+            }
+            await legacyHandler(env);
+        });
+        // Cooperative cancel: the platform pushes `chat_cancel` envelopes
+        // when the caller hangs up / explicitly cancels / times out. We
+        // address the in-flight turn IM-natively by `target_message_id`
+        // (== inbound chat_message.message_id) so the agent stays free of
+        // A2A / MCP / OpenAPI protocol knowledge.
+        const cancelHandler = buildMessageBusCancelHandler({
+            sessionManager,
+            tracker,
+            logger: log,
+        });
+        sdk.onMessage(MESSAGE_TYPE_CHAT_CANCEL, async (env) => cancelHandler(env));
+        sdk.onceConnected(() => {
+            log.info({
+                principalId,
+                centrifugoUrl: tok.centrifugo_url,
+                channels: tok.channels,
+                attempt,
+            }, "message-bus: connected");
+        });
+        try {
+            await sdk.connect(principalId, {
+                centrifugoUrl: tok.centrifugo_url,
+                tokenProvider,
+            });
+        }
+        catch (err) {
+            // Disconnect the half-opened SDK so the next retry starts clean.
+            try {
+                await sdk.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            this.logAttemptFailure(attempt, "Centrifugo connect failed", err, log);
+            return false;
+        }
+        this.sdk = sdk;
+        this.tracker = tracker;
+        this.resolvedPrincipalId = principalId;
+        return true;
+    }
+    nextDelayMs(attempt) {
+        const schedule = this.opts.retrySchedule ?? DEFAULT_RETRY_SCHEDULE_MS;
+        const idx = Math.min(attempt - 1, schedule.length - 1);
+        return schedule[idx];
+    }
+    /**
+     * 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.
+     */
+    logAttemptFailure(attempt, summary, err, log) {
+        const errStr = err == null
+            ? null
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        const fields = { attempt };
+        if (errStr)
+            fields.err = errStr;
+        if (WARN_ATTEMPT_INDICES.has(attempt)) {
+            log.warn(fields, `message-bus: ${summary} — will retry`);
+        }
+        else {
+            log.debug(fields, `message-bus: ${summary} — will retry`);
+        }
+    }
+    logRetryScheduled(attempt, delayMs, log) {
+        if (WARN_ATTEMPT_INDICES.has(attempt)) {
+            log.warn({ attempt, retryInMs: delayMs }, "message-bus: scheduled connect retry");
+        }
+    }
+    /**
+     * 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.
+     */
+    sleep(ms) {
+        const sched = this.scheduler();
+        return new Promise((resolve) => {
+            this.retryResolve = resolve;
+            this.retryHandle = sched.setTimeout(() => {
+                this.retryHandle = null;
+                this.retryResolve = null;
+                resolve(false);
+            }, ms);
+        });
+    }
+    cancelPendingRetry() {
+        if (this.retryHandle == null)
+            return;
+        const sched = this.scheduler();
+        try {
+            sched.clearTimeout(this.retryHandle);
+        }
+        catch {
+            /* ignore */
+        }
+        this.retryHandle = null;
+        const resolve = this.retryResolve;
+        this.retryResolve = null;
+        if (resolve)
+            resolve(true);
+    }
+    scheduler() {
+        return (this.opts.scheduler ?? {
+            setTimeout: (cb, t) => setTimeout(cb, t),
+            clearTimeout: (h) => clearTimeout(h),
+        });
+    }
+}
+/**
+ * Adapt the device-agent pino logger to the MessageSDKLogger shape the
+ * shared SDK expects. The SDK calls `info(msg)` / `warn(msg, fields?)`
+ * with positional args; pino's signature is `(obj, msg)` so we coerce
+ * to a stringly form that prints sanely either way.
+ */
+function wrapLoggerForSdk(log) {
+    return {
+        info: (...args) => log.info(formatSdkArgs(args)),
+        warn: (...args) => log.warn(formatSdkArgs(args)),
+        error: (...args) => log.error(formatSdkArgs(args)),
+        debug: (...args) => log.debug(formatSdkArgs(args)),
+    };
+}
+function formatSdkArgs(args) {
+    return args
+        .map((a) => {
+        if (typeof a === "string")
+            return a;
+        if (a instanceof Error)
+            return a.message;
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(" ");
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/plugins/message-bus/ms-channel-notifier.d.ts

@@ -0,0 +1,101 @@
+/**
+ * MsChannelNotifier — translate per-session ACP `session/update`
+ * envelopes into BeeOS Message Service wire envelopes for ONE
+ * Centrifugo channel (`ch:{channelId}`).
+ *
+ * Implements `SessionUpdateNotifier` so it can be `bindNotifier`'d
+ * to a specific sid in `SessionManager`. The MessageBus inbound
+ * handler creates one of these per `chat_message` envelope, binds
+ * it for the duration of the turn, then unbinds it when the await
+ * for `promptForSession()` returns.
+ *
+ * Wire mapping (locked in to match beeos-claw `acp-server.ts onStreamDelta`):
+ *
+ *   - `agent_message_chunk` → `agent_reply_delta` envelope with
+ *     `update.sessionUpdate=agent_message_chunk`. The text is also
+ *     accumulated into `accumulatedText` so the terminal `agent_reply`
+ *     can carry the full reply as `payload.text`.
+ *
+ *   - `agent_thought_chunk` → `agent_reply_delta` envelope with
+ *     `update.sessionUpdate=agent_thought_chunk`. Reasoning is NEVER
+ *     accumulated — `backend/pkg/convmsg/extract.go::extractNestedDelta`
+ *     intentionally drops thought chunks so they don't pollute reply
+ *     text, and we mirror that here.
+ *
+ *   - `stream_complete` → terminal `agent_reply` envelope. Payload
+ *     shape mirrors beeos-claw:
+ *       success   → { session_key, text }
+ *       cancelled → { session_key, error: "cancelled", text? }
+ *       failure   → { session_key, error, text? }
+ *
+ *   - All other `sessionUpdate` types (`agent_status`, `tool_call`,
+ *     `tool_call_update`, `history_turn`, `system_message_chunk`,
+ *     `user_message_chunk`) are intentionally SKIPPED. The old
+ *     outbound listener also skipped them; mirroring keeps the wire
+ *     format byte-for-byte identical for downstream consumers.
+ *
+ * **Only the terminal `agent_reply`** carries `in_reply_to = inboundMessageId`
+ * so the L0 `/channels/{id}/wait` endpoint can match the reply on the
+ * original `message_id`. Streaming deltas are fan-out only and MUST NOT
+ * carry `in_reply_to` — otherwise MS `/wait` (which only checks
+ * `in_reply_to`, not message type) would short-circuit on the first
+ * delta and the caller would misreport "completed". Mirrors beeos-claw
+ * `acp-server.ts:73-85`.
+ *
+ * The notifier never throws out of `send()` — that runs on the
+ * SessionManager event hot path and a synchronous throw would skip
+ * subsequent handlers (e.g. status:idle). All publish failures are
+ * logged and swallowed. The next event for the same turn will retry
+ * any subsequent publishes via the same path.
+ */
+import type { MessageSDK } from "@beeos-ai/message-sdk";
+import type { SessionUpdateNotifier } from "../../app/session-manager.js";
+import type { Logger } from "../../logger/index.js";
+export interface MsChannelNotifierOptions {
+    sdk: MessageSDK;
+    /** IM channel the reply is published on (`ch:{channelId}`). */
+    channelId: string;
+    /**
+     * Original `chat_message.message_id`. Echoed as `in_reply_to` on
+     * every published envelope so L0 `/wait` can match.
+     */
+    inboundMessageId: string;
+    /**
+     * Stable session anchor (`agent:{id}:invoke:ctx-{contextId}` or
+     * `agent:{id}:invoke:ch-{channelId}`) derived by `extractChatPrompt`.
+     * Embedded as `payload.session_key` for forward-compat parity with
+     * beeos-claw downstream observers.
+     */
+    sessionKey: string;
+    logger: Logger;
+}
+export declare class MsChannelNotifier implements SessionUpdateNotifier {
+    private readonly opts;
+    /** Cumulative `agent_message_chunk` text — populates terminal `agent_reply.text`. */
+    private accumulatedText;
+    private finalized;
+    constructor(opts: MsChannelNotifierOptions);
+    /**
+     * Called by SessionManager for every `session/update` envelope on
+     * this notifier's bound sid. Fire-and-forget: the SessionManager
+     * event hot path is synchronous, so we kick off the publish in the
+     * background and never block.
+     */
+    send(_sessionId: string, update: Record<string, unknown>): void;
+    /**
+     * Cumulative reply text emitted so far. Exposed for diagnostics +
+     * tests; not part of any wire contract.
+     */
+    get currentText(): string;
+    /** True once the terminal `agent_reply` has been published. */
+    get isFinalized(): boolean;
+    private handle;
+    private publishDelta;
+    /**
+     * Emit the terminal `agent_reply`. Idempotent — guarded by
+     * `finalized` so a duplicate `stream_complete` (extremely rare,
+     * but possible if the host event handler ever fires twice) cannot
+     * publish two terminal envelopes.
+     */
+    private publishFinal;
+}

package/dist/plugins/message-bus/ms-channel-notifier.js

@@ -0,0 +1,181 @@
+/**
+ * MsChannelNotifier — translate per-session ACP `session/update`
+ * envelopes into BeeOS Message Service wire envelopes for ONE
+ * Centrifugo channel (`ch:{channelId}`).
+ *
+ * Implements `SessionUpdateNotifier` so it can be `bindNotifier`'d
+ * to a specific sid in `SessionManager`. The MessageBus inbound
+ * handler creates one of these per `chat_message` envelope, binds
+ * it for the duration of the turn, then unbinds it when the await
+ * for `promptForSession()` returns.
+ *
+ * Wire mapping (locked in to match beeos-claw `acp-server.ts onStreamDelta`):
+ *
+ *   - `agent_message_chunk` → `agent_reply_delta` envelope with
+ *     `update.sessionUpdate=agent_message_chunk`. The text is also
+ *     accumulated into `accumulatedText` so the terminal `agent_reply`
+ *     can carry the full reply as `payload.text`.
+ *
+ *   - `agent_thought_chunk` → `agent_reply_delta` envelope with
+ *     `update.sessionUpdate=agent_thought_chunk`. Reasoning is NEVER
+ *     accumulated — `backend/pkg/convmsg/extract.go::extractNestedDelta`
+ *     intentionally drops thought chunks so they don't pollute reply
+ *     text, and we mirror that here.
+ *
+ *   - `stream_complete` → terminal `agent_reply` envelope. Payload
+ *     shape mirrors beeos-claw:
+ *       success   → { session_key, text }
+ *       cancelled → { session_key, error: "cancelled", text? }
+ *       failure   → { session_key, error, text? }
+ *
+ *   - All other `sessionUpdate` types (`agent_status`, `tool_call`,
+ *     `tool_call_update`, `history_turn`, `system_message_chunk`,
+ *     `user_message_chunk`) are intentionally SKIPPED. The old
+ *     outbound listener also skipped them; mirroring keeps the wire
+ *     format byte-for-byte identical for downstream consumers.
+ *
+ * **Only the terminal `agent_reply`** carries `in_reply_to = inboundMessageId`
+ * so the L0 `/channels/{id}/wait` endpoint can match the reply on the
+ * original `message_id`. Streaming deltas are fan-out only and MUST NOT
+ * carry `in_reply_to` — otherwise MS `/wait` (which only checks
+ * `in_reply_to`, not message type) would short-circuit on the first
+ * delta and the caller would misreport "completed". Mirrors beeos-claw
+ * `acp-server.ts:73-85`.
+ *
+ * The notifier never throws out of `send()` — that runs on the
+ * SessionManager event hot path and a synchronous throw would skip
+ * subsequent handlers (e.g. status:idle). All publish failures are
+ * logged and swallowed. The next event for the same turn will retry
+ * any subsequent publishes via the same path.
+ */
+export class MsChannelNotifier {
+    opts;
+    /** Cumulative `agent_message_chunk` text — populates terminal `agent_reply.text`. */
+    accumulatedText = "";
+    finalized = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Called by SessionManager for every `session/update` envelope on
+     * this notifier's bound sid. Fire-and-forget: the SessionManager
+     * event hot path is synchronous, so we kick off the publish in the
+     * background and never block.
+     */
+    send(_sessionId, update) {
+        void this.handle(update);
+    }
+    /**
+     * Cumulative reply text emitted so far. Exposed for diagnostics +
+     * tests; not part of any wire contract.
+     */
+    get currentText() {
+        return this.accumulatedText;
+    }
+    /** True once the terminal `agent_reply` has been published. */
+    get isFinalized() {
+        return this.finalized;
+    }
+    async handle(update) {
+        const sessionUpdate = pickSessionUpdate(update);
+        try {
+            switch (sessionUpdate) {
+                case "agent_message_chunk": {
+                    const text = pickContentText(update.content);
+                    if (!text)
+                        return;
+                    this.accumulatedText += text;
+                    await this.publishDelta("agent_message_chunk", text);
+                    return;
+                }
+                case "agent_thought_chunk": {
+                    const text = pickContentText(update.content);
+                    if (!text)
+                        return;
+                    await this.publishDelta("agent_thought_chunk", text);
+                    return;
+                }
+                case "stream_complete": {
+                    const stopReason = pickString(update.stopReason) || "end_turn";
+                    const errorText = pickString(update.error);
+                    await this.publishFinal(stopReason, errorText);
+                    return;
+                }
+                default:
+                    // agent_status / tool_call / tool_call_update / history_turn
+                    // / system_message_chunk / user_message_chunk → skip.
+                    return;
+            }
+        }
+        catch (err) {
+            this.opts.logger.error({
+                err: err instanceof Error ? err.message : String(err),
+                channelId: this.opts.channelId,
+                sessionUpdate,
+            }, "ms-channel-notifier: publish failed");
+        }
+    }
+    async publishDelta(sessionUpdate, text) {
+        // Streaming deltas are fan-out only — they MUST NOT carry
+        // `in_reply_to`, otherwise MS `/wait` (which only checks
+        // `in_reply_to`, not message type) would short-circuit on the
+        // first delta and the caller would think the turn finished.
+        // Mirrors beeos-claw `acp-server.ts:73-85`.
+        await this.opts.sdk.sendToChannel(this.opts.channelId, "agent_reply_delta", {
+            session_key: this.opts.sessionKey,
+            update: {
+                sessionUpdate,
+                content: { type: "text", text },
+            },
+        });
+    }
+    /**
+     * Emit the terminal `agent_reply`. Idempotent — guarded by
+     * `finalized` so a duplicate `stream_complete` (extremely rare,
+     * but possible if the host event handler ever fires twice) cannot
+     * publish two terminal envelopes.
+     */
+    async publishFinal(stopReason, errorText) {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        let payload;
+        if (stopReason === "cancelled") {
+            payload = {
+                session_key: this.opts.sessionKey,
+                error: "cancelled",
+                text: this.accumulatedText,
+            };
+        }
+        else if (errorText) {
+            payload = {
+                session_key: this.opts.sessionKey,
+                error: errorText,
+                text: this.accumulatedText,
+            };
+        }
+        else {
+            payload = {
+                session_key: this.opts.sessionKey,
+                text: this.accumulatedText,
+            };
+        }
+        await this.opts.sdk.sendToChannel(this.opts.channelId, "agent_reply", payload, { inReplyTo: this.opts.inboundMessageId });
+    }
+}
+function pickSessionUpdate(update) {
+    const v = update.sessionUpdate;
+    return typeof v === "string" ? v : "";
+}
+function pickContentText(content) {
+    if (!content || typeof content !== "object")
+        return "";
+    const c = content;
+    if (typeof c.text === "string")
+        return c.text;
+    return "";
+}
+function pickString(v) {
+    return typeof v === "string" ? v : "";
+}
+//# sourceMappingURL=ms-channel-notifier.js.map