@qearlyao/familiar 0.1.0

package/dist/runtime.js

@@ -0,0 +1,493 @@
+import { randomUUID } from "node:crypto";
+import { buildRecordBase, } from "./chat-log.js";
+import { promptAttachmentNotes } from "./inbound-attachments.js";
+function formatAuthor(authorName, authorId) {
+    return authorName ? `${authorName} (uid:${authorId})` : `uid:${authorId}`;
+}
+function formatLocalTimestamp(ts) {
+    const date = new Date(ts);
+    if (Number.isNaN(date.getTime()))
+        return ts;
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const absolute = Math.abs(offsetMinutes);
+    const hours = Math.floor(absolute / 60);
+    const minutes = absolute % 60;
+    const offset = minutes === 0 ? `GMT${sign}${hours}` : `GMT${sign}${hours}:${String(minutes).padStart(2, "0")}`;
+    const local = [
+        date.getFullYear(),
+        String(date.getMonth() + 1).padStart(2, "0"),
+        String(date.getDate()).padStart(2, "0"),
+    ].join("-");
+    const time = [
+        String(date.getHours()).padStart(2, "0"),
+        String(date.getMinutes()).padStart(2, "0"),
+        String(date.getSeconds()).padStart(2, "0"),
+    ].join(":");
+    return `${local} ${time} ${offset}`;
+}
+function formatPromptRecord(record) {
+    const text = record.text.trim() || "(no text)";
+    const author = record.authorName?.trim()
+        ? `${record.authorName.trim()} uid:${record.authorId}`
+        : `uid:${record.authorId}`;
+    const attachmentText = record.attachments.length ? `\n${promptAttachmentNotes(record.attachments)}` : "";
+    return `[${author} @ ${formatLocalTimestamp(record.ts)}] ${text}${attachmentText}`;
+}
+function getTriggerRecord(records, job) {
+    const record = records.find((candidate) => candidate.recordId === job.triggerRecordId);
+    return record?.type === "inbound" ? record : undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export class ConversationRuntime {
+    channel;
+    channelKey;
+    log;
+    ownerId;
+    botUserId;
+    records = [];
+    nextRecordId = 1;
+    armedAfterRecordId;
+    lastUserInteractionAt = 0;
+    pendingJobs = [];
+    activeJob;
+    listeners = new Set();
+    agentEventListeners = new Set();
+    constructor(options) {
+        this.channel = options.log.channel;
+        this.channelKey = options.channelKey;
+        this.log = options.log;
+        this.ownerId = options.ownerId;
+        this.botUserId = options.botUserId;
+    }
+    static async connect(options) {
+        const runtime = new ConversationRuntime(options);
+        await runtime.initialize();
+        return runtime;
+    }
+    async initialize() {
+        await this.log.acquire(`familiar-${process.pid}-${this.channelKey}`);
+        this.records = await this.log.read();
+        this.nextRecordId = this.records.reduce((max, record) => Math.max(max, record.recordId), 0) + 1;
+        this.lastUserInteractionAt = this.findLastUserInteractionAt();
+        this.rebuildPendingJobs();
+    }
+    findLastUserInteractionAt() {
+        for (let index = this.records.length - 1; index >= 0; index--) {
+            const record = this.records[index];
+            if (!record || record.type !== "inbound" || !this.isOwnerMessage(record))
+                continue;
+            const parsed = Date.parse(record.ts);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+        return Date.now();
+    }
+    rebuildPendingJobs() {
+        const terminalJobIds = new Set();
+        const queuedJobs = [];
+        for (const record of this.records) {
+            if (record.type === "job_completed" || record.type === "job_failed")
+                terminalJobIds.add(record.jobId);
+            if (record.type === "job_queued") {
+                queuedJobs.push({
+                    jobId: record.jobId,
+                    trigger: record.trigger,
+                    triggerRecordId: record.triggerRecordId,
+                    queuedRecordId: record.recordId,
+                });
+            }
+        }
+        this.pendingJobs = queuedJobs.filter((job) => !terminalJobIds.has(job.jobId));
+    }
+    async disconnect() {
+        await this.log.release();
+    }
+    getLastUserInteractionAt() {
+        return this.lastUserInteractionAt;
+    }
+    async armAfterCurrentTail() {
+        this.armedAfterRecordId = this.records.at(-1)?.recordId ?? 0;
+        await this.appendRecord({
+            type: "runtime",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            event: "armed",
+            detail: `armed after record ${this.armedAfterRecordId}`,
+        });
+    }
+    async noteHeartbeat(detail) {
+        await this.appendRecord({
+            type: "runtime",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            event: "heartbeat",
+            detail,
+        });
+    }
+    async noteHeartbeatFailure(detail) {
+        await this.appendRecord({
+            type: "runtime",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            event: "heartbeat_failed",
+            detail,
+        });
+    }
+    async appendRecord(record, options = {}) {
+        this.records.push(record);
+        this.nextRecordId = Math.max(this.nextRecordId, record.recordId + 1);
+        if (record.type === "inbound" && this.isOwnerMessage(record)) {
+            const parsed = Date.parse(record.ts);
+            this.lastUserInteractionAt = Number.isFinite(parsed) ? parsed : Date.now();
+        }
+        await this.log.append(record);
+        if (options.notify === false)
+            return;
+        for (const listener of this.listeners) {
+            void Promise.resolve(listener(record)).catch((error) => console.error(`runtime listener failed for ${this.channelKey}`, error));
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    subscribeAgentEvents(listener) {
+        this.agentEventListeners.add(listener);
+        return () => {
+            this.agentEventListeners.delete(listener);
+        };
+    }
+    publishAgentEvent(jobId, messageId, event) {
+        const payload = { jobId, messageId, event, ts: Date.now() };
+        for (const listener of this.agentEventListeners) {
+            void Promise.resolve(listener(payload)).catch((error) => console.error(`runtime agent event listener failed for ${this.channelKey}`, error));
+        }
+    }
+    isOwnerMessage(input) {
+        if (input.isBot)
+            return false;
+        return input.authorId === this.ownerId;
+    }
+    getLastQueuedTriggerRecordId() {
+        let last = 0;
+        for (const record of this.records) {
+            if (record.type === "job_queued")
+                last = Math.max(last, record.triggerRecordId);
+        }
+        return last;
+    }
+    getLastCompletedTriggerRecordId() {
+        let last = 0;
+        for (const record of this.records) {
+            if (record.type === "job_completed")
+                last = Math.max(last, record.triggerRecordId);
+        }
+        return last;
+    }
+    canRecordTrigger(record, options = {}) {
+        if (this.armedAfterRecordId === undefined)
+            return undefined;
+        if (record.recordId <= this.armedAfterRecordId)
+            return undefined;
+        if (record.recordId <= this.getLastQueuedTriggerRecordId())
+            return undefined;
+        if (this.channel.scope === "dm" || this.channel.scope === "web") {
+            if (!this.isOwnerMessage(record))
+                return undefined;
+            return options.mode === "collect" ? undefined : "dm";
+        }
+        if (options.mode === "collect")
+            return undefined;
+        if (options.channelTrigger === "always")
+            return "message";
+        return record.mentionedBot ? "mention" : undefined;
+    }
+    hasActiveJob(jobId) {
+        if (!this.activeJob)
+            return false;
+        return jobId ? this.activeJob.jobId === jobId : true;
+    }
+    parseControlCommand(input) {
+        if (!this.isOwnerMessage(input))
+            return undefined;
+        let text = input.text;
+        if (this.botUserId)
+            text = text.replace(new RegExp(`<@!?${escapeRegExp(this.botUserId)}>`, "g"), " ");
+        const normalized = text.replace(/\s+/g, " ").trim();
+        const commandText = normalized.toLowerCase();
+        const slashCommand = commandText.startsWith("/");
+        const explicitBotCommand = input.mentionedBot === true;
+        if (!slashCommand && !explicitBotCommand)
+            return undefined;
+        const [rawCommand = "", ...argParts] = normalized.split(" ");
+        const command = rawCommand.replace(/^\//, "").toLowerCase();
+        if (!["stop", "status", "new", "reload", "compact", "model", "thinking", "channel-trigger"].includes(command)) {
+            return undefined;
+        }
+        return {
+            command: command,
+            args: argParts.join(" ").trim(),
+        };
+    }
+    async noteControlCommand(input, control) {
+        await this.appendRecord({
+            type: "control",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            command: control.command,
+            args: control.args || undefined,
+            messageId: input.messageId,
+            authorId: input.authorId,
+            authorName: input.authorName,
+            text: input.text.trim(),
+        });
+        if (input.checkpoint)
+            await this.noteCheckpoint(input.checkpoint);
+    }
+    async ingestInbound(input, options = {}) {
+        const record = {
+            type: "inbound",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            ts: input.remoteTimestamp || new Date().toISOString(),
+            messageId: input.messageId,
+            authorId: input.authorId,
+            authorName: input.authorName,
+            text: input.text.trim(),
+            isBot: input.isBot ?? false,
+            mentionedBot: input.mentionedBot ?? false,
+            attachments: input.attachments ?? [],
+        };
+        await this.appendRecord(record);
+        if (input.checkpoint)
+            await this.noteCheckpoint(input.checkpoint);
+        const trigger = this.canRecordTrigger(record, options);
+        if (!trigger)
+            return { record, jobQueued: false };
+        await this.queueTrigger(record, trigger);
+        return { record, jobQueued: true };
+    }
+    async queueLatestTrigger(options = {}) {
+        const record = this.getLatestQueueableInbound(options);
+        if (!record)
+            return undefined;
+        const trigger = this.channel.scope === "dm" || this.channel.scope === "web"
+            ? "dm"
+            : options.channelTrigger === "always"
+                ? "message"
+                : "mention";
+        return this.queueTrigger(record, trigger);
+    }
+    buildSteerPromptForRecord(record) {
+        return formatPromptRecord(record);
+    }
+    getLatestQueueableInbound(options) {
+        const lastQueuedTriggerRecordId = this.getLastQueuedTriggerRecordId();
+        let latest;
+        let sawMention = false;
+        for (let index = this.records.length - 1; index >= 0; index--) {
+            const record = this.records[index];
+            if (record?.type !== "inbound")
+                continue;
+            if (this.armedAfterRecordId === undefined)
+                return undefined;
+            if (record.recordId <= this.armedAfterRecordId || record.recordId <= lastQueuedTriggerRecordId)
+                break;
+            if (this.channel.scope === "dm" || this.channel.scope === "web") {
+                if (!this.isOwnerMessage(record))
+                    continue;
+                return record;
+            }
+            latest ??= record;
+            if (record.mentionedBot)
+                sawMention = true;
+        }
+        if (options.channelTrigger === "always")
+            return latest;
+        return sawMention ? latest : undefined;
+    }
+    async queueTrigger(record, trigger) {
+        const queuedRecord = {
+            type: "job_queued",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            jobId: randomUUID(),
+            trigger,
+            triggerRecordId: record.recordId,
+        };
+        await this.appendRecord(queuedRecord);
+        const job = {
+            jobId: queuedRecord.jobId,
+            trigger: queuedRecord.trigger,
+            triggerRecordId: queuedRecord.triggerRecordId,
+            queuedRecordId: queuedRecord.recordId,
+        };
+        this.pendingJobs.push(job);
+        return job;
+    }
+    beginNextJob() {
+        if (this.activeJob || this.pendingJobs.length === 0)
+            return undefined;
+        const job = this.pendingJobs.shift();
+        if (!job)
+            return undefined;
+        this.activeJob = job;
+        const triggerRecord = getTriggerRecord(this.records, job);
+        return {
+            job,
+            prompt: this.buildPrompt(job),
+            attachments: this.buildPromptAttachments(job),
+            triggerMessageId: triggerRecord?.messageId,
+        };
+    }
+    buildPrompt(job) {
+        const completedBoundary = this.getLastCompletedTriggerRecordId();
+        const slice = this.records.filter((record) => {
+            return (record.type === "inbound" && record.recordId > completedBoundary && record.recordId <= job.triggerRecordId);
+        });
+        return slice.map(formatPromptRecord).join("\n").trim();
+    }
+    buildPromptAttachments(job) {
+        const completedBoundary = this.getLastCompletedTriggerRecordId();
+        const slice = this.records.filter((record) => {
+            return (record.type === "inbound" && record.recordId > completedBoundary && record.recordId <= job.triggerRecordId);
+        });
+        return slice.flatMap((record) => record.attachments);
+    }
+    async noteOutbound(options) {
+        const text = options.text.trim();
+        if (!text && options.messageIds.length === 0)
+            return undefined;
+        const record = {
+            type: "outbound",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            messageIds: options.messageIds,
+            webMessageId: options.webMessageId,
+            text,
+            attachments: options.attachments?.length ? options.attachments : undefined,
+            thinking: options.thinking,
+            thinkingMs: options.thinkingMs,
+            silent: options.silent || undefined,
+            replyToMessageId: options.replyToMessageId,
+            jobId: options.jobId,
+            control: options.control,
+        };
+        await this.appendRecord(record);
+        return record.recordId;
+    }
+    async completeActiveJob(options) {
+        const job = this.activeJob;
+        if (!job)
+            return;
+        const outboundRecordId = await this.noteOutbound({
+            text: options.text,
+            messageIds: options.messageIds,
+            webMessageId: options.webMessageId,
+            attachments: options.attachments,
+            thinking: options.thinking,
+            thinkingMs: options.thinkingMs,
+            silent: options.silent,
+            replyToMessageId: options.replyToMessageId,
+            jobId: job.jobId,
+        });
+        await this.appendRecord({
+            type: "job_completed",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            jobId: job.jobId,
+            triggerRecordId: job.triggerRecordId,
+            outboundRecordId,
+        });
+        this.activeJob = undefined;
+    }
+    async noteAgentEvent(jobId, messageId, event, options = {}) {
+        await this.appendRecord({
+            type: "agent_event",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            jobId,
+            messageId,
+            event,
+        }, options);
+    }
+    async failActiveJob(error) {
+        const job = this.activeJob;
+        if (!job)
+            return;
+        await this.appendRecord({
+            type: "job_failed",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            jobId: job.jobId,
+            triggerRecordId: job.triggerRecordId,
+            error,
+        });
+        this.activeJob = undefined;
+    }
+    async noteCheckpoint(checkpoint) {
+        const previous = this.getLastCheckpoint();
+        if (previous.cursor === checkpoint.cursor && previous.messageId === checkpoint.messageId)
+            return;
+        await this.appendRecord({
+            type: "checkpoint",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            cursor: checkpoint.cursor,
+            messageId: checkpoint.messageId,
+        });
+    }
+    getLastCheckpoint() {
+        for (let index = this.records.length - 1; index >= 0; index--) {
+            const record = this.records[index];
+            if (record?.type === "checkpoint")
+                return { cursor: record.cursor, messageId: record.messageId };
+        }
+        return {};
+    }
+    async resetConversation(detail = "new conversation requested") {
+        this.pendingJobs = [];
+        this.activeJob = undefined;
+        this.armedAfterRecordId = this.records.at(-1)?.recordId ?? 0;
+        await this.appendRecord({
+            type: "runtime",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            event: "reset",
+            detail,
+        });
+    }
+    async appendError(message) {
+        await this.appendRecord({
+            type: "error",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            message,
+        });
+    }
+    getStatus() {
+        return {
+            channelKey: this.channelKey,
+            logDir: this.log.dir,
+            queueLength: this.pendingJobs.length,
+            hasActiveJob: this.activeJob !== undefined,
+            recordCount: this.records.length,
+            lastRecordId: this.records.at(-1)?.recordId ?? 0,
+            armed: this.armedAfterRecordId !== undefined,
+        };
+    }
+    hasLiveWork() {
+        return this.activeJob !== undefined || this.pendingJobs.length > 0;
+    }
+    formatStatus() {
+        const status = this.getStatus();
+        const active = status.hasActiveJob ? "yes" : "no";
+        return [
+            `channel: ${status.channelKey}`,
+            `records: ${status.recordCount}`,
+            `last_record: ${status.lastRecordId}`,
+            `queued: ${status.queueLength}`,
+            `active_job: ${active}`,
+            `armed: ${status.armed ? "yes" : "no"}`,
+            `log_dir: ${status.logDir}`,
+        ].join("\n");
+    }
+    formatInboundForLog(record) {
+        return `${formatAuthor(record.authorName, record.authorId)} @ ${formatLocalTimestamp(record.ts)}: ${record.text}`;
+    }
+    getRecords() {
+        return this.records;
+    }
+}

package/dist/scheduler.js

@@ -0,0 +1,200 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+const stateWriteQueues = new Map();
+function toDate(value) {
+    if (value instanceof Date)
+        return value;
+    return new Date(value);
+}
+function formatOffset(date) {
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const absolute = Math.abs(offsetMinutes);
+    const hours = Math.floor(absolute / 60);
+    const minutes = absolute % 60;
+    return minutes === 0 ? `GMT${sign}${hours}` : `GMT${sign}${hours}:${String(minutes).padStart(2, "0")}`;
+}
+export function formatLocalTimestamp(value) {
+    const date = toDate(value);
+    if (Number.isNaN(date.getTime()))
+        return String(value);
+    const localDate = [
+        date.getFullYear(),
+        String(date.getMonth() + 1).padStart(2, "0"),
+        String(date.getDate()).padStart(2, "0"),
+    ].join("-");
+    const localTime = [
+        String(date.getHours()).padStart(2, "0"),
+        String(date.getMinutes()).padStart(2, "0"),
+        String(date.getSeconds()).padStart(2, "0"),
+    ].join(":");
+    return `${localDate} ${localTime} ${formatOffset(date)}`;
+}
+export function formatIdleDuration(ms) {
+    if (!Number.isFinite(ms) || ms <= 0)
+        return "0m";
+    const totalMinutes = Math.floor(ms / 60000);
+    const days = Math.floor(totalMinutes / 1440);
+    const hours = Math.floor((totalMinutes % 1440) / 60);
+    const minutes = totalMinutes % 60;
+    if (days > 0) {
+        return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+    }
+    if (hours > 0) {
+        return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+    }
+    return `${minutes}m`;
+}
+export function buildHeartbeatInjectionText(options) {
+    const nowDate = toDate(options.now);
+    const idleSinceDate = toDate(options.idleSince);
+    const idleDurationMs = Math.max(0, nowDate.getTime() - idleSinceDate.getTime());
+    const idleMinutes = Math.floor(idleDurationMs / 60000);
+    const body = options.body ??
+        `hey~ been quiet for a bit. this is your time now.
+
+what you do with it is up to you — HEARTBEAT.md has the menu if you don't remember it. once you know the shape of it you don't have to re-read every fire, just trust what you remember and pick what fits.
+
+it's okay to sit one out, but only when that's actually the real answer — not when it's the easy one.`;
+    return `<heartbeat local_time="${formatLocalTimestamp(nowDate)}" idle_duration="${formatIdleDuration(idleDurationMs)}" idle_minutes="${idleMinutes}">\n${body}\n</heartbeat>`;
+}
+function pad2(value) {
+    return String(value).padStart(2, "0");
+}
+function localDateKey(date) {
+    return [date.getFullYear(), pad2(date.getMonth() + 1), pad2(date.getDate())].join("-");
+}
+function parseTimeOfDay(value) {
+    const match = /^([01]?\d|2[0-3]):([0-5]\d)$/.exec(value.trim());
+    if (!match)
+        throw new Error(`Invalid cron time: ${value}`);
+    return { hour: Number(match[1]), minute: Number(match[2]) };
+}
+function parseLocalDateTime(value) {
+    const normalized = value.trim().replace("T", " ");
+    const match = /^(\d{4})-(\d{2})-(\d{2}) ([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?$/.exec(normalized);
+    if (!match)
+        return new Date(value);
+    return new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]), Number(match[4]), Number(match[5]), Number(match[6] ?? 0));
+}
+function daysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+function scheduledDate(year, month, day, time) {
+    const clampedDay = Math.min(day, daysInMonth(year, month));
+    // Local Date construction follows host timezone DST rules; rare skipped or repeated wall-clock hours are acceptable for v0.
+    return new Date(year, month, clampedDay, time.hour, time.minute, 0, 0);
+}
+function cronSlotKey(job, date) {
+    return `${job.id}:${job.frequency}:${localDateKey(date)}T${pad2(date.getHours())}:${pad2(date.getMinutes())}`;
+}
+function latestScheduledDate(job, now) {
+    if (job.frequency === "once") {
+        if (!job.runAt)
+            return undefined;
+        const runAt = parseLocalDateTime(job.runAt);
+        return now.getTime() >= runAt.getTime() ? runAt : undefined;
+    }
+    if (job.frequency === "hourly") {
+        const minute = job.minute ?? 0;
+        const candidate = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), minute, 0, 0);
+        if (candidate.getTime() <= now.getTime())
+            return candidate;
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours() - 1, minute, 0, 0);
+    }
+    const time = parseTimeOfDay(job.time ?? "00:00");
+    if (job.frequency === "daily") {
+        const candidate = scheduledDate(now.getFullYear(), now.getMonth(), now.getDate(), time);
+        if (candidate.getTime() <= now.getTime())
+            return candidate;
+        return scheduledDate(now.getFullYear(), now.getMonth(), now.getDate() - 1, time);
+    }
+    if (job.frequency === "weekly") {
+        const weekday = job.weekday ?? 0;
+        const daysSince = (now.getDay() - weekday + 7) % 7;
+        const candidate = scheduledDate(now.getFullYear(), now.getMonth(), now.getDate() - daysSince, time);
+        if (candidate.getTime() <= now.getTime())
+            return candidate;
+        return scheduledDate(now.getFullYear(), now.getMonth(), now.getDate() - daysSince - 7, time);
+    }
+    const day = job.day ?? 1;
+    const candidate = scheduledDate(now.getFullYear(), now.getMonth(), day, time);
+    if (candidate.getTime() <= now.getTime())
+        return candidate;
+    return scheduledDate(now.getFullYear(), now.getMonth() - 1, day, time);
+}
+export function dueCronSlot(job, state, now) {
+    if (!job.enabled)
+        return undefined;
+    if (state?.completed)
+        return undefined;
+    const nowDate = toDate(now);
+    const scheduled = latestScheduledDate(job, nowDate);
+    if (!scheduled)
+        return undefined;
+    const slot = cronSlotKey(job, scheduled);
+    return state?.lastFiredSlot === slot ? undefined : slot;
+}
+export function buildCronInjectionText(options) {
+    const nowDate = toDate(options.now);
+    return `<cron id="${options.job.id}" frequency="${options.job.frequency}" delivery="${options.job.deliveryMode}" local_time="${formatLocalTimestamp(nowDate)}" slot="${options.slot}">\n${options.job.prompt}\n</cron>`;
+}
+export function schedulerStatePath(dataDir) {
+    return resolve(dataDir, "scheduler", "cron-state.json");
+}
+export function schedulerLogPath(dataDir, now = new Date()) {
+    return resolve(dataDir, "scheduler", `${now.toISOString().slice(0, 10)}.jsonl`);
+}
+export async function loadSchedulerState(dataDir) {
+    const path = schedulerStatePath(dataDir);
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            heartbeat: parsed.heartbeat && typeof parsed.heartbeat === "object" && !Array.isArray(parsed.heartbeat)
+                ? parsed.heartbeat
+                : undefined,
+            cron: parsed.cron && typeof parsed.cron === "object" && !Array.isArray(parsed.cron) ? parsed.cron : {},
+        };
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return { cron: {} };
+        throw error;
+    }
+}
+export async function saveSchedulerState(dataDir, state) {
+    const path = schedulerStatePath(dataDir);
+    const prior = stateWriteQueues.get(path) ?? Promise.resolve();
+    const write = prior.then(async () => {
+        await mkdir(dirname(path), { recursive: true });
+        const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tempPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+        await rename(tempPath, path);
+    });
+    const queued = write.catch(() => undefined);
+    stateWriteQueues.set(path, queued);
+    void queued.finally(() => {
+        if (stateWriteQueues.get(path) === queued)
+            stateWriteQueues.delete(path);
+    });
+    await write;
+}
+export async function appendSchedulerLog(dataDir, event) {
+    const record = { ...event, ts: event.ts ?? new Date().toISOString() };
+    const path = schedulerLogPath(dataDir);
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+export function isHeartbeatDue(options) {
+    if (options.now < options.lastUserInteractionAt)
+        return false;
+    const idleDurationMs = options.now - options.lastUserInteractionAt;
+    if (idleDurationMs < options.idleThresholdMs)
+        return false;
+    const lastHeartbeatAt = options.lastHeartbeatAt ? Date.parse(options.lastHeartbeatAt) : undefined;
+    if (lastHeartbeatAt == null || !Number.isFinite(lastHeartbeatAt) || lastHeartbeatAt <= options.lastUserInteractionAt) {
+        return true;
+    }
+    return options.now - lastHeartbeatAt >= Math.max(0, options.intervalMs);
+}