@xopcai/xopc 0.0.82 → 0.0.83

package/dist/src/channels/heartbeat-scheduler.js

@@ -0,0 +1,94 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+//#region src/channels/heartbeat-scheduler.ts
+init_logger();
+const log = createLogger("ChannelHeartbeatScheduler");
+/** Minimum gap between successive soft-restart attempts for the same channel. */
+const HEARTBEAT_RESTART_THROTTLE_MS = 6e4;
+var ChannelHeartbeatScheduler = class {
+	opts;
+	/** Key shape: `${pluginId}:${accountId}`. */
+	timers = /* @__PURE__ */ new Map();
+	lastRestartAt = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.opts = opts;
+	}
+	/** Register heartbeat checks for every account exposed by the plugin. */
+	schedule(plugin) {
+		const hb = plugin.heartbeat;
+		if (!hb) return;
+		this.clear(plugin.id);
+		let accountIds;
+		try {
+			accountIds = plugin.config.listAccountIds(this.opts.getConfig());
+		} catch (err) {
+			log.warn({
+				channel: plugin.id,
+				err
+			}, "Heartbeat: failed to list accounts");
+			return;
+		}
+		for (const accountId of accountIds) {
+			const key = `${plugin.id}:${accountId}`;
+			const timer = setInterval(() => void this.runProbe(plugin, accountId), hb.intervalMs);
+			this.timers.set(key, timer);
+		}
+	}
+	/** Drop every probe scheduled for `pluginId` (called on stop / soft-restart). */
+	clear(pluginId) {
+		const prefix = `${pluginId}:`;
+		for (const key of [...this.timers.keys()]) {
+			if (!key.startsWith(prefix)) continue;
+			clearInterval(this.timers.get(key));
+			this.timers.delete(key);
+		}
+	}
+	/** Test helper / process shutdown. */
+	clearAll() {
+		for (const timer of this.timers.values()) clearInterval(timer);
+		this.timers.clear();
+		this.lastRestartAt.clear();
+	}
+	async runProbe(plugin, accountId) {
+		const hb = plugin.heartbeat;
+		if (!hb) return;
+		const cfg = this.opts.getConfig();
+		try {
+			const r = await hb.check({
+				cfg,
+				accountId
+			});
+			this.opts.healthMonitor.set(plugin.id, accountId, {
+				healthy: r.healthy,
+				lastCheckAt: Date.now(),
+				detail: typeof r.details === "string" ? r.details : r.details != null ? JSON.stringify(r.details) : void 0
+			});
+			if (!r.healthy) {
+				log.warn({
+					channel: plugin.id,
+					accountId,
+					detail: r.details
+				}, "Channel heartbeat unhealthy");
+				const now = Date.now();
+				if (now - (this.lastRestartAt.get(plugin.id) ?? 0) < HEARTBEAT_RESTART_THROTTLE_MS) return;
+				this.lastRestartAt.set(plugin.id, now);
+				this.opts.requestSoftRestart(plugin.id);
+			}
+		} catch (err) {
+			this.opts.healthMonitor.set(plugin.id, accountId, {
+				healthy: false,
+				lastCheckAt: Date.now(),
+				detail: err instanceof Error ? err.message : String(err)
+			});
+			log.error({
+				channel: plugin.id,
+				accountId,
+				err
+			}, "Channel heartbeat check failed");
+		}
+	}
+};
+//#endregion
+export { ChannelHeartbeatScheduler };
+
+//# sourceMappingURL=heartbeat-scheduler.js.map

