@dobby.ai/dobby 0.1.0

package/dist/src/core/tests/runtime-registry.test.js

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { RuntimeRegistry } from "../runtime-registry.js";
+function deferred() {
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    return { promise, resolve };
+}
+function createLogger() {
+    return {
+        error() { },
+        warn() { },
+        info() { },
+        debug() { },
+    };
+}
+function createConversationRuntime(id, abortCalls, closeCalls) {
+    return {
+        key: id,
+        routeId: "route.main",
+        route: {
+            projectRoot: "/tmp/project",
+            tools: "full",
+            mentions: "required",
+            provider: "provider.main",
+            sandbox: "host.builtin",
+        },
+        providerId: "provider.main",
+        sandboxId: "host.builtin",
+        runtime: {
+            async prompt() { },
+            subscribe() {
+                return () => { };
+            },
+            async abort() {
+                abortCalls.push(id);
+            },
+            dispose() { },
+        },
+        async close() {
+            closeCalls.push(id);
+        },
+    };
+}
+test("cancel aborts the active run and drops queued turns", async () => {
+    const registry = new RuntimeRegistry(createLogger());
+    const abortCalls = [];
+    const closeCalls = [];
+    let runtimeCount = 0;
+    const createRuntime = async () => {
+        runtimeCount += 1;
+        return createConversationRuntime(`runtime-${runtimeCount}`, abortCalls, closeCalls);
+    };
+    const firstStarted = deferred();
+    const releaseFirst = deferred();
+    const started = [];
+    const firstTurn = registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+        firstStarted.resolve(undefined);
+        await releaseFirst.promise;
+    });
+    await firstStarted.promise;
+    const secondTurn = registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+    });
+    const thirdTurn = registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+    });
+    assert.equal(await registry.cancel("conversation"), true);
+    assert.deepEqual(abortCalls, ["runtime-1"]);
+    releaseFirst.resolve(undefined);
+    await Promise.all([firstTurn, secondTurn, thirdTurn]);
+    assert.deepEqual(started, ["runtime-1"]);
+    assert.deepEqual(closeCalls, []);
+    await registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+    });
+    assert.deepEqual(started, ["runtime-1", "runtime-1"]);
+    assert.equal(runtimeCount, 1);
+});
+test("reset closes the current runtime and recreates it on the next turn", async () => {
+    const registry = new RuntimeRegistry(createLogger());
+    const abortCalls = [];
+    const closeCalls = [];
+    let runtimeCount = 0;
+    const createRuntime = async () => {
+        runtimeCount += 1;
+        return createConversationRuntime(`runtime-${runtimeCount}`, abortCalls, closeCalls);
+    };
+    const firstStarted = deferred();
+    const releaseFirst = deferred();
+    const started = [];
+    const firstTurn = registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+        firstStarted.resolve(undefined);
+        await releaseFirst.promise;
+    });
+    await firstStarted.promise;
+    const queuedTurn = registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+    });
+    const resetPromise = registry.reset("conversation");
+    releaseFirst.resolve(undefined);
+    assert.equal(await resetPromise, true);
+    await Promise.all([firstTurn, queuedTurn]);
+    assert.deepEqual(abortCalls, ["runtime-1"]);
+    assert.deepEqual(closeCalls, ["runtime-1"]);
+    assert.deepEqual(started, ["runtime-1"]);
+    await registry.run("conversation", createRuntime, async (runtime) => {
+        started.push(runtime.key);
+    });
+    assert.deepEqual(started, ["runtime-1", "runtime-2"]);
+    assert.equal(runtimeCount, 2);
+});

