@qearlyao/familiar 0.2.5 → 0.4.0

package/dist/runtime/agent-core.js

@@ -0,0 +1,82 @@
+import { chatChannelKey } from "../conversation/chat-log.js";
+import { createAgentWorkQueue } from "./agent-work-queue.js";
+import { createRuntimeManager } from "./runtime-manager.js";
+import { createSchedulerRunner } from "./scheduler-runner.js";
+const webPersistenceOnlyDelivery = {
+    async deliver() {
+        return [];
+    },
+};
+export function createAgentCore(deps) {
+    let sessionSource;
+    const requireSessionSource = () => {
+        if (!sessionSource)
+            throw new Error("Owner identity is not established");
+        return sessionSource;
+    };
+    let schedulerStarted = false;
+    const runtimeManager = createRuntimeManager({
+        config: deps.config,
+        memoryService: deps.memoryService,
+        botUserId: () => requireSessionSource().botUserId,
+    });
+    const agentWork = createAgentWorkQueue({ familiarAgent: deps.familiarAgent });
+    const scheduler = createSchedulerRunner({
+        config: deps.config,
+        agentWork,
+        familiarAgent: deps.familiarAgent,
+        resolveDefaultSession: () => requireSessionSource().resolveDefaultSession(),
+        delivery: {
+            deliver: (options) => requireSessionSource().delivery.deliver(options),
+        },
+    });
+    // The scheduler can only run once a session source exists; start it with the first
+    // source to arrive (cached identity at boot, or the live Discord connection).
+    const setSessionSource = async (source) => {
+        sessionSource = source;
+        if (!schedulerStarted) {
+            await scheduler.start();
+            schedulerStarted = true;
+        }
+    };
+    return {
+        attachDiscord(source) {
+            return setSessionSource(source);
+        },
+        useCachedIdentity(identity) {
+            const dmRef = { service: "discord", scope: "dm", channelId: identity.dmChannelId };
+            return setSessionSource({
+                botUserId: identity.botUserId,
+                resolveDefaultSession: async () => ({ runtime: await runtimeManager.getRuntimeForChannel(dmRef) }),
+                getWebSessions: async () => [
+                    { key: chatChannelKey(dmRef), label: "Main Chat", channel: dmRef, isDefault: true },
+                ],
+                delivery: webPersistenceOnlyDelivery,
+            });
+        },
+        hasSessionSource() {
+            return sessionSource !== undefined;
+        },
+        getRuntimeForChannel: runtimeManager.getRuntimeForChannel,
+        peekRuntime: runtimeManager.peekRuntime,
+        getWebSessions() {
+            return requireSessionSource().getWebSessions();
+        },
+        async getRuntimeForWebChannel(channelKey) {
+            const sessions = await requireSessionSource().getWebSessions();
+            const session = channelKey ? sessions.find((candidate) => candidate.key === channelKey) : sessions[0];
+            if (!session)
+                throw new Error(channelKey ? `Unknown web session: ${channelKey}` : "No sessions available");
+            return runtimeManager.getRuntimeForChannel(session.channel);
+        },
+        promptForRuntime: agentWork.promptForRuntime,
+        get activeOwner() {
+            return agentWork.activeOwner;
+        },
+        rearmHeartbeat: scheduler.rearmHeartbeat,
+        stop() {
+            scheduler.stop();
+            return runtimeManager.disconnectAll();
+        },
+    };
+}

package/dist/{agent-events.js → runtime/agent-events.js}

@@ -1,4 +1,4 @@
-import { isRecord } from "./util/guards.js";
+import { isRecord } from "../util/guards.js";
 function normalizeToolArguments(value) {
     return isRecord(value) ? value : {};
 }

package/dist/runtime/agent-work-queue.js