package/dist/src/channels/heartbeat-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-scheduler.js","names":[],"sources":["../../../src/channels/heartbeat-scheduler.ts"],"sourcesContent":["/**\n * ChannelHeartbeatScheduler — runs per-account heartbeat probes for plugins\n * that expose a `heartbeat.check(...)` hook, records the result in the shared\n * {@link ChannelHealthMonitor}, and asks the lifecycle supervisor for a soft\n * restart when a check fails (rate-limited to once per minute per channel).\n *\n * Previously this lived as `_scheduleHeartbeat` + `_clearHeartbeatTimers` +\n * `_softRestartChannel` + two private Maps on `ChannelManager`. Extracting it\n * makes the heartbeat policy testable in isolation and lets the lifecycle\n * supervisor focus on plugin start/stop without worrying about timer wiring.\n */\n\nimport type { Config } from '../config/schema.js';\n\nimport type { ChannelPlugin } from './plugin-types.js';\nimport type { ChannelHealthMonitor } from './health-monitor.js';\nimport { createLogger } from '../utils/logger.js';\n\nconst log = createLogger('ChannelHeartbeatScheduler');\n\n/** Minimum gap between successive soft-restart attempts for the same channel. */\nconst HEARTBEAT_RESTART_THROTTLE_MS = 60_000;\n\nexport interface ChannelHeartbeatSchedulerOptions {\n  /** Effective config snapshot (per-account listing comes from `plugin.config.listAccountIds(cfg)`). */\n  getConfig: () => Config;\n  /** Shared health monitor that channel APIs surface to the UI. */\n  healthMonitor: ChannelHealthMonitor;\n  /**\n   * Triggered when a check fails AND we are past the restart-throttle window.\n   * The supervisor performs `stop()` + `startPlugin()`; the scheduler does not\n   * touch plugin lifecycle directly.\n   */\n  requestSoftRestart: (channelId: string) => void;\n}\n\nexport class ChannelHeartbeatScheduler {\n  private readonly opts: ChannelHeartbeatSchedulerOptions;\n  /** Key shape: `${pluginId}:${accountId}`. */\n  private readonly timers = new Map<string, ReturnType<typeof setInterval>>();\n  private readonly lastRestartAt = new Map<string, number>();\n\n  constructor(opts: ChannelHeartbeatSchedulerOptions) {\n    this.opts = opts;\n  }\n\n  /** Register heartbeat checks for every account exposed by the plugin. */\n  schedule(plugin: ChannelPlugin): void {\n    const hb = plugin.heartbeat;\n    if (!hb) return;\n\n    this.clear(plugin.id);\n\n    let accountIds: string[];\n    try {\n      accountIds = plugin.config.listAccountIds(this.opts.getConfig());\n    } catch (err) {\n      log.warn({ channel: plugin.id, err }, 'Heartbeat: failed to list accounts');\n      return;\n    }\n\n    for (const accountId of accountIds) {\n      const key = `${plugin.id}:${accountId}`;\n      const timer = setInterval(\n        () => void this.runProbe(plugin, accountId),\n        hb.intervalMs,\n      );\n      this.timers.set(key, timer);\n    }\n  }\n\n  /** Drop every probe scheduled for `pluginId` (called on stop / soft-restart). */\n  clear(pluginId: string): void {\n    const prefix = `${pluginId}:`;\n    for (const key of [...this.timers.keys()]) {\n      if (!key.startsWith(prefix)) continue;\n      clearInterval(this.timers.get(key)!);\n      this.timers.delete(key);\n    }\n  }\n\n  /** Test helper / process shutdown. */\n  clearAll(): void {\n    for (const timer of this.timers.values()) {\n      clearInterval(timer);\n    }\n    this.timers.clear();\n    this.lastRestartAt.clear();\n  }\n\n  private async runProbe(plugin: ChannelPlugin, accountId: string): Promise<void> {\n    const hb = plugin.heartbeat;\n    if (!hb) return;\n    const cfg = this.opts.getConfig();\n    try {\n      const r = await hb.check({ cfg, accountId });\n      this.opts.healthMonitor.set(plugin.id, accountId, {\n        healthy: r.healthy,\n        lastCheckAt: Date.now(),\n        detail:\n          typeof r.details === 'string'\n            ? r.details\n            : r.details != null\n              ? JSON.stringify(r.details)\n              : undefined,\n      });\n      if (!r.healthy) {\n        log.warn(\n          { channel: plugin.id, accountId, detail: r.details },\n          'Channel heartbeat unhealthy',\n        );\n        const now = Date.now();\n        const last = this.lastRestartAt.get(plugin.id) ?? 0;\n        if (now - last < HEARTBEAT_RESTART_THROTTLE_MS) {\n          return;\n        }\n        this.lastRestartAt.set(plugin.id, now);\n        this.opts.requestSoftRestart(plugin.id);\n      }\n    } catch (err) {\n      this.opts.healthMonitor.set(plugin.id, accountId, {\n        healthy: false,\n        lastCheckAt: Date.now(),\n        detail: err instanceof Error ? err.message : String(err),\n      });\n      log.error({ channel: plugin.id, accountId, err }, 'Channel heartbeat check failed');\n    }\n  }\n}\n"],"mappings":";;;aAgBkD;AAElD,MAAM,MAAM,aAAa,4BAA4B;;AAGrD,MAAM,gCAAgC;AAetC,IAAa,4BAAb,MAAuC;CACrC;;CAEA,yBAA0B,IAAI,KAA6C;CAC3E,gCAAiC,IAAI,KAAqB;CAE1D,YAAY,MAAwC;AAClD,OAAK,OAAO;;;CAId,SAAS,QAA6B;EACpC,MAAM,KAAK,OAAO;AAClB,MAAI,CAAC,GAAI;AAET,OAAK,MAAM,OAAO,GAAG;EAErB,IAAI;AACJ,MAAI;AACF,gBAAa,OAAO,OAAO,eAAe,KAAK,KAAK,WAAW,CAAC;WACzD,KAAK;AACZ,OAAI,KAAK;IAAE,SAAS,OAAO;IAAI;IAAK,EAAE,qCAAqC;AAC3E;;AAGF,OAAK,MAAM,aAAa,YAAY;GAClC,MAAM,MAAM,GAAG,OAAO,GAAG,GAAG;GAC5B,MAAM,QAAQ,kBACN,KAAK,KAAK,SAAS,QAAQ,UAAU,EAC3C,GAAG,WACJ;AACD,QAAK,OAAO,IAAI,KAAK,MAAM;;;;CAK/B,MAAM,UAAwB;EAC5B,MAAM,SAAS,GAAG,SAAS;AAC3B,OAAK,MAAM,OAAO,CAAC,GAAG,KAAK,OAAO,MAAM,CAAC,EAAE;AACzC,OAAI,CAAC,IAAI,WAAW,OAAO,CAAE;AAC7B,iBAAc,KAAK,OAAO,IAAI,IAAI,CAAE;AACpC,QAAK,OAAO,OAAO,IAAI;;;;CAK3B,WAAiB;AACf,OAAK,MAAM,SAAS,KAAK,OAAO,QAAQ,CACtC,eAAc,MAAM;AAEtB,OAAK,OAAO,OAAO;AACnB,OAAK,cAAc,OAAO;;CAG5B,MAAc,SAAS,QAAuB,WAAkC;EAC9E,MAAM,KAAK,OAAO;AAClB,MAAI,CAAC,GAAI;EACT,MAAM,MAAM,KAAK,KAAK,WAAW;AACjC,MAAI;GACF,MAAM,IAAI,MAAM,GAAG,MAAM;IAAE;IAAK;IAAW,CAAC;AAC5C,QAAK,KAAK,cAAc,IAAI,OAAO,IAAI,WAAW;IAChD,SAAS,EAAE;IACX,aAAa,KAAK,KAAK;IACvB,QACE,OAAO,EAAE,YAAY,WACjB,EAAE,UACF,EAAE,WAAW,OACX,KAAK,UAAU,EAAE,QAAQ,GACzB,KAAA;IACT,CAAC;AACF,OAAI,CAAC,EAAE,SAAS;AACd,QAAI,KACF;KAAE,SAAS,OAAO;KAAI;KAAW,QAAQ,EAAE;KAAS,EACpD,8BACD;IACD,MAAM,MAAM,KAAK,KAAK;AAEtB,QAAI,OADS,KAAK,cAAc,IAAI,OAAO,GAAG,IAAI,KACjC,8BACf;AAEF,SAAK,cAAc,IAAI,OAAO,IAAI,IAAI;AACtC,SAAK,KAAK,mBAAmB,OAAO,GAAG;;WAElC,KAAK;AACZ,QAAK,KAAK,cAAc,IAAI,OAAO,IAAI,WAAW;IAChD,SAAS;IACT,aAAa,KAAK,KAAK;IACvB,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;IACzD,CAAC;AACF,OAAI,MAAM;IAAE,SAAS,OAAO;IAAI;IAAW;IAAK,EAAE,iCAAiC"}

