@dobby.ai/dobby 0.2.0 → 0.3.0

package/README.md

@@ -394,6 +394,9 @@ npm run start -- cron add daily-report \
 
 ## Discord 连接器的当前行为
 
+- 所有 connector 都会经过宿主侧 health supervisor 包装
+  - 统一暴露 `starting / ready / degraded / reconnecting / failed / stopped` 状态
+  - 若 connector 长时间停留在 `starting`、`degraded`、`reconnecting` 或 `failed`，宿主会 stop 并重建实例
 - guild channel 仍按显式 binding 匹配
 - DM 可通过 `bindings.default` 回落到默认 route
 - 线程消息使用父频道 ID 做 binding 查找

package/dist/src/core/connector-supervisor.js

@@ -0,0 +1,411 @@
+const DEFAULT_MONITOR_INTERVAL_MS = 5_000;
+const DEFAULT_START_TIMEOUT_MS = 30_000;
+const DEFAULT_DEGRADED_RESTART_THRESHOLD_MS = 90_000;
+const DEFAULT_RECONNECTING_RESTART_THRESHOLD_MS = 180_000;
+const DEFAULT_RESTART_BACKOFF_MS = 5_000;
+const DEFAULT_MAX_RESTART_BACKOFF_MS = 60_000;
+function createHealth(status, detail) {
+    const now = Date.now();
+    return {
+        status,
+        statusSinceMs: now,
+        updatedAtMs: now,
+        ...(detail ? { detail } : {}),
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class SupervisedConnector {
+    descriptor;
+    createInstance;
+    logger;
+    monitorIntervalMs;
+    startTimeoutMs;
+    degradedRestartThresholdMs;
+    reconnectingRestartThresholdMs;
+    restartBackoffMs;
+    maxRestartBackoffMs;
+    current;
+    ctx = null;
+    health = createHealth("stopped");
+    started = false;
+    stopping = false;
+    restarting = false;
+    generation = 0;
+    monitorTimer = null;
+    restartTimer = null;
+    restartFailures = 0;
+    restartCount = 0;
+    activeRestart = null;
+    constructor(options) {
+        this.current = options.initialConnector;
+        this.createInstance = options.createInstance;
+        this.logger = options.logger;
+        this.monitorIntervalMs = options.monitorIntervalMs ?? DEFAULT_MONITOR_INTERVAL_MS;
+        this.startTimeoutMs = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+        this.degradedRestartThresholdMs = options.degradedRestartThresholdMs ?? DEFAULT_DEGRADED_RESTART_THRESHOLD_MS;
+        this.reconnectingRestartThresholdMs =
+            options.reconnectingRestartThresholdMs ?? DEFAULT_RECONNECTING_RESTART_THRESHOLD_MS;
+        this.restartBackoffMs = options.restartBackoffMs ?? DEFAULT_RESTART_BACKOFF_MS;
+        this.maxRestartBackoffMs = options.maxRestartBackoffMs ?? DEFAULT_MAX_RESTART_BACKOFF_MS;
+        this.descriptor = {
+            id: options.initialConnector.id,
+            platform: options.initialConnector.platform,
+            name: options.initialConnector.name,
+            capabilities: options.initialConnector.capabilities,
+        };
+    }
+    get id() {
+        return this.descriptor.id;
+    }
+    get platform() {
+        return this.descriptor.platform;
+    }
+    get name() {
+        return this.descriptor.name;
+    }
+    get capabilities() {
+        return this.descriptor.capabilities;
+    }
+    async start(ctx) {
+        if (this.started) {
+            this.logger.warn({ connectorId: this.id }, "Supervised connector start called while already started");
+            return;
+        }
+        this.ctx = ctx;
+        this.started = true;
+        this.stopping = false;
+        this.restartFailures = 0;
+        this.clearRestartTimer();
+        this.updateHealth({ status: "starting", detail: "Starting connector" });
+        this.generation += 1;
+        const generation = this.generation;
+        try {
+            await this.startConnectorInstance(this.current, generation, "initial connector start");
+            this.syncCurrentHealth("Connector started");
+            this.startMonitor();
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            this.updateHealth({
+                status: "failed",
+                detail: "Initial connector start failed",
+                lastError: message,
+                lastErrorAtMs: Date.now(),
+            });
+            this.started = false;
+            this.ctx = null;
+            throw error;
+        }
+    }
+    async send(message) {
+        try {
+            const result = await this.current.send(message);
+            this.noteOutbound();
+            return result;
+        }
+        catch (error) {
+            this.noteRuntimeError("Failed to send outbound message", error);
+            throw error;
+        }
+    }
+    async sendTyping(message) {
+        const sendTyping = this.current.sendTyping;
+        if (!sendTyping) {
+            return;
+        }
+        try {
+            await sendTyping.call(this.current, message);
+            this.noteOutbound();
+        }
+        catch (error) {
+            this.noteRuntimeError("Failed to send typing indicator", error);
+            throw error;
+        }
+    }
+    getHealth() {
+        this.syncCurrentHealth();
+        return { ...this.health, restartCount: this.restartCount };
+    }
+    async stop() {
+        if (!this.started && this.health.status === "stopped") {
+            return;
+        }
+        this.stopping = true;
+        this.started = false;
+        this.ctx = null;
+        this.generation += 1;
+        this.stopMonitor();
+        this.clearRestartTimer();
+        try {
+            await this.current.stop();
+            await this.activeRestart;
+        }
+        finally {
+            this.updateHealth({ status: "stopped", detail: "Connector stopped by host" });
+            this.stopping = false;
+        }
+    }
+    startMonitor() {
+        if (this.monitorTimer) {
+            return;
+        }
+        this.monitorTimer = setInterval(() => {
+            void this.monitor();
+        }, this.monitorIntervalMs);
+    }
+    stopMonitor() {
+        if (!this.monitorTimer) {
+            return;
+        }
+        clearInterval(this.monitorTimer);
+        this.monitorTimer = null;
+    }
+    async monitor() {
+        if (!this.started || this.stopping || this.restarting) {
+            return;
+        }
+        this.syncCurrentHealth();
+        const now = Date.now();
+        const unhealthyForMs = now - this.health.statusSinceMs;
+        switch (this.health.status) {
+            case "starting":
+                if (unhealthyForMs >= this.startTimeoutMs) {
+                    this.scheduleRestart("start_timeout", true);
+                }
+                return;
+            case "degraded":
+                if (unhealthyForMs >= this.degradedRestartThresholdMs) {
+                    this.scheduleRestart("degraded_timeout", true);
+                }
+                return;
+            case "reconnecting":
+                if (unhealthyForMs >= this.reconnectingRestartThresholdMs) {
+                    this.scheduleRestart("reconnecting_timeout", true);
+                }
+                return;
+            case "failed":
+                this.scheduleRestart("connector_failed", false);
+                return;
+            default:
+                return;
+        }
+    }
+    syncCurrentHealth(fallbackDetail) {
+        try {
+            const observed = this.current.getHealth?.();
+            if (!observed) {
+                if (this.started && !this.stopping && !this.restarting && this.health.status === "starting") {
+                    this.updateHealth({ status: "ready", detail: fallbackDetail ?? "Connector ready" });
+                }
+                return;
+            }
+            if (observed.status === "stopped" && this.started && !this.stopping) {
+                return;
+            }
+            this.updateHealth(observed);
+        }
+        catch (error) {
+            this.noteRuntimeError("Failed to read connector health", error);
+        }
+    }
+    createManagedContext(generation) {
+        return {
+            emitInbound: async (message) => {
+                if (generation !== this.generation || !this.ctx) {
+                    return;
+                }
+                this.noteInbound();
+                await this.ctx.emitInbound(message);
+            },
+            emitControl: async (event) => {
+                if (generation !== this.generation || !this.ctx) {
+                    return;
+                }
+                await this.ctx.emitControl(event);
+            },
+        };
+    }
+    noteInbound() {
+        const now = Date.now();
+        this.updateHealth({
+            status: "ready",
+            detail: "Observed inbound connector activity",
+            lastInboundAtMs: now,
+            lastReadyAtMs: this.health.lastReadyAtMs ?? now,
+        });
+    }
+    noteOutbound() {
+        const now = Date.now();
+        this.updateHealth({
+            status: "ready",
+            detail: "Observed outbound connector activity",
+            lastOutboundAtMs: now,
+            lastReadyAtMs: this.health.lastReadyAtMs ?? now,
+        });
+    }
+    noteRuntimeError(detail, error) {
+        const message = errorMessage(error);
+        this.updateHealth({
+            status: this.health.status === "reconnecting" ? "reconnecting" : "degraded",
+            detail,
+            lastError: message,
+            lastErrorAtMs: Date.now(),
+        });
+    }
+    updateHealth(next) {
+        const previous = this.health;
+        const now = next.updatedAtMs ?? Date.now();
+        const statusChanged = next.status !== previous.status;
+        const merged = {
+            ...previous,
+            ...next,
+            status: next.status,
+            statusSinceMs: next.statusSinceMs ?? (statusChanged ? now : previous.statusSinceMs),
+            updatedAtMs: now,
+            restartCount: this.restartCount,
+        };
+        this.health = merged;
+        if (statusChanged || merged.detail !== previous.detail) {
+            this.logHealthTransition(previous, merged);
+        }
+    }
+    logHealthTransition(previous, next) {
+        const payload = {
+            connectorId: this.id,
+            previousStatus: previous.status,
+            status: next.status,
+            detail: next.detail ?? null,
+            restartCount: this.restartCount,
+            lastError: next.lastError ?? null,
+        };
+        if (next.status === "failed") {
+            this.logger.error(payload, "Connector health changed");
+            return;
+        }
+        if (next.status === "degraded" || next.status === "reconnecting") {
+            this.logger.warn(payload, "Connector health changed");
+            return;
+        }
+        this.logger.info(payload, "Connector health changed");
+    }
+    scheduleRestart(reason, immediate) {
+        if (!this.started || this.stopping || this.restarting || this.restartTimer) {
+            return;
+        }
+        const delayMs = immediate ? 0 : this.computeRestartDelay();
+        this.updateHealth({
+            status: "reconnecting",
+            detail: delayMs > 0
+                ? `Supervisor scheduled connector restart in ${delayMs}ms (${reason})`
+                : `Supervisor restarting connector (${reason})`,
+        });
+        if (delayMs === 0) {
+            const restart = this.restart(reason);
+            this.activeRestart = restart.finally(() => {
+                if (this.activeRestart === restart) {
+                    this.activeRestart = null;
+                }
+            });
+            return;
+        }
+        this.logger.warn({ connectorId: this.id, reason, delayMs }, "Scheduling supervised connector restart");
+        this.restartTimer = setTimeout(() => {
+            this.restartTimer = null;
+            const restart = this.restart(reason);
+            this.activeRestart = restart.finally(() => {
+                if (this.activeRestart === restart) {
+                    this.activeRestart = null;
+                }
+            });
+        }, delayMs);
+    }
+    clearRestartTimer() {
+        if (!this.restartTimer) {
+            return;
+        }
+        clearTimeout(this.restartTimer);
+        this.restartTimer = null;
+    }
+    computeRestartDelay() {
+        return Math.min(this.restartBackoffMs * 2 ** this.restartFailures, this.maxRestartBackoffMs);
+    }
+    async restart(reason) {
+        if (!this.started || this.stopping || this.restarting || !this.ctx) {
+            return;
+        }
+        this.restarting = true;
+        this.clearRestartTimer();
+        const previous = this.current;
+        const nextGeneration = this.generation + 1;
+        this.generation = nextGeneration;
+        this.updateHealth({ status: "reconnecting", detail: `Supervisor restarting connector (${reason})` });
+        this.logger.warn({ connectorId: this.id, reason }, "Restarting connector through supervisor");
+        let shouldRetry = false;
+        try {
+            await previous.stop().catch((error) => {
+                this.logger.warn({ err: error, connectorId: this.id, reason }, "Failed to stop connector before restart");
+            });
+            if (!this.started || this.stopping || !this.ctx) {
+                return;
+            }
+            const candidate = await this.createInstance();
+            this.assertCompatible(candidate);
+            if (!this.started || this.stopping || !this.ctx) {
+                await this.safeStopConnector(candidate, "Failed to clean up replacement connector after stop during restart");
+                return;
+            }
+            this.updateHealth({ status: "starting", detail: `Starting replacement connector (${reason})` });
+            await this.startConnectorInstance(candidate, nextGeneration, `replacement connector start (${reason})`);
+            if (!this.started || this.stopping || !this.ctx || this.generation !== nextGeneration) {
+                await this.safeStopConnector(candidate, "Failed to clean up replacement connector after stop during replacement start");
+                return;
+            }
+            this.current = candidate;
+            this.restartFailures = 0;
+            this.restartCount += 1;
+            this.syncCurrentHealth("Replacement connector started");
+            this.logger.info({ connectorId: this.id, reason, restartCount: this.restartCount }, "Connector restarted");
+        }
+        catch (error) {
+            shouldRetry = true;
+            this.restartFailures += 1;
+            this.updateHealth({
+                status: "failed",
+                detail: `Connector restart failed (${reason})`,
+                lastError: errorMessage(error),
+                lastErrorAtMs: Date.now(),
+            });
+            this.logger.error({ err: error, connectorId: this.id, reason, restartFailures: this.restartFailures }, "Failed to restart connector");
+        }
+        finally {
+            this.restarting = false;
+        }
+        if (shouldRetry) {
+            this.scheduleRestart(`retry_after_${reason}`, false);
+        }
+    }
+    async startConnectorInstance(connector, generation, phase) {
+        try {
+            await connector.start(this.createManagedContext(generation));
+        }
+        catch (error) {
+            await this.safeStopConnector(connector, `Failed to clean up connector after ${phase}`);
+            throw error;
+        }
+    }
+    async safeStopConnector(connector, errorMessage) {
+        try {
+            await connector.stop();
+        }
+        catch (error) {
+            this.logger.warn({ err: error, connectorId: connector.id }, errorMessage);
+        }
+    }
+    assertCompatible(candidate) {
+        if (candidate.id !== this.id || candidate.platform !== this.platform || candidate.name !== this.name) {
+            throw new Error(`Replacement connector metadata mismatch for '${this.id}' (${candidate.id}/${candidate.platform}/${candidate.name})`);
+        }
+    }
+}

package/dist/src/core/gateway.js

@@ -26,11 +26,33 @@ export class Gateway {
             return;
         await this.options.dedupStore.load();
         this.options.dedupStore.startAutoFlush();
-        for (const connector of this.options.connectors) {
-            await connector.start({
-                emitInbound: async (message) => this.handleInbound(message),
-                emitControl: async (event) => this.handleControl(event),
-            });
+        const startedConnectors = [];
+        try {
+            for (const connector of this.options.connectors) {
+                await connector.start({
+                    emitInbound: async (message) => this.handleInbound(message),
+                    emitControl: async (event) => this.handleControl(event),
+                });
+                startedConnectors.push(connector);
+            }
+        }
+        catch (error) {
+            for (const connector of startedConnectors.reverse()) {
+                try {
+                    await connector.stop();
+                }
+                catch (stopError) {
+                    this.options.logger.warn({ err: stopError, connectorId: connector.id }, "Failed to roll back connector after startup failure");
+                }
+            }
+            this.options.dedupStore.stopAutoFlush();
+            try {
+                await this.options.dedupStore.flush();
+            }
+            catch (flushError) {
+                this.options.logger.warn({ err: flushError }, "Failed to flush dedup store after startup failure");
+            }
+            throw error;
         }
         this.started = true;
     }

package/dist/src/extension/registry.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { SupervisedConnector } from "../core/connector-supervisor.js";
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -108,13 +109,19 @@ export class ExtensionRegistry {
             if (!contribution) {
                 throw new Error(`Connector instance '${instanceId}' references unknown contribution '${instanceConfig.type}'`);
             }
-            const connector = await contribution.createInstance({
+            const attachmentsRoot = join(attachmentsBaseDir, instanceId);
+            const createInstance = () => contribution.createInstance({
                 instanceId,
                 config: instanceConfig.config,
                 host: context,
-                attachmentsRoot: join(attachmentsBaseDir, instanceId),
+                attachmentsRoot,
             });
-            instances.push(connector);
+            const connector = await createInstance();
+            instances.push(new SupervisedConnector({
+                initialConnector: connector,
+                createInstance,
+                logger: context.logger,
+            }));
         }
         return instances;
     }

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@dobby.ai/dobby",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "Discord-first local agent gateway built on pi packages",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/don7panic/dobby"
+  },
+  "homepage": "https://github.com/don7panic/dobby#readme",
+  "bugs": {
+    "url": "https://github.com/don7panic/dobby/issues"
+  },
   "bin": {
     "dobby": "dist/src/main.js"
   },