@aitne/daemon 0.1.0

package/dist/adapters/docs-qa-adapter.js

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import { EventPriority, createEvent, } from "@aitne/shared";
+import { createStreamingValidator, } from "../core/docs/citation-validator.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("docs-qa-adapter");
+/**
+ * DocsQAAdapter — SSE-based MessageAdapter for the operator-facing
+ * Docs Q&A panel (DOCS_QA_B7_DESIGN.md §3.2).
+ *
+ * Parallel to `DashboardAdapter`: same SSE/HTTP transport, same
+ * dispatcher entry point, but a separate channel registry and a
+ * per-channel streaming-citation validator spliced into outbound
+ * deltas. Inbound messages are tagged with `intent: "docs_qa"` so
+ * `resolveProcessKey` returns `dashboard.docs_qa` and the dispatcher
+ * loads the docs-qa task flow + skill set + light-tier clamp.
+ *
+ * Implements:
+ *   - `IDashboardStream`: dispatcher fans outbound calls out to this
+ *     adapter via `CompositeDashboardStream`. The streaming validator
+ *     splice lives inside `sendStreamChunk` per §11.3. The
+ *     persistence-side `validateAndRewrite` runs in the dispatcher
+ *     (gated on `isDocsQAMessage(event)` per §11.1) — not here — so
+ *     this adapter never sees the full assembled output.
+ *   - `MessageAdapter`: registered with `MessageHub` so the standard
+ *     adapter lifecycle (`start`/`stop`) and `notificationEligible`
+ *     contract apply. `sendMessage` is required by the interface but
+ *     unused on this path (the QA model streams; it never lands a
+ *     non-streaming reply), so the implementation rejects to surface
+ *     misrouting early.
+ */
+export class DocsQAAdapter {
+    platformName = "dashboard";
+    /** QA replies are not eligible for owner-DM notification fan-out —
+     *  the panel renders them inline; the user is right there. */
+    notificationEligible = false;
+    clients = new Map();
+    onMessage;
+    citationLookup;
+    constructor(onMessage, citationLookup) {
+        this.onMessage = onMessage;
+        this.citationLookup = citationLookup;
+    }
+    async start() {
+        logger.info("Docs QA adapter ready (awaiting SSE connections)");
+    }
+    async stop() {
+        this.clients.clear();
+        logger.info("Docs QA adapter stopped");
+    }
+    /**
+     * Register a new SSE client. Mints a `channelId`, emits the initial
+     * `session_info` event so the dashboard knows the id to echo on
+     * subsequent POSTs (D5 — SSE-first channelId minting), and returns
+     * the id for the route's `onAbort` to unregister with.
+     *
+     * No `resumeSessionId` parameter (§11.6): QA panel state lives in
+     * React state in-memory; the panel does not persist transcripts
+     * across reload.
+     */
+    registerClient(client) {
+        const channelId = randomUUID();
+        this.clients.set(channelId, { client, validator: null });
+        const info = { channelId };
+        client
+            .writeSSE("session_info", JSON.stringify(info))
+            .catch((err) => logger.debug({ err, channelId, event: "session_info" }, "SSE write failed"));
+        logger.debug({ channelId }, "Docs QA client connected");
+        return channelId;
+    }
+    /** Drop a client. Called by the SSE route's `onAbort`. */
+    unregisterClient(channelId) {
+        const entry = this.clients.get(channelId);
+        if (!entry)
+            return;
+        // Dispose any in-flight validator buffer so a flapping client
+        // does not leak memory across reconnects.
+        entry.validator = null;
+        this.clients.delete(channelId);
+        logger.debug({ channelId }, "Docs QA client disconnected");
+    }
+    /** True iff the channel has an open SSE writer. The route uses this
+     *  to short-circuit POST `/docs/qa/messages` with `404
+     *  channel_not_connected` rather than enqueuing into the void. */
+    isConnected(channelId) {
+        const entry = this.clients.get(channelId);
+        return entry !== undefined && !entry.client.closed;
+    }
+    /**
+     * Translate an HTTP POST into a `MessageEvent` and feed it to the
+     * dispatcher. Forces `intent: "docs_qa"`, `platform: "dashboard"`,
+     * `isDm: true` regardless of the body — the route already guarded
+     * the body shape; this is the second forced-fields layer per §3.3.
+     */
+    handleIncomingMessage(channelId, content, options) {
+        const event = createEvent({
+            type: "message.received",
+            source: "dashboard",
+            priority: EventPriority.HIGH,
+        });
+        const message = Object.assign(event, {
+            sender: "user",
+            channel: channelId,
+            content,
+            platform: "dashboard",
+            threadId: null,
+            isDm: true,
+            isMention: false,
+            intent: "docs_qa",
+            ...(options.modelOverride
+                ? {
+                    requestedBackendId: options.modelOverride.backendId,
+                    requestedModelId: options.modelOverride.modelId,
+                }
+                : {}),
+        });
+        // Stash scope + context hint on event.data so the docs-search skill
+        // can read them. The scope discriminator narrows the corpus, and the
+        // hint surfaces the slug / category the operator was looking at when
+        // they opened the panel — the docs-qa task flow uses these to bias
+        // the search query without forcing a route-side query rewrite.
+        //
+        // `currentDocSlug` is duplicated as a flat string (defaulting to
+        // `"(none)"`) so `extractEventData` flattens it for the QA task
+        // flow's `{event_data[currentDocSlug]}` placeholder — `resolveTemplate`
+        // needs a primitive value, not the nested `docsContextHint` object.
+        message.data = {
+            ...message.data,
+            docsScope: options.scope,
+            currentDocSlug: options.contextHint?.currentSlug || "(none)",
+            ...(options.contextHint ? { docsContextHint: options.contextHint } : {}),
+        };
+        this.onMessage(message);
+    }
+    // ── IDashboardStream — outbound (dispatcher → SSE wire) ──
+    /**
+     * Forward a streaming text delta through the per-channel citation
+     * validator and emit the validated suffix. Unknown channelIds
+     * silently no-op (matches `dashboard-adapter.ts:211-218`) so the
+     * `CompositeDashboardStream` fan-out works without per-channel
+     * ownership tracking — only the adapter that owns the id emits.
+     */
+    sendStreamChunk(channelId, chunk) {
+        const entry = this.clients.get(channelId);
+        if (!entry || entry.client.closed)
+            return;
+        if (entry.validator === null) {
+            entry.validator = createStreamingValidator(this.citationLookup);
+        }
+        const validated = entry.validator.feed(chunk);
+        if (validated.length === 0)
+            return;
+        entry.client
+            .writeSSE("chat_stream", JSON.stringify({ chunk: validated }))
+            .catch((err) => logger.debug({ err, channelId, event: "chat_stream" }, "SSE write failed"));
+    }
+    /**
+     * Flush the trailing buffer through the validator and emit the
+     * final `stream_end` event. Disposes the per-channel validator so
+     * the next turn on the same channel starts with a fresh buffer.
+     */
+    sendStreamEnd(channelId) {
+        const entry = this.clients.get(channelId);
+        if (!entry)
+            return;
+        if (entry.validator !== null) {
+            const tail = entry.validator.flush();
+            entry.validator = null;
+            if (tail.length > 0 && !entry.client.closed) {
+                entry.client
+                    .writeSSE("chat_stream", JSON.stringify({ chunk: tail }))
+                    .catch((err) => logger.debug({ err, channelId, event: "chat_stream" }, "SSE write failed"));
+            }
+        }
+        if (!entry.client.closed) {
+            entry.client
+                .writeSSE("stream_end", "")
+                .catch((err) => logger.debug({ err, channelId, event: "stream_end" }, "SSE write failed"));
+        }
+    }
+    sendMessageMeta(channelId, meta) {
+        const entry = this.clients.get(channelId);
+        if (!entry || entry.client.closed)
+            return;
+        entry.client
+            .writeSSE("chat_meta", JSON.stringify(meta))
+            .catch((err) => logger.debug({ err, channelId, event: "chat_meta" }, "SSE write failed"));
+    }
+    sendSessionInfo(channelId, info) {
+        const entry = this.clients.get(channelId);
+        if (!entry || entry.client.closed)
+            return;
+        entry.client
+            .writeSSE("session_info", JSON.stringify(info))
+            .catch((err) => logger.debug({ err, channelId, event: "session_info" }, "SSE write failed"));
+    }
+    sendError(channelId, message) {
+        const entry = this.clients.get(channelId);
+        if (!entry || entry.client.closed)
+            return;
+        entry.client
+            .writeSSE("chat_error", JSON.stringify({ message }))
+            .catch((err) => logger.debug({ err, channelId, event: "chat_error" }, "SSE write failed"));
+    }
+    // ── MessageAdapter — outbound `sendMessage` is required by the
+    //    interface but the QA path is streaming-only. Reject loudly to
+    //    surface a misrouted dispatcher path during integration tests. ──
+    async sendMessage() {
+        throw new Error("DocsQAAdapter.sendMessage is not implemented — QA replies are streamed via sendStreamChunk/sendStreamEnd");
+    }
+    /** Active channel ids — used by `/health` integration probes and
+     *  test assertions; mirrors the chat adapter's helper. */
+    getActiveChannels() {
+        return [...this.clients.entries()]
+            .filter(([, entry]) => !entry.client.closed)
+            .map(([id]) => id);
+    }
+}
+//# sourceMappingURL=docs-qa-adapter.js.map