package/dist/src/channels/lifecycle-supervisor.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ChannelLifecycleSupervisor — owns the start/stop/restart state machine for
+ * every channel plugin.
+ *
+ * Concerns:
+ *   - `initialize()` — call each plugin's `init(...)` once and remember success
+ *   - Two-phase `start()` + `startDeferredConnects()` for channels whose
+ *     `meta.deferConnectUntilAfterListen` is true (HTTP listener has to be up
+ *     before they dial out)
+ *   - Per-channel manual stop / start (UI-driven; suppresses auto-restart)
+ *   - Exponential restart backoff via {@link CHANNEL_RESTART_POLICY}
+ *   - Soft restart (called from heartbeat) — stop + startPlugin, manual-stop guarded
+ *
+ * Heartbeat probes themselves live in {@link ChannelHeartbeatScheduler}; this
+ * supervisor schedules them via `onPluginStarted` / `onPluginStopped` callbacks
+ * passed in by the caller.
+ *
+ * Extracted from `ChannelManager` so the manager can be a thin composition root.
+ */
+import type { Config } from '../config/schema.js';
+import type { MessageBus } from '../infra/bus/index.js';
+import type { ChannelPlugin, ChannelPluginSessionModelHooks } from './plugin-types.js';
+import type { ChannelPluginRegistry } from './plugin-registry.js';
+export interface ChannelLifecycleSupervisorOptions {
+    bus: MessageBus;
+    registry: ChannelPluginRegistry;
+    /** Effective config snapshot (per-channel `channels.<id>.*`). */
+    getConfig: () => Config;
+    /** Hooks for sub-classes / external observers: heartbeat scheduling, etc. */
+    onPluginStarted?: (plugin: ChannelPlugin) => void;
+    onPluginStopped?: (pluginId: string) => void;
+    /** Optional session-model hooks forwarded into `plugin.init()`. */
+    getSessionModelHooks?: () => ChannelPluginSessionModelHooks | undefined;
+}
+export declare class ChannelLifecycleSupervisor {
+    private readonly opts;
+    /** Plugin ids whose `init()` completed (used by start/stop loops). */
+    private readonly initializedPluginIds;
+    private readonly restartAttempts;
+    /** When set, failed-start auto-restart is suppressed for that channel id. */
+    private readonly manuallyStopped;
+    /** Plugins that skipped `start()` until `startDeferredConnects()`. */
+    private readonly deferredConnectPending;
+    private initialized;
+    private running;
+    constructor(opts: ChannelLifecycleSupervisorOptions);
+    isInitialized(pluginId: string): boolean;
+    snapshot(): {
+        initialized: boolean;
+        running: boolean;
+        initializedPluginIds: string[];
+        manuallyStopped: string[];
+        restartAttempts: Record<string, number>;
+    };
+    /** Channel ids that would run and declare `meta.deferConnectUntilAfterListen` (for logging / metrics). */
+    listDeferConnectChannelIds(cfg: Config): string[];
+    initialize(): Promise<void>;
+    /** Phase 1: start every enabled channel except those in `deferConnectPluginIds`. */
+    start(options?: {
+        deferConnectPluginIds?: ReadonlySet<string>;
+    }): Promise<void>;
+    /** Phase 2: `start()` for channels deferred at Phase 1. No-op if none pending. */
+    startDeferredConnects(): Promise<void>;
+    stop(): Promise<void>;
+    /** Stop one channel and suppress automatic restart until `startChannel` is called. */
+    stopChannel(channelId: string): Promise<void>;
+    /** Clear manual-stop and start one channel (requires prior `initialize()`). */
+    startChannel(channelId: string): Promise<void>;
+    /** Called by heartbeat: stop + start without clearing manualStop. No-op if user stopped it. */
+    softRestart(channelId: string): Promise<void>;
+    /** Forward a config snapshot to every initialised plugin's `onConfigUpdated` hook. */
+    forwardConfigUpdate(cfg: Config): Promise<void>;
+    /**
+     * Builtin channels require `channels.<id>.enabled`. Extension-managed channels
+     * run unless explicitly disabled.
+     */
+    private shouldRunChannelPlugin;
+    private initializePlugin;
+    private startPlugin;
+    private stopPlugin;
+}

package/dist/src/channels/lifecycle-supervisor.js