package/dist/src/core/tests/typing-controller.test.js

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { setTimeout as delay } from "node:timers/promises";
+import test from "node:test";
+import { createTypingKeepAliveController } from "../typing-controller.js";
+function createLogger() {
+    return {
+        error() { },
+        warn() { },
+        info() { },
+        debug() { },
+    };
+}
+function createInbound() {
+    return {
+        connectorId: "discord.main",
+        platform: "discord",
+        accountId: "discord.main",
+        source: {
+            type: "channel",
+            id: "123",
+        },
+        chatId: "123",
+        messageId: "m-1",
+        userId: "u-1",
+        userName: "tester",
+        text: "hello",
+        attachments: [],
+        timestampMs: Date.now(),
+        raw: {},
+        isDirectMessage: false,
+        mentionedBot: true,
+    };
+}
+function createConnector(sentTyping) {
+    return {
+        id: "discord.main",
+        platform: "discord",
+        name: "discord",
+        capabilities: {
+            updateStrategy: "edit",
+            supportedSources: ["channel"],
+            supportsThread: true,
+            supportsTyping: true,
+            supportsFileUpload: true,
+            maxTextLength: 2000,
+        },
+        async start() { },
+        async send() {
+            return { messageId: "reply-1" };
+        },
+        async sendTyping() {
+            sentTyping.push(Date.now());
+        },
+        async stop() { },
+    };
+}
+test("typing is sent before the first visible output when response is slow", async () => {
+    const sentTyping = [];
+    const controller = createTypingKeepAliveController(createConnector(sentTyping), createInbound(), createLogger(), {
+        initialDelayMs: 0,
+        keepaliveIntervalMs: 200,
+    });
+    try {
+        await controller.prime();
+        assert.equal(sentTyping.length, 1);
+    }
+    finally {
+        controller.stop();
+    }
+});
+test("visible output before prime suppresses typing", async () => {
+    const sentTyping = [];
+    const controller = createTypingKeepAliveController(createConnector(sentTyping), createInbound(), createLogger(), {
+        initialDelayMs: 0,
+        keepaliveIntervalMs: 200,
+    });
+    try {
+        controller.markVisibleOutput();
+        await controller.prime();
+        assert.deepEqual(sentTyping, []);
+    }
+    finally {
+        controller.stop();
+    }
+});
+test("visible output stops further typing keepalive", async () => {
+    const sentTyping = [];
+    const controller = createTypingKeepAliveController(createConnector(sentTyping), createInbound(), createLogger(), {
+        initialDelayMs: 0,
+        keepaliveIntervalMs: 15,
+    });
+    try {
+        await controller.prime();
+        const beforeVisibleOutput = sentTyping.length;
+        assert.equal(beforeVisibleOutput > 0, true);
+        controller.markVisibleOutput();
+        await delay(30);
+        assert.equal(sentTyping.length, beforeVisibleOutput);
+    }
+    finally {
+        controller.stop();
+    }
+});

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export const BUILTIN_HOST_SANDBOX_ID = "host.builtin";

package/dist/src/core/typing-controller.js

@@ -0,0 +1,88 @@
+const DEFAULT_TYPING_INITIAL_DELAY_MS = 0;
+const DEFAULT_TYPING_KEEPALIVE_INTERVAL_MS = 8_000;
+export function createTypingKeepAliveController(connector, message, logger, options = {}) {
+    const sendTypingMethod = connector.sendTyping;
+    if (!connector.capabilities.supportsTyping || !sendTypingMethod) {
+        return {
+            prime: async () => { },
+            markVisibleOutput: () => { },
+            stop: () => { },
+        };
+    }
+    const typingTarget = {
+        platform: message.platform,
+        accountId: message.accountId,
+        chatId: message.chatId,
+        ...(message.threadId ? { threadId: message.threadId } : {}),
+    };
+    const initialDelayMs = options.initialDelayMs ?? DEFAULT_TYPING_INITIAL_DELAY_MS;
+    const keepaliveIntervalMs = options.keepaliveIntervalMs ?? DEFAULT_TYPING_KEEPALIVE_INTERVAL_MS;
+    let stopped = false;
+    let visibleOutputSent = false;
+    let inFlight = false;
+    let keepaliveTimer = null;
+    const clearKeepalive = () => {
+        if (!keepaliveTimer) {
+            return;
+        }
+        clearInterval(keepaliveTimer);
+        keepaliveTimer = null;
+    };
+    const sendTyping = async () => {
+        if (stopped || visibleOutputSent || inFlight) {
+            return;
+        }
+        inFlight = true;
+        try {
+            await sendTypingMethod.call(connector, typingTarget);
+        }
+        catch (error) {
+            logger.warn({
+                err: error,
+                connectorId: message.connectorId,
+                chatId: message.chatId,
+                threadId: message.threadId,
+            }, "Failed to send typing indicator");
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    const startKeepalive = () => {
+        if (keepaliveTimer || stopped || visibleOutputSent) {
+            return;
+        }
+        keepaliveTimer = setInterval(() => {
+            void sendTyping();
+        }, keepaliveIntervalMs);
+    };
+    return {
+        prime: async () => {
+            if (stopped || visibleOutputSent) {
+                return;
+            }
+            if (initialDelayMs > 0) {
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, initialDelayMs);
+                    if (stopped || visibleOutputSent) {
+                        clearTimeout(timer);
+                        resolve();
+                    }
+                });
+            }
+            await sendTyping();
+            startKeepalive();
+        },
+        markVisibleOutput: () => {
+            if (visibleOutputSent) {
+                return;
+            }
+            visibleOutputSent = true;
+            clearKeepalive();
+        },
+        stop: () => {
+            stopped = true;
+            clearKeepalive();
+        },
+    };
+}