package/dist/adapters/docs-qa-adapter.js.map

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

package/dist/adapters/message-hub.d.ts

@@ -0,0 +1,70 @@
+import type Database from "better-sqlite3";
+import type { AgentConfig } from "../config.js";
+import { type NotificationDestinationPlatform } from "../messaging/constants.js";
+import type { MessageAdapter, ProcessingIndicatorHandle } from "./types.js";
+export declare class MessageDeliveryError extends Error {
+    constructor(message: string);
+}
+export interface MessageDelivery {
+    platform: string;
+    channel: string;
+    messageId?: string;
+}
+export interface AdapterRuntimeStatus {
+    runtimeState: "ok" | "error" | "connecting";
+    error: string | null;
+}
+export interface PlatformRuntimeStatus {
+    runtimeState: "ok" | "error" | "not_configured" | "connecting";
+    error: string | null;
+}
+interface ProactiveLogContext {
+    dispatchId: string;
+    notificationType: string;
+    priority: string;
+    contentSummary: string;
+}
+/**
+ * MessageHub — central registry for all messaging adapters.
+ *
+ * Replies to inbound events stay targeted to the originating platform/channel.
+ * Proactive notifications fan out to the configured destination set.
+ */
+export declare class MessageHub {
+    private readonly config;
+    private readonly db?;
+    private readonly adapters;
+    private readonly adapterStatus;
+    private readonly configuredPlatforms;
+    constructor(config: AgentConfig, db?: Database.Database | undefined);
+    register(adapter: MessageAdapter): void;
+    unregister(platform: string): MessageAdapter | undefined;
+    getAdapter(platform: string): MessageAdapter | undefined;
+    getPlatforms(): string[];
+    getPrimaryPlatform(): string;
+    setPrimaryPlatform(platform: string): void;
+    getAdapterStatuses(): Record<string, AdapterRuntimeStatus>;
+    setPlatformConfigured(platform: string, configured: boolean): void;
+    setPlatformRuntimeStatus(platform: string, status: AdapterRuntimeStatus): void;
+    isPlatformConfigured(platform: string): boolean;
+    isOwnerConfigured(platform: string): boolean;
+    getPlatformRuntimeStatus(platform: string): PlatformRuntimeStatus;
+    isPlatformNotificationEligible(platform: string): boolean;
+    getNotificationEligiblePlatforms(): NotificationDestinationPlatform[];
+    getEffectiveFallbackPlatforms(): NotificationDestinationPlatform[];
+    private decorateOutboundText;
+    private resolveUserChannel;
+    private resolveDestinationPlatforms;
+    private filterEligibleDestinationPlatforms;
+    private logFailedDelivery;
+    sendToUserDestinations(text: string, platforms?: string[], logContext?: ProactiveLogContext): Promise<MessageDelivery[]>;
+    sendToExactUserDestinations(text: string, platforms: readonly string[], logContext?: ProactiveLogContext): Promise<MessageDelivery[]>;
+    private deliverToResolvedPlatforms;
+    sendToUser(text: string, platforms?: string[], logContext?: ProactiveLogContext): Promise<MessageDelivery[]>;
+    sendToPlatform(platform: string, channel: string, text: string, threadId?: string): Promise<MessageDelivery>;
+    beginProcessingIndicator(platform: string, channel: string, threadId?: string): Promise<ProcessingIndicatorHandle>;
+    startAll(): Promise<void>;
+    stopAll(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=message-hub.d.ts.map

package/dist/adapters/message-hub.d.ts.map

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

package/dist/adapters/message-hub.js

@@ -0,0 +1,359 @@
+import { NOTIFICATION_DESTINATION_PLATFORMS, } from "../messaging/constants.js";
+import { formatAgentOutboundLabel } from "@aitne/shared";
+import { getOwnerChannel, upsertOwnerChannel } from "../messaging/owner-channels.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("message-hub");
+const NOOP_PROCESSING_INDICATOR = {
+    stop: async () => { },
+};
+export class MessageDeliveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MessageDeliveryError";
+    }
+}
+/**
+ * MessageHub — central registry for all messaging adapters.
+ *
+ * Replies to inbound events stay targeted to the originating platform/channel.
+ * Proactive notifications fan out to the configured destination set.
+ */
+export class MessageHub {
+    config;
+    db;
+    adapters = new Map();
+    adapterStatus = new Map();
+    configuredPlatforms = new Map();
+    constructor(config, db) {
+        this.config = config;
+        this.db = db;
+        this.configuredPlatforms.set("dashboard", true);
+    }
+    register(adapter) {
+        if (this.adapters.has(adapter.platformName)) {
+            logger.warn({ platform: adapter.platformName }, "Adapter already registered, replacing");
+        }
+        this.adapters.set(adapter.platformName, adapter);
+        this.adapterStatus.set(adapter.platformName, {
+            runtimeState: "ok",
+            error: null,
+        });
+        logger.info({ platform: adapter.platformName }, "Adapter registered");
+    }
+    unregister(platform) {
+        const adapter = this.adapters.get(platform);
+        if (!adapter)
+            return undefined;
+        this.adapters.delete(platform);
+        this.adapterStatus.delete(platform);
+        logger.info({ platform }, "Adapter unregistered");
+        return adapter;
+    }
+    getAdapter(platform) {
+        return this.adapters.get(platform);
+    }
+    getPlatforms() {
+        return [...this.adapters.keys()];
+    }
+    getPrimaryPlatform() {
+        return this.config.primaryPlatform;
+    }
+    setPrimaryPlatform(platform) {
+        this.config.primaryPlatform = platform;
+    }
+    getAdapterStatuses() {
+        return Object.fromEntries(this.adapterStatus.entries());
+    }
+    setPlatformConfigured(platform, configured) {
+        this.configuredPlatforms.set(platform, configured);
+    }
+    setPlatformRuntimeStatus(platform, status) {
+        this.adapterStatus.set(platform, status);
+    }
+    isPlatformConfigured(platform) {
+        if (platform === "whatsapp") {
+            return !!this.config.whatsappEnabled;
+        }
+        return this.configuredPlatforms.get(platform) ?? false;
+    }
+    isOwnerConfigured(platform) {
+        switch (platform) {
+            case "dashboard":
+                return true;
+            case "slack":
+                return !!this.config.slackOwnerUserId;
+            case "telegram":
+                return !!this.config.telegramOwnerChatId;
+            case "discord":
+                return !!this.config.discordOwnerUserId;
+            case "whatsapp":
+                return !!this.config.whatsappOwnerPhone;
+            default:
+                return false;
+        }
+    }
+    getPlatformRuntimeStatus(platform) {
+        if (!this.isPlatformConfigured(platform)) {
+            return {
+                runtimeState: "not_configured",
+                error: null,
+            };
+        }
+        const adapter = this.adapters.get(platform);
+        if (!adapter) {
+            return {
+                runtimeState: "error",
+                error: "Adapter not registered",
+            };
+        }
+        if (adapter.getNotificationRuntimeStatus) {
+            return adapter.getNotificationRuntimeStatus();
+        }
+        return this.adapterStatus.get(platform) ?? {
+            runtimeState: "error",
+            error: "Adapter not registered",
+        };
+    }
+    isPlatformNotificationEligible(platform) {
+        if (!NOTIFICATION_DESTINATION_PLATFORMS.includes(platform)) {
+            return false;
+        }
+        const adapter = this.adapters.get(platform);
+        if (!adapter || adapter.notificationEligible === false) {
+            return false;
+        }
+        return this.isPlatformConfigured(platform)
+            && this.isOwnerConfigured(platform)
+            && this.getPlatformRuntimeStatus(platform).runtimeState === "ok";
+    }
+    getNotificationEligiblePlatforms() {
+        return NOTIFICATION_DESTINATION_PLATFORMS.filter((platform) => this.isPlatformNotificationEligible(platform));
+    }
+    getEffectiveFallbackPlatforms() {
+        return this.resolveDestinationPlatforms();
+    }
+    decorateOutboundText(platform, text) {
+        if (platform !== "whatsapp") {
+            return text;
+        }
+        const prefix = formatAgentOutboundLabel(this.config.agentDisplayName);
+        if (text === prefix || text.startsWith(`${prefix}\n`) || text.startsWith(`${prefix} `)) {
+            return text;
+        }
+        return text ? `${prefix}\n${text}` : prefix;
+    }
+    async resolveUserChannel(adapter) {
+        if (adapter.primaryRecipient) {
+            return adapter.primaryRecipient;
+        }
+        if (this.db) {
+            const ownerChannel = getOwnerChannel(this.db, adapter.platformName);
+            if (ownerChannel?.channel_id) {
+                return ownerChannel.channel_id;
+            }
+        }
+        if (adapter.resolveUserChannel) {
+            return adapter.resolveUserChannel();
+        }
+        return null;
+    }
+    resolveDestinationPlatforms(requested) {
+        const eligible = this.getNotificationEligiblePlatforms();
+        if (eligible.length === 0) {
+            return [];
+        }
+        const filterKnown = (platforms) => this.filterEligibleDestinationPlatforms(platforms, eligible);
+        if (requested && requested.length > 0) {
+            return [...new Set(filterKnown(requested))];
+        }
+        const configuredDefaults = filterKnown(this.config.defaultNotificationPlatforms);
+        if (configuredDefaults.length > 0) {
+            return configuredDefaults;
+        }
+        const primary = filterKnown([this.config.primaryPlatform]);
+        if (primary.length > 0) {
+            return primary;
+        }
+        return [eligible[0]];
+    }
+    filterEligibleDestinationPlatforms(platforms, eligible = this.getNotificationEligiblePlatforms()) {
+        return platforms.filter((platform) => eligible.includes(platform));
+    }
+    logFailedDelivery(platform, reason, context) {
+        if (!this.db || !context)
+            return;
+        const summaryBase = `delivery failed: ${reason}; ${context.contentSummary}`;
+        const summary = summaryBase.length > 200 ? `${summaryBase.slice(0, 197)}...` : summaryBase;
+        this.db
+            .prepare(`INSERT INTO notification_log (
+           dispatch_id,
+           notification_type,
+           priority,
+           platform,
+           content_summary,
+           status
+         )
+         VALUES (?, ?, ?, ?, ?, 'failed')`)
+            .run(context.dispatchId, context.notificationType, context.priority, platform, summary);
+    }
+    async sendToUserDestinations(text, platforms, logContext) {
+        const targets = this.resolveDestinationPlatforms(platforms);
+        if (targets.length === 0) {
+            throw new MessageDeliveryError("No eligible notification destination is configured");
+        }
+        return this.deliverToResolvedPlatforms(text, targets, logContext);
+    }
+    async sendToExactUserDestinations(text, platforms, logContext) {
+        const targets = this.filterEligibleDestinationPlatforms(platforms);
+        if (targets.length === 0) {
+            throw new MessageDeliveryError("No eligible configured notification destination is available");
+        }
+        return this.deliverToResolvedPlatforms(text, targets, logContext);
+    }
+    async deliverToResolvedPlatforms(text, targets, logContext) {
+        const deliveries = [];
+        const errors = [];
+        for (const platform of targets) {
+            const adapter = this.adapters.get(platform);
+            if (!adapter) {
+                const reason = "adapter not registered";
+                errors.push(`${platform}: ${reason}`);
+                this.logFailedDelivery(platform, reason, logContext);
+                continue;
+            }
+            const channel = await this.resolveUserChannel(adapter);
+            if (!channel) {
+                const reason = "owner channel could not be resolved";
+                errors.push(`${platform}: ${reason}`);
+                this.logFailedDelivery(platform, reason, logContext);
+                continue;
+            }
+            try {
+                const result = await adapter.sendMessage({
+                    channel,
+                    text: this.decorateOutboundText(platform, text),
+                });
+                deliveries.push({
+                    platform,
+                    channel,
+                    messageId: result?.messageId,
+                });
+                if (this.db) {
+                    upsertOwnerChannel(this.db, {
+                        platform,
+                        channelId: channel,
+                        touchOutbound: true,
+                    });
+                }
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                errors.push(`${platform}: ${reason}`);
+                this.logFailedDelivery(platform, reason, logContext);
+                logger.warn({ platform, error: reason }, "Failed proactive delivery");
+            }
+        }
+        if (deliveries.length === 0) {
+            throw new MessageDeliveryError(`Unable to deliver proactive message (${errors.join("; ")})`);
+        }
+        return deliveries;
+    }
+    async sendToUser(text, platforms, logContext) {
+        return this.sendToUserDestinations(text, platforms, logContext);
+    }
+    async sendToPlatform(platform, channel, text, threadId) {
+        const adapter = this.adapters.get(platform);
+        if (!adapter) {
+            throw new MessageDeliveryError(`Adapter not found for platform "${platform}"`);
+        }
+        const resolvedChannel = channel === "user" ? await this.resolveUserChannel(adapter) : channel;
+        if (!resolvedChannel) {
+            throw new MessageDeliveryError(`No default recipient available for platform "${platform}"`);
+        }
+        const result = await adapter.sendMessage({
+            channel: resolvedChannel,
+            text: this.decorateOutboundText(platform, text),
+            threadId,
+        });
+        if (channel === "user" && this.db) {
+            upsertOwnerChannel(this.db, {
+                platform,
+                channelId: resolvedChannel,
+                touchOutbound: true,
+            });
+        }
+        return {
+            platform: adapter.platformName,
+            channel: resolvedChannel,
+            messageId: result?.messageId,
+        };
+    }
+    async beginProcessingIndicator(platform, channel, threadId) {
+        const adapter = this.adapters.get(platform);
+        if (!adapter?.beginProcessingIndicator) {
+            return NOOP_PROCESSING_INDICATOR;
+        }
+        const resolvedChannel = channel === "user" ? await this.resolveUserChannel(adapter) : channel;
+        if (!resolvedChannel) {
+            return NOOP_PROCESSING_INDICATOR;
+        }
+        try {
+            return (await adapter.beginProcessingIndicator({
+                channel: resolvedChannel,
+                threadId,
+            })) ?? NOOP_PROCESSING_INDICATOR;
+        }
+        catch (err) {
+            logger.debug({ platform, channel: resolvedChannel, error: err instanceof Error ? err.message : String(err) }, "Failed to start processing indicator");
+            return NOOP_PROCESSING_INDICATOR;
+        }
+    }
+    async startAll() {
+        const adapters = [...this.adapters.values()];
+        // Mark every adapter as "connecting" before launching their start() in
+        // parallel. The API server typically starts listening before startAll()
+        // runs during boot, so /health polled in the multi-second start window
+        // would otherwise report the register() default of "ok" — claiming a
+        // live connection that hasn't happened yet. The per-adapter result loop
+        // below transitions each one to "ok" or "error" as their start resolves.
+        for (const adapter of adapters) {
+            this.adapterStatus.set(adapter.platformName, {
+                runtimeState: "connecting",
+                error: null,
+            });
+        }
+        const results = await Promise.allSettled(adapters.map((adapter) => adapter.start()));
+        for (const [index, result] of results.entries()) {
+            const platform = adapters[index]?.platformName;
+            /* v8 ignore next 1 — index always in bounds (results.length === adapters.length) */
+            if (!platform)
+                continue;
+            if (result.status === "rejected") {
+                const reason = result.reason instanceof Error
+                    ? result.reason.message
+                    : String(result.reason);
+                this.adapterStatus.set(platform, {
+                    runtimeState: "error",
+                    error: reason,
+                });
+                logger.error({ platform, error: reason }, "Failed to start adapter");
+                continue;
+            }
+            this.adapterStatus.set(platform, {
+                runtimeState: "ok",
+                error: null,
+            });
+        }
+    }
+    async stopAll() {
+        const adapters = [...this.adapters.values()];
+        const results = await Promise.allSettled(adapters.map((adapter) => adapter.stop()));
+        for (const [index, result] of results.entries()) {
+            if (result.status === "rejected") {
+                const platform = adapters[index]?.platformName;
+                logger.error({ platform, error: result.reason }, "Failed to stop adapter");
+            }
+        }
+    }
+}
+//# sourceMappingURL=message-hub.js.map