@nanhara/hara 0.53.0 → 0.62.0

package/dist/cron/runner.js

@@ -0,0 +1,109 @@
+// The tick runner for `hara cron`: find due jobs and run each as a fresh `hara` session (the fired
+// session IS the agent — same model as openclaw/hermes). Meant to be invoked every minute by the OS
+// scheduler (see install.ts). A lock file prevents overlapping ticks from double-firing a slow job.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, rmSync, statSync, appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadJobs, recordRun, cronDir, logPath } from "./store.js";
+import { isDue } from "./schedule.js";
+/** Jobs that are enabled AND due at `nowMs` (pure — for the tick and for testing). */
+export function dueJobs(jobs, nowMs) {
+    return jobs.filter((j) => j.enabled && isDue(j, nowMs));
+}
+/** How to invoke hara again — handles both `node dist/index.js` (argv[1] is a script) and the compiled
+ *  single-binary (argv[1] is a user arg, so re-invoke the binary directly). Used by the tick + by install. */
+export function selfArgv() {
+    const a1 = process.argv[1];
+    return a1 && /\.[cm]?js$|\.ts$/.test(a1) ? [process.execPath, a1] : [process.execPath];
+}
+const lockPath = () => join(cronDir(), ".tick.lock");
+// Generous: a live-PID owner is respected this long (so a genuinely long job isn't double-fired); past it
+// we assume PID reuse and take over. A *dead* owner is taken over within one tick regardless (see below).
+const LOCK_STALE_MS = 6 * 60 * 60_000;
+/** Keep a per-job log from growing forever: once over ~1MB, retain only the last ~256KB. */
+function capLog(log) {
+    try {
+        if (existsSync(log) && statSync(log).size > 1_000_000) {
+            writeFileSync(log, "…[older log truncated]\n" + readFileSync(log, "utf8").slice(-256_000));
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Run one job's task in a fresh hara process (full-auto, no prompts), appending output to its log.
+ *  Exported so `hara cron run <id>` can fire a job on demand, ignoring its schedule. */
+export function runJobOnce(job) {
+    return new Promise((resolve) => {
+        mkdirSync(join(cronDir(), "logs"), { recursive: true });
+        const args = job.mode === "org" ? ["org", job.task] : ["-p", job.task, "--approval", "full-auto"];
+        const log = logPath(job.id);
+        capLog(log);
+        try {
+            appendFileSync(log, `\n===== ${new Date().toISOString()} · ${job.name} (${job.mode}) =====\n`);
+        }
+        catch {
+            /* logging is best-effort */
+        }
+        const self = selfArgv();
+        const child = spawn(self[0], [...self.slice(1), ...args], { cwd: job.cwd, env: process.env });
+        const append = (d) => {
+            try {
+                appendFileSync(log, d);
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        child.stdout.on("data", append);
+        child.stderr.on("data", append);
+        child.on("error", (e) => resolve({ ok: false, error: String(e?.message ?? e) }));
+        child.on("close", (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: `exited ${code}` }));
+    });
+}
+/** One scheduler tick: run every due job (sequentially), recording each outcome. Lock-guarded so an
+ *  overlapping tick (launchd fires every 60s; a job may run longer) skips instead of double-firing.
+ *  `run` is injectable for tests. Returns the job ids that ran. */
+export async function runTick(nowMs, run = runJobOnce) {
+    mkdirSync(cronDir(), { recursive: true });
+    const lock = lockPath();
+    if (existsSync(lock)) {
+        let held = false;
+        try {
+            const fresh = nowMs - statSync(lock).mtimeMs < LOCK_STALE_MS;
+            const pid = Number(readFileSync(lock, "utf8").trim());
+            let alive = false;
+            try {
+                alive = pid > 0 && (process.kill(pid, 0), true); // signal 0 = liveness probe
+            }
+            catch {
+                alive = false; // ESRCH → the tick that wrote this lock is gone
+            }
+            held = fresh && alive; // respect a lock only if it's recent AND owned by a live process (no crash-poison)
+        }
+        catch {
+            held = false; // unreadable lock → proceed
+        }
+        if (held)
+            return { ran: [], skipped: "another tick is in progress" };
+    }
+    writeFileSync(lock, String(process.pid));
+    try {
+        const due = dueJobs(loadJobs(), nowMs);
+        const ran = [];
+        for (const job of due) {
+            const r = await run(job);
+            recordRun(job.id, nowMs, r.ok ? "ok" : "error", r.error);
+            ran.push(job.id);
+        }
+        return { ran };
+    }
+    finally {
+        try {
+            rmSync(lock);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}

package/dist/cron/schedule.js

@@ -0,0 +1,147 @@
+// Schedule parsing + matching for `hara cron` — the pure, testable core (no I/O, no Date.now()).
+// Three forms, mirroring openclaw/hermes: a 5-field cron expr, a fixed interval ("every 30m"), and a
+// one-shot ("in 2h" or an ISO timestamp). Cron matching is hand-rolled (no dependency) at minute
+// granularity in LOCAL time — same mental model as a real crontab.
+const UNIT_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** "45s" | "30m" | "2h" | "1d" → milliseconds, or null. */
+export function durationToMs(s) {
+    const m = /^(\d+)\s*([smhd])$/.exec(s.trim());
+    if (!m)
+        return null;
+    return Number(m[1]) * UNIT_MS[m[2]];
+}
+// Parse one cron field — supports `*`, a step `/n`, a single value `a`, a range `a-b`, a list `a,b`,
+// and a stepped range `a-b/n` — into the explicit set of matching values.
+const isUint = (s) => /^\d+$/.test(s); // strict — `Number("")`/`Number(" ")` are 0, so reject non-digits
+function parseField(f, min, max) {
+    const out = new Set();
+    for (const part of f.split(",")) {
+        if (part === "")
+            return null; // empty list element (e.g. a trailing/leading comma)
+        const slash = part.split("/");
+        if (slash.length > 2)
+            return null; // more than one step
+        const [rangeRaw, stepRaw] = slash;
+        if (stepRaw !== undefined && !isUint(stepRaw))
+            return null; // "5/", "5/x"
+        const step = stepRaw === undefined ? 1 : Number(stepRaw);
+        if (step < 1)
+            return null;
+        let lo;
+        let hi;
+        if (rangeRaw === "*") {
+            lo = min;
+            hi = max;
+        }
+        else if (rangeRaw.includes("-")) {
+            const ab = rangeRaw.split("-");
+            if (ab.length !== 2 || !isUint(ab[0]) || !isUint(ab[1]))
+                return null;
+            lo = Number(ab[0]);
+            hi = Number(ab[1]);
+        }
+        else {
+            if (!isUint(rangeRaw))
+                return null;
+            lo = Number(rangeRaw);
+            hi = stepRaw !== undefined ? max : lo; // Vixie: "N/step" means N..max step (not just {N})
+        }
+        if (lo < min || hi > max || lo > hi)
+            return null;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out.size ? out : null;
+}
+/** Parse a 5-field cron expression (minute hour day-of-month month day-of-week), or null if invalid. */
+export function parseCron(expr) {
+    const f = expr.trim().split(/\s+/);
+    if (f.length !== 5)
+        return null;
+    const m = parseField(f[0], 0, 59);
+    const h = parseField(f[1], 0, 23);
+    const dom = parseField(f[2], 1, 31);
+    const mon = parseField(f[3], 1, 12);
+    const dow = parseField(f[4], 0, 6); // 0 = Sunday
+    if (!m || !h || !dom || !mon || !dow)
+        return null;
+    return { m, h, dom, mon, dow, domStar: f[2] === "*", dowStar: f[4] === "*" };
+}
+/** Does `expr` fire at the given local minute? Uses the Vixie day-of-month/day-of-week OR rule. */
+export function cronMatches(expr, d) {
+    const p = parseCron(expr);
+    if (!p)
+        return false;
+    if (!p.m.has(d.getMinutes()) || !p.h.has(d.getHours()) || !p.mon.has(d.getMonth() + 1))
+        return false;
+    const domOk = p.dom.has(d.getDate());
+    const dowOk = p.dow.has(d.getDay());
+    if (p.domStar && p.dowStar)
+        return true; // both unrestricted → any day
+    if (!p.domStar && !p.dowStar)
+        return domOk || dowOk; // both restricted → OR
+    return p.domStar ? dowOk : domOk; // one restricted → that one
+}
+/** Parse a user schedule string into a Schedule (or an error). `nowMs` anchors relative one-shots. */
+export function parseSchedule(input, nowMs) {
+    const s = input.trim();
+    let m = /^every\s+(\d+\s*[smhd])$/i.exec(s);
+    if (m) {
+        const ms = durationToMs(m[1]);
+        if (!ms)
+            return { error: `bad interval: ${m[1]}` };
+        return { kind: "every", everyMs: ms, display: `every ${m[1].replace(/\s+/g, "")}` };
+    }
+    m = /^in\s+(\d+\s*[smhd])$/i.exec(s);
+    if (m) {
+        const ms = durationToMs(m[1]);
+        if (!ms)
+            return { error: `bad delay: ${m[1]}` };
+        return { kind: "once", runAt: nowMs + ms, display: `once, in ${m[1].replace(/\s+/g, "")}` };
+    }
+    if (/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(s)) {
+        const t = Date.parse(s);
+        if (Number.isNaN(t))
+            return { error: `bad timestamp: ${s}` };
+        return { kind: "once", runAt: t, display: `once, at ${s}` };
+    }
+    if (parseCron(s))
+        return { kind: "cron", expr: s };
+    return { error: `unrecognized schedule "${s}" — use a cron expr ("0 9 * * *"), "every 30m", "in 2h", or an ISO timestamp` };
+}
+export function describeSchedule(sched) {
+    return sched.kind === "cron" ? `cron \`${sched.expr}\`` : sched.display;
+}
+/** Is this job due to run at `nowMs`? Cron jobs fire once per matching minute (deduped via lastRunAt);
+ *  intervals fire when `everyMs` has elapsed since the last run; one-shots fire once when their time passes. */
+export function isDue(job, nowMs) {
+    const s = job.schedule;
+    if (s.kind === "cron") {
+        if (!cronMatches(s.expr, new Date(nowMs)))
+            return false;
+        return job.lastRunAt === undefined || Math.floor(job.lastRunAt / 60_000) < Math.floor(nowMs / 60_000);
+    }
+    // interval: fire once per grid slot of width everyMs — a tick landing slightly early still counts the
+    // slot (a plain `now >= last+everyMs` deadline loses ~half the fires of `every 1m` at 60s tick granularity).
+    if (s.kind === "every")
+        return Math.floor(nowMs / s.everyMs) > Math.floor((job.lastRunAt ?? job.createdAt) / s.everyMs);
+    return job.lastRunAt === undefined && nowMs >= s.runAt; // once
+}
+/** Next fire time at/after `fromMs` (for display). Cron scans minute-by-minute up to a year; null if none
+ *  (e.g. a one-shot already past). */
+export function nextRun(job, fromMs) {
+    const s = job.schedule;
+    if (s.kind === "every")
+        return (Math.floor(fromMs / s.everyMs) + 1) * s.everyMs; // next grid boundary (always > fromMs)
+    if (s.kind === "once")
+        return job.lastRunAt === undefined ? s.runAt : null;
+    const p = parseCron(s.expr);
+    if (!p)
+        return null;
+    const start = Math.floor(fromMs / 60_000) * 60_000 + 60_000; // next minute boundary
+    for (let t = start, i = 0; i < 366 * 24 * 60; t += 60_000, i++) {
+        if (cronMatches(s.expr, new Date(t)))
+            return t;
+    }
+    return null;
+}

package/dist/cron/store.js

@@ -0,0 +1,87 @@
+// Persistent job store for `hara cron` — atomic JSON at ~/.hara/cron/jobs.json (temp + rename, like
+// openclaw/hermes). Each job runs a fresh `hara` session when due; per-job run logs live alongside.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+export function cronDir() {
+    return join(homedir(), ".hara", "cron");
+}
+export function jobsPath() {
+    return join(cronDir(), "jobs.json");
+}
+export function logPath(id) {
+    return join(cronDir(), "logs", `${id}.log`);
+}
+export function loadJobs() {
+    const p = jobsPath();
+    if (!existsSync(p))
+        return [];
+    try {
+        const j = JSON.parse(readFileSync(p, "utf8"));
+        return Array.isArray(j) ? j : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Persist the job list with an atomic temp-write + rename (never leaves a half-written jobs.json). */
+export function saveJobs(jobs) {
+    mkdirSync(cronDir(), { recursive: true });
+    const p = jobsPath();
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(jobs, null, 2) + "\n", "utf8");
+    renameSync(tmp, p);
+}
+export function addJob(j) {
+    const jobs = loadJobs();
+    const job = { id: randomUUID().slice(0, 8), enabled: j.enabled ?? true, ...j };
+    jobs.push(job);
+    saveJobs(jobs);
+    return job;
+}
+/** Resolve an id or unique id-prefix to a single job. Exact id wins; otherwise the prefix must match
+ *  EXACTLY one job — an ambiguous prefix returns "ambiguous" (never silently picks one, since callers
+ *  delete/toggle). `undefined` = no match. */
+export function resolveJob(idOrPrefix) {
+    const jobs = loadJobs();
+    const exact = jobs.find((x) => x.id === idOrPrefix);
+    if (exact)
+        return exact;
+    const pre = jobs.filter((x) => x.id.startsWith(idOrPrefix));
+    return pre.length === 1 ? pre[0] : pre.length > 1 ? "ambiguous" : undefined;
+}
+/** Find a job by id/unique-prefix (back-compat; ambiguous → undefined). */
+export function findJob(idOrPrefix) {
+    const r = resolveJob(idOrPrefix);
+    return r === "ambiguous" ? undefined : r;
+}
+/** Delete a job by EXACT id (callers resolve the prefix first via resolveJob). */
+export function removeJob(id) {
+    const jobs = loadJobs();
+    if (!jobs.some((x) => x.id === id))
+        return false;
+    saveJobs(jobs.filter((x) => x.id !== id));
+    return true;
+}
+/** Enable/disable a job by EXACT id. */
+export function setEnabled(id, on) {
+    const jobs = loadJobs();
+    const job = jobs.find((x) => x.id === id);
+    if (!job)
+        return false;
+    job.enabled = on;
+    saveJobs(jobs);
+    return true;
+}
+/** Record a run's outcome (and stamp lastRunAt) for the given job. */
+export function recordRun(id, at, status, error) {
+    const jobs = loadJobs();
+    const job = jobs.find((x) => x.id === id);
+    if (!job)
+        return;
+    job.lastRunAt = at;
+    job.lastStatus = status;
+    job.lastError = error;
+    saveJobs(jobs);
+}