package/dist/src/cron/config.js

@@ -0,0 +1,114 @@
+import { dirname, isAbsolute, resolve } from "node:path";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { z } from "zod";
+const rawCronConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    storeFile: z.string().min(1).optional(),
+    runLogFile: z.string().min(1).optional(),
+    pollIntervalMs: z.number().int().positive().default(10_000),
+    maxConcurrentRuns: z.number().int().positive().default(1),
+    runMissedOnStartup: z.boolean().default(true),
+    jobTimeoutMs: z.number().int().positive().default(10 * 60 * 1000),
+});
+function expandHome(value) {
+    if (value === "~") {
+        return homedir();
+    }
+    if (value.startsWith("~/") || value.startsWith("~\\")) {
+        return resolve(homedir(), value.slice(2));
+    }
+    return value;
+}
+function gatewayConfigBaseDir(gatewayConfigPath) {
+    const configDir = dirname(resolve(gatewayConfigPath));
+    return configDir.endsWith("/config") || configDir.endsWith("\\config")
+        ? resolve(configDir, "..")
+        : configDir;
+}
+function resolvePathFromBase(baseDir, value) {
+    const expanded = expandHome(value);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(baseDir, expanded);
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultCronConfigPayload() {
+    return {
+        enabled: true,
+        storeFile: "./data/state/cron-jobs.json",
+        runLogFile: "./data/state/cron-runs.jsonl",
+        pollIntervalMs: 10_000,
+        maxConcurrentRuns: 1,
+        runMissedOnStartup: true,
+        jobTimeoutMs: 10 * 60 * 1000,
+    };
+}
+async function ensureCronConfigFile(configPath) {
+    if (await fileExists(configPath)) {
+        return;
+    }
+    await mkdir(dirname(configPath), { recursive: true });
+    const payload = `${JSON.stringify(defaultCronConfigPayload(), null, 2)}\n`;
+    await writeFile(configPath, payload, "utf-8");
+}
+function resolveCronConfigPath(options) {
+    if (options.explicitCronConfigPath && options.explicitCronConfigPath.trim().length > 0) {
+        const rawPath = options.explicitCronConfigPath.trim();
+        const expanded = expandHome(rawPath);
+        const configPath = isAbsolute(expanded) ? resolve(expanded) : resolve(process.cwd(), expanded);
+        return { configPath, source: "explicit" };
+    }
+    const envPath = process.env.DOBBY_CRON_CONFIG_PATH?.trim();
+    if (envPath) {
+        const expanded = expandHome(envPath);
+        const configPath = isAbsolute(expanded) ? resolve(expanded) : resolve(process.cwd(), expanded);
+        return { configPath, source: "env" };
+    }
+    const candidate = resolve(dirname(resolve(options.gatewayConfigPath)), "cron.json");
+    if (process.env.DOBBY_CRON_CONFIG_PATH === undefined && options.explicitCronConfigPath === undefined) {
+        // no-op branch to make intent explicit for the resolution order
+    }
+    return {
+        configPath: candidate,
+        source: "gateway",
+    };
+}
+function normalizeCronConfig(gatewayConfigPath, gatewayConfig, raw) {
+    const baseDir = gatewayConfigBaseDir(gatewayConfigPath);
+    const defaultStoreFile = resolve(gatewayConfig.data.stateDir, "cron-jobs.json");
+    const defaultRunLogFile = resolve(gatewayConfig.data.stateDir, "cron-runs.jsonl");
+    return {
+        enabled: raw.enabled,
+        storeFile: raw.storeFile ? resolvePathFromBase(baseDir, raw.storeFile) : defaultStoreFile,
+        runLogFile: raw.runLogFile ? resolvePathFromBase(baseDir, raw.runLogFile) : defaultRunLogFile,
+        pollIntervalMs: raw.pollIntervalMs,
+        maxConcurrentRuns: raw.maxConcurrentRuns,
+        runMissedOnStartup: raw.runMissedOnStartup,
+        jobTimeoutMs: raw.jobTimeoutMs,
+    };
+}
+export async function loadCronConfig(options) {
+    const resolved = resolveCronConfigPath(options);
+    const gatewayFallbackPath = resolve(options.gatewayConfig.data.stateDir, "cron.config.json");
+    let configPath = resolved.configPath;
+    let source = resolved.source;
+    if (source === "gateway" && !(await fileExists(configPath))) {
+        configPath = gatewayFallbackPath;
+        source = "state";
+    }
+    await ensureCronConfigFile(configPath);
+    const raw = await readFile(configPath, "utf-8");
+    const parsed = rawCronConfigSchema.parse(JSON.parse(raw));
+    return {
+        configPath,
+        source,
+        config: normalizeCronConfig(options.gatewayConfigPath, options.gatewayConfig, parsed),
+    };
+}

package/dist/src/cron/schedule.js

@@ -0,0 +1,49 @@
+import { CronExpressionParser } from "cron-parser";
+const BACKOFF_STEPS_MS = [30_000, 60_000, 5 * 60_000, 15 * 60_000];
+function parseAtTimestamp(at) {
+    const timestamp = Date.parse(at);
+    if (!Number.isFinite(timestamp)) {
+        throw new Error(`Invalid at schedule timestamp '${at}'`);
+    }
+    return timestamp;
+}
+function nextCronAtMs(expr, currentDateMs, tz) {
+    const parsed = CronExpressionParser.parse(expr, {
+        currentDate: new Date(currentDateMs),
+        ...(tz ? { tz } : {}),
+    });
+    return parsed.next().toDate().getTime();
+}
+export function computeInitialNextRunAtMs(schedule, nowMs) {
+    if (schedule.kind === "at") {
+        return parseAtTimestamp(schedule.at);
+    }
+    if (schedule.kind === "every") {
+        return nowMs + schedule.everyMs;
+    }
+    return nextCronAtMs(schedule.expr, nowMs, schedule.tz);
+}
+export function computeNextRunAfterSuccessMs(schedule, nowMs) {
+    if (schedule.kind === "at") {
+        return undefined;
+    }
+    if (schedule.kind === "every") {
+        return nowMs + schedule.everyMs;
+    }
+    return nextCronAtMs(schedule.expr, nowMs, schedule.tz);
+}
+export function computeBackoffDelayMs(consecutiveErrors) {
+    const safeErrors = Number.isFinite(consecutiveErrors) && consecutiveErrors > 0 ? Math.floor(consecutiveErrors) : 1;
+    const index = Math.min(safeErrors - 1, BACKOFF_STEPS_MS.length - 1);
+    const fallback = BACKOFF_STEPS_MS[BACKOFF_STEPS_MS.length - 1];
+    return BACKOFF_STEPS_MS[index] ?? fallback;
+}
+export function describeSchedule(schedule) {
+    if (schedule.kind === "at") {
+        return `at ${schedule.at}`;
+    }
+    if (schedule.kind === "every") {
+        return `every ${schedule.everyMs}ms`;
+    }
+    return schedule.tz ? `cron '${schedule.expr}' (tz=${schedule.tz})` : `cron '${schedule.expr}'`;
+}

package/dist/src/cron/service.js

@@ -0,0 +1,196 @@
+import { computeBackoffDelayMs, computeInitialNextRunAtMs, computeNextRunAfterSuccessMs } from "./schedule.js";
+export class CronService {
+    options;
+    timer = null;
+    activeRuns = new Map();
+    tickInFlight = false;
+    started = false;
+    stopping = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async start() {
+        if (this.started) {
+            return;
+        }
+        await this.options.store.load();
+        await this.recoverOnStartup();
+        if (!this.options.config.enabled) {
+            this.options.logger.info("Cron scheduler is disabled by config");
+            this.started = true;
+            return;
+        }
+        const intervalMs = Math.min(this.options.config.pollIntervalMs, 60_000);
+        await this.tick();
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, intervalMs);
+        this.started = true;
+        this.options.logger.info({
+            pollIntervalMs: intervalMs,
+            maxConcurrentRuns: this.options.config.maxConcurrentRuns,
+        }, "Cron scheduler started");
+    }
+    async stop() {
+        this.stopping = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await Promise.allSettled(this.activeRuns.values());
+        this.activeRuns.clear();
+        this.started = false;
+    }
+    async triggerNow(jobId) {
+        await this.options.store.load();
+        const job = this.options.store.getJob(jobId);
+        if (!job) {
+            throw new Error(`Cron job '${jobId}' does not exist`);
+        }
+        await this.enqueueJob(job, Date.now());
+        const latestRun = [...this.activeRuns.values()].at(-1);
+        if (latestRun) {
+            await latestRun;
+        }
+    }
+    async recoverOnStartup() {
+        const now = Date.now();
+        for (const job of this.options.store.listJobs()) {
+            let changed = false;
+            const next = structuredClone(job);
+            if (next.state.runningAtMs !== undefined) {
+                next.state.runningAtMs = undefined;
+                next.state.lastStatus = "error";
+                next.state.lastError = "Recovered stale running state after restart";
+                changed = true;
+            }
+            if (next.state.nextRunAtMs === undefined) {
+                next.state.nextRunAtMs = computeInitialNextRunAtMs(next.schedule, now);
+                changed = true;
+            }
+            if (this.options.config.runMissedOnStartup
+                && next.enabled
+                && next.state.nextRunAtMs !== undefined
+                && next.state.nextRunAtMs <= now) {
+                next.state.nextRunAtMs = now;
+                changed = true;
+            }
+            if (changed) {
+                next.updatedAtMs = now;
+                await this.options.store.upsertJob(next);
+            }
+        }
+    }
+    async tick() {
+        if (this.stopping || !this.options.config.enabled) {
+            return;
+        }
+        if (this.tickInFlight) {
+            return;
+        }
+        this.tickInFlight = true;
+        try {
+            // Reload from disk on every tick so CLI mutations (cron run/update/pause/resume)
+            // made by a separate process become visible to the long-running scheduler.
+            await this.options.store.load();
+            const now = Date.now();
+            const dueJobs = this.options.store.listJobs().filter((job) => job.enabled
+                && job.state.runningAtMs === undefined
+                && job.state.nextRunAtMs !== undefined
+                && job.state.nextRunAtMs <= now);
+            for (const job of dueJobs) {
+                if (this.activeRuns.size >= this.options.config.maxConcurrentRuns) {
+                    break;
+                }
+                await this.enqueueJob(job, now);
+            }
+        }
+        finally {
+            this.tickInFlight = false;
+        }
+    }
+    async enqueueJob(job, now) {
+        const scheduledAtMs = job.state.nextRunAtMs ?? now;
+        const runContext = {
+            runId: `${job.id}:${scheduledAtMs}`,
+            jobId: job.id,
+            scheduledAtMs,
+        };
+        await this.options.store.updateJob(job.id, (current) => ({
+            ...current,
+            updatedAtMs: now,
+            state: {
+                ...current.state,
+                runningAtMs: now,
+            },
+        }));
+        const runPromise = this.executeJobRun(runContext)
+            .catch((error) => {
+            this.options.logger.warn({ err: error, jobId: runContext.jobId, runId: runContext.runId }, "Cron run failed");
+        })
+            .finally(() => {
+            this.activeRuns.delete(runContext.runId);
+        });
+        this.activeRuns.set(runContext.runId, runPromise);
+    }
+    async executeJobRun(run) {
+        const startedAtMs = Date.now();
+        const job = this.options.store.getJob(run.jobId);
+        if (!job) {
+            return;
+        }
+        let status = "ok";
+        let errorMessage;
+        try {
+            await this.options.gateway.handleScheduled({
+                jobId: job.id,
+                runId: run.runId,
+                prompt: job.prompt,
+                connectorId: job.delivery.connectorId,
+                routeId: job.delivery.routeId,
+                channelId: job.delivery.channelId,
+                ...(job.delivery.threadId ? { threadId: job.delivery.threadId } : {}),
+                timeoutMs: this.options.config.jobTimeoutMs,
+            });
+        }
+        catch (error) {
+            status = "error";
+            errorMessage = error instanceof Error ? error.message : String(error);
+        }
+        const endedAtMs = Date.now();
+        await this.options.store.updateJob(job.id, (current) => {
+            const isSuccess = status === "ok";
+            const previousErrors = current.state.consecutiveErrors ?? 0;
+            const nextErrorCount = isSuccess ? 0 : previousErrors + 1;
+            const nextRunAtMs = isSuccess
+                ? computeNextRunAfterSuccessMs(current.schedule, endedAtMs)
+                : current.schedule.kind === "at"
+                    ? undefined
+                    : endedAtMs + computeBackoffDelayMs(nextErrorCount);
+            return {
+                ...current,
+                enabled: current.schedule.kind === "at" ? false : current.enabled,
+                updatedAtMs: endedAtMs,
+                state: {
+                    ...current.state,
+                    runningAtMs: undefined,
+                    lastRunAtMs: endedAtMs,
+                    lastStatus: isSuccess ? "ok" : "error",
+                    lastError: isSuccess ? undefined : errorMessage,
+                    consecutiveErrors: nextErrorCount,
+                    nextRunAtMs,
+                },
+            };
+        });
+        const runRecord = {
+            runId: run.runId,
+            jobId: job.id,
+            jobName: job.name,
+            startedAtMs,
+            endedAtMs,
+            status,
+            ...(errorMessage ? { error: errorMessage } : {}),
+        };
+        await this.options.store.appendRunLog(runRecord);
+    }
+}