@@ -0,0 +1,263 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { CHANNEL_RESTART_POLICY, computeBackoff } from "./restart-policy.js";
+//#region src/channels/lifecycle-supervisor.ts
+init_logger();
+const log = createLogger("ChannelLifecycleSupervisor");
+function asChannelConfig(raw) {
+	if (raw && typeof raw === "object" && !Array.isArray(raw)) return raw;
+}
+var ChannelLifecycleSupervisor = class {
+	opts;
+	/** Plugin ids whose `init()` completed (used by start/stop loops). */
+	initializedPluginIds = /* @__PURE__ */ new Set();
+	restartAttempts = /* @__PURE__ */ new Map();
+	/** When set, failed-start auto-restart is suppressed for that channel id. */
+	manuallyStopped = /* @__PURE__ */ new Set();
+	/** Plugins that skipped `start()` until `startDeferredConnects()`. */
+	deferredConnectPending = /* @__PURE__ */ new Set();
+	initialized = false;
+	running = false;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	isInitialized(pluginId) {
+		return this.initializedPluginIds.has(pluginId);
+	}
+	snapshot() {
+		return {
+			initialized: this.initialized,
+			running: this.running,
+			initializedPluginIds: [...this.initializedPluginIds],
+			manuallyStopped: [...this.manuallyStopped],
+			restartAttempts: Object.fromEntries(this.restartAttempts)
+		};
+	}
+	/** Channel ids that would run and declare `meta.deferConnectUntilAfterListen` (for logging / metrics). */
+	listDeferConnectChannelIds(cfg) {
+		const out = [];
+		for (const [id, plugin] of this.opts.registry.entries()) {
+			const channelConfig = asChannelConfig(cfg.channels?.[id]);
+			if (!this.shouldRunChannelPlugin(plugin, channelConfig)) continue;
+			if (plugin.meta.deferConnectUntilAfterListen === true) out.push(id);
+		}
+		return out;
+	}
+	async initialize() {
+		if (this.initialized) {
+			log.warn({ pluginCount: this.opts.registry.ids().length }, "initialize() called again; channels already initialized — skipping");
+			return;
+		}
+		const cfg = this.opts.getConfig();
+		const initPromises = [];
+		for (const [id, plugin] of this.opts.registry.entries()) {
+			const channelConfig = asChannelConfig(cfg.channels?.[id]);
+			initPromises.push(this.initializePlugin(plugin, channelConfig ?? {}));
+		}
+		await Promise.allSettled(initPromises);
+		this.initialized = true;
+		log.info("All channel plugins initialized");
+	}
+	/** Phase 1: start every enabled channel except those in `deferConnectPluginIds`. */
+	async start(options) {
+		if (!this.initialized) throw new Error("Channels not initialized");
+		if (this.running) {
+			log.warn({ pluginCount: this.opts.registry.ids().length }, "start() called while channels already running — skipping");
+			return;
+		}
+		const deferIds = options?.deferConnectPluginIds ?? /* @__PURE__ */ new Set();
+		this.deferredConnectPending.clear();
+		const cfg = this.opts.getConfig();
+		const startPromises = [];
+		for (const [id, plugin] of this.opts.registry.entries()) {
+			const channelConfig = asChannelConfig(cfg.channels?.[id]);
+			if (!this.shouldRunChannelPlugin(plugin, channelConfig)) continue;
+			if (deferIds.has(id)) {
+				this.deferredConnectPending.add(id);
+				log.info({ channel: id }, "Channel connect deferred until HTTP listen");
+				continue;
+			}
+			startPromises.push(this.startPlugin(plugin, {}).catch((err) => {
+				log.error({
+					channel: id,
+					err
+				}, "Failed to start channel plugin");
+			}));
+		}
+		await Promise.allSettled(startPromises);
+		this.running = true;
+		log.info({ deferred: [...this.deferredConnectPending] }, this.deferredConnectPending.size > 0 ? "Channel plugins started (deferred connects pending)" : "All channel plugins started");
+	}
+	/** Phase 2: `start()` for channels deferred at Phase 1. No-op if none pending. */
+	async startDeferredConnects() {
+		if (this.deferredConnectPending.size === 0) return;
+		if (!this.running) {
+			log.warn("startDeferredConnects called before channel phase-1 start; skipping");
+			return;
+		}
+		const ids = [...this.deferredConnectPending];
+		this.deferredConnectPending.clear();
+		const cfg = this.opts.getConfig();
+		const startPromises = [];
+		for (const id of ids) {
+			const plugin = this.opts.registry.get(id);
+			if (!plugin) continue;
+			const channelConfig = asChannelConfig(cfg.channels?.[id]);
+			if (!this.shouldRunChannelPlugin(plugin, channelConfig)) continue;
+			startPromises.push(this.startPlugin(plugin, {}).catch((err) => {
+				log.error({
+					channel: id,
+					err
+				}, "Failed to start deferred channel plugin");
+			}));
+		}
+		await Promise.allSettled(startPromises);
+		log.info({ channels: ids }, "Deferred channel connects completed");
+	}
+	async stop() {
+		if (!this.running) return;
+		this.deferredConnectPending.clear();
+		const stopPromises = [];
+		for (const id of this.initializedPluginIds) {
+			const plugin = this.opts.registry.get(id);
+			if (!plugin) continue;
+			stopPromises.push(this.stopPlugin(plugin).catch((err) => {
+				log.error({
+					channel: id,
+					err
+				}, "Failed to stop channel plugin");
+			}));
+		}
+		await Promise.allSettled(stopPromises);
+		this.running = false;
+		log.info("All channel plugins stopped");
+	}
+	/** Stop one channel and suppress automatic restart until `startChannel` is called. */
+	async stopChannel(channelId) {
+		this.manuallyStopped.add(channelId);
+		const plugin = this.opts.registry.get(channelId);
+		if (!plugin || !this.initializedPluginIds.has(channelId)) return;
+		await this.stopPlugin(plugin).catch((err) => {
+			log.error({
+				channel: channelId,
+				err
+			}, "Failed to stop channel plugin");
+		});
+	}
+	/** Clear manual-stop and start one channel (requires prior `initialize()`). */
+	async startChannel(channelId) {
+		this.manuallyStopped.delete(channelId);
+		const plugin = this.opts.registry.get(channelId);
+		if (!plugin) {
+			log.warn({ channel: channelId }, "Unknown channel");
+			return;
+		}
+		if (!this.initialized) {
+			log.warn({ channel: channelId }, "Channels not initialized");
+			return;
+		}
+		const channelConfig = asChannelConfig(this.opts.getConfig().channels?.[channelId]);
+		if (!this.shouldRunChannelPlugin(plugin, channelConfig)) {
+			log.debug({ channel: channelId }, "Channel disabled in config, skipping start");
+			return;
+		}
+		if (!this.initializedPluginIds.has(channelId)) {
+			log.warn({ channel: channelId }, "Channel was never initialized; call initialize() first");
+			return;
+		}
+		await this.startPlugin(plugin, {});
+	}
+	/** Called by heartbeat: stop + start without clearing manualStop. No-op if user stopped it. */
+	async softRestart(channelId) {
+		if (this.manuallyStopped.has(channelId)) return;
+		const plugin = this.opts.registry.get(channelId);
+		if (!plugin || !this.initializedPluginIds.has(channelId)) return;
+		try {
+			await this.stopPlugin(plugin);
+			await this.startPlugin(plugin, {});
+		} catch (err) {
+			log.error({
+				channel: channelId,
+				err
+			}, "Channel soft restart after heartbeat failed");
+		}
+	}
+	/** Forward a config snapshot to every initialised plugin's `onConfigUpdated` hook. */
+	async forwardConfigUpdate(cfg) {
+		for (const id of this.initializedPluginIds) {
+			const plugin = this.opts.registry.get(id);
+			if (plugin?.onConfigUpdated) await Promise.resolve(plugin.onConfigUpdated(cfg));
+		}
+	}
+	/**
+	* Builtin channels require `channels.<id>.enabled`. Extension-managed channels
+	* run unless explicitly disabled.
+	*/
+	shouldRunChannelPlugin(plugin, channelConfig) {
+		if (plugin.extensionManagedConfig) return channelConfig?.enabled !== false;
+		return !!channelConfig?.enabled;
+	}
+	async initializePlugin(plugin, channelConfig) {
+		try {
+			const options = {
+				bus: this.opts.bus,
+				config: this.opts.getConfig(),
+				channelConfig,
+				sessionModel: this.opts.getSessionModelHooks?.()
+			};
+			await plugin.init(options);
+			this.initializedPluginIds.add(plugin.id);
+			log.debug({ channel: plugin.id }, "Channel plugin initialized");
+		} catch (err) {
+			log.error({
+				channel: plugin.id,
+				err
+			}, "Failed to initialize channel plugin");
+		}
+	}
+	async startPlugin(plugin, opts) {
+		const options = {};
+		try {
+			await plugin.start(options);
+			if (!opts.preserveRestartAttempts) this.restartAttempts.delete(plugin.id);
+			this.opts.onPluginStarted?.(plugin);
+			log.debug({ channel: plugin.id }, "Channel plugin started");
+		} catch (err) {
+			const attempt = (this.restartAttempts.get(plugin.id) ?? 0) + 1;
+			this.restartAttempts.set(plugin.id, attempt);
+			if (attempt <= CHANNEL_RESTART_POLICY.maxAttempts) {
+				const delayMs = computeBackoff(CHANNEL_RESTART_POLICY, attempt);
+				log.warn({
+					channel: plugin.id,
+					attempt,
+					delayMs,
+					err
+				}, "Channel failed to start, scheduling restart");
+				setTimeout(() => {
+					if (this.manuallyStopped.has(plugin.id)) {
+						log.debug({ channel: plugin.id }, "Skipping scheduled restart (manual stop)");
+						return;
+					}
+					this.startPlugin(plugin, { preserveRestartAttempts: true }).catch((e) => {
+						log.error({
+							channel: plugin.id,
+							err: e
+						}, "Channel restart attempt failed");
+					});
+				}, delayMs);
+			} else log.error({
+				channel: plugin.id,
+				err
+			}, "Channel exceeded max restart attempts");
+		}
+	}
+	async stopPlugin(plugin) {
+		this.opts.onPluginStopped?.(plugin.id);
+		await plugin.stop();
+		log.info({ channel: plugin.id }, "Channel plugin stopped");
+	}
+};
+//#endregion
+export { ChannelLifecycleSupervisor };
+
+//# sourceMappingURL=lifecycle-supervisor.js.map

