@dobby.ai/dobby 0.2.0 → 0.4.0

package/README.md

@@ -192,6 +192,12 @@ dobby config schema show <contributionId> [--json]
 
 配置变更建议直接编辑 `gateway.json`，再通过 `dobby doctor` 或 `dobby start` 做校验。
 
+连接器状态：
+
+```bash
+dobby connector status [connectorId] [--json]
+```
+
 扩展管理：
 
 ```bash
@@ -394,6 +400,11 @@ npm run start -- cron add daily-report \
 
 ## Discord 连接器的当前行为
 
+- 所有 connector 都会经过宿主侧 health supervisor 包装
+  - 统一暴露 `starting / ready / degraded / reconnecting / failed / stopped` 状态
+  - 若 connector 长时间停留在 `starting`、`degraded`、`reconnecting` 或 `failed`，宿主会 stop 并重建实例
+- 运行中的 gateway 会把 connector 状态快照写到 `<data.rootDir>/state/connectors-status.json`
+  - `dobby connector status` 会读取这份快照并展示当前 connector 健康状态
 - guild channel 仍按显式 binding 匹配
 - DM 可通过 `bindings.default` 回落到默认 route
 - 线程消息使用父频道 ID 做 binding 查找
@@ -440,7 +451,7 @@ npm run plugins:setup:local
 
 - `plugins/*` 是扩展源码，不是运行时加载入口
 - 本地扩展安装到 extension store 后，才会被宿主识别
-- `@dobby.ai/plugin-sdk` 在插件里按 `peerDependencies` 暴露，开发期通过 `file:../plugin-sdk` 提供
+- `@dobby.ai/plugin-sdk` 在插件里按非 optional 的 `peerDependencies` 暴露，开发期通过 `file:../plugin-sdk` 提供
 
 ## 检查与测试
 

package/dist/src/cli/commands/connector.js

@@ -0,0 +1,77 @@
+import { join } from "node:path";
+import { connectorStatusSnapshotExists, connectorStatusSnapshotPath, isConnectorStatusSnapshotStale, readConnectorStatusSnapshot, } from "../../core/connector-status.js";
+import { requireRawConfig, resolveConfigPath, resolveDataRootDir } from "../shared/config-io.js";
+function formatTimestamp(timestampMs) {
+    return new Date(timestampMs).toISOString();
+}
+function pad(value, width) {
+    return value.padEnd(width);
+}
+function renderTable(items) {
+    const rows = items.map((item) => ({
+        connectorId: item.connectorId,
+        platform: item.platform,
+        availability: item.availability,
+        health: item.health.status,
+        restarts: String(item.health.restartCount ?? 0),
+        updated: formatTimestamp(item.health.updatedAtMs),
+    }));
+    const widths = {
+        connectorId: Math.max("CONNECTOR".length, ...rows.map((row) => row.connectorId.length)),
+        platform: Math.max("PLATFORM".length, ...rows.map((row) => row.platform.length)),
+        availability: Math.max("AVAILABILITY".length, ...rows.map((row) => row.availability.length)),
+        health: Math.max("HEALTH".length, ...rows.map((row) => row.health.length)),
+        restarts: Math.max("RESTARTS".length, ...rows.map((row) => row.restarts.length)),
+        updated: Math.max("UPDATED".length, ...rows.map((row) => row.updated.length)),
+    };
+    const lines = [
+        [
+            pad("CONNECTOR", widths.connectorId),
+            pad("PLATFORM", widths.platform),
+            pad("AVAILABILITY", widths.availability),
+            pad("HEALTH", widths.health),
+            pad("RESTARTS", widths.restarts),
+            pad("UPDATED", widths.updated),
+        ].join("  "),
+    ];
+    for (const row of rows) {
+        lines.push([
+            pad(row.connectorId, widths.connectorId),
+            pad(row.platform, widths.platform),
+            pad(row.availability, widths.availability),
+            pad(row.health, widths.health),
+            pad(row.restarts, widths.restarts),
+            pad(row.updated, widths.updated),
+        ].join("  "));
+    }
+    return lines;
+}
+export async function runConnectorStatusCommand(options) {
+    const configPath = resolveConfigPath();
+    const rawConfig = await requireRawConfig(configPath);
+    const statusPath = connectorStatusSnapshotPath(join(resolveDataRootDir(configPath, rawConfig), "state"));
+    if (!(await connectorStatusSnapshotExists(statusPath))) {
+        throw new Error(`Connector status snapshot '${statusPath}' does not exist. Start 'dobby start' first.`);
+    }
+    const snapshot = await readConnectorStatusSnapshot(statusPath);
+    const items = options.connectorId
+        ? snapshot.items.filter((item) => item.connectorId === options.connectorId)
+        : snapshot.items;
+    if (options.connectorId && items.length === 0) {
+        throw new Error(`Connector '${options.connectorId}' was not found in '${statusPath}'.`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ...snapshot, items }));
+        return;
+    }
+    if (isConnectorStatusSnapshotStale(snapshot)) {
+        console.log("Warning: connector status snapshot is stale; the gateway may not be running.");
+    }
+    if (items.length === 0) {
+        console.log("(empty)");
+        return;
+    }
+    for (const line of renderTable(items)) {
+        console.log(line);
+    }
+}

package/dist/src/cli/commands/start.js

@@ -2,6 +2,7 @@ import { dirname, join } from "node:path";
 import { loadCronConfig } from "../../cron/config.js";
 import { CronService } from "../../cron/service.js";
 import { CronStore } from "../../cron/store.js";
+import { connectorStatusSnapshotPath, DEFAULT_CONNECTOR_STATUS_PUBLISH_INTERVAL_MS, DEFAULT_CONNECTOR_STATUS_STALE_AFTER_MS, writeConnectorStatusSnapshot, } from "../../core/connector-status.js";
 import { DedupStore } from "../../core/dedup-store.js";
 import { Gateway } from "../../core/gateway.js";
 import { BindingResolver, loadGatewayConfig, RouteResolver } from "../../core/routing.js";
@@ -90,6 +91,8 @@ function selectSandboxInstances(config) {
 export async function runStartCommand() {
     const configPath = resolveConfigPath();
     const config = await loadGatewayConfig(configPath);
+    const gatewayStartedAtMs = Date.now();
+    const connectorStatusPath = connectorStatusSnapshotPath(config.data.stateDir);
     await ensureDataDirs(config.data.rootDir);
     const logger = createLogger();
     const loader = new ExtensionLoader(logger, {
@@ -151,18 +154,67 @@ export async function runStartCommand() {
         gateway,
         logger,
     });
+    const publishConnectorStatuses = async () => {
+        await writeConnectorStatusSnapshot(connectorStatusPath, {
+            schemaVersion: 1,
+            generatedAtMs: Date.now(),
+            staleAfterMs: DEFAULT_CONNECTOR_STATUS_STALE_AFTER_MS,
+            gateway: {
+                pid: process.pid,
+                startedAtMs: gatewayStartedAtMs,
+            },
+            items: gateway.listConnectorStatuses(),
+        });
+    };
+    let connectorStatusTimer = null;
+    const startConnectorStatusPublisher = async () => {
+        try {
+            await publishConnectorStatuses();
+        }
+        catch (error) {
+            logger.warn({ err: error, connectorStatusPath }, "Failed to write initial connector status snapshot");
+        }
+        connectorStatusTimer = setInterval(() => {
+            void publishConnectorStatuses().catch((error) => {
+                logger.warn({ err: error, connectorStatusPath }, "Failed to refresh connector status snapshot");
+            });
+        }, DEFAULT_CONNECTOR_STATUS_PUBLISH_INTERVAL_MS);
+    };
+    const stopConnectorStatusPublisher = async () => {
+        if (connectorStatusTimer) {
+            clearInterval(connectorStatusTimer);
+            connectorStatusTimer = null;
+        }
+        try {
+            await publishConnectorStatuses();
+        }
+        catch (error) {
+            logger.warn({ err: error, connectorStatusPath }, "Failed to write final connector status snapshot");
+        }
+    };
     await gateway.start();
     await cronService.start();
+    await startConnectorStatusPublisher();
     logger.info({
         configPath,
         cronConfigPath: loadedCronConfig.configPath,
         cronConfigSource: loadedCronConfig.source,
         cronEnabled: loadedCronConfig.config.enabled,
     }, "Gateway started");
+    let shuttingDown = false;
     const shutdown = async (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
         logger.info({ signal }, "Shutting down gateway");
+        if (connectorStatusTimer) {
+            clearInterval(connectorStatusTimer);
+            connectorStatusTimer = null;
+        }
         await cronService.stop();
         await gateway.stop();
+        await stopConnectorStatusPublisher();
         await hostExecutor.close();
         await closeProviderInstances(providers, logger);
         await closeSandboxInstances(sandboxes, logger);

package/dist/src/cli/program.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { runConfigListCommand, runConfigSchemaListCommand, runConfigSchemaShowCommand, runConfigShowCommand, } from "./commands/config.js";
+import { runConnectorStatusCommand } from "./commands/connector.js";
 import { runCronAddCommand, runCronListCommand, runCronPauseCommand, runCronRemoveCommand, runCronResumeCommand, runCronRunCommand, runCronStatusCommand, runCronUpdateCommand, } from "./commands/cron.js";
 import { runDoctorCommand } from "./commands/doctor.js";
 import { runExtensionInstallCommand, runExtensionListCommand, runExtensionUninstallCommand, } from "./commands/extension.js";
@@ -127,6 +128,18 @@ export function buildProgram() {
             fix: Boolean(opts.fix),
         });
     });
+    const connectorCommand = program.command("connector").description("Inspect runtime connector status");
+    connectorCommand
+        .command("status")
+        .description("Show status for all connectors or one connector")
+        .argument("[connectorId]", "Connector instance ID")
+        .option("--json", "Output JSON", false)
+        .action(async (connectorId, opts) => {
+        await runConnectorStatusCommand({
+            ...(typeof connectorId === "string" ? { connectorId } : {}),
+            json: Boolean(opts.json),
+        });
+    });
     const cronCommand = program.command("cron").description("Manage scheduled cron jobs");
     cronCommand
         .command("add")

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

@@ -0,0 +1,132 @@
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export const CONNECTOR_STATUS_SNAPSHOT_FILENAME = "connectors-status.json";
+export const DEFAULT_CONNECTOR_STATUS_PUBLISH_INTERVAL_MS = 5_000;
+export const DEFAULT_CONNECTOR_STATUS_STALE_AFTER_MS = 15_000;
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function createFallbackHealth(detail) {
+    const now = Date.now();
+    return {
+        status: "stopped",
+        detail,
+        statusSinceMs: now,
+        updatedAtMs: now,
+    };
+}
+export function availabilityFromHealthStatus(status) {
+    switch (status) {
+        case "ready":
+            return "online";
+        case "degraded":
+            return "degraded";
+        case "reconnecting":
+            return "reconnecting";
+        case "starting":
+        case "failed":
+        case "stopped":
+        default:
+            return "offline";
+    }
+}
+export function connectorStatusSnapshotPath(stateDir) {
+    return join(resolve(stateDir), CONNECTOR_STATUS_SNAPSHOT_FILENAME);
+}
+export function statusItemFromConnector(connector) {
+    const health = connector.getHealth?.() ?? createFallbackHealth("Connector health is not available");
+    const availability = availabilityFromHealthStatus(health.status);
+    return {
+        connectorId: connector.id,
+        platform: connector.platform,
+        connectorName: connector.name,
+        availability,
+        online: availability === "online",
+        health,
+    };
+}
+async function writeAtomic(filePath, content) {
+    const absolutePath = resolve(filePath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    const tempPath = `${absolutePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    await writeFile(tempPath, content, "utf-8");
+    await rename(tempPath, absolutePath);
+}
+export async function writeConnectorStatusSnapshot(filePath, snapshot) {
+    await writeAtomic(filePath, `${JSON.stringify(snapshot, null, 2)}\n`);
+}
+export async function connectorStatusSnapshotExists(filePath) {
+    try {
+        await access(resolve(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseHealth(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    if (typeof value.status !== "string" || typeof value.statusSinceMs !== "number" || typeof value.updatedAtMs !== "number") {
+        return null;
+    }
+    return value;
+}
+function parseStatusItem(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    if (typeof value.connectorId !== "string"
+        || typeof value.platform !== "string"
+        || typeof value.connectorName !== "string"
+        || typeof value.availability !== "string"
+        || typeof value.online !== "boolean") {
+        return null;
+    }
+    const health = parseHealth(value.health);
+    if (!health) {
+        return null;
+    }
+    return {
+        connectorId: value.connectorId,
+        platform: value.platform,
+        connectorName: value.connectorName,
+        availability: value.availability,
+        online: value.online,
+        health,
+    };
+}
+export async function readConnectorStatusSnapshot(filePath) {
+    const raw = await readFile(resolve(filePath), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed) || parsed.schemaVersion !== 1 || typeof parsed.generatedAtMs !== "number" || typeof parsed.staleAfterMs !== "number") {
+        throw new Error(`Connector status snapshot '${resolve(filePath)}' has invalid metadata`);
+    }
+    if (!isRecord(parsed.gateway) || typeof parsed.gateway.pid !== "number" || typeof parsed.gateway.startedAtMs !== "number") {
+        throw new Error(`Connector status snapshot '${resolve(filePath)}' has invalid gateway metadata`);
+    }
+    if (!Array.isArray(parsed.items)) {
+        throw new Error(`Connector status snapshot '${resolve(filePath)}' must contain an items array`);
+    }
+    const items = parsed.items.map((item) => {
+        const normalized = parseStatusItem(item);
+        if (!normalized) {
+            throw new Error(`Connector status snapshot '${resolve(filePath)}' contains an invalid connector entry`);
+        }
+        return normalized;
+    });
+    return {
+        schemaVersion: 1,
+        generatedAtMs: parsed.generatedAtMs,
+        staleAfterMs: parsed.staleAfterMs,
+        gateway: {
+            pid: parsed.gateway.pid,
+            startedAtMs: parsed.gateway.startedAtMs,
+        },
+        items,
+    };
+}
+export function isConnectorStatusSnapshotStale(snapshot, now = Date.now()) {
+    return now - snapshot.generatedAtMs > snapshot.staleAfterMs;
+}

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

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { EventForwarder } from "../agent/event-forwarder.js";
+import { statusItemFromConnector } from "./connector-status.js";
 import { parseControlCommand } from "./control-command.js";
 import { createTypingKeepAliveController } from "./typing-controller.js";
 function isImageAttachment(attachment) {
@@ -26,11 +27,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;
     }
@@ -45,6 +68,11 @@ export class Gateway {
         await this.options.runtimeRegistry.closeAll();
         this.started = false;
     }
+    listConnectorStatuses() {
+        return this.options.connectors
+            .map((connector) => statusItemFromConnector(connector))
+            .sort((a, b) => a.connectorId.localeCompare(b.connectorId));
+    }
     async handleScheduled(request) {
         const connector = this.connectorsById.get(request.connectorId);
         if (!connector) {

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.4.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"
   },