@tea-agent/loop-agent 0.28.11 → 0.28.12

package/dist/worker/scheduler/clock.js

@@ -0,0 +1,420 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { countActiveLeases, readExecutionLease } from "./lease.js";
+import { getClockInstallReceiptPath, getClockReceiptPath, getLeasesDir, } from "./paths.js";
+import { ensureSchedulerDirs } from "./store.js";
+import { readdir } from "node:fs/promises";
+export const CLOCK_RECEIPT_SCHEMA_VERSION = 1;
+export const CLOCK_INSTALL_SCHEMA_VERSION = 1;
+export const DEFAULT_CLOCK_INTERVAL_SEC = 60;
+export function computeStaleAfterSec(expectedIntervalSec) {
+    const interval = Number.isFinite(expectedIntervalSec) && expectedIntervalSec > 0
+        ? Math.floor(expectedIntervalSec)
+        : DEFAULT_CLOCK_INTERVAL_SEC;
+    return Math.max(180, 3 * interval);
+}
+export function createRunningClockReceipt(input) {
+    const now = input.now ?? new Date();
+    return {
+        schemaVersion: CLOCK_RECEIPT_SCHEMA_VERSION,
+        expectedIntervalSec: input.expectedIntervalSec ?? DEFAULT_CLOCK_INTERVAL_SEC,
+        lastAttemptAt: now.toISOString(),
+        lastCompletedAt: null,
+        lastOutcome: "running",
+        lastError: null,
+        lastSource: input.source ?? "manual",
+        lastDurationMs: null,
+    };
+}
+export function completeClockReceipt(running, input) {
+    const now = input.now ?? new Date();
+    const started = Date.parse(running.lastAttemptAt);
+    const durationMs = Number.isFinite(started)
+        ? Math.max(0, now.getTime() - started)
+        : null;
+    if (input.ok) {
+        return {
+            ...running,
+            lastCompletedAt: now.toISOString(),
+            lastOutcome: "ok",
+            lastError: null,
+            lastDurationMs: durationMs,
+        };
+    }
+    return {
+        ...running,
+        lastCompletedAt: now.toISOString(),
+        lastOutcome: "error",
+        lastError: input.error ?? {
+            code: "clock-tick-error",
+            message: "scheduler tick failed",
+        },
+        lastDurationMs: durationMs,
+    };
+}
+export async function readClockReceipt(controlRepoRoot) {
+    try {
+        const raw = await readFile(getClockReceiptPath(controlRepoRoot), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.schemaVersion !== CLOCK_RECEIPT_SCHEMA_VERSION)
+            return null;
+        return parsed;
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeClockReceipt(controlRepoRoot, receipt) {
+    await ensureSchedulerDirs(controlRepoRoot);
+    await writeJsonAtomic(getClockReceiptPath(controlRepoRoot), receipt, {
+        repoRoot: controlRepoRoot,
+    });
+}
+export async function readClockInstallReceipt(controlRepoRoot) {
+    try {
+        const raw = await readFile(getClockInstallReceiptPath(controlRepoRoot), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.schemaVersion !== CLOCK_INSTALL_SCHEMA_VERSION)
+            return null;
+        return parsed;
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeClockInstallReceipt(controlRepoRoot, receipt) {
+    await ensureSchedulerDirs(controlRepoRoot);
+    await writeJsonAtomic(getClockInstallReceiptPath(controlRepoRoot), receipt, {
+        repoRoot: controlRepoRoot,
+    });
+}
+export function hashManagedConfig(parts) {
+    const payload = [
+        parts.provider,
+        parts.unitName,
+        parts.controlRepoRoot,
+        String(parts.intervalSec),
+        parts.nodeBin,
+        parts.agentWorkerEntry,
+        parts.loopAgentBin,
+    ].join("\n");
+    const digest = createHash("sha256").update(payload).digest("hex");
+    return `sha256:${digest}`;
+}
+export function deriveClockUnitName(controlRepoRoot) {
+    const canonical = canonicalizeControlRoot(controlRepoRoot);
+    const digest = createHash("sha256")
+        .update(canonical)
+        .digest("hex")
+        .slice(0, 8);
+    return `com.tea-agent.loop-agent.night.${digest}`;
+}
+export function canonicalizeControlRoot(controlRepoRoot) {
+    // Keep stable across platforms; realpath is applied by install resolvers.
+    return controlRepoRoot.replace(/\\/g, "/").replace(/\/+$/, "") || "/";
+}
+export function classifyClockHealth(input) {
+    const now = input.now ?? new Date();
+    const receipt = input.receipt ?? null;
+    const install = input.install ?? null;
+    const expectedIntervalSec = receipt?.expectedIntervalSec ??
+        install?.intervalSec ??
+        DEFAULT_CLOCK_INTERVAL_SEC;
+    const staleAfterSec = computeStaleAfterSec(expectedIntervalSec);
+    const activeLeaseCount = input.activeLeaseCount ?? 0;
+    const maxConcurrency = input.defaultMaxConcurrency ?? 1;
+    const providerSupported = input.providerSupported !== false;
+    const base = {
+        schemaVersion: 1,
+        expectedIntervalSec,
+        staleAfterSec,
+        provider: install?.provider ?? null,
+        unitName: install?.unitName ?? null,
+        unitLoaded: input.unitLoaded ?? null,
+        install,
+        receipt,
+        lastSuccessfulTickAt: receipt?.lastOutcome === "ok" ? receipt.lastCompletedAt : null,
+        activeLeaseCount,
+    };
+    if (!providerSupported && !install) {
+        return {
+            ...base,
+            status: "unsupported",
+            message: "No supported user-level OS timer provider on this host (need launchd, systemd --user, or schtasks).",
+            nextAction: "Use agent-worker scheduler tick --repo . manually, or move to a supported platform.",
+        };
+    }
+    if (!install && (input.unitPresent === false || input.unitPresent == null)) {
+        // No install receipt: still allow "observed" health from manual ticks.
+        if (receipt) {
+            const freshness = classifyReceiptFreshness(receipt, now, staleAfterSec);
+            if (freshness === "running") {
+                if (activeLeaseCount >= maxConcurrency) {
+                    return {
+                        ...base,
+                        status: "busy",
+                        message: "Clock tick is running and default concurrency capacity is in use.",
+                        nextAction: null,
+                    };
+                }
+                return {
+                    ...base,
+                    status: "healthy",
+                    message: "Clock tick is currently running (manual or unmanaged).",
+                    nextAction: "Optional: agent-worker scheduler clock install --repo . for automatic ticks.",
+                };
+            }
+            if (freshness === "fresh-ok") {
+                return {
+                    ...base,
+                    status: "healthy",
+                    message: "Recent successful tick observed, but no managed OS timer is installed.",
+                    nextAction: "Install automatic clock: agent-worker scheduler clock install --repo .",
+                };
+            }
+            if (freshness === "fresh-error") {
+                return {
+                    ...base,
+                    status: "degraded",
+                    message: `Recent tick failed: ${receipt.lastError?.message ?? "unknown error"}`,
+                    nextAction: "Inspect last tick error; re-run scheduler tick.",
+                };
+            }
+            return {
+                ...base,
+                status: "stale",
+                message: "Tick receipt is stale and no managed OS timer is installed.",
+                nextAction: "agent-worker scheduler clock install --repo .",
+            };
+        }
+        return {
+            ...base,
+            status: "missing",
+            message: "No managed clock timer installed and no tick receipt yet.",
+            nextAction: "agent-worker scheduler clock install --repo .",
+        };
+    }
+    if (input.configMatches === false ||
+        input.pathsMatch === false ||
+        (install && input.unitPresent === false)) {
+        return {
+            ...base,
+            status: "drifted",
+            message: input.unitPresent === false
+                ? "Install receipt exists but managed OS unit is missing."
+                : "Managed clock unit or package entry has drifted from install receipt.",
+            nextAction: "agent-worker scheduler clock install --repo .",
+        };
+    }
+    if (!receipt) {
+        return {
+            ...base,
+            status: "stale",
+            message: "Managed clock is installed but no tick receipt has been written yet.",
+            nextAction: "Wait for the next timer fire, or run scheduler tick once.",
+        };
+    }
+    const freshness = classifyReceiptFreshness(receipt, now, staleAfterSec);
+    if (freshness === "running") {
+        if (activeLeaseCount >= maxConcurrency) {
+            return {
+                ...base,
+                status: "busy",
+                message: "Clock tick is running and default concurrency capacity is in use.",
+                nextAction: null,
+            };
+        }
+        return {
+            ...base,
+            status: "healthy",
+            message: "Clock tick is currently running.",
+            nextAction: null,
+        };
+    }
+    if (freshness === "fresh-error") {
+        return {
+            ...base,
+            status: "degraded",
+            message: `Last tick failed: ${receipt.lastError?.message ?? "unknown error"}`,
+            nextAction: "Inspect scheduler doctor / last tick error, then re-run tick.",
+        };
+    }
+    if (freshness === "fresh-ok") {
+        return {
+            ...base,
+            status: "healthy",
+            message: "Managed clock is installed and recent ticks succeeded.",
+            nextAction: null,
+        };
+    }
+    return {
+        ...base,
+        status: "stale",
+        message: `No fresh tick within ${staleAfterSec}s (expected every ${expectedIntervalSec}s).`,
+        nextAction: "agent-worker scheduler clock status --repo . → reinstall if needed",
+    };
+}
+function classifyReceiptFreshness(receipt, now, staleAfterSec) {
+    const attemptMs = Date.parse(receipt.lastAttemptAt);
+    const completedMs = receipt.lastCompletedAt
+        ? Date.parse(receipt.lastCompletedAt)
+        : Number.NaN;
+    const freshest = Number.isFinite(completedMs)
+        ? Math.max(attemptMs, completedMs)
+        : attemptMs;
+    const ageSec = Number.isFinite(freshest)
+        ? (now.getTime() - freshest) / 1000
+        : Number.POSITIVE_INFINITY;
+    if (receipt.lastOutcome === "running" && ageSec <= staleAfterSec) {
+        return "running";
+    }
+    if (ageSec > staleAfterSec)
+        return "stale";
+    if (receipt.lastOutcome === "error")
+        return "fresh-error";
+    if (receipt.lastOutcome === "ok")
+        return "fresh-ok";
+    return "stale";
+}
+export async function countActiveExecutionLeases(controlRepoRoot, now = new Date()) {
+    const leases = [];
+    try {
+        const names = await readdir(getLeasesDir(controlRepoRoot));
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const scheduleId = name.slice(0, -5);
+            const lease = await readExecutionLease(controlRepoRoot, scheduleId);
+            if (lease)
+                leases.push(lease);
+        }
+    }
+    catch {
+        return 0;
+    }
+    return countActiveLeases(leases, now);
+}
+/**
+ * Wrap any schedulerTick implementation with Clock receipt bookkeeping.
+ * Business semantics stay in schedulerTick; this only records evidence.
+ */
+export async function runRecordedSchedulerTick(input) {
+    const now = input.now ?? new Date();
+    const running = createRunningClockReceipt({
+        now,
+        expectedIntervalSec: input.expectedIntervalSec,
+        source: input.source ?? "manual",
+    });
+    // Prefer install interval when present.
+    if (!input.expectedIntervalSec) {
+        const install = await readClockInstallReceipt(input.controlRepoRoot);
+        if (install?.intervalSec) {
+            running.expectedIntervalSec = install.intervalSec;
+        }
+    }
+    await writeClockReceipt(input.controlRepoRoot, running);
+    try {
+        const result = await input.tick();
+        const completed = completeClockReceipt(running, {
+            now: new Date(),
+            ok: true,
+        });
+        await writeClockReceipt(input.controlRepoRoot, completed);
+        return result;
+    }
+    catch (error) {
+        const code = error &&
+            typeof error === "object" &&
+            "code" in error &&
+            typeof error.code === "string"
+            ? error.code
+            : "clock-tick-error";
+        const message = error instanceof Error ? error.message : String(error);
+        const completed = completeClockReceipt(running, {
+            now: new Date(),
+            ok: false,
+            error: { code, message },
+        });
+        await writeClockReceipt(input.controlRepoRoot, completed);
+        throw error;
+    }
+}
+export function formatClockHealthHuman(health) {
+    const lines = [
+        `Clock: ${health.status}`,
+        health.provider
+            ? `Provider: ${health.provider}${health.unitLoaded === true ? " (loaded)" : health.unitLoaded === false ? " (not loaded)" : ""}`
+            : "Provider: (none)",
+        `Interval: ${health.expectedIntervalSec}s`,
+    ];
+    if (health.unitName)
+        lines.push(`Unit: ${health.unitName}`);
+    if (health.receipt) {
+        const r = health.receipt;
+        const when = r.lastCompletedAt ?? r.lastAttemptAt ?? "(never)";
+        lines.push(`Last tick: ${r.lastOutcome} at ${when}`);
+        if (r.lastError) {
+            lines.push(`Last error: ${r.lastError.code}: ${r.lastError.message}`);
+        }
+        if (r.lastDurationMs != null) {
+            lines.push(`Last duration: ${r.lastDurationMs}ms`);
+        }
+        lines.push(`Source: ${r.lastSource}`);
+    }
+    else {
+        lines.push("Last tick: (none)");
+    }
+    lines.push(health.message);
+    if (health.nextAction) {
+        lines.push(`Next: ${health.nextAction}`);
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+export function clockDoctorSeverity(input) {
+    const { health, hasFutureScheduled, hasDueUnclaimed } = input;
+    if (health.status === "healthy" || health.status === "busy") {
+        return health.status === "busy" ? "info" : null;
+    }
+    if (health.status === "drifted")
+        return "error";
+    if (hasDueUnclaimed) {
+        if (health.status === "missing" ||
+            health.status === "stale" ||
+            health.status === "degraded" ||
+            health.status === "unsupported") {
+            return "error";
+        }
+    }
+    if (hasFutureScheduled) {
+        if (health.status === "missing" ||
+            health.status === "stale" ||
+            health.status === "unsupported") {
+            return "warning";
+        }
+        if (health.status === "degraded")
+            return "warning";
+    }
+    // no activity
+    if (health.status === "missing" ||
+        health.status === "stale" ||
+        health.status === "unsupported") {
+        return "info";
+    }
+    if (health.status === "degraded")
+        return "warning";
+    return "info";
+}

package/dist/worker/scheduler/doctor.js

@@ -1,11 +1,14 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { listTaskPoolStates } from "../pool/run-store.js";
+import { clockDoctorSeverity, readClockInstallReceipt, readClockReceipt, classifyClockHealth, countActiveExecutionLeases, } from "./clock.js";
+import { selectClockAdapter } from "./clock-install.js";
 import { getLeasesDir, getMutationLockPath, getSchedulerRoot, } from "./paths.js";
 import { classifyLeaseLiveness, classifyLeaseRecovery } from "./recovery.js";
 import { verifyEvidenceArchive } from "./evidence.js";
 import { readExecutionLease } from "./lease.js";
 import { listPendingJournals, listSchedules, readAdmission, readExecution, readLedgerEvents, } from "./store.js";
+import { evaluateOnceDue } from "./trigger.js";
 import { ACTIVE_SCHEDULE_STATUSES, isTerminalScheduleStatus, } from "./types.js";
 /**
  * Read-only consistency check for Night Scheduler facts.
@@ -96,7 +99,8 @@ export async function diagnoseScheduler(controlRepoRoot, options) {
                 }
             }
         }
-        if (isTerminalScheduleStatus(schedule.status) && schedule.currentExecutionId) {
+        if (isTerminalScheduleStatus(schedule.status) &&
+            schedule.currentExecutionId) {
             const evidence = await verifyEvidenceArchive({
                 controlRepoRoot,
                 executionId: schedule.currentExecutionId,
@@ -306,6 +310,87 @@ export async function diagnoseScheduler(controlRepoRoot, options) {
             message: "scheduler root does not exist yet (no schedules submitted)",
         });
     }
+    // Clock health (OS timer + tick receipt)
+    try {
+        const [clockReceipt, clockInstall, activeLeaseCount] = await Promise.all([
+            readClockReceipt(controlRepoRoot),
+            readClockInstallReceipt(controlRepoRoot),
+            countActiveExecutionLeases(controlRepoRoot, now),
+        ]);
+        const adapter = selectClockAdapter();
+        let unitPresent = null;
+        let unitLoaded = null;
+        let configMatches = null;
+        let providerSupported = adapter != null;
+        if (adapter) {
+            providerSupported = await adapter.isAvailable();
+            if (clockInstall) {
+                const probe = await adapter.probe({
+                    receipt: clockInstall,
+                    unitName: clockInstall.unitName,
+                });
+                unitPresent = probe.present;
+                unitLoaded = probe.loaded;
+                configMatches = probe.configMatches;
+            }
+        }
+        const health = classifyClockHealth({
+            now,
+            receipt: clockReceipt,
+            install: clockInstall,
+            unitPresent,
+            unitLoaded,
+            configMatches,
+            providerSupported,
+            activeLeaseCount,
+            defaultMaxConcurrency: 1,
+        });
+        const futureScheduled = schedules.some((schedule) => (schedule.status === "scheduled" || schedule.status === "waiting") &&
+            schedule.trigger?.type === "once" &&
+            Date.parse(schedule.trigger.executeAtUtc) > now.getTime());
+        const dueUnclaimed = schedules.some((schedule) => {
+            if (schedule.status !== "scheduled" && schedule.status !== "waiting") {
+                return false;
+            }
+            const trigger = schedule.trigger;
+            if (!trigger || trigger.type !== "once")
+                return false;
+            const decision = evaluateOnceDue({
+                nowUtc: now,
+                executeAtUtc: trigger.executeAtUtc,
+                ...(trigger.latestStartAtUtc
+                    ? { latestStartAtUtc: trigger.latestStartAtUtc }
+                    : {}),
+                timezone: trigger.displayTimezone ??
+                    schedule.policySnapshot?.timezone ??
+                    "Asia/Shanghai",
+                allowedHours: schedule.policySnapshot?.allowedHours ?? ["00:00-08:00"],
+                misfirePolicy: trigger.misfirePolicy ??
+                    schedule.policySnapshot?.misfirePolicy ??
+                    "wait-next-window",
+            });
+            return decision.kind === "eligible";
+        });
+        const severity = clockDoctorSeverity({
+            health,
+            hasFutureScheduled: futureScheduled,
+            hasDueUnclaimed: dueUnclaimed,
+        });
+        if (severity) {
+            findings.push({
+                code: `clock-${health.status}`,
+                severity,
+                message: `${health.message}${health.nextAction ? ` Next: ${health.nextAction}` : ""}`,
+            });
+        }
+    }
+    catch (error) {
+        findings.push({
+            code: "clock-unreadable",
+            severity: "warning",
+            message: `cannot classify clock health: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
     const activeCount = schedules.filter((item) => ACTIVE_SCHEDULE_STATUSES.has(item.status)).length;
     const errors = findings.filter((item) => item.severity === "error");
     return {

package/dist/worker/scheduler/index.js

@@ -20,4 +20,6 @@ export * from "./recovery.js";
 export * from "./retry.js";
 export * from "./prepared-attempt-recovery.js";
 export * from "./auto-followup.js";
+export * from "./clock.js";
+export * from "./clock-install.js";
 export { registerSchedulerCommands } from "./cli.js";

package/dist/worker/scheduler/morning-window.js

@@ -1,3 +1,4 @@
+import { classifyClockHealth, readClockInstallReceipt, readClockReceipt, } from "./clock.js";
 import { listSchedules } from "./store.js";
 /**
  * Project Night Scheduler facts for morning report --window night.
@@ -23,6 +24,17 @@ export async function buildNightMorningWindow(input) {
             row.status === "waiting" ||
             row.status === "validated").length,
     };
+    const [clockReceipt, clockInstall] = await Promise.all([
+        readClockReceipt(input.controlRepoRoot),
+        readClockInstallReceipt(input.controlRepoRoot),
+    ]);
+    const clockHealth = classifyClockHealth({
+        now,
+        receipt: clockReceipt,
+        install: clockInstall,
+        unitPresent: clockInstall ? true : null,
+        providerSupported: true,
+    });
     return {
         schemaVersion: 1,
         window: "night",
@@ -30,6 +42,13 @@ export async function buildNightMorningWindow(input) {
         timezone,
         generatedAt: now.toISOString(),
         schedules: rows,
+        clock: {
+            status: clockHealth.status,
+            message: clockHealth.message,
+            lastSuccessfulTickAt: clockHealth.lastSuccessfulTickAt,
+            expectedIntervalSec: clockHealth.expectedIntervalSec,
+            nextAction: clockHealth.nextAction,
+        },
         summary,
     };
 }
@@ -49,6 +68,17 @@ export function renderNightMorningMarkdown(window) {
         `- Pending harvest: ${window.summary.pendingHarvest}`,
         `- Still scheduled/waiting: ${window.summary.scheduledOrWaiting}`,
         "",
+        "## Clock",
+        "",
+        window.clock
+            ? `- Status: ${window.clock.status} (interval ${window.clock.expectedIntervalSec}s)`
+            : "- Status: unknown",
+        window.clock?.lastSuccessfulTickAt
+            ? `- Last successful tick: ${window.clock.lastSuccessfulTickAt}`
+            : "- Last successful tick: (none)",
+        window.clock ? `- Detail: ${window.clock.message}` : "",
+        window.clock?.nextAction ? `- Next: ${window.clock.nextAction}` : "",
+        "",
         "## Schedules",
         "",
         "| Schedule | Task | Plan | Status | Merge | Card | Next |",
@@ -123,7 +153,7 @@ export function resolveNextAction(schedule) {
         return `agent-worker scheduler discard ${schedule.id} --repo . --reason "..."${schedule.status === "failed" || schedule.status === "human_required" ? " --force" : ""}`;
     }
     if (schedule.status === "scheduled" || schedule.status === "waiting") {
-        return "wait for scheduler tick / inspect schedule status";
+        return "wait for OS clock timer / scheduler tick; inspect: agent-worker scheduler clock status --repo .";
     }
     if (schedule.status === "validated") {
         return `agent-worker scheduler add ${schedule.id} --approve-gate <token> --repo .`;

package/dist/worker/scheduler/paths.js

@@ -40,6 +40,14 @@ export function getLedgerPath(controlRepoRoot) {
 export function getMutationLockPath(controlRepoRoot) {
     return path.join(getSchedulerRoot(controlRepoRoot), "mutation.lock");
 }
+/** Actual tick receipt (manual + OS timer share this file). */
+export function getClockReceiptPath(controlRepoRoot) {
+    return path.join(getSchedulerRoot(controlRepoRoot), "clock.json");
+}
+/** Managed OS timer install receipt (not the same as tick evidence). */
+export function getClockInstallReceiptPath(controlRepoRoot) {
+    return path.join(getSchedulerRoot(controlRepoRoot), "clock-install.json");
+}
 export function getSchedulePath(controlRepoRoot, scheduleId) {
     assertSafeSchedulerId(scheduleId, "scheduleId");
     const schedulePath = path.join(getSchedulesDir(controlRepoRoot), `${scheduleId}.json`);