@@ -0,0 +1,55 @@
+import { CRON_SKIPPED, canceledJobError, HEARTBEAT_SKIPPED } from "../discord/turn.js";
+import { promptImagesFromAttachments } from "../media/inbound-attachments.js";
+export function createAgentWorkQueue(deps) {
+    let activeAgentOwner;
+    let agentWorkQueue = Promise.resolve();
+    const enqueueAgentWork = (work) => {
+        const run = agentWorkQueue.then(work);
+        agentWorkQueue = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const promptForRuntime = async (runtime, jobId, prompt, attachments = [], onEvent, onTurnEnd) => {
+        return enqueueAgentWork(async () => {
+            if (!runtime.hasActiveJob(jobId))
+                throw canceledJobError();
+            activeAgentOwner = runtime.channelKey;
+            try {
+                const promptImages = await promptImagesFromAttachments(attachments);
+                const input = [prompt, promptImages.promptSuffix].filter(Boolean).join("\n");
+                const reply = await deps.familiarAgent.prompt(runtime.channelKey, input, promptImages.images, onEvent, {
+                    referenceAttachments: attachments,
+                    onTurnEnd,
+                });
+                if (!runtime.hasActiveJob(jobId))
+                    throw canceledJobError();
+                return reply;
+            }
+            finally {
+                if (activeAgentOwner === runtime.channelKey)
+                    activeAgentOwner = undefined;
+            }
+        });
+    };
+    const promptScheduledMessage = async (runtime, buildMessage, onEvent, options) => {
+        return enqueueAgentWork(async () => {
+            const message = await buildMessage();
+            if (message === HEARTBEAT_SKIPPED || message === CRON_SKIPPED)
+                return message;
+            activeAgentOwner = runtime.channelKey;
+            try {
+                return await deps.familiarAgent.promptMessage(runtime.channelKey, message, onEvent, options);
+            }
+            finally {
+                if (activeAgentOwner === runtime.channelKey)
+                    activeAgentOwner = undefined;
+            }
+        });
+    };
+    return {
+        promptForRuntime,
+        promptScheduledMessage,
+        get activeOwner() {
+            return activeAgentOwner;
+        },
+    };
+}

package/dist/{runtime.js → runtime/conversation-runtime.js}

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { buildRecordBase, } from "./chat-log.js";
-import { promptAttachmentNotes } from "./inbound-attachments.js";
-import { formatLocalTimestamp } from "./util/time.js";
+import { buildRecordBase, hiddenWebMessageIds, } from "../conversation/chat-log.js";
+import { promptAttachmentNotes } from "../media/inbound-attachments.js";
+import { formatLocalTimestamp } from "../util/time.js";
 function formatAuthor(authorName, authorId) {
     return authorName ? `${authorName} (uid:${authorId})` : `uid:${authorId}`;
 }
@@ -32,6 +32,9 @@ export class ConversationRuntime {
     lastUserInteractionAt = 0;
     pendingJobs = [];
     activeJob;
+    lastQueuedTriggerRecordId = 0;
+    lastCompletedTriggerRecordId = 0;
+    queuedTriggerByJobId = new Map();
     listeners = new Set();
     agentEventListeners = new Set();
     constructor(options) {
@@ -65,9 +68,13 @@ export class ConversationRuntime {
         return Date.now();
     }
     rebuildPendingJobs() {
+        this.lastQueuedTriggerRecordId = 0;
+        this.lastCompletedTriggerRecordId = 0;
+        this.queuedTriggerByJobId.clear();
         const terminalJobIds = new Set();
         const queuedJobs = [];
         for (const record of this.records) {
+            this.indexRecordForTriggers(record);
             if (record.type === "job_completed" || record.type === "job_failed")
                 terminalJobIds.add(record.jobId);
             if (record.type === "outbound" && record.jobId)
@@ -83,6 +90,21 @@ export class ConversationRuntime {
         }
         this.pendingJobs = queuedJobs.filter((job) => !terminalJobIds.has(job.jobId));
     }
+    indexRecordForTriggers(record) {
+        if (record.type === "job_queued") {
+            this.queuedTriggerByJobId.set(record.jobId, record.triggerRecordId);
+            this.lastQueuedTriggerRecordId = Math.max(this.lastQueuedTriggerRecordId, record.triggerRecordId);
+        }
+        if (record.type === "job_completed") {
+            this.lastCompletedTriggerRecordId = Math.max(this.lastCompletedTriggerRecordId, record.triggerRecordId);
+        }
+        if (record.type === "outbound" && record.jobId) {
+            const triggerRecordId = this.queuedTriggerByJobId.get(record.jobId);
+            if (triggerRecordId !== undefined) {
+                this.lastCompletedTriggerRecordId = Math.max(this.lastCompletedTriggerRecordId, triggerRecordId);
+            }
+        }
+    }
     async disconnect() {
         await this.log.release();
     }
@@ -116,6 +138,7 @@ export class ConversationRuntime {
     }
     async appendRecord(record, options = {}) {
         this.records.push(record);
+        this.indexRecordForTriggers(record);
         this.nextRecordId = Math.max(this.nextRecordId, record.recordId + 1);
         if (record.type === "inbound" && this.isOwnerMessage(record)) {
             const parsed = Date.parse(record.ts);
@@ -151,36 +174,12 @@ export class ConversationRuntime {
             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;
-        const queuedTriggerRecordIds = new Map();
-        for (const record of this.records) {
-            if (record.type === "job_queued")
-                queuedTriggerRecordIds.set(record.jobId, record.triggerRecordId);
-            if (record.type === "job_completed")
-                last = Math.max(last, record.triggerRecordId);
-            if (record.type === "outbound" && record.jobId) {
-                const triggerRecordId = queuedTriggerRecordIds.get(record.jobId);
-                if (triggerRecordId !== undefined)
-                    last = Math.max(last, triggerRecordId);
-            }
-        }
-        return last;
-    }
     canRecordTrigger(record, options = {}) {
         if (this.armedAfterRecordId === undefined)
             return undefined;
         if (record.recordId <= this.armedAfterRecordId)
             return undefined;
-        if (record.recordId <= this.getLastQueuedTriggerRecordId())
+        if (record.recordId <= this.lastQueuedTriggerRecordId)
             return undefined;
         if (this.channel.scope === "dm" || this.channel.scope === "web") {
             if (!this.isOwnerMessage(record))
@@ -271,7 +270,7 @@ export class ConversationRuntime {
         return formatPromptRecord(record);
     }
     getLatestQueueableInbound(options) {
-        const lastQueuedTriggerRecordId = this.getLastQueuedTriggerRecordId();
+        const lastQueuedTriggerRecordId = this.lastQueuedTriggerRecordId;
         let latest;
         let sawMention = false;
         for (let index = this.records.length - 1; index >= 0; index--) {
@@ -321,26 +320,58 @@ export class ConversationRuntime {
             return undefined;
         this.activeJob = job;
         const triggerRecord = getTriggerRecord(this.records, job);
+        const slice = this.triggerInboundSlice(job);
         return {
             job,
-            prompt: this.buildPrompt(job),
-            attachments: this.buildPromptAttachments(job),
+            prompt: slice.map(formatPromptRecord).join("\n").trim(),
+            attachments: slice.flatMap((record) => record.attachments),
             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();
+    latestLiveAssistantOutbound() {
+        const hidden = hiddenWebMessageIds(this.records);
+        for (let index = this.records.length - 1; index >= 0; index--) {
+            const record = this.records[index];
+            if (!record)
+                continue;
+            if (record.type === "runtime" && record.event === "reset")
+                return undefined;
+            if (record.type === "inbound")
+                return undefined;
+            if (record.type !== "outbound" || record.control || !record.jobId)
+                continue;
+            const messageId = record.webMessageId || record.messageIds[0];
+            if (!messageId || hidden.has(messageId))
+                continue;
+            return { record, messageId };
+        }
+        return undefined;
     }
-    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);
+    latestAssistantRetryTarget() {
+        const found = this.latestLiveAssistantOutbound();
+        if (!found)
+            return undefined;
+        const { record, messageId } = found;
+        if (this.assistantMessageWasAborted(messageId))
+            return undefined;
+        const triggerRecordId = record.jobId ? this.queuedTriggerByJobId.get(record.jobId) : undefined;
+        if (triggerRecordId === undefined)
+            return undefined;
+        return { messageId, triggerRecordId, attachments: record.attachments ?? [] };
+    }
+    latestAssistantDeleteTarget() {
+        const found = this.latestLiveAssistantOutbound();
+        return found ? { messageId: found.messageId } : undefined;
+    }
+    assistantMessageWasAborted(messageId) {
+        return this.records.some((record) => record.type === "agent_event" &&
+            record.messageId === messageId &&
+            record.event.type === "message_end" &&
+            record.event.stopReason === "aborted");
+    }
+    triggerInboundSlice(job) {
+        const completedBoundary = this.lastCompletedTriggerRecordId;
+        return this.records.filter((record) => record.type === "inbound" && record.recordId > completedBoundary && record.recordId <= job.triggerRecordId);
     }
     async noteOutbound(options) {
         const text = options.text.trim();
@@ -396,6 +427,23 @@ export class ConversationRuntime {
             event,
         }, options);
     }
+    async noteAssistantRetry(options) {
+        await this.appendRecord({
+            type: "assistant_retry",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            oldMessageId: options.oldMessageId,
+            newMessageId: options.newMessageId,
+            jobId: options.jobId,
+            triggerRecordId: options.triggerRecordId,
+        });
+    }
+    async noteMessageDelete(messageId) {
+        await this.appendRecord({
+            type: "message_delete",
+            ...buildRecordBase(this.channel, this.nextRecordId),
+            messageId,
+        });
+    }
     async failActiveJob(error) {
         const job = this.activeJob;
         if (!job)

package/dist/runtime/runtime-manager.js

@@ -0,0 +1,51 @@
+import { chatChannelKey, createChatLog } from "../conversation/chat-log.js";
+import { ConversationRuntime } from "./conversation-runtime.js";
+export function createRuntimeManager(deps) {
+    const runtimes = new Map();
+    const openEntry = async (channel, channelKey) => {
+        const runtime = await ConversationRuntime.connect({
+            channelKey,
+            log: createChatLog(deps.config, channel),
+            ownerId: deps.config.discord.ownerId,
+            botUserId: deps.botUserId(),
+        });
+        const unsubscribe = deps.memoryService?.subscribeRuntime(runtime, runtime.channelKey);
+        const release = async () => {
+            unsubscribe?.();
+            await runtime.disconnect();
+        };
+        try {
+            await runtime.armAfterCurrentTail();
+        }
+        catch (error) {
+            await release();
+            throw error;
+        }
+        return { runtime, release };
+    };
+    return {
+        async getRuntimeForChannel(channel) {
+            const channelKey = chatChannelKey(channel);
+            const existing = runtimes.get(channelKey);
+            if (existing)
+                return (await existing).runtime;
+            const entryPromise = openEntry(channel, channelKey);
+            runtimes.set(channelKey, entryPromise);
+            try {
+                return (await entryPromise).runtime;
+            }
+            catch (error) {
+                runtimes.delete(channelKey);
+                throw error;
+            }
+        },
+        async peekRuntime(channelKey) {
+            return (await runtimes.get(channelKey)?.catch(() => undefined))?.runtime;
+        },
+        async disconnectAll() {
+            const entries = await Promise.all([...runtimes.values()].map((entry) => entry.catch(() => undefined)));
+            runtimes.clear();
+            await Promise.all(entries.flatMap((entry) => (entry ? [entry.release()] : [])));
+        },
+    };
+}

package/dist/runtime/scheduler-runner.js

@@ -0,0 +1,243 @@
+import { CRON_SKIPPED, HEARTBEAT_SKIPPED, heartbeatStillDue, runAgentTurn, scheduledUserMessage, } from "../discord/turn.js";
+import { thinkingDurationMs } from "./agent-events.js";
+import { appendSchedulerLog, buildCronInjectionText, buildHeartbeatInjectionText, dueCronSlot, formatIdleDuration, loadSchedulerState, saveSchedulerState, } from "./scheduler.js";
+export function createSchedulerRunner(deps) {
+    const { config, agentWork, familiarAgent, resolveDefaultSession, delivery } = deps;
+    let heartbeatTimer;
+    let cronTimer;
+    let heartbeatQueued = false;
+    let cronRunning = false;
+    let schedulerState = { cron: {} };
+    const saveScheduler = async () => {
+        await saveSchedulerState(config.workspace.dataDir, schedulerState);
+    };
+    const initializeHeartbeatState = async (runtime) => {
+        if (!config.heartbeat.enabled || schedulerState.heartbeat)
+            return;
+        const now = Date.now();
+        const lastUserInteractionAt = runtime.getLastUserInteractionAt();
+        if (now - lastUserInteractionAt < config.heartbeat.idleThresholdMs)
+            return;
+        // Treat a cold start on an already-idle transcript as "we just fired at boot":
+        // the standard cadence/first-fire branches in isHeartbeatDue then handle user-reply
+        // vs. no-reply correctly without a separate suppression concept.
+        schedulerState.heartbeat = { lastFiredAt: new Date(now).toISOString() };
+        await saveScheduler();
+    };
+    const runHeartbeat = async () => {
+        if (!config.heartbeat.enabled)
+            return;
+        if (agentWork.activeOwner)
+            return;
+        if (heartbeatQueued)
+            return;
+        heartbeatQueued = true;
+        let runtime;
+        try {
+            const session = await resolveDefaultSession();
+            runtime = session.runtime;
+            const heartbeatRuntime = session.runtime;
+            const now = Date.now();
+            if (heartbeatRuntime.hasLiveWork())
+                return;
+            const lastUserInteractionAt = heartbeatRuntime.getLastUserInteractionAt();
+            if (!heartbeatStillDue(config, now, lastUserInteractionAt, schedulerState.heartbeat?.lastFiredAt)) {
+                return;
+            }
+            const turn = await runAgentTurn("heartbeat", heartbeatRuntime, (onEvent) => agentWork.promptScheduledMessage(heartbeatRuntime, async () => {
+                const queuedNow = Date.now();
+                const latestUserInteractionAt = heartbeatRuntime.getLastUserInteractionAt();
+                if (heartbeatRuntime.hasLiveWork())
+                    return HEARTBEAT_SKIPPED;
+                if (!heartbeatStillDue(config, queuedNow, latestUserInteractionAt, schedulerState.heartbeat?.lastFiredAt)) {
+                    return HEARTBEAT_SKIPPED;
+                }
+                schedulerState.heartbeat = { lastFiredAt: new Date(queuedNow).toISOString() };
+                await saveScheduler();
+                const text = buildHeartbeatInjectionText({ now: queuedNow, idleSince: latestUserInteractionAt });
+                await heartbeatRuntime.noteHeartbeat(`heartbeat stirred after ${formatIdleDuration(queuedNow - latestUserInteractionAt)}`);
+                return scheduledUserMessage(text, queuedNow);
+            }, onEvent, { skipAmbient: true }));
+            if (!turn)
+                return;
+            const { reply, parsedReply, summary, assistantMessageId } = turn;
+            const messageIds = await delivery.deliver({ reply, parsedReply });
+            await heartbeatRuntime.noteOutbound({
+                text: parsedReply.text,
+                messageIds,
+                webMessageId: assistantMessageId,
+                attachments: reply.attachments,
+                thinking: summary.thinking,
+                thinkingMs: thinkingDurationMs(summary),
+                silent: parsedReply.silent,
+                jobId: "heartbeat",
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await runtime?.noteHeartbeatFailure(message);
+            await runtime?.appendError(`Heartbeat failed: ${message}`);
+            console.error("Heartbeat failed", error);
+        }
+        finally {
+            heartbeatQueued = false;
+        }
+    };
+    const markCronSlotStarted = async (job, slot) => {
+        schedulerState.cron[job.id] = {
+            lastFiredSlot: slot,
+            lastFiredAt: new Date().toISOString(),
+            ...(schedulerState.cron[job.id]?.completed ? { completed: true } : {}),
+        };
+        await saveScheduler();
+    };
+    const completeCronSlot = async (job, slot) => {
+        schedulerState.cron[job.id] = {
+            ...schedulerState.cron[job.id],
+            lastFiredSlot: slot,
+            lastFiredAt: schedulerState.cron[job.id]?.lastFiredAt ?? new Date().toISOString(),
+            ...(job.frequency === "once" ? { completed: true } : {}),
+        };
+        await saveScheduler();
+    };
+    const runCronJob = async (job, slot, runtime) => {
+        await appendSchedulerLog(config.workspace.dataDir, {
+            type: "cron_due",
+            jobId: job.id,
+            slot,
+            deliveryMode: job.deliveryMode,
+        });
+        if (job.deliveryMode === "follow_up" && agentWork.activeOwner === runtime.channelKey) {
+            const now = Date.now();
+            const text = buildCronInjectionText({ job, slot, now });
+            await appendSchedulerLog(config.workspace.dataDir, {
+                type: "cron_started",
+                jobId: job.id,
+                slot,
+                deliveryMode: job.deliveryMode,
+            });
+            await markCronSlotStarted(job, slot);
+            await familiarAgent.followUpMessage(runtime.channelKey, scheduledUserMessage(text, now), {
+                skipAmbient: true,
+            });
+            await completeCronSlot(job, slot);
+            await appendSchedulerLog(config.workspace.dataDir, {
+                type: "cron_completed",
+                jobId: job.id,
+                slot,
+                deliveryMode: job.deliveryMode,
+                detail: "queued as follow-up",
+            });
+            return;
+        }
+        const jobKey = `cron:${job.id}`;
+        const turn = await runAgentTurn(jobKey, runtime, (onEvent) => agentWork.promptScheduledMessage(runtime, async () => {
+            const jobState = schedulerState.cron[job.id];
+            if (jobState?.completed || jobState?.lastFiredSlot === slot)
+                return CRON_SKIPPED;
+            const now = Date.now();
+            await appendSchedulerLog(config.workspace.dataDir, {
+                type: "cron_started",
+                jobId: job.id,
+                slot,
+                deliveryMode: job.deliveryMode,
+            });
+            await markCronSlotStarted(job, slot);
+            return scheduledUserMessage(buildCronInjectionText({ job, slot, now }), now);
+        }, onEvent, { skipAmbient: true }));
+        if (!turn) {
+            await appendSchedulerLog(config.workspace.dataDir, {
+                type: "cron_skipped",
+                jobId: job.id,
+                slot,
+                deliveryMode: job.deliveryMode,
+                detail: "already completed before prompt",
+            });
+            return;
+        }
+        const { reply, parsedReply, summary, assistantMessageId } = turn;
+        const messageIds = await delivery.deliver({ reply, parsedReply });
+        await runtime.noteOutbound({
+            text: parsedReply.text,
+            messageIds,
+            webMessageId: assistantMessageId,
+            attachments: reply.attachments,
+            thinking: summary.thinking,
+            thinkingMs: thinkingDurationMs(summary),
+            silent: parsedReply.silent,
+            jobId: jobKey,
+        });
+        await completeCronSlot(job, slot);
+        await appendSchedulerLog(config.workspace.dataDir, {
+            type: "cron_completed",
+            jobId: job.id,
+            slot,
+            deliveryMode: job.deliveryMode,
+        });
+    };
+    const tickCron = async () => {
+        if (!config.cron.enabled || cronRunning)
+            return;
+        cronRunning = true;
+        try {
+            const session = await resolveDefaultSession();
+            for (const job of config.cron.jobs) {
+                const slot = dueCronSlot(job, schedulerState.cron[job.id], Date.now());
+                if (!slot)
+                    continue;
+                try {
+                    await runCronJob(job, slot, session.runtime);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    await appendSchedulerLog(config.workspace.dataDir, {
+                        type: "cron_failed",
+                        jobId: job.id,
+                        slot,
+                        deliveryMode: job.deliveryMode,
+                        detail: message,
+                    });
+                    await session.runtime.appendError(`Cron job ${job.id} failed: ${message}`);
+                    console.error(`Cron job ${job.id} failed`, error);
+                }
+            }
+        }
+        finally {
+            cronRunning = false;
+        }
+    };
+    const tickHeartbeat = () => {
+        void runHeartbeat().catch((error) => console.error("Heartbeat tick failed", error));
+    };
+    const rearmHeartbeat = () => {
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = undefined;
+        }
+        if (config.heartbeat.enabled) {
+            heartbeatTimer = setInterval(tickHeartbeat, Math.min(config.heartbeat.intervalMs, 60_000));
+        }
+    };
+    const start = async () => {
+        schedulerState = await loadSchedulerState(config.workspace.dataDir);
+        if (config.heartbeat.enabled) {
+            await initializeHeartbeatState((await resolveDefaultSession()).runtime);
+            rearmHeartbeat();
+            tickHeartbeat();
+        }
+        if (config.cron.enabled && config.cron.jobs.some((job) => job.enabled)) {
+            const runCronTick = () => {
+                void tickCron().catch((error) => console.error("Cron tick failed", error));
+            };
+            cronTimer = setInterval(runCronTick, config.cron.pollMs);
+            runCronTick();
+        }
+    };
+    const stop = () => {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        if (cronTimer)
+            clearInterval(cronTimer);
+    };
+    return { start, rearmHeartbeat, stop };
+}

package/dist/{scheduler.js → runtime/scheduler.js}

@@ -1,8 +1,8 @@
 import { appendFile, mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { readFileOrNull } from "./util/fs.js";
-import { formatLocalTimestamp, toDate } from "./util/time.js";
-export { formatLocalTimestamp } from "./util/time.js";
+import { readFileOrNull } from "../util/fs.js";
+import { formatLocalTimestamp, toDate } from "../util/time.js";
+export { formatLocalTimestamp } from "../util/time.js";
 const stateWriteQueues = new Map();
 export function formatIdleDuration(ms) {
     if (!Number.isFinite(ms) || ms <= 0)
@@ -54,7 +54,7 @@ function daysInMonth(year, month) {
 }
 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.
+    // Local Date construction follows host timezone DST rules; rare skipped or repeated wall-clock hours are acceptable.
     return new Date(year, month, clampedDay, time.hour, time.minute, 0, 0);
 }
 function cronSlotKey(job, date) {