package/dist/src/channels/lifecycle-supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-supervisor.js","names":[],"sources":["../../../src/channels/lifecycle-supervisor.ts"],"sourcesContent":["/**\n * ChannelLifecycleSupervisor — owns the start/stop/restart state machine for\n * every channel plugin.\n *\n * Concerns:\n *   - `initialize()` — call each plugin's `init(...)` once and remember success\n *   - Two-phase `start()` + `startDeferredConnects()` for channels whose\n *     `meta.deferConnectUntilAfterListen` is true (HTTP listener has to be up\n *     before they dial out)\n *   - Per-channel manual stop / start (UI-driven; suppresses auto-restart)\n *   - Exponential restart backoff via {@link CHANNEL_RESTART_POLICY}\n *   - Soft restart (called from heartbeat) — stop + startPlugin, manual-stop guarded\n *\n * Heartbeat probes themselves live in {@link ChannelHeartbeatScheduler}; this\n * supervisor schedules them via `onPluginStarted` / `onPluginStopped` callbacks\n * passed in by the caller.\n *\n * Extracted from `ChannelManager` so the manager can be a thin composition root.\n */\n\nimport type { Config } from '../config/schema.js';\nimport type { MessageBus } from '../infra/bus/index.js';\n\nimport type {\n  ChannelPlugin,\n  ChannelPluginInitOptions,\n  ChannelPluginSessionModelHooks,\n  ChannelPluginStartOptions,\n} from './plugin-types.js';\nimport type { ChannelPluginRegistry } from './plugin-registry.js';\nimport { CHANNEL_RESTART_POLICY, computeBackoff } from './restart-policy.js';\nimport { createLogger } from '../utils/logger.js';\n\nconst log = createLogger('ChannelLifecycleSupervisor');\n\nfunction asChannelConfig(raw: unknown): Record<string, unknown> | undefined {\n  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {\n    return raw as Record<string, unknown>;\n  }\n  return undefined;\n}\n\nexport interface ChannelLifecycleSupervisorOptions {\n  bus: MessageBus;\n  registry: ChannelPluginRegistry;\n  /** Effective config snapshot (per-channel `channels.<id>.*`). */\n  getConfig: () => Config;\n  /** Hooks for sub-classes / external observers: heartbeat scheduling, etc. */\n  onPluginStarted?: (plugin: ChannelPlugin) => void;\n  onPluginStopped?: (pluginId: string) => void;\n  /** Optional session-model hooks forwarded into `plugin.init()`. */\n  getSessionModelHooks?: () => ChannelPluginSessionModelHooks | undefined;\n}\n\nexport class ChannelLifecycleSupervisor {\n  private readonly opts: ChannelLifecycleSupervisorOptions;\n  /** Plugin ids whose `init()` completed (used by start/stop loops). */\n  private readonly initializedPluginIds = new Set<string>();\n  private readonly restartAttempts = new Map<string, number>();\n  /** When set, failed-start auto-restart is suppressed for that channel id. */\n  private readonly manuallyStopped = new Set<string>();\n  /** Plugins that skipped `start()` until `startDeferredConnects()`. */\n  private readonly deferredConnectPending = new Set<string>();\n  private initialized = false;\n  private running = false;\n\n  constructor(opts: ChannelLifecycleSupervisorOptions) {\n    this.opts = opts;\n  }\n\n  isInitialized(pluginId: string): boolean {\n    return this.initializedPluginIds.has(pluginId);\n  }\n\n  snapshot(): {\n    initialized: boolean;\n    running: boolean;\n    initializedPluginIds: string[];\n    manuallyStopped: string[];\n    restartAttempts: Record<string, number>;\n  } {\n    return {\n      initialized: this.initialized,\n      running: this.running,\n      initializedPluginIds: [...this.initializedPluginIds],\n      manuallyStopped: [...this.manuallyStopped],\n      restartAttempts: Object.fromEntries(this.restartAttempts),\n    };\n  }\n\n  /** Channel ids that would run and declare `meta.deferConnectUntilAfterListen` (for logging / metrics). */\n  listDeferConnectChannelIds(cfg: Config): string[] {\n    const out: string[] = [];\n    for (const [id, plugin] of this.opts.registry.entries()) {\n      const channelConfig = asChannelConfig(cfg.channels?.[id]);\n      if (!this.shouldRunChannelPlugin(plugin, channelConfig)) continue;\n      if (plugin.meta.deferConnectUntilAfterListen === true) {\n        out.push(id);\n      }\n    }\n    return out;\n  }\n\n  async initialize(): Promise<void> {\n    if (this.initialized) {\n      log.warn(\n        { pluginCount: this.opts.registry.ids().length },\n        'initialize() called again; channels already initialized — skipping',\n      );\n      return;\n    }\n\n    const cfg = this.opts.getConfig();\n    const initPromises: Promise<void>[] = [];\n\n    for (const [id, plugin] of this.opts.registry.entries()) {\n      const channelConfig = asChannelConfig(cfg.channels?.[id]);\n      // Always init so `onConfigUpdated` runs on hot reload (e.g. Weixin turned off after QR-login\n      // started monitors while the plugin was previously skipped here and had no bus/`initialized` id).\n      initPromises.push(this.initializePlugin(plugin, channelConfig ?? {}));\n    }\n\n    await Promise.allSettled(initPromises);\n    this.initialized = true;\n    log.info('All channel plugins initialized');\n  }\n\n  /** Phase 1: start every enabled channel except those in `deferConnectPluginIds`. */\n  async start(options?: { deferConnectPluginIds?: ReadonlySet<string> }): Promise<void> {\n    if (!this.initialized) {\n      throw new Error('Channels not initialized');\n    }\n    if (this.running) {\n      log.warn(\n        { pluginCount: this.opts.registry.ids().length },\n        'start() called while channels already running — skipping',\n      );\n      return;\n    }\n\n    const deferIds = options?.deferConnectPluginIds ?? new Set<string>();\n    this.deferredConnectPending.clear();\n\n    const cfg = this.opts.getConfig();\n    const startPromises: Promise<void>[] = [];\n\n    for (const [id, plugin] of this.opts.registry.entries()) {\n      const channelConfig = asChannelConfig(cfg.channels?.[id]);\n      if (!this.shouldRunChannelPlugin(plugin, channelConfig)) continue;\n\n      if (deferIds.has(id)) {\n        this.deferredConnectPending.add(id);\n        log.info({ channel: id }, 'Channel connect deferred until HTTP listen');\n        continue;\n      }\n\n      startPromises.push(\n        this.startPlugin(plugin, {}).catch((err) => {\n          log.error({ channel: id, err }, 'Failed to start channel plugin');\n        }),\n      );\n    }\n\n    await Promise.allSettled(startPromises);\n    this.running = true;\n    log.info(\n      { deferred: [...this.deferredConnectPending] },\n      this.deferredConnectPending.size > 0\n        ? 'Channel plugins started (deferred connects pending)'\n        : 'All channel plugins started',\n    );\n  }\n\n  /** Phase 2: `start()` for channels deferred at Phase 1. No-op if none pending. */\n  async startDeferredConnects(): Promise<void> {\n    if (this.deferredConnectPending.size === 0) return;\n    if (!this.running) {\n      log.warn('startDeferredConnects called before channel phase-1 start; skipping');\n      return;\n    }\n    const ids = [...this.deferredConnectPending];\n    this.deferredConnectPending.clear();\n    const cfg = this.opts.getConfig();\n    const startPromises: Promise<void>[] = [];\n    for (const id of ids) {\n      const plugin = this.opts.registry.get(id);\n      if (!plugin) continue;\n      const channelConfig = asChannelConfig(cfg.channels?.[id]);\n      if (!this.shouldRunChannelPlugin(plugin, channelConfig)) continue;\n      startPromises.push(\n        this.startPlugin(plugin, {}).catch((err) => {\n          log.error({ channel: id, err }, 'Failed to start deferred channel plugin');\n        }),\n      );\n    }\n    await Promise.allSettled(startPromises);\n    log.info({ channels: ids }, 'Deferred channel connects completed');\n  }\n\n  async stop(): Promise<void> {\n    if (!this.running) return;\n\n    this.deferredConnectPending.clear();\n\n    const stopPromises: Promise<void>[] = [];\n    for (const id of this.initializedPluginIds) {\n      const plugin = this.opts.registry.get(id);\n      if (!plugin) continue;\n      stopPromises.push(\n        this.stopPlugin(plugin).catch((err) => {\n          log.error({ channel: id, err }, 'Failed to stop channel plugin');\n        }),\n      );\n    }\n\n    await Promise.allSettled(stopPromises);\n    this.running = false;\n    log.info('All channel plugins stopped');\n  }\n\n  /** Stop one channel and suppress automatic restart until `startChannel` is called. */\n  async stopChannel(channelId: string): Promise<void> {\n    this.manuallyStopped.add(channelId);\n    const plugin = this.opts.registry.get(channelId);\n    if (!plugin || !this.initializedPluginIds.has(channelId)) {\n      return;\n    }\n    await this.stopPlugin(plugin).catch((err) => {\n      log.error({ channel: channelId, err }, 'Failed to stop channel plugin');\n    });\n  }\n\n  /** Clear manual-stop and start one channel (requires prior `initialize()`). */\n  async startChannel(channelId: string): Promise<void> {\n    this.manuallyStopped.delete(channelId);\n    const plugin = this.opts.registry.get(channelId);\n    if (!plugin) {\n      log.warn({ channel: channelId }, 'Unknown channel');\n      return;\n    }\n    if (!this.initialized) {\n      log.warn({ channel: channelId }, 'Channels not initialized');\n      return;\n    }\n    const cfg = this.opts.getConfig();\n    const channelConfig = asChannelConfig(cfg.channels?.[channelId]);\n    if (!this.shouldRunChannelPlugin(plugin, channelConfig)) {\n      log.debug({ channel: channelId }, 'Channel disabled in config, skipping start');\n      return;\n    }\n    if (!this.initializedPluginIds.has(channelId)) {\n      log.warn({ channel: channelId }, 'Channel was never initialized; call initialize() first');\n      return;\n    }\n    await this.startPlugin(plugin, {});\n  }\n\n  /** Called by heartbeat: stop + start without clearing manualStop. No-op if user stopped it. */\n  async softRestart(channelId: string): Promise<void> {\n    if (this.manuallyStopped.has(channelId)) return;\n    const plugin = this.opts.registry.get(channelId);\n    if (!plugin || !this.initializedPluginIds.has(channelId)) return;\n    try {\n      await this.stopPlugin(plugin);\n      await this.startPlugin(plugin, {});\n    } catch (err) {\n      log.error({ channel: channelId, err }, 'Channel soft restart after heartbeat failed');\n    }\n  }\n\n  /** Forward a config snapshot to every initialised plugin's `onConfigUpdated` hook. */\n  async forwardConfigUpdate(cfg: Config): Promise<void> {\n    for (const id of this.initializedPluginIds) {\n      const plugin = this.opts.registry.get(id);\n      if (plugin?.onConfigUpdated) {\n        await Promise.resolve(plugin.onConfigUpdated(cfg));\n      }\n    }\n  }\n\n  // ── Internals ───────────────────────────────────────────────────────────\n\n  /**\n   * Builtin channels require `channels.<id>.enabled`. Extension-managed channels\n   * run unless explicitly disabled.\n   */\n  private shouldRunChannelPlugin(\n    plugin: ChannelPlugin,\n    channelConfig: Record<string, unknown> | undefined,\n  ): boolean {\n    if (plugin.extensionManagedConfig) {\n      return channelConfig?.enabled !== false;\n    }\n    return !!channelConfig?.enabled;\n  }\n\n  private async initializePlugin(\n    plugin: ChannelPlugin,\n    channelConfig: Record<string, unknown>,\n  ): Promise<void> {\n    try {\n      const options: ChannelPluginInitOptions = {\n        bus: this.opts.bus,\n        config: this.opts.getConfig(),\n        channelConfig,\n        sessionModel: this.opts.getSessionModelHooks?.(),\n      };\n      await plugin.init(options);\n      this.initializedPluginIds.add(plugin.id);\n      log.debug({ channel: plugin.id }, 'Channel plugin initialized');\n    } catch (err) {\n      log.error({ channel: plugin.id, err }, 'Failed to initialize channel plugin');\n    }\n  }\n\n  private async startPlugin(\n    plugin: ChannelPlugin,\n    opts: { preserveRestartAttempts?: boolean },\n  ): Promise<void> {\n    const options: ChannelPluginStartOptions = {};\n    try {\n      await plugin.start(options);\n      if (!opts.preserveRestartAttempts) {\n        this.restartAttempts.delete(plugin.id);\n      }\n      this.opts.onPluginStarted?.(plugin);\n      log.debug({ channel: plugin.id }, 'Channel plugin started');\n    } catch (err) {\n      const attempt = (this.restartAttempts.get(plugin.id) ?? 0) + 1;\n      this.restartAttempts.set(plugin.id, attempt);\n      if (attempt <= CHANNEL_RESTART_POLICY.maxAttempts) {\n        const delayMs = computeBackoff(CHANNEL_RESTART_POLICY, attempt);\n        log.warn(\n          { channel: plugin.id, attempt, delayMs, err },\n          'Channel failed to start, scheduling restart',\n        );\n        setTimeout(() => {\n          if (this.manuallyStopped.has(plugin.id)) {\n            log.debug({ channel: plugin.id }, 'Skipping scheduled restart (manual stop)');\n            return;\n          }\n          void this.startPlugin(plugin, { preserveRestartAttempts: true }).catch((e) => {\n            log.error({ channel: plugin.id, err: e }, 'Channel restart attempt failed');\n          });\n        }, delayMs);\n      } else {\n        log.error({ channel: plugin.id, err }, 'Channel exceeded max restart attempts');\n      }\n    }\n  }\n\n  private async stopPlugin(plugin: ChannelPlugin): Promise<void> {\n    this.opts.onPluginStopped?.(plugin.id);\n    await plugin.stop();\n    log.info({ channel: plugin.id }, 'Channel plugin stopped');\n  }\n}\n"],"mappings":"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"}

package/dist/src/channels/manager.d.ts

@@ -1,100 +1,71 @@
 /**
- * Channel Manager - Channel plugin management based on ChannelPlugin interface
+ * Channel Manager — thin composition root for the channel subsystem.
+ *
+ * Wires together the four coordinators that own what used to be the eight
+ * concerns of this 707-line class:
+ *
+ *   - {@link ChannelPluginRegistry}        — plugins Map, register/get
+ *   - {@link ChannelLifecycleSupervisor}   — init/start/stop/restart-backoff
+ *   - {@link ChannelHeartbeatScheduler}    — per-account heartbeat probes
+ *   - {@link ChannelOutboundSender}        — TTS rewrite + persist + delivery
+ *
+ * The public surface (`registerPlugin`, `initialize`, `start`, `send`, etc.) is
+ * preserved so callers (`GatewayService`, CLI commands, channel plugins) are
+ * unchanged.
  */
-import type { Config } from '../config/index.js';
+import type { Config } from '../config/schema.js';
 import type { MessageBus } from '../infra/bus/index.js';
 import type { InboundMessage, OutboundMessage } from './transport-types.js';
 import type { ChannelPlugin, ChannelPluginSessionModelHooks, ChannelStreamHandle } from './plugin-types.js';
 import { ChannelHealthMonitor, type ChannelHealthState } from './health-monitor.js';
-/** Hooks wired from AgentService for `message_sending` / `message_sent` on outbound delivery. */
-export interface OutboundChannelHooks {
-    runMessageSending: (to: string, content: string, channel: string) => Promise<{
-        send: boolean;
-        content?: string;
-        reason?: string;
-    }>;
-    runMessageSent: (to: string, content: string, success: boolean, error: string | undefined, channel: string) => Promise<void>;
-}
+import { type OutboundChannelHooks } from './outbound-sender.js';
+export type { OutboundChannelHooks } from './outbound-sender.js';
 export declare class ChannelManager {
-    private plugins;
-    /** Plugins that completed `init()` successfully (skipped channels are not listed). */
-    private initializedPluginIds;
-    private bus;
     private config;
-    private initialized;
-    private running;
-    private restartAttempts;
-    /** When set, failed-start auto-restart is suppressed for that channel id. */
-    private manuallyStopped;
-    private heartbeatTimers;
-    private outboundHooks?;
-    private persistStore?;
-    private _lastHeartbeatRestartAt;
+    private readonly registry;
     private readonly healthMonitor;
+    private readonly lifecycle;
+    private readonly heartbeat;
+    private readonly outbound;
     private sessionModelHooks?;
-    /** Plugins that skipped `start()` until `startDeferredConnects()` (see `ChannelMeta.deferConnectUntilAfterListen`). */
-    private deferredConnectPending;
     constructor(config: Config, bus: MessageBus);
     setOutboundHooks(hooks: OutboundChannelHooks): void;
-    /** Call before `initialize()` so plugins can persist per-session model overrides (e.g. Telegram /models UI). */
+    /** Call before `initialize()` so plugins can persist per-session model overrides. */
     setSessionModelHooks(hooks: ChannelPluginSessionModelHooks | undefined): void;
     enableOutboundPersistence(agentDir: string): void;
-    /**
-     * Redeliver persisted outbound items (after channels are started). Best-effort; may duplicate if prior send succeeded but ack did not.
-     */
-    replayPendingOutboundMessages(): Promise<void>;
     registerPlugin(plugin: ChannelPlugin): void;
     getPlugin(id: string): ChannelPlugin | undefined;
-    /**
-     * Optional channel hook before AgentService consumes an inbound message (e.g. Feishu card actions).
-     */
-    dispatchInboundMessageAction(msg: InboundMessage): Promise<void>;
     getAllPlugins(): ChannelPlugin[];
+    /** Backward-compat alias for `getAllPlugins`. */
+    getAllChannels(): ChannelPlugin[];
+    /** Channel IDs whose runtime reports connected (e.g. Telegram polling active). */
+    getRunningChannels(): string[];
     initialize(): Promise<void>;
-    /**
-     * Builtin channels require `channels.<id>.enabled`. Extension-managed channels run unless explicitly disabled.
-     */
-    private shouldRunChannelPlugin;
-    private initializePlugin;
-    /**
-     * Channel ids that would run and declare `meta.deferConnectUntilAfterListen` (for logging / metrics).
-     */
-    listDeferConnectChannelIds(cfg: Config): string[];
-    /**
-     * Phase 1: start every enabled channel except those in `deferConnectPluginIds` (they stay pending).
-     */
     start(options?: {
         deferConnectPluginIds?: ReadonlySet<string>;
     }): Promise<void>;
-    /** Phase 2: run `start()` for channels deferred at `start()`. No-op if none pending. */
     startDeferredConnects(): Promise<void>;
-    private startPlugin;
     stop(): Promise<void>;
-    private stopPlugin;
-    private _clearHeartbeatTimers;
-    private _scheduleHeartbeat;
-    private _softRestartChannel;
-    private cloneOutbound;
+    stopChannel(channelId: string): Promise<void>;
+    startChannel(channelId: string): Promise<void>;
+    listDeferConnectChannelIds(cfg: Config): string[];
     send(msg: OutboundMessage, options?: {
         skipPersist?: boolean;
     }): Promise<void>;
+    replayPendingOutboundMessages(): Promise<void>;
     startStream(channel: string, chatId: string, accountId?: string, opts?: {
         threadId?: string;
         replyToMessageId?: string;
     }): ChannelStreamHandle | null;
     getChannelStatus(channel: string): Promise<Record<string, unknown>>;
+    /**
+     * Optional channel hook before `AgentService` consumes an inbound message
+     * (e.g. Feishu card-action triggers).
+     */
+    dispatchInboundMessageAction(msg: InboundMessage): Promise<void>;
     updateConfig(config: Config): Promise<void>;
     /** Replace in-memory config without running plugin `onConfigUpdated` hooks. */
     setRuntimeConfig(config: Config): void;
-    private applyTtsIfNeeded;
-    /**
-     * Stop a single channel and suppress automatic restart until `startChannel` is called.
-     */
-    stopChannel(channelId: string): Promise<void>;
-    /**
-     * Clear manual-stop and start one channel (requires prior `initialize()`).
-     */
-    startChannel(channelId: string): Promise<void>;
     getRuntimeSnapshot(): {
         initialized: boolean;
         running: boolean;
@@ -105,10 +76,5 @@ export declare class ChannelManager {
         channelHealth: Record<string, ChannelHealthState>;
     };
     getHealthMonitor(): ChannelHealthMonitor;
-    /**
-     * Channel IDs whose runtime reports connected (e.g. Telegram polling active).
-     */
-    getRunningChannels(): string[];
-    getAllChannels(): ChannelPlugin[];
 }
 export declare function createChannelManager(config: Config, bus: MessageBus): ChannelManager;