Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

27.7 KB
Raw Blame
import { createHash, randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { logger } from '../utils/logger.js';
import { isSqliteAvailable, openSqlite, type SqliteDatabase } from '../utils/sqlite-driver.js';
import type { ChannelAttachment } from '../types/channel.js';
import type { BotTrigger } from './types.js';

export const QUEUE_DB_FILE = 'queue.db';

export interface DurableBotJob {
  id: string;
  botId: string;
  trigger: BotTrigger;
  prompt: string;
  fromBot?: string;
  /**
   * Files on disk for this job (`web/api/uploads.ts` wrote them). Paths, not bytes:
   * the queue survives a restart and the image is already stored.
   */
  attachments?: ChannelAttachment[];
  source?: { channelType: string; channelId: string };
  state: 'pending' | 'claimed' | 'dead';
  attempts: number;
  createdAt: number;
  leaseExpiresAt?: number;
  idempotencyKey: string;
  reasonCode?: string;
  settledAt?: number;
  /** Earliest time the job may run again (transient-retry backoff). */
  runAfter?: number;
}

export interface DurableMail {
  id: string;
  botId: string;
  from: string;
  content: string;
  createdAt: number;
}

export interface DlqEntry extends DurableBotJob {
  deadAt: number;
}

export interface QueueCounts {
  pending: number;
  claimed: number;
  dlq: number;
}

export interface BotQueueBackend {
  readonly name: string;
  /** Returns the stored job (existing one when duplicated by idempotency key). */
  enqueue(job: Omit<DurableBotJob, 'state'>): { job: DurableBotJob; duplicated: boolean };
  claim(jobId: string, leaseSeconds: number): void;
  /** done → removed; dead → moved to the capped DLQ. */
  settle(jobId: string, outcome: 'done' | 'dead', reasonCode?: string): void;
  /**
   * Durable in-place retry for a claimed job: attempts+1, back to pending,
   * with an optional run-after timestamp. No settle-then-reenqueue window —
   * a crash at any point still leaves the job in the queue.
   */
  retry(jobId: string, attempts: number, runAfterMs?: number): void;
  /** Jobs safe to resume: pending (due), or claimed whose lease has expired. */
  rehydratable(): DurableBotJob[];
  /** Startup only: claimed scheduled jobs and old scheduled retry entries, regardless of lease/backoff. */
  interruptedSchedules(): DurableBotJob[];
  /** Pending jobs whose run-after time has arrived (retry backoff elapsed). */
  dueJobs(): DurableBotJob[];
  /** All pending jobs for one bot, in creation order — explicit resume (/bots start), ignores retry backoff. */
  pendingJobs(botId: string): DurableBotJob[];
  /** Expired-lease claimed jobs → pending. Returns the count requeued. */
  requeueExpiredLeases(): number;
  heartbeatLease(jobId: string, leaseSeconds: number): void;
  listDlq(botId?: string): DlqEntry[];
  /** Read a DLQ entry without removing it (replay does lookup-then-remove so a bot mismatch never destroys the entry). */
  peekDlq(jobId: string): DurableBotJob | null;
  removeFromDlq(jobId: string): DurableBotJob | null;
  /** Drop every dead-lettered job (of one bot, or all). Returns the count removed. */
  clearDlq(botId?: string): number;
  /** Durable bot-to-bot mailbox (§2.6: a handoff must survive a crash). */
  enqueueMail(mail: Omit<DurableMail, 'id'>): string;
  drainMail(botId: string): DurableMail[];
  /** Remove every trace of a bot: jobs, mail, DLQ rows (delete lifecycle). */
  purgeBot(botId: string): void;
  counts(): QueueCounts;
  /**
   * Release native handles (the SQLite connection). Idempotent — a second
   * close is a no-op. On Windows an open handle keeps the file locked
   * (EBUSY on delete): teardown, fleet-delete cleanup, and shutdown must
   * close before any directory removal.
   */
  close(): void;
}

export const LEASE_SECONDS = 60;
const DLQ_CAP = 100;

/**
 * Two requests that differ only by their files are different jobs: the same caption
 * ("what is this?") with two different photos must not collapse into one. Files are keyed
 * by their bytes, not their path: every upload gets a fresh random name, so a path would
 * never let a retried request dedupe.
 */
/** A file's content hash, or its path when it can't be read (the turn will skip it anyway). */
function fileFingerprint(attachment: ChannelAttachment): string {
  try {
    return createHash('sha256').update(readFileSync(attachment.path)).digest('hex');
  } catch {
    return attachment.path;
  }
}

export function idempotencyKeyFor(
  botId: string,
  trigger: BotTrigger,
  prompt: string,
  fromBot?: string,
  attachments?: ChannelAttachment[],
): string {
  const files = (attachments ?? []).map(fileFingerprint).join(',');
  return createHash('sha256').update(`${botId}|${trigger}|${prompt}|${fromBot ?? ''}|${files}`).digest('hex').slice(0, 16);
}

function normalizeJob(raw: any): DurableBotJob {
  // SQLite rows use snake_case columns; JSON rows camelCase — map both.
  let source = raw.source;
  if (typeof source === 'string') {
    try { source = JSON.parse(source); } catch { source = undefined; }
  }
  let attachments = raw.attachments;
  if (typeof attachments === 'string') {
    try { attachments = JSON.parse(attachments); } catch { attachments = undefined; }
  }
  if (!Array.isArray(attachments) || attachments.length === 0) attachments = undefined;
  return {
    id: String(raw.id),
    botId: String(raw.botId ?? raw.bot_id),
    trigger: raw.trigger,
    prompt: raw.prompt ?? '',
    fromBot: raw.fromBot ?? raw.from_bot ?? undefined,
    attachments,
    source,
    state: raw.state ?? 'pending',
    attempts: raw.attempts ?? 0,
    createdAt: raw.createdAt ?? raw.created_at ?? Date.now(),
    leaseExpiresAt: raw.leaseExpiresAt ?? raw.lease_expires_at ?? undefined,
    idempotencyKey: raw.idempotencyKey ?? '',
    reasonCode: raw.reasonCode ?? raw.reason_code ?? undefined,
    settledAt: raw.settledAt ?? raw.settled_at ?? undefined,
    runAfter: raw.runAfter ?? raw.run_after ?? undefined,
  };
}

/**
 * Durable bot job queue — the "enqueue before ack" boundary
 * (BOTS-ARCHITECTURE.md §2.6). Backend chain: SQLite via the shared driver
 * (better-sqlite3 → bun:sqlite → node:sqlite, src/utils/sqlite-driver.ts)
 * → JSON-file lease store. Correctness never depends on SQLite: the queue is
 * single-writer (in-process BotManager), so durability (atomic rename +
 * fsync) and lease-expiry timestamp logic are all that is required.
 */
export class BotQueue {
  readonly backend: BotQueueBackend;
  /** The manager pauses future routines when a prior scheduled run is uncertain. */
  onInterruptedSchedule?: (job: DurableBotJob) => void;
  /** Post-close guard: in-flight turns' queue access degrades to no-ops. */
  private closed = false;

  constructor(botsRoot: string, dlqCap: number = DLQ_CAP) {
    const path = resolve(botsRoot);
    if (isSqliteAvailable()) {
      this.backend = new SqliteQueueBackend(path, dlqCap);
    } else {
      this.backend = new JsonFileQueueBackend(path, dlqCap);
    }
    logger.info({ backend: this.backend.name, path }, 'Bot queue initialized');
  }

  /** Release native handles (the SQLite connection). Idempotent. */
  close(): void {
    this.closed = true;
    this.backend.close();
  }

  enqueue(job: Omit<DurableBotJob, 'state'>): { job: DurableBotJob; duplicated: boolean } {
    if (this.closed) return { job: { ...job, state: 'pending' } as DurableBotJob, duplicated: false };
    return this.backend.enqueue(job);
  }

  claim(jobId: string, leaseSeconds: number = LEASE_SECONDS): void {
    this.backend.claim(jobId, leaseSeconds);
  }

  settle(jobId: string, outcome: 'done' | 'dead', reasonCode?: string): void {
    if (this.closed) return;
    this.backend.settle(jobId, outcome, reasonCode);
  }

  /** Durable in-place retry: no settle-then-reenqueue window. */
  retry(jobId: string, attempts: number, runAfterMs?: number): void {
    if (this.closed) return;
    this.backend.retry(jobId, attempts, runAfterMs);
  }

  /** Jobs to resume on startup: due pending, plus expired-lease claimed jobs. */
  resumeJobs(): DurableBotJob[] {
    this.excludeInterruptedSchedules(this.backend.interruptedSchedules());
    const expired = this.backend.requeueExpiredLeases();
    if (expired > 0) logger.info({ expired }, 'Requeued expired bot job leases');
    return this.excludeInterruptedSchedules(this.backend.rehydratable());
  }

  private excludeInterruptedSchedules(jobs: DurableBotJob[]): DurableBotJob[] {
    return jobs.filter((job) => {
      // A pending first attempt has not acted. Claimed work and old retry/
      // continuation entries may already have effects and require manual replay.
      if (job.trigger !== 'cron' || (job.state === 'pending' && job.attempts === 0 && job.runAfter === undefined)) return true;
      // Persist the routine pause first. If that fails, leave the job eligible
      // for quarantine again rather than losing the opportunity to stop future ticks.
      this.onInterruptedSchedule?.(job);
      this.backend.settle(job.id, 'dead', 'scheduled_interrupted');
      return false;
    });
  }

  /** Pending jobs whose retry backoff has elapsed (swept periodically). */
  dueJobs(): DurableBotJob[] {
    if (this.closed) return [];
    return this.excludeInterruptedSchedules(this.backend.dueJobs());
  }

  /** All pending jobs for one bot — explicit resume via /bots start. */
  pendingJobs(botId: string): DurableBotJob[] {
    if (this.closed) return [];
    return this.backend.pendingJobs(botId);
  }

  enqueueMail(mail: Omit<DurableMail, 'id'>): string {
    if (this.closed) return '';
    return this.backend.enqueueMail(mail);
  }

  drainMail(botId: string): DurableMail[] {
    if (this.closed) return [];
    return this.backend.drainMail(botId);
  }

  purgeBot(botId: string): void {
    if (this.closed) return;
    this.backend.purgeBot(botId);
  }

  listDlq(botId?: string): DlqEntry[] {
    if (this.closed) return [];
    return this.backend.listDlq(botId);
  }

  removeFromDlq(jobId: string): DurableBotJob | null {
    if (this.closed) return null;
    return this.backend.removeFromDlq(jobId);
  }

  peekDlq(jobId: string): DurableBotJob | null {
    if (this.closed) return null;
    return this.backend.peekDlq(jobId);
  }

  clearDlq(botId?: string): number {
    if (this.closed) return 0;
    return this.backend.clearDlq(botId);
  }

  heartbeatLease(jobId: string, leaseSeconds: number = LEASE_SECONDS): void {
    if (this.closed) return;
    this.backend.heartbeatLease(jobId, leaseSeconds);
  }

  counts(): QueueCounts {
    if (this.closed) return { pending: 0, claimed: 0, dlq: 0 };
    return this.backend.counts();
  }
}

// ---------------------------------------------------------------------------
// SQLite backend (shared driver, WAL)
// ---------------------------------------------------------------------------

export class SqliteQueueBackend implements BotQueueBackend {
  /** The engine name (`better-sqlite3`, `bun:sqlite`, `node:sqlite`). */
  readonly name: string;
  private db: SqliteDatabase;
  private dlqCap: number;
  // A disposed manager must never turn an in-flight turn's queue access into
  // a crash: post-close ops degrade to no-ops (an unsettled claim survives
  // via lease expiry and resumes on the next boot).
  private closed = false;

  /** `db` lets tests hand in an already-open handle; otherwise `<path>/queue.db` is opened via the driver. */
  constructor(path: string, dlqCap: number, db?: SqliteDatabase) {
    mkdirSync(path, { recursive: true });
    const handle = db ?? openSqlite(join(path, QUEUE_DB_FILE));
    if (!handle) throw new Error('No SQLite engine available for the bot queue');
    this.db = handle;
    this.name = handle.backend;
    this.db.pragma('journal_mode = WAL');
    this.db.exec(`
      CREATE TABLE IF NOT EXISTS bot_jobs (
        id TEXT PRIMARY KEY,
        bot_id TEXT NOT NULL,
        trigger TEXT NOT NULL,
        prompt TEXT NOT NULL,
        from_bot TEXT,
        source TEXT,
        state TEXT NOT NULL DEFAULT 'pending',
        attempts INTEGER NOT NULL DEFAULT 0,
        created_at INTEGER NOT NULL,
        lease_expires_at INTEGER,
        idempotency_key TEXT NOT NULL,
        reason_code TEXT,
        settled_at INTEGER,
        attachments TEXT
      );
      CREATE INDEX IF NOT EXISTS idx_bot_jobs_state ON bot_jobs (state, created_at);
      CREATE TABLE IF NOT EXISTS bot_mail (
        id TEXT PRIMARY KEY,
        bot_id TEXT NOT NULL,
        from_bot TEXT NOT NULL,
        content TEXT NOT NULL,
        created_at INTEGER NOT NULL
      );
      CREATE INDEX IF NOT EXISTS idx_bot_mail_bot ON bot_mail (bot_id, created_at);
      CREATE TABLE IF NOT EXISTS bot_dlq (
        id TEXT PRIMARY KEY,
        bot_id TEXT NOT NULL,
        trigger TEXT NOT NULL,
        prompt TEXT NOT NULL,
        from_bot TEXT,
        source TEXT,
        attempts INTEGER NOT NULL DEFAULT 0,
        created_at INTEGER NOT NULL,
        idempotency_key TEXT NOT NULL,
        reason_code TEXT,
        dead_at INTEGER NOT NULL
      );
    `);
    // Migration for queues created before run_after / bot_mail existed.
    try { this.db.exec('ALTER TABLE bot_jobs ADD COLUMN run_after INTEGER'); } catch { /* already present */ }
    try { this.db.exec('ALTER TABLE bot_jobs ADD COLUMN attachments TEXT'); } catch { /* already present */ }
    this.dlqCap = dlqCap;
  }

  enqueue(job: Omit<DurableBotJob, 'state'>): { job: DurableBotJob; duplicated: boolean } {
    const dup = this.db.prepare(
      `SELECT * FROM bot_jobs WHERE bot_id = ? AND idempotency_key = ? AND state IN ('pending','claimed') LIMIT 1`,
    ).get(job.botId, job.idempotencyKey) as any;
    if (dup) {
      return { job: normalizeJob(dup), duplicated: true };
    }
    const stored: DurableBotJob = { ...job, state: 'pending' };
    this.db.prepare(
      `INSERT INTO bot_jobs (id, bot_id, trigger, prompt, from_bot, source, state, attempts, created_at, lease_expires_at, idempotency_key, attachments)
       VALUES (?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?)`,
    ).run(
      stored.id, stored.botId, stored.trigger, stored.prompt,
      stored.fromBot ?? null, stored.source ? JSON.stringify(stored.source) : null,
      stored.attempts, stored.createdAt, stored.leaseExpiresAt ?? null, stored.idempotencyKey,
      stored.attachments?.length ? JSON.stringify(stored.attachments) : null,
    );
    return { job: stored, duplicated: false };
  }

  claim(jobId: string, leaseSeconds: number): void {
    if (this.closed) return;
    this.db.prepare(`UPDATE bot_jobs SET state = 'claimed', lease_expires_at = ? WHERE id = ?`)
      .run(Date.now() + leaseSeconds * 1000, jobId);
  }

  heartbeatLease(jobId: string, leaseSeconds: number): void {
    if (this.closed) return;
    this.db.prepare(`UPDATE bot_jobs SET lease_expires_at = ? WHERE id = ? AND state = 'claimed'`)
      .run(Date.now() + leaseSeconds * 1000, jobId);
  }

  settle(jobId: string, outcome: 'done' | 'dead', reasonCode?: string): void {
    if (this.closed) return;
    this.db.transaction(() => {
      const row = this.db.prepare(`SELECT * FROM bot_jobs WHERE id = ?`).get(jobId) as any;
      if (!row) return;
      if (outcome === 'done') {
        this.db.prepare(`DELETE FROM bot_jobs WHERE id = ?`).run(jobId);
        return;
      }
      this.db.prepare(`DELETE FROM bot_jobs WHERE id = ?`).run(jobId);
      this.db.prepare(
        `INSERT INTO bot_dlq (id, bot_id, trigger, prompt, from_bot, source, attempts, created_at, idempotency_key, reason_code, dead_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
      ).run(
        row.id, row.bot_id, row.trigger, row.prompt, row.from_bot, row.source,
        row.attempts + 1, row.created_at, row.idempotency_key, reasonCode ?? row.reason_code ?? null, Date.now(),
      );
      // Cap the DLQ — evict oldest, bounded by design (§2.10).
      const overflow = this.db.prepare(
        `SELECT id FROM bot_dlq ORDER BY dead_at DESC, created_at DESC, rowid DESC LIMIT -1 OFFSET ?`,
      ).all(this.dlqCap) as any[];
      for (const r of overflow) {
        this.db.prepare(`DELETE FROM bot_dlq WHERE id = ?`).run(r.id);
      }
    });
  }

  requeueExpiredLeases(): number {
    if (this.closed) return 0;
    const result = this.db.prepare(
      `UPDATE bot_jobs SET state = 'pending', lease_expires_at = NULL WHERE state = 'claimed' AND lease_expires_at <= ?`,
    ).run(Date.now());
    return result.changes as number;
  }

  retry(jobId: string, attempts: number, runAfterMs?: number): void {
    this.db.prepare(
      `UPDATE bot_jobs SET state = 'pending', attempts = ?, lease_expires_at = NULL, run_after = ? WHERE id = ?`,
    ).run(attempts, runAfterMs ?? null, jobId);
  }

  interruptedSchedules(): DurableBotJob[] {
    if (this.closed) return [];
    const rows = this.db.prepare(
      `SELECT * FROM bot_jobs WHERE trigger = 'cron' AND (state = 'claimed' OR attempts > 0 OR run_after IS NOT NULL) ORDER BY created_at`,
    ).all() as unknown[];
    return rows.map(normalizeJob);
  }

  rehydratable(): DurableBotJob[] {
    if (this.closed) return [];
    // Due pending jobs + expired-lease claimed jobs — jobs still in their
    // retry backoff (run_after in the future) wait until due.
    const rows = this.db.prepare(
      `SELECT * FROM bot_jobs WHERE state = 'pending' AND (run_after IS NULL OR run_after <= ?)
       UNION ALL SELECT * FROM bot_jobs WHERE state = 'claimed' AND lease_expires_at <= ? ORDER BY created_at`,
    ).all(Date.now(), Date.now()) as any[];
    return rows.map(normalizeJob);
  }

  dueJobs(): DurableBotJob[] {
    const rows = this.db.prepare(
      `SELECT * FROM bot_jobs WHERE state = 'pending' AND (run_after IS NULL OR run_after <= ?) ORDER BY created_at`,
    ).all(Date.now()) as any[];
    return rows.map(normalizeJob);
  }

  pendingJobs(botId: string): DurableBotJob[] {
    const rows = this.db.prepare(
      `SELECT * FROM bot_jobs WHERE bot_id = ? AND state = 'pending' ORDER BY created_at`,
    ).all(botId) as any[];
    return rows.map(normalizeJob);
  }

  enqueueMail(mail: Omit<DurableMail, 'id'>): string {
    const id = randomUUID().slice(0, 12);
    this.db.prepare(
      `INSERT INTO bot_mail (id, bot_id, from_bot, content, created_at) VALUES (?, ?, ?, ?, ?)`,
    ).run(id, mail.botId, mail.from, mail.content, mail.createdAt);
    return id;
  }

  drainMail(botId: string): DurableMail[] {
    const rows = this.db.prepare(
      `SELECT * FROM bot_mail WHERE bot_id = ? ORDER BY created_at`,
    ).all(botId) as any[];
    if (rows.length === 0) return [];
    this.db.prepare(`DELETE FROM bot_mail WHERE bot_id = ?`).run(botId);
    return rows.map(r => ({
      id: String(r.id), botId: String(r.bot_id), from: String(r.from_bot),
      content: String(r.content), createdAt: Number(r.created_at),
    }));
  }

  purgeBot(botId: string): void {
    this.db.prepare(`DELETE FROM bot_jobs WHERE bot_id = ?`).run(botId);
    this.db.prepare(`DELETE FROM bot_mail WHERE bot_id = ?`).run(botId);
    this.db.prepare(`DELETE FROM bot_dlq WHERE bot_id = ?`).run(botId);
  }

  listDlq(botId?: string): DlqEntry[] {
    const rows = botId
      ? this.db.prepare(`SELECT * FROM bot_dlq WHERE bot_id = ? ORDER BY dead_at DESC`).all(botId) as any[]
      : this.db.prepare(`SELECT * FROM bot_dlq ORDER BY dead_at DESC`).all() as any[];
    return rows.map(r => ({
      ...normalizeJob(r),
      state: 'dead' as const,
      deadAt: r.dead_at,
    }));
  }

  peekDlq(jobId: string): DurableBotJob | null {
    const row = this.db.prepare(`SELECT * FROM bot_dlq WHERE id = ?`).get(jobId) as any;
    return row ? ({ ...normalizeJob(row), state: 'dead' as const, deadAt: row.dead_at } as any) : null;
  }

  removeFromDlq(jobId: string): DurableBotJob | null {
    const row = this.db.prepare(`SELECT * FROM bot_dlq WHERE id = ?`).get(jobId) as any;
    if (!row) return null;
    this.db.prepare(`DELETE FROM bot_dlq WHERE id = ?`).run(jobId);
    return normalizeJob(row);
  }

  clearDlq(botId?: string): number {
    const before = (this.db.prepare(botId ? `SELECT COUNT(*) AS n FROM bot_dlq WHERE bot_id = ?` : `SELECT COUNT(*) AS n FROM bot_dlq`).get(...(botId ? [botId] : [])) as { n: number }).n;
    if (botId) this.db.prepare(`DELETE FROM bot_dlq WHERE bot_id = ?`).run(botId);
    else this.db.prepare(`DELETE FROM bot_dlq`).run();
    return before;
  }

  counts(): QueueCounts {
    const pending = (this.db.prepare(`SELECT COUNT(*) c FROM bot_jobs WHERE state = 'pending'`).get() as any).c as number;
    const claimed = (this.db.prepare(`SELECT COUNT(*) c FROM bot_jobs WHERE state = 'claimed'`).get() as any).c as number;
    const dlq = (this.db.prepare(`SELECT COUNT(*) c FROM bot_dlq`).get() as any).c as number;
    return { pending, claimed, dlq };
  }

  /** WAL checkpoints on close, releasing the -wal/-shm sidecars too. Idempotent. */
  close(): void {
    this.closed = true;
    try {
      this.db.close();
    } catch {
      // Already closed (double teardown must never throw).
    }
  }
}

// ---------------------------------------------------------------------------
// JSON-file lease backend (zero native deps — Termux / old Node fallback)
// ---------------------------------------------------------------------------

const QUEUE_FILE = 'queue.json';

interface QueueFile {
  jobs: DurableBotJob[];
  dlq: DlqEntry[];
  mails: DurableMail[];
}

export class JsonFileQueueBackend implements BotQueueBackend {
  readonly name = 'json-file';
  private file: string;
  private data: QueueFile;
  private dlqCap: number;

  /** Writes are fd-opened-and-closed per op (write-to-rename + fsync) — nothing to release. */
  close(): void { /* no native handles */ }

  constructor(dir: string, dlqCap: number) {
    mkdirSync(dir, { recursive: true });
    this.file = join(dir, QUEUE_FILE);
    this.dlqCap = dlqCap;
    this.data = existsSync(this.file) ? this.read() : { jobs: [], dlq: [], mails: [] };
  }

  private read(): QueueFile {
    try {
      const parsed = JSON.parse(readFileSync(this.file, 'utf-8'));
      return {
        jobs: (parsed.jobs ?? []).map(normalizeJob),
        dlq: (parsed.dlq ?? []).map((d: any) => ({ ...normalizeJob(d), state: 'dead' as const, deadAt: d.deadAt ?? Date.now() })),
        mails: parsed.mails ?? [],
      };
    } catch {
      return { jobs: [], dlq: [], mails: [] };
    }
  }

  /** Atomic rewrite: tmp file + rename (the SessionRepository discipline). */
  private flush(): void {
    const tmp = `${this.file}.tmp-${process.pid}`;
    writeFileSyncFsync(tmp, JSON.stringify(this.data));
    renameSync(tmp, this.file);
  }

  enqueue(job: Omit<DurableBotJob, 'state'>): { job: DurableBotJob; duplicated: boolean } {
    const dup = this.data.jobs.find(j => j.botId === job.botId && j.idempotencyKey === job.idempotencyKey && j.state !== 'dead');
    if (dup) return { job: dup, duplicated: true };
    const stored: DurableBotJob = { ...job, state: 'pending' };
    this.data.jobs.push(stored);
    this.flush();
    return { job: stored, duplicated: false };
  }

  claim(jobId: string, leaseSeconds: number): void {
    const job = this.data.jobs.find(j => j.id === jobId);
    if (job) {
      job.state = 'claimed';
      job.leaseExpiresAt = Date.now() + leaseSeconds * 1000;
      this.flush();
    }
  }

  heartbeatLease(jobId: string, leaseSeconds: number): void {
    const job = this.data.jobs.find(j => j.id === jobId && j.state === 'claimed');
    if (job) {
      job.leaseExpiresAt = Date.now() + leaseSeconds * 1000;
      this.flush();
    }
  }

  settle(jobId: string, outcome: 'done' | 'dead', reasonCode?: string): void {
    const idx = this.data.jobs.findIndex(j => j.id === jobId);
    if (idx === -1) return;
    const [job] = this.data.jobs.splice(idx, 1);
    if (outcome === 'dead') {
      this.data.dlq.unshift({
        ...job, state: 'dead', attempts: job.attempts + 1,
        reasonCode: reasonCode ?? job.reasonCode, deadAt: Date.now(),
      });
      if (this.data.dlq.length > this.dlqCap) this.data.dlq.length = this.dlqCap;
    }
    this.flush();
  }

  requeueExpiredLeases(): number {
    const now = Date.now();
    let n = 0;
    for (const job of this.data.jobs) {
      // Inclusive boundary (matches SQLite's lease_expires_at <= now): a
      // heartbeat to an instant-expiry lease (now + 0) must be sweepable in
      // the SAME millisecond it was written — strict < raced the ms clock
      // and trapped zero-width leases on fast-Linux/Windows fsync.
      if (job.state === 'claimed' && (job.leaseExpiresAt ?? 0) <= now) {
        job.state = 'pending';
        job.leaseExpiresAt = undefined;
        n++;
      }
    }
    if (n > 0) this.flush();
    return n;
  }

  retry(jobId: string, attempts: number, runAfterMs?: number): void {
    const job = this.data.jobs.find(j => j.id === jobId);
    if (job) {
      job.state = 'pending';
      job.attempts = attempts;
      job.leaseExpiresAt = undefined;
      job.runAfter = runAfterMs;
      this.flush();
    }
  }

  interruptedSchedules(): DurableBotJob[] {
    return this.data.jobs.filter((job) => job.trigger === 'cron'
      && (job.state === 'claimed' || job.attempts > 0 || job.runAfter !== undefined));
  }

  rehydratable(): DurableBotJob[] {
    // Due pending + expired-lease claimed (INCLUSIVE — a heartbeat to an
    // instant-expiry lease must be sweepable in the same millisecond;
    // strict < raced the ms clock and trapped zero-width leases).
    // Future run_after waits.
    const now = Date.now();
    return this.data.jobs.filter(j =>
      (j.state === 'pending' && (j.runAfter === undefined || j.runAfter <= now))
      || (j.state === 'claimed' && (j.leaseExpiresAt ?? 0) <= now));
  }

  dueJobs(): DurableBotJob[] {
    const now = Date.now();
    return this.data.jobs.filter(j => j.state === 'pending' && (j.runAfter === undefined || j.runAfter <= now));
  }

  pendingJobs(botId: string): DurableBotJob[] {
    return this.data.jobs.filter(j => j.botId === botId && j.state === 'pending');
  }

  enqueueMail(mail: Omit<DurableMail, 'id'>): string {
    const id = randomUUID().slice(0, 12);
    this.data.mails.push({ ...mail, id });
    this.flush();
    return id;
  }

  drainMail(botId: string): DurableMail[] {
    const drained = this.data.mails.filter(m => m.botId === botId);
    if (drained.length > 0) {
      this.data.mails = this.data.mails.filter(m => m.botId !== botId);
      this.flush();
    }
    return drained;
  }

  purgeBot(botId: string): void {
    const before = this.data.jobs.length + this.data.dlq.length + this.data.mails.length;
    this.data.jobs = this.data.jobs.filter(j => j.botId !== botId);
    this.data.dlq = this.data.dlq.filter(j => j.botId !== botId);
    this.data.mails = this.data.mails.filter(m => m.botId !== botId);
    if (this.data.jobs.length + this.data.dlq.length + this.data.mails.length !== before) this.flush();
  }

  listDlq(botId?: string): DlqEntry[] {
    return this.data.dlq.filter(j => !botId || j.botId === botId);
  }

  peekDlq(jobId: string): DurableBotJob | null {
    return this.data.dlq.find(j => j.id === jobId) ?? null;
  }

  removeFromDlq(jobId: string): DurableBotJob | null {
    const idx = this.data.dlq.findIndex(j => j.id === jobId);
    if (idx === -1) return null;
    const [job] = this.data.dlq.splice(idx, 1);
    this.flush();
    return job;
  }

  clearDlq(botId?: string): number {
    const before = this.data.dlq.length;
    this.data.dlq = botId ? this.data.dlq.filter(j => j.botId !== botId) : [];
    if (this.data.dlq.length !== before) this.flush();
    return before - this.data.dlq.length;
  }

  counts(): QueueCounts {
    return {
      pending: this.data.jobs.filter(j => j.state === 'pending').length,
      claimed: this.data.jobs.filter(j => j.state === 'claimed').length,
      dlq: this.data.dlq.length,
    };
  }
}

import { writeFileSync as writeFdsync, fsyncSync, openSync, closeSync } from 'node:fs';

/** write + fsync before rename so the queue survives a hard power cut. */
function writeFileSyncFsync(file: string, content: string): void {
  const fd = openSync(file, 'w');
  try {
    writeFdsync(fd, content, 'utf-8');
    fsyncSync(fd);
  } finally {
    closeSync(fd);
